@gamaze/hicortex 0.22.1 → 0.22.2

package/dist/consolidate.js

@@ -467,8 +467,13 @@ async function scoreMemoriesImportance(db, memories, llm, opts = {}) {
     }
     return { scored, failed, skipped_budget: skippedBudget };
 }
-async function stageImportance(db, memories, llm, budget, dryRun, deadline) {
-    return scoreMemoriesImportance(db, memories, llm, { budget, deadline, dryRun });
+async function stageImportance(db, memories, llm, budget, dryRun, deadline, 
+/** #478: pool candidates the paid-gain guard dropped at the stage
+ *  boundary — reported, not scored, so the run's evidence shows the
+ *  promotion/enrichment gains that survived the nightly. */
+guardSkipped = 0) {
+    const r = await scoreMemoriesImportance(db, memories, llm, { budget, deadline, dryRun });
+    return { ...r, guard_skipped: guardSkipped };
 }
 // ---------------------------------------------------------------------------
 // Stage 2.5: Reflection
@@ -639,12 +644,18 @@ async function stageContentDomains(db, domains, llm, budget, embedFn, dryRun, st
     //   - domain NOT IN the current vocabulary (a rename/removal re-files), OR
     //   - no memory_tags rows yet (single-domain memories from feat/content-domains
     //     that have a primary but no tag set — backfill them to multi-tag).
+    // #477: absorbed dedup losers are excluded — the merge clears their tags
+    // and nulls domain before absorbing, so without the predicate every dead
+    // loser re-enters this scope nightly (one classify call + a halving on
+    // evidence no recall can ever see). Conjoined OUTSIDE the parenthesized OR
+    // group so SQL precedence cannot let an OR arm absorb it.
     const placeholders = domains.map(() => "?").join(", ");
     const rows = db
         .prepare(`SELECT id, content, project FROM memories
-       WHERE domain IS NULL
-          OR domain NOT IN (${placeholders})
-          OR id NOT IN (SELECT DISTINCT memory_id FROM memory_tags)`)
+       WHERE COALESCE(status, '') != 'absorbed'
+         AND (domain IS NULL
+              OR domain NOT IN (${placeholders})
+              OR id NOT IN (SELECT DISTINCT memory_id FROM memory_tags))`)
         .all(...domains.map((d) => d.name));
     if (dryRun) {
         return { curated: false, domains: domains.length, classified: 0, reason: `dry_run (${rows.length} would classify)` };
@@ -1664,12 +1675,29 @@ deadline) {
     };
     // Stage 1: Pre-check
     const precheck = stagePrecheck(db, stateDir);
-    // Also check for unscored memories
+    // #478: the importance pool is ROW-AGE bound — young (ingested within
+    // IMPORTANCE_SETTLE_WINDOW_DAYS) ∪ never-scored. The lastConsolidated
+    // watermark no longer defines any part of it: a deferred run's stuck
+    // watermark used to re-settle a growing cohort nightly, and every
+    // re-settle overwrites base_strength outright (erasing gains
+    // stagePromotion had already paid — 5/5 observed erasures). The watermark
+    // cohort (precheck.newMemories) STILL feeds reflection + links below —
+    // their work is batch retry by design; only importance's per-row settling
+    // was mis-bound to the batch marker.
+    const settleCutoff = new Date(Date.now() - CALIBRATION.IMPORTANCE_SETTLE_WINDOW_DAYS * 86_400_000).toISOString();
+    // getMemoriesSince keys on ingested_at only — absorbed rows (invisible to
+    // recall) are filtered here in the same vocabulary getUnscoredMemories
+    // uses in SQL: no LLM call on dead evidence.
+    const young = storage
+        .getMemoriesSince(db, settleCutoff)
+        .filter((m) => m.status !== "absorbed");
+    const youngIds = new Set(young.map((m) => m.id));
+    // Also check for unscored memories (#425 watermark pool) — first settle is
+    // age-independent, so a row used before its first score is never stranded.
     const unscored = storage.getUnscoredMemories(db);
-    const newIds = new Set(precheck.newMemories.map((m) => m.id));
     const scoreMemories = [
-        ...precheck.newMemories,
-        ...unscored.filter((m) => !newIds.has(m.id)),
+        ...young,
+        ...unscored.filter((m) => !youngIds.has(m.id)),
     ];
     // #194 no-fit scope: untagged rows (domain IS NULL) stay in the
     // re-evaluation scope — the decay/re-attempt contract ("re-halves once per
@@ -1678,15 +1706,26 @@ deadline) {
     // never caught because stagePrecheck used to read the AMBIENT (always
     // empty in the suite) state instead of the run's own watermark — threading
     // stateDir (#357) exposed the divergence between test and production.
-    const nofitInScope = db.prepare("SELECT COUNT(*) AS n FROM memories WHERE domain IS NULL").get().n;
-    const skip = scoreMemories.length === 0 && nofitInScope === 0;
+    // #477: absorbed dedup losers (tags cleared, domain NULLed by the merge)
+    // are dead evidence — they must not keep the no-fit scope (and the run)
+    // alive every night. Same predicate spelling as getUnscoredMemories.
+    const nofitInScope = db
+        .prepare("SELECT COUNT(*) AS n FROM memories WHERE domain IS NULL AND COALESCE(status, '') != 'absorbed'")
+        .get().n;
+    // #478: the quiet-night gate is the UNION — watermark cohort OR young OR
+    // unscored OR no-fit scope. A stuck watermark alone must never silence
+    // reflection/links (their pool is the watermark cohort, and their retry
+    // semantics are the reason a deferred run holds the watermark at all).
+    const skip = scoreMemories.length === 0 &&
+        precheck.newMemories.length === 0 &&
+        nofitInScope === 0;
     report.stages.precheck = {
         skip,
         reason: skip
             ? precheck.reason
-            : `${precheck.newMemories.length} new + ${scoreMemories.length - precheck.newMemories.length} unscored memories`,
+            : `${precheck.newMemories.length} new (watermark) + ${young.length} young + ${scoreMemories.length - young.length} unscored memories`,
         new_memory_count: precheck.newMemories.length,
-        unscored_count: scoreMemories.length - precheck.newMemories.length,
+        unscored_count: unscored.length,
     };
     // Strength promotion (#448) — runs in the pre-skip deterministic zone, in
     // the same placement discipline as memory_cap BELOW it: accesses happen on
@@ -1724,7 +1763,27 @@ deadline) {
         // deferred. Deferred stages drain next run (cursors hold below them).
         // Stage 2: Importance Scoring
         if (!deadline?.hit("importance")) {
-            report.stages.importance = await stageImportance(db, scoreMemories, llm, budget, dryRun, deadline);
+            // #478 paid-gain guard — evaluated HERE, at the stage boundary, not at
+            // pool-build time: the pool above was built before this run's
+            // stagePromotion payment, so a row whose FIRST use lands this run
+            // passes a pool-build check and its just-paid gain is overwritten at
+            // the first re-settle. This read sits after promotion by construction
+            // and sees the advanced baseline. Already-scored rows carrying a paid
+            // gain (promotion baseline advanced OR owner corroboration) keep it —
+            // re-settling would stomp base_strength; `hicortex rescore-importance`
+            // remains the wholesale operator re-judge. Never-scored rows
+            // (importance_scored_at IS NULL) are NEVER skipped: first settle
+            // always happens, whatever their use history.
+            const paidGainIds = scoreMemories.length
+                ? new Set(db.prepare(`SELECT id FROM memories
+                WHERE importance_scored_at IS NOT NULL
+                  AND (COALESCE(promotion_last_count, 0) > 0
+                       OR COALESCE(corroboration_count, 0) > 0)
+                  AND id IN (${scoreMemories.map(() => "?").join(", ")})`).all(...scoreMemories.map((m) => m.id))
+                    .map((r) => r.id))
+                : new Set();
+            const settleCandidates = scoreMemories.filter((m) => !paidGainIds.has(m.id));
+            report.stages.importance = await stageImportance(db, settleCandidates, llm, budget, dryRun, deadline, scoreMemories.length - settleCandidates.length);
         }
         // Stage 2.5: Reflection
         if (deadline?.hit("reflection")) {

package/dist/dashboard.d.ts

@@ -23,6 +23,7 @@
 import type express from "express";
 import type Database from "better-sqlite3";
 import { type CaptureHealthRow } from "./capture-health.js";
+import { type MemoryPrecision } from "./recall-precision.js";
 import { type Stage } from "./stages.js";
 /** Corpus-shape snapshot. `adoption` is null in backfilled rows (point-in-time,
  *  can't be reconstructed from created_at). */
@@ -257,6 +258,16 @@ export interface DashboardData {
             last_outcome: string;
         }>;
     };
+    /**
+     * #476 — the Memory Precision card: Level 1 (pushed-index precision
+     * proxies over the recall_pushes/recall_events window) beside Level 2
+     * (recall depth = the uses-per-showing ratio over the SAME window, from
+     * snapshot deltas) + the divergence list. ALWAYS present; edges echoed
+     * like every threshold (the page never hardcodes), and the block measures
+     * ≤ 2 KB against the live 30-day payload. The page degrades to the
+     * pre-#476 recall-card rendering when the block is absent.
+     */
+    memory_precision: MemoryPrecision;
     digest: {
         date: string | null;
         run_at: string | null;

package/dist/dashboard.js

@@ -45,6 +45,7 @@ const recall_index_js_1 = require("./recall-index.js");
 const config_read_js_1 = require("./config-read.js");
 const consolidate_js_1 = require("./consolidate.js");
 const capture_health_js_1 = require("./capture-health.js");
+const recall_precision_js_1 = require("./recall-precision.js");
 const capture_pause_js_1 = require("./capture-pause.js");
 const state_js_1 = require("./state.js");
 const retrieval_js_1 = require("./retrieval.js");
@@ -576,6 +577,14 @@ function handleDashboardData(db, query, config) {
                 by_source_machine: live.by_source_machine,
             },
             capture_health: { ...(0, capture_health_js_1.readCaptureHealth)(db), ...(0, capture_health_js_1.readCaptureHealthWindow)(db) },
+            // #476 Memory Precision: the window aggregation over the precision
+            // event tables + snapshot deltas. Level 2's "latest" is the SAME live
+            // adoption this handler already computed (one definition of corpus
+            // shape — computeDashboardMetrics); readMemoryPrecision owns the rest.
+            memory_precision: (0, recall_precision_js_1.readMemoryPrecision)(db, rangeParam, {
+                shown_sum: live.adoption?.shown_sum ?? 0,
+                used_sum: live.adoption?.used_sum ?? 0,
+            }),
             // #423 phase 3: pauses + presence in one block — one source of truth
             // for the rail's dots, toggles and the capture card's PAUSED badges.
             fleet: {

package/dist/db.js

@@ -668,6 +668,80 @@ const MIGRATIONS = [
             db.exec("UPDATE memories SET promotion_last_count = access_count WHERE promotion_last_count IS NULL");
         },
     },
+    {
+        version: 21,
+        name: "memory_layout",
+        up: (db) => {
+            // #464 — the console field's server-computed placement. One row per
+            // placed memory at one epoch; the CURRENT epoch is MAX(epoch) and the
+            // payload (dashboard.ts handleDashboardField) LEFT JOINs on it. A full
+            // re-projection (`hicortex layout --reproject`) writes a NEW epoch and
+            // drops older ones in the SAME transaction (atomic swap — a mid-write
+            // failure leaves the previous epoch fully intact). Epochs exist so the
+            // whole store moves at once (one announced visual shift), never as a
+            // mix of projections. Idempotent: IF NOT EXISTS (the v18 pattern —
+            // plain CREATE, no ALTER).
+            // Kept after the #464/#475 field revert (#474): nothing reads or writes
+            // this table now — a dormant orphan. Rc databases already applied v21
+            // (user_version 21), so removing it would fork schema versions; it
+            // stays per the append-only migration discipline.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS memory_layout (
+            memory_id TEXT PRIMARY KEY,
+            x REAL NOT NULL,
+            y REAL NOT NULL,
+            epoch INTEGER NOT NULL
+        )
+      `);
+            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_layout_epoch ON memory_layout(epoch)");
+        },
+    },
+    {
+        version: 22,
+        name: "recall_precision_events",
+        up: (db) => {
+            // #476 — the Memory Precision card's event store (Option A, owner
+            // decision 2026-09-19: per-push event rows incl. a ≤256-char prompt
+            // excerpt — the exact-window Level-1 measures + the judge follow-up's
+            // sample frame). Two sidecar tables, the v16 distill_activity pattern:
+            // OPERATIONS telemetry, no memories FK — recall_events.memory_id is
+            // DATA (absorbed memories' history stays queryable; rows outliving
+            // their memory are valid). recall_pushes: one row per NON-skipped
+            // /recall-index call (short-prompt skips and resets record nothing; a
+            // silent turn records its push row with zero events — the silence rate
+            // is computable). recall_events: one kind='shown' row per pushed line
+            // (similarity = cosine vs the PURE prompt embedding, redundancy = max
+            // cosine vs the standing-context basis — both RAW, verdicts computed at
+            // render so recalibration never rewrites history) + one kind='fetch'
+            // row per handleMemoryGet (push_id NULL). Pruned nightly at the
+            // retention horizon (= the longest window, the capture-health
+            // single-constant law). Idempotent: IF NOT EXISTS everywhere.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS recall_pushes (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          ts TEXT NOT NULL,
+          day TEXT NOT NULL,
+          session_id TEXT,
+          prompt_excerpt TEXT
+        )
+      `);
+            db.exec("CREATE INDEX IF NOT EXISTS idx_recall_pushes_day ON recall_pushes(day)");
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS recall_events (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          ts TEXT NOT NULL,
+          day TEXT NOT NULL,
+          push_id INTEGER,
+          memory_id TEXT NOT NULL,
+          similarity REAL,
+          redundancy REAL,
+          kind TEXT NOT NULL
+        )
+      `);
+            db.exec("CREATE INDEX IF NOT EXISTS idx_recall_events_day ON recall_events(day)");
+            db.exec("CREATE INDEX IF NOT EXISTS idx_recall_events_memory_kind ON recall_events(memory_id, kind)");
+        },
+    },
 ];
 /**
  * Run all pending migrations against the database.

package/dist/mcp-server.js

@@ -90,6 +90,7 @@ const dedup_js_1 = require("./dedup.js");
 const reconsolidation_js_1 = require("./reconsolidation.js");
 const redact_js_1 = require("./redact.js");
 const capture_health_js_1 = require("./capture-health.js");
+const recall_precision_js_1 = require("./recall-precision.js");
 const capture_pause_js_1 = require("./capture-pause.js");
 const init_js_1 = require("./init.js");
 // ---------------------------------------------------------------------------
@@ -207,8 +208,10 @@ function createMcpServer() {
         // (incl. the #204 FETCHED marker) is built in ONE place shared with the
         // REST GET /memory path. CC reaches Hicortex through THIS MCP tool;
         // before #207's fix it got a marker-less citation built inline here.
+        // #476: the fetch recorder forwards through the same funnel — exactly
+        // one precision event per fetch, whichever path served it.
         try {
-            const r = (0, recall_index_js_1.formatMemoryGetText)(db, { id });
+            const r = (0, recall_index_js_1.formatMemoryGetText)(db, { id }, { recordFetch: recall_precision_js_1.recordRecallFetch });
             return { content: [{ type: "text", text: r.text }], isError: r.status !== 200 };
         }
         catch (err) {
@@ -1053,6 +1056,22 @@ async function startServer(options = {}) {
     // last_accessed, NOT access_count (that stays reserved for hicortex_get /
     // GET /memory — real use). {reset: true} clears the session's dedup state
     // (SessionStart/compaction).
+    //
+    // #476 Memory Precision: the route also wires the precision seams — the
+    // factory's exposed embedPrompt (the per-request memo: the recorder
+    // measures per-line similarity with ZERO extra embeds), the 24h-TTL
+    // standing-context basis (lessons in /learnings order + identity only when
+    // every known client is served — the redundancy reference), and the
+    // fail-soft recorder. handleRecallIndex owns the fail-soft law: a
+    // recording failure never touches the response.
+    const standingContextBasis = (0, recall_precision_js_1.createStandingContextBasis)({
+        // Lazy getters: identityClients is resolved at boot and stateDir is
+        // assigned before the routes serve, but both land AFTER this provider is
+        // created — read per cache rebuild (a config restart applies at the next
+        // TTL), never captured once.
+        clients: () => identityClients,
+        identityDir: () => (0, node_path_1.join)(stateDir, "identity"),
+    });
     app.post("/recall-index", async (req, res) => {
         if (!db) {
             res.status(503).json({ error: "Server not initialized" });
@@ -1067,22 +1086,30 @@ async function startServer(options = {}) {
         // that searches unblended and touches no centroid state. Extracted so the
         // exact behavior is unit-testable without HTTP (blendQueryVector
         // precedent); this adapter stays thin.
+        const factory = (0, recall_index_js_1.createRecallRetrieveFn)({
+            db,
+            registry: recallRegistry,
+            embedFn: embedder_js_1.embed,
+        });
         const r = await (0, recall_index_js_1.handleRecallIndex)({
             db,
             registry: recallRegistry,
-            retrieveFn: (0, recall_index_js_1.createRecallRetrieveFn)({
-                db,
-                registry: recallRegistry,
-                embedFn: embedder_js_1.embed,
-            }),
+            retrieveFn: factory.retrieveFn,
             options: recallIndexOptions,
+            precision: {
+                promptEmbed: factory.embedPrompt,
+                basis: standingContextBasis,
+                recorder: recall_precision_js_1.recordRecallPush,
+            },
         }, req.body);
         res.status(r.status).json(r.body);
     });
     // REST /memory?id= — fetch one memory's full content (lazy-load counterpart
     // of /recall-index for REST clients: Hermes/OC plugins). Marks it as used.
     // Prefix ids resolve. 0.16.x: the `privacy` query param is accepted but
-    // ignored (column is vestigial, never filtered). Logic in handleMemoryGet.
+    // ignored (column is vestigial, never filtered). Logic in handleMemoryGet;
+    // the #476 fetch recorder rides the same funnel (exactly one event per
+    // fetch, shared with the MCP hicortex_get path).
     app.get("/memory", (req, res) => {
         if (!db) {
             res.status(503).json({ error: "Server not initialized" });
@@ -1090,7 +1117,7 @@ async function startServer(options = {}) {
         }
         warnDeprecatedPrivacyParamIfPresent(req.query, "memory");
         try {
-            const r = (0, recall_index_js_1.handleMemoryGet)(db, { id: req.query.id });
+            const r = (0, recall_index_js_1.handleMemoryGet)(db, { id: req.query.id }, { recordFetch: recall_precision_js_1.recordRecallFetch });
             res.status(r.status).json(r.body);
         }
         catch (err) {

package/dist/nightly.js

@@ -79,6 +79,7 @@ const capture_cursors_js_1 = require("./capture-cursors.js");
 const capture_js_1 = require("./capture.js");
 const run_deadline_js_1 = require("./run-deadline.js");
 const dashboard_js_1 = require("./dashboard.js");
+const recall_precision_js_1 = require("./recall-precision.js");
 const telemetry_js_1 = require("./telemetry.js");
 const init_js_1 = require("./init.js");
 const backup_js_1 = require("./backup.js");
@@ -1071,6 +1072,19 @@ async function runNightly(options = {}) {
                 console.warn(`[hicortex] Dashboard snapshot write failed: ` +
                     `${snapErr instanceof Error ? snapErr.message : String(snapErr)}`);
             }
+            // #476 — recall-precision retention prune (zero-LLM, full nightly only):
+            // both event tables drop rows outside the rolling window whose length IS
+            // the retention constant (the capture-health single-constant law — the
+            // Memory Precision card can never claim a window the store no longer
+            // holds rows for). Own try/catch like the snapshot writer: telemetry
+            // housekeeping must never fail the run.
+            try {
+                (0, recall_precision_js_1.pruneRecallPrecision)(db);
+            }
+            catch (pruneErr) {
+                console.warn(`[hicortex] Recall-precision retention prune failed: ` +
+                    `${pruneErr instanceof Error ? pruneErr.message : String(pruneErr)}`);
+            }
         }
         // Anonymous telemetry (fire-and-forget, full nightly only).
         // Capture-only runs are excluded to avoid inflating install pings.

package/dist/recall-index.d.ts

@@ -51,6 +51,7 @@ import type Database from "better-sqlite3";
 import type { MemorySearchResult } from "./types.js";
 import * as storage from "./storage.js";
 import { SessionRecallRegistry } from "./recall-registry.js";
+import type { RecallPushEntry, RecallFetchRecorder } from "./recall-precision.js";
 export interface RecallIndexOptions {
     /** Minimum measured cosine for vector-only candidates (release-managed
      *  since #408 — calibration.ts RECALL_MIN_SIMILARITY; this field is the
@@ -161,6 +162,16 @@ export interface RecallFilters {
  *  RecallIndexDeps.retrieveFn). Named so the production factory
  *  (createRecallRetrieveFn) and test doubles share one type. */
 export type RecallRetrieveFn = (query: string, limit: number, filters: RecallFilters | undefined, sessionId: string, purePrompt?: boolean) => Promise<MemorySearchResult[]>;
