sessionmem 1.4.0 → 1.5.0

package/dist/core/extract/factClaims.js

@@ -0,0 +1,97 @@
+import { canonicalEntityName, extractKnowledge } from "./knowledge.js";
+import { applyRedaction } from "../summarize/redaction.js";
+const CATEGORIES = [
+    ["editor", ["vs code", "vscode", "visual studio code", "neovim", "vim", "emacs", "sublime text", "intellij"]],
+    ["language", ["python", "rust", "typescript", "javascript", "java", "go", "ruby"]],
+    ["database", ["sqlite", "postgresql", "postgres", "mysql", "mongodb"]],
+    ["package manager", ["npm", "pnpm", "yarn", "bun"]],
+    ["test runner", ["vitest", "jest", "mocha", "pytest"]],
+];
+const aliases = { vscode: "vs code", "visual studio code": "vs code", postgres: "postgresql" };
+const value = (claim) => aliases[claim.target.name] ?? claim.target.name;
+export function claimKey(claim) {
+    return JSON.stringify([claim.source.kind, claim.source.name, claim.type,
+        claim.target.kind, claim.target.name, claim.context]);
+}
+export function claimSlot(claim) {
+    return JSON.stringify([claim.source, claim.type, claim.context, claim.attribute || claim.target]);
+}
+/** Small affirmative/negative grammar layered on migration 014's entity rules. */
+export function extractFactClaims(content) {
+    const text = applyRedaction(content, { redactionEnabled: true }).text.normalize("NFKC");
+    const claims = new Map();
+    let speaker = "";
+    for (let line of text.split(/\n|(?<=[.!?])\s+/)) {
+        line = line.replace(/^\s*(?:-\s*)?(?:\[[^\]]{1,60}\]\s*)?/, "").trim();
+        const prefix = /^([\p{Lu}][\p{L}'’-]*(?:\s+[\p{Lu}][\p{L}'’-]*){0,2}):\s*/u.exec(line);
+        if (prefix && !/^(actions|decisions|outcomes|facts|summary|user|assistant)$/i.test(prefix[1])) {
+            speaker = prefix[1];
+            line = line.slice(prefix[0].length);
+        }
+        // No questions, hypothetical statements, reported quotations or code.
+        if (/\?|^[`"“]|```/.test(line) || /\b(?:if|might|may|could|should|would|can|said|says|asked|used to)\b/i.test(line))
+            continue;
+        const negative = /\b(?:not|never|no longer|stopped)\b|n['’]t\b/i.test(line);
+        const explicitChange = /\b(?:now|switched|replaced|instead|no longer|stopped)\b/i.test(line);
+        const replaced = /\bswitched\s+from\s+(.+?)\s+to\b|\breplaced\s+(.+?)\s+with\b|\binstead\s+of\s+(.+?)[.!]?$/i.exec(line);
+        const replaces = canonicalEntityName(replaced?.slice(1).find(Boolean) ?? "").replace(/^(?:tool|service|project)\s+/, "");
+        let affirmative = line
+            .replace(/\b(?:do|does|did)\s+not\s+|\b(?:don['’]t|doesn['’]t|didn['’]t)\s+|\b(?:never|no longer)\s+/gi, "")
+            .replace(/\bstopped\s+using\b/gi, "uses")
+            .replace(/\bnot\s+(?=(?:uses?|using|prefers?|works?\s+on|working\s+on|blocked\s+by)\b)/gi, "")
+            .replace(/\bswitched\s+(?:from\s+.+?\s+)?to\s+/gi, "uses ")
+            .replace(/\breplaced\s+.+?\s+with\s+/gi, "uses ")
+            .replace(/\b(?:now|currently)\s+/gi, "")
+            .replace(/\s+(?:now|currently|again)[.!]?$/i, ".");
+        // Other negation forms are ambiguous; never turn them into positive claims.
+        if (/\bnot\b|n['’]t\b/i.test(affirmative))
+            continue;
+        const context = canonicalEntityName(/\b(?:for|as)\s+(.+?)(?:[.!;]|\s+because\b|$)/i.exec(affirmative)?.[1] ?? "")
+            .replace(/\b(?:my|our|the|a|an)\s+/g, "");
+        affirmative = affirmative.replace(/\s+as\s+.+$/i, "");
+        const graph = extractKnowledge(speaker ? `${speaker}: ${affirmative}` : affirmative);
+        for (const edge of graph.relations) {
+            const category = edge.type === "uses" || edge.type === "prefers"
+                ? CATEGORIES.find(([, names]) => names.includes(edge.target.name))?.[0] ?? "" : "";
+            const claim = { ...edge, context, attribute: category, negative, explicitChange, replaces };
+            // Last assertion about the same slot in a session wins, including retraction.
+            const slot = claimSlot(claim);
+            claims.delete(slot);
+            claims.set(slot, claim);
+        }
+    }
+    return [...claims.values()];
+}
+function contextOverlap(left, right) {
+    if (left === right)
+        return true;
+    if (!left || !right)
+        return false;
+    const words = (text) => new Set(text.match(/[\p{L}\p{N}]+/gu) ?? []);
+    const a = words(left), b = words(right);
+    const shared = [...a].filter(word => b.has(word)).length;
+    return shared >= 2 && shared / new Set([...a, ...b]).size >= 0.6;
+}
+export function supersessionReason(older, newer) {
+    if (older.source.kind !== newer.source.kind || older.source.name !== newer.source.name || older.type !== newer.type)
+        return;
+    if (value(older) === value(newer) && older.target.kind === newer.target.kind) {
+        if (older.negative !== newer.negative && (!older.context || !newer.context || contextOverlap(older.context, newer.context)))
+            return "explicit_negation";
+        return;
+    }
+    if (older.negative || newer.negative || older.target.kind !== newer.target.kind)
+        return;
+    if (value(older) === (aliases[newer.replaces] ?? newer.replaces))
+        return "different_value";
+    // Shared lexical purpose is a stronger attribute cue than a tool category.
+    if (older.context || newer.context) {
+        if (contextOverlap(older.context, newer.context))
+            return "different_value";
+        return;
+    }
+    if (older.attribute && older.attribute === newer.attribute)
+        return "different_value";
+    if (newer.explicitChange && older.type === "works_on")
+        return "different_value";
+}

package/dist/core/extract/knowledge.js

@@ -0,0 +1,127 @@
+import { applyRedaction } from "../summarize/redaction.js";
+// Deliberately small vocabulary. Unknown names require an explicit contextual
+// cue; capitalized sentence starters alone are not evidence of a person/tool.
+const TOOLS = ["SQLite", "PostgreSQL", "Postgres", "MySQL", "Redis", "Docker", "Git",
+    "Python", "TypeScript", "JavaScript", "Rust", "Node.js", "npm", "pnpm", "yarn",
+    "Vitest", "Jest", "React", "Vite", "Terraform", "Kubernetes", "VS Code", "Claude Code"];
+const SERVICES = ["GitHub", "GitLab", "Slack", "AWS", "S3", "Azure", "Google Cloud",
+    "OpenAI", "Anthropic", "Supabase", "Vercel", "Firebase"];
+const LABELS = new Set(["actions", "decisions", "outcomes", "facts", "decision", "summary",
+    "image caption", "ran", "edited", "created", "read", "updated", "tool", "user", "assistant"]);
+const FILE_PATTERN = /(?:\.{0,2}\/)?[\p{L}\p{N}_@-]+(?:\/[\p{L}\p{N}_.@-]+)*\.(?:[cm]?[jt]sx?|py|rs|go|java|jsonl?|ya?ml|toml|md|sql|sh|css|html|txt|env|lock)\b/giu;
+const key = (entity) => `${entity.kind}:${entity.name}`;
+export function canonicalEntityName(name) {
+    return name.normalize("NFKC").toLowerCase().replace(/[`"“”]/g, "")
+        .replace(/’/g, "'").replace(/'s\b/g, "").replace(/\s+/g, " ").trim()
+        .replace(/^[\s'.,:;!?]+|[\s'.,:;!?]+$/g, "");
+}
+/** Offline, order-stable rules. No inferred coreference beyond I/we and a speaker. */
+export function extractKnowledge(content) {
+    // Derived tables must never resurrect secrets, including during legacy backfill.
+    const text = applyRedaction(content, { redactionEnabled: true }).text.normalize("NFKC");
+    const entities = new Map();
+    const relations = new Map();
+    function add(kind, raw) {
+        const name = canonicalEntityName(raw);
+        if (!name || name.length > 160 || /redacted|[\n{}<>]/i.test(name))
+            return;
+        const entity = { kind, name };
+        entities.set(key(entity), entity);
+        return entity;
+    }
+    function classify(raw, fallback) {
+        const name = canonicalEntityName(raw);
+        const known = [...entities.values()].find(entity => entity.name === name);
+        if (known)
+            return known;
+        if (new RegExp(`^(?:${FILE_PATTERN.source})$`, "iu").test(name))
+            return add("file", name);
+        const label = /^(person|project|tool|service|file)\s+(.+)$/i.exec(name);
+        return label ? add(label[1], label[2]) : add(fallback, name);
+    }
+    for (const [kind, names] of [["tool", TOOLS], ["service", SERVICES]]) {
+        for (const name of names) {
+            const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            if (new RegExp(`(?<![\\p{L}\\p{N}_])${escaped}(?![\\p{L}\\p{N}_])`, "iu").test(text))
+                add(kind, name);
+        }
+    }
+    for (const match of text.matchAll(FILE_PATTERN))
+        add("file", match[0]);
+    // Explicit labels support names outside the vocabulary, including lowercase.
+    for (const match of text.matchAll(/\b(person|project|tool|service|file)\s+(`[^`\n]{1,120}`|"[^"\n]{1,120}"|[\p{L}\p{N}_.@/-]+)/giu)) {
+        add(match[1].toLowerCase(), match[2]);
+    }
+    let speaker;
+    for (const rawLine of text.split(/\n|(?<=[.!?])\s+/)) {
+        let line = rawLine.replace(/^\s*(?:-\s*)?(?:\[[^\]]{1,60}\]\s*)?/, "");
+        const command = /^Ran:\s*(.+)$/i.exec(line)?.[1];
+        if (command) {
+            const source = add("person", "user");
+            const executable = command.split(/\s+/)[0];
+            const tool = [...entities.values()].find(entity => entity.kind === "tool" && entity.name === canonicalEntityName(executable));
+            if (tool) {
+                const edge = { source, type: "uses", target: tool };
+                relations.set(`${key(source)}:uses:${key(tool)}`, edge);
+            }
+            // The existing local summarizer treats git commits as durable decisions.
+            if (/^git\s+commit\b/i.test(command)) {
+                const target = add("decision", command);
+                if (target)
+                    relations.set(`${key(source)}:decided:${key(target)}`, { source, type: "decided", target });
+            }
+            continue;
+        }
+        const prefix = /^([\p{Lu}][\p{L}'’-]*(?:\s+[\p{Lu}][\p{L}'’-]*){0,2}):\s*/u.exec(line);
+        if (prefix && !LABELS.has(prefix[1].toLowerCase())) {
+            speaker = add("person", prefix[1]);
+            line = line.slice(prefix[0].length);
+        }
+        else if (prefix) {
+            line = line.slice(prefix[0].length);
+        }
+        const relation = /\b(works?\s+on|working\s+on|decided(?:\s+to|\s+on)?|prefers?|uses?|using|(?:is\s+)?blocked\s+by)\s+(.+)$/i.exec(line);
+        if (!relation)
+            continue;
+        const verb = relation[1].toLowerCase();
+        const type = verb.startsWith("work") ? "works_on" : verb.startsWith("decided") ? "decided"
+            : verb.startsWith("prefer") ? "prefers" : verb.includes("blocked") ? "blocked_by" : "uses";
+        let subject = line.slice(0, relation.index).trim().replace(/\s+(?:is|was|am|are)$/i, "");
+        // Questions, negation and hypothetical statements are not affirmative edges.
+        if (/\?|\b(?:not|never|no longer|might|may|could|should|would|can|does|did)\b|n['’]t\b/i.test(line.slice(0, relation.index)))
+            continue;
+        if (/^(?:i|we|he|she|they|user|assistant)?$/i.test(subject)) {
+            // Third-person pronouns cannot be resolved safely without a parser.
+            if (/^(he|she|they)$/i.test(subject))
+                continue;
+            subject = speaker?.name ?? (/^we$/i.test(subject) ? "team" : "user");
+        }
+        // Avoid turning arbitrary preceding prose into a named subject.
+        if (subject.split(/\s+/).length > 4 || /[,;!?]/.test(subject) || line.endsWith("?"))
+            continue;
+        const source = classify(subject, "person");
+        let targetText = relation[2].replace(/[.!?]+$/, "").trim();
+        if (type !== "decided")
+            targetText = targetText.split(/\s+(?:for|with|because|but|and|instead|over|using|to)\s+/i)[0];
+        targetText = targetText.replace(/^(?:the|a|an)\s+/i, "");
+        const target = type === "decided" ? add("decision", targetText)
+            : classify(targetText, type === "works_on" ? "project" : "tool");
+        if (source && target && key(source) !== key(target)) {
+            const edge = { source, type, target };
+            relations.set(`${key(source)}:${type}:${key(target)}`, edge);
+        }
+    }
+    return { entities: [...entities.values()].sort((a, b) => key(a).localeCompare(key(b))),
+        relations: [...relations.values()].sort((a, b) => JSON.stringify(a).localeCompare(JSON.stringify(b))) };
+}
+/** Literal n-grams also match lowercase questions against known stored names. */
+export function queryEntityNames(query) {
+    const words = canonicalEntityName(query).match(/[\p{L}\p{N}_.@/'-]+/gu) ?? [];
+    const names = new Set();
+    for (let i = 0; i < Math.min(words.length, 64); i++) {
+        for (let length = 1; length <= 8 && i + length <= words.length; length++) {
+            names.add(canonicalEntityName(words.slice(i, i + length).join(" ")));
+        }
+    }
+    return [...names];
+}

package/dist/core/retrieve/retrieveMemories.js

@@ -1,8 +1,12 @@
+import { entityOverlap } from "../storage/knowledgeRepo.js";
 import { deterministicEmbed } from "../embed/deterministicEmbed.js";
 import { decayOldBoosts } from "./decay.js";
 import { scoreMemoryCandidate, } from "./score.js";
 import { searchMemoryCandidatesFTS, } from "../storage/memorySearchRepo.js";
 const DEFAULT_EMBEDDING_DIMENSION = 32;
+// Small, fixed contribution inside the existing relevance component. Keep the
+// public score shape/outer recency and importance weights unchanged.
+const ENTITY_RELEVANCE_WEIGHT = 0.10;
 function resolveEmbeddingDimension(candidates) {
     for (const candidate of candidates) {
         if (Number.isInteger(candidate.embedding_dim) && (candidate.embedding_dim ?? 0) > 0) {
@@ -41,12 +45,16 @@ export function retrieveMemories(input) {
     }
     const topK = input.topK ?? input.limit ?? 20;
     const now = input.now ?? new Date();
-    // Use FTS5 pre-filtering to limit cosine similarity computation to ~50 candidates.
-    // queryText is guaranteed non-empty by the Zod schema (z.string().min(1)) upstream.
-    const candidates = searchMemoryCandidatesFTS(input.db, input.projectId, queryText, now);
+    // FTS5 retrieves up to 50 BM25 matches; sparse matches retain the existing
+    // recency/importance fallback. The public request schema validates queryText.
+    const candidates = searchMemoryCandidatesFTS(input.db, input.projectId, queryText, now, input.includeHistory);
     const decayedCandidates = decayOldBoosts(candidates, now);
     const dimension = resolveEmbeddingDimension(candidates);
     const queryVector = deterministicEmbed(queryText, dimension).vector;
+    const overlap = entityOverlap(input.db, input.projectId, queryText, now);
+    // FTS5 returns negative BM25 ranks; storage converts them to positive scores.
+    // Normalize within this query so BM25 fits the existing relevance weight.
+    const maxLexicalScore = candidates.reduce((max, candidate) => Math.max(max, candidate.lexical_score), 0);
     const ranked = decayedCandidates
         .map((candidate) => {
         // When embedding is null (version mismatch or missing), use a neutral
@@ -58,8 +66,16 @@ export function retrieveMemories(input) {
             candidate.embedding.length !== queryVector.length
             ? 0.5
             : cosineSimilarity(queryVector, candidate.embedding);
+        // Hash cosine is useful for identical text, but adds noise to lexical
+        // matches. Keep it as a diagnostic and as the no-match fallback only.
+        const baseRelevance = maxLexicalScore > 0
+            ? candidate.lexical_score / maxLexicalScore
+            : semantic;
+        const relevance = overlap.size > 0
+            ? (1 - ENTITY_RELEVANCE_WEIGHT) * baseRelevance + ENTITY_RELEVANCE_WEIGHT * (overlap.get(candidate.id) ?? 0)
+            : baseRelevance;
         const score = scoreMemoryCandidate({
-            semantic,
+            semantic: relevance,
             updated_at: candidate.updated_at,
             importance: candidate.importance,
             access_count: candidate.access_count,

package/dist/core/schema/migrations/012_transcript_checkpoints.sql

@@ -0,0 +1,4 @@
+CREATE TABLE IF NOT EXISTS transcript_checkpoints (
+  path TEXT PRIMARY KEY,
+  fingerprint TEXT NOT NULL
+);

package/dist/core/schema/migrations/013_fts_porter.sql

@@ -0,0 +1,32 @@
+-- Rebuild the external-content index with SQLite's offline English stemmer.
+-- Existing memory bodies and IDs are unchanged; all rows are backfilled.
+DROP TRIGGER IF EXISTS memories_fts_insert;
+DROP TRIGGER IF EXISTS memories_fts_delete;
+DROP TRIGGER IF EXISTS memories_fts_update;
+DROP TABLE memories_fts;
+
+CREATE VIRTUAL TABLE memories_fts USING fts5(
+  content,
+  normalized_content,
+  content='memories',
+  content_rowid='rowid',
+  tokenize='porter unicode61'
+);
+INSERT INTO memories_fts(memories_fts) VALUES ('rebuild');
+
+CREATE TRIGGER memories_fts_insert AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, content, normalized_content)
+    VALUES (new.rowid, new.content, new.normalized_content);
+END;
+
+CREATE TRIGGER memories_fts_delete AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, content, normalized_content)
+    VALUES ('delete', old.rowid, old.content, old.normalized_content);
+END;
+
+CREATE TRIGGER memories_fts_update AFTER UPDATE OF content, normalized_content ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, content, normalized_content)
+    VALUES ('delete', old.rowid, old.content, old.normalized_content);
+  INSERT INTO memories_fts(rowid, content, normalized_content)
+    VALUES (new.rowid, new.content, new.normalized_content);
+END;

package/dist/core/schema/migrations/014_memory_entities.sql

@@ -0,0 +1,19 @@
+CREATE TABLE IF NOT EXISTS memory_entities (
+  memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE ON UPDATE CASCADE,
+  kind TEXT NOT NULL CHECK (kind IN ('person', 'project', 'tool', 'service', 'file', 'decision')),
+  name TEXT NOT NULL,
+  PRIMARY KEY (memory_id, kind, name)
+);
+CREATE INDEX IF NOT EXISTS idx_memory_entities_name ON memory_entities(name, memory_id);
+
+CREATE TABLE IF NOT EXISTS memory_relations (
+  memory_id TEXT NOT NULL,
+  source_kind TEXT NOT NULL,
+  source_name TEXT NOT NULL,
+  relation TEXT NOT NULL CHECK (relation IN ('works_on', 'decided', 'prefers', 'uses', 'blocked_by')),
+  target_kind TEXT NOT NULL,
+  target_name TEXT NOT NULL,
+  PRIMARY KEY (memory_id, source_kind, source_name, relation, target_kind, target_name),
+  FOREIGN KEY (memory_id, source_kind, source_name) REFERENCES memory_entities(memory_id, kind, name) ON DELETE CASCADE ON UPDATE CASCADE,
+  FOREIGN KEY (memory_id, target_kind, target_name) REFERENCES memory_entities(memory_id, kind, name) ON DELETE CASCADE ON UPDATE CASCADE
+);

package/dist/core/schema/migrations/015_memory_supersessions.sql

@@ -0,0 +1,41 @@
+-- Derived claims retain polarity and attribute context absent from migration 014.
+CREATE TABLE memory_claims (
+  memory_id TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE ON UPDATE CASCADE,
+  claim_key TEXT NOT NULL,
+  source_kind TEXT NOT NULL,
+  source_name TEXT NOT NULL,
+  relation TEXT NOT NULL,
+  target_kind TEXT NOT NULL,
+  target_name TEXT NOT NULL,
+  context TEXT NOT NULL,
+  attribute TEXT NOT NULL,
+  negative INTEGER NOT NULL CHECK (negative IN (0, 1)),
+  explicit_change INTEGER NOT NULL CHECK (explicit_change IN (0, 1)),
+  replaces_value TEXT NOT NULL,
+  observed_at TEXT NOT NULL,
+  PRIMARY KEY (memory_id, claim_key)
+);
+CREATE INDEX idx_memory_claims_subject ON memory_claims(source_kind, source_name, relation, memory_id);
+
+-- supersedes is the old memory; superseded_by is its replacement. One link per
+-- invalidated claim permits summaries to keep their independent, current facts.
+CREATE TABLE memory_supersessions (
+  supersedes TEXT NOT NULL,
+  claim_key TEXT NOT NULL,
+  superseded_by TEXT NOT NULL REFERENCES memories(id) ON DELETE CASCADE ON UPDATE CASCADE,
+  new_claim_key TEXT NOT NULL,
+  superseded_at TEXT NOT NULL,
+  detected_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  reason TEXT NOT NULL CHECK (reason IN ('different_value', 'explicit_negation')),
+  PRIMARY KEY (supersedes, claim_key),
+  FOREIGN KEY (supersedes, claim_key) REFERENCES memory_claims(memory_id, claim_key) ON DELETE CASCADE ON UPDATE CASCADE,
+  FOREIGN KEY (superseded_by, new_claim_key) REFERENCES memory_claims(memory_id, claim_key) ON DELETE CASCADE ON UPDATE CASCADE,
+  CHECK (supersedes <> superseded_by)
+);
+CREATE INDEX idx_memory_supersessions_replacement ON memory_supersessions(superseded_by);
+
+-- A memory is fully superseded only when all of its extracted claims changed.
+CREATE VIEW superseded_memories AS
+SELECT c.memory_id FROM memory_claims c
+LEFT JOIN memory_supersessions s ON s.supersedes = c.memory_id AND s.claim_key = c.claim_key
+GROUP BY c.memory_id HAVING COUNT(*) = COUNT(s.claim_key);

package/dist/core/schema/runMigrations.js

@@ -1,6 +1,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { indexMemoryKnowledge } from "../storage/knowledgeRepo.js";
+import { indexMemorySupersessions } from "../storage/supersessionRepo.js";
+import { listSessionEventsBySession } from "../storage/sessionEventsRepo.js";
+import { extractEventText } from "../summarize/summaryShape.js";
 const DEFAULT_MIGRATIONS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "migrations");
 function ensureMigrationsTable(db) {
     db.exec(`
@@ -19,6 +23,20 @@ function listMigrationFiles(migrationsDir) {
         .filter((fileName) => fileName.endsWith(".sql"))
         .sort((left, right) => left.localeCompare(right));
 }
+/** Inspect migration history without creating tables or applying migrations. */
+export function inspectMigrations(db, migrationsDir = DEFAULT_MIGRATIONS_DIR) {
+    const expected = listMigrationFiles(migrationsDir);
+    if (expected.length === 0)
+        throw new Error(`No schema migrations found in ${migrationsDir}`);
+    const hasHistory = db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = '_migrations'").get();
+    const applied = hasHistory
+        ? db.prepare("SELECT name FROM _migrations").all().map((row) => row.name)
+        : [];
+    return {
+        pending: expected.filter((name) => !applied.includes(name)),
+        unknown: applied.filter((name) => !expected.includes(name)),
+    };
+}
 /**
  * Verify that every column an ADD COLUMN migration declares already exists in
  * its target table. Parses `ALTER TABLE <table> ADD COLUMN <name>` statements
@@ -62,6 +80,34 @@ export function runMigrations(db, migrationsDir = DEFAULT_MIGRATIONS_DIR) {
         const filePath = path.join(migrationsDir, fileName);
         const sql = fs.readFileSync(filePath, "utf8");
         db.exec(sql);
+        if (fileName === "014_memory_entities.sql") {
+            // Backfill in the migration transaction: failures roll back both schema
+            // and derived data, and reopening never indexes legacy rows twice.
+            // Finish each read before nested write transactions; an active SQLite
+            // iterator prevents SAVEPOINT. Batches bound memory use on large stores.
+            const batch = db.prepare("SELECT id, content, kind, project_id, session_id FROM memories ORDER BY id LIMIT 256 OFFSET ?");
+            for (let offset = 0;; offset += 256) {
+                const rows = batch.all(offset);
+                for (const row of rows) {
+                    const events = row.kind === "summary" ? listSessionEventsBySession(db, row.project_id, row.session_id) : [];
+                    indexMemoryKnowledge(db, row.id, events.length ? events.map(extractEventText).join("\n") : row.content);
+                }
+                if (rows.length < 256)
+                    break;
+            }
+        }
+        if (fileName === "015_memory_supersessions.sql") {
+            const batch = db.prepare("SELECT id, content, kind, project_id, session_id FROM memories ORDER BY created_at, rowid LIMIT 256 OFFSET ?");
+            for (let offset = 0;; offset += 256) {
+                const rows = batch.all(offset);
+                for (const row of rows) {
+                    const events = row.kind === "summary" ? listSessionEventsBySession(db, row.project_id, row.session_id) : [];
+                    indexMemorySupersessions(db, row.id, row.content, events.length ? events.map(event => ({ text: extractEventText(event), observedAt: event.created_at })) : undefined);
+                }
+                if (rows.length < 256)
+                    break;
+            }
+        }
         insertMigrationStmt.run(fileName);
     });
     for (const fileName of files) {

package/dist/core/storage/knowledgeRepo.js

@@ -0,0 +1,67 @@
+import { extractKnowledge, queryEntityNames } from "../extract/knowledge.js";
+const cache = new WeakMap();
+function statements(db) {
+    let result = cache.get(db);
+    if (result)
+        return result;
+    result = {
+        clear: db.prepare("DELETE FROM memory_entities WHERE memory_id = ?"),
+        entity: db.prepare("INSERT INTO memory_entities (memory_id, kind, name) VALUES (?, ?, ?)"),
+        relation: db.prepare(`INSERT INTO memory_relations
+      (memory_id, source_kind, source_name, relation, target_kind, target_name) VALUES (?, ?, ?, ?, ?, ?)`),
+        overlap: db.prepare(`SELECT DISTINCT e.memory_id, e.name FROM memory_entities e
+      JOIN memories m ON m.id = e.memory_id
+      WHERE m.project_id = ? AND (m.expires_at IS NULL OR m.expires_at > ?)
+        AND e.name IN (SELECT value FROM json_each(?))`),
+    };
+    cache.set(db, result);
+    return result;
+}
+/** Replace, never append: replays, redaction, import and summary upserts stay safe. */
+export function replaceMemoryKnowledge(db, memoryId, knowledge) {
+    const stmts = statements(db);
+    db.transaction(() => {
+        stmts.clear.run(memoryId);
+        for (const entity of knowledge.entities)
+            stmts.entity.run(memoryId, entity.kind, entity.name);
+        for (const edge of knowledge.relations)
+            stmts.relation.run(memoryId, edge.source.kind, edge.source.name, edge.type, edge.target.kind, edge.target.name);
+    })();
+}
+export function indexMemoryKnowledge(db, memoryId, content) {
+    replaceMemoryKnowledge(db, memoryId, extractKnowledge(content));
+}
+export function entityOverlap(db, projectId, query, now) {
+    const rows = statements(db).overlap.all(projectId, now.toISOString(), JSON.stringify(queryEntityNames(query)));
+    const queryNames = new Set(rows.map(row => row.name));
+    const counts = new Map();
+    for (const row of rows)
+        counts.set(row.memory_id, (counts.get(row.memory_id) ?? 0) + 1);
+    return new Map([...counts].map(([id, count]) => [id, count / queryNames.size]));
+}
+export function listProjectKnowledge(db, projectId, now = new Date()) {
+    const entities = db.prepare(`SELECT e.kind, e.name, e.memory_id FROM memory_entities e
+    JOIN memories m ON m.id = e.memory_id WHERE m.project_id = ?
+    AND (m.expires_at IS NULL OR m.expires_at > ?) ORDER BY e.kind, e.name, e.memory_id`)
+        .all(projectId, now.toISOString());
+    const relations = db.prepare(`SELECT r.* FROM memory_relations r JOIN memories m ON m.id = r.memory_id
+    WHERE m.project_id = ? AND (m.expires_at IS NULL OR m.expires_at > ?)
+    ORDER BY source_kind, source_name, relation, target_kind, target_name, r.memory_id`)
+        .all(projectId, now.toISOString());
+    const nodes = new Map();
+    const edges = new Map();
+    for (const row of entities) {
+        const key = JSON.stringify([row.kind, row.name]);
+        const node = nodes.get(key) ?? { kind: row.kind, name: row.name, memoryIds: [] };
+        node.memoryIds.push(row.memory_id);
+        nodes.set(key, node);
+    }
+    for (const row of relations) {
+        const key = JSON.stringify([row.source_kind, row.source_name, row.relation, row.target_kind, row.target_name]);
+        const edge = edges.get(key) ?? { sourceKind: row.source_kind, sourceName: row.source_name,
+            relation: row.relation, targetKind: row.target_kind, targetName: row.target_name, memoryIds: [] };
+        edge.memoryIds.push(row.memory_id);
+        edges.set(key, edge);
+    }
+    return { entities: [...nodes.values()], relations: [...edges.values()] };
+}

package/dist/core/storage/memoryRepo.js

@@ -1,3 +1,5 @@
+import { indexMemoryKnowledge, replaceMemoryKnowledge } from "./knowledgeRepo.js";
+import { indexMemorySupersessions, reconcileProjectSupersessions } from "./supersessionRepo.js";
 // Shared INSERT ... ON CONFLICT(id) upsert column lists. The import and team-pull
 // paths differ only in how they resolve `importance` on conflict (import takes the
 // incoming value; pull preserves MAX(local, incoming)), so the surrounding SQL is
@@ -217,11 +219,22 @@ function toParams(input) {
 }
 export function insertMemory(db, input) {
     assertImportance(input.importance);
-    getStatements(db).insertMemory.run(toParams(input));
+    db.transaction(() => {
+        getStatements(db).insertMemory.run(toParams(input));
+        indexMemoryKnowledge(db, input.id, input.content);
+        indexMemorySupersessions(db, input.id, input.content);
+    })();
 }
-export function upsertSessionSummaryMemory(db, input) {
+export function upsertSessionSummaryMemory(db, input, knowledge, factSource) {
     assertImportance(input.importance);
-    getStatements(db).upsertSessionSummary.run(toParams({ ...input, kind: "summary" }));
+    db.transaction(() => {
+        getStatements(db).upsertSessionSummary.run(toParams({ ...input, kind: "summary" }));
+        if (knowledge)
+            replaceMemoryKnowledge(db, input.id, knowledge);
+        else
+            indexMemoryKnowledge(db, input.id, input.content);
+        indexMemorySupersessions(db, input.id, input.content, factSource);
+    })();
 }
 /**
  * Upsert a memory imported from an external export. On `id` conflict the incoming
@@ -231,7 +244,11 @@ export function upsertSessionSummaryMemory(db, input) {
  */
 export function upsertImportedMemory(db, input) {
     assertImportance(input.importance);
-    getStatements(db).importUpsert.run(toParams(input));
+    db.transaction(() => {
+        getStatements(db).importUpsert.run(toParams(input));
+        indexMemoryKnowledge(db, input.id, input.content);
+        indexMemorySupersessions(db, input.id, input.content);
+    })();
 }
 /**
  * Upsert a memory pulled from a teammate. Identical to {@link upsertImportedMemory}
@@ -240,7 +257,11 @@ export function upsertImportedMemory(db, input) {
  */
 export function upsertPulledMemory(db, input) {
     assertImportance(input.importance);
-    getStatements(db).pullUpsert.run(toParams(input));
+    db.transaction(() => {
+        getStatements(db).pullUpsert.run(toParams(input));
+        indexMemoryKnowledge(db, input.id, input.content);
+        indexMemorySupersessions(db, input.id, input.content);
+    })();
 }
 export function listMemoriesByProject(db, projectId) {
     return getStatements(db).listByProject.all(projectId);
@@ -277,7 +298,12 @@ export function getMemoryOwnerProjectId(db, memoryId) {
  * removed (0 when the id does not exist in this project).
  */
 export function deleteMemoryById(db, projectId, memoryId) {
-    return getStatements(db).deleteById.run(projectId, memoryId).changes;
+    return db.transaction(() => {
+        const deleted = getStatements(db).deleteById.run(projectId, memoryId).changes;
+        if (deleted)
+            reconcileProjectSupersessions(db, projectId);
+        return deleted;
+    })();
 }
 /**
  * All memory ids across every project. `id` is a globally-unique
@@ -299,8 +325,12 @@ export function deleteMemoriesOlderThan(db, projectId, cutoffIso) {
     // Hard-delete scoped to the memories table only; never touches
     // session_events or memory_feedback. project_id and cutoff are bound, never
     // string-concatenated, to prevent SQL injection.
-    const result = getStatements(db).deleteOlderThan.run(projectId, cutoffIso);
-    return result.changes;
+    return db.transaction(() => {
+        const result = getStatements(db).deleteOlderThan.run(projectId, cutoffIso);
+        if (result.changes)
+            reconcileProjectSupersessions(db, projectId);
+        return result.changes;
+    })();
 }
 // NOTE: no MCP tool, CLI command, or service method currently calls this. It is
 // retained as intentional repository API surface (the importance-update
@@ -345,10 +375,13 @@ export function updateMemoryContent(db, projectId, memoryId, newContent, newNorm
 // recomputed embedding so the vector tracks the redacted text; omit to leave
 // the existing embedding untouched (COALESCE keeps the prior value on null).
 newEmbedding) {
-    const result = getStatements(db).updateContent.run(newContent, newNormalizedContent ?? null, newEmbedding ? JSON.stringify(newEmbedding.vector) : null, newEmbedding?.dimension ?? null, newEmbedding?.embeddingVersion ?? null, projectId, memoryId);
-    if (result.changes === 0) {
-        throw new Error(`Memory not found: ${memoryId}`);
-    }
+    db.transaction(() => {
+        const result = getStatements(db).updateContent.run(newContent, newNormalizedContent ?? null, newEmbedding ? JSON.stringify(newEmbedding.vector) : null, newEmbedding?.dimension ?? null, newEmbedding?.embeddingVersion ?? null, projectId, memoryId);
+        if (result.changes === 0)
+            throw new Error(`Memory not found: ${memoryId}`);
+        indexMemoryKnowledge(db, memoryId, newContent);
+        indexMemorySupersessions(db, memoryId, newContent);
+    })();
 }
 export function incrementAccessCounts(db, projectId, memoryIds, accessedAt) {
     if (memoryIds.length === 0)