@gamaze/hicortex 0.14.3 → 0.15.0

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/mcp-server.js

@@ -65,9 +65,11 @@ const viz_js_1 = require("./viz.js");
 const context_store_js_1 = require("./context-store.js");
 const retrieval = __importStar(require("./retrieval.js"));
 const recall_registry_js_1 = require("./recall-registry.js");
+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
 // ---------------------------------------------------------------------------
@@ -90,6 +92,8 @@ let contextAgents = {};
 // Pushed-recall dedup registry (#192) + options; configured at boot.
 let recallRegistry = new recall_registry_js_1.SessionRecallRegistry();
 let recallIndexOptions = {};
+// Product-owned memory instructions (#192): on unless config says false.
+let memoryInstructionsEnabled = true;
 // Cache detectChunkSize results keyed by "<provider>/<model>@<baseUrl>" so we
 // probe each endpoint once per server boot rather than once per /distill request.
 const chunkSizeCache = new Map();
@@ -493,6 +497,7 @@ async function startServer(options = {}) {
         maxItems: savedConfig?.recallMaxItems,
         minPromptLength: savedConfig?.recallMinPromptChars,
     };
+    memoryInstructionsEnabled = savedConfig?.memoryInstructions !== false;
     if (resolvedAgents.dropped.length > 0) {
         console.warn(`[hicortex] Ignoring invalid contextAgents entries: ${resolvedAgents.dropped.join(", ")} ` +
             `(keys must match ^[a-z0-9][a-z0-9_-]*$; modes must be override|global|off)`);
@@ -727,6 +732,13 @@ async function startServer(options = {}) {
     app.get("/context", (req, res) => {
         try {
             const r = (0, context_store_js_1.handleContextGet)((0, node_path_1.join)(stateDir, "context"), contextClients, req.query, contextAgents);
+            // #192: product-owned memory instructions ride as a synthetic read-only
+            // `memory` section (config memoryInstructions !== false; agent mode
+            // "off" respected inside the helper). Every harness renders it via the
+            // shared section renderer — zero client changes.
+            if (r.status === 200) {
+                (0, memory_instructions_js_1.injectMemorySection)(r.body, memoryInstructionsEnabled);
+            }
             res.status(r.status).json(r.body);
         }
         catch (err) {
@@ -735,6 +747,12 @@ async function startServer(options = {}) {
     });
     app.put("/context", (req, res) => {
         try {
+            // Reserved product section: never writable, loud error (no silent skip).
+            const putSections = req.body?.sections;
+            if (putSections && Object.keys(putSections).some((n) => (0, memory_instructions_js_1.isReservedSectionName)(n))) {
+                res.status(400).json({ error: `Section name '${memory_instructions_js_1.MEMORY_SECTION_NAME}' is reserved for the product-owned memory instructions (config memoryInstructions to disable them)` });
+                return;
+            }
             const r = (0, context_store_js_1.handleContextPut)((0, node_path_1.join)(stateDir, "context"), req.body, req.query, contextAgents);
             if (r.warn)
                 console.warn(`[hicortex] ${r.warn}`);
@@ -773,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/memory-instructions.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Product-owned memory instructions (#192, owner decision 28.07.2026).
+ *
+ * The instructions for HOW agents use Hicortex are shipped BY the product,
+ * versioned with the server, and injected as a synthetic read-only `memory`
+ * section in the GET /context response. Rationale ("enforced, built-in"):
+ *   - Harness personas (SOUL.md etc.) carry ZERO hicortex content — mechanics
+ *     described there rot silently when the product changes (field evidence:
+ *     stale "captured via hooks" sentences; an agent shell-spelunking its own
+ *     plugin infrastructure when told "the plugin was updated").
+ *   - User context files (user.md / rules.md) stay purely personal — norms the
+ *     product depends on must not live in user-editable files (same principle
+ *     as the built-in citation norm, 0.14.1).
+ *   - Because every harness already renders `## Context` sections through the
+ *     shared gate/render path, a synthetic section ships fleet-wide with zero
+ *     client changes — including plugins that predate this feature.
+ *
+ * The section name is RESERVED: PUT /context rejects it, and the synthetic
+ * text overrides any user file of the same name (enforced means enforced).
+ * Off-switch: config `memoryInstructions: false`.
+ */
+export declare const MEMORY_SECTION_NAME = "memory";
+/** The product-authored instruction text. Keep compact (~120 tokens): it is
+ *  injected once per session into every agent on the fleet. */
+export declare function renderMemoryInstructions(): string;
+/** True for the reserved product section name (case-insensitive guard —
+ *  section names are lowercase by allowlist, but be safe). */
+export declare function isReservedSectionName(name: unknown): boolean;
+/**
+ * Inject the synthetic section into a successful GET /context body.
+ * Pure: returns the same body object with sections.memory set. Skips agent
+ * mode "off" (operator explicitly silenced context for that agent) and
+ * non-object bodies (error shapes). Overrides a user file named memory.md.
+ */
+export declare function injectMemorySection<T extends {
+    sections?: Record<string, string>;
+    mode?: string;
+}>(body: T, enabled: boolean): T;

package/dist/memory-instructions.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Product-owned memory instructions (#192, owner decision 28.07.2026).
+ *
+ * The instructions for HOW agents use Hicortex are shipped BY the product,
+ * versioned with the server, and injected as a synthetic read-only `memory`
+ * section in the GET /context response. Rationale ("enforced, built-in"):
+ *   - Harness personas (SOUL.md etc.) carry ZERO hicortex content — mechanics
+ *     described there rot silently when the product changes (field evidence:
+ *     stale "captured via hooks" sentences; an agent shell-spelunking its own
+ *     plugin infrastructure when told "the plugin was updated").
+ *   - User context files (user.md / rules.md) stay purely personal — norms the
+ *     product depends on must not live in user-editable files (same principle
+ *     as the built-in citation norm, 0.14.1).
+ *   - Because every harness already renders `## Context` sections through the
+ *     shared gate/render path, a synthetic section ships fleet-wide with zero
+ *     client changes — including plugins that predate this feature.
+ *
+ * The section name is RESERVED: PUT /context rejects it, and the synthetic
+ * text overrides any user file of the same name (enforced means enforced).
+ * Off-switch: config `memoryInstructions: false`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEMORY_SECTION_NAME = void 0;
+exports.renderMemoryInstructions = renderMemoryInstructions;
+exports.isReservedSectionName = isReservedSectionName;
+exports.injectMemorySection = injectMemorySection;
+exports.MEMORY_SECTION_NAME = "memory";
+/** The product-authored instruction text. Keep compact (~120 tokens): it is
+ *  injected once per session into every agent on the fleet. */
+function renderMemoryInstructions() {
+    return [
+        "Your long-term memory is Hicortex — shared across all agents and sessions.",
+        "- A `## Memory recall (auto)` index may arrive with prompts: it is a MENU, not content. Fetch a full memory with `hicortex_get(id)` only when the entry is relevant to your current task.",
+        "- Recall before assuming: `hicortex_search` for prior decisions/facts/preferences, `hicortex_recent` to catch up on a project.",
+        "- Cite any memory you rely on (id, date); on conflicts, newer memories supersede older.",
+        "- Capture is automatic (nightly). Do not manually ingest routine content — `hicortex_ingest` is for explicitly requested learnings only.",
+        "- Never inspect, test, or modify memory/plugin/gateway infrastructure (configs, services, tokens). If a memory tool seems missing or broken, say so and stop.",
+    ].join("\n");
+}
+/** True for the reserved product section name (case-insensitive guard —
+ *  section names are lowercase by allowlist, but be safe). */
+function isReservedSectionName(name) {
+    return typeof name === "string" && name.trim().toLowerCase() === exports.MEMORY_SECTION_NAME;
+}
+/**
+ * Inject the synthetic section into a successful GET /context body.
+ * Pure: returns the same body object with sections.memory set. Skips agent
+ * mode "off" (operator explicitly silenced context for that agent) and
+ * non-object bodies (error shapes). Overrides a user file named memory.md.
+ */
+function injectMemorySection(body, enabled) {
+    if (!enabled)
+        return body;
+    if (!body || typeof body !== "object")
+        return body;
+    if (body.mode === "off")
+        return body;
+    if (!body.sections || typeof body.sections !== "object")
+        return body;
+    body.sections[exports.MEMORY_SECTION_NAME] = renderMemoryInstructions();
+    return body;
+}

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)` : ""));

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.
  */