@psiclawops/hypermem 0.1.0 → 0.5.1

package/dist/library-schema.d.ts

@@ -1,5 +1,5 @@
 /**
- * HyperMem Library Schema — Fleet-Wide Structured Knowledge
+ * hypermem Library Schema — Fleet-Wide Structured Knowledge
  *
  * Single database: ~/.openclaw/hypermem/library.db
  * The "crown jewel" — durable, backed up, low-write-frequency.
@@ -17,6 +17,6 @@
  *  10. Topics (cross-session thread tracking)
  */
 import type { DatabaseSync } from 'node:sqlite';
-export declare const LIBRARY_SCHEMA_VERSION = 7;
-export declare function migrateLibrary(db: DatabaseSync): void;
+export declare const LIBRARY_SCHEMA_VERSION = 13;
+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,IAAI,CAAC;AA4rBxC,wBAAgB,cAAc,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA8DrD"}
+{"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"}

package/dist/library-schema.js

@@ -1,5 +1,5 @@
 /**
- * HyperMem Library Schema — Fleet-Wide Structured Knowledge
+ * hypermem Library Schema — Fleet-Wide Structured Knowledge
  *
  * Single database: ~/.openclaw/hypermem/library.db
  * The "crown jewel" — durable, backed up, low-write-frequency.
@@ -16,7 +16,7 @@
  *   9. Work items (fleet kanban)
  *  10. Topics (cross-session thread tracking)
  */
-export const LIBRARY_SCHEMA_VERSION = 7;
+export const LIBRARY_SCHEMA_VERSION = 13;
 function nowIso() {
     return new Date().toISOString();
 }
