local-agentic-ai-mem 0.1.0

package/dist/lib/recall.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recall = recall;
+/**
+ * Hybrid recall over the local store.
+ *
+ * Same shape as the hosted version — several arms fused with reciprocal rank
+ * fusion, then ranked and deduplicated — but the vector arms are a plain
+ * scan rather than an HNSW index. Measured: 1.7ms over 2,000 vectors. An
+ * index would be machinery in service of nothing at this scale.
+ *
+ * Arms, and why each exists:
+ *   content vector   what was learned
+ *   prompt vector    how it was asked — at recall time the query is itself a
+ *                    user prompt, and dropping this arm cost 2.7 points of
+ *                    precision@5 when it was measured
+ *   lexical (FTS5)   exact identifiers, SHAs, error strings, where embeddings
+ *                    are weakest
+ */
+const db_1 = require("../db");
+const RRF_K = 60;
+const ARM_DEPTH = 60;
+const RECENCY_HALF_LIFE_DAYS = 90;
+const RECENCY_FLOOR = 0.45;
+const SAME_PROJECT_BOOST = 1.3;
+const PROVEN_WEIGHT = 0.12;
+const PROVEN_CAP = 1.5;
+const MMR_DUP_THRESHOLD = 0.6;
+/** Work that reached a remote passed whatever gates exist. Grades, never gates. */
+const CONFIDENCE_WEIGHT = { pushed: 1.25, committed: 1.1, stated: 1.0 };
+function tokenSet(s) {
+    return new Set((s || "").toLowerCase().replace(/[^a-z0-9/._-]+/g, " ").split(/\s+/).filter((t) => t.length > 2));
+}
+function jaccard(a, b) {
+    if (!a.size || !b.size)
+        return 0;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    return inter / (a.size + b.size - inter);
+}
+/**
+ * Staleness is measured from when a memory was last confirmed useful, not when
+ * it was written. A note from five months ago that was pulled up yesterday is
+ * not stale.
+ */
+function recencyFactor(row) {
+    const created = row.started_at;
+    const recalled = row.last_recalled;
+    const iso = recalled && new Date(recalled) > new Date(created) ? recalled : created;
+    const ageDays = (Date.now() - new Date(iso).getTime()) / 86_400_000;
+    if (!Number.isFinite(ageDays) || ageDays < 0)
+        return 1;
+    return RECENCY_FLOOR + (1 - RECENCY_FLOOR) * Math.pow(0.5, ageDays / RECENCY_HALF_LIFE_DAYS);
+}
+function bodyOf(row) {
+    if (row.content && row.content.trim())
+        return row.content.trim();
+    const decisions = safeArray(row.decisions);
+    const meaningful = decisions.filter((d) => !/^(task|at commit|areas):/i.test(d));
+    if (meaningful.length)
+        return meaningful.slice(0, 4).join(" · ");
+    return (row.prompt || "").trim();
+}
+function safeArray(json) {
+    try {
+        const v = JSON.parse(json);
+        return Array.isArray(v) ? v.map(String) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function rankArm(rows, key, q) {
+    const scored = [];
+    for (const r of rows) {
+        const v = (0, db_1.decodeVec)(r[key] ?? null);
+        if (!v)
+            continue;
+        scored.push({ id: r.id, sim: (0, db_1.cosine)(q, v) });
+    }
+    scored.sort((a, b) => b.sim - a.sim);
+    return scored.slice(0, ARM_DEPTH).map((s) => s.id);
+}
+function recall(opts) {
+    const limit = opts.limit ?? 5;
+    const q = opts.queryVec instanceof Float32Array ? opts.queryVec : Float32Array.from(opts.queryVec);
+    // One scan serves every arm — the whole live set for this user is small.
+    const rows = (0, db_1.liveMemories)({ tier: opts.tier ?? 2 });
+    if (rows.length === 0)
+        return [];
+    const byId = new Map(rows.map((r) => [r.id, r]));
+    const arms = [
+        rankArm(rows, "vec", q),
+        rankArm(rows, "prompt_vec", q),
+        (0, db_1.lexicalSearch)(opts.queryText, ARM_DEPTH).filter((id) => byId.has(id)),
+    ];
+    if (opts.projectId !== undefined) {
+        const scoped = rows.filter((r) => r.project_id === opts.projectId);
+        if (scoped.length)
+            arms.push(rankArm(scoped, "vec", q));
+    }
+    const fused = new Map();
+    for (const arm of arms) {
+        arm.forEach((id, rank) => {
+            fused.set(id, (fused.get(id) ?? 0) + 1 / (RRF_K + rank + 1));
+        });
+    }
+    const scored = [];
+    for (const [id, rrf] of fused) {
+        const row = byId.get(id);
+        const text = bodyOf(row);
+        if (!text)
+            continue;
+        const proven = Math.min(PROVEN_CAP, 1 + PROVEN_WEIGHT * Math.log1p(row.recall_count || 0));
+        const sameProject = opts.projectId !== undefined && row.project_id === opts.projectId;
+        scored.push({
+            id,
+            text,
+            decisions: safeArray(row.decisions).filter((d) => !/^(task|at commit|areas):/i.test(d)),
+            files: safeArray(row.files),
+            project: row.project_slug ?? "",
+            projectId: row.project_id,
+            date: row.started_at,
+            gitCommit: row.git_commit,
+            anchorSha: row.anchor_sha,
+            confidence: row.confidence,
+            score: rrf *
+                recencyFactor(row) *
+                (sameProject ? SAME_PROJECT_BOOST : 1) *
+                proven *
+                (CONFIDENCE_WEIGHT[row.confidence] ?? 1),
+        });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    // Greedy MMR. Without it a query near a recurring phrase returns five copies
+    // of the same non-memory.
+    const picked = [];
+    const seen = [];
+    for (const cand of scored) {
+        if (picked.length >= limit)
+            break;
+        const t = tokenSet(cand.text);
+        if (seen.some((s) => jaccard(t, s) > MMR_DUP_THRESHOLD))
+            continue;
+        picked.push(cand);
+        seen.push(t);
+    }
+    (0, db_1.markRecalled)(picked.map((p) => p.id));
+    return picked;
+}

package/dist/lib/redact.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Server-side secret redaction.
+ *
+ * The CLI has an equivalent in templates/lib/pii.mjs, but it was only applied
+ * to the text being embedded — the raw prompt was posted and stored verbatim.
+ * That is backwards: secrets were scrubbed from the 384 floats nobody can read
+ * and preserved in the column anybody with database access can. Auditing the
+ * live corpus turned up internal hostnames, absolute server paths and shell
+ * lines like `user@host:~$ sudo /opt/platform/repo/tools/ops/refresh.sh`.
+ *
+ * The client now redacts before sending; this runs again on the server so an
+ * old or modified client cannot write an unredacted secret into the database.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redact = redact;
+exports.redactAll = redactAll;
+const PATTERNS = [
+    // Prefixed opaque tokens (sk-, ghp_, xoxb-, api_key-...)
+    [/\b(sk|pk|rk|api|token|key|bearer|ghp|gho|ghu|ghs|ghr|xox[abprs])[-_][A-Za-z0-9_-]{16,}\b/gi, "[REDACTED_TOKEN]"],
+    [/\bnpm_[A-Za-z0-9]{20,}\b/g, "[REDACTED_NPM_TOKEN]"],
+    [/\bmemos_[a-f0-9-]{20,}\b/gi, "[REDACTED_MEMOS_KEY]"],
+    [/\bAKIA[0-9A-Z]{16}\b/g, "[REDACTED_AWS_KEY]"],
+    [/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, "[REDACTED_JWT]"],
+    [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "[REDACTED_PRIVATE_KEY]"],
+    // Connection strings — the class of secret this codebase actually leaked.
+    [/\b([a-z][a-z0-9+.-]*):\/\/([^\s:/@]+):([^\s@]+)@/gi, "$1://$2:[REDACTED_PASSWORD]@"],
+    // Assignment shapes: DB_PASSWORD=hunter2, "secret": "abc123", api_key: xyz.
+    // Unambiguous because of the separator, so the value is taken as-is. The
+    // leading \w* matters: \b does not match between "DB_" and "PASSWORD",
+    // which is the most common env-var shape there is.
+    [
+        /\b(\w*(?:password|passwd|pwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token|client[_-]?secret))(\s*["']?\s*[:=]\s*["']?)([^\s"',;]{6,})/gi,
+        (_m, k, sep) => `${k}${sep}[REDACTED_SECRET]`,
+    ],
+    // Prose shape: "password s3cretLeak". Riskier, so the value must look like a
+    // secret rather than an English word — it needs both a digit and a letter,
+    // which "password validation logic" does not have.
+    [
+        /\b(password|passphrase|secret|token)\s+(?=\S*[0-9])(?=\S*[A-Za-z])([^\s"',;]{8,})/gi,
+        (_m, k) => `${k} [REDACTED_SECRET]`,
+    ],
+    [/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, "[REDACTED_EMAIL]"],
+    // Public IPv4 only — private ranges are dev infra and useful context.
+    [/\b(?!10\.|192\.168\.|127\.|0\.|172\.(?:1[6-9]|2\d|3[01])\.)(?:\d{1,3}\.){3}\d{1,3}\b/g, "[REDACTED_IP]"],
+    [/\b(?:\d[ -]?){13,19}\b/g, (m) => (/\d{13,19}/.test(m.replace(/[ -]/g, "")) ? "[REDACTED_CC]" : m)],
+    [/\b[a-f0-9]{32,}\b/gi, "[REDACTED_HEX]"],
+];
+function redact(text) {
+    if (!text || typeof text !== "string")
+        return text;
+    let out = text;
+    for (const [re, sub] of PATTERNS) {
+        out = typeof sub === "function"
+            ? out.replace(re, sub)
+            : out.replace(re, sub);
+    }
+    return out;
+}
+function redactAll(values) {
+    if (!Array.isArray(values))
+        return [];
+    return values.map((v) => redact(String(v)));
+}

package/dist/lib/tiers.js

@@ -0,0 +1,405 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_FACTS_PER_PROJECT = void 0;
+exports.assignTier = assignTier;
+exports.gradeConfidence = gradeConfidence;
+exports.confidenceFactor = confidenceFactor;
+exports.deriveProjectFacts = deriveProjectFacts;
+exports.findSupersessions = findSupersessions;
+/**
+ * Memory tiering — what gets promoted, what expires, what is always present.
+ *
+ * The corpus problem was never ranking. It was that everything got in and
+ * nothing ever left, so 11,345 equals competed for five slots. These three
+ * tiers separate them by how they should be used:
+ *
+ *   1  repo knowledge  — few, injected whole, never searched
+ *   2  decisions       — retrieved, anchored, supersedable
+ *   3  episodes        — raw turns, decay and archive
+ *
+ * This module is deliberately free of database imports: it is pure logic over
+ * atoms, so the evaluation harness can measure exactly what the server runs
+ * without needing a connection. The DB wrappers live in services/tiering.ts.
+ */
+const compose_1 = require("./compose");
+// ── tunables ─────────────────────────────────────────────────────────────────
+/** Tier 1 is injected whole on every session, so it has to stay small. */
+exports.MAX_FACTS_PER_PROJECT = 40;
+const MAX_HOTSPOTS = 14;
+const HOTSPOT_MIN_TOUCHES = 3;
+const CONSTRAINT_MIN_OBSERVATIONS = 2;
+/** Restatement threshold for supersession. High on purpose — see below. */
+const RESTATEMENT_THRESHOLD = 0.7;
+// ── tier assignment ──────────────────────────────────────────────────────────
+/**
+ * Tier 2 is a decision you could act on: it says something, and it is anchored
+ * to code. Everything else is an episode. The anchor matters as much as the
+ * text — an unanchored claim cannot be checked for staleness later.
+ */
+function assignTier(atom) {
+    const decisions = (0, compose_1.meaningfulDecisions)(atom.decisions);
+    const files = atom.files_touched ?? [];
+    if (decisions.length === 0)
+        return 3;
+    if (files.length === 0 && !atom.git_commit)
+        return 3;
+    return 2;
+}
+/**
+ * Grade, do not gate.
+ *
+ * Reaching a remote means the work passed whatever gates exist. But a great
+ * deal of valuable knowledge never touches a commit — ops facts, client
+ * preferences, "this is their bug not ours" — so this ranks memories rather
+ * than admitting them.
+ */
+function gradeConfidence(atom) {
+    if (atom.git_commit && atom.git_pushed)
+        return "pushed";
+    if (atom.git_commit)
+        return "committed";
+    return "stated";
+}
+const CONFIDENCE_WEIGHT = {
+    pushed: 1.25,
+    committed: 1.1,
+    stated: 1.0,
+};
+function confidenceFactor(c) {
+    return CONFIDENCE_WEIGHT[c ?? "stated"];
+}
+// ── text helpers ─────────────────────────────────────────────────────────────
+function tokens(s) {
+    return new Set((s || "").toLowerCase().replace(/[^a-z0-9/._-]+/g, " ").split(/\s+/).filter((t) => t.length > 2));
+}
+function jaccard(a, b) {
+    if (!a.size || !b.size)
+        return 0;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    return inter / (a.size + b.size - inter);
+}
+const norm = (s) => s.toLowerCase().replace(/[.!?,;:]+$/g, "").replace(/\s+/g, " ").trim();
+/** Claude stating a completed outcome. */
+const OUTCOME = /^(done|fixed|added|created|removed|updated|refactored|migrated|implemented|configured|wired|built|set up|renamed|dropped|moved|merged|replaced|switched|reverted)\b/i;
+/** An explanation of why something is the way it is. */
+const CAUSAL = /\b(root cause|because|the reason|turns? out|which is why|caused by|due to|the bug was|the problem was)\b/i;
+/** A statement that will still be true next month. */
+const CONSTRAINT = /\b(must (?:be|not|always|never)|cannot be|can'?t be|should (?:always|never)|always (?:use|run|keep)|never (?:use|run|commit)|only works? (?:if|when)|is required|requires? )/i;
+/**
+ * An approach that was tried and abandoned.
+ *
+ * This is the single most valuable thing a memory system holds, because it is
+ * the one thing that leaves no trace in the codebase. The code shows what was
+ * kept; nothing shows what was discarded and why. 28% of this corpus mentions
+ * a failed or abandoned path.
+ */
+const ABANDONED = /\b(did ?n'?t work|does ?n'?t work|do ?n'?t work|didn't help|failed because|turned out|reverted|rolled back|had to (?:revert|undo|drop)|abandoned|gave up on|no longer works?|broke|regressed|caused the|was the culprit|is not the fix|won'?t work|can'?t (?:use|do) .+ because)\b/i;
+/** A reason, which is what makes an abandoned path worth keeping. */
+const REASONED = /\b(because|since|due to|root cause|the reason|turns? out|which is why|so that|otherwise)\b/i;
+/**
+ * Something a human or an external system imposed. Also not in the code:
+ * client preferences, ops facts, third-party behaviour, "this is their bug".
+ * 28% of this corpus mentions one.
+ */
+const EXTERNAL = /\b(client|customer|the user wants|they want|they asked|ops|sysadmin|staging|production server|credential|password rotat|third[- ]party|vendor|upstream|support (?:said|told)|their (?:bug|issue|side|infra|api|server)|rejected|approved|requires? (?:a|an|the) (?:account|licen[cs]e|key))\b/i;
+/**
+ * Shapes that look like knowledge but are not.
+ *
+ * The source material is prose scraped out of a transcript, so it carries
+ * three kinds of impostor: thinking-aloud mid-debug ("there must be another
+ * code path"), UI strings the session happened to be editing ("always use
+ * data"), and changelog lines ("Pushed 58f7b73"). All three match the same
+ * surface patterns as real knowledge. A fact injected into every session
+ * forever has to clear a much higher bar than a search result.
+ */
+const SPECULATION = /\b(there must be|must be another|maybe|perhaps|i think|i wonder|not sure|let me|let's check|hmm|wait[,.]|actually[,.]|probably|might be|could be|looks like|seems to)\b/i;
+/** UI copy, option lists and rendered strings, not statements about the work. */
+const UI_COPY = /(["'][^"']{3,}["']\s*(?:\/|→|->|,)\s*["']|^[-•*]\s|→|✓|✗|\bpanel\b|\bplaceholder\b|\blabel\b|\btooltip\b|\bbutton text\b)/i;
+/** Commit/deploy narration — true, dated, and worthless next month. */
+const CHANGELOG = /^(pushed|committed|deployed|merged|bumped|released)\b|\b[0-9a-f]{7,40}\b.*\b(will run|deploy)/i;
+function isImpostor(d) {
+    return SPECULATION.test(d) || UI_COPY.test(d) || CHANGELOG.test(d);
+}
+/** An explicit replacement — the strongest supersession signal available. */
+const REPLACEMENT = /\b(replaced .+ with|switched from .+ to|no longer|reverted|removed .+ in favou?r of|migrated from .+ to|renamed .+ to|deprecated)\b/i;
+// ── Tier 1 derivation ────────────────────────────────────────────────────────
+/**
+ * Build the always-injected set for one project.
+ *
+ * Nothing here is generated: every fact is either a file the project actually
+ * revolves around, a behaviour observed enough times to be a convention, or a
+ * constraint stated more than once. A fact that cannot point at its evidence
+ * does not belong in a set that is injected unconditionally.
+ */
+function deriveProjectFacts(atoms) {
+    const facts = [];
+    const seen = new Set();
+    const push = (f) => {
+        const key = `${f.kind}::${norm(f.fact)}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        facts.push(f);
+    };
+    // ── hotspots: the files this project revolves around, and what is known
+    // about them. Frequency is the signal — a file touched twenty times is
+    // where the work happens.
+    const touches = new Map();
+    for (const a of atoms) {
+        for (const f of a.files_touched ?? []) {
+            if (!f)
+                continue;
+            const list = touches.get(f);
+            if (list)
+                list.push(a);
+            else
+                touches.set(f, [a]);
+        }
+    }
+    const ranked = [...touches.entries()]
+        .filter(([, as]) => as.length >= HOTSPOT_MIN_TOUCHES)
+        .sort((a, b) => b[1].length - a[1].length)
+        .slice(0, MAX_HOTSPOTS);
+    const described = [];
+    const bare = [];
+    for (const [file, fileAtoms] of ranked) {
+        const base = file.split("/").pop() ?? file;
+        const short = file.split("/").slice(-3).join("/");
+        // A hotspot fact is injected into every session, so a wrong one is
+        // expensive. Only attach a description when the statement actually names
+        // the file — scoring on prose signals alone attached a migration's root
+        // cause to a CI workflow just because one session touched both.
+        let best = null;
+        for (const a of fileAtoms) {
+            for (const raw of (0, compose_1.meaningfulDecisions)(a.decisions)) {
+                const d = raw.replace(/^[-•·*]\s+/, "").trim();
+                if (d.length < 30 || d.length > 180)
+                    continue;
+                if (!d.includes(base))
+                    continue;
+                // A "description" that is mostly the path again says nothing.
+                if (d.replace(file, "").replace(base, "").trim().length < 20)
+                    continue;
+                // Prefer a statement that explains or decides over one that lists.
+                const better = OUTCOME.test(d) || CAUSAL.test(d) || CONSTRAINT.test(d);
+                if (!best || (better && !(OUTCOME.test(best.text) || CAUSAL.test(best.text)))) {
+                    best = { text: d, conf: a.confidence ?? "stated" };
+                }
+            }
+        }
+        if (best) {
+            described.push(file);
+            push({
+                kind: "hotspot",
+                fact: `${short} — ${best.text}`,
+                evidence: `touched in ${fileAtoms.length} sessions`,
+                files: [file],
+                observations: fileAtoms.length,
+                confidence: best.conf,
+            });
+        }
+        else {
+            bare.push(file);
+        }
+    }
+    // Files we know are central but have nothing to say about. One line beats
+    // fourteen copies of "X is central to this project".
+    if (bare.length) {
+        push({
+            kind: "hotspot",
+            fact: `Most-touched files: ${bare.map((f) => f.split("/").slice(-2).join("/")).slice(0, 10).join(", ")}`,
+            evidence: `${bare.length} files by edit frequency`,
+            files: bare,
+            observations: bare.reduce((s2, f) => s2 + (touches.get(f)?.length ?? 0), 0),
+            confidence: "stated",
+        });
+    }
+    // ── pitfalls: what was tried and abandoned, with the reason
+    //
+    // Held to a high bar because these are injected into every session: a
+    // statement must both report an abandonment AND give a reason. "That broke"
+    // is not worth a permanent slot; "that broke because the hook runs in a
+    // fresh process each time" is.
+    const pitfalls = new Map();
+    for (const a of atoms) {
+        for (const raw of (0, compose_1.meaningfulDecisions)(a.decisions)) {
+            const d = raw.replace(/^[-•·*]\s+/, "").trim();
+            if (d.length < 30 || d.length > 220)
+                continue;
+            if (d.endsWith("?"))
+                continue;
+            if (!ABANDONED.test(d) || !REASONED.test(d))
+                continue;
+            if (isImpostor(d))
+                continue;
+            const key = norm(d);
+            const prev = pitfalls.get(key);
+            if (prev)
+                prev.count++;
+            else
+                pitfalls.set(key, { count: 1, files: a.files_touched ?? [], conf: a.confidence ?? "stated", at: a.started_at });
+        }
+    }
+    for (const [key, v] of [...pitfalls.entries()].sort((x, y) => y[1].count - x[1].count).slice(0, 10)) {
+        push({
+            kind: "pitfall",
+            fact: key.charAt(0).toUpperCase() + key.slice(1),
+            evidence: v.count > 1 ? `hit ${v.count} times` : "learned once",
+            files: v.files.slice(0, 3),
+            observations: v.count,
+            confidence: v.conf,
+        });
+    }
+    // ── context: what a human or an external system imposed
+    const contexts = new Map();
+    for (const a of atoms) {
+        for (const raw of (0, compose_1.meaningfulDecisions)(a.decisions)) {
+            const d = raw.replace(/^[-•·*]\s+/, "").trim();
+            if (d.length < 30 || d.length > 220)
+                continue;
+            if (d.endsWith("?"))
+                continue;
+            if (!EXTERNAL.test(d))
+                continue;
+            if (isImpostor(d))
+                continue;
+            // The external actor must be the subject of a durable claim, not a word
+            // that happens to appear. "the client wants X" qualifies; "update status
+            // modal (pending -> approved)" does not.
+            if (!/\b(client|customer|ops|vendor|upstream|they|their|support|staging|production)\b[^.]{0,40}\b(is|are|was|were|must|should|cannot|can'?t|wants?|needs?|requires?|rotat|rejected|approved|said|told|asked|returns?|fails?|crashes?|breaks?|blocks?|holds?|throws?|expires?|times out|changed)\b/i.test(d))
+                continue;
+            const key = norm(d);
+            const prev = contexts.get(key);
+            if (prev)
+                prev.count++;
+            else
+                contexts.set(key, { count: 1, files: a.files_touched ?? [], conf: a.confidence ?? "stated" });
+        }
+    }
+    for (const [key, v] of [...contexts.entries()].sort((x, y) => y[1].count - x[1].count).slice(0, 10)) {
+        push({
+            kind: "context",
+            fact: key.charAt(0).toUpperCase() + key.slice(1),
+            evidence: v.count > 1 ? `stated ${v.count} times` : "stated once",
+            files: v.files.slice(0, 3),
+            observations: v.count,
+            confidence: v.conf,
+        });
+    }
+    // ── constraints: rules stated more than once
+    const constraintCounts = new Map();
+    for (const a of atoms) {
+        for (const d of (0, compose_1.meaningfulDecisions)(a.decisions)) {
+            if (!CONSTRAINT.test(d) || d.length > 200)
+                continue;
+            if (isImpostor(d))
+                continue;
+            // "Done. now uses X" reports a change; it is not a standing rule.
+            // Outcome narration belongs in tier 2, where it can be retrieved when
+            // relevant, rather than asserted on every session forever.
+            if (OUTCOME.test(d))
+                continue;
+            const key = norm(d);
+            const prev = constraintCounts.get(key);
+            if (prev) {
+                prev.count++;
+            }
+            else {
+                constraintCounts.set(key, { count: 1, files: a.files_touched ?? [], conf: a.confidence ?? "stated" });
+            }
+        }
+    }
+    for (const [key, v] of [...constraintCounts.entries()].sort((a, b) => b[1].count - a[1].count)) {
+        if (v.count < CONSTRAINT_MIN_OBSERVATIONS)
+            continue;
+        push({
+            kind: "constraint",
+            fact: key.charAt(0).toUpperCase() + key.slice(1),
+            evidence: `stated ${v.count} times`,
+            files: v.files.slice(0, 3),
+            observations: v.count,
+            confidence: v.conf,
+        });
+    }
+    // Rank by what only memory can know, then by weight of evidence. Sorting on
+    // raw counts let hotspots — cheap, and re-derivable with one `git log` —
+    // crowd out the pitfalls that are the whole point of keeping a history.
+    const KIND_RANK = {
+        pitfall: 0, context: 1, constraint: 2, note: 3, hotspot: 4,
+    };
+    return facts
+        .sort((a, b) => (KIND_RANK[a.kind] - KIND_RANK[b.kind]) || (b.observations - a.observations))
+        .slice(0, exports.MAX_FACTS_PER_PROJECT);
+}
+function safeParse(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find memories a later one has made obsolete.
+ *
+ * Deliberately conservative, and nothing here deletes. Two rules only:
+ *
+ *   restated  the same statement, made again later about the same file. The
+ *             older copy adds nothing.
+ *   replaced  a later memory explicitly says something was swapped out, and
+ *             names a thing the older one was about.
+ *
+ * What this does NOT do is treat "the file changed" as "the decision is
+ * wrong". Files change constantly without invalidating why they are the way
+ * they are, and some decisions outlive their code entirely — "we left Stripe
+ * because of PH support" stays true long after the Stripe code is gone.
+ */
+function findSupersessions(atoms) {
+    const byProject = new Map();
+    for (const a of atoms) {
+        const list = byProject.get(a.project_id);
+        if (list)
+            list.push(a);
+        else
+            byProject.set(a.project_id, [a]);
+    }
+    const out = [];
+    for (const group of byProject.values()) {
+        const sorted = [...group].sort((a, b) => new Date(a.started_at).getTime() - new Date(b.started_at).getTime());
+        for (let i = 0; i < sorted.length; i++) {
+            const older = sorted[i];
+            const olderFiles = new Set(older.files_touched ?? []);
+            if (olderFiles.size === 0)
+                continue;
+            const olderText = tokens(older.content ?? "");
+            if (olderText.size === 0)
+                continue;
+            for (let j = i + 1; j < sorted.length; j++) {
+                const newer = sorted[j];
+                const sharesFile = (newer.files_touched ?? []).some((f) => olderFiles.has(f));
+                if (!sharesFile)
+                    continue;
+                const newerText = tokens(newer.content ?? "");
+                if (newerText.size === 0)
+                    continue;
+                if (jaccard(olderText, newerText) >= RESTATEMENT_THRESHOLD) {
+                    out.push({ superseded: older.id, by: newer.id, reason: "restated" });
+                    break;
+                }
+                if (REPLACEMENT.test(newer.content ?? "")) {
+                    // Only when the replacement actually talks about the same subject,
+                    // not merely the same file.
+                    const overlap = jaccard(olderText, newerText);
+                    if (overlap >= 0.35) {
+                        out.push({ superseded: older.id, by: newer.id, reason: "replaced" });
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    return out;
+}