@gamaze/hicortex 0.14.4 → 0.15.0

package/README.md

@@ -157,6 +157,8 @@ npx @gamaze/hicortex nightly                   # Run distill + consolidate (full
 npx @gamaze/hicortex nightly --capture-only    # Capture only, skip consolidation (safe for sub-daily runs)
 npx @gamaze/hicortex nightly --dry-run         # Preview without changes
 npx @gamaze/hicortex classify-domains          # Backfill domain tags over the corpus (see Memory Domains & Tags)
+npx @gamaze/hicortex dedup                     # Preview near-duplicate memory clusters (dry run, no changes)
+npx @gamaze/hicortex dedup --apply             # Merge near-duplicate clusters (backs up the DB first)
 npx @gamaze/hicortex context show [name]       # Print the standing context layer (see Context Layer)
 npx @gamaze/hicortex context edit <name>       # Edit a context section in $EDITOR
 npx @gamaze/hicortex context show --agent <id> # Show a specific agent's resolved context (0.13)
@@ -215,6 +217,10 @@ Config at `~/.hicortex/config.json`. Created by `init`. Key options:
 | `recallMinSimilarity` | Relevance floor for index entries (default: 0.55; text-search matches always pass) |
 | `recallReshowTurns` | Turns before an already-shown memory may reappear in the same session (default: 30) |
 | `recallMinPromptChars` | Prompts shorter than this skip the recall index (default: 20) |