@@ -662,8 +662,211 @@ function applyV7KnowledgeVersioning(db) {
     END
   `);
 }
+// ── V9: Add session_key to doc_chunks ───────────────────────
+// Enables ephemeral session-scoped doc chunks for subagent context inheritance.
+// Chunks stored with a session_key are transient — clearSessionChunks() removes them.
+function applyV9DocChunkSessionKey(db) {
+    const cols = db.prepare('PRAGMA table_info(doc_chunks)').all()
+        .map(r => r.name);
+    if (!cols.includes('session_key')) {
+        db.exec('ALTER TABLE doc_chunks ADD COLUMN session_key TEXT');
+    }
+    db.exec('CREATE INDEX IF NOT EXISTS idx_doc_chunks_session ON doc_chunks(session_key) WHERE session_key IS NOT NULL');
+}
+// ── V8: Add source_message_id to episodes ───────────────────
+function applyV8EpisodeSourceMessageId(db) {
+    // ALTER TABLE ADD COLUMN is safe — existing rows get NULL for new column
+    const cols = db.prepare('PRAGMA table_info(episodes)').all()
+        .map(r => r.name);
+    if (!cols.includes('source_message_id')) {
+        db.exec('ALTER TABLE episodes ADD COLUMN source_message_id INTEGER');
+    }
+    db.exec('CREATE INDEX IF NOT EXISTS idx_episodes_source_msg ON episodes(agent_id, source_message_id)');
+}
+// ── V12: FOS / MOD tables + builtin seed data ──────────────
+function applyV12FosMod(db) {
+    // fleet_output_standard: fleet-wide output formatting standards
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS fleet_output_standard (
+      id                TEXT PRIMARY KEY,
+      name              TEXT NOT NULL,
+      directives        TEXT NOT NULL,
+      task_variants     TEXT DEFAULT '{}',
+      token_budget      INTEGER DEFAULT 250,
+      active            INTEGER DEFAULT 0,
+      source            TEXT DEFAULT 'builtin',
+      version           INTEGER DEFAULT 1,
+      last_validated_at TEXT,
+      created_at        TEXT NOT NULL,
+      updated_at        TEXT NOT NULL
+    )
+  `);
+    // model_output_directives: per-model corrections and calibration
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS model_output_directives (
+      id                TEXT PRIMARY KEY,
+      match_pattern     TEXT NOT NULL,
+      priority          INTEGER DEFAULT 0,
+      corrections       TEXT NOT NULL,
+      calibration       TEXT NOT NULL,
+      task_overrides    TEXT DEFAULT '{}',
+      token_budget      INTEGER DEFAULT 150,
+      version           INTEGER DEFAULT 1,
+      source            TEXT DEFAULT 'builtin',
+      enabled           INTEGER DEFAULT 1,
+      last_validated_at TEXT,
+      created_at        TEXT NOT NULL,
+      updated_at        TEXT NOT NULL
+    )
+  `);
+    // output_metrics: per-request telemetry for drift analytics
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS output_metrics (
+      id                TEXT PRIMARY KEY,
+      timestamp         TEXT NOT NULL,
+      agent_id          TEXT NOT NULL,
+      session_key       TEXT NOT NULL,
+      model_id          TEXT NOT NULL,
+      provider          TEXT NOT NULL,
+      fos_version       INTEGER,
+      mod_version       INTEGER,
+      mod_id            TEXT,
+      task_type         TEXT,
+      output_tokens     INTEGER NOT NULL,
+      input_tokens      INTEGER,
+      cache_read_tokens INTEGER,
+      corrections_fired TEXT DEFAULT '[]',
+      latency_ms        INTEGER,
+      created_at        TEXT NOT NULL
+    )
+  `);
+    db.exec('CREATE INDEX IF NOT EXISTS idx_output_metrics_model ON output_metrics(model_id, timestamp)');
+    db.exec('CREATE INDEX IF NOT EXISTS idx_output_metrics_agent ON output_metrics(agent_id, timestamp)');
+    // ── Seed builtin FOS profile ──
+    const now = nowIso();
+    const fosDirectives = JSON.stringify({
+        structural: [
+            'Lead with the answer. Conclusion first, reasoning after.',
+            'Headers earn their place. Under 200 words: no headers.',
+            'Lists cap at 7 items. Technical enumerations exempt.',
+            'One metaphor lands. Two is the limit.',
+        ],
+        anti_patterns: [
+            'No sycophantic openings: Great question, Certainly, Absolutely, Of course',
+            'No em dashes',
+            'No preamble restating the question',
+            'No: Let me know if you need anything else',
+            'No AI vocabulary: delve, tapestry, pivotal, fostering, garner, underscore, vibrant, leverage, noteworthy, realm',
+            'No unverifiable references — don\'t cite "you mentioned earlier" or "as discussed" without a direct quote',
+            'No claiming actions completed without tool results to back them up',
+            'No attributing statements to people without quoting the actual message',
+        ],
+        density_targets: {
+            simple: '1-3 sentences',
+            analysis: '200-500 words',
+            code: 'code first, explain only non-obvious parts',
+        },
+        voice: [
+            'Every sentence states a fact, makes a decision, or advances an argument',
+            'Numbers over adjectives',
+            'Vary sentence length deliberately',
+            'Match confidence to evidence: facts zero hedges, inference one hedge max',
+        ],
+    });
+    const fosVariants = JSON.stringify({
+        'council-deliberation': {
+            density_target: '400-800 words. Depth over brevity.',
+            structure: 'Headers required. Position statement, risk assessment, confidence, action.',
+        },
+        'code-generation': {
+            density_target: 'Minimize prose. Code is the deliverable.',
+            list_cap: 'DISABLED',
+        },
+        'quick-answer': {
+            density_target: '1-3 sentences.',
+            structure: 'No headers. No lists unless the answer is genuinely a list.',
+        },
+    });
+    const existingFos = db.prepare("SELECT id FROM fleet_output_standard WHERE id = 'psiclawops-default'").get();
+    if (!existingFos) {
+        db.prepare(`
+      INSERT INTO fleet_output_standard (id, name, directives, task_variants, token_budget, active, source, version, created_at, updated_at)
+      VALUES ('psiclawops-default', 'PsiClawOps Default', ?, ?, 250, 1, 'builtin', 1, ?, ?)
+    `).run(fosDirectives, fosVariants, now, now);
+    }
+    // ── Seed builtin MOD profiles ──
+    const mods = [
+        {
+            id: 'gpt-5.4',
+            match_pattern: 'gpt-5.4*',
+            priority: 10,
+            corrections: JSON.stringify([
+                { id: 'plan-loop', rule: 'If 2+ responses without concrete output, execute immediately. Ship partial.', severity: 'hard' },
+                { id: 'first-person-opening', rule: 'Do not open with I.', severity: 'medium' },
+                { id: 'throat-clearing', rule: 'No preamble before the answer.', severity: 'medium' },
+                { id: 'conditional-hedging', rule: 'Decision questions: answer + 1-2 reasons. No if-X-then-Y branching.', severity: 'medium' },
+            ]),
+            calibration: JSON.stringify([
+                { id: 'verbosity-offset', fos_target: 'analysis: 200-500 words', model_tendency: '~600 words vs Opus baseline', adjustment: 'Actively compress. Your natural output is ~2x the target. Cut first drafts in half.' },
+                { id: 'list-length-offset', fos_target: '7 items max', model_tendency: 'defaults to 12-15 items', adjustment: 'After drafting a list, cut the bottom half.' },
+            ]),
+        },
+        {
+            id: 'claude-opus-4.6',
+            match_pattern: 'claude-opus-4*',
+            priority: 10,
+            corrections: JSON.stringify([
+                { id: 'over-structuring', rule: 'Resist adding headers and sections to short answers.', severity: 'medium' },
+                { id: 'premature-enumeration', rule: "Don't list when prose works. Lists require 3+ genuinely distinct items.", severity: 'medium' },
+            ]),
+            calibration: JSON.stringify([
+                { id: 'verbosity-offset', fos_target: 'analysis: 200-500 words', model_tendency: '1.1x target', adjustment: 'Near target. Minor compression on detailed analysis.' },
+            ]),
+        },
+        {
+            id: 'claude-sonnet-4.6',
+            match_pattern: 'claude-sonnet-4*',
+            priority: 10,
+            corrections: JSON.stringify([
+                { id: 'caveat-frontloading', rule: "Don't open with caveats. State the answer, then caveats if needed.", severity: 'medium' },
+                { id: 'safety-hedging', rule: 'Minimize safety qualifiers on unambiguous requests.', severity: 'medium' },
+            ]),
+            calibration: JSON.stringify([
+                { id: 'verbosity-offset', fos_target: 'analysis: 200-500 words', model_tendency: '1.3x target', adjustment: 'Compress by ~25%. Cut qualifications and restatements.' },
+            ]),
+        },
+        {
+            id: 'gemini-3.1',
+            match_pattern: 'gemini-3.1*',
+            priority: 10,
+            corrections: JSON.stringify([
+                { id: 'numbered-list-default', rule: "Don't default to numbered lists. Use prose unless order matters.", severity: 'hard' },
+                { id: 'source-attribution-noise', rule: 'Skip attribution boilerplate unless sourcing is specifically requested.', severity: 'medium' },
+            ]),
+            calibration: JSON.stringify([
+                { id: 'list-length-offset', fos_target: '7 items max', model_tendency: '1.5x target', adjustment: 'Cut lists to 7 items. Merge or drop the rest.' },
+            ]),
+        },
+        {
+            id: 'default',
+            match_pattern: '*',
+            priority: 0,
+            corrections: JSON.stringify([]),
+            calibration: JSON.stringify([]),
+        },
+    ];
+    for (const mod of mods) {
+        const existing = db.prepare('SELECT id FROM model_output_directives WHERE id = ?').get(mod.id);
+        if (!existing) {
+            db.prepare(`
+        INSERT INTO model_output_directives (id, match_pattern, priority, corrections, calibration, task_overrides, token_budget, version, source, enabled, created_at, updated_at)
+        VALUES (?, ?, ?, ?, ?, '{}', 150, 1, 'builtin', 1, ?, ?)
+      `).run(mod.id, mod.match_pattern, mod.priority, mod.corrections, mod.calibration, now, now);
+        }
+    }
+}
 // ── Migration runner ──────────────────────────────────────────