+/** What createRecallRetrieveFn returns (#476): the search closure PLUS the
+ *  per-request prompt-embed memo it already maintained — exposed so the
+ *  precision recorder reuses the SAME embedding (zero extra embeds) instead
+ *  of re-embedding the prompt to measure per-line similarity. */
+export interface RecallRetrieveFactory {
+    retrieveFn: RecallRetrieveFn;
+    /** The single-entry embed memo (keyed on the query text; the factory is
+     *  built per request, so the memo never outlives it). */
+    embedPrompt: (query: string) => Promise<Float32Array>;
+}
 export interface RecallIndexDeps {
     db: Database.Database;
     registry: SessionRecallRegistry;
@@ -176,6 +187,30 @@ export interface RecallIndexDeps {
      *  no breakage. */
     retrieveFn: RecallRetrieveFn;
     options?: RecallIndexOptions;
+    /** #476 Memory Precision seams — OPTIONAL so existing callers (tests,
+     *  library use) keep their exact no-recording behavior. Absent → no event
+     *  rows, the plain exposure write runs as before. mcp-server wires the
+     *  production set (the real recorder, the request-memoized prompt embed,
+     *  the 24h-TTL standing-context basis). Recording is FAIL-SOFT: any error
+     *  is caught here and the recall response (200 + block) is never affected;
+     *  on failure the exposure touch re-runs standalone so shown_count never
+     *  depends on telemetry. */
+    precision?: RecallPrecisionDeps;
+}
+/** The #476 precision-recording seams (see RecallIndexDeps.precision). All
+ *  three are injectable; tests force failures through them. */
+export interface RecallPrecisionDeps {
+    /** The request's memoized pure-prompt embed (createRecallRetrieveFn's
+     *  embedPrompt) — the recorder computes per-line cosines with ZERO extra
+     *  embeds (the perf law). */
+    promptEmbed: (prompt: string) => Promise<Float32Array>;
+    /** Standing-context basis vectors (recall-precision.ts's 24h-TTL cached
+     *  provider; empty array → redundancy NULL, unmeasured). */
+    basis: (db: Database.Database) => Promise<Float32Array[]>;
+    /** The recorder (recall-precision.ts recordRecallPush). Throws on failure —
+     *  this handler catches (fail-soft) and falls back to the plain exposure
+     *  write. */
+    recorder: (db: Database.Database, entry: RecallPushEntry, basis?: Float32Array[]) => void;
 }
 /**
  * The PRODUCTION /recall-index retrieveFn (what mcp-server wires into
@@ -209,7 +244,7 @@ export declare function createRecallRetrieveFn(deps: {
     embedFn: (text: string) => Promise<Float32Array>;
     /** FTS resolution override (tests). Defaults to storage.searchFts. */
     ftsFn?: typeof storage.searchFts;
-}): RecallRetrieveFn;
+}): RecallRetrieveFactory;
 /** Normalize a request-supplied string-list param: array of strings or a CSV
  *  string → string[] | undefined. Anything else (or an empty result) means
  *  "absent" — never a partial guess. Used by `mission_domains` (#203) so it
@@ -220,6 +255,14 @@ export declare function parseStringListParam(v: unknown): string[] | undefined;
  * all behavior lives here so tests exercise it directly.
  */
 export declare function handleRecallIndex(deps: RecallIndexDeps, body: unknown): Promise<RecallIndexResult>;
