mnueron 0.2.0 → 0.4.0

package/dist/store/local.js

@@ -5,7 +5,88 @@ 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
+ * search() and list(). Returns clauses joined by AND (always at least
+ * `1=1` so callers can append `${...}` after `WHERE`).
+ *
+ * The `m.` prefix is hard-coded — callers must alias their memories table
+ * as `m` for these clauses to bind. (The whole local store uses one table
+ * named `memories`, but the search path joins, so consistent aliasing is
+ * what keeps this reusable.)
+ */
+function buildFilterFragment(f, alias = 'm') {
+    const parts = ['1=1'];
+    const params = [];
+    const a = alias ? `${alias}.` : '';
+    if (f.namespace) {
+        parts.push(`${a}namespace = ?`);
+        params.push(f.namespace);
+    }
+    if (f.created_after != null) {
+        parts.push(`${a}created_at >= ?`);
+        params.push(f.created_after);
+    }
+    if (f.created_before != null) {
+        parts.push(`${a}created_at <= ?`);
+        params.push(f.created_before);
+    }
+    if (f.updated_after != null) {
+        parts.push(`${a}updated_at >= ?`);
+        params.push(f.updated_after);
+    }
+    if (f.updated_before != null) {
+        parts.push(`${a}updated_at <= ?`);
+        params.push(f.updated_before);
+    }
+    // metadata_filter: SQLite has no native @> operator, but we can match
+    // every top-level k=v pair via json_extract. We only support strings,
+    // numbers, and booleans on the RHS — nested objects are not supported
+    // in this minimal port. Matches what most callers actually use.
+    if (f.metadata_filter && typeof f.metadata_filter === 'object') {
+        for (const [k, v] of Object.entries(f.metadata_filter)) {
+            if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+                parts.push(`json_extract(${a}metadata, '$.' || ?) = ?`);
+                params.push(k, v);
+            }
+        }
+    }
+    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.
@@ -43,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 '';
@@ -158,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) {
@@ -165,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)) {
@@ -199,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,
         });
     }
@@ -368,21 +647,19 @@ export class LocalProvider {
     // ─── read path: hybrid keyword + vector with RRF ─────────────────────────
     async search(input) {
         const k = input.k ?? 10;
-        // FTS5 leg
+        // FTS5 leg — now honors all MemoryFilters (date range + metadata filter).
         const safeQuery = buildFtsQuery(input.query);
         const ftsRanks = new Map(); // id → 1-based rank
         if (safeQuery) {
+            const filter = buildFilterFragment(input, 'm');
             let sql = `
         SELECT m.id
         FROM memories_fts f
         JOIN memories m ON m.id = f.content_id
         WHERE memories_fts MATCH ?
+          AND ${filter.sql}
       `;
-            const params = [safeQuery];
-            if (input.namespace) {
-                sql += ` AND m.namespace = ?`;
-                params.push(input.namespace);
-            }
+            const params = [safeQuery, ...filter.params];
             sql += ` ORDER BY bm25(memories_fts) LIMIT 50`;
             const rows = this.db.prepare(sql).all(...params);
             rows.forEach((r, i) => ftsRanks.set(r.id, i + 1));
@@ -452,18 +729,23 @@ export class LocalProvider {
         return memories;
     }
     async list(input) {
-        let sql = `SELECT * FROM memories WHERE 1=1`;
-        const params = [];
-        if (input.namespace) {
-            sql += ` AND namespace = ?`;
-            params.push(input.namespace);
-        }
+        // v0.2.1 + v0.2.4: full filter support via shared helper.
+        // Note: 'm' alias is omitted here because list() doesn't join other
+        // tables, so we pass alias = '' to skip the prefix.
+        const filter = buildFilterFragment(input, '');
+        let sql = `SELECT * FROM memories WHERE ${filter.sql}`;
+        const params = [...filter.params];
+        // Keep legacy `before` cursor working for older SDK callers.
         if (input.before) {
             sql += ` AND created_at < ?`;
             params.push(input.before);
         }
         sql += ` ORDER BY created_at DESC LIMIT ?`;
         params.push(input.limit ?? 50);
+        if (input.offset && input.offset > 0) {
+            sql += ` OFFSET ?`;
+            params.push(input.offset);
+        }
         const rows = this.db.prepare(sql).all(...params);
         let memories = rows.map(r => this.rowToMemory(r));
         if (input.tags && input.tags.length > 0) {
@@ -472,6 +754,100 @@ export class LocalProvider {
         }
         return memories;
     }
+    /**
+     * v0.2.3 — bulk search: same scope, multiple queries, one call.
+     * SQLite is single-threaded; the only saving here is the function-call
+     * overhead. The hosted version's savings are larger (one HTTP RTT). For
+     * API parity, exposed under the same Provider method either way.
+     */
+    async bulkSearch(input) {
+        const k = input.k ?? 5;
+        const out = [];
+        for (const q of input.queries) {
+            const hits = await this.search({
+                query: q, k,
+                namespace: input.namespace,
+                tags: input.tags,
+                created_after: input.created_after,
+                created_before: input.created_before,
+                updated_after: input.updated_after,
+                updated_before: input.updated_before,
+                metadata_filter: input.metadata_filter,
+            });
+            out.push({ query: q, hits });
+        }
+        return out;
+    }
+    /**
+     * v0.2.2 — partial update. Re-runs redaction + chunking-aware embed for
+     * the content path. Logs change to metadata.history so the same audit
+     * trail works against local and hosted.
+     *
+     * Returns the updated Memory or null if id wasn't found.
+     */
+    async update(id, patch) {
+        const existing = this.db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id);
+        if (!existing)
+            return null;
+        // 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)) {
+                if (v === null)
+                    delete merged[k];
+                else
+                    merged[k] = v;
+            }
+        }
+        const nextContent = patch.content != null ? redact(patch.content).content : existing.content;
+        const contentChanged = nextContent !== existing.content;
+        if (contentChanged) {
+            const history = Array.isArray(merged.history)
+                ? merged.history.slice(0)
+                : [];
+            history.push({
+                at: Date.now(),
+                prev_content_len: typeof existing.content === 'string' ? existing.content.length : 0,
+            });
+            merged.history = history;
+        }
+        const nextNs = patch.namespace ?? existing.namespace;
+        const nextTags = patch.tags
+            ?? JSON.parse((existing.tags_json ?? existing.tags) ?? '[]');
+        const now = Date.now();
+        this.db.prepare(`UPDATE memories
+          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.
+        if (contentChanged) {
+            this.db.prepare(`DELETE FROM memories_fts WHERE content_id = ?`).run(id);
+            this.db.prepare(`INSERT INTO memories_fts (content_id, content) VALUES (?, ?)`).run(id, nextContent);
+            if (this.vecAvailable) {
+                try {
+                    const v = await embed(nextContent);
+                    if (v) {
+                        this.db.prepare(`DELETE FROM memories_vec WHERE memory_id = ?`).run(id);
+                        this.db.prepare(`INSERT INTO memories_vec (memory_id, embedding) VALUES (?, ?)`).run(id, Buffer.from(v.buffer));
+                    }
+                }
+                catch (e) {
+                    process.stderr.write(`[mnueron] re-embed on update failed: ${e.message}\n`);
+                }
+            }
+        }
+        const fresh = this.db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id);
+        return fresh ? this.rowToMemory(fresh) : null;
+    }
     async get(id) {
         const row = this.db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id);
         return row ? this.rowToMemory(row) : null;
@@ -502,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();
     }