-export function migrateLibrary(db) {
+export function migrateLibrary(db, engineVersion) {
     db.exec(`
     CREATE TABLE IF NOT EXISTS schema_version (
       version INTEGER PRIMARY KEY,
@@ -713,5 +916,123 @@ export function migrateLibrary(db) {
         db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
             .run(7, nowIso());
     }
+    if (currentVersion < 8) {
+        applyV8EpisodeSourceMessageId(db);
+        db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(8, nowIso());
+    }
+    if (currentVersion < 9) {
+        applyV9DocChunkSessionKey(db);
+        db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(9, nowIso());
+    }
+    if (currentVersion < 10) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS meta (
+        key        TEXT PRIMARY KEY,
+        value      TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      )
+    `);
+        db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(10, nowIso());
+    }
+    // ── V11: Topics FTS + indexer watermarks ──────────────────
+    // topics_fts was missing from V3 (topics table was created without FTS).
+    // indexer_watermarks tracks per-agent indexer progress for resumable indexing.
+    if (currentVersion < 11) {
+        db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS topics_fts USING fts5(
+        name,
+        description,
+        content='topics',
+        content_rowid='id'
+      )
+    `);
+        db.exec(`
+      CREATE TRIGGER IF NOT EXISTS topics_fts_ai AFTER INSERT ON topics BEGIN
+        INSERT INTO topics_fts(rowid, name, description) VALUES (new.id, new.name, new.description);
+      END
+    `);
+        db.exec(`
+      CREATE TRIGGER IF NOT EXISTS topics_fts_ad AFTER DELETE ON topics BEGIN
+        INSERT INTO topics_fts(topics_fts, rowid, name, description) VALUES('delete', old.id, old.name, old.description);
+      END
+    `);
+        db.exec(`
+      CREATE TRIGGER IF NOT EXISTS topics_fts_au AFTER UPDATE ON topics BEGIN
+        INSERT INTO topics_fts(topics_fts, rowid, name, description) VALUES('delete', old.id, old.name, old.description);
+        INSERT INTO topics_fts(rowid, name, description) VALUES (new.id, new.name, new.description);
+      END
+    `);
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS indexer_watermarks (
+        agent_id TEXT PRIMARY KEY,
+        last_message_id INTEGER NOT NULL DEFAULT 0,
+        last_run_at TEXT NOT NULL
+      )
+    `);
+        db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(11, nowIso());
+    }
+    // ── V12: FOS/MOD tables + builtin seed data ──────────────
+    // fleet_output_standard: fleet-wide output standards
+    // model_output_directives: per-model correction & calibration profiles
+    // output_metrics: per-request telemetry for drift analytics
+    if (currentVersion < 12) {
+        applyV12FosMod(db);
+        db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(12, nowIso());
+    }
+    // ── V13: Temporal index ──────────────────────────────────────────────────
+    // Maps fact_id → occurred_at (unix ms). Initially backfilled from created_at
+    // (ingest time as proxy). Enables time-range retrieval for LoCoMo temporal
+    // questions without vector similarity.
+    if (currentVersion < 13) {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS temporal_index (
+        fact_id     INTEGER PRIMARY KEY REFERENCES facts(id) ON DELETE CASCADE,
+        agent_id    TEXT NOT NULL,
+        occurred_at INTEGER NOT NULL,
+        ingest_at   INTEGER NOT NULL,
+        time_ref    TEXT,
+        confidence  REAL NOT NULL DEFAULT 0.5
+      )
+    `);
+        db.exec('CREATE INDEX IF NOT EXISTS idx_temporal_agent_time ON temporal_index(agent_id, occurred_at DESC)');
+        db.exec('CREATE INDEX IF NOT EXISTS idx_temporal_occurred ON temporal_index(occurred_at DESC)');
+        // Backfill existing facts using created_at as occurred_at proxy
+        db.exec(`
+      INSERT OR IGNORE INTO temporal_index (fact_id, agent_id, occurred_at, ingest_at, confidence)
+      SELECT
+        id,
+        agent_id,
+        CAST((julianday(created_at) - 2440587.5) * 86400000 AS INTEGER),
+        CAST((julianday(created_at) - 2440587.5) * 86400000 AS INTEGER),
+        0.5
+      FROM facts
+      WHERE superseded_by IS NULL
+    `);
+        db.prepare('INSERT INTO schema_version (version, applied_at) VALUES (?, ?)')
+            .run(13, 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
+    // "no such table: meta" during an otherwise unrelated init path.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS meta (
+      key        TEXT PRIMARY KEY,
+      value      TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    )
+  `);
+    // Always stamp the running engine version so any query can surface it.
+    if (engineVersion) {
+        db.prepare(`
+      INSERT INTO meta (key, value, updated_at) VALUES ('engine_version', ?, ?)
+      ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
+    `).run(engineVersion, nowIso());
+    }
 }
 //# sourceMappingURL=library-schema.js.map

