@psiclawops/hypermem 0.5.6 → 0.6.2

package/dist/context-backfill.d.ts

@@ -0,0 +1,46 @@
+/**
+ * hypermem Context Backfill
+ *
+ * One-time migration that creates context rows for existing conversations
+ * that don't yet have an active context. Designed to be idempotent — running
+ * it multiple times produces the same result without modifying existing data.
+ *
+ * Also provides parent chain backfill (Phase 2): reconstructs parent_id/depth
+ * for legacy flat conversations that were created before the Turn DAG model.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+/**
+ * Backfill active contexts for all existing conversations.
+ *
+ * For each conversation without an active context:
+ *   1. Creates an active context via getOrCreateActiveContext
+ *   2. If the conversation has messages, advances the head pointer
+ *      to the highest message ID
+ *
+ * @returns counts of created and skipped conversations
+ */
+export declare function backfillContexts(db: DatabaseSync): {
+    created: number;
+    skipped: number;
+};
+/**
+ * Backfill parent_id and depth for existing messages that lack them.
+ *
+ * Reconstructs a linear chain per conversation ordered by message_index:
+ *   - first message: parent_id = NULL, depth = 0
+ *   - each subsequent: parent_id = previous.id, depth = previous.depth + 1
+ *
+ * Idempotent: only touches messages where parent_id IS NULL AND depth = 0
+ * AND there is more than one message or the message is not the first.
+ * In practice, we simply skip messages that already have parent_id set.
+ *
+ * Also stamps context_id on messages that lack it, using the active context
+ * for their conversation.
+ *
+ * @returns counts of messages updated and conversations processed
+ */
+export declare function backfillParentChains(db: DatabaseSync): {
+    conversationsProcessed: number;
+    messagesUpdated: number;
+};
+//# sourceMappingURL=context-backfill.d.ts.map

package/dist/context-backfill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-backfill.d.ts","sourceRoot":"","sources":["../src/context-backfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,YAAY,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAwCvF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,YAAY,GACf;IAAE,sBAAsB,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CA+D7D"}

package/dist/context-backfill.js

