@psiclawops/hypermem 0.5.6 → 0.7.0

package/dist/index.js

@@ -20,7 +20,9 @@ export { PreferenceStore } from './preference-store.js';
 export { FleetStore } from './fleet-store.js';
 export { SystemStore } from './system-store.js';
 export { WorkStore } from './work-store.js';
+export { ensureContextSchema, getActiveContext, getOrCreateActiveContext, updateContextHead, archiveContext, rotateSessionContext } from './context-store.js';
 export { DesiredStateStore } from './desired-state-store.js';
+export { ExpertiseStore } from './expertise-store.js';
 export { evictStaleContent, DEFAULT_EVICTION_CONFIG } from './image-eviction.js';
 export { KnowledgeGraph } from './knowledge-graph.js';
 export { RateLimiter, createRateLimitedEmbedder } from './rate-limiter.js';
@@ -34,6 +36,7 @@ export { migrate, SCHEMA_VERSION } from './schema.js';
 export { migrateLibrary, LIBRARY_SCHEMA_VERSION } from './library-schema.js';
 export { VectorStore, generateEmbeddings } from './vector-store.js';
 export { hybridSearch, buildFtsQuery } from './hybrid-retrieval.js';
+export { ContradictionDetector } from './contradiction-detector.js';
 export { DocChunkStore } from './doc-chunk-store.js';
 export { WorkspaceSeeder, seedWorkspace } from './seed.js';
 export { chunkMarkdown, chunkFile, inferCollection, hashContent, ACA_COLLECTIONS } from './doc-chunker.js';
@@ -105,11 +108,13 @@ const DEFAULT_CONFIG = {
         maxMessagesPerTick: 500,
     },
     embedding: {
+        provider: 'openai',
         ollamaUrl: 'http://localhost:11434',
-        model: 'nomic-embed-text',
-        dimensions: 768,
-        timeout: 10000,
-        batchSize: 32,
+        openaiBaseUrl: 'https://openrouter.ai/api/v1',
+        model: 'qwen/qwen3-embedding-8b',
+        dimensions: 4096,
+        timeout: 15000,
+        batchSize: 100,
     },
 };
 /**
@@ -117,8 +122,8 @@ const DEFAULT_CONFIG = {
  *
  * 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 class HyperMem {
     dbManager;
@@ -205,10 +210,18 @@ export class HyperMem {
             provider: opts?.provider,
             model: opts?.model,
         });
+        let contextId;
+        try {
+            const { getOrCreateActiveContext } = await import('./context-store.js');
+            const ctx = getOrCreateActiveContext(db, agentId, sessionKey, conversation.id);
+            contextId = ctx.id;
+        }
+        catch (_) { /* context wiring is best-effort in Phase 1 */ }
         const neutral = userMessageToNeutral(stripMessageMetadata(content));
         const stored = store.recordMessage(conversation.id, agentId, neutral, {
             tokenCount: opts?.tokenCount,
             isHeartbeat: opts?.isHeartbeat,
+            contextId,
         });
         await this.cache.pushHistory(agentId, sessionKey, [stored], this.config.compositor.maxHistoryMessages);
         await this.cache.touchSession(agentId, sessionKey);
