zouroboros-memory 3.0.0

package/dist/context-budget.d.ts

@@ -0,0 +1,94 @@
+#!/usr/bin/env bun
+/**
+ * context-budget.ts — Token Budget Tracking for Swarm Orchestration
+ * MEM-001: Context Budget Awareness
+ *
+ * Implements MemGPT-style context budget awareness:
+ * - Tracks current token usage vs. model limits
+ * - Warning/critical thresholds trigger proactive checkpointing
+ * - Compresses or paginates retrieved facts before context overflow
+ */
+import { Database } from "bun:sqlite";
+export interface ContextBudget {
+    maxTokens: number;
+    warningThreshold: number;
+    criticalThreshold: number;
+    currentUsage: number;
+    warningFired: boolean;
+    criticalFired: boolean;
+    lastUpdated: number;
+}
+export interface BudgetCheckpoint {
+    id: string;
+    swarmId: string;
+    summary: string;
+    facts: CompressedFact[];
+    openLoops: string[];
+    pendingEpisodes: string[];
+    tokenEstimate: number;
+    compressedFrom: number;
+    compressionRatio: number;
+    createdAt: number;
+}
+export interface CompressedFact {
+    entity: string;
+    key: string | null;
+    value: string;
+    isSummary: boolean;
+    originalIds?: string[];
+}
+export interface BudgetMetrics {
+    checkpointsCreated: number;
+    compressionsTriggered: number;
+    warningFires: number;
+    criticalFires: number;
+    totalTokensTracked: number;
+    avgTokensPerOperation: number;
+}
+export interface CompressionPlan {
+    includeFacts: CompressedFact[];
+    excludeCount: number;
+    estimatedTokens: number;
+    withinBudget: boolean;
+}
+export interface RetrievalBudgetResult {
+    includeFacts: CompressedFact[];
+    checkpointRecommended: boolean;
+    checkpoint?: BudgetCheckpoint;
+    withinBudget: boolean;
+    estimatedTokens: number;
+    compressed: boolean;
+    excludedCount: number;
+}
+export declare function estimateTokens(text: string): number;
+export declare function estimateFactTokens(fact: {
+    entity: string;
+    key: string | null;
+    value: string;
+}): number;
+export declare function getBudget(db?: Database): ContextBudget;
+export declare function updateBudget(currentUsage: number, db?: Database): {
+    level: "ok" | "warning" | "critical";
+    budget: ContextBudget;
+};
+export declare function resetBudget(db?: Database): void;
+export declare function initBudget(maxTokens: number, warningThreshold: number, criticalThreshold: number, db?: Database): void;
+export declare function planCompression(facts: Array<{
+    id: string;
+    entity: string;
+    key: string | null;
+    value: string;
+    importance?: number;
+    confidence?: number;
+}>, availableTokens: number): CompressionPlan;
+export declare function createCheckpoint(swarmId: string, summary: string, facts: CompressedFact[], openLoopIds: string[], pendingEpisodeIds: string[]): BudgetCheckpoint;
+export declare function loadCheckpoint(checkpointId: string): BudgetCheckpoint | null;
+export declare function listCheckpoints(swarmId?: string, limit?: number): BudgetCheckpoint[];
+export declare function retrievalWithBudget(facts: Array<{
+    id: string;
+    entity: string;
+    key: string | null;
+    value: string;
+    importance?: number;
+    confidence?: number;
+}>, swarmId: string, operationSummary: string, maxTokens?: number): RetrievalBudgetResult;