package/dist/message-store.d.ts

@@ -1,12 +1,12 @@
 /**
- * HyperMem Message Store
+ * 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';
+import type { NeutralMessage, StoredMessage, Conversation, ChannelType, ConversationStatus, RecentTurn } from './types.js';
 export declare class MessageStore {
     private readonly db;
     constructor(db: DatabaseSync);
@@ -52,6 +52,13 @@ export declare class MessageStore {
      * Get recent messages for a conversation.
      */
     getRecentMessages(conversationId: number, limit?: 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[];
     /**
      * Get messages across all conversations for an agent (cross-session query).
      */
@@ -64,6 +71,12 @@ export declare class MessageStore {
      * Full-text search across all messages for an agent.
      */
     searchMessages(agentId: string, query: string, limit?: number): StoredMessage[];
+    /**
+     * Get recent turns for a session, in chronological order, with tool calls stripped.
+     * Joins messages through conversations to find by session_key.
+     * Returns up to `n` turns (capped at 50).
+     */
+    getRecentTurns(sessionKey: string, n: number): RecentTurn[];
     /**
      * 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,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"}
+{"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"}

package/dist/message-store.js

@@ -1,5 +1,5 @@
 /**
- * HyperMem Message Store
+ * hypermem Message Store
  *
  * CRUD operations for conversations and messages in SQLite.
  * All messages are stored in provider-neutral format.
@@ -200,6 +200,22 @@ export class MessageStore {
         // Reverse to get chronological order
         return rows.reverse().map(parseMessageRow);
     }
+    /**
+     * 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, 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);
+        // Reverse to get chronological order
+        return rows.reverse().map(parseMessageRow);
+    }
     /**
      * Get messages across all conversations for an agent (cross-session query).
      */
@@ -241,6 +257,40 @@ export class MessageStore {
     `).all(query, limit);
         return rows.map(parseMessageRow);
     }
+    /**
+     * Get recent turns for a session, in chronological order, with tool calls stripped.
+     * Joins messages through conversations to find by session_key.
+     * Returns up to `n` turns (capped at 50).
+     */
+    getRecentTurns(sessionKey, n) {
+        const limit = Math.min(n, 50);
+        try {
+            const rows = this.db.prepare(`
+        SELECT m.role, m.text_content, m.created_at, m.message_index
+        FROM messages m
+        JOIN conversations c ON m.conversation_id = c.id
+        WHERE c.session_key = ?
+          AND m.role IN ('user', 'assistant')
+        ORDER BY m.message_index DESC
+        LIMIT ?
+      `).all(sessionKey, limit);
+            // Reverse to chronological order
+            rows.reverse();
+            return rows.map(row => ({
+                role: row.role,
+                // text_content only — tool calls are stored separately and excluded here
+                content: row.text_content ?? '',
+                timestamp: row.created_at
+                    ? new Date(row.created_at).getTime()
+                    : Date.now(),
+                seq: row.message_index,
+            }));
+        }
+        catch (err) {
+            console.warn('[hypermem:message-store] getRecentTurns failed:', err.message);
+            return [];
+        }
+    }
     /**
      * Get message count for a conversation.
      */

package/dist/metrics-dashboard.d.ts

@@ -0,0 +1,114 @@
+/**
+ * hypermem Metrics Dashboard
+ *
+ * Provides a unified surface for observing system health:
+ * - Memory counts (facts, pages, episodes, vectors)
+ * - Composition performance (avg assembly time, budget utilization)
+ * - Ingestion stats (indexer throughput, promotion rate)
+ * - Embedding stats (cache hit rate, Ollama availability)
+ *
+ * All queries are read-only and safe to call on hot DBs.
+ */
+import type { DatabaseSync } from 'node:sqlite';
+export interface FactMetrics {
+    /** Total facts indexed across all agents */
+    totalFacts: number;
+    /** Facts per agent breakdown */
+    byAgent: Record<string, number>;
+    /** Facts added in the last 24h */
+    recentFacts: number;
+}
+export interface WikiMetrics {
+    /** Total synthesized wiki pages (non-superseded) */
+    totalPages: number;
+    /** Pages per agent */
+    byAgent: Record<string, number>;
+    /** Pages synthesized in the last 24h */
+    recentPages: number;
+    /** Oldest page age in hours (staleness indicator) */
+    oldestPageAgeHours: number | null;
+}
+export interface EpisodeMetrics {
+    /** Total episodes stored */
+    totalEpisodes: number;
+    /** Episodes per agent */
+    byAgent: Record<string, number>;
+    /** Average episode significance score (0-1) */
+    avgSignificance: number | null;
+}
+export interface VectorMetrics {
+    /** Total vectors indexed */
+    totalVectors: number;
+    /** Breakdown by source table */
+    byTable: Record<string, number>;
+    /** Embedding cache hit rate (0-1) for this process lifetime */
+    cacheHitRate: number | null;
+}
+export interface CompositionMetrics {
+    /** Average assembly time in ms (from output_metrics table) */
+    avgAssemblyMs: number | null;
+    /** p95 assembly time in ms */
+    p95AssemblyMs: number | null;
+    /** Average output tokens per turn */
+    avgOutputTokens: number | null;
+    /** Average input tokens per turn (context size) */
+    avgInputTokens: number | null;
+    /** Number of turns recorded */
+    totalTurns: number;
+    /** Average cache read tokens (Anthropic prompt cache utilization) */
+    avgCacheReadTokens: number | null;
+}
+export interface IngestionMetrics {
+    /** Total messages processed by the background indexer */
+    totalMessagesIndexed: number;
+    /** Total facts extracted */
+    totalFactsExtracted: number;
+    /** Noise rejection rate (1 - facts/messages, approximate) */
+    noiseRejectionRate: number | null;
+    /** Total episodes created */
+    totalEpisodesCreated: number;
+    /** Total knowledge items promoted by dreaming promoter */
+    totalKnowledgePromoted: number;
+}
+export interface SystemHealth {
+    /** Whether the main DB is readable */
+    mainDbOk: boolean;
+    /** Whether the library DB is readable */
+    libraryDbOk: boolean;
+    /** Main DB schema version */
+    mainSchemaVersion: number | null;
+    /** Library DB schema version */
+    librarySchemaVersion: number | null;
+    /** hypermem package version */
+    packageVersion: string;
+    /** Cache connection status (if provided) */
+    cacheOk: boolean | null;
+    /** Timestamp of this snapshot */
+    snapshotAt: string;
+}
+export interface HyperMemMetrics {
+    facts: FactMetrics;
+    wiki: WikiMetrics;
+    episodes: EpisodeMetrics;
+    vectors: VectorMetrics;
+    composition: CompositionMetrics;
+    ingestion: IngestionMetrics;
+    health: SystemHealth;
+}
+export interface MetricsDashboardOptions {
+    /** Agent IDs to scope to. If omitted, returns fleet-wide metrics. */
+    agentIds?: string[];
+    /** Include per-agent breakdowns. Default: true */
+    includeBreakdowns?: boolean;
+}
+/**
+ * Collect all metrics in a single pass.
+ * Safe to call on live DBs — all queries are read-only.
+ */
+export declare function collectMetrics(mainDb: DatabaseSync, libraryDb: DatabaseSync, opts?: MetricsDashboardOptions): Promise<HyperMemMetrics>;
+/**
+ * Format metrics as a human-readable summary string.
+ * Suitable for logging or status replies.
+ */
+export declare function formatMetricsSummary(m: HyperMemMetrics): string;
+//# sourceMappingURL=metrics-dashboard.d.ts.map

package/dist/metrics-dashboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-dashboard.d.ts","sourceRoot":"","sources":["../src/metrics-dashboard.ts"],"names":[],"mappings":"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"}