mnueron 0.3.0 → 0.4.0

package/dist/store/local.js

@@ -5,6 +5,11 @@ import { dirname } from 'node:path';
 import * as sqliteVec from 'sqlite-vec';
 import { embed, embedBatch, EMBEDDING_DIM, preload } from './embeddings.js';
 import { chunkContent, shouldChunk, DEFAULT_CHUNK_THRESHOLD } from './chunking.js';
+import { extractEntities, shouldExtractEntities } from './entity-extractor.js';
+import { resolveEntitiesForMemory } from './entity-resolver.js';
+import { extractRelations, shouldExtractRelations } from './relation-extractor.js';
+import { ensureConsolidationSchema, detectDuplicates, listProposals, reviewProposal, } from './consolidator.js';
+import { ensureProceduralSchema, saveProcedural, getProceduralByName, listProcedural, recallProcedural, deleteProcedural, } from './procedural.js';
 import { redact } from './redactor.js';
 /**
  * Build a SQL fragment + params for the shared filter shape used by
@@ -54,6 +59,34 @@ function buildFilterFragment(f, alias = 'm') {
     }
     return { sql: parts.join(' AND '), params };
 }
+/** Clamp a caller-supplied LIMIT to a sensible max — prevents accidental
+ *  `LIMIT 999999` exhausting memory on large stores. */
+function clampLimit(want, max) {
+    if (!Number.isFinite(want) || want <= 0)
+        return Math.min(100, max);
+    return Math.min(Math.floor(want), max);
+}
+/** Materialize an `entities` row into the public Entity shape. Parses
+ *  aliases_json defensively — older rows or hand-edited data can have
+ *  malformed JSON and we'd rather return an empty alias list than throw. */
+function rowToEntity(row) {
+    let aliases = [];
+    try {
+        const parsed = JSON.parse(row.aliases_json);
+        if (Array.isArray(parsed))
+            aliases = parsed.filter((x) => typeof x === 'string');
+    }
+    catch { /* leave empty */ }
+    return {
+        id: row.id,
+        display_name: row.display_name,
+        entity_type: row.entity_type,
+        aliases,
+        mention_count: row.mention_count,
+        first_seen_at: row.first_seen_at,
+        last_seen_at: row.last_seen_at,
+    };
+}
 /**
  * Run pre-save transforms in fixed order:
  *   1. Redact secrets — never store API keys / JWTs / etc.
@@ -91,19 +124,36 @@ const FTS_STOP_WORDS = new Set([
 ]);
 /**
  * Translate a natural-language query into an FTS5 MATCH expression.
- * - strips FTS5 control characters
+ * - strips FTS5 control characters AND user-facing punctuation that
+ *   trips FTS5's parser (., /, ', etc.). FTS5's grammar treats `.` and
+ *   apostrophes as separators between identifiers — `"redeploy.sh"` is
+ *   parsed as "redeploy" "." "sh" and chokes. We replace all of these
+ *   with spaces BEFORE tokenizing so the resulting tokens are pure
+ *   alphanumeric-plus-underscore.
  * - lowercases
  * - drops stop words and 1-character tokens
  * - prefix-matches each surviving token (`token*`) so "stores" matches "stored"
  * - ORs the tokens — any one is enough, BM25 ranks multi-hit rows higher
+ *
+ * Regex characters we strip:
+ *   "  (  )  *  :  ^  ~  — FTS5 grammar
+ *   .  ,  ;  /  \  '  `  — punctuation that breaks FTS5 token boundaries
+ *   !  ?  &  |  =  +  -  # @ $  — user-typed but unsafe in MATCH
+ * This is permissive: any non-[a-z0-9_] char is replaced with a space
+ * inside `buildFtsQuery`, so we don't have to enumerate every case.
  */
 function buildFtsQuery(raw) {
-    const cleaned = raw.replace(/["()*:^~]/g, ' ').toLowerCase().trim();
+    // First: collapse anything that isn't a word-char into a space. This is
+    // safer than maintaining a denylist — FTS5 only consumes word tokens
+    // anyway, so we lose nothing by pre-flattening punctuation.
+    const cleaned = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/g, ' ')
+        .trim();
     if (!cleaned)
         return '';
     const tokens = cleaned
         .split(/\s+/)
-        .map(t => t.replace(/^[^a-z0-9_]+|[^a-z0-9_]+$/g, ''))
         .filter(t => t.length >= 2 && !FTS_STOP_WORDS.has(t));
     if (tokens.length === 0)
         return '';
@@ -206,6 +256,83 @@ export class LocalProvider {
         );
       `);
         }
+        // ── P2.3 — Entity resolution tables ──────────────────────────────────
+        // Canonical entities: one row per unique entity (person/org/project/...)
+        // resolved across all memories. `mention_count` and `last_seen_at` make
+        // it trivial to show "who/what is most active in your store right now".
+        //
+        // memory_entities: many-to-many join — one row per (memory, canonical
+        // entity) pair. `surface_form` is what the memory text actually said
+        // (e.g., "Johnny" → resolved to canonical "John Doe"); `confidence`
+        // ranges in [0, 1] from exact match (1.0) down through embedding
+        // similarity and LLM tiebreak picks (0.65-0.85).
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS entities (
+        id              TEXT PRIMARY KEY,
+        display_name    TEXT NOT NULL,
+        entity_type     TEXT NOT NULL,
+        aliases_json    TEXT NOT NULL DEFAULT '[]',
+        mention_count   INTEGER NOT NULL DEFAULT 0,
+        first_seen_at   INTEGER NOT NULL,
+        last_seen_at    INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_entities_type
+        ON entities(entity_type);
+      CREATE INDEX IF NOT EXISTS idx_entities_last_seen
+        ON entities(last_seen_at DESC);
+
+      CREATE TABLE IF NOT EXISTS memory_entities (
+        memory_id     TEXT NOT NULL,
+        entity_id     TEXT NOT NULL,
+        surface_form  TEXT NOT NULL,
+        confidence    REAL NOT NULL,
+        PRIMARY KEY (memory_id, entity_id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_memory_entities_entity
+        ON memory_entities(entity_id);
+
+      -- P3 — Knowledge-graph edges. Each row is a triple (from, predicate,
+      -- to) plus provenance (memory_id) + confidence. P4 forward-looking
+      -- columns (valid_from / valid_to) are added now so bi-temporal
+      -- queries don't require a schema migration later.
+      CREATE TABLE IF NOT EXISTS relations (
+        id              TEXT PRIMARY KEY,
+        from_entity_id  TEXT NOT NULL,
+        to_entity_id    TEXT NOT NULL,
+        predicate       TEXT NOT NULL,
+        memory_id       TEXT NOT NULL,
+        confidence      REAL NOT NULL,
+        valid_from      INTEGER,
+        valid_to        INTEGER,
+        recorded_at     INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_relations_from
+        ON relations(from_entity_id);
+      CREATE INDEX IF NOT EXISTS idx_relations_to
+        ON relations(to_entity_id);
+      CREATE INDEX IF NOT EXISTS idx_relations_predicate
+        ON relations(predicate);
+      CREATE INDEX IF NOT EXISTS idx_relations_memory
+        ON relations(memory_id);
+      CREATE INDEX IF NOT EXISTS idx_relations_valid_to
+        ON relations(valid_to);
+    `);
+        if (this.vecAvailable) {
+            // Embedding index for entity name+context strings. Used by the
+            // resolver's vector-similarity stage when finding candidate matches
+            // for a freshly extracted entity.
+            this.db.exec(`
+        CREATE VIRTUAL TABLE IF NOT EXISTS entities_vec
+        USING vec0(
+          entity_id TEXT PRIMARY KEY,
+          embedding float[${EMBEDDING_DIM}]
+        );
+      `);
+        }
+        // P5 — Consolidation proposal table (idempotent).
+        ensureConsolidationSchema(this.db);
+        // Procedural memory table (idempotent). Mem0 leapfrog feature.
+        ensureProceduralSchema(this.db);
     }
     // ─── write path ──────────────────────────────────────────────────────────
     async save(input) {
@@ -213,7 +340,39 @@ export class LocalProvider {
         //    boundaries can't slip through. Single source of truth for what
         //    hits SQLite.
         const transformed = preSaveTransform(input);
-        // 2. Long content gets auto-chunked into multiple memories. Each chunk
+        // 2. P1 — entity extraction. SECURITY-CRITICAL: capture and strip BYOK
+        //    keys from metadata BEFORE the gate check, mirroring the hosted
+        //    backend's ordering. Short-content saves with BYOK keys still get
+        //    keys scrubbed even when extraction is skipped.
+        const meta = transformed.metadata ?? {};
+        const byokAnthropic = typeof meta.byok_anthropic_key === 'string'
+            ? meta.byok_anthropic_key : undefined;
+        const byokOpenAI = typeof meta.byok_openai_key === 'string'
+            ? meta.byok_openai_key : undefined;
+        if (byokAnthropic)
+            delete meta.byok_anthropic_key;
+        if (byokOpenAI)
+            delete meta.byok_openai_key;
+        transformed.metadata = meta;
+        if (shouldExtractEntities(transformed.content.length, transformed.metadata)) {
+            // Explicit opt-in (metadata.extract_entities or BYOK) bypasses the
+            // 200-char min-length floor. Otherwise (env-var default path) the
+            // floor still applies as a guardrail against burning money on
+            // one-liner autosaves.
+            const meta = transformed.metadata;
+            const explicit = meta?.extract_entities === true ||
+                (typeof byokAnthropic === 'string' && byokAnthropic.length > 0) ||
+                (typeof byokOpenAI === 'string' && byokOpenAI.length > 0);
+            const entities = await extractEntities(transformed.content, {
+                anthropicKey: byokAnthropic,
+                openaiKey: byokOpenAI,
+                ...(explicit ? { minChars: 1 } : {}),
+            });
+            if (entities.length > 0) {
+                transformed.metadata = { ...(transformed.metadata ?? {}), entities };
+            }
+        }
+        // 3. Long content gets auto-chunked into multiple memories. Each chunk
         //    becomes a searchable atomic memory; the original conversation is
         //    linkable via `parent_ref` (= source_ref + chunk_index in metadata).
         if (shouldChunk(transformed.content)) {
@@ -247,12 +406,84 @@ export class LocalProvider {
             }
         });
         tx();
+        // ── P2.3 — Entity resolution ────────────────────────────────────────
+        // If P1 extraction stamped `metadata.entities`, resolve each one to a
+        // canonical entity (reuse OR create), insert memory_entities edges,
+        // and write the resolved canonical_ids back onto the stored metadata.
+        //
+        // This runs AFTER the memory row exists so the resolver has a valid
+        // memory_id to link to. It also runs OUTSIDE the transaction because
+        // embeddings + LLM tiebreak are async; if those fail mid-way, the
+        // memory still saved successfully (fail-open contract).
+        let finalMetadata = input.metadata;
+        const extractedEntities = Array.isArray(input.metadata?.entities)
+            ? input.metadata.entities
+            : [];
+        if (extractedEntities.length > 0) {
+            try {
+                const meta = input.metadata;
+                const byokAnthropic = typeof meta.byok_anthropic_key === 'string'
+                    ? meta.byok_anthropic_key : undefined;
+                const resolutions = await resolveEntitiesForMemory(this.db, id, extractedEntities.map((e) => ({
+                    name: e.name,
+                    type: e.type,
+                    context: e.context,
+                })), this.vecAvailable, { anthropicKey: byokAnthropic });
+                // Stamp canonical_id back onto each entity in the stored metadata.
+                const entitiesWithIds = extractedEntities.map((e, i) => ({
+                    ...e,
+                    canonical_id: resolutions[i]?.canonical_id ?? null,
+                }));
+                finalMetadata = { ...(input.metadata ?? {}), entities: entitiesWithIds };
+                this.db.prepare(`UPDATE memories SET meta_json = ?, updated_at = ? WHERE id = ?`)
+                    .run(JSON.stringify(finalMetadata), now, id);
+                // ── P3 — Relationship extraction ────────────────────────────────
+                // Once we have resolved canonical entities, ask the LLM what
+                // relationships exist between them. This populates `relations`
+                // edges that form the knowledge-graph layer. Gated separately
+                // from entity extraction so users can have entities-only without
+                // paying the second Haiku call.
+                const resolvedForRelations = extractedEntities
+                    .map((e, i) => ({
+                    canonical_id: resolutions[i]?.canonical_id ?? null,
+                    name: e.name,
+                    type: e.type,
+                }))
+                    .filter((e) => !!e.canonical_id);
+                if (shouldExtractRelations(input.content.length, resolvedForRelations.length, input.metadata)) {
+                    try {
+                        const meta = input.metadata;
+                        const byokAnthropic = typeof meta.byok_anthropic_key === 'string'
+                            ? meta.byok_anthropic_key : undefined;
+                        const relations = await extractRelations(input.content, resolvedForRelations, { anthropicKey: byokAnthropic });
+                        if (relations.length > 0) {
+                            const insertRel = this.db.prepare(`INSERT INTO relations
+                   (id, from_entity_id, to_entity_id, predicate, memory_id,
+                    confidence, valid_from, valid_to, recorded_at)
+                 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+                            const tx2 = this.db.transaction(() => {
+                                for (const r of relations) {
+                                    insertRel.run(randomUUID(), r.from_canonical_id, r.to_canonical_id, r.predicate, id, r.confidence, r.valid_from, r.valid_to, now);
+                                }
+                            });
+                            tx2();
+                        }
+                    }
+                    catch (e) {
+                        console.warn('[mnueron/local] relation extraction failed (memory + entities saved):', e instanceof Error ? e.message : e);
+                    }
+                }
+            }
+            catch (e) {
+                console.warn('[mnueron/local] entity resolution failed (memory saved without canonical_ids):', e instanceof Error ? e.message : e);
+            }
+        }
         return this.rowToMemory({
             id, namespace: ns, content: input.content,
             tags_json: JSON.stringify(tags),
             source: input.source ?? 'manual',
             source_ref: input.source_ref ?? null,
-            meta_json: input.metadata ? JSON.stringify(input.metadata) : null,
+            meta_json: finalMetadata ? JSON.stringify(finalMetadata) : null,
             created_at: now, updated_at: now,
         });
     }
@@ -558,10 +789,13 @@ export class LocalProvider {
         const existing = this.db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id);
         if (!existing)
             return null;
-        // Build merged metadata + history entry
-        const priorMeta = typeof existing.metadata === 'string'
-            ? JSON.parse(existing.metadata || '{}')
-            : (existing.metadata ?? {});
+        // Build merged metadata + history entry. Note: the column is `meta_json`,
+        // not `metadata` (same schema mismatch that broke updates before P2.3
+        // backfill ran).
+        const metaCol = existing.meta_json ?? existing.metadata;
+        const priorMeta = typeof metaCol === 'string'
+            ? JSON.parse(metaCol || '{}')
+            : (metaCol ?? {});
         const merged = { ...priorMeta };
         if (patch.metadata && typeof patch.metadata === 'object') {
             for (const [k, v] of Object.entries(patch.metadata)) {
@@ -584,13 +818,14 @@ export class LocalProvider {
             merged.history = history;
         }
         const nextNs = patch.namespace ?? existing.namespace;
-        const nextTags = patch.tags ?? JSON.parse(existing.tags ?? '[]');
+        const nextTags = patch.tags
+            ?? JSON.parse((existing.tags_json ?? existing.tags) ?? '[]');
         const now = Date.now();
         this.db.prepare(`UPDATE memories
-          SET content   = ?,
-              namespace = ?,
-              tags      = ?,
-              metadata  = ?,
+          SET content    = ?,
+              namespace  = ?,
+              tags_json  = ?,
+              meta_json  = ?,
               updated_at = ?
         WHERE id = ?`).run(nextContent, nextNs, JSON.stringify(nextTags), JSON.stringify(merged), now, id);
         // If content changed, re-index FTS + (optionally) re-embed.
@@ -643,6 +878,279 @@ export class LocalProvider {
             last_updated: r.last_updated ?? 0,
         }));
     }
+    // ─── P2.3 — Entity API ──────────────────────────────────────────────────
+    /**
+     * List canonical entities with optional type filter, free-text query
+     * against display_name + aliases, and sort. Default sort: most-recently-seen.
+     */
+    async listEntities(input = {}) {
+        const limit = clampLimit(input.limit ?? 100, 500);
+        const offset = Math.max(0, input.offset ?? 0);
+        const parts = ['1=1'];
+        const params = [];
+        if (input.type) {
+            parts.push('entity_type = ?');
+            params.push(input.type);
+        }
+        if (input.q && input.q.trim()) {
+            // Match display_name OR any alias (case-insensitive substring).
+            parts.push(`(
+        lower(display_name) LIKE lower('%' || ? || '%')
+        OR EXISTS (
+          SELECT 1 FROM json_each(aliases_json) AS a
+           WHERE lower(a.value) LIKE lower('%' || ? || '%')
+        )
+      )`);
+            params.push(input.q.trim(), input.q.trim());
+        }
+        const orderBy = (() => {
+            switch (input.sort) {
+                case 'mentions': return 'mention_count DESC, last_seen_at DESC';
+                case 'alpha': return 'lower(display_name) ASC';
+                default: return 'last_seen_at DESC'; // 'recent'
+            }
+        })();
+        const rows = this.db
+            .prepare(`SELECT * FROM entities WHERE ${parts.join(' AND ')} ORDER BY ${orderBy} LIMIT ? OFFSET ?`)
+            .all(...params, limit, offset);
+        return rows.map(rowToEntity);
+    }
+    /** Single canonical entity by id, or null if not found. */
+    async getEntity(id) {
+        const row = this.db
+            .prepare(`SELECT * FROM entities WHERE id = ? LIMIT 1`)
+            .get(id);
+        return row ? rowToEntity(row) : null;
+    }
+    /**
+     * All memories linked to a canonical entity, most recent first. Includes
+     * the original surface_form so callers can render "John (mentioned as
+     * 'Johnny')". Caps at `limit` (default 100, max 500) — entity histories
+     * can get long.
+     */
+    async getEntityMemories(id, limit = 100) {
+        const cap = clampLimit(limit, 500);
+        const rows = this.db
+            .prepare(`SELECT m.id, m.namespace, m.content, m.tags_json, m.source, m.source_ref,
+                m.meta_json, m.created_at, m.updated_at,
+                me.surface_form, me.confidence
+           FROM memory_entities me
+           JOIN memories m ON m.id = me.memory_id
+          WHERE me.entity_id = ?
+          ORDER BY m.created_at DESC
+          LIMIT ?`)
+            .all(id, cap);
+        return rows.map((r) => ({
+            ...this.rowToMemory(r),
+            surface_form: r.surface_form,
+            confidence: r.confidence,
+        }));
+    }
+    /**
+     * Merge two canonical entities. After merge:
+     *   • loserId is hard-deleted from `entities` + `entities_vec`.
+     *   • All memory_entities rows pointing at loserId are repointed at winnerId.
+     *     If the winner already has an edge to the same memory, we keep the
+     *     stronger-confidence one and drop the duplicate.
+     *   • Aliases from loser are absorbed into winner (deduped).
+     *   • mention_count is summed; first_seen_at = min, last_seen_at = max.
+     *
+     * Returns the merged winner row, or null if either id is missing.
+     *
+     * This runs in a single SQL transaction. Future enhancement: emit a
+     * `entity_merge_log` row so merges are auditable / reversible.
+     */
+    async mergeEntities(winnerId, loserId) {
+        if (winnerId === loserId)
+            return this.getEntity(winnerId);
+        const winner = this.db.prepare(`SELECT * FROM entities WHERE id = ?`).get(winnerId);
+        const loser = this.db.prepare(`SELECT * FROM entities WHERE id = ?`).get(loserId);
+        if (!winner || !loser)
+            return null;
+        let winnerAliases = [];
+        let loserAliases = [];
+        try {
+            winnerAliases = JSON.parse(winner.aliases_json);
+        }
+        catch { /* */ }
+        try {
+            loserAliases = JSON.parse(loser.aliases_json);
+        }
+        catch { /* */ }
+        const mergedAliases = Array.from(new Set([...winnerAliases, ...loserAliases, loser.display_name]));
+        const tx = this.db.transaction(() => {
+            // Repoint edges. INSERT-OR-IGNORE then DELETE-old, with confidence MAX
+            // fold to preserve the strongest edge if both winner and loser shared
+            // a memory.
+            this.db.prepare(`INSERT INTO memory_entities (memory_id, entity_id, surface_form, confidence)
+         SELECT memory_id, ?, surface_form, confidence
+           FROM memory_entities WHERE entity_id = ?
+         ON CONFLICT(memory_id, entity_id) DO UPDATE SET
+           confidence = MAX(memory_entities.confidence, excluded.confidence)`).run(winnerId, loserId);
+            this.db.prepare(`DELETE FROM memory_entities WHERE entity_id = ?`).run(loserId);
+            // Update winner aggregate.
+            this.db.prepare(`UPDATE entities SET
+           aliases_json   = ?,
+           mention_count  = mention_count + ?,
+           first_seen_at  = MIN(first_seen_at, ?),
+           last_seen_at   = MAX(last_seen_at,  ?)
+         WHERE id = ?`).run(JSON.stringify(mergedAliases), loser.mention_count, loser.first_seen_at, loser.last_seen_at, winnerId);
+            // Delete loser everywhere.
+            if (this.vecAvailable) {
+                try {
+                    this.db.prepare(`DELETE FROM entities_vec WHERE entity_id = ?`).run(loserId);
+                }
+                catch { /* vec0 sometimes lacks DELETE; non-fatal */ }
+            }
+            this.db.prepare(`DELETE FROM entities WHERE id = ?`).run(loserId);
+        });
+        tx();
+        return this.getEntity(winnerId);
+    }
+    /**
+     * P2.3 backfill — run the resolver against entities that already exist
+     * in a saved memory's metadata.entities. Used by
+     * `mnueron entities backfill` to retro-fit canonical IDs onto memories
+     * saved before the resolver shipped. Returns the resolutions parallel
+     * to `extracted` so the caller can update metadata.
+     */
+    async backfillResolveMemory(memoryId, extracted, opts = {}) {
+        if (extracted.length === 0)
+            return [];
+        const res = await resolveEntitiesForMemory(this.db, memoryId, extracted, this.vecAvailable, { anthropicKey: opts.anthropicKey });
+        return res;
+    }
+    // ─── P3 + P4 — Knowledge graph API ──────────────────────────────────────
+    /**
+     * Fetch relation edges. All filters compose with AND. Uses indexed
+     * lookups when from/to/predicate is set; otherwise sorted by most-recent.
+     *
+     * The P4 `asOf` filter implements bi-temporal recall: only edges whose
+     * validity window contains `asOf` (and edges with no temporal info,
+     * which are treated as "always valid") are returned. This is what
+     * powers queries like "what did John think about X in January?"
+     */
+    async getRelations(input) {
+        const parts = ['1=1'];
+        const params = [];
+        if (input.fromEntityId) {
+            parts.push('from_entity_id = ?');
+            params.push(input.fromEntityId);
+        }
+        if (input.toEntityId) {
+            parts.push('to_entity_id = ?');
+            params.push(input.toEntityId);
+        }
+        if (input.predicate) {
+            parts.push('predicate = ?');
+            params.push(input.predicate);
+        }
+        if (typeof input.asOf === 'number') {
+            // Match if (valid_from IS NULL OR valid_from <= asOf)
+            //     AND (valid_to   IS NULL OR valid_to   >  asOf)
+            // Edges with no temporal info pass both clauses.
+            parts.push('(valid_from IS NULL OR valid_from <= ?)');
+            parts.push('(valid_to   IS NULL OR valid_to   >  ?)');
+            params.push(input.asOf, input.asOf);
+        }
+        const limit = clampLimit(input.limit ?? 200, 1000);
+        const rows = this.db
+            .prepare(`SELECT id, from_entity_id, to_entity_id, predicate, memory_id,
+                confidence, valid_from, valid_to, recorded_at
+           FROM relations
+          WHERE ${parts.join(' AND ')}
+          ORDER BY recorded_at DESC
+          LIMIT ?`)
+            .all(...params, limit);
+        return rows;
+    }
+    /**
+     * BFS traversal from a seed entity. Visits up to `depth` hops, following
+     * BOTH outgoing and incoming edges so the user sees a complete
+     * neighborhood. Each hop carries the edge that led to it.
+     *
+     * Respects the P4 `asOf` filter — only edges valid at that point in
+     * time are followed.
+     *
+     * Bounds: depth is capped to 5 to keep dense graphs sane. Within each
+     * hop we cap at 50 edges to avoid pathological star-graph blowups
+     * (one super-node with thousands of mentions).
+     */
+    async traverseGraph(seedEntityId, opts = {}) {
+        const depth = Math.max(0, Math.min(opts.depth ?? 2, 5));
+        const seed = await this.getEntity(seedEntityId);
+        if (!seed)
+            return [];
+        const visited = new Map();
+        const queue = [
+            { entityId: seedEntityId, depth: 0, via: null, direction: null },
+        ];
+        while (queue.length > 0) {
+            const { entityId, depth: d, via, direction } = queue.shift();
+            if (visited.has(entityId))
+                continue;
+            const e = entityId === seedEntityId ? seed : await this.getEntity(entityId);
+            if (!e)
+                continue;
+            visited.set(entityId, { entity: e, via, direction, depth: d });
+            if (d >= depth)
+                continue;
+            // Expand outgoing.
+            const outgoing = await this.getRelations({
+                fromEntityId: entityId,
+                asOf: opts.asOf,
+                limit: 50,
+            });
+            for (const rel of outgoing) {
+                if (!visited.has(rel.to_entity_id)) {
+                    queue.push({ entityId: rel.to_entity_id, depth: d + 1, via: rel, direction: 'out' });
+                }
+            }
+            // Expand incoming.
+            const incoming = await this.getRelations({
+                toEntityId: entityId,
+                asOf: opts.asOf,
+                limit: 50,
+            });
+            for (const rel of incoming) {
+                if (!visited.has(rel.from_entity_id)) {
+                    queue.push({ entityId: rel.from_entity_id, depth: d + 1, via: rel, direction: 'in' });
+                }
+            }
+        }
+        // Stable order: depth ASC, then alpha for readable output.
+        return Array.from(visited.values()).sort((a, b) => {
+            if (a.depth !== b.depth)
+                return a.depth - b.depth;
+            return a.entity.display_name.localeCompare(b.entity.display_name);
+        });
+    }
+    // ─── P5 — Self-revising memory (5a detection) ───────────────────────────
+    async detectConsolidation(opts = {}) {
+        return detectDuplicates(this.db, this.vecAvailable, opts);
+    }
+    async proposalsList(opts = {}) {
+        return listProposals(this.db, opts);
+    }
+    async proposalReview(id, decision) {
+        return reviewProposal(this.db, id, decision);
+    }
+    // ─── Procedural memory ──────────────────────────────────────────────────
+    async saveProcedural(input) {
+        return saveProcedural(this.db, input);
+    }
+    async getProcedural(name, namespace) {
+        return getProceduralByName(this.db, name, namespace);
+    }
+    async listProcedural(opts = {}) {
+        return listProcedural(this.db, opts);
+    }
+    async recallProcedural(name, namespace) {
+        return recallProcedural(this.db, name, namespace);
+    }
+    async deleteProcedural(id) {
+        return deleteProcedural(this.db, id);
+    }
     async close() {
         this.db.close();
     }