+/** Optional #476 deps for handleMemoryGet: the fetch-event recorder. Absent
+ *  (old callers, tests) → no recording, byte-identical behavior. mcp-server
+ *  wires recordRecallFetch so BOTH fetch paths (REST GET /memory, MCP
+ *  hicortex_get via formatMemoryGetText) record exactly once — this is the
+ *  ONE funnel. Fail-soft: a recorder error is caught here, never surfaced. */
+export interface MemoryGetDeps {
+    recordFetch: RecallFetchRecorder;
+}
 /**
  * Handle a GET /memory request (lazy-load counterpart of the recall index for
  * REST clients). Thin Express adapter in mcp-server.ts; behavior lives here so
@@ -235,7 +278,7 @@ export declare function handleRecallIndex(deps: RecallIndexDeps, body: unknown):
  */
 export declare function handleMemoryGet(db: Database.Database, query: {
     id?: unknown;
-}): RecallIndexResult;
+}, deps?: MemoryGetDeps): RecallIndexResult;
 /**
  * MCP `hicortex_get` presentation: handleMemoryGet's result framed as the
  * text block the MCP tool returns (provenance header + the SHARED citation +
@@ -249,7 +292,7 @@ export declare function handleMemoryGet(db: Database.Database, query: {
  */
 export declare function formatMemoryGetText(db: Database.Database, query: {
     id?: unknown;
-}): {
+}, deps?: MemoryGetDeps): {
     status: number;
     text: string;
 };