@@ -0,0 +1,113 @@
+/**
+ * hypermem Context Backfill
+ *
+ * One-time migration that creates context rows for existing conversations
+ * that don't yet have an active context. Designed to be idempotent — running
+ * it multiple times produces the same result without modifying existing data.
+ *
+ * Also provides parent chain backfill (Phase 2): reconstructs parent_id/depth
+ * for legacy flat conversations that were created before the Turn DAG model.
+ */
+import { getOrCreateActiveContext, updateContextHead } from './context-store.js';
+/**
+ * Backfill active contexts for all existing conversations.
+ *
+ * For each conversation without an active context:
+ *   1. Creates an active context via getOrCreateActiveContext
+ *   2. If the conversation has messages, advances the head pointer
+ *      to the highest message ID
+ *
+ * @returns counts of created and skipped conversations
+ */
+export function backfillContexts(db) {
+    let created = 0;
+    let skipped = 0;
+    const conversations = db
+        .prepare('SELECT id, agent_id, session_key FROM conversations')
+        .all();
+    for (const conv of conversations) {
+        // Check if an active context already exists for this conversation
+        const existing = db
+            .prepare("SELECT id FROM contexts WHERE conversation_id = ? AND status = 'active'")
+            .get(conv.id);
+        if (existing) {
+            skipped++;
+            continue;
+        }
+        // Find the max message ID for this conversation (may be null if no messages)
+        const maxRow = db
+            .prepare('SELECT MAX(id) as max_id FROM messages WHERE conversation_id = ?')
+            .get(conv.id);
+        const maxId = maxRow?.max_id ?? null;
+        // Create the active context
+        const context = getOrCreateActiveContext(db, conv.agent_id, conv.session_key, conv.id);
+        // If conversation has messages, advance head to the latest
+        if (maxId !== null) {
+            updateContextHead(db, context.id, maxId);
+        }
+        created++;
+    }
+    return { created, skipped };
+}
+/**
+ * Backfill parent_id and depth for existing messages that lack them.
+ *
+ * Reconstructs a linear chain per conversation ordered by message_index:
+ *   - first message: parent_id = NULL, depth = 0
+ *   - each subsequent: parent_id = previous.id, depth = previous.depth + 1
+ *
+ * Idempotent: only touches messages where parent_id IS NULL AND depth = 0
+ * AND there is more than one message or the message is not the first.
+ * In practice, we simply skip messages that already have parent_id set.
+ *
+ * Also stamps context_id on messages that lack it, using the active context
+ * for their conversation.
+ *
+ * @returns counts of messages updated and conversations processed
+ */
+export function backfillParentChains(db) {
+    let conversationsProcessed = 0;
+    let messagesUpdated = 0;
+    // Get all conversations that have at least one non-first message without parent_id.
+    // This is the idempotency guard: after backfill, all messages at index > 0
+    // have parent_id set. The first message (index 0) legitimately has parent_id = NULL.
+    const conversations = db
+        .prepare(`SELECT DISTINCT conversation_id
+       FROM messages
+       WHERE message_index > 0 AND parent_id IS NULL
+       ORDER BY conversation_id`)
+        .all();
+    const updateStmt = db.prepare('UPDATE messages SET parent_id = ?, depth = ?, context_id = COALESCE(context_id, ?) WHERE id = ?');
+    for (const { conversation_id: convId } of conversations) {
+        // Get active context for this conversation (if any)
+        const ctxRow = db
+            .prepare("SELECT id FROM contexts WHERE conversation_id = ? AND status = 'active' LIMIT 1")
+            .get(convId);
+        const contextId = ctxRow?.id ?? null;
+        // Get all messages for this conversation without parent_id, ordered by message_index
+        const messages = db
+            .prepare('SELECT id, message_index FROM messages WHERE conversation_id = ? AND parent_id IS NULL ORDER BY message_index ASC')
+            .all(convId);
+        if (messages.length === 0)
+            continue;
+        // Also get the last message that already HAS a parent_id (if any),
+        // so we can chain the backfilled messages after it.
+        const lastChainedRow = db
+            .prepare('SELECT id, depth FROM messages WHERE conversation_id = ? AND parent_id IS NOT NULL ORDER BY message_index DESC LIMIT 1')
+            .get(convId);
+        let prevId = lastChainedRow?.id ?? null;
+        let prevDepth = lastChainedRow?.depth ?? -1;
+        // If there's no prior chain AND the first unlinked message is truly
+        // message_index 0, start the chain from scratch
+        for (const msg of messages) {
+            const depth = prevDepth + 1;
+            updateStmt.run(prevId, depth, contextId, msg.id);
+            prevId = msg.id;
+            prevDepth = depth;
+            messagesUpdated++;
+        }
+        conversationsProcessed++;
+    }
+    return { conversationsProcessed, messagesUpdated };
+}
+//# sourceMappingURL=context-backfill.js.map

package/dist/context-store.d.ts

