@psiclawops/hypermem 0.1.0

package/dist/message-store.d.ts

@@ -0,0 +1,76 @@
+/**
+ * HyperMem Message Store
+ *
+ * CRUD operations for conversations and messages in SQLite.
+ * All messages are stored in provider-neutral format.
+ * This is the write-through layer: Redis → here.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { NeutralMessage, StoredMessage, Conversation, ChannelType, ConversationStatus } from './types.js';
+export declare class MessageStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Get or create a conversation for a session.
+     */
+    getOrCreateConversation(agentId: string, sessionKey: string, opts?: {
+        channelType?: ChannelType;
+        channelId?: string;
+        provider?: string;
+        model?: string;
+    }): Conversation;
+    /**
+     * Get a conversation by session key.
+     */
+    getConversation(sessionKey: string): Conversation | null;
+    /**
+     * Get all conversations for an agent, optionally filtered.
+     */
+    getConversations(agentId: string, opts?: {
+        status?: ConversationStatus;
+        channelType?: ChannelType;
+        limit?: number;
+    }): Conversation[];
+    /**
+     * Update conversation metadata.
+     */
+    updateConversation(conversationId: number, updates: {
+        provider?: string;
+        model?: string;
+        status?: ConversationStatus;
+        endedAt?: string;
+    }): void;
+    /**
+     * Record a message to the database.
+     * Returns the stored message with its assigned ID.
+     */
+    recordMessage(conversationId: number, agentId: string, message: NeutralMessage, opts?: {
+        tokenCount?: number;
+        isHeartbeat?: boolean;
+    }): StoredMessage;
+    /**
+     * Get recent messages for a conversation.
+     */
+    getRecentMessages(conversationId: number, limit?: number): StoredMessage[];
+    /**
+     * Get messages across all conversations for an agent (cross-session query).
+     */
+    getAgentMessages(agentId: string, opts?: {
+        since?: string;
+        limit?: number;
+        excludeHeartbeats?: boolean;
+    }): StoredMessage[];
+    /**
+     * Full-text search across all messages for an agent.
+     */
+    searchMessages(agentId: string, query: string, limit?: number): StoredMessage[];
+    /**
+     * Get message count for a conversation.
+     */
+    getMessageCount(conversationId: number): number;
+    /**
+     * Infer channel type from session key format.
+     */
+    private inferChannelType;
+}
+//# sourceMappingURL=message-store.d.ts.map

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

@@ -0,0 +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,EACnB,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;;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;;OAEG;IACH,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM;IAS/C;;OAEG;IACH,OAAO,CAAC,gBAAgB;CASzB"}

package/dist/message-store.js