package/dist/recall-index.js

@@ -251,27 +251,34 @@ function createRecallRetrieveFn(deps) {
         }
         return ftsMemo.rows;
     };
-    return async (query, limit, filters, sessionId, purePrompt) => {
-        const { weight, alpha } = (0, retrieval_js_1.getSessionIntent)();
-        const promptEmb = await embedOnce(query);
-        const queryVec = (0, retrieval_js_1.recallQueryVector)(deps.registry, sessionId, promptEmb, {
-            weight,
-            alpha,
-            purePrompt,
-        });
-        return (0, retrieval_js_1.retrieve)(deps.db, deps.embedFn, query, {
-            limit,
-            noStrengthen: true,
-            // #203: project + mission_domains are SOFT affinity (zero-boost
-            // neutral), threaded into computeScore.
-            project: filters?.project,
-            missionDomains: filters?.mission_domains,
-            queryEmbedding: queryVec,
-            // #329: shared per-request FTS list. The recall path never passes
-            // sourceAgent, so the memo is keyed on (query, fetchLimit) only —
-            // exactly the two things retrieve() would pass to searchFts.
-            ftsCandidates: (fetchLimit) => ftsOnce(query, fetchLimit),
-        });
+    return {
+        retrieveFn: async (query, limit, filters, sessionId, purePrompt) => {
+            const { weight, alpha } = (0, retrieval_js_1.getSessionIntent)();
+            const promptEmb = await embedOnce(query);
+            const queryVec = (0, retrieval_js_1.recallQueryVector)(deps.registry, sessionId, promptEmb, {
+                weight,
+                alpha,
+                purePrompt,
+            });
+            return (0, retrieval_js_1.retrieve)(deps.db, deps.embedFn, query, {
+                limit,
+                noStrengthen: true,
+                // #203: project + mission_domains are SOFT affinity (zero-boost
+                // neutral), threaded into computeScore.
+                project: filters?.project,
+                missionDomains: filters?.mission_domains,
+                queryEmbedding: queryVec,
+                // #329: shared per-request FTS list. The recall path never passes
+                // sourceAgent, so the memo is keyed on (query, fetchLimit) only —
+                // exactly the two things retrieve() would pass to searchFts.
+                ftsCandidates: (fetchLimit) => ftsOnce(query, fetchLimit),
+            });
+        },
+        // #476: the memoized prompt embed, EXPOSED so the precision recorder
+        // computes per-line cosines with ZERO additional embeds (the perf law —
+        // the memo semantics are unchanged: one embed per distinct query string
+        // per factory instance).
+        embedPrompt: embedOnce,
     };
 }
 /** Normalize a request-supplied string-list param: array of strings or a CSV
@@ -421,12 +428,48 @@ async function handleRecallIndex(deps, body) {
         picked = [...picked, ...backfill];
     }
     if (picked.length === 0) {
+        // #476: a silent turn (searches ran, no line passed the gates) still
+        // records its PUSH row — the silence rate is computable later and the
+        // judge's population stays complete. Zero event rows, no exposure touch.
+        // Fail-soft like every recording site.
+        if (deps.precision) {
+            try {
+                deps.precision.recorder(deps.db, { sessionId, prompt, ids: [] });
+            }
+            catch (err) {
+                console.warn(`[hicortex] recall-precision push recording failed (fail-soft): ` +
+                    `${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         return { status: 200, body: { block: null, shown: [], turn } };
     }
     const ids = picked.map((r) => r.id);
     deps.registry.markShown(sessionId, ids);
-    // Exposure signal: shown_count + last_accessed refresh, NOT access_count.
-    storage.touchMemoriesShown(deps.db, ids, new Date().toISOString());
+    const nowIso = new Date().toISOString();
+    // #476 Memory Precision: record the push + per-line events IN THE SAME
+    // TRANSACTION as the exposure write (the recorder owns the unit — it calls
+    // touchMemoriesShown inside its own transaction). FAIL-SOFT: on any error
+    // (or when the seams are absent — library callers, test doubles) the plain
+    // exposure write runs instead, so shown_count NEVER depends on telemetry.
+    let exposureWritten = false;
+    if (deps.precision) {
+        try {
+            const [promptEmb, basis] = await Promise.all([
+                deps.precision.promptEmbed(prompt),
+                deps.precision.basis(deps.db),
+            ]);
+            deps.precision.recorder(deps.db, { ts: nowIso, sessionId, prompt, ids, promptEmbedding: promptEmb }, basis);
+            exposureWritten = true;
+        }
+        catch (err) {
+            console.warn(`[hicortex] recall-precision recording failed (fail-soft): ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (!exposureWritten) {
+        // Exposure signal: shown_count + last_accessed refresh, NOT access_count.
+        storage.touchMemoriesShown(deps.db, ids, nowIso);
+    }
     const lines = picked.map((r) => formatIndexLine(r, titleChars));
     const block = [
         "## Memory recall (auto)",
@@ -456,7 +499,7 @@ async function handleRecallIndex(deps, body) {
  * never filtered. Callers may still send a `privacy` field (backward compat)
  * but it is ignored.
  */
