@gamaze/hicortex 0.22.0 → 0.22.2

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) {
@@ -787,7 +790,8 @@ async function startServer(options = {}) {
         `/novelty=${CALIBRATION.NOVELTY_FLOOR_SLOTS}` +
         ` · ` +
         `score sim=${scoringCfg.similarity}/str=${scoringCfg.strength}/conn=${scoringCfg.connections}` +
-        `/rec=${scoringCfg.recency}, fresh=${scoringCfg.freshnessBoostWeight}@${scoringCfg.freshnessBoostDays}d, ` +
+        `/K=${scoringCfg.connectionsSaturation}` +
+        `/rec=${scoringCfg.recency}, head=${scoringCfg.recencyHead}@${scoringCfg.recencyHeadDays}d, ` +
         `superseded×${scoringCfg.supersededDemotion}` +
         `, intent w=${sessionIntentCfg.weight}` +
         (sessionIntentCfg.weight === 0 ? " (disabled)" : ""));
@@ -1052,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" });
@@ -1066,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" });
@@ -1089,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 ?? ""}`) };
     }

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;