@@ -0,0 +1,273 @@
+/**
+ * HyperMem Message Store
+ *
+ * CRUD operations for conversations and messages in SQLite.
+ * All messages are stored in provider-neutral format.
+ * This is the write-through layer: Redis → here.
+ */
+function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Parse a stored message row from SQLite into a StoredMessage object.
+ */
+function parseMessageRow(row) {
+    return {
+        id: row.id,
+        conversationId: row.conversation_id,
+        agentId: row.agent_id,
+        role: row.role,
+        textContent: row.text_content || null,
+        toolCalls: row.tool_calls ? JSON.parse(row.tool_calls) : null,
+        toolResults: row.tool_results ? JSON.parse(row.tool_results) : null,
+        metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+        messageIndex: row.message_index,
+        tokenCount: row.token_count || null,
+        isHeartbeat: row.is_heartbeat === 1,
+        createdAt: row.created_at,
+    };
+}
+function parseConversationRow(row) {
+    return {
+        id: row.id,
+        sessionKey: row.session_key,
+        sessionId: row.session_id || null,
+        agentId: row.agent_id,
+        channelType: row.channel_type,
+        channelId: row.channel_id || null,
+        provider: row.provider || null,
+        model: row.model || null,
+        status: row.status,
+        messageCount: row.message_count,
+        tokenCountIn: row.token_count_in,
+        tokenCountOut: row.token_count_out,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        endedAt: row.ended_at || null,
+    };
+}
+export class MessageStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    // ─── Conversation Operations ─────────────────────────────────
+    /**
+     * Get or create a conversation for a session.
+     */
+    getOrCreateConversation(agentId, sessionKey, opts) {
+        const existing = this.db
+            .prepare('SELECT * FROM conversations WHERE session_key = ?')
+            .get(sessionKey);
+        if (existing) {
+            return parseConversationRow(existing);
+        }
+        const now = nowIso();
+        const channelType = opts?.channelType || this.inferChannelType(sessionKey);
+        const result = this.db.prepare(`
+      INSERT INTO conversations (session_key, agent_id, channel_type, channel_id, provider, model, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(sessionKey, agentId, channelType, opts?.channelId || null, opts?.provider || null, opts?.model || null, now, now);
+        // node:sqlite returns { changes, lastInsertRowid }
+        const id = result.lastInsertRowid;
+        return {
+            id,
+            sessionKey,
+            sessionId: null,
+            agentId,
+            channelType,
+            channelId: opts?.channelId || null,
+            provider: opts?.provider || null,
+            model: opts?.model || null,
+            status: 'active',
+            messageCount: 0,
+            tokenCountIn: 0,
+            tokenCountOut: 0,
+            createdAt: now,
+            updatedAt: now,
+            endedAt: null,
+        };
+    }
+    /**
+     * Get a conversation by session key.
+     */
+    getConversation(sessionKey) {
+        const row = this.db
+            .prepare('SELECT * FROM conversations WHERE session_key = ?')
+            .get(sessionKey);
+        return row ? parseConversationRow(row) : null;
+    }
+    /**
+     * Get all conversations for an agent, optionally filtered.
+     */
+    getConversations(agentId, opts) {
+        let sql = 'SELECT * FROM conversations WHERE agent_id = ?';
+        const params = [agentId];
+        if (opts?.status) {
+            sql += ' AND status = ?';
+            params.push(opts.status);
+        }
+        if (opts?.channelType) {
+            sql += ' AND channel_type = ?';
+            params.push(opts.channelType);
+        }
+        sql += ' ORDER BY updated_at DESC';
+        if (opts?.limit) {
+            sql += ' LIMIT ?';
+            params.push(opts.limit);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseConversationRow);
+    }
+    /**
+     * Update conversation metadata.
+     */
+    updateConversation(conversationId, updates) {
+        const sets = ['updated_at = ?'];
+        const params = [nowIso()];
+        if (updates.provider !== undefined) {
+            sets.push('provider = ?');
+            params.push(updates.provider);
+        }
+        if (updates.model !== undefined) {
+            sets.push('model = ?');
+            params.push(updates.model);
+        }
+        if (updates.status !== undefined) {
+            sets.push('status = ?');
+            params.push(updates.status);
+        }
+        if (updates.endedAt !== undefined) {
+            sets.push('ended_at = ?');
+            params.push(updates.endedAt);
+        }
+        params.push(conversationId);
+        this.db.prepare(`UPDATE conversations SET ${sets.join(', ')} WHERE id = ?`).run(...params);
+    }
+    // ─── Message Operations ──────────────────────────────────────
+    /**
+     * Record a message to the database.
+     * Returns the stored message with its assigned ID.
+     */
+    recordMessage(conversationId, agentId, message, opts) {
+        const now = nowIso();
+        // Get next message index
+        const lastRow = this.db
+            .prepare('SELECT MAX(message_index) AS max_idx FROM messages WHERE conversation_id = ?')
+            .get(conversationId);
+        const messageIndex = (lastRow?.max_idx ?? -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);
+        const id = result.lastInsertRowid;
+        // Update conversation counters
+        const tokenDelta = opts?.tokenCount || 0;
+        const isOutput = message.role === 'assistant';
+        this.db.prepare(`
+      UPDATE conversations
+      SET message_count = message_count + 1,
+          token_count_in = token_count_in + ?,
+          token_count_out = token_count_out + ?,
+          updated_at = ?
+      WHERE id = ?
+    `).run(isOutput ? 0 : tokenDelta, isOutput ? tokenDelta : 0, now, conversationId);
+        return {
+            id,
+            conversationId,
+            agentId,
+            role: message.role,
+            textContent: message.textContent,
+            toolCalls: message.toolCalls,
+            toolResults: message.toolResults,
+            metadata: message.metadata,
+            messageIndex,
+            tokenCount: opts?.tokenCount || null,
+            isHeartbeat: opts?.isHeartbeat || false,
+            createdAt: now,
+        };
+    }
+    /**
+     * 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);
+        // Reverse to get chronological order
+        return rows.reverse().map(parseMessageRow);
+    }
+    /**
+     * Get messages across all conversations for an agent (cross-session query).
+     */
+    getAgentMessages(agentId, opts) {
+        let sql = 'SELECT * FROM messages WHERE agent_id = ?';
+        const params = [agentId];
+        if (opts?.since) {
+            sql += ' AND created_at > ?';
+            params.push(opts.since);
+        }
+        if (opts?.excludeHeartbeats) {
+            sql += ' AND is_heartbeat = 0';
+        }
+        sql += ' ORDER BY created_at DESC';
+        if (opts?.limit) {
+            sql += ' LIMIT ?';
+            params.push(opts.limit);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseMessageRow);
+    }
+    /**
+     * Full-text search across all messages for an agent.
+     */
+    searchMessages(agentId, query, limit = 20) {
+        // Per-agent DB contains only one agent's data, so agent_id filter is
+        // redundant and catastrophically slows FTS (forces full result scan +
+        // join before LIMIT). Omitted by design — see bench/data-access-bench.mjs.
+        // Two-phase query: FTS subquery runs first (fast LIMIT inside FTS),
+        // then join the small result set for metadata retrieval.
+        // Direct JOIN + WHERE MATCH + ORDER BY rank + LIMIT forces SQLite to
+        // materialize the full FTS join before applying LIMIT — catastrophic
+        // on large message DBs. See: specs/HYPERMEM_INCIDENT_HISTORY.md Incident 3.
+        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 ORDER BY fts_matches.rank
+    `).all(query, limit);
+        return rows.map(parseMessageRow);
+    }
+    /**
+     * Get message count for a conversation.
+     */
+    getMessageCount(conversationId) {
+        const row = this.db
+            .prepare('SELECT COUNT(*) AS count FROM messages WHERE conversation_id = ?')
+            .get(conversationId);
+        return row.count;
+    }
+    // ─── Helpers ─────────────────────────────────────────────────
+    /**
+     * Infer channel type from session key format.
+     */
+    inferChannelType(sessionKey) {
+        if (sessionKey.includes(':webchat:'))
+            return 'webchat';
+        if (sessionKey.includes(':discord:'))
+            return 'discord';
+        if (sessionKey.includes(':telegram:'))
+            return 'telegram';
+        if (sessionKey.includes(':signal:'))
+            return 'signal';
+        if (sessionKey.includes(':subagent:') || sessionKey.includes(':spawn:'))
+            return 'subagent';
+        if (sessionKey.includes(':heartbeat'))
+            return 'heartbeat';
+        return 'other';
+    }
+}
+//# sourceMappingURL=message-store.js.map