@@ -0,0 +1,77 @@
+/**
+ * hypermem Context Store
+ *
+ * Manages the `contexts` table — a durable record of agent conversation
+ * contexts that tracks which session is active, what the current head
+ * message is, and supports archival and forking.
+ *
+ * Each agent + session pair has at most one active context at a time.
+ * Contexts are the anchor point for the compositor: they track the
+ * head message (most recent message included in composed context) and
+ * link back to the underlying conversation.
+ *
+ * Design principles:
+ *   - All functions take DatabaseSync as first arg (standalone, no classes)
+ *   - Fully idempotent — safe to call on every startup
+ *   - Head pointer is monotone-forward (never moves backward)
+ *   - Archive is idempotent (no-op if already archived)
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface Context {
+    id: number;
+    agentId: string;
+    sessionKey: string;
+    conversationId: number;
+    headMessageId: number | null;
+    parentContextId: number | null;
+    status: 'active' | 'archived' | 'forked';
+    createdAt: string;
+    updatedAt: string;
+    metadataJson: string | null;
+}
+/**
+ * Add the contexts table and related indexes to an existing messages.db.
+ * Also ALTERs the messages table to add a context_id foreign key column.
+ * Idempotent — safe to call on every startup.
+ */
+export declare function ensureContextSchema(db: DatabaseSync): void;
+/**
+ * Get the active context for an agent + session pair.
+ * Returns null if no active context exists.
+ */
+export declare function getActiveContext(db: DatabaseSync, agentId: string, sessionKey: string): Context | null;
+/**
+ * Get the active context for an agent + session, creating one if none exists.
+ *
+ * If an active context already exists, returns it unchanged.
+ * Otherwise INSERTs a new context with status='active', head_message_id=NULL,
+ * and the given conversationId.
+ *
+ * Idempotent — safe to call repeatedly.
+ */
+export declare function getOrCreateActiveContext(db: DatabaseSync, agentId: string, sessionKey: string, conversationId: number): Context;
+/**
+ * Update the head message pointer for a context.
+ *
+ * Monotone forward: only updates if messageId > current head_message_id
+ * (or current is NULL). This prevents accidental regression of the head
+ * pointer, matching the compaction-fence monotone progress pattern.
+ */
+export declare function updateContextHead(db: DatabaseSync, contextId: number, messageId: number): void;
+/**
+ * Archive a context, setting its status to 'archived'.
+ * Idempotent — no-op if already archived.
+ */
+export declare function archiveContext(db: DatabaseSync, contextId: number): void;
+/**
+ * Rotate a session's active context: archive the current active context
+ * and create a new one, optionally linking back via parent_context_id.
+ *
+ * Used on session restarts/rotations so the new context starts with a
+ * clean head pointer instead of inheriting the stale tail.
+ *
+ * Returns the newly created active context.
+ * If no active context exists, simply creates one (no archive step).
+ */
+export declare function rotateSessionContext(db: DatabaseSync, agentId: string, sessionKey: string, conversationId: number): Context;
+//# sourceMappingURL=context-store.d.ts.map

package/dist/context-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-store.d.ts","sourceRoot":"","sources":["../src/context-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,QAAQ,GAAG,UAAU,GAAG,QAAQ,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAyBD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CAmC1D;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,GAAG,IAAI,CAShB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,OAAO,CAwBT;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,IAAI,CAeN;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,YAAY,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,YAAY,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,OAAO,CA2BT"}

package/dist/context-store.js