package/dist/context-budget.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env bun
+/**
+ * context-budget.ts — Token Budget Tracking for Swarm Orchestration
+ * MEM-001: Context Budget Awareness
+ *
+ * Implements MemGPT-style context budget awareness:
+ * - Tracks current token usage vs. model limits
+ * - Warning/critical thresholds trigger proactive checkpointing
+ * - Compresses or paginates retrieved facts before context overflow
+ */
+import { Database } from "bun:sqlite";
+import { randomUUID } from "crypto";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
+import { join } from "path";
+const DB_PATH = process.env.ZO_MEMORY_DB || "/home/workspace/.zo/memory/shared-facts.db";
+const CHECKPOINT_DIR = process.env.ZO_CHECKPOINT_DIR || "/home/workspace/.zo/memory/checkpoints";
+// ─── Database Setup ──────────────────────────────────────────────────────────
+function getDb() {
+    const db = new Database(DB_PATH);
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS context_budget_state (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      max_tokens INTEGER NOT NULL DEFAULT 8000,
+      warning_threshold REAL NOT NULL DEFAULT 0.70,
+      critical_threshold REAL NOT NULL DEFAULT 0.90,
+      current_usage INTEGER NOT NULL DEFAULT 0,
+      warning_fired INTEGER NOT NULL DEFAULT 0,
+      critical_fired INTEGER NOT NULL DEFAULT 0,
+      last_updated INTEGER DEFAULT (strftime('%s','now'))
+    );
+    INSERT OR IGNORE INTO context_budget_state (id) VALUES (1);
+    CREATE TABLE IF NOT EXISTS budget_checkpoints (
+      id TEXT PRIMARY KEY,
+      swarm_id TEXT NOT NULL,
+      summary TEXT NOT NULL,
+      token_estimate INTEGER NOT NULL,
+      compressed_from INTEGER NOT NULL DEFAULT 0,
+      compression_ratio REAL NOT NULL DEFAULT 1.0,
+      created_at INTEGER DEFAULT (strftime('%s','now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_budget_checkpoints_swarm ON budget_checkpoints(swarm_id);
+  `);
+    return db;
+}
+// ─── Token Estimation ─────────────────────────────────────────────────────────
+// ~4 chars per token is a common heuristic for English text
+const CHARS_PER_TOKEN = 4;
+export function estimateTokens(text) {
+    return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+export function estimateFactTokens(fact) {
+    return estimateTokens(`${fact.entity} ${fact.key || ""} ${fact.value}`.trim());
+}
+// ─── Budget State ─────────────────────────────────────────────────────────────
+export function getBudget(db) {
+    const _db = db || getDb();
+    const row = _db.prepare("SELECT * FROM context_budget_state WHERE id = 1").get();
+    if (!row)
+        return { maxTokens: 8000, warningThreshold: 0.70, criticalThreshold: 0.90, currentUsage: 0, warningFired: false, criticalFired: false, lastUpdated: Date.now() / 1000 };
+    return {
+        maxTokens: row.max_tokens,
+        warningThreshold: row.warning_threshold,
+        criticalThreshold: row.critical_threshold,
+        currentUsage: row.current_usage,
+        warningFired: Boolean(row.warning_fired),
+        criticalFired: Boolean(row.critical_fired),
+        lastUpdated: row.last_updated,
+    };
+}
+export function updateBudget(currentUsage, db) {
+    const _db = db || getDb();
+    const budget = getBudget(_db);
+    const usage = Math.max(0, currentUsage);
+    const ratio = budget.maxTokens > 0 ? usage / budget.maxTokens : 0;
+    let warningFired = budget.warningFired;
+    let criticalFired = budget.criticalFired;
+    if (ratio >= budget.criticalThreshold && !budget.criticalFired) {
+        warningFired = true;
+        criticalFired = true;
+        console.warn(`[context-budget] CRITICAL: ${Math.round(ratio * 100)}% (${usage}/${budget.maxTokens} tokens)`);
+    }
+    else if (ratio >= budget.warningThreshold && !budget.warningFired) {
+        warningFired = true;
+        console.warn(`[context-budget] WARNING: ${Math.round(ratio * 100)}% (${usage}/${budget.maxTokens} tokens)`);
+    }
+    _db.prepare(`UPDATE context_budget_state SET current_usage = ?, warning_fired = ?, critical_fired = ?, last_updated = strftime('%s','now') WHERE id = 1`).run(usage, warningFired ? 1 : 0, criticalFired ? 1 : 0);
+    return { level: ratio >= budget.criticalThreshold ? "critical" : ratio >= budget.warningThreshold ? "warning" : "ok", budget: getBudget(_db) };
+}
+export function resetBudget(db) {
+    const _db = db || getDb();
+    _db.prepare(`UPDATE context_budget_state SET current_usage = 0, warning_fired = 0, critical_fired = 0, last_updated = strftime('%s','now') WHERE id = 1`).run();
+}
+export function initBudget(maxTokens, warningThreshold, criticalThreshold, db) {
+    const _db = db || getDb();
+    _db.prepare(`UPDATE context_budget_state SET max_tokens = ?, warning_threshold = ?, critical_threshold = ?, last_updated = strftime('%s','now') WHERE id = 1`).run(maxTokens, warningThreshold, criticalThreshold);
+    console.log(`Context budget initialized: max=${maxTokens}, warning=${Math.round(warningThreshold * 100)}%, critical=${Math.round(criticalThreshold * 100)}%`);
+}
+// ─── Fact Compression ─────────────────────────────────────────────────────────
+export function planCompression(facts, availableTokens) {
+    if (facts.length === 0)
+        return { includeFacts: [], excludeCount: 0, estimatedTokens: 0, withinBudget: true };
+    const scored = facts.map((f) => {
+        const tokens = estimateFactTokens(f);
+        const priority = (f.importance ?? 1.0) * (f.confidence ?? 1.0);
+        return { fact: f, tokens, score: priority / Math.max(1, tokens) };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    let totalTokens = 0;
+    const includeFacts = [];
+    for (const item of scored) {
+        if (totalTokens + item.tokens <= availableTokens) {
+            includeFacts.push({ entity: item.fact.entity, key: item.fact.key, value: item.fact.value, isSummary: false, originalIds: [item.fact.id] });
+            totalTokens += item.tokens;
+        }
+    }
+    return { includeFacts, excludeCount: facts.length - includeFacts.length, estimatedTokens: totalTokens, withinBudget: totalTokens <= availableTokens };
+}
+// ─── Checkpoint Management ────────────────────────────────────────────────────
+function ensureCheckpointDir() {
+    if (!existsSync(CHECKPOINT_DIR))
+        mkdirSync(CHECKPOINT_DIR, { recursive: true });
+}
+export function createCheckpoint(swarmId, summary, facts, openLoopIds, pendingEpisodeIds) {
+    ensureCheckpointDir();
+    const id = `ckpt-${randomUUID().slice(0, 8)}`;
+    const compressedFrom = facts.length;
+    const tokenEstimate = facts.reduce((sum, f) => sum + estimateTokens(f.value), 0);
+    const compressionRatio = compressedFrom > 0 ? Math.max(0, 1 - (tokenEstimate / Math.max(1, compressedFrom * 200))) : 1.0;
+    const checkpoint = { id, swarmId, summary, facts, openLoops: openLoopIds, pendingEpisodes: pendingEpisodeIds, tokenEstimate, compressedFrom, compressionRatio, createdAt: Math.floor(Date.now() / 1000) };
+    const db = getDb();
+    db.prepare(`INSERT INTO budget_checkpoints (id, swarm_id, summary, token_estimate, compressed_from, compression_ratio) VALUES (?, ?, ?, ?, ?, ?)`).run(id, swarmId, summary, tokenEstimate, compressedFrom, compressionRatio);
+    writeFileSync(join(CHECKPOINT_DIR, `${id}.json`), JSON.stringify(checkpoint, null, 2));
+    return checkpoint;
+}
+export function loadCheckpoint(checkpointId) {
+    const p = join(CHECKPOINT_DIR, `${checkpointId}.json`);
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function listCheckpoints(swarmId, limit = 10) {
+    const db = getDb();
+    let query = "SELECT * FROM budget_checkpoints";
+    const args = [];
+    if (swarmId) {
+        query += " WHERE swarm_id = ?";
+        args.push(swarmId);
+    }
+    query += " ORDER BY created_at DESC LIMIT ?";
+    args.push(limit);
+    return db.prepare(query).all(...args).map((row) => {
+        const cp = loadCheckpoint(row.id);
+        if (cp)
+            return cp;
+        return { id: row.id, swarmId: row.swarm_id, summary: row.summary, tokenEstimate: row.token_estimate, compressedFrom: row.compressed_from, compressionRatio: row.compression_ratio, createdAt: row.created_at, facts: [], openLoops: [], pendingEpisodes: [] };
+    });
+}
+// ─── Integration with memory retrieval ────────────────────────────────────────
+export function retrievalWithBudget(facts, swarmId, operationSummary, maxTokens) {
+    const budget = getBudget();
+    const availableTokens = maxTokens ?? Math.floor(budget.maxTokens * (1 - budget.criticalThreshold));
+    const plan = planCompression(facts, availableTokens);
+    const { level } = updateBudget(budget.currentUsage + plan.estimatedTokens);
+    let checkpoint;
+    if (plan.excludeCount > 0 && plan.excludeCount >= Math.ceil(facts.length * 0.3)) {
+        checkpoint = createCheckpoint(swarmId, operationSummary, plan.includeFacts, [], []);
+    }
+    if (level !== "ok")
+        console.warn(`[context-budget] ${level.toUpperCase()}: ${plan.excludeCount} facts excluded, ${plan.estimatedTokens} tokens of ${availableTokens} budget`);
+    return { includeFacts: plan.includeFacts, checkpointRecommended: plan.excludeCount > 0, checkpoint, withinBudget: plan.withinBudget, estimatedTokens: plan.estimatedTokens, compressed: plan.excludeCount > 0, excludedCount: plan.excludeCount };
+}
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        console.log(`Context Budget CLI - v1.0
+
+Commands:
+  init --maxTokens <n> --warning <0.0-1.0> --critical <0.0-1.0>
+  status
+  track --operation <name> --inputTokens <n> --outputTokens <n>
+  compress --factCount <n> --availableTokens <n>
+  checkpoints --swarmId <id>
+  reset
+`);
+        process.exit(0);
+    }
+    const command = args[0];
+    switch (command) {
+        case "init": {
+            let maxTokens = 8000, warning = 0.70, critical = 0.90;
+            for (let i = 1; i < args.length - 1; i++) {
+                if (args[i] === "--maxTokens" || args[i] === "-m")
+                    maxTokens = parseInt(args[i + 1]);
+                if (args[i] === "--warning" || args[i] === "-w")
+                    warning = parseFloat(args[i + 1]);
+                if (args[i] === "--critical" || args[i] === "-c")
+                    critical = parseFloat(args[i + 1]);
+            }
+            initBudget(maxTokens, warning, critical);
+            break;
+        }
+        case "status": {
+            const budget = getBudget();
+            const ratio = budget.maxTokens > 0 ? (budget.currentUsage / budget.maxTokens) : 0;
+            const level = ratio >= budget.criticalThreshold ? "CRITICAL" : ratio >= budget.warningThreshold ? "WARNING" : "OK";
+            console.log(`Context Budget Status\n  Max tokens: ${budget.maxTokens}\n  Current: ${budget.currentUsage} (${Math.round(ratio * 100)}%)\n  Warning at: ${Math.round(budget.warningThreshold * 100)}%\n  Critical at: ${Math.round(budget.criticalThreshold * 100)}%\n  Level: ${level}\n  Warning fired: ${budget.warningFired}\n  Critical fired: ${budget.criticalFired}\n  Last updated: ${new Date(budget.lastUpdated * 1000).toISOString()}`);
+            break;
+        }
+        case "track": {
+            let operation = "unknown", inputTokens = 0, outputTokens = 0;
+            for (let i = 1; i < args.length; i++) {
+                if (args[i] === "--operation" || args[i] === "-o")
+                    operation = args[i + 1] || "unknown";
+                if (args[i] === "--inputTokens" || args[i] === "-i")
+                    inputTokens = parseInt(args[i + 1] || "0");
+                if (args[i] === "--outputTokens")
+                    outputTokens = parseInt(args[i + 1] || "0");
+            }
+            const totalTokens = inputTokens + outputTokens;
+            const budget = getBudget();
+            const newUsage = budget.currentUsage + totalTokens;
+            const { level } = updateBudget(newUsage);
+            console.log(`Tracked: ${operation} +${totalTokens} tokens | Budget: ${newUsage}/${budget.maxTokens} | Level: ${level}`);
+            break;
+        }
+        case "compress": {
+            let factCount = 0, availableTokens = 1000;
+            for (let i = 1; i < args.length; i++) {
+                if (args[i] === "--factCount" || args[i] === "-n")
+                    factCount = parseInt(args[i + 1] || "0");
+                if (args[i] === "--availableTokens" || args[i] === "-t")
+                    availableTokens = parseInt(args[i + 1] || "0");
+            }
+            const mockFacts = Array.from({ length: factCount }, (_, i) => ({ id: `mock-${i}`, entity: "mock.entity", key: `key${i}`, value: "Sample fact value with reasonable content for token estimation. ".repeat(5), importance: 1.0, confidence: 1.0 }));
+            const plan = planCompression(mockFacts, availableTokens);
+            console.log(`Compression Plan\n  Total facts: ${factCount}\n  Available: ${availableTokens}\n  Estimated: ${plan.estimatedTokens}\n  Included: ${plan.includeFacts.length}\n  Excluded: ${plan.excludeCount}\n  Within budget: ${plan.withinBudget ? "YES" : "NO"}`);
+            break;
+        }
+        case "checkpoints": {
+            let swarmId;
+            for (let i = 1; i < args.length; i++)
+                if (args[i] === "--swarmId" || args[i] === "-s")
+                    swarmId = args[i + 1];
+            const checkpoints = listCheckpoints(swarmId);
+            if (checkpoints.length === 0) {
+                console.log("No checkpoints found.");
+                break;
+            }
+            console.log(`Budget Checkpoints (${checkpoints.length})`);
+            for (const cp of checkpoints)
+                console.log(`  ${cp.id} | ${cp.swarmId} | ${cp.tokenEstimate}t | ${cp.compressedFrom} facts | ${new Date(cp.createdAt * 1000).toISOString()}`);
+            break;
+        }
+        case "reset": {
+            resetBudget();
+            console.log("Budget reset to zero.");
+            break;
+        }
+        default:
+            console.error(`Unknown command: ${command}`);
+            process.exit(1);
+    }
+}
+if (import.meta.main)
+    main();

package/dist/cross-persona.d.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env bun
+/**
+ * cross-persona.ts — Cross-Persona Memory Sharing & Inheritance
+ * MEM-104: Cross-Persona Memory Sharing
+ *
+ * Usage:
+ *   bun cross-persona.ts list-shared
+ *   bun cross-persona.ts share --entity <name> --pools pool1,pool2
+ *   bun cross-persona.ts inherit --persona <name> --from parent1,parent2
+ *   bun cross-persona.ts search --persona <name> --query "<text>"
+ */
+import { Database } from "bun:sqlite";
+export interface SharedPool {
+    id: string;
+    name: string;
+    description?: string;
+    personas: string[];
+    factCount: number;
+}
+export interface PersonaNode {
+    name: string;
+    depth: number;
+    children: PersonaNode[];
+}
+export declare function listPools(db: Database): SharedPool[];
+export declare function createPool(db: Database, name: string, description?: string): string;
+export declare function addToPool(db: Database, poolId: string, persona: string): void;
+export declare function removeFromPool(db: Database, poolId: string, persona: string): void;
+export declare function setInheritance(db: Database, childPersona: string, parentPersonas: string[]): void;
+export declare function getAccessiblePersonas(db: Database, persona: string): string[];
+export declare function searchCrossPersona(db: Database, persona: string, query: string, limit?: number): Array<Record<string, unknown>>;

package/dist/cross-persona.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env bun
+/**
+ * cross-persona.ts — Cross-Persona Memory Sharing & Inheritance
+ * MEM-104: Cross-Persona Memory Sharing
+ *
+ * Usage:
+ *   bun cross-persona.ts list-shared
+ *   bun cross-persona.ts share --entity <name> --pools pool1,pool2
+ *   bun cross-persona.ts inherit --persona <name> --from parent1,parent2
+ *   bun cross-persona.ts search --persona <name> --query "<text>"
+ */
+import { Database } from "bun:sqlite";
+const DB_PATH = process.env.ZO_MEMORY_DB || "/home/workspace/.zo/memory/shared-facts.db";
+function getDb() {
+    const db = new Database(DB_PATH);
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS persona_pools (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL UNIQUE,
+      description TEXT,
+      created_at INTEGER DEFAULT (strftime('%s','now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS persona_pool_members (
+      pool_id TEXT NOT NULL REFERENCES persona_pools(id) ON DELETE CASCADE,
+      persona TEXT NOT NULL,
+      added_at INTEGER DEFAULT (strftime('%s','now')),
+      PRIMARY KEY (pool_id, persona)
+    );
+
+    CREATE TABLE IF NOT EXISTS persona_inheritance (
+      child_persona TEXT PRIMARY KEY,
+      parent_persona TEXT NOT NULL,
+      depth INTEGER NOT NULL DEFAULT 1,
+      created_at INTEGER DEFAULT (strftime('%s','now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_pool_members_persona ON persona_pool_members(persona);
+    CREATE INDEX IF NOT EXISTS idx_inheritance_child ON persona_inheritance(child_persona);
+  `);
+    return db;
+}
+export function listPools(db) {
+    const pools = db.prepare("SELECT * FROM persona_pools ORDER BY name").all();
+    return pools.map(p => {
+        const members = db.prepare("SELECT persona FROM persona_pool_members WHERE pool_id = ?").all(p.id).map(m => m.persona);
+        const factCount = members.length > 0
+            ? db.prepare(`SELECT COUNT(*) as c FROM facts WHERE persona IN (${members.map(() => "?").join(",")})`).get(...members).c
+            : 0;
+        return { id: p.id, name: p.name, description: p.description, personas: members, factCount };
+    });
+}
+export function createPool(db, name, description) {
+    const { randomUUID } = require("crypto");
+    const id = randomUUID();
+    db.prepare("INSERT OR IGNORE INTO persona_pools (id, name, description) VALUES (?, ?, ?)").run(id, name, description || null);
+    return id;
+}
+export function addToPool(db, poolId, persona) {
+    db.prepare("INSERT OR IGNORE INTO persona_pool_members (pool_id, persona) VALUES (?, ?)").run(poolId, persona);
+}
+export function removeFromPool(db, poolId, persona) {
+    db.prepare("DELETE FROM persona_pool_members WHERE pool_id = ? AND persona = ?").run(poolId, persona);
+}
+export function setInheritance(db, childPersona, parentPersonas) {
+    db.prepare("DELETE FROM persona_inheritance WHERE child_persona = ?").run(childPersona);
+    for (let i = 0; i < parentPersonas.length; i++) {
+        db.prepare("INSERT OR IGNORE INTO persona_inheritance (child_persona, parent_persona, depth) VALUES (?, ?, ?)").run(childPersona, parentPersonas[i], i + 1);
+    }
+}
+export function getAccessiblePersonas(db, persona) {
+    const direct = [persona];
+    // Direct pool membership
+    const pools = db.prepare("SELECT pool_id FROM persona_pool_members WHERE persona = ?").all(persona);
+    for (const pool of pools) {
+        const members = db.prepare("SELECT persona FROM persona_pool_members WHERE pool_id = ? AND persona != ?").all(pool.pool_id, persona);
+        for (const m of members)
+            direct.push(m.persona);
+    }
+    // Inheritance chain
+    const parents = db.prepare("SELECT parent_persona FROM persona_inheritance WHERE child_persona = ? ORDER BY depth ASC").all(persona);
+    for (const parent of parents)
+        direct.push(parent.parent_persona);
+    return [...new Set(direct)];
+}
+export function searchCrossPersona(db, persona, query, limit = 10) {
+    const accessible = getAccessiblePersonas(db, persona);
+    if (accessible.length === 0)
+        return [];
+    const placeholders = accessible.map(() => "?").join(",");
+    const safeQuery = query.replace(/['"*]/g, "").trim();
+    try {
+        return db.prepare(`
+      SELECT f.*, rank,
+        CASE WHEN f.persona = ? THEN 1.0 ELSE 0.8 END as access_bonus
+      FROM facts f
+      JOIN facts_fts fts ON f.rowid = fts.rowid
+      WHERE facts_fts MATCH ? AND f.persona IN (${placeholders})
+        AND (f.expires_at IS NULL OR f.expires_at > ?)
+      ORDER BY rank * (CASE WHEN f.persona = ? THEN 1.0 ELSE 0.8 END) ASC
+      LIMIT ?
+    `).all(persona, safeQuery, ...accessible, Math.floor(Date.now() / 1000), persona, limit);
+    }
+    catch {
+        return [];
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        console.log("Cross-Persona Memory CLI\n\nCommands:\n  list-pools                   List all shared pools\n  create-pool --name <n> --desc <d>  Create a shared pool\n  add-to-pool --pool <id> --persona <p>  Add persona to pool\n  remove-from-pool --pool <id> --persona <p>  Remove persona from pool\n  list-inheritance             Show inheritance hierarchy\n  set-inheritance --child <p> --parents p1,p2  Set parent chain\n  accessible --persona <name>  Show accessible personas for a persona\n  search --persona <name> --query <text>  Cross-persona search");
+        process.exit(0);
+    }
+    const flags = {};
+    for (let i = 0; i < args.length; i++)
+        if (args[i].startsWith("--"))
+            flags[args[i].slice(2)] = args[i + 1] || "";
+    const command = args[0];
+    const db = getDb();
+    if (command === "list-pools") {
+        const pools = listPools(db);
+        if (pools.length === 0) {
+            console.log("No shared pools.");
+        }
+        else {
+            pools.forEach(p => { console.log(`[${p.id.slice(0, 8)}] ${p.name} | ${p.description || "no description"} | ${p.personas.length} personas | ${p.factCount} facts`); if (p.personas.length)
+                console.log(`  Members: ${p.personas.join(", ")}`); });
+        }
+    }
+    else if (command === "create-pool") {
+        if (!flags.name) {
+            console.error("--name required");
+            process.exit(1);
+        }
+        const id = createPool(db, flags.name, flags.desc);
+        console.log(`Pool "${flags.name}" created: ${id.slice(0, 8)}`);
+    }
+    else if (command === "add-to-pool") {
+        if (!flags.pool || !flags.persona) {
+            console.error("--pool and --persona required");
+            process.exit(1);
+        }
+        addToPool(db, flags.pool, flags.persona);
+        console.log(`Added "${flags.persona}" to pool ${flags.pool.slice(0, 8)}.`);
+    }
+    else if (command === "remove-from-pool") {
+        if (!flags.pool || !flags.persona) {
+            console.error("--pool and --persona required");
+            process.exit(1);
+        }
+        removeFromPool(db, flags.pool, flags.persona);
+        console.log(`Removed "${flags.persona}" from pool ${flags.pool.slice(0, 8)}.`);
+    }
+    else if (command === "set-inheritance") {
+        if (!flags.child || !flags.parents) {
+            console.error("--child and --parents required");
+            process.exit(1);
+        }
+        const parents = flags.parents.split(",").map(p => p.trim()).filter(Boolean);
+        setInheritance(db, flags.child, parents);
+        console.log(`"${flags.child}" now inherits from: ${parents.join(" > ")}`);
+    }
+    else if (command === "accessible") {
+        if (!flags.persona) {
+            console.error("--persona required");
+            process.exit(1);
+        }
+        const accessible = getAccessiblePersonas(db, flags.persona);
+        console.log(`Accessible for "${flags.persona}": ${accessible.join(", ")}`);
+    }
+    else if (command === "search") {
+        if (!flags.persona || !flags.query) {
+            console.error("--persona and --query required");
+            process.exit(1);
+        }
+        const results = await searchCrossPersona(db, flags.persona, flags.query);
+        if (results.length === 0) {
+            console.log("No results.");
+        }
+        else {
+            results.forEach(r => console.log(`  [${r.persona.padEnd(20)}] ${r.entity}.${(r.key || "_")} = ${r.value.slice(0, 80)}`));
+        }
+    }
+    db.close();
+}
+if (import.meta.main)
+    main();

package/dist/database.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Database management for Zouroboros Memory
+ */
+import { Database } from 'bun:sqlite';
+import type { MemoryConfig } from 'zouroboros-core';
+/**
+ * Initialize the database with schema
+ */
+export declare function initDatabase(config: MemoryConfig): Database;
+/**
+ * Get the database instance (must call initDatabase first)
+ */
+export declare function getDatabase(): Database;
+/**
+ * Close the database connection
+ */
+export declare function closeDatabase(): void;
+/**
+ * Check if database is initialized
+ */
+export declare function isInitialized(): boolean;
+/**
+ * Run database migrations
+ */
+export declare function runMigrations(config: MemoryConfig): void;
+/**
+ * Get database statistics
+ */
+export declare function getDbStats(config: MemoryConfig): {
+    facts: number;
+    episodes: number;
+    procedures: number;
+    openLoops: number;
+    embeddings: number;
+};