package/dist/preference-store.d.ts

@@ -0,0 +1,54 @@
+/**
+ * HyperMem Preference Store
+ *
+ * Behavioral patterns observed about people, systems, and workflows.
+ * Lives in the central library DB.
+ * "ragesaq prefers architectural stability" is a preference, not a fact.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface Preference {
+    id: number;
+    subject: string;
+    domain: string;
+    key: string;
+    value: string;
+    agentId: string;
+    confidence: number;
+    visibility: string;
+    sourceType: string;
+    sourceRef: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare class PreferenceStore {
+    private readonly db;
+    constructor(db: DatabaseSync);
+    /**
+     * Set or update a preference. Upserts on (subject, domain, key).
+     */
+    set(subject: string, key: string, value: string, opts?: {
+        domain?: string;
+        agentId?: string;
+        confidence?: number;
+        visibility?: string;
+        sourceType?: string;
+        sourceRef?: string;
+    }): Preference;
+    /**
+     * Get a specific preference.
+     */
+    get(subject: string, key: string, domain?: string): Preference | null;
+    /**
+     * Get all preferences for a subject.
+     */
+    getForSubject(subject: string, domain?: string): Preference[];
+    /**
+     * Search preferences by value content.
+     */
+    search(query: string, subject?: string): Preference[];
+    /**
+     * Delete a preference.
+     */
+    delete(subject: string, key: string, domain?: string): boolean;
+}
+//# sourceMappingURL=preference-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preference-store.d.ts","sourceRoot":"","sources":["../src/preference-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAMhD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAmBD,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;OAEG;IACH,GAAG,CACD,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,UAAU;IA+Cb;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAkB,GAAG,UAAU,GAAG,IAAI;IAQhF;;OAEG;IACH,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE;IAe7D;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE;IAerD;;OAEG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,MAAkB,GAAG,OAAO;CAO1E"}

