@modusensus/dsh-mneme 0.4.4 → 0.4.5

package/src/dream/decisions.js

@@ -1,5 +1,10 @@
 const ACTIONS = new Set(["keep", "merge", "archive", "conflict", "update", "create"]);
 
+// Epistemic trust (v0.4.5): when config.trustEpistemicWeighting is on, merge
+// keepSource and conflict winners prefer the higher-trust memory. Higher value
+// = preferred. observation (measured) > inferred (derived) > subjective (guess).
+const EPISTEMIC_PRIORITY = { observation: 3, inferred: 2, subjective: 1 };
+
 /**
  * Validate a dream decision list against a snapshot of eligible memories.
  * @param decisions - LLM-produced decision list.
@@ -252,12 +257,34 @@ function applyOne(d, service, snapshot, config = {}) {
   switch (d.action) {
     case "archive": return applyArchive(d, service, snapshot);
     case "merge": return applyMerge(d, service, snapshot, config);
-    case "conflict": return applyConflict(d, service, snapshot);
+    case "conflict": return applyConflict(d, service, snapshot, config);
     case "create": return applyCreate(d, service, config);
     default: return applyUpdate(d, service, snapshot, config);
   }
 }
 
+/**
+ * Highest-epistemic-priority UNARCHIVED id among `ids` (ties break toward
+ * `preferred`). Archived memories are never eligible keepers — promoting one
+ * would demote the real keepSource to a source and then hit the archived-keeper
+ * guard in applyMerge, silently skipping the whole merge. When `preferred`
+ * itself is archived (or missing), fall back to any unarchived candidate.
+ */
+function pickBestKeeper(ids, preferred, service) {
+  let best = null;
+  let bestP = -1;
+  for (const id of ids) {
+    const mem = service.getById(id);
+    if (!mem || mem.archived) continue; // archived/missing: ineligible keeper
+    const p = EPISTEMIC_PRIORITY[mem.epistemic_status] ?? 0;
+    if (p > bestP || (p === bestP && id === preferred)) {
+      bestP = p;
+      best = id;
+    }
+  }
+  return best ?? preferred;
+}
+
 /**
  * Mint a fresh memory (pattern discovery). No existing target, so no CAS guard.
  * Evidence ids ride in the content so a pattern stays traceable to its source
@@ -297,6 +324,13 @@ function applyArchive(d, service, snapshot) {
 }
 
 function applyMerge(d, service, snapshot, config = {}) {
+  // Epistemic trust (v0.4.5): when enabled, prefer an observation keeper over a
+  // subjective/inferred one. Mutating the decision keeps the receipt + committed
+  // record aligned with the actual keeper.
+  if (config.trustEpistemicWeighting === true) {
+    const best = pickBestKeeper(d.ids, d.keepSource, service);
+    if (best && best !== d.keepSource) d.keepSource = best;
+  }
   const sources = d.ids.filter((id) => id !== d.keepSource);
   // Idempotent replay: if every other source is already archived, this merge
   // already landed — skip so a replayed/concurrent decision never double-counts
@@ -334,7 +368,14 @@ function applyMerge(d, service, snapshot, config = {}) {
   };
 }
 
-function applyConflict(d, service, snapshot) {
+function applyConflict(d, service, snapshot, config = {}) {
+  // Epistemic trust (v0.4.5): when enabled, the observation side of a conflict
+  // is preferred as winner over a subjective/inferred one.
+  if (config.trustEpistemicWeighting === true) {
+    const pw = EPISTEMIC_PRIORITY[service.getById(d.winner)?.epistemic_status] ?? 0;
+    const pl = EPISTEMIC_PRIORITY[service.getById(d.loser)?.epistemic_status] ?? 0;
+    if (pl > pw) [d.winner, d.loser] = [d.loser, d.winner];
+  }
   const winner = service.getById(d.winner);
   const loser = service.getById(d.loser);
   if (!winner || !loser) return "skipped";

package/src/inject.js

@@ -6,7 +6,12 @@ export function createInjector(ctx, service, settings, config) {
     if (!candidates.length) return "";
     const lines = ["[记忆库] 来自 dsh-mneme 的跨会话记忆（用户偏好与高优先级项目/决策）："];
     for (const m of candidates) {
-      lines.push(`- [${m.type}] ${m.title}（重要性 ${m.importance}）：${m.content}`);
+      // Epistemic trust (v0.4.5): when enabled, measured observations are
+      // flagged so the agent can weigh them above guesses/opinions.
+      const verified = config.trustEpistemicWeighting === true && m.epistemic_status === "observation"
+        ? "[verified] "
+        : "";
+      lines.push(`- [${m.type}] ${verified}${m.title}（重要性 ${m.importance}）：${m.content}`);
     }
     return lines.join("\n");
   }

package/src/service.js

@@ -3,6 +3,39 @@ import { TYPE_FILE } from "./mirror.js";
 
 const INJECT_TYPES = new Set(["preference", "project", "decision", "summary"]);
 
+// Epistemic trust weights (v0.4.5): when config.trustEpistemicWeighting is on,
+// each recall candidate's existing score is multiplied by the weight of its
+// epistemic_status before ranking — measured facts outrank guesses. Missing /
+// unknown statuses are unscaled (×1). Off by default, so nothing changes.
+const EPISTEMIC_WEIGHTS = { observation: 1.0, inferred: 0.85, subjective: 0.7 };
+
+/**
+ * Standard retrieval-quality metrics over the ordered candidate ids actually
+ * returned vs the ids the evaluator marked relevant (方案 B). Pure + total, so
+ * callers (and tests) get deterministic numbers without touching a store:
+ *   precision = |relevant ∩ retrieved| / |retrieved|
+ *   recall    = |relevant ∩ retrieved| / |expected|
+ *   mrr       = 1 / rank of the first relevant doc (0 when none retrieved)
+ * hit_count is the raw intersection size. Values are rounded to 4 decimals so
+ * repeated divisions (e.g. 1/3) never surface binary-float noise.
+ */
+export function computeRetrievalMetrics(actualIds, expectedIds) {
+  const expected = new Set(Array.isArray(expectedIds) ? expectedIds : []);
+  const actual = Array.isArray(actualIds) ? actualIds : [];
+  const relevant = actual.filter((id) => expected.has(id)).length;
+  const round4 = (x) => Math.round(x * 10000) / 10000;
+  let mrr = 0;
+  for (let i = 0; i < actual.length; i++) {
+    if (expected.has(actual[i])) { mrr = 1 / (i + 1); break; }
+  }
+  return {
+    precision: round4(actual.length ? relevant / actual.length : 0),
+    recall: round4(expected.size ? relevant / expected.size : 0),
+    mrr: round4(mrr),
+    hit_count: relevant
+  };
+}
+
 export function createService({ store, mirror, config, onWrite, logger }) {
   // Optional dream scheduler hook, installed via setDreamHook after creation
   // (the scheduler holds a reference back to the service, so it cannot be
@@ -357,9 +390,21 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     }
 
     merged = merged.slice(0, lim);