+| `dedupMergeThreshold` | Minimum cosine similarity for `hicortex dedup` to cluster memories as near-duplicates (default: 0.92) |
+| `supersessionMinSimilarity` | Minimum cosine similarity for a nightly supersession candidate pair (default: 0.80) |
+| `supersessionMaxCalls` | Max classify-tier LLM calls the nightly's supersession stage spends per run (default: 30) |
+| `supersessionPenalty` | Multiplier applied to a superseded memory's `base_strength` (default: 0.5) |
 | `telemetry` | Anonymous usage telemetry, `false` to opt out |
 
 Full docs: [hicortex.gamaze.com/docs/configuration.html](https://hicortex.gamaze.com/docs/configuration.html)

package/dist/cli.d.ts

@@ -9,6 +9,8 @@
  *              nightly --capture-only  Capture only, skip consolidation
  *              nightly --status        Show nightly pipeline health check
  *   relink     Resumable link-discovery pass over the entire corpus (issue #143)
+ *   dedup      Cluster + merge near-duplicate memories (issue #100)
+ *              dedup --apply           Execute the merge (default: dry run)
  *   status     Show config, DB stats, adapter status
  *   uninstall  Clean removal of CC integration
  */

package/dist/cli.js

@@ -10,6 +10,8 @@
  *              nightly --capture-only  Capture only, skip consolidation
  *              nightly --status        Show nightly pipeline health check
  *   relink     Resumable link-discovery pass over the entire corpus (issue #143)
+ *   dedup      Cluster + merge near-duplicate memories (issue #100)
+ *              dedup --apply           Execute the merge (default: dry run)
  *   status     Show config, DB stats, adapter status
  *   uninstall  Clean removal of CC integration
  */
@@ -134,6 +136,40 @@ switch (command) {
         });
         break;
     }
+    case "dedup": {
+        const args = process.argv.slice(3);
+        let threshold;
+        try {
+            const raw = (0, cli_args_js_1.readValueFlag)(args, "--threshold");
+            if (raw !== undefined) {
+                threshold = parseFloat(raw);
+                if (isNaN(threshold)) {
+                    console.error("[hicortex] dedup: --threshold requires a numeric value, e.g. --threshold 0.9");
+                    process.exit(1);
+                }
+            }
+        }
+        catch {
+            console.error("[hicortex] dedup: --threshold requires a value, e.g. --threshold 0.9");
+            process.exit(1);
+        }
+        let dbPath;
+        try {
+            dbPath = (0, cli_args_js_1.readValueFlag)(args, "--db");
+        }
+        catch {
+            console.error("[hicortex] dedup: --db requires a path value");
+            process.exit(1);
+        }
+        const dedupOptions = { apply: args.includes("--apply"), threshold, dbPath };
+        import("./dedup.js").then(({ runDedup }) => {
+            runDedup(dedupOptions).catch((err) => {
+                console.error(err instanceof Error ? err.message : `[hicortex] dedup failed: ${err}`);
+                process.exit(1);
+            });
+        });
+        break;
+    }
     case "context": {
         // Standing context layer edit surface (spec §6): show|edit against the
         // configured server. Secondary to the /context/ui Web UI; for headless boxes.
@@ -205,6 +241,7 @@ Commands:
                             Pass --agent-name "" to clear it back to global
   nightly         Run nightly denoise + capture + consolidate
   relink          Resumable link-discovery pass over the ENTIRE corpus (server mode)
+  dedup           Cluster + merge near-duplicate memories (server mode; dry run by default)
   classify-domains  Backfill content-based domain tags over the corpus (server mode, needs config.domains)
   lessons-context Fetch lessons and print Markdown to stdout (CC SessionStart hook)
   recall-hook    Pushed recall index for the current prompt (CC UserPromptSubmit/SessionStart hook)
@@ -222,6 +259,9 @@ Options:
   relink --dry-run          Discovery + counts only, zero writes, cursor untouched
   relink --batch <n>        Memories per batch (default: 200)
   relink --reset            Restart from the beginning (ignore saved cursor)
+  dedup --apply             Execute the merge (default: dry run, report only)
+  dedup --threshold <t>     Override config dedupMergeThreshold for one run
+  dedup --db <path>         DB path override (defaults to the configured DB)
   classify-domains --all    Reclassify every memory (default: only NULL/stale-domain rows)
   classify-domains --batch <n>  Memories per batch (default: 200)
   classify-domains --reset  Restart from the beginning (ignore saved cursor)

package/dist/cluster.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared vector-cluster utilities: union-find clustering + KNN edge building.
+ *
+ * Originally lived entirely in src/eval/dups.ts (the #191 D1 duplicate-rate
+ * audit). Extracted so `hicortex dedup` (#100) reuses the EXACT same
+ * clustering math instead of re-implementing it — the read-only audit and the
+ * live merge command must agree on what a "cluster" is.
+ */
+import type Database from "better-sqlite3";
+/** An undirected similarity edge between two memory ids. */
+export interface Edge {
+    a: string;
+    b: string;
+    cosine: number;
+}
+/** Minimal union-find over string ids, with path compression. */
+export declare class UnionFind {
+    private parent;
+    find(x: string): string;
+    union(a: string, b: string): void;
+    /** All known nodes grouped by cluster root (includes singletons). */
+    clusters(): Map<string, string[]>;
+}
+/** Build clusters (size >= 2) from edges at/above a cosine threshold. */
+export declare function clusterEdges(edges: Edge[], threshold: number): string[][];
+/** Excess = sum(cluster size − 1) — rows that would disappear if every cluster merged to one. */
+export declare function clusterExcess(clusters: string[][]): number;
+/** The three metadata fields a merge candidate cluster must agree on. */
+export interface ClusterMetaRow {
+    project: string | null;
+    privacy: string;
+    source_agent: string;
+}
+export interface ClusterMetadataMismatch {
+    projectMismatch: boolean;
+    privacyMismatch: boolean;
+    sourceAgentMismatch: boolean;
+}
+/** Do cluster members disagree on project/privacy/source_agent? (merge-safety input for #100). */
+export declare function clusterMetadataMismatch(members: ClusterMetaRow[]): ClusterMetadataMismatch;
+/**
+ * Build the max-cosine edge set via top-K KNN on `memory_vectors`, keeping
+ * only pairs at/above `minCosine`. Shared by the #191 audit (which then
+ * clusters at several report thresholds) and `hicortex dedup` (a single merge
+ * threshold) — same query, same math, so the two never disagree on what
+ * counts as a near-duplicate pair.
+ */
+export declare function buildKnnEdges(db: Database.Database, opts: {
+    k?: number;
+    minCosine: number;
+}): Edge[];

package/dist/cluster.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Shared vector-cluster utilities: union-find clustering + KNN edge building.
+ *
+ * Originally lived entirely in src/eval/dups.ts (the #191 D1 duplicate-rate
+ * audit). Extracted so `hicortex dedup` (#100) reuses the EXACT same
+ * clustering math instead of re-implementing it — the read-only audit and the
+ * live merge command must agree on what a "cluster" is.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnionFind = void 0;
+exports.clusterEdges = clusterEdges;
+exports.clusterExcess = clusterExcess;
+exports.clusterMetadataMismatch = clusterMetadataMismatch;
+exports.buildKnnEdges = buildKnnEdges;
+const retrieval_js_1 = require("./retrieval.js");
+// ---------------------------------------------------------------------------
+// Union-Find (pure — unit tested)
+// ---------------------------------------------------------------------------
+/** Minimal union-find over string ids, with path compression. */
+class UnionFind {
+    parent = new Map();
+    find(x) {
+        if (!this.parent.has(x)) {
+            this.parent.set(x, x);
+            return x;
+        }
+        let root = x;
+        while (this.parent.get(root) !== root) {
+            root = this.parent.get(root);
+        }
+        let cur = x;
+        while (this.parent.get(cur) !== root) {
+            const next = this.parent.get(cur);
+            this.parent.set(cur, root);
+            cur = next;
+        }
+        return root;
+    }
+    union(a, b) {
+        const ra = this.find(a);
+        const rb = this.find(b);
+        if (ra !== rb)
+            this.parent.set(ra, rb);
+    }
+    /** All known nodes grouped by cluster root (includes singletons). */
+    clusters() {
+        const groups = new Map();
+        for (const node of this.parent.keys()) {
+            const root = this.find(node);
+            const arr = groups.get(root) ?? [];
+            arr.push(node);
+            groups.set(root, arr);
+        }
+        return groups;
+    }
+}
+exports.UnionFind = UnionFind;
+/** Build clusters (size >= 2) from edges at/above a cosine threshold. */
+function clusterEdges(edges, threshold) {
+    const uf = new UnionFind();
+    for (const e of edges) {
+        if (e.cosine >= threshold)
+            uf.union(e.a, e.b);
+    }
+    return [...uf.clusters().values()].filter((g) => g.length >= 2);
+}
+/** Excess = sum(cluster size − 1) — rows that would disappear if every cluster merged to one. */
+function clusterExcess(clusters) {
+    return clusters.reduce((sum, c) => sum + (c.length - 1), 0);
+}
+/** Do cluster members disagree on project/privacy/source_agent? (merge-safety input for #100). */
+function clusterMetadataMismatch(members) {
+    const projects = new Set(members.map((m) => m.project ?? "\u0000null"));
+    const privacies = new Set(members.map((m) => m.privacy));
+    const agents = new Set(members.map((m) => m.source_agent));
+    return {
+        projectMismatch: projects.size > 1,
+        privacyMismatch: privacies.size > 1,
+        sourceAgentMismatch: agents.size > 1,
+    };
+}
+// ---------------------------------------------------------------------------
+// KNN edge building
+// ---------------------------------------------------------------------------
+/** Neighbors requested per memory (excluding the memory itself), unless overridden. */
+const DEFAULT_KNN_K = 10;
+/**
+ * Build the max-cosine edge set via top-K KNN on `memory_vectors`, keeping
+ * only pairs at/above `minCosine`. Shared by the #191 audit (which then
+ * clusters at several report thresholds) and `hicortex dedup` (a single merge
+ * threshold) — same query, same math, so the two never disagree on what
+ * counts as a near-duplicate pair.
+ */
+function buildKnnEdges(db, opts) {
+    const k = opts.k ?? DEFAULT_KNN_K;
+    const vectorRows = db.prepare("SELECT id, embedding FROM memory_vectors").all();
+    const knnStmt = db.prepare("SELECT id, distance FROM memory_vectors WHERE embedding MATCH ? AND k = ? ORDER BY distance");
+    const edgeMap = new Map(); // "a|b" (a < b) -> max cosine seen from either direction
+    for (const row of vectorRows) {
+        const neighbors = knnStmt.all(row.embedding, k + 1);
+        for (const n of neighbors) {
+            if (n.id === row.id)
+                continue;
+            const cosine = (0, retrieval_js_1.l2ToCosine)(n.distance);
+            if (cosine < opts.minCosine)
+                continue;
+            const key = row.id < n.id ? `${row.id}|${n.id}` : `${n.id}|${row.id}`;
+            const existing = edgeMap.get(key);
+            if (existing === undefined || cosine > existing)
+                edgeMap.set(key, cosine);
+        }
+    }
+    return [...edgeMap.entries()].map(([key, cosine]) => {
+        const [a, b] = key.split("|");
+        return { a, b, cosine };
+    });
+}

package/dist/consolidate.d.ts

@@ -131,6 +131,68 @@ export declare function classifyLinkCandidates(candidates: LinkCandidate[], _llm
  * boundary from the l2ToCosine calibration is preserved.
  */
 export declare function classifyRelationship(source: Memory, target: Memory, similarity: number): string;
+/** Default minimum COSINE similarity for a supersession candidate pair. */
+export declare const DEFAULT_SUPERSESSION_MIN_SIMILARITY = 0.8;
+/** Default max classify-tier LLM calls (pairs evaluated) spent per nightly run. */
+export declare const DEFAULT_SUPERSESSION_MAX_CALLS = 30;
+/** Default multiplier applied to a superseded memory's base_strength. */
+export declare const DEFAULT_SUPERSESSION_PENALTY = 0.5;
+export interface SupersessionOptions {
+    minSimilarity?: number;
+    maxCalls?: number;
+    penalty?: number;
+}
+export interface SupersessionStageResult {
+    scanned: number;
+    evaluated: number;
+    superseded: number;
+    skipped_infra: number;
+    skipped_idempotent: number;
+    cursor: number;
+}
+/**
+ * Build the constrained supersession-check prompt. Content is truncated the
+ * same width as domain-classify.ts's classifier (1500 chars) — this is a
+ * classify-tier call with the same cost profile.
+ */
+export declare function buildSupersessionPrompt(oldContent: string, newContent: string): string;
+/**
+ * Parse the model's supersession verdict. Returns the boolean on a valid
+ * reply, or null on anything unparseable (caller skips the pair — no retry,
+ * unlike domain-classify's tag classifier; a missed pair is retried naturally
+ * when this stage revisits the corpus).
+ */
+export declare function parseSupersessionReply(reply: string): boolean | null;
+/**
+ * Nightly supersession-detection stage. Scans memories/rowid > cursor whose
+ * shape suggests a decision/correction, checks each against its older
+ * same-shape neighbors, and links confirmed supersessions. Dry-run performs
+ * discovery + the free idempotency check only — no LLM calls, no writes, no
+ * cursor persistence (mirrors stageImportance/stageContentDomains's dry-run
+ * convention of never spending budget on a preview).
+ *
+ * Cursor discipline is DELIBERATELY simple (owner amendment): the cursor
+ * advances past a candidate once its neighbor set has been considered,
+ * REGARDLESS of whether every pair got an LLM call (call budget) or a clean
+ * verdict (infra skip) — missing one pair is acceptable and self-heals next
+ * time this memory's neighborhood is re-examined via a NEWER memory's own
+ * candidacy. It only stops SHORT of a candidate when the budget is already
+ * exhausted before that candidate starts, so the cursor never skips a
+ * candidate that was never looked at.
+ */
+export declare function stageSupersession(db: Database.Database, llm: LlmClient, budget: BudgetTracker, embedFn: EmbedFn, dryRun: boolean, stateDir: string | undefined, options?: SupersessionOptions): Promise<SupersessionStageResult>;
+/**
+ * Exported for the #191 eval baseline (src/eval/decay-eval.ts) so the audit
+ * runs the REAL production prune predicate against a DB snapshot instead of
+ * reimplementing it. `dryRun=true` performs reads only (candidates are
+ * counted, nothing is deleted) — safe against a readonly snapshot connection.
+ * Not otherwise part of the public API surface.
+ */
+export declare function stageDecayPrune(db: Database.Database, dryRun: boolean): {
+    candidates: number;
+    pruned: number;
+    failed: number;
+};
 /**
  * Run the full consolidation pipeline. Returns a structured report.
  */
@@ -156,7 +218,7 @@ export interface DomainStageOptions {
      */
     weakPrimaryFloor?: number;
 }
-export declare function runConsolidation(db: Database.Database, llm: LlmClient, embedFn: EmbedFn, dryRun?: boolean, skipReflection?: boolean, stateDir?: string, domainOptions?: DomainStageOptions): Promise<ConsolidationReport>;
+export declare function runConsolidation(db: Database.Database, llm: LlmClient, embedFn: EmbedFn, dryRun?: boolean, skipReflection?: boolean, stateDir?: string, domainOptions?: DomainStageOptions, supersessionOptions?: SupersessionOptions): Promise<ConsolidationReport>;
 /**
  * Calculate milliseconds until the next occurrence of a given hour (local time).
  */

package/dist/consolidate.js

@@ -38,13 +38,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BudgetTracker = exports.REFLECTION_CONTRADICTION_MIN_COSINE = exports.l2ToCosine = exports.CROSS_PROJECT_LINK_THRESHOLD = exports.CONSOLIDATE_LINK_TOP_K = exports.CONSOLIDATE_LINK_THRESHOLD = void 0;
+exports.DEFAULT_SUPERSESSION_PENALTY = exports.DEFAULT_SUPERSESSION_MAX_CALLS = exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY = exports.BudgetTracker = exports.REFLECTION_CONTRADICTION_MIN_COSINE = exports.l2ToCosine = exports.CROSS_PROJECT_LINK_THRESHOLD = exports.CONSOLIDATE_LINK_TOP_K = exports.CONSOLIDATE_LINK_THRESHOLD = void 0;
 exports.isContradictionCandidate = isContradictionCandidate;
 exports.parseJsonLenient = parseJsonLenient;
 exports.rebuildContentModuleIndex = rebuildContentModuleIndex;
 exports.discoverLinkCandidates = discoverLinkCandidates;
 exports.classifyLinkCandidates = classifyLinkCandidates;
 exports.classifyRelationship = classifyRelationship;
+exports.buildSupersessionPrompt = buildSupersessionPrompt;
+exports.parseSupersessionReply = parseSupersessionReply;
+exports.stageSupersession = stageSupersession;
+exports.stageDecayPrune = stageDecayPrune;
 exports.runConsolidation = runConsolidation;
 exports.msUntilHour = msUntilHour;
 exports.scheduleConsolidation = scheduleConsolidation;
@@ -822,8 +826,228 @@ function stageHubBoost(db, dryRun) {
     return { hubs_found: hubs.length, boosted };
 }
 // ---------------------------------------------------------------------------
+// Stage 3.7: Supersession Detection (#191 Phase B)
+// ---------------------------------------------------------------------------
+//
+// A later decision/correction can reverse, replace, or invalidate an earlier
+// one — e.g. "chose Ollama for distillation" superseded a month later by
+// "switched distillation to the MBP's 35B model over Tailscale". Left
+// unlinked, retrieval and lesson selection can surface the stale one. This
+// stage links OLD → NEW with relationship `superseded_by` and accelerates the
+// old memory's decay, WITHOUT deleting it (unlike `hicortex dedup`'s merge —
+// this is a judgment call about content, not a duplicate).
+//
+// Scope: memories with `rowid > supersessionCursor` (state.json; starts 0 —
+// the corpus is back-processed gradually, config `supersessionMaxCalls` LLM
+// calls per night) whose shape suggests a decision/correction. For each,
+// KNN top-5 OLDER same-shape neighbors at/above `supersessionMinSimilarity`;
+// one constrained classify-tier LLM call per pair decides `superseded: true|
+// false`. A parse/infra error skips just that PAIR (retried naturally next
+// night since the cursor still advances past the memory — see the cursor
+// note below); it never mis-links.
+/** Default minimum COSINE similarity for a supersession candidate pair. */
+exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY = 0.8;
+/** Default max classify-tier LLM calls (pairs evaluated) spent per nightly run. */
+exports.DEFAULT_SUPERSESSION_MAX_CALLS = 30;
+/** Default multiplier applied to a superseded memory's base_strength. */
+exports.DEFAULT_SUPERSESSION_PENALTY = 0.5;
+/** Floor under which a superseded memory's base_strength never drops. */
+const SUPERSESSION_STRENGTH_FLOOR = 0.1;
+/** Neighbor pool size before shape/older/similarity filtering narrows to top 5. */
+const SUPERSESSION_NEIGHBOR_POOL = 15;
+/** Older-neighbor pairs kept per candidate after filtering. */
+const SUPERSESSION_NEIGHBOR_TOP_K = 5;
+/** Candidate rows read per SQL page (call budget stops the loop well before this in practice). */
+const SUPERSESSION_BATCH_SIZE = 500;
+/** A memory whose content/type marks it as a decision or correction. */
+function isDecisionShape(mem) {
+    return (mem.memory_type === "decision" ||
+        mem.content.includes("[Decisions Made]") ||
+        mem.content.includes("[Corrections & Rejections]"));
+}
+/** True when a `superseded_by` link already exists between the pair, either direction. */
+function alreadySupersedeLinked(db, oldId, newId) {
+    const row = db
+        .prepare(`SELECT 1 FROM memory_links WHERE relationship = 'superseded_by'
+       AND ((source_id = ? AND target_id = ?) OR (source_id = ? AND target_id = ?))`)
+        .get(oldId, newId, newId, oldId);
+    return !!row;
+}
+/**
+ * Build the constrained supersession-check prompt. Content is truncated the
+ * same width as domain-classify.ts's classifier (1500 chars) — this is a
+ * classify-tier call with the same cost profile.
+ */
+function buildSupersessionPrompt(oldContent, newContent) {
+    const trunc = (s) => (s.length > 1500 ? `${s.slice(0, 1500)}…` : s);
+    return (`You are checking whether a NEWER memory supersedes an OLDER one in an AI agent's long-term memory.\n\n` +
+        `OLDER MEMORY:\n${trunc(oldContent)}\n\n` +
+        `NEWER MEMORY:\n${trunc(newContent)}\n\n` +
+        `Does the NEWER memory reverse, replace, or invalidate the OLDER one — e.g. a later decision overturns an ` +
+        `earlier one, or a correction retracts a prior claim? Two memories that are merely related, or that both ` +
+        `still hold true, are NOT a supersession.\n` +
+        `Reply with ONLY a JSON object, no prose: {"superseded": true} or {"superseded": false}.`);
+}
+/**
+ * Parse the model's supersession verdict. Returns the boolean on a valid
+ * reply, or null on anything unparseable (caller skips the pair — no retry,
+ * unlike domain-classify's tag classifier; a missed pair is retried naturally
+ * when this stage revisits the corpus).
+ */
+function parseSupersessionReply(reply) {
+    if (!reply)
+        return null;
+    const start = reply.indexOf("{");
+    const end = reply.lastIndexOf("}");
+    if (start === -1 || end === -1 || end <= start)
+        return null;
+    try {
+        const obj = JSON.parse(reply.slice(start, end + 1));
+        return typeof obj.superseded === "boolean" ? obj.superseded : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ONE classify-tier LLM call judging whether `newContent` supersedes
+ * `oldContent`. Returns null on any infra error or unparseable reply — the
+ * caller treats null as "skip this pair" (never mis-links on ambiguity).
+ */
+async function classifySupersession(llm, oldContent, newContent) {
+    try {
+        const raw = await llm.completeClassify(buildSupersessionPrompt(oldContent, newContent), 32);
+        return parseSupersessionReply(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Find up to SUPERSESSION_NEIGHBOR_TOP_K OLDER, same-shape neighbors for a
+ * candidate, at/above minSimilarity, highest cosine first. Reuses the
+ * candidate's stored embedding when available (relink-style fallback to
+ * embedFn otherwise).
+ */
+async function findOlderNeighbors(db, candidate, embedFn, minSimilarity) {
+    const embedding = storage.getStoredEmbedding(db, candidate.id) ?? (await embedFn(candidate.content));
+    return storage
+        .vectorSearch(db, embedding, SUPERSESSION_NEIGHBOR_POOL, [candidate.id])
+        .filter((n) => n.created_at < candidate.created_at &&
+        isDecisionShape(n) &&
+        (0, retrieval_js_1.l2ToCosine)(n.distance) >= minSimilarity)
+        .sort((a, b) => (0, retrieval_js_1.l2ToCosine)(b.distance) - (0, retrieval_js_1.l2ToCosine)(a.distance))
+        .slice(0, SUPERSESSION_NEIGHBOR_TOP_K);
+}
+/**
+ * Nightly supersession-detection stage. Scans memories/rowid > cursor whose
+ * shape suggests a decision/correction, checks each against its older
+ * same-shape neighbors, and links confirmed supersessions. Dry-run performs
+ * discovery + the free idempotency check only — no LLM calls, no writes, no
+ * cursor persistence (mirrors stageImportance/stageContentDomains's dry-run
+ * convention of never spending budget on a preview).
+ *
+ * Cursor discipline is DELIBERATELY simple (owner amendment): the cursor
+ * advances past a candidate once its neighbor set has been considered,
+ * REGARDLESS of whether every pair got an LLM call (call budget) or a clean
+ * verdict (infra skip) — missing one pair is acceptable and self-heals next
+ * time this memory's neighborhood is re-examined via a NEWER memory's own
+ * candidacy. It only stops SHORT of a candidate when the budget is already
+ * exhausted before that candidate starts, so the cursor never skips a
+ * candidate that was never looked at.
+ */
+async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, options = {}) {
+    // Config values pass through `unknown`-typed JSON — validate rather than
+    // trust (same discipline as retrieval.ts's configureRecall).
+    const validNumber = (v, fallback, ok) => {
+        const n = Number(v);
+        return Number.isFinite(n) && ok(n) ? n : fallback;
+    };
+    const minSimilarity = validNumber(options.minSimilarity, exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY, (n) => n > 0 && n <= 1);
+    const maxCalls = validNumber(options.maxCalls, exports.DEFAULT_SUPERSESSION_MAX_CALLS, (n) => n >= 0);
+    const penalty = validNumber(options.penalty, exports.DEFAULT_SUPERSESSION_PENALTY, (n) => n > 0 && n <= 1);
+    const startCursor = (0, state_js_1.loadState)(stateDir).supersessionCursor ?? 0;
+    const rows = db
+        .prepare(`SELECT rowid AS __rowid, * FROM memories
+       WHERE rowid > ?
+         AND (memory_type = 'decision' OR content LIKE '%[Decisions Made]%' OR content LIKE '%[Corrections & Rejections]%')
+       ORDER BY rowid ASC LIMIT ?`)
+        .all(startCursor, SUPERSESSION_BATCH_SIZE);
+    let scanned = 0;
+    let evaluated = 0;
+    let superseded = 0;
+    let skippedInfra = 0;
+    let skippedIdempotent = 0;
+    let callsUsed = 0;
+    let cursor = startCursor;
+    for (const candidate of rows) {
+        if (!dryRun && (callsUsed >= maxCalls || budget.exhausted))
+            break;
+        scanned++;
+        let neighbors;
+        try {
+            neighbors = await findOlderNeighbors(db, candidate, embedFn, minSimilarity);
+        }
+        catch (err) {
+            console.warn(`[hicortex] supersession: discovery failed for ${candidate.id.slice(0, 8)} — ${err instanceof Error ? err.message : String(err)}`);
+            cursor = candidate.__rowid;
+            continue;
+        }
+        for (const neighbor of neighbors) {
+            if (alreadySupersedeLinked(db, neighbor.id, candidate.id)) {
+                skippedIdempotent++;
+                continue;
+            }
+            if (dryRun)
+                continue; // preview only — no LLM call, no write
+            if (callsUsed >= maxCalls || !budget.use("supersession"))
+                break;
+            callsUsed++;
+            const verdict = await classifySupersession(llm, neighbor.content, candidate.content);
+            evaluated++;
+            if (verdict === null) {
+                skippedInfra++;
+                continue;
+            }
+            if (verdict) {
+                const cosine = (0, retrieval_js_1.l2ToCosine)(neighbor.distance);
+                storage.addLink(db, neighbor.id, candidate.id, "superseded_by", cosine);
+                const newStrength = Math.max(SUPERSESSION_STRENGTH_FLOOR, (neighbor.base_strength ?? 0.5) * penalty);
+                storage.updateMemory(db, neighbor.id, { base_strength: newStrength });
+                superseded++;
+                console.log(`[hicortex] Supersession: ${neighbor.id.slice(0, 8)} superseded_by ${candidate.id.slice(0, 8)} (cosine ${cosine.toFixed(3)})`);
+            }
+        }
+        cursor = candidate.__rowid;
+    }
+    if (!dryRun) {
+        (0, state_js_1.updateState)((s) => {
+            s.supersessionCursor = cursor;
+        }, stateDir);
+    }
+    if (rows.length > 0) {
+        console.log(`[hicortex] Supersession detection: ${scanned} scanned, ${evaluated} evaluated, ${superseded} superseded, ` +
+            `${skippedIdempotent} already-linked, ${skippedInfra} infra-skipped (cursor ${cursor})`);
+    }
+    return {
+        scanned,
+        evaluated,
+        superseded,
+        skipped_infra: skippedInfra,
+        skipped_idempotent: skippedIdempotent,
+        cursor,
+    };
+}
+// ---------------------------------------------------------------------------
 // Stage 4: Decay & Prune
 // ---------------------------------------------------------------------------
+/**
+ * Exported for the #191 eval baseline (src/eval/decay-eval.ts) so the audit
+ * runs the REAL production prune predicate against a DB snapshot instead of
+ * reimplementing it. `dryRun=true` performs reads only (candidates are
+ * counted, nothing is deleted) — safe against a readonly snapshot connection.
+ * Not otherwise part of the public API surface.
+ */
 function stageDecayPrune(db, dryRun) {
     const now = new Date();
     const cutoff = new Date(now.getTime() - CONSOLIDATE_PRUNE_MIN_AGE_DAYS * 24 * 60 * 60 * 1000);
@@ -853,7 +1077,7 @@ function stageDecayPrune(db, dryRun) {
     }
     return { candidates, pruned, failed };
 }
-async function runConsolidation(db, llm, embedFn, dryRun = false, skipReflection = false, stateDir, domainOptions) {
+async function runConsolidation(db, llm, embedFn, dryRun = false, skipReflection = false, stateDir, domainOptions, supersessionOptions) {
     const start = new Date();
     const report = {
         started_at: start.toISOString(),
@@ -924,6 +1148,8 @@ async function runConsolidation(db, llm, embedFn, dryRun = false, skipReflection
         report.stages.links = await stageLinks(db, precheck.newMemories, embedFn, dryRun, llm, budget);
         // Stage 3.5: Hub Detection — boost highly-connected memories
         report.stages.hub_boost = stageHubBoost(db, dryRun);
+        // Stage 3.7: Supersession Detection (#191 Phase B)
+        report.stages.supersession = await stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, supersessionOptions);
         // Stage 4: Decay & Prune
         report.stages.decay_prune = stageDecayPrune(db, dryRun);
     }

package/dist/db.js

@@ -335,6 +335,32 @@ const MIGRATIONS = [
             }
         },
     },
+    {
+        version: 9,
+        name: "add_dedup_log",
+        up: (db) => {
+            // `hicortex dedup` (#100) audit trail. Every merged-away loser gets a
+            // row here BEFORE it is deleted, keyed by loser_id so a loser can only
+            // be logged once (defensive — the CLI never re-merges a deleted id).
+            // `source_session` is the loser's OWN source_session value (may be
+            // NULL): it is CRITICAL that /distill's dedup prechecks in
+            // mcp-server.ts also consult this table, because a deleted loser may
+            // have carried the ONLY marker for a session — without this table a
+            // `--recapture-window` run could re-ingest content the merge already
+            // consolidated. Sidecar table (not a memories column) since it survives
+            // the row it describes being deleted.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS dedup_log (
+          loser_id TEXT PRIMARY KEY,
+          canonical_id TEXT NOT NULL,
+          source_session TEXT,
+          content_head TEXT,
+          merged_at TIMESTAMP NOT NULL
+        )
+      `);
+            db.exec("CREATE INDEX IF NOT EXISTS idx_dedup_log_source_session ON dedup_log(source_session)");
+        },
+    },
 ];
 /**
  * Run all pending migrations against the database.