@@ -0,0 +1,177 @@
+/**
+ * hypermem Context Store
+ *
+ * Manages the `contexts` table — a durable record of agent conversation
+ * contexts that tracks which session is active, what the current head
+ * message is, and supports archival and forking.
+ *
+ * Each agent + session pair has at most one active context at a time.
+ * Contexts are the anchor point for the compositor: they track the
+ * head message (most recent message included in composed context) and
+ * link back to the underlying conversation.
+ *
+ * Design principles:
+ *   - All functions take DatabaseSync as first arg (standalone, no classes)
+ *   - Fully idempotent — safe to call on every startup
+ *   - Head pointer is monotone-forward (never moves backward)
+ *   - Archive is idempotent (no-op if already archived)
+ */
+// ─── Internal Helpers ───────────────────────────────────────────
+function parseContextRow(row) {
+    return {
+        id: row.id,
+        agentId: row.agent_id,
+        sessionKey: row.session_key,
+        conversationId: row.conversation_id,
+        headMessageId: row.head_message_id ?? null,
+        parentContextId: row.parent_context_id ?? null,
+        status: row.status,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        metadataJson: row.metadata_json ?? null,
+    };
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+// ─── Schema ─────────────────────────────────────────────────────
+/**
+ * Add the contexts table and related indexes to an existing messages.db.
+ * Also ALTERs the messages table to add a context_id foreign key column.
+ * Idempotent — safe to call on every startup.
+ */
+export function ensureContextSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS contexts (
+      id INTEGER PRIMARY KEY,
+      agent_id TEXT NOT NULL,
+      session_key TEXT NOT NULL,
+      conversation_id INTEGER REFERENCES conversations(id),
+      head_message_id INTEGER REFERENCES messages(id),
+      parent_context_id INTEGER REFERENCES contexts(id),
+      status TEXT NOT NULL DEFAULT 'active',
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      metadata_json TEXT
+    )
+  `);
+    db.exec(`
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_contexts_active_session
+      ON contexts(agent_id, session_key, status)
+      WHERE status = 'active'
+  `);
+    db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_contexts_head
+      ON contexts(head_message_id)
+  `);
+    // ALTER messages table to add context_id column (PRAGMA guard)
+    const msgCols = db.prepare('PRAGMA table_info(messages)').all().map(r => r.name);
+    if (!msgCols.includes('context_id')) {
+        db.exec('ALTER TABLE messages ADD COLUMN context_id INTEGER REFERENCES contexts(id)');
+    }
+}
+// ─── Context Operations ─────────────────────────────────────────
+/**
+ * Get the active context for an agent + session pair.
+ * Returns null if no active context exists.
+ */
+export function getActiveContext(db, agentId, sessionKey) {
+    const row = db
+        .prepare('SELECT * FROM contexts WHERE agent_id = ? AND session_key = ? AND status = ?')
+        .get(agentId, sessionKey, 'active');
+    if (!row)
+        return null;
+    return parseContextRow(row);
+}
+/**
+ * Get the active context for an agent + session, creating one if none exists.
+ *
+ * If an active context already exists, returns it unchanged.
+ * Otherwise INSERTs a new context with status='active', head_message_id=NULL,
+ * and the given conversationId.
+ *
+ * Idempotent — safe to call repeatedly.
+ */
+export function getOrCreateActiveContext(db, agentId, sessionKey, conversationId) {
+    const existing = getActiveContext(db, agentId, sessionKey);
+    if (existing)
+        return existing;
+    const now = nowIso();
+    const result = db
+        .prepare(`INSERT INTO contexts (agent_id, session_key, conversation_id, head_message_id, parent_context_id, status, created_at, updated_at, metadata_json)
+       VALUES (?, ?, ?, NULL, NULL, 'active', ?, ?, NULL)`)
+        .run(agentId, sessionKey, conversationId, now, now);
+    return {
+        id: Number(result.lastInsertRowid),
+        agentId,
+        sessionKey,
+        conversationId,
+        headMessageId: null,
+        parentContextId: null,
+        status: 'active',
+        createdAt: now,
+        updatedAt: now,
+        metadataJson: null,
+    };
+}
+/**
+ * Update the head message pointer for a context.
+ *
+ * Monotone forward: only updates if messageId > current head_message_id
+ * (or current is NULL). This prevents accidental regression of the head
+ * pointer, matching the compaction-fence monotone progress pattern.
+ */
+export function updateContextHead(db, contextId, messageId) {
+    const now = nowIso();
+    const row = db
+        .prepare('SELECT head_message_id FROM contexts WHERE id = ?')
+        .get(contextId);
+    if (!row)
+        return;
+    // Monotone forward: only advance, never regress
+    if (row.head_message_id === null || messageId > row.head_message_id) {
+        db.prepare('UPDATE contexts SET head_message_id = ?, updated_at = ? WHERE id = ?').run(messageId, now, contextId);
+    }
+}
+/**
+ * Archive a context, setting its status to 'archived'.
+ * Idempotent — no-op if already archived.
+ */
+export function archiveContext(db, contextId) {
+    const now = nowIso();
+    db.prepare(`UPDATE contexts SET status = 'archived', updated_at = ? WHERE id = ? AND status != 'archived'`).run(now, contextId);
+}
+/**
+ * Rotate a session's active context: archive the current active context
+ * and create a new one, optionally linking back via parent_context_id.
+ *
+ * Used on session restarts/rotations so the new context starts with a
+ * clean head pointer instead of inheriting the stale tail.
+ *
+ * Returns the newly created active context.
+ * If no active context exists, simply creates one (no archive step).
+ */
+export function rotateSessionContext(db, agentId, sessionKey, conversationId) {
+    const existing = getActiveContext(db, agentId, sessionKey);
+    if (existing) {
+        archiveContext(db, existing.id);
+    }
+    const now = nowIso();
+    const result = db
+        .prepare(`INSERT INTO contexts (agent_id, session_key, conversation_id, head_message_id, parent_context_id, status, created_at, updated_at, metadata_json)
+       VALUES (?, ?, ?, NULL, ?, 'active', ?, ?, NULL)`)
+        .run(agentId, sessionKey, conversationId, existing?.id ?? null, now, now);
+    return {
+        id: Number(result.lastInsertRowid),
+        agentId,
+        sessionKey,
+        conversationId,
+        headMessageId: null,
+        parentContextId: existing?.id ?? null,
+        status: 'active',
+        createdAt: now,
+        updatedAt: now,
+        metadataJson: null,
+    };
+}
+//# sourceMappingURL=context-store.js.map