-    const result = useRerank && reranker && merged.length
+    let result = useRerank && reranker && merged.length
       ? await rerankCandidates(q, merged, lim)
       : merged;
+    // Epistemic trust (v0.4.5): opt-in re-weighting of the final candidate
+    // scores by source credibility. When off (default) `result` is returned
+    // untouched — exactly the legacy behavior.
+    if (config.trustEpistemicWeighting === true) {
+      result = result
+        .map((m) => ({
+          ...m,
+          score: (m.score ?? 0) * (EPISTEMIC_WEIGHTS[m.epistemic_status] ?? 1)
+        }))
+        .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+        .slice(0, lim);
+    }
 
     // Recall layer receipt: with recordRecall on, hand the actual merged
     // candidate list (id/title/content/score/source) to the injected recorder
@@ -388,6 +433,93 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     return result;
   }
 
+  /**
+   * Retrieval evaluation (方案 B): run one search for `query`, compare the ids
+   * it actually returned against `expectedIds`, and return the computed
+   * metrics. When persistence is on (config.evalPersistTestResults, or an
+   * explicit `persist` override per call) the snapshot is written to the
+   * recall_evals table — a SEPARATE store from the recall_runs production audit,
+   * so test/eval data never inflates the production trail.
+   *
+   * options:
+   *   mode/topK/threshold/useRerank — passed through to searchMemories
+   *   evalType                      — label for the snapshot (default 'manual')
+   *   recordRecall                  — also write a recall_runs audit row for the
+   *                                   same scene and link it via recall_run_id
+   *                                   (default false: eval stays unlinked)
+   *   recallRunId                   — explicit link to an existing recall_runs id
+   *   persist                       — override the config gate for this call
+   *
+   * Returns { metrics, actualIds, expectedIds, recallRunId, persisted }.
+   * Never throws on persistence failures: a broken eval write must not break
+   * the retrieval quality measurement.
+   */
+  async function evaluateRetrieval(query, expectedIds, options = {}) {
+    const q = String(query ?? "").trim();
+    const expected = Array.isArray(expectedIds) ? expectedIds : [];
+    const {
+      mode = "auto",
+      topK = 20,
+      threshold,
+      useRerank = true,
+      evalType = "manual",
+      recordRecall = false,
+      recallRunId = null,
+      persist = config.evalPersistTestResults === true
+    } = options;
+    if (!q) {
+      const empty = computeRetrievalMetrics([], expected);
+      return { metrics: empty, actualIds: [], expectedIds: expected, recallRunId: null, persisted: false };
+    }
+
+    const rows = await searchMemories(q, { mode, topK, threshold, useRerank, recordRecall: false });
+    const actualIds = rows.map((m) => m.id);
+    const metrics = computeRetrievalMetrics(actualIds, expected);
+
+    // Optional recall_runs audit for the same scene; the eval row then links to
+    // it. Kept separate from the production recorder (which fires only on
+    // recordRecall=true inside searchMemories) — eval never double-records.
+    // An explicit recallRunId wins; recordRecall only mints a NEW audit run when
+    // the caller did not already link one (never clobber an existing link).
+    let runId = recallRunId ?? null;
+    if (recordRecall && runId === null) {
+      try {
+        const run = store.saveRecallRun({
+          query: q,
+          mode,
+          topK,
+          threshold: threshold ?? null,
+          candidates: rows.map((m) => ({
+            id: m.id,
+            title: m.title,
+            content: m.content,
+            score: m.score ?? null,
+            source: m.source ?? "keyword"
+          })),
+          created_at: new Date().toISOString()
+        });
+        runId = run.id;
+      } catch { /* non-fatal: the eval itself still succeeds */ }
+    }
+
+    let persisted = false;
+    if (persist) {
+      try {
+        store.saveRecallEval({
+          recall_run_id: runId,
+          query: q,
+          expected_ids: expected,
+          actual_ids: actualIds,
+          metrics,
+          eval_type: evalType,
+          created_at: new Date().toISOString()
+        });
+        persisted = true;
+      } catch { /* non-fatal: measurement survives a failed eval write */ }
+    }
+    return { metrics, actualIds, expectedIds: expected, recallRunId: runId, persisted };
+  }
+
   /**
    * Fire-and-forget write notification; errors are swallowed to keep write
    * paths clean. The store mutation has already committed, so a throwing
@@ -867,6 +999,8 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     setReranker(rn) { reranker = rn; },
     setRecallRecorder(fn) { recallRecorder = fn; },
     searchMemories,
+    evaluateRetrieval,
+    computeRetrievalMetrics,
     // passthroughs used by tools and api layers; mutations keep the mirror in sync
     search: (q, o) => store.search(q, o),
     searchVector: (v, o) => store.searchVector(v, o),
@@ -999,6 +1133,12 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     listConflictPending: (opts) => store.listConflictPending(opts),
     resolveConflictPending: (id, o) => store.resolveConflictPending(id, o),
     countConflictPending: () => store.countConflictPending(),
+    // Recall evaluation trail (方案 B): audit-bookkeeping semantics like the
+    // dream/recall passthroughs above — a recall_evals write is a snapshot, not
+    // a memory mutation, so it never triggers write hooks.
+    saveRecallEval: (r) => store.saveRecallEval(r),
+    getRecallEval: (id) => store.getRecallEval(id),
+    listRecallEvals: (opts) => store.listRecallEvals(opts),
     // Entity gene (v0.3.0) passthroughs for the autoDream apply path
     // (applyDecisions): records supersedes relations after an update and
     // migrates entity_attrs on merge. Bookkeeping writes like the audit

package/src/store.js

@@ -13,6 +13,7 @@ CREATE TABLE IF NOT EXISTS memories (
   archived    INTEGER NOT NULL DEFAULT 0,
   source      TEXT,
   embedding   TEXT,
+  epistemic_status TEXT NOT NULL DEFAULT 'subjective',
   last_accessed_at  TEXT,
   _full_content     TEXT,
   created_at  TEXT NOT NULL,
@@ -61,6 +62,29 @@ CREATE TABLE IF NOT EXISTS recall_runs (
 CREATE INDEX IF NOT EXISTS idx_recall_runs_created ON recall_runs(created_at);
 CREATE INDEX IF NOT EXISTS idx_recall_runs_query ON recall_runs(query);
 
+-- recall_evals: retrieval evaluation/test snapshots, kept SEPARATE from the
+-- recall_runs production audit so test runs never inflate the production trail.
+-- One row per evaluateRetrieval call that opted into persistence
+-- (config.evalPersistTestResults): the query, the expected ids the operator
+-- marked relevant, the actual ids retrieval returned, and the computed
+-- metrics (precision/recall/mrr). recall_run_id optionally links to the
+-- recall_runs audit row that captured the same retrieval scene (null when the
+-- eval did not also record a run). Bookkeeping like the other audit tables: it
+-- never triggers write hooks.
+CREATE TABLE IF NOT EXISTS recall_evals (
+  id            TEXT PRIMARY KEY,
+  recall_run_id TEXT,                -- FK → recall_runs.id (optional linkage)
+  query         TEXT NOT NULL,
+  expected_ids  TEXT NOT NULL,       -- JSON: relevant ids expected by the evaluator
+  actual_ids    TEXT NOT NULL,       -- JSON: ids actually retrieved
+  metrics       TEXT NOT NULL,       -- JSON: { precision, recall, mrr, hit_count }
+  eval_type     TEXT NOT NULL DEFAULT 'manual',
+  created_at    TEXT NOT NULL,
+  FOREIGN KEY (recall_run_id) REFERENCES recall_runs(id)
+);
+CREATE INDEX IF NOT EXISTS idx_recall_evals_created ON recall_evals(created_at);
+CREATE INDEX IF NOT EXISTS idx_recall_evals_run ON recall_evals(recall_run_id);
+
 -- failure_memories: records user corrections / reflection failures. Captures
 -- what a memory was (actual) vs what the user changed it to (expected)
 -- so later reflection passes can mine recurring correction patterns.
@@ -191,6 +215,48 @@ CREATE TABLE IF NOT EXISTS mirror_state (
 
 const TYPES = new Set(["preference", "project", "decision", "history", "summary", "pattern"]);
 
+// Epistemic status: what kind of evidence a memory rests on. Defaults to
+// 'subjective' so legacy rows (and rows without any signal) stay compatible.
+const EPISTEMIC_STATUSES = new Set(["observation", "subjective", "inferred"]);
+// Rule-based inference markers, checked in priority order (observation >
+// inferred > subjective). The default fallback is 'subjective'.
+const OBSERVATION_RE = /实测|观察到|观测|测得|测量|结果表明|数据显示|实验|统计|结果/;
+const INFERRED_RE = /推断|推测出|推导|推论|由此可|据此|综上|意味着|所以|因此/;
+const SUBJECTIVE_RE = /我推测|我猜|我觉得|我感觉|可能|大概|也许|认为|猜想|似乎|猜测|感觉/;
+
+/**
+ * Heuristically infer a memory's epistemic status from its content (and the
+ * AI-generated types). summary/pattern entries are always 'inferred' (derived
+ * from other memories); otherwise content markers decide. Pure rule-based, so
+ * it never throws and always returns a value in EPISTEMIC_STATUSES.
+ */
+function inferEpistemicStatus(memory) {
+  if (memory.type === "summary" || memory.type === "pattern") return "inferred";
+  const text = `${memory.title ?? ""} ${memory.content ?? ""}`;
+  if (OBSERVATION_RE.test(text)) return "observation";
+  if (INFERRED_RE.test(text)) return "inferred";
+  if (SUBJECTIVE_RE.test(text)) return "subjective";
+  return "subjective";
+}
+
+/** Resolve a requested epistemic_status: explicit valid value wins, otherwise
+ *  re-infer from (possibly updated) content. Never returns an invalid value. */
+function resolveEpistemicStatus(memory, patch) {
+  if (patch?.epistemic_status !== undefined) {
+    return EPISTEMIC_STATUSES.has(patch.epistemic_status) ? patch.epistemic_status : "subjective";
+  }
+  // Re-infer whenever any signal that feeds the heuristic changed: content
+  // (marker words), title (marker words), or type (summary/pattern are always
+  // inferred). Otherwise keep the stored status.
+  const changed = ["content", "title", "type"].some(
+    (k) => patch?.[k] !== undefined && patch[k] !== memory?.[k]
+  );
+  if (changed) {
+    return inferEpistemicStatus({ ...memory, ...patch });
+  }
+  return memory?.epistemic_status ?? "subjective";
+}
+
 // Per-type mirror sync receipts (peer blocker 4): a type is either committed
 // (file written + fence applied), failed (last sync round errored for it), or
 // pending (still owed a write).