package/dist/preference-store.js

@@ -0,0 +1,109 @@
+/**
+ * HyperMem Preference Store
+ *
+ * Behavioral patterns observed about people, systems, and workflows.
+ * Lives in the central library DB.
+ * "ragesaq prefers architectural stability" is a preference, not a fact.
+ */
+function nowIso() {
+    return new Date().toISOString();
+}
+function parseRow(row) {
+    return {
+        id: row.id,
+        subject: row.subject,
+        domain: row.domain,
+        key: row.key,
+        value: row.value,
+        agentId: row.agent_id,
+        confidence: row.confidence,
+        visibility: row.visibility || 'fleet',
+        sourceType: row.source_type || 'observation',
+        sourceRef: row.source_ref || null,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+export class PreferenceStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Set or update a preference. Upserts on (subject, domain, key).
+     */
+    set(subject, key, value, opts) {
+        const now = nowIso();
+        const domain = opts?.domain || 'general';
+        const result = this.db.prepare(`
+      INSERT INTO preferences (subject, domain, key, value, agent_id, confidence,
+        visibility, source_type, source_ref, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(subject, domain, key) DO UPDATE SET
+        value = excluded.value,
+        confidence = excluded.confidence,
+        agent_id = excluded.agent_id,
+        source_type = excluded.source_type,
+        source_ref = excluded.source_ref,
+        updated_at = excluded.updated_at
+    `).run(subject, domain, key, value, opts?.agentId || 'system', opts?.confidence || 1.0, opts?.visibility || 'fleet', opts?.sourceType || 'observation', opts?.sourceRef || null, now, now);
+        const id = Number(result.lastInsertRowid);
+        return {
+            id,
+            subject,
+            domain,
+            key,
+            value,
+            agentId: opts?.agentId || 'system',
+            confidence: opts?.confidence || 1.0,
+            visibility: opts?.visibility || 'fleet',
+            sourceType: opts?.sourceType || 'observation',
+            sourceRef: opts?.sourceRef || null,
+            createdAt: now,
+            updatedAt: now,
+        };
+    }
+    /**
+     * Get a specific preference.
+     */
+    get(subject, key, domain = 'general') {
+        const row = this.db.prepare('SELECT * FROM preferences WHERE subject = ? AND domain = ? AND key = ?').get(subject, domain, key);
+        return row ? parseRow(row) : null;
+    }
+    /**
+     * Get all preferences for a subject.
+     */
+    getForSubject(subject, domain) {
+        let sql = 'SELECT * FROM preferences WHERE subject = ?';
+        const params = [subject];
+        if (domain) {
+            sql += ' AND domain = ?';
+            params.push(domain);
+        }
+        sql += ' ORDER BY domain, key';
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseRow);
+    }
+    /**
+     * Search preferences by value content.
+     */
+    search(query, subject) {
+        let sql = 'SELECT * FROM preferences WHERE (value LIKE ? OR key LIKE ?)';
+        const params = [`%${query}%`, `%${query}%`];
+        if (subject) {
+            sql += ' AND subject = ?';
+            params.push(subject);
+        }
+        sql += ' ORDER BY confidence DESC LIMIT 20';
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseRow);
+    }
+    /**
+     * Delete a preference.
+     */
+    delete(subject, key, domain = 'general') {
+        const result = this.db.prepare('DELETE FROM preferences WHERE subject = ? AND domain = ? AND key = ?').run(subject, domain, key);
+        return result.changes > 0;
+    }
+}
+//# sourceMappingURL=preference-store.js.map

package/dist/preservation-gate.d.ts