package/dist/cross-agent.d.ts

@@ -25,6 +25,18 @@ export interface OrgRegistry {
 }
 /**
  * Default fleet org structure.
+ *
+ * ── EXAMPLE DATA ──────────────────────────────────────────────────────────
+ * The agent names below (agent1, agent2, director1, etc.) are PLACEHOLDERS.
+ * Replace them with your own agent IDs to match your fleet configuration.
+ *
+ * Single-agent installs: you don't need to edit this. Your agent ID is
+ * resolved automatically at runtime from your OpenClaw config.
+ *
+ * Multi-agent installs: edit the agents map and orgs map below, then
+ * rebuild (`npm run build`). See INSTALL.md § "Configure your fleet" for
+ * a worked example.
+ * ─────────────────────────────────────────────────────────────────────────
  */
 export declare function defaultOrgRegistry(): OrgRegistry;
 export declare function canAccess(requester: AgentIdentity, target: AgentIdentity, visibility: MemoryVisibility, registry: OrgRegistry): boolean;

package/dist/cross-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cross-agent.d.ts","sourceRoot":"","sources":["../src/cross-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,aAAa,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAK1C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACvC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,WAAW,CA2BhD;AAID,wBAAgB,SAAS,CACvB,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,gBAAgB,EAC5B,QAAQ,EAAE,WAAW,GACpB,OAAO,CAaT;AASD,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,aAAa,EACxB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,WAAW,GACpB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,CA6B3F;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,YAAY,GAAG,WAAW,CAgD3E;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,+BAAyB,CAAC;AAI5D;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,eAAe,EAC1B,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,WAAW,GACpB,OAAO,EAAE,CAgCX"}
+{"version":3,"file":"cross-agent.d.ts","sourceRoot":"","sources":["../src/cross-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,aAAa,EACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAK1C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACvC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,IAAI,WAAW,CA2BhD;AAID,wBAAgB,SAAS,CACvB,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,gBAAgB,EAC5B,QAAQ,EAAE,WAAW,GACpB,OAAO,CAaT;AASD,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,aAAa,EACxB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,WAAW,GACpB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,OAAO,CAAA;CAAE,CA6B3F;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,YAAY,GAAG,WAAW,CAgD3E;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,+BAAyB,CAAC;AAI5D;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,eAAe,EAC1B,KAAK,EAAE,eAAe,EACtB,QAAQ,EAAE,WAAW,GACpB,OAAO,EAAE,CAgCX"}

package/dist/cross-agent.js

@@ -19,30 +19,42 @@
 import { FleetStore } from './fleet-store.js';
 /**
  * Default fleet org structure.
+ *
+ * ── EXAMPLE DATA ──────────────────────────────────────────────────────────
+ * The agent names below (agent1, agent2, director1, etc.) are PLACEHOLDERS.
+ * Replace them with your own agent IDs to match your fleet configuration.
+ *
+ * Single-agent installs: you don't need to edit this. Your agent ID is
+ * resolved automatically at runtime from your OpenClaw config.
+ *
+ * Multi-agent installs: edit the agents map and orgs map below, then
+ * rebuild (`npm run build`). See INSTALL.md § "Configure your fleet" for
+ * a worked example.
+ * ─────────────────────────────────────────────────────────────────────────
  */
 export function defaultOrgRegistry() {
     const agents = {
-        alice: { agentId: 'alice', tier: 'council' },
-        bob: { agentId: 'bob', tier: 'council' },
-        clarity: { agentId: 'clarity', tier: 'council' },
-        dave: { agentId: 'dave', tier: 'council' },
-        carol: { agentId: 'carol', tier: 'council' },
-        oscar: { agentId: 'oscar', tier: 'council' },
-        hank: { agentId: 'hank', tier: 'director', org: 'alice-org', councilLead: 'alice' },
-        jack: { agentId: 'jack', tier: 'director', org: 'alice-org', councilLead: 'alice' },
-        irene: { agentId: 'irene', tier: 'director', org: 'alice-org', councilLead: 'alice' },
-        eve: { agentId: 'eve', tier: 'director', org: 'bob-org', councilLead: 'bob' },
-        frank: { agentId: 'frank', tier: 'director', org: 'bob-org', councilLead: 'bob' },
-        grace: { agentId: 'grace', tier: 'director', org: 'bob-org', councilLead: 'bob' },
-        leo: { agentId: 'leo', tier: 'director', org: 'dave-org', councilLead: 'dave' },
-        kate: { agentId: 'kate', tier: 'director', org: 'dave-org', councilLead: 'dave' },
-        mike: { agentId: 'mike', tier: 'specialist' },
-        nancy: { agentId: 'nancy', tier: 'specialist' },
+        agent1: { agentId: 'agent1', tier: 'council' },
+        agent2: { agentId: 'agent2', tier: 'council' },
+        agent4: { agentId: 'agent4', tier: 'council' },
+        agent3: { agentId: 'agent3', tier: 'council' },
+        agent6: { agentId: 'agent6', tier: 'council' },
+        agent5: { agentId: 'agent5', tier: 'council' },
+        director1: { agentId: 'director1', tier: 'director', org: 'agent1-org', councilLead: 'agent1' },
+        director2: { agentId: 'director2', tier: 'director', org: 'agent1-org', councilLead: 'agent1' },
+        director3: { agentId: 'director3', tier: 'director', org: 'agent1-org', councilLead: 'agent1' },
+        director4: { agentId: 'director4', tier: 'director', org: 'agent2-org', councilLead: 'agent2' },
+        director5: { agentId: 'director5', tier: 'director', org: 'agent2-org', councilLead: 'agent2' },
+        director6: { agentId: 'director6', tier: 'director', org: 'agent2-org', councilLead: 'agent2' },
+        director7: { agentId: 'director7', tier: 'director', org: 'agent3-org', councilLead: 'agent3' },
+        director8: { agentId: 'director8', tier: 'director', org: 'agent3-org', councilLead: 'agent3' },
+        specialist1: { agentId: 'specialist1', tier: 'specialist' },
+        specialist2: { agentId: 'specialist2', tier: 'specialist' },
     };
     const orgs = {
-        'alice-org': ['alice', 'hank', 'jack', 'irene'],
-        'bob-org': ['bob', 'eve', 'frank', 'grace'],
-        'dave-org': ['dave', 'leo', 'kate'],
+        'agent1-org': ['agent1', 'director1', 'director2', 'director3'],
+        'agent2-org': ['agent2', 'director4', 'director5', 'director6'],
+        'agent3-org': ['agent3', 'director7', 'director8'],
     };
     return { orgs, agents };
 }

package/dist/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAqC3C,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD;;;GAGG;AACH,iBAAS,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAI9C;AAED;;;GAGG;AACH,iBAAS,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAIvD;AAmBD,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,CAAC;AAEpD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAC7D,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,aAAa,CAAwB;IAE7C,6EAA6E;IAC7E,IAAI,YAAY,IAAI,OAAO,CAE1B;gBAEW,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC;IAKnD;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY;IAiB3C;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IA0BjD;;;;;;OAMG;IACH,iBAAiB,IAAI,YAAY,GAAG,IAAI;IAsBxC;;;OAGG;IACH,YAAY,IAAI,YAAY;IAa5B;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY;IAIzC;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAClC,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,IAAI;IA2BR;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA+BxB;;OAEG;IACH,UAAU,IAAI,MAAM,EAAE;IAWtB;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAKpC;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAQzC;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAWzC;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA8C/C;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QACnC,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG;QAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IA4BzE;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY;IAc9D;;OAEG;IACH,KAAK,IAAI,IAAI;CAgBd"}
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAuC3C,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;CACjB;AAQD;;;GAGG;AACH,iBAAS,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAI9C;AAED;;;GAGG;AACH,iBAAS,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAIvD;AAmBD,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,CAAC;AAEpD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmC;IAC9D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAC7D,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,aAAa,CAAwB;IAE7C,6EAA6E;IAC7E,IAAI,YAAY,IAAI,OAAO,CAE1B;gBAEW,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC;IAKnD;;;OAGG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY;IAwB3C;;;;OAIG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IA0BjD;;;;;;OAMG;IACH,iBAAiB,IAAI,YAAY,GAAG,IAAI;IAsBxC;;;OAGG;IACH,YAAY,IAAI,YAAY;IAa5B;;;OAGG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY;IAIzC;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAClC,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,IAAI;IA2BR;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA+BxB;;OAEG;IACH,UAAU,IAAI,MAAM,EAAE;IAWtB;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAKpC;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE;IAQzC;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAWzC;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IA8C/C;;;;;;;OAOG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QACnC,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,GAAG;QAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IA4BzE;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY;IAc9D;;OAEG;IACH,KAAK,IAAI,IAAI;CAgBd"}

package/dist/db.js

@@ -15,6 +15,8 @@ import path from 'node:path';
 import { migrate } from './schema.js';
 import { migrateLibrary } from './library-schema.js';
 import { ENGINE_VERSION } from './version.js';
+import { ensureContextSchema } from './context-store.js';
+import { backfillContexts } from './context-backfill.js';
 // sqlite-vec extension loading — optional dependency
 import { createRequire } from 'node:module';
 let sqliteVecAvailable = null;
@@ -106,6 +108,12 @@ export class DatabaseManager {
         db = new DatabaseSync(dbPath);
         applyPragmas(db);
         migrate(db);
+        ensureContextSchema(db);
+        // Backfill contexts for existing conversations on first run after migration
+        const contextCount = db.prepare('SELECT COUNT(*) as cnt FROM contexts').get();
+        if (contextCount.cnt === 0) {
+            backfillContexts(db);
+        }
         this.messageDbs.set(agentId, db);
         return db;
     }

package/dist/dreaming-promoter.d.ts

@@ -67,7 +67,7 @@ export interface DreamerResult {
 }
 /**
  * Resolve the workspace directory for an agent.
- * Council agents live at ~/.openclaw/workspace/{agentId}/
+ * Council agents live at ~/.openclaw/workspace-council/{agentId}/
  * Other agents at ~/.openclaw/workspace/{agentId}/
  */
 export declare function resolveAgentWorkspacePath(agentId: string): Promise<string | null>;

package/dist/dreaming-promoter.js

@@ -31,7 +31,7 @@ export const DEFAULT_DREAMER_CONFIG = {
 // ─── Workspace path resolution ───────────────────────────────────────────────
 /**
  * Resolve the workspace directory for an agent.
- * Council agents live at ~/.openclaw/workspace/{agentId}/
+ * Council agents live at ~/.openclaw/workspace-council/{agentId}/
  * Other agents at ~/.openclaw/workspace/{agentId}/
  */
 export async function resolveAgentWorkspacePath(agentId) {

package/dist/index.d.ts

@@ -25,6 +25,8 @@ export type { FleetAgent, FleetOrg, AgentCapability } from './fleet-store.js';
 export { SystemStore } from './system-store.js';
 export type { SystemState, SystemEvent } from './system-store.js';
 export { WorkStore } from './work-store.js';
+export { ensureContextSchema, getActiveContext, getOrCreateActiveContext, updateContextHead, archiveContext, rotateSessionContext } from './context-store.js';
+export type { Context } from './context-store.js';
 export type { WorkItem, WorkEvent, WorkStatus } from './work-store.js';
 export { DesiredStateStore } from './desired-state-store.js';
 export { evictStaleContent, DEFAULT_EVICTION_CONFIG } from './image-eviction.js';
@@ -98,8 +100,8 @@ import { type OrgRegistry } from './cross-agent.js';
  *
  * Usage:
  *   const hm = await hypermem.create({ dataDir: '~/.openclaw/hypermem' });
- *   await hm.record('alice', 'agent:alice:webchat:main', userMsg);
- *   const result = await hm.compose({ agentId: 'alice', sessionKey: '...', ... });
+ *   await hm.record('agent1', 'agent:agent1:webchat:main', userMsg);
+ *   const result = await hm.compose({ agentId: 'agent1', sessionKey: '...', ... });
  */
 export declare class HyperMem {
     readonly dbManager: DatabaseManager;