@gamaze/hicortex 0.14.4 → 0.15.1

package/dist/eval/run-eval.js

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * #191 mechanical audit baseline — orchestrates every section (D1 duplicate
+ * rate, D4 decay/prune/no-fit + #192 adoption, D6 link-graph health, the
+ * reflection census) into one markdown report.
+ *
+ * Read-only end to end: opens the snapshot via eval-db.ts (`openSnapshot`,
+ * never `initDb()`), never writes to the DB. Not wired into `cli.ts` — this
+ * is an internal measurement tool, run via the `eval` npm script:
+ *
+ *   npm run eval -- <snapshot.db> [report.md]
+ *
+ * `state.json` is expected alongside the snapshot DB (same directory) for
+ * the `domainCursor`/`relinkCursor` watermarks. Report path defaults to
+ * `eval-report.md` next to the DB.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const eval_db_js_1 = require("./eval-db.js");
+const dups_js_1 = require("./dups.js");
+const decay_eval_js_1 = require("./decay-eval.js");
+const graph_eval_js_1 = require("./graph-eval.js");
+const reflection_census_js_1 = require("./reflection-census.js");
+const retrieval_js_1 = require("../retrieval.js");
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+function pct(n) {
+    return `${(n * 100).toFixed(1)}%`;
+}
+function round(n, places = 4) {
+    const f = 10 ** places;
+    return Math.round(n * f) / f;
+}
+/** Extract the leading number from a bucket label (e.g. "[0.2, 0.3)" -> 0.2) so buckets render in ascending order. */
+function bucketSortKey(label) {
+    const match = label.match(/-?\d+(\.\d+)?/);
+    return match ? Number(match[0]) : Number.POSITIVE_INFINITY;
+}
+function histTable(h) {
+    const entries = Object.entries(h).sort((a, b) => bucketSortKey(a[0]) - bucketSortKey(b[0]));
+    if (entries.length === 0)
+        return "_(no data)_\n";
+    return entries.map(([bucket, count]) => `| ${bucket} | ${count} |`).join("\n") + "\n";
+}
+// ---------------------------------------------------------------------------
+// Report sections
+// ---------------------------------------------------------------------------
+function renderDups(d) {
+    const lines = [];
+    lines.push("## D1 — Duplicate rate\n");
+    lines.push(`Top-${d.knnK} vector KNN per memory (${d.totalMemories} memories), pairs kept at cosine >= 0.90 and clustered per threshold (union-find). "Excess" = rows that would disappear if every cluster merged to one.\n`);
+    lines.push("| Threshold | Clusters | Excess (rows) |");
+    lines.push("|---|---|---|");
+    for (const t of d.thresholds) {
+        lines.push(`| ${t.threshold} | ${t.clusterCount} | ${t.excess} |`);
+    }
+    lines.push("");
+    lines.push(`**Pair attribution** (over all ${d.pairAttribution.totalPairs} pairs at/above the lowest threshold, 0.90): ` +
+        `${d.pairAttribution.recoveryReingest} recovery/re-ingest-suspect (${pct(d.pairAttribution.totalPairs > 0 ? d.pairAttribution.recoveryReingest / d.pairAttribution.totalPairs : 0)}), ${d.pairAttribution.organic} organic (${pct(d.pairAttribution.totalPairs > 0 ? d.pairAttribution.organic / d.pairAttribution.totalPairs : 0)}).\n`);
+    lines.push(`### Top ${d.topClusters.length} clusters (0.90 threshold, largest first)\n`);
+    d.topClusters.forEach((cluster, i) => {
+        const mismatch = cluster.metadataMismatch;
+        const mismatchFlags = [
+            mismatch.projectMismatch ? "project" : null,
+            mismatch.privacyMismatch ? "privacy" : null,
+            mismatch.sourceAgentMismatch ? "source_agent" : null,
+        ].filter(Boolean);
+        lines.push(`**Cluster ${i + 1}** — size ${cluster.size}, attribution: ${cluster.attribution.recoveryReingest} recovery-pair(s) / ${cluster.attribution.organic} organic-pair(s)` +
+            (mismatchFlags.length > 0 ? `, metadata mismatch: ${mismatchFlags.join(", ")}` : ", metadata consistent"));
+        for (const m of cluster.members) {
+            lines.push(`  - \`${m.id.slice(0, 8)}\` ${m.created_at} — ${m.preview.replace(/\n/g, " ")}`);
+        }
+        lines.push("");
+    });
+    return lines.join("\n");
+}
+function renderDecay(backlog, prune, structural, adoption) {
+    const lines = [];
+    lines.push("## D4 — Decay / Prune / No-fit lifecycle + #192 adoption\n");
+    lines.push("### Domain classification backlog\n");
+    lines.push(`${backlog.nullDomainTotal} memories have NULL domain (of ${backlog.maxRowid} max rowid). Partitioned by ` +
+        `\`domainCursor\` (${backlog.domainCursor ?? "unset — classify-domains never run"}), documented in ` +
+        `classify-domains.ts as the last fully-committed rowid:\n`);
+    lines.push(`- **Never-classified backlog** (rowid > cursor): ${backlog.neverClassifiedBacklog}`);
+    lines.push(`- **Classified but no fitting domain** (rowid <= cursor, no-fit path): ${backlog.classifiedButEmpty}\n`);
+    lines.push("### Prune dry-run (real production predicate: `stageDecayPrune`, `dryRun: true`)\n");
+    lines.push(`Decay clock configured to \`decayHalfLifeDays: ${prune.decayHalfLifeDaysUsed}\` (bedrock has no override — this is the shipped default) before running.\n`);
+    lines.push(`- Candidates (would prune today): **${prune.candidates}**`);
+    lines.push(`- Pruned: ${prune.pruned} (0 expected — dry run)`);
+    lines.push(`- Failed: ${prune.failed}\n`);
+    lines.push("### Structural strength — who can EVER prune\n");
+    lines.push(`A memory can only ever cross the prune floor (effective strength < 0.01) if its asymptote is below that floor: ` +
+        `\`base_strength < sqrt(0.1) ≈ ${round(structural.everPrunableCeiling, 4)}\` (floor = base_strength × importance × 0.1, ` +
+        `importance defaults to base_strength — independent of access/link hardening, which only slows the approach).\n`);
+    lines.push(`**Ever-prunable: ${structural.everPrunableCount} / ${structural.totalMemories} (${pct(structural.totalMemories > 0 ? structural.everPrunableCount / structural.totalMemories : 0)})** — everyone else has a strength floor that never drops low enough to prune, no matter how long it goes unaccessed.\n`);
+    for (const [label, hist] of [
+        ["Effective strength now", structural.effectiveStrengthNowHistogram],
+        ["Simulated +180 days (no further access)", structural.effectiveStrengthAt180dHistogram],
+        ["Simulated +365 days (no further access)", structural.effectiveStrengthAt365dHistogram],
+        ["Asymptotic floor (never, base_strength² × 0.1)", structural.effectiveStrengthNeverHistogram],
+    ]) {
+        lines.push(`**${label}**\n`);
+        lines.push("| Bucket | Count |");
+        lines.push("|---|---|");
+        lines.push(histTable(hist));
+    }
+    lines.push("### Adoption (#192 shown_count / access_count)\n");
+    lines.push("`shown_count` (migration v8) was deployed ~2 days before this snapshot — near-zero shown counts reflect the " +
+        "feature's youth as much as its effectiveness; read this section as a baseline to compare against, not a verdict.\n");
+    lines.push(`- Total shown (sum): ${adoption.totalShown}, total access (sum): ${adoption.totalAccess}`);
+    lines.push(`- Uses per showing (overall): ${adoption.usesPerShowingOverall !== null ? round(adoption.usesPerShowingOverall) : "n/a (nothing shown yet)"}`);
+    lines.push(`- Cold (shown=0 AND access=0): ${adoption.coldShare.coldCount} / ${adoption.coldShare.total} (${pct(adoption.coldShare.share)})\n`);
+    lines.push("**shown_count distribution**\n\n| Bucket | Count |\n|---|---|\n" + histTable(adoption.shownCountHistogram));
+    lines.push("**access_count distribution**\n\n| Bucket | Count |\n|---|---|\n" + histTable(adoption.accessCountHistogram));
+    lines.push("**Uses per showing by source_agent** (agents with at least one showing)\n");
+    lines.push("| source_agent | shown | access | ratio |");
+    lines.push("|---|---|---|---|");
+    const byAgent = Object.entries(adoption.usesPerShowingBySourceAgent)
+        .filter(([, v]) => v.shown > 0 || v.access > 0)
+        .sort((a, b) => b[1].shown - a[1].shown);
+    for (const [agent, v] of byAgent) {
+        lines.push(`| ${agent} | ${v.shown} | ${v.access} | ${v.ratio !== null ? round(v.ratio) : "n/a"} |`);
+    }
+    lines.push("");
+    lines.push("**Exposure age profile** — are new memories getting shown?\n");
+    lines.push("| Age bucket | Total | Ever shown | Share shown |");
+    lines.push("|---|---|---|---|");
+    for (const b of adoption.exposureAgeProfile) {
+        lines.push(`| ${b.bucket} | ${b.total} | ${b.everShown} | ${pct(b.shareShown)} |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function renderGraph(g) {
+    const lines = [];
+    lines.push("## D6 — Link-graph health\n");
+    lines.push(`Total links: **${g.totalLinks}**\n`);
+    lines.push("| Relationship | Count |");
+    lines.push("|---|---|");
+    for (const [rel, count] of Object.entries(g.byRelationship)) {
+        lines.push(`| ${rel} | ${count} |`);
+    }
+    lines.push("");
+    lines.push(`### Degree distribution (${g.degree.memoriesWithLinks} / ${g.degree.totalMemories} memories have at least one link)\n`);
+    lines.push("| Degree bucket | Count |");
+    lines.push("|---|---|");
+    lines.push(histTable(g.degree.degreeHistogram));
+    lines.push(`### Top ${g.degree.topHubs.length} hubs\n`);
+    lines.push("| id | degree | project | domain | preview |");
+    lines.push("|---|---|---|---|---|");
+    for (const h of g.degree.topHubs) {
+        lines.push(`| \`${h.id.slice(0, 8)}\` | ${h.degree} | ${h.project ?? "-"} | ${h.domain ?? "-"} | ${h.preview.replace(/\|/g, "/")} |`);
+    }
+    lines.push("");
+    lines.push(`### Cosine drift (stored \`memory_links.strength\` vs recomputed, ${g.drift.sampleSize}-link random sample` +
+        (g.drift.skippedMissingEmbedding > 0 ? `, ${g.drift.skippedMissingEmbedding} skipped for missing embeddings` : "") +
+        ")\n");
+    lines.push(`Mean |drift|: ${round(g.drift.meanAbsDrift, 8)}, max |drift|: ${round(g.drift.maxAbsDrift, 8)} ` +
+        "(float32 rounding-noise scale (~1e-7) counts as zero drift — strength was set from the same embeddings at link-creation time, so no staleness is expected).\n");
+    lines.push("| |drift| bucket | Count |");
+    lines.push("|---|---|");
+    lines.push(histTable(g.drift.driftHistogram));
+    lines.push(`### Dup-noise links (endpoints >= ${g.dupNoise.threshold} cosine, measured over ${g.dupNoise.measured} links with both embeddings)\n`);
+    lines.push(`${g.dupNoise.count} / ${g.dupNoise.measured} (${pct(g.dupNoise.share)}) of links connect near-duplicate memories.\n`);
+    lines.push(`### Relink migration partition (\`relinkCursor\`: ${g.relinkCursor ?? "unset — relink never run"})\n`);
+    lines.push("| Partition | Links | Dup-noise share |");
+    lines.push("|---|---|---|");
+    lines.push(`| Relinked (source rowid <= cursor) | ${g.relinkedPartition.linkCount} | ${pct(g.relinkedPartition.dupNoiseShare)} |`);
+    lines.push(`| Not yet relinked (source rowid > cursor) | ${g.notYetRelinkedPartition.linkCount} | ${pct(g.notYetRelinkedPartition.dupNoiseShare)} |`);
+    lines.push("");
+    return lines.join("\n");
+}
+function renderReflection(r) {
+    const lines = [];
+    lines.push("## Reflection census\n");
+    lines.push(`Lessons: ${r.totalLessons}, episodes: ${r.totalEpisodes}, yield ratio (lessons/episodes): ${r.yieldRatio !== null ? round(r.yieldRatio) : "n/a"}\n`);
+    lines.push("_Not a quality read — actionable-vs-noise sampling is deferred Phase-A grading work._\n");
+    if (r.lessonsByDate.length > 0) {
+        lines.push("| Date | Lessons |");
+        lines.push("|---|---|");
+        for (const row of r.lessonsByDate) {
+            lines.push(`| ${row.date} | ${row.count} |`);
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function renderPhaseB(dups, prune, structural, backlog, graph, adoption) {
+    const lines = [];
+    lines.push("## Phase-B decision inputs\n");
+    lines.push("**1. Merge-threshold curve (dup excess at each cosine)**\n");
+    for (const t of dups.thresholds) {
+        lines.push(`- ${t.threshold}: ${t.clusterCount} clusters, ${t.excess} excess rows`);
+    }
+    lines.push("");
+    lines.push("**2. Prune posture — inert by design or miscalibration?**\n");
+    lines.push(`- Dry-run candidates today: ${prune.candidates} (half-life ${prune.decayHalfLifeDaysUsed}d)`);
+    lines.push(`- Ever-prunable ceiling: ${structural.everPrunableCount} / ${structural.totalMemories} (${pct(structural.totalMemories > 0 ? structural.everPrunableCount / structural.totalMemories : 0)}) memories can EVER cross the floor regardless of age`);
+    lines.push(`- If the current trend holds, compare the now/+180d/+365d histograms above for how many additional memories drift into low-strength bands`);
+    lines.push("");
+    lines.push("**3. Classification backlog size**\n");
+    lines.push(`- ${backlog.neverClassifiedBacklog} never-classified (beyond domainCursor), ${backlog.classifiedButEmpty} classified-but-empty (no-fit), of ${backlog.nullDomainTotal} total NULL-domain`);
+    lines.push("");
+    lines.push("**4. Link-threshold pile-up evidence**\n");
+    lines.push(`- ${graph.dupNoise.count} / ${graph.dupNoise.measured} links (${pct(graph.dupNoise.share)}) connect near-duplicate memories (>= ${graph.dupNoise.threshold} cosine)`);
+    lines.push(`- Relinked partition dup-noise share: ${pct(graph.relinkedPartition.dupNoiseShare)} vs not-yet-relinked: ${pct(graph.notYetRelinkedPartition.dupNoiseShare)}`);
+    lines.push("");
+    lines.push("**5. Adoption snapshot**\n");
+    lines.push(`- Cold (never shown, never accessed): ${adoption.coldShare.coldCount} / ${adoption.coldShare.total} (${pct(adoption.coldShare.share)})`);
+    lines.push(`- Uses per showing overall: ${adoption.usesPerShowingOverall !== null ? round(adoption.usesPerShowingOverall) : "n/a"} — CAVEAT: shown_count is ~2 days old at snapshot time, read directionally only`);
+    lines.push("");
+    return lines.join("\n");
+}
+function renderReport(input) {
+    const parts = [];
+    parts.push("# Hicortex Mechanical Audit Baseline (#191)\n");
+    parts.push(`Snapshot: \`${input.dbPath}\`  \nGenerated: ${input.generatedAt}  \nRead-only, zero LLM, zero human grading — mechanical measurement only.\n`);
+    parts.push(renderDups(input.dups));
+    parts.push(renderDecay(input.domainBacklog, input.pruneDryRun, input.structural, input.adoption));
+    parts.push(renderGraph(input.graph));
+    parts.push(renderReflection(input.reflection));
+    parts.push(renderPhaseB(input.dups, input.pruneDryRun, input.structural, input.domainBacklog, input.graph, input.adoption));
+    return parts.join("\n");
+}
+// ---------------------------------------------------------------------------
+// CLI entry
+// ---------------------------------------------------------------------------
+function main() {
+    const [, , dbPathArg, reportPathArg] = process.argv;
+    if (!dbPathArg) {
+        console.error("Usage: run-eval.js <snapshot.db> [report.md]");
+        process.exitCode = 1;
+        return;
+    }
+    const dbPath = dbPathArg;
+    const stateDir = (0, node_path_1.dirname)(dbPath);
+    const reportPath = reportPathArg ?? (0, node_path_1.join)(stateDir, "eval-report.md");
+    const db = (0, eval_db_js_1.openSnapshot)(dbPath);
+    try {
+        console.log("[eval] D1 duplicate audit...");
+        const dups = (0, dups_js_1.runDupAudit)(db);
+        console.log("[eval] D4 domain backlog...");
+        const domainBacklog = (0, decay_eval_js_1.runDomainBacklogAudit)(db, stateDir);
+        console.log("[eval] D4 prune dry-run...");
+        const pruneDryRun = (0, decay_eval_js_1.runPruneDryRun)(db, retrieval_js_1.DEFAULT_DECAY_HALF_LIFE_DAYS);
+        console.log("[eval] D4 structural strength stats...");
+        const structural = (0, decay_eval_js_1.runStructuralStrengthStats)(db);
+        console.log("[eval] D4 adoption stats...");
+        const adoption = (0, decay_eval_js_1.runAdoptionStats)(db);
+        console.log("[eval] D6 link-graph audit...");
+        const graph = (0, graph_eval_js_1.runGraphAudit)(db, stateDir);
+        console.log("[eval] reflection census...");
+        const reflection = (0, reflection_census_js_1.runReflectionCensus)(db);
+        const report = renderReport({
+            dbPath,
+            generatedAt: new Date().toISOString(),
+            dups,
+            domainBacklog,
+            pruneDryRun,
+            structural,
+            adoption,
+            graph,
+            reflection,
+        });
+        (0, node_fs_1.writeFileSync)(reportPath, report, "utf-8");
+        console.log(`[eval] report written to ${reportPath}`);
+    }
+    finally {
+        db.close();
+    }
+}
+main();

package/dist/init.js

@@ -1296,6 +1296,11 @@ async function runInit(options = {}) {
         console.log(`  ✓ Removed old static lessons block from ${claudeMdPath} — lessons now injected at session start`);
     }
     console.log("\n✓ Hicortex setup complete!\n");
+    // Telemetry disclosure at install time (informed consent, best practice):
+    // opt-out telemetry is only acceptable if the user is TOLD about it.
+    console.log("Anonymous usage telemetry (aggregate counts only, no content) is on by default —");
+    console.log("see exactly what is sent with `hicortex telemetry`; to opt out, add");
+    console.log('"telemetry": false to ~/.hicortex/config.json or set HICORTEX_TELEMETRY=off.\n');
     console.log("Next steps:");
     console.log("  1. Restart Claude Code to pick up the new MCP server and SessionStart hook");
     if (d.hermesFound) {
@@ -1461,6 +1466,11 @@ async function runClientInit(serverUrl, agentName) {
         setupHermes(serverUrl, authToken);
     }
     console.log("\n✓ Hicortex client setup complete!\n");
+    // Telemetry disclosure at install time (informed consent, best practice):
+    // opt-out telemetry is only acceptable if the user is TOLD about it.
+    console.log("Anonymous usage telemetry (aggregate counts only, no content) is on by default —");
+    console.log("see exactly what is sent with `hicortex telemetry`; to opt out, add");
+    console.log('"telemetry": false to ~/.hicortex/config.json or set HICORTEX_TELEMETRY=off.\n');
     console.log("How it works:");
     console.log("  • MCP tools (search, context, ingest) talk to the remote server");
     console.log("  • Nightly pipeline denoises CC transcripts, POSTs to server for distillation");

package/dist/mcp-server.js

@@ -69,6 +69,7 @@ const memory_instructions_js_1 = require("./memory-instructions.js");
 const recall_index_js_1 = require("./recall-index.js");
 const seed_lesson_js_1 = require("./seed-lesson.js");
 const distiller_js_1 = require("./distiller.js");
+const dedup_js_1 = require("./dedup.js");
 // ---------------------------------------------------------------------------
 // Server state
 // ---------------------------------------------------------------------------
@@ -790,30 +791,31 @@ async function startServer(options = {}) {
             res.status(400).json({ error: "Provide either 'text' (string) or 'messages' (array)" });
             return;
         }
-        // Escape LIKE wildcards — Hermes ids contain "_" (e.g. 20260701_045744_...).
-        const escapeLike = (s) => s.replace(/[\\%_]/g, (m) => "\\" + m);
         // Segment-exact dedup (#189): an incremental capture POST carries
         // segment_id "<start>-<end>[.pN]". Skip iff THIS exact segment's chunks are
         // already stored (keys "<sid>#<segment_id>#<i>"). This is what lets a failed
         // segment be safely retried with the same id, and a legacy session-level row
         // (key "<sid>#<i>", no segment) does NOT match — so the #189 recovery
         // re-ingest is never blocked by night-1's whole-session rows.
+        // ALSO consults dedup_log (#100): a merged-away loser's source_session
+        // marker survives there after the `memories` row is deleted, so a
+        // `hicortex dedup --apply` merge can't be undone by a retried/recaptured
+        // segment silently re-ingesting the same content.
         if (session_id && segment_id) {
-            const likePrefix = `${escapeLike(session_id)}#${escapeLike(segment_id)}#%`;
-            const existing = db.prepare("SELECT COUNT(*) as c FROM memories WHERE source_session LIKE ? ESCAPE '\\'").get(likePrefix);
-            if (existing.c > 0) {
-                res.status(200).json({ skipped: true, existing_count: existing.c });
+            const existingCount = (0, dedup_js_1.countExistingSegment)(db, session_id, segment_id);
+            if (existingCount > 0) {
+                res.status(200).json({ skipped: true, existing_count: existingCount });
                 return;
             }
         }
         // Session-level dedup: when session_id is present and this is a whole-session
         // POST (no segment_id — legacy ≤0.13.1 clients), skip if any chunk of this
-        // session is already stored. Unchanged: legacy clients keep exact behaviour.
+        // session is already stored (memories OR dedup_log — see above).
+        // Unchanged: legacy clients keep exact behaviour.
         if (session_id && !segment_id) {
-            const likePrefix = `${escapeLike(session_id)}#%`;
-            const existing = db.prepare("SELECT COUNT(*) as c FROM memories WHERE source_session = ? OR source_session LIKE ? ESCAPE '\\'").get(session_id, likePrefix);
-            if (existing.c > 0) {
-                res.status(200).json({ skipped: true, existing_count: existing.c });
+            const existingCount = (0, dedup_js_1.countExistingSession)(db, session_id);
+            if (existingCount > 0) {
+                res.status(200).json({ skipped: true, existing_count: existingCount });
                 return;
             }
         }

package/dist/nightly.js

@@ -390,6 +390,10 @@ async function runNightly(options = {}) {
                     domains: cfgDomains,
                     contentDomainsReady,
                     weakPrimaryFloor: (0, nofit_js_1.resolveWeakPrimaryFloor)(savedConfig),
+                }, {
+                    minSimilarity: savedConfig?.supersessionMinSimilarity,
+                    maxCalls: savedConfig?.supersessionMaxCalls,
+                    penalty: savedConfig?.supersessionPenalty,
                 });
                 console.log(`[hicortex] Consolidation ${report.status} in ${report.elapsed_seconds}s` +
                     (report.stages.reflection ? ` (${report.stages.reflection.lessons_generated} lessons)` : ""));
@@ -419,15 +423,28 @@ async function runNightly(options = {}) {
                 ocBatches.length > 0 && "oc",
             ].filter(Boolean);
             const agentType = kinds.length > 1 ? "mixed" : (kinds[0] ?? "cc");
+            // Adoption aggregates (0.15.1): corpus-wide exposure vs use. uses/shown
+            // is the recall-quality signal; cold is the never-touched share.
+            const adoption = db
+                .prepare(`SELECT COALESCE(SUM(shown_count), 0) AS shown,
+                  COALESCE(SUM(access_count), 0) AS uses,
+                  SUM(CASE WHEN COALESCE(shown_count, 0) = 0
+                            AND COALESCE(access_count, 0) = 0 THEN 1 ELSE 0 END) AS cold
+             FROM memories`)
+                .get();
             await (0, telemetry_js_1.sendTelemetry)({
                 id: (0, telemetry_js_1.getTelemetryId)(stateDir),
                 v: VERSION,
+                pv: telemetry_js_1.TELEMETRY_PAYLOAD_VERSION,
                 mode: "server",
                 agent: agentType,
                 mem: storage.countMemories(db),
                 lessons: storage.getLessons(db, 365).length,
                 sessions: batches.length,
                 ok: !hadTransientFailure,
+                shown: adoption.shown,
+                uses: adoption.uses,
+                cold: adoption.cold,
             });
         }
     }
@@ -550,12 +567,14 @@ async function runClientNightly(config, dryRun, stateDir = HICORTEX_HOME, recapt
         await (0, telemetry_js_1.sendTelemetry)({
             id: (0, telemetry_js_1.getTelemetryId)(stateDir),
             v: VERSION,
+            pv: telemetry_js_1.TELEMETRY_PAYLOAD_VERSION,
             mode: "client",
             agent: agentType,
             mem: memoriesIngested,
             lessons: 0, // client doesn't have direct DB access
             sessions: batches.length,
             ok: !hadTransientFailure,
+            // No adoption fields: a client install has no local DB to aggregate.
         });
     }
 }

package/dist/relink.d.ts

@@ -37,7 +37,6 @@
  * Server-mode only: relink needs the local DB. Client installs must run it
  * on the server machine.
  */
-import type Database from "better-sqlite3";
 import type { EmbedFn } from "./retrieval.js";
 export interface RelinkOptions {
     /** Full discovery + would-be counts, zero writes, cursor untouched. */
@@ -87,8 +86,10 @@ export interface RelinkReport {
 /**
  * Read the stored embedding for a memory from memory_vectors.
  * Returns null when the row is missing (caller falls back to re-embedding).
+ * @deprecated moved to storage.ts (shared with consolidate.ts's supersession
+ * stage); re-exported here so existing importers of relink.ts keep working.
  */
-export declare function getStoredEmbedding(db: Database.Database, memoryId: string): Float32Array | null;
+export { getStoredEmbedding } from "./storage.js";
 /**
  * Run the relink pass. Returns a structured report.
  * Throws on unrecoverable errors (client mode, DB write failure) — the cursor

package/dist/relink.js

@@ -72,7 +72,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getStoredEmbedding = getStoredEmbedding;
+exports.getStoredEmbedding = void 0;
 exports.runRelink = runRelink;
 const paths_js_1 = require("./paths.js");
 const node_fs_1 = require("node:fs");
@@ -107,16 +107,11 @@ function loadExistingPairs(db) {
 /**
  * Read the stored embedding for a memory from memory_vectors.
  * Returns null when the row is missing (caller falls back to re-embedding).
+ * @deprecated moved to storage.ts (shared with consolidate.ts's supersession
+ * stage); re-exported here so existing importers of relink.ts keep working.
  */
-function getStoredEmbedding(db, memoryId) {
-    const row = db
-        .prepare("SELECT embedding FROM memory_vectors WHERE id = ?")
-        .get(memoryId);
-    if (!row?.embedding)
-        return null;
-    const buf = row.embedding;
-    return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
-}
+var storage_js_1 = require("./storage.js");
+Object.defineProperty(exports, "getStoredEmbedding", { enumerable: true, get: function () { return storage_js_1.getStoredEmbedding; } });
 /**
  * Run the relink pass. Returns a structured report.
  * Throws on unrecoverable errors (client mode, DB write failure) — the cursor
@@ -193,7 +188,7 @@ async function runRelink(options = {}) {
                 const { __rowid: _ignored, ...memRow } = row;
                 const mem = memRow;
                 try {
-                    let embedding = getStoredEmbedding(db, mem.id);
+                    let embedding = storage.getStoredEmbedding(db, mem.id);
                     if (!embedding) {
                         embedding = await (await getEmbedFn())(mem.content);
                     }

package/dist/seed-lesson.d.ts

@@ -3,5 +3,5 @@
  * Shared between OC plugin and CC MCP server.
  */
 import type Database from "better-sqlite3";
-export declare const SEED_LESSON = "## Lesson: 1% Daily Self-Improvement\n\nSelf-improvement protocol: Review your sessions daily. Scan for mistakes, gaps, user corrections, and friction. Identify 1-2 issues maximum. Apply one targeted fix to your instruction files (AGENT.md, IDENTITY.md, TOOLS.md, SOUL.md, or CLAUDE.md). Never overcorrect \u2014 feedback is guidance, not emergency. One fix per issue. Never rewrite entire systems. Before changing something, ask: is this a real pattern or am I reacting to noise?\n\nThe flywheel: Sessions \u2192 Hicortex captures \u2192 Nightly consolidation \u2192 Lessons generated \u2192 Lessons injected into your context \u2192 You apply one fix \u2192 Better sessions tomorrow.\n\nUse hicortex_lessons to check for new insights. If a lesson has high confidence, apply it. If medium, observe for one more day. If nothing needs fixing today, skip \u2014 that's fine.\n\n**Severity:** critical\n**Confidence:** high\n**Generated:** seed-lesson";
+export declare const SEED_LESSON = "## Lesson: 1% Daily Self-Improvement\n\nSelf-improvement protocol: Review your sessions daily. Scan for mistakes, gaps, user corrections, and friction. Identify 1-2 issues maximum. Apply one targeted fix to your agent instruction files (e.g. SOUL.md / MEMORY.md for Hermes profiles, CLAUDE.md for Claude Code). Never overcorrect \u2014 feedback is guidance, not emergency. One fix per issue. Never rewrite entire systems. Before changing something, ask: is this a real pattern or am I reacting to noise?\n\nThe flywheel: Sessions \u2192 Hicortex captures \u2192 Nightly consolidation \u2192 Lessons generated \u2192 Lessons injected into your context \u2192 You apply one fix \u2192 Better sessions tomorrow.\n\nUse hicortex_lessons to check for new insights. If a lesson has high confidence, apply it. If medium, observe for one more day. If nothing needs fixing today, skip \u2014 that's fine.\n\n**Severity:** critical\n**Confidence:** high\n**Generated:** seed-lesson";
 export declare function injectSeedLesson(database: Database.Database, log?: (msg: string) => void): Promise<void>;

package/dist/seed-lesson.js

@@ -43,7 +43,7 @@ const embedder_js_1 = require("./embedder.js");
 const storage = __importStar(require("./storage.js"));
 exports.SEED_LESSON = `## Lesson: 1% Daily Self-Improvement
 
-Self-improvement protocol: Review your sessions daily. Scan for mistakes, gaps, user corrections, and friction. Identify 1-2 issues maximum. Apply one targeted fix to your instruction files (AGENT.md, IDENTITY.md, TOOLS.md, SOUL.md, or CLAUDE.md). Never overcorrect — feedback is guidance, not emergency. One fix per issue. Never rewrite entire systems. Before changing something, ask: is this a real pattern or am I reacting to noise?
+Self-improvement protocol: Review your sessions daily. Scan for mistakes, gaps, user corrections, and friction. Identify 1-2 issues maximum. Apply one targeted fix to your agent instruction files (e.g. SOUL.md / MEMORY.md for Hermes profiles, CLAUDE.md for Claude Code). Never overcorrect — feedback is guidance, not emergency. One fix per issue. Never rewrite entire systems. Before changing something, ask: is this a real pattern or am I reacting to noise?
 
 The flywheel: Sessions → Hicortex captures → Nightly consolidation → Lessons generated → Lessons injected into your context → You apply one fix → Better sessions tomorrow.
 

package/dist/state.d.ts

@@ -50,6 +50,16 @@ export interface HicortexState {
      * Same discipline as relinkCursor.
      */
     domainCursor?: number;
+    /**
+     * Resume cursor for the nightly's supersession-detection stage (#191 Phase
+     * B) — highest memories.rowid whose decision/correction candidates have
+     * been evaluated (or infra-skipped) this run. Absent/0 = never run. Unlike
+     * relinkCursor/domainCursor (separate resumable CLI commands), this cursor
+     * advances a SMALL amount per night (config `supersessionMaxCalls`, default
+     * 30) as part of the regular nightly — the corpus is back-processed
+     * gradually over many nights.
+     */
+    supersessionCursor?: number;
 }
 /**
  * Load the state file. Returns an empty state if the file is missing

package/dist/storage.d.ts

@@ -89,6 +89,16 @@ export declare function getMemoryTagsWeighted(db: Database.Database, memoryId: s
     tag: string;
     weight: number | null;
 }>;
+/**
+ * Read the stored embedding for a memory from memory_vectors.
+ * Returns null when the row is missing (caller falls back to re-embedding).
+ *
+ * Shared by `hicortex relink` and the nightly's supersession stage
+ * (consolidate.ts) — lives here (not in relink.ts) so consolidate.ts can use
+ * it without importing from relink.ts, which itself imports from
+ * consolidate.ts (BudgetTracker, discoverLinkCandidates).
+ */
+export declare function getStoredEmbedding(db: Database.Database, memoryId: string): Float32Array | null;
 /**
  * Find similar memories by vector distance. Returns memories with distance field.
  */

package/dist/storage.js

@@ -15,6 +15,7 @@ exports.deleteMemory = deleteMemory;
 exports.setMemoryTags = setMemoryTags;
 exports.getMemoryTags = getMemoryTags;
 exports.getMemoryTagsWeighted = getMemoryTagsWeighted;
+exports.getStoredEmbedding = getStoredEmbedding;
 exports.vectorSearch = vectorSearch;
 exports.searchFts = searchFts;
 exports.addLink = addLink;
@@ -115,6 +116,10 @@ const ALLOWED_UPDATE_FIELDS = new Set([
     "base_strength",
     "last_accessed",
     "access_count",
+    // shown_count is normally maintained by touchMemoriesShown (bulk +1 per
+    // recall-index appearance); it's also allowed here so `hicortex dedup`
+    // (#100) can sum a merged cluster's counters onto the canonical row.
+    "shown_count",
     "source_agent",
     "source_session",
     "project",
@@ -239,6 +244,24 @@ function getMemoryTagsWeighted(db, memoryId) {
         .all(memoryId);
     return rows;
 }
+/**
+ * Read the stored embedding for a memory from memory_vectors.
+ * Returns null when the row is missing (caller falls back to re-embedding).
+ *
+ * Shared by `hicortex relink` and the nightly's supersession stage
+ * (consolidate.ts) — lives here (not in relink.ts) so consolidate.ts can use
+ * it without importing from relink.ts, which itself imports from
+ * consolidate.ts (BudgetTracker, discoverLinkCandidates).
+ */
+function getStoredEmbedding(db, memoryId) {
+    const row = db
+        .prepare("SELECT embedding FROM memory_vectors WHERE id = ?")
+        .get(memoryId);
+    if (!row?.embedding)
+        return null;
+    const buf = row.embedding;
+    return new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4);
+}
 // ---------------------------------------------------------------------------
 // Vector search
 // ---------------------------------------------------------------------------

package/dist/telemetry-cli.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `hicortex telemetry` — transparency surface for anonymous usage telemetry.
+ *
+ * Read-only BY DESIGN (owner decision 30.07.2026). It shows the exact payload
+ * and both documented ways to switch telemetry off, but it does not flip the
+ * switch itself: the `telemetry` key is deliberately NOT scaffolded into
+ * config.json, and opting out is a deliberate edit the operator makes. Turning
+ * it off must stay completely possible and completely documented — just not a
+ * one-keystroke default-path action.
+ */
+export declare function runTelemetryCommand(args: string[]): void;