-function handleMemoryGet(db, query) {
+function handleMemoryGet(db, query, deps) {
     const id = typeof query.id === "string" ? query.id : "";
     if (!id)
         return { status: 400, body: { error: "Missing 'id'" } };
@@ -471,6 +514,18 @@ function handleMemoryGet(db, query) {
     if (!mem)
         return notFound;
     storage.strengthenMemory(db, fullId, new Date().toISOString());
+    // #476: one kind='fetch' precision event per successful fetch (the use
+    // signal for Level 2 / divergence). Fail-soft — the fetch result is never
+    // affected by a recording failure.
+    if (deps?.recordFetch) {
+        try {
+            deps.recordFetch(db, fullId, new Date().toISOString());
+        }
+        catch (err) {
+            console.warn(`[hicortex] recall-precision fetch recording failed (fail-soft): ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     // `citation` is server-rendered so every plugin surfaces the same built-in
     // provenance norm (owner directive 27.07) — see #193.
     const date = (mem.created_at ?? "").slice(0, 10);
@@ -498,8 +553,10 @@ function handleMemoryGet(db, query) {
  * built inline, while the REST path used handleMemoryGet — same contract, two
  * implementations, one updated).
  */
-function formatMemoryGetText(db, query) {
-    const r = handleMemoryGet(db, query);
+function formatMemoryGetText(db, query, deps) {
+    // deps (the #476 fetch recorder) forwards so the MCP path records exactly
+    // like the REST path — one funnel, one event per fetch.
+    const r = handleMemoryGet(db, query, deps);
     if (r.status !== 200) {
         return { status: r.status, text: String(r.body.error ?? `No memory with id ${query.id ?? ""}`) };
     }