@@ -229,6 +295,7 @@ function toRow(row) {
     forgotten: row.forgotten === 1,
     archived: row.archived === 1,
     source: row.source ?? undefined,
+    epistemic_status: row.epistemic_status ?? "subjective",
     created_at: row.created_at,
     updated_at: row.updated_at,
     last_accessed_at: row.last_accessed_at ?? undefined,
@@ -305,6 +372,24 @@ function toRecallRun(row) {
   };
 }
 
+function toRecallEval(row) {
+  if (!row) return undefined;
+  let metrics;
+  if (row.metrics != null) {
+    try { metrics = JSON.parse(row.metrics); } catch { metrics = undefined; }
+  }
+  return {
+    id: row.id,
+    recall_run_id: row.recall_run_id ?? undefined,
+    query: row.query,
+    expected_ids: parseJsonArray(row.expected_ids),
+    actual_ids: parseJsonArray(row.actual_ids),
+    metrics,
+    eval_type: row.eval_type,
+    created_at: row.created_at
+  };
+}
+
 function toEntity(row) {
   if (!row) return undefined;
   return {
@@ -421,6 +506,9 @@ export function createStore(path) {
   if (!columns.includes("_full_content")) {
     db.exec("ALTER TABLE memories ADD COLUMN _full_content TEXT");
   }
+  if (!columns.includes("epistemic_status")) {
+    db.exec("ALTER TABLE memories ADD COLUMN epistemic_status TEXT NOT NULL DEFAULT 'subjective'");
+  }
 
   // Legacy dream_runs without policy_epoch → backfill with the default epoch.
   const dreamCols = db.prepare("PRAGMA table_info(dream_runs)").all().map((c) => c.name);
@@ -512,11 +600,16 @@ export function createStore(path) {
     const embedding = Array.isArray(memory.embedding) && memory.embedding.length
       ? JSON.stringify(memory.embedding)
       : null;
+    // Explicit valid status wins; otherwise infer from content/type. Falls back
+    // to 'subjective' (the column default) so legacy callers never break.
+    const epistemicStatus = EPISTEMIC_STATUSES.has(memory.epistemic_status)
+      ? memory.epistemic_status
+      : inferEpistemicStatus(memory);
     runAtomically(() => {
       db.prepare(
-        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, source, embedding, created_at, updated_at)
-         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?)`
-      ).run(id, type, memory.title, memory.content, tags, importance, memory.source ?? null, embedding, now, now);
+        `INSERT INTO memories (id, type, title, content, tags, importance, forgotten, source, embedding, epistemic_status, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?)`
+      ).run(id, type, memory.title, memory.content, tags, importance, memory.source ?? null, embedding, epistemicStatus, now, now);
       // desired generation bumped in the same transaction as the write: once
       // this commits, generation > applied_generation, so a crash right after
       // (before syncMirror) is caught by recoverMirror on restart (peer
@@ -538,9 +631,10 @@ export function createStore(path) {
     const embedding = patch.embedding !== undefined
       ? (Array.isArray(patch.embedding) && patch.embedding.length ? JSON.stringify(patch.embedding) : null)
       : existing.embedding ?? null;
+    const epistemicStatus = resolveEpistemicStatus(existing, patch);
     runAtomically(() => {
       db.prepare(
-        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, updated_at=? WHERE id=?`
+        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, epistemic_status=?, updated_at=? WHERE id=?`
       ).run(
         type,
         patch.title ?? existing.title,
@@ -549,6 +643,7 @@ export function createStore(path) {
         Number.isInteger(patch.importance) ? patch.importance : existing.importance,
         patch.source !== undefined ? patch.source : (existing.source ?? null),
         embedding,
+        epistemicStatus,
         now,
         id
       );
@@ -588,6 +683,7 @@ export function createStore(path) {
     const embedding = patch.embedding !== undefined
       ? (Array.isArray(patch.embedding) && patch.embedding.length ? JSON.stringify(patch.embedding) : null)
       : existing.embedding ?? null;
+    const epistemicStatus = resolveEpistemicStatus(existing, patch);
     // The CAS UPDATE and the desired-generation bump must commit together (audit
     // peer A): if the UPDATE autocommits first and the process dies before the
     // increment, the store is mutated while generation == applied_generation and
@@ -597,7 +693,7 @@ export function createStore(path) {
     let applied = false;
     runAtomically(() => {
       const result = db.prepare(
-        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, updated_at=?
+        `UPDATE memories SET type=?, title=?, content=?, tags=?, importance=?, source=?, embedding=?, epistemic_status=?, updated_at=?
          WHERE id=? AND updated_at=?`
       ).run(
         type,
@@ -607,6 +703,7 @@ export function createStore(path) {
         Number.isInteger(patch.importance) ? patch.importance : existing.importance,
         patch.source !== undefined ? patch.source : (existing.source ?? null),
         embedding,
+        epistemicStatus,
         now,
         id,
         expectedUpdatedAt
@@ -1001,6 +1098,60 @@ export function createStore(path) {
     return rows.map(toRecallRun);
   }
 
+  // --- recall evaluation trail (方案 B: separate from the production audit) -
+
+  /**
+   * Persist one retrieval-evaluation snapshot into recall_evals — the test/eval
+   * sibling of recall_runs, deliberately stored apart so eval snapshots never
+   * inflate the production recall audit. Like the other audit tables this is
+   * bookkeeping: it never triggers write hooks. Writes are idempotent on id
+   * (replay overwrites, never duplicates), matching saveRecallRun. recall_run_id
+   * optionally links the eval to the recall_runs row that captured the same
+   * retrieval scene (FK-referenced, null when no run was recorded).
+   */
+  function saveRecallEval(evalRow) {
+    const id = evalRow.id ?? randomUUID();
+    db.prepare(
+      `INSERT INTO recall_evals (id, recall_run_id, query, expected_ids, actual_ids, metrics, eval_type, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         recall_run_id=excluded.recall_run_id, query=excluded.query,
+         expected_ids=excluded.expected_ids, actual_ids=excluded.actual_ids,
+         metrics=excluded.metrics, eval_type=excluded.eval_type,
+         created_at=excluded.created_at`
+    ).run(
+      id,
+      evalRow.recall_run_id ?? null,
+      evalRow.query,
+      JSON.stringify(evalRow.expected_ids ?? []),
+      JSON.stringify(evalRow.actual_ids ?? []),
+      JSON.stringify(evalRow.metrics ?? {}),
+      evalRow.eval_type ?? "manual",
+      evalRow.created_at ?? nowIso()
+    );
+    return getRecallEval(id);
+  }
+
+  function getRecallEval(id) {
+    const row = db.prepare("SELECT * FROM recall_evals WHERE id = ?").get(id);
+    return toRecallEval(row);
+  }
+
+  function listRecallEvals({ limit = 50, offset = 0, query } = {}) {
+    const { limit: lim, offset: off } = sanitizePage(limit, offset, 50);
+    const clauses = [];
+    const params = [];
+    if (query) {
+      clauses.push("query LIKE ? ESCAPE '\\'");
+      params.push(`%${escapeLike(String(query))}%`);
+    }
+    const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+    const rows = db.prepare(
+      `SELECT * FROM recall_evals ${where} ORDER BY created_at DESC, id LIMIT ? OFFSET ?`
+    ).all(...params, lim, off);
+    return rows.map(toRecallEval);
+  }
+
   // --- failure memories ----------------------------------------------------
 
   /**
@@ -1524,6 +1675,9 @@ export function createStore(path) {
     saveRecallRun,
     getRecallRun,
     listRecallRuns,
+    saveRecallEval,
+    getRecallEval,
+    listRecallEvals,
     saveFailure,
     listFailures,
     getFailureStats,