@@ -0,0 +1,82 @@
+/**
+ * HyperMem Preservation Gate
+ *
+ * Verifies that a proposed compaction summary preserves the semantic
+ * content of its source messages by measuring geometric fidelity in
+ * embedding space.
+ *
+ * Before a summary replaces raw messages, it must pass two checks:
+ *
+ *   1. Centroid Alignment — the summary embedding must be close to the
+ *      centroid of the source message embeddings (cos similarity).
+ *
+ *   2. Source Coverage — the summary must have positive cosine similarity
+ *      with each individual source message (averaged).
+ *
+ * If the combined preservation score falls below the threshold, the
+ * summary is rejected. The caller should fall back to extractive
+ * compaction (concatenation/selection) rather than accepting a
+ * semantically drifted summary.
+ *
+ * This prevents the silent failure mode where a confident summarizer
+ * produces fluent text that has drifted away from the original meaning
+ * in vector space — making it unretrievable by the very system that
+ * will later search for it.
+ *
+ * Inspired by the Nomic-space preservation gate in openclaw-memory-libravdb
+ * (mathematics-v2.md §5.3), adapted for our Ollama + sqlite-vec stack.
+ */
+import { type EmbeddingConfig } from './vector-store.js';
+export interface PreservationResult {
+    /** Cosine similarity between summary and source centroid */
+    alignment: number;
+    /** Average positive cosine similarity between summary and each source */
+    coverage: number;
+    /** Combined score: (alignment + coverage) / 2, clamped to [0, 1] */
+    score: number;
+    /** Whether the summary passed the preservation gate */
+    passed: boolean;
+    /** The threshold used for the gate */
+    threshold: number;
+}
+export interface PreservationConfig {
+    /**
+     * Minimum combined preservation score for a summary to be accepted.
+     * Default: 0.65 (same as libravdb's shipped default).
+     *
+     * At 0.65, the summary must be meaningfully close to the source cluster.
+     * Lower values accept more drift; higher values are stricter.
+     * Range: [0, 1].
+     */
+    threshold: number;
+    /** Embedding config for Ollama calls (used by async path only) */
+    embedding?: Partial<EmbeddingConfig>;
+}
+/**
+ * Verify that a summary preserves its source content in embedding space.
+ *
+ * SYNCHRONOUS PATH — for when you already have pre-computed embeddings
+ * (e.g., from the background indexer or vector store cache).
+ *
+ * This is the preferred path: no network calls, no async, deterministic.
+ *
+ * @param summaryEmbedding - The embedding of the proposed summary
+ * @param sourceEmbeddings - Embeddings of the source messages being replaced
+ * @param config - Preservation threshold config
+ */
+export declare function verifyPreservationFromVectors(summaryEmbedding: Float32Array, sourceEmbeddings: Float32Array[], config?: Partial<PreservationConfig>): PreservationResult;
+/**
+ * Verify that a summary preserves its source content in embedding space.
+ *
+ * ASYNC PATH — generates embeddings via Ollama on demand.
+ * Use when pre-computed embeddings aren't available.
+ *
+ * This makes N+1 embedding calls (1 for summary, N for sources if not cached).
+ * For batch compaction, prefer pre-computing embeddings and using the sync path.
+ *
+ * @param summaryText - The proposed summary text
+ * @param sourceTexts - The source message texts being replaced
+ * @param config - Preservation threshold and embedding config
+ */
+export declare function verifyPreservation(summaryText: string, sourceTexts: string[], config?: Partial<PreservationConfig>): Promise<PreservationResult>;
+//# sourceMappingURL=preservation-gate.d.ts.map

package/dist/preservation-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preservation-gate.d.ts","sourceRoot":"","sources":["../src/preservation-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAI7E,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAC;IAChB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;CACtC;AA4DD;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,YAAY,EAC9B,gBAAgB,EAAE,YAAY,EAAE,EAChC,MAAM,GAAE,OAAO,CAAC,kBAAkB,CAAM,GACvC,kBAAkB,CAmCpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EAAE,EACrB,MAAM,GAAE,OAAO,CAAC,kBAAkB,CAAM,GACvC,OAAO,CAAC,kBAAkB,CAAC,CAqB7B"}