@gamaze/hicortex 0.22.1 → 0.22.3

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

package/dist/recall-precision.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Memory Precision (#476) — the event store behind the console's Memory
+ * Precision card, and the two-level context model made visible:
+ *
+ *   - Level 1 (pushed index): what every prompt receives unasked. One
+ *     `recall_pushes` row per NON-skipped /recall-index call + one
+ *     `recall_events` kind='shown' row per pushed line, carrying the RAW
+ *     cosines (similarity to the prompt, redundancy vs standing context) —
+ *     stored threshold-free, verdicts computed at render so recalibration
+ *     never rewrites history.
+ *   - Level 2 (recall depth): what the agent fetches when needed. One
+ *     `recall_events` kind='fetch' row per handleMemoryGet — the ONE funnel
+ *     the REST GET /memory and MCP hicortex_get paths share.
+ *
+ * Layering (the recall-index.ts / capture-health.ts convention): all write +
+ * aggregation logic lives here as pure functions over the db handle so tests
+ * exercise them without HTTP; mcp-server.ts only wires the record calls into
+ * the /recall-index and fetch funnels, and dashboard.ts spreads the window
+ * aggregation into /dashboard/data.
+ *
+ * FAIL-SOFT LAW: recording is telemetry. Any error here is caught by the
+ * CALLER (handleRecallIndex / handleMemoryGet) and swallowed — the recall
+ * response (status 200 + block) is never affected, and the exposure signal
+ * (touchMemoriesShown) never depends on it (the handler falls back to the
+ * plain exposure write when recording is absent or fails).
+ *
+ * The perf law (bounded hot-path cost): the recorder computes cosines with
+ * the request's ALREADY-MEMOIZED prompt embedding (createRecallRetrieveFn's
+ * embedPrompt — zero extra embeds) against STORED memory vectors, and writes
+ * one transaction of ≤ maxItems+1 INSERTs — microseconds inside an endpoint
+ * that already writes and spends ~100-300 ms embedding and searching.
+ */
+import type Database from "better-sqlite3";
+/** One non-skipped /recall-index call to record (recorder seam contract —
+ *  recall-index.ts types its precision deps against this). */
+export interface RecallPushEntry {
+    /** ISO timestamp of the push; defaults to now. */
+    ts?: string;
+    /** The request's session_id (nullable — the wire field is optional). */
+    sessionId: string | null;
+    /** The prompt text (only the ≤256-char excerpt is persisted). */
+    prompt: string;
+    /** The shown memory ids, in index order. EMPTY = silent turn (the push row
+     *  is still recorded — the silence rate is computable and the judge's
+     *  population complete — but no event rows, no exposure touch). */
+    ids: string[];
+    /** The PURE-prompt embedding — REQUIRED when ids.length > 0 (the request's
+     *  memoized embed; unused on a silent turn, so no embed is ever spent on
+     *  recording). */
+    promptEmbedding?: Float32Array;
+}
+/**
+ * Record one /recall-index push: the push row + (when lines were shown) the
+ * per-line kind='shown' event rows, in ONE transaction WITH the existing
+ * exposure write (storage.touchMemoriesShown — the spec's "same transaction";
+ * better-sqlite3 nests the inner transaction as a savepoint, so a recording
+ * failure rolls back the whole unit and the CALLER's fallback re-runs the
+ * exposure touch alone — shown_count never depends on telemetry).
+ *
+ * similarity = cosine(memory embedding, PURE prompt embedding), computed
+ * UNIFORMLY via cosineBetweenVectors against the stored vector — FTS-sourced
+ * picks (which bypass the cosine floor and carry similarity:null in
+ * MemorySearchResult) get a measured value here too. redundancy = MAX cosine
+ * against the standing-context basis vectors (NULL when the basis is empty —
+ * embed failure degrades to "unmeasured", never a guessed 0). Both stored
+ * raw; no thresholds touch this row.
+ */
+export declare function recordRecallPush(db: Database.Database, entry: RecallPushEntry, basis?: Float32Array[]): void;
+/** Fetch-event recorder contract (handleMemoryGet's optional #476 dep —
+ *  mcp-server wires recordRecallFetch; tests can force a failure). */
+export type RecallFetchRecorder = (db: Database.Database, memoryId: string, ts?: string) => void;
+/**
+ * Record one explicit fetch (handleMemoryGet — the funnel both REST GET
+ * /memory and MCP hicortex_get route through, so the row is written exactly
+ * once per fetch). similarity/redundancy are NULL on fetch rows: Level 2 is
+ * the use signal, not a relevance measure. push_id NULL — a fetch stands
+ * alone. Fail-soft at the CALLER (handleMemoryGet wraps this).
+ */
+export declare function recordRecallFetch(db: Database.Database, memoryId: string, ts?: string): void;
+/**
+ * Nightly retention prune (zero-LLM): drop both event tables' rows outside
+ * the rolling window whose length IS the retention constant (the
+ * CAPTURE_HEALTH_WINDOW_DAYS single-constant law — the card can never claim a
+ * window the store no longer has rows for). Inclusive cutoff: the last N
+ * calendar days with today counted stay (day >= today−(N−1)), the complement
+ * is deleted — retained rows == window rows.
+ */
+export declare function pruneRecallPrecision(db: Database.Database): void;
+/**
+ * True when the identity scope is served to EVERY known client — the only
+ * case where identity sections belong in the corpus-level standing-context
+ * basis. /recall-index carries no client type, so a SCOPED identity config
+ * (any subset) excludes identity rather than guessing which sections the
+ * calling session sees. `clients` is the boot-resolved
+ * resolveIdentityClientsConfig output; the absent-config default ["cc"] is
+ * NOT all → identity excluded.
+ */
+export declare function identityServedToAllClients(clients: string[]): boolean;
+export interface StandingContextBasisConfig {
+    /** The daemon's boot-resolved identityClients (read lazily — assigned at
+     *  boot, after the routes that consume the basis are registered). */
+    clients: () => string[];
+    /** The daemon's identity dir (sections read only when all-clients). */
+    identityDir: () => string;
+    /** Embedding seam — tests inject a deterministic embedder. Default embedBatch. */
+    embedFn?: (texts: string[]) => Promise<Float32Array[]>;
+    /** Clock seam (tests). Default Date.now. */
+    now?: () => number;
+    /** Cache TTL seam (tests). Default 24h. */
+    ttlMs?: number;
+}
+/** The basis provider: db → basis vectors (may be empty). Callable, plus a
+ *  test-only cache reset (the cache is deliberately per-provider so suites
+ *  with different configs never share it). */
+export interface StandingContextBasis {
+    (db: Database.Database): Promise<Float32Array[]>;
+    resetForTests(): void;
+}
+/**
+ * The standing-context basis: the top lessons in /learnings order
+ * (storage.getLessons(db, 30) — exactly what the /learnings handler serves
+ * and every client's session-start hook injects) PLUS identity sections ONLY
+ * when identityServedToAllClients (see above). Embedded with the LOCAL
+ * embedder — no LLM anywhere in this feature. Cached for 24h (single-flight:
+ * concurrent callers share the embedding pass); an embed failure degrades to
+ * an EMPTY cached basis (redundancy NULL — "unmeasured", never guessed) and
+ * is retried after the TTL.
+ */
+export declare function createStandingContextBasis(config: StandingContextBasisConfig): StandingContextBasis;
+/** The Level-1 half: pushed-index precision proxies over the window's stored
+ *  events. Thresholds are ECHOED (the page never hardcodes an edge);
+ *  mean/share are computed at read time from raw values. */
+export interface MemoryPrecisionLevel1 {
+    /** Non-skipped /recall-index calls in the window (silent turns included). */
+    pushes: number;
+    /** Pushed index lines (kind='shown' event rows) in the window. */
+    lines: number;
+    /** Mean cosine(line, its prompt) over lines with a measured similarity;
+     *  null when nothing was measured. */
+    mean_similarity: number | null;
+    /** Share of measured lines at/above the redundancy threshold; null when
+     *  nothing was measured (empty/unmeasured — undefined, not zero). */
+    redundant_share: number | null;
+    thresholds: {
+        /** The redundancy render edge (calibration MEMORY_PRECISION_REDUNDANT_ABOVE). */
+        redundant_above: number;
+        /** The divergence bar (calibration MEMORY_PRECISION_DIVERGENCE_MIN_SHOWN). */
+        divergence_min_shown: number;
+    };
+}
+/** The Level-2 half: recall depth (fetches per showing) over the window,
+ *  derived from corpus-wide cumulative counter DELTAS — live adoption minus
+ *  the newest pre-window snapshot. No second source of truth: the events
+ *  above are per-line; this is the corpus aggregate the nightly already
+ *  snapshots. Null = no honest value (no pre-window baseline), never 0. */
+export interface MemoryPrecisionLevel2 {
+    shown: number | null;
+    used: number | null;
+    uses_per_showing: number | null;
+}
+/** The whole /dashboard/data memory_precision block (one card's payload,
+ *  budget ≤ 2 KB — the top-3 divergence lines are the only content). */
+export interface MemoryPrecision {
+    /** The EFFECTIVE window (min(range, retention)); the page renders
+     *  "last N days" from this echo, never a hardcoded literal. */
+    window_days: number;
+    level1: MemoryPrecisionLevel1;
+    level2: MemoryPrecisionLevel2;
+    divergence: {
+        /** Live memories with ≥ thresholds.divergence_min_shown window showings
+         *  and ZERO window fetches — the index keeps pushing, nothing reads. */
+        count: number;
+        /** Top-3 by window showings DESC, lines rendered through the SHARED
+         *  formatIndexLine (≤ RECALL_TITLE_CHARS — the card cannot drift from
+         *  what agents see). Hover-only on the card face (no memory lists on
+         *  the main page — owner ruling 2026-09-12). */
+        top: Array<{
+            id: string;
+            line: string;
+            shown: number;
+        }>;
+    };
+}
+/** Read-time seams (the #408 experiment pattern — the eval/tests sweep
+ *  values through them; production never passes anything). */
+export interface MemoryPrecisionReadOptions {
+    /** Fixed clock (tests); default now. */
+    now?: Date;
+    /** Redundancy render threshold override (tests — changing it must move
+     *  only the share, never a stored row). */
+    redundantAbove?: number;
+}
+/**
+ * The window aggregation behind /dashboard/data's memory_precision block
+ * (the readCaptureHealthWindow pattern). Effective window = min(range,
+ * MEMORY_PRECISION_WINDOW_DAYS) for every range incl. 180d/all (the #452
+ * selector's wide options clamp to what the retention honestly holds).
+ *
+ * Level 1 groups the stored event rows over the window (day >= today−(N−1),
+ * the inclusive capture-health convention); Level 2 is the corpus-wide
+ * adoption delta — live sums minus the NEWEST non-null `adoption` in
+ * dashboard_snapshots at/before now−N days (cumulative counters telescope:
+ * a missing nightly widens the effective window rather than corrupting it;
+ * two snapshots on one day are harmless — the newest wins; no pre-window
+ * baseline → null, undefined rather than zero). Divergence joins the
+ * window's per-memory shown/fetch counts against LIVE (non-absorbed)
+ * memories and renders the top-3 through the shared index-line path.
+ */
+export declare function readMemoryPrecision(db: Database.Database, range: string, liveAdoption: {
+    shown_sum: number;
+    used_sum: number;
+}, opts?: MemoryPrecisionReadOptions): MemoryPrecision;