@@ -224,8 +237,16 @@ export class HyperMem {
         if (!conversation) {
             throw new Error(`No conversation found for session ${sessionKey}`);
         }
+        let contextId;
+        try {
+            const { getOrCreateActiveContext } = await import('./context-store.js');
+            const ctx = getOrCreateActiveContext(db, agentId, sessionKey, conversation.id);
+            contextId = ctx.id;
+        }
+        catch (_) { /* context wiring is best-effort in Phase 1 */ }
         const stored = store.recordMessage(conversation.id, agentId, message, {
             tokenCount: opts?.tokenCount,
+            contextId,
         });
         await this.cache.pushHistory(agentId, sessionKey, [stored], this.config.compositor.maxHistoryMessages);
         await this.cache.touchSession(agentId, sessionKey);

package/dist/library-schema.d.ts

@@ -17,6 +17,6 @@
  *  10. Topics (cross-session thread tracking)
  */
 import type { DatabaseSync } from 'node:sqlite';
-export declare const LIBRARY_SCHEMA_VERSION = 13;
+export declare const LIBRARY_SCHEMA_VERSION = 15;
 export declare function migrateLibrary(db: DatabaseSync, engineVersion?: string): void;
 //# sourceMappingURL=library-schema.d.ts.map

package/dist/library-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"library-schema.d.ts","sourceRoot":"","sources":["../src/library-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAs5BzC,wBAAgB,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CA8L7E"}
+{"version":3,"file":"library-schema.d.ts","sourceRoot":"","sources":["../src/library-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAy5BzC,wBAAgB,cAAc,CAAC,EAAE,EAAE,YAAY,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CA6P7E"}

package/dist/library-schema.js

@@ -16,7 +16,7 @@
  *   9. Work items (fleet kanban)
  *  10. Topics (cross-session thread tracking)
  */
-export const LIBRARY_SCHEMA_VERSION = 13;
+export const LIBRARY_SCHEMA_VERSION = 15;
 function nowIso() {
     return new Date().toISOString();
 }
@@ -150,12 +150,15 @@ function applyV3Collections(db) {
       updated_at TEXT NOT NULL,
       expires_at TEXT,
       superseded_by INTEGER,
-      decay_score REAL DEFAULT 0.0
+      decay_score REAL DEFAULT 0.0,
+      valid_from TEXT,
+      invalid_at TEXT
     )
   `);
     db.exec('CREATE INDEX IF NOT EXISTS idx_facts_agent ON facts(agent_id, scope, domain)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_facts_visibility ON facts(visibility, agent_id)');
     db.exec('CREATE INDEX IF NOT EXISTS idx_facts_active ON facts(agent_id, superseded_by, decay_score, confidence DESC)');
+    db.exec('CREATE INDEX IF NOT EXISTS idx_facts_temporal_validity ON facts(agent_id, valid_from, invalid_at)');
     db.exec(`
     CREATE VIRTUAL TABLE IF NOT EXISTS facts_fts USING fts5(
       content,
@@ -1016,6 +1019,73 @@ export function migrateLibrary(db, engineVersion) {
         db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
             .run(13, nowIso());
     }
+    // ── V14: Temporal validity columns on facts ──────────────────────────
+    // valid_from / invalid_at enable "what was true on date X?" queries.
+    if (currentVersion < 14) {
+        try {
+            db.exec('ALTER TABLE facts ADD COLUMN valid_from TEXT');
+        }
+        catch { /* already exists */ }
+        try {
+            db.exec('ALTER TABLE facts ADD COLUMN invalid_at TEXT');
+        }
+        catch { /* already exists */ }
+        try {
+            db.exec('CREATE INDEX IF NOT EXISTS idx_facts_temporal_validity ON facts(agent_id, valid_from, invalid_at)');
+        }
+        catch { /* already exists */ }
+        db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(14, nowIso());
+    }
+    // ── V15: Expertise tables (domain expertise patterns) ──────────────
+    // expertise_observations: raw learnings from conversations, pipelines, reviews
+    // expertise_patterns: graduated observations with confirming evidence
+    // expertise_evidence: links observations to patterns (confirms/contradicts)
+    if (currentVersion < 15) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS expertise_observations (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        agent_id TEXT NOT NULL,
+        domain TEXT NOT NULL,
+        context TEXT,
+        observation_text TEXT NOT NULL,
+        source_type TEXT NOT NULL DEFAULT 'conversation',
+        source_ref TEXT,
+        created_at TEXT NOT NULL
+      )
+    `);
+        db.exec('CREATE INDEX IF NOT EXISTS idx_expertise_obs_agent ON expertise_observations(agent_id, domain)');
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS expertise_patterns (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        agent_id TEXT NOT NULL,
+        domain TEXT NOT NULL,
+        pattern_text TEXT NOT NULL,
+        confidence REAL DEFAULT 0.7,
+        frequency INTEGER DEFAULT 1,
+        first_seen TEXT NOT NULL,
+        last_confirmed TEXT NOT NULL,
+        invalidated_at TEXT,
+        invalidation_reason TEXT,
+        decay_score REAL DEFAULT 0.0,
+        updated_at TEXT
+      )
+    `);
+        db.exec('CREATE INDEX IF NOT EXISTS idx_expertise_patterns_agent ON expertise_patterns(agent_id, domain, invalidated_at)');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_expertise_patterns_active ON expertise_patterns(agent_id, invalidated_at, confidence DESC)');
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS expertise_evidence (
+        observation_id INTEGER NOT NULL,
+        pattern_id INTEGER NOT NULL,
+        relationship TEXT NOT NULL CHECK(relationship IN ('confirms', 'contradicts')),
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (observation_id, pattern_id)
+      )
+    `);
+        db.exec('CREATE INDEX IF NOT EXISTS idx_expertise_evidence_pattern ON expertise_evidence(pattern_id, relationship)');
+        db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(15, nowIso());
+    }
     // Always ensure meta exists before stamping the running engine version.
     // Some legacy/stale DBs reached schema >=10 without the V10 migration having
     // actually created the table, which would make startup fail with

package/dist/message-store.d.ts

@@ -43,22 +43,27 @@ export declare class MessageStore {
     /**
      * Record a message to the database.
      * Returns the stored message with its assigned ID.
+     *
+     * Phase 2 (Turn DAG): automatically sets parent_id and depth.
+     *   - parent_id = context.head_message_id (the previous message on this branch)
+     *   - depth = parent.depth + 1 (or 0 if first message)
      */
     recordMessage(conversationId: number, agentId: string, message: NeutralMessage, opts?: {
         tokenCount?: number;
         isHeartbeat?: boolean;
+        contextId?: number;
     }): StoredMessage;
     /**
      * Get recent messages for a conversation.
      */
-    getRecentMessages(conversationId: number, limit?: number): StoredMessage[];
+    getRecentMessages(conversationId: number, limit?: number, minMessageId?: number): StoredMessage[];
     /**
      * Get recent messages scoped to a topic (P3.4, Option B).
      * Returns messages matching the topic_id OR with topic_id IS NULL
      * (legacy messages created before topic tracking was introduced).
      * This is transition-safe: no legacy messages are silently dropped.
      */
-    getRecentMessagesByTopic(conversationId: number, topicId: string, limit?: number): StoredMessage[];
+    getRecentMessagesByTopic(conversationId: number, topicId: string, limit?: number, minMessageId?: number): StoredMessage[];
     /**
      * Get messages across all conversations for an agent (cross-session query).
      */
@@ -77,6 +82,30 @@ export declare class MessageStore {
      * Returns up to `n` turns (capped at 50).
      */
     getRecentTurns(sessionKey: string, n: number): RecentTurn[];
+    /**
+     * Get messages by walking the parent_id chain from a head message backward.
+     * This is the DAG-native read path introduced in Phase 3.
+     *
+     * Walks from headMessageId backward through parent_id links, collecting
+     * up to `limit` messages in chronological order.
+     *
+     * Falls back to getRecentMessages if the head message has no parent chain
+     * (e.g., legacy data before backfill).
+     */
+    getHistoryByDAGWalk(headMessageId: number, limit?: number): StoredMessage[];
+    /**
+     * Get messages scoped to a specific context_id.
+     * Used by keystone/FTS/topic recall to constrain results to the active branch.
+     */
+    getMessagesByContextId(contextId: number, limit?: number, opts?: {
+        excludeHeartbeats?: boolean;
+        requireText?: boolean;
+    }): StoredMessage[];
+    /**
+     * Full-text search constrained to a specific context_id.
+     * Phase 3: replaces unscoped searchMessages for composition paths.
+     */
+    searchMessagesByContextId(contextId: number, query: string, limit?: number): StoredMessage[];
     /**
      * Get message count for a conversation.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"message-store.d.ts","sourceRoot":"","sources":["../src/message-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,UAAU,EACX,MAAM,YAAY,CAAC;AA8CpB,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAI7C;;OAEG;IACH,uBAAuB,CACrB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE;QACL,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GACA,YAAY;IAgDf;;OAEG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAQxD;;OAEG;IACH,gBAAgB,CACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,kBAAkB,CAAC;QAC5B,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GACA,YAAY,EAAE;IAwBjB;;OAEG;IACH,kBAAkB,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE;QAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,kBAAkB,CAAC;QAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,IAAI;IA2BR;;;OAGG;IACH,aAAa,CACX,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,cAAc,EACvB,IAAI,CAAC,EAAE;QACL,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,GACA,aAAa;IA+DhB;;OAEG;IACH,iBAAiB,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,aAAa,EAAE;IAY9E;;;;;OAKG;IACH,wBAAwB,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,aAAa,EAAE;IAYtG;;OAEG;IACH,gBAAgB,CACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,iBAAiB,CAAC,EAAE,OAAO,CAAC;KAC7B,GACA,aAAa,EAAE;IAuBlB;;OAEG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,aAAa,EAAE;IAmBnF;;;;OAIG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE;IA+B3D;;OAEG;IACH,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM;IAS/C;;OAEG;IACH,OAAO,CAAC,gBAAgB;CASzB"}
+{"version":3,"file":"message-store.d.ts","sourceRoot":"","sources":["../src/message-store.ts"],"names":[],"mappings":"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"}

package/dist/message-store.js

@@ -5,6 +5,7 @@
  * All messages are stored in provider-neutral format.
  * This is the write-through layer: Redis → here.
  */
+import { getOrCreateActiveContext, updateContextHead } from './context-store.js';
 function nowIso() {
     return new Date().toISOString();
 }
@@ -70,6 +71,8 @@ export class MessageStore {
     `).run(sessionKey, agentId, channelType, opts?.channelId || null, opts?.provider || null, opts?.model || null, now, now);
         // node:sqlite returns { changes, lastInsertRowid }
         const id = result.lastInsertRowid;
+        // Ensure an active context exists for the new conversation (fire-and-forget side effect)
+        getOrCreateActiveContext(this.db, agentId, sessionKey, id);
         return {
             id,
             sessionKey,
@@ -148,6 +151,10 @@ export class MessageStore {
     /**
      * Record a message to the database.
      * Returns the stored message with its assigned ID.
+     *
+     * Phase 2 (Turn DAG): automatically sets parent_id and depth.
+     *   - parent_id = context.head_message_id (the previous message on this branch)
+     *   - depth = parent.depth + 1 (or 0 if first message)
      */
     recordMessage(conversationId, agentId, message, opts) {
         const now = nowIso();
@@ -156,11 +163,30 @@ export class MessageStore {
             .prepare('SELECT MAX(message_index) AS max_idx FROM messages WHERE conversation_id = ?')
             .get(conversationId);
         const messageIndex = (lastRow?.max_idx ?? -1) + 1;
+        // Phase 2 (Turn DAG): resolve parent_id and depth from context head
+        let parentId = null;
+        let depth = 0;
+        if (opts?.contextId) {
+            const headRow = this.db
+                .prepare('SELECT head_message_id FROM contexts WHERE id = ?')
+                .get(opts.contextId);
+            if (headRow?.head_message_id != null) {
+                parentId = headRow.head_message_id;
+                const parentDepthRow = this.db
+                    .prepare('SELECT depth FROM messages WHERE id = ?')
+                    .get(parentId);
+                depth = (parentDepthRow?.depth ?? -1) + 1;
+            }
+        }
         const result = this.db.prepare(`
-      INSERT INTO messages (conversation_id, agent_id, role, text_content, tool_calls, tool_results, metadata, token_count, message_index, is_heartbeat, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(conversationId, agentId, message.role, message.textContent, message.toolCalls ? JSON.stringify(message.toolCalls) : null, message.toolResults ? JSON.stringify(message.toolResults) : null, message.metadata ? JSON.stringify(message.metadata) : null, opts?.tokenCount || null, messageIndex, opts?.isHeartbeat ? 1 : 0, now);
+      INSERT INTO messages (conversation_id, agent_id, role, text_content, tool_calls, tool_results, metadata, token_count, message_index, is_heartbeat, created_at, context_id, parent_id, depth)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(conversationId, agentId, message.role, message.textContent, message.toolCalls ? JSON.stringify(message.toolCalls) : null, message.toolResults ? JSON.stringify(message.toolResults) : null, message.metadata ? JSON.stringify(message.metadata) : null, opts?.tokenCount || null, messageIndex, opts?.isHeartbeat ? 1 : 0, now, opts?.contextId ?? null, parentId, depth);
         const id = result.lastInsertRowid;
+        // Update context head pointer if contextId was provided
+        if (opts?.contextId) {
+            updateContextHead(this.db, opts.contextId, Number(id));
+        }
         // Update conversation counters
         const tokenDelta = opts?.tokenCount || 0;
         const isOutput = message.role === 'assistant';
@@ -190,13 +216,16 @@ export class MessageStore {
     /**
      * Get recent messages for a conversation.
      */
-    getRecentMessages(conversationId, limit = 50) {
-        const rows = this.db.prepare(`
-      SELECT * FROM messages
-      WHERE conversation_id = ?
-      ORDER BY message_index DESC
-      LIMIT ?
-    `).all(conversationId, limit);
+    getRecentMessages(conversationId, limit = 50, minMessageId) {
+        const params = [conversationId];
+        let sql = 'SELECT * FROM messages WHERE conversation_id = ?';
+        if (minMessageId != null) {
+            sql += ' AND id >= ?';
+            params.push(minMessageId);
+        }
+        sql += ' ORDER BY message_index DESC LIMIT ?';
+        params.push(limit);
+        const rows = this.db.prepare(sql).all(...params);
         // Reverse to get chronological order
         return rows.reverse().map(parseMessageRow);
     }
@@ -206,13 +235,16 @@ export class MessageStore {
      * (legacy messages created before topic tracking was introduced).
      * This is transition-safe: no legacy messages are silently dropped.
      */
-    getRecentMessagesByTopic(conversationId, topicId, limit = 50) {
-        const rows = this.db.prepare(`
-      SELECT * FROM messages
-      WHERE conversation_id = ? AND (topic_id = ? OR topic_id IS NULL)
-      ORDER BY message_index DESC
-      LIMIT ?
-    `).all(conversationId, topicId, limit);
+    getRecentMessagesByTopic(conversationId, topicId, limit = 50, minMessageId) {
+        const params = [conversationId, topicId];
+        let sql = 'SELECT * FROM messages WHERE conversation_id = ? AND (topic_id = ? OR topic_id IS NULL)';
+        if (minMessageId != null) {
+            sql += ' AND id >= ?';
+            params.push(minMessageId);
+        }
+        sql += ' ORDER BY message_index DESC LIMIT ?';
+        params.push(limit);
+        const rows = this.db.prepare(sql).all(...params);
         // Reverse to get chronological order
         return rows.reverse().map(parseMessageRow);
     }
@@ -291,6 +323,88 @@ export class MessageStore {
             return [];
         }
     }
+    /**
+     * Get messages by walking the parent_id chain from a head message backward.
+     * This is the DAG-native read path introduced in Phase 3.
+     *
+     * Walks from headMessageId backward through parent_id links, collecting
+     * up to `limit` messages in chronological order.
+     *
+     * Falls back to getRecentMessages if the head message has no parent chain
+     * (e.g., legacy data before backfill).
+     */
+    getHistoryByDAGWalk(headMessageId, limit = 50) {
+        try {
+            // Use recursive CTE to walk backward from head
+            const rows = this.db.prepare(`
+        WITH RECURSIVE chain AS (
+          SELECT id, parent_id, depth, conversation_id, agent_id, role,
+                 text_content, tool_calls, tool_results, metadata,
+                 message_index, token_count, is_heartbeat, created_at,
+                 1 AS chain_pos
+          FROM messages
+          WHERE id = ?
+
+          UNION ALL
+
+          SELECT m.id, m.parent_id, m.depth, m.conversation_id, m.agent_id, m.role,
+                 m.text_content, m.tool_calls, m.tool_results, m.metadata,
+                 m.message_index, m.token_count, m.is_heartbeat, m.created_at,
+                 c.chain_pos + 1
+          FROM messages m
+          JOIN chain c ON m.id = c.parent_id
+          WHERE c.chain_pos < ?
+        )
+        SELECT * FROM chain ORDER BY depth ASC, message_index ASC
+      `).all(headMessageId, limit);
+            if (rows.length === 0)
+                return [];
+            return rows.map(parseMessageRow);
+        }
+        catch {
+            // DAG walk failed (e.g., no parent chain) — return empty, caller should fall back
+            return [];
+        }
+    }
+    /**
+     * Get messages scoped to a specific context_id.
+     * Used by keystone/FTS/topic recall to constrain results to the active branch.
+     */
+    getMessagesByContextId(contextId, limit = 200, opts) {
+        let sql = 'SELECT * FROM messages WHERE context_id = ?';
+        const params = [contextId];
+        if (opts?.excludeHeartbeats) {
+            sql += ' AND is_heartbeat = 0';
+        }
+        if (opts?.requireText) {
+            sql += " AND text_content IS NOT NULL AND text_content != ''";
+        }
+        sql += ' ORDER BY message_index DESC LIMIT ?';
+        params.push(limit);
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.reverse().map(parseMessageRow);
+    }
+    /**
+     * Full-text search constrained to a specific context_id.
+     * Phase 3: replaces unscoped searchMessages for composition paths.
+     */
+    searchMessagesByContextId(contextId, query, limit = 20) {
+        try {
+            const rows = this.db.prepare(`
+        WITH fts_matches AS (
+          SELECT rowid, rank FROM messages_fts WHERE messages_fts MATCH ? ORDER BY rank LIMIT ?
+        )
+        SELECT m.* FROM messages m
+        JOIN fts_matches ON m.id = fts_matches.rowid
+        WHERE m.context_id = ?
+        ORDER BY fts_matches.rank
+      `).all(query, limit * 3, contextId);
+            return rows.slice(0, limit).map(parseMessageRow);
+        }
+        catch {
+            return [];
+        }
+    }
     /**
      * Get message count for a conversation.
      */

package/dist/preference-store.d.ts

@@ -3,7 +3,7 @@
  *
  * Behavioral patterns observed about people, systems, and workflows.
  * Lives in the central library DB.
- * "ragesaq prefers architectural stability" is a preference, not a fact.
+ * "operator prefers architectural stability" is a preference, not a fact.
  */
 import type { DatabaseSync } from 'node:sqlite';
 export interface Preference {

package/dist/preference-store.js

@@ -3,7 +3,7 @@
  *
  * Behavioral patterns observed about people, systems, and workflows.
  * Lives in the central library DB.
- * "ragesaq prefers architectural stability" is a preference, not a fact.
+ * "operator prefers architectural stability" is a preference, not a fact.
  */
 function nowIso() {
     return new Date().toISOString();

package/dist/profiles.d.ts

@@ -9,7 +9,9 @@
  *   standard — 128k context, fleet default, balanced
  *   rich     — 200k+ context, multi-agent, full feature set
  */
-import type { HyperMemConfig } from './types.js';
+import type { HyperMemConfig, EmbeddingProviderConfig } from './types.js';
+/** Gemini embedding preset — use with mergeProfile() when switching fleet to Gemini. */
+export declare const GEMINI_EMBEDDING: Partial<EmbeddingProviderConfig>;
 export declare const lightProfile: HyperMemConfig;
 export declare const standardProfile: HyperMemConfig;
 export declare const fullProfile: HyperMemConfig;

package/dist/profiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../src/profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAyE,MAAM,YAAY,CAAC;AA0ExH,eAAO,MAAM,YAAY,EAAE,cAa1B,CAAC;AAsDF,eAAO,MAAM,eAAe,EAAE,cAO7B,CAAC;AAuDF,eAAO,MAAM,WAAW,EAAE,cAWzB,CAAC;AAMF,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;AAGxD,eAAO,MAAM,cAAc,gBAAe,CAAC;AAC3C,eAAO,MAAM,eAAe,gBAAc,CAAC;AAC3C,eAAO,MAAM,WAAW,gBAAc,CAAC;AAEvC,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE,cAAc,CAIxD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,cAAc,CAIzE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,WAAW,GAAG,UAAU,EAC9B,SAAS,EAAE,WAAW,CAAC,cAAc,CAAC,GACrC,cAAc,CAUhB;AAMD,KAAK,WAAW,CAAC,CAAC,IAAI;KACnB,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAChE,CAAC"}
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../src/profiles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAmC,uBAAuB,EAAe,MAAM,YAAY,CAAC;AAoBxH,wFAAwF;AACxF,eAAO,MAAM,gBAAgB,EAAE,OAAO,CAAC,uBAAuB,CAM7D,CAAC;AAwDF,eAAO,MAAM,YAAY,EAAE,cAa1B,CAAC;AAsDF,eAAO,MAAM,eAAe,EAAE,cAO7B,CAAC;AAuDF,eAAO,MAAM,WAAW,EAAE,cAWzB,CAAC;AAMF,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,CAAC;AAGxD,eAAO,MAAM,cAAc,gBAAe,CAAC;AAC3C,eAAO,MAAM,eAAe,gBAAc,CAAC;AAC3C,eAAO,MAAM,WAAW,gBAAc,CAAC;AAEvC,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,WAAW,EAAE,cAAc,CAIxD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,GAAG,cAAc,CAIzE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,WAAW,GAAG,UAAU,EAC9B,SAAS,EAAE,WAAW,CAAC,cAAc,CAAC,GACrC,cAAc,CAUhB;AAMD,KAAK,WAAW,CAAC,CAAC,IAAI;KACnB,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAChE,CAAC"}

package/dist/profiles.js

@@ -24,6 +24,14 @@ const BASE_EMBEDDING = {
     timeout: 10000,
     batchSize: 32,
 };
+/** Gemini embedding preset — use with mergeProfile() when switching fleet to Gemini. */
+export const GEMINI_EMBEDDING = {
+    provider: 'gemini',
+    model: 'gemini-embedding-2-preview',
+    dimensions: 3072,
+    timeout: 15000,
+    batchSize: 100,
+};
 // ---------------------------------------------------------------------------
 // light — 64k context window, single agent, constrained resources
 //

package/dist/repair-tool-pairs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repair-tool-pairs.d.ts","sourceRoot":"","sources":["../src/repair-tool-pairs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAmHpE"}
+{"version":3,"file":"repair-tool-pairs.d.ts","sourceRoot":"","sources":["../src/repair-tool-pairs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CA0LpE"}

package/dist/repair-tool-pairs.js

@@ -129,9 +129,80 @@ export function repairToolPairs(messages) {
         }
         result.push(msg);
     }
+    // ── Pass 4: Intra-message content block integrity ─────────────────────────
+    // Anthropic requires that every tool_result content block in a user message
+    // references a tool_use_id that exists in the IMMEDIATELY PRECEDING assistant
+    // message's content blocks. Pass 3 only checks global existence. This pass
+    // enforces adjacency.
+    let intraBlockDropped = 0;
+    for (let i = 0; i < result.length; i++) {
+        const msg = result[i];
+        if (msg.role !== 'user' || !Array.isArray(msg.content))
+            continue;
+        const content = msg.content;
+        const hasToolResultBlocks = content.some(b => b.type === 'tool_result');
+        if (!hasToolResultBlocks)
+            continue;
+        // Find the immediately preceding assistant message
+        let precedingAssistant = null;
+        for (let j = i - 1; j >= 0; j--) {
+            if (result[j].role === 'assistant') {
+                precedingAssistant = result[j];
+                break;
+            }
+        }
+        // Collect tool_use IDs from the preceding assistant message only
+        const adjacentCallIds = new Set();
+        if (precedingAssistant) {
+            // Content array format
+            if (Array.isArray(precedingAssistant.content)) {
+                for (const block of precedingAssistant.content) {
+                    if ((block.type === 'toolCall' || block.type === 'tool_use') &&
+                        typeof block.id === 'string' && block.id) {
+                        adjacentCallIds.add(block.id);
+                    }
+                }
+            }
+            // NeutralMessage format
+            if (Array.isArray(precedingAssistant.toolCalls)) {
+                for (const tc of precedingAssistant.toolCalls) {
+                    if (typeof tc.id === 'string' && tc.id)
+                        adjacentCallIds.add(tc.id);
+                }
+            }
+        }
+        // Also check pi-agent ToolResultMessages that reference the preceding assistant
+        // (these are message-level, not content-block level — skip for adjacency check)
+        // Filter: keep tool_result blocks only if their tool_use_id is in the
+        // immediately preceding assistant message
+        const filteredContent = content.filter(block => {
+            if (block.type !== 'tool_result')
+                return true;
+            const toolUseId = typeof block.tool_use_id === 'string' ? block.tool_use_id : '';
+            if (!toolUseId)
+                return false; // malformed, drop
+            if (adjacentCallIds.has(toolUseId))
+                return true;
+            intraBlockDropped++;
+            return false;
+        });
+        if (filteredContent.length === 0) {
+            // All content blocks were orphaned — remove the message entirely
+            result.splice(i, 1);
+            i--; // re-check this index
+        }
+        else if (filteredContent.length !== content.length) {
+            result[i] = { ...msg, content: filteredContent };
+        }
+    }
     const dropped = messages.length - result.length;
-    if (dropped > 0) {
-        console.log(`[hypermem] repairToolPairs: dropped ${dropped} orphaned message(s) (${messages.length} → ${result.length})`);
+    if (dropped > 0 || intraBlockDropped > 0) {
+        const parts = [];
+        if (dropped > 0)
+            parts.push(`${dropped} orphaned message(s)`);
+        if (intraBlockDropped > 0)
+            parts.push(`${intraBlockDropped} intra-message orphaned content block(s)`);
+        console.log(`[hypermem] repairToolPairs: dropped ${parts.join(' + ')} (${messages.length} → ${result.length})`);
     }
     return result;
 }

package/dist/schema.d.ts

@@ -6,7 +6,7 @@
  * Contains ONLY conversation data — structured knowledge lives in library.db.
  */
 import type { DatabaseSync } from 'node:sqlite';
-export declare const LATEST_SCHEMA_VERSION = 6;
+export declare const LATEST_SCHEMA_VERSION = 8;
 /**
  * Run migrations on an agent message database.
  */

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAgJvC;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA4F9C;AAED,OAAO,EAAE,qBAAqB,IAAI,cAAc,EAAE,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAgJvC;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA0H9C;AAED,OAAO,EAAE,qBAAqB,IAAI,cAAc,EAAE,CAAC"}