@staix/agent-mem 0.10.0 → 0.11.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mem",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Bounded project memory tools and seven deterministic capture hooks, without a resident worker.",
   "mcpServers": {
     "agent-mem": {

package/README.md

@@ -2,7 +2,7 @@
 
 Curated memory with append-only JSONL logs, a derived SQLite index, short- and long-term tiers, a typed graph, goals with leases, and git sync between machines. Extracted from [agent-hub](https://github.com/STAIxBWLB/agent-hub), with compatible storage and entry IDs.
 
-Version: 0.10.0. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.11.0. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Quick start
 
@@ -213,6 +213,8 @@ Project identity (#15 D2) keeps `memoryProjectKey`: a worktree, a submodule and
 
 `amem eval [--set ko|<file>] [--k 1,5,10] [--json]` measures recall with no model and no network (agent-mem#40 F13): it replays a question set against ranked `store.search` and reports recall@k, hit@k and MRR. The ordinary curated project `amem search` path now uses that ranked search; `--filter` selects the legacy substring behavior. Without `--set` it scores the built-in synthetic set (26 invented harbour entries, long and short tier, written a day apart, and 32 questions, shipped in `src/memory/eval-set.json`), which is seeded into a throwaway store, so it never reads or writes your memory home and gives the same numbers on every machine. A set of your own either carries its own `entries` (self-contained, named by `key`) or, without entries, names real entry ids (or a prefix of 8 or more hex characters) and is scored against this project's store; each name is resolved like `amem show` does (a promoted short-term id finds its long-term copy, and a superseded id stands for the entry that replaced it, since search returns only live entries), and a prefix that matches more than one live entry is refused. `mem:<id>` as a brief prints it is accepted. Questions whose expected entry is not in the store score 0 in `all` and are left out of `answerable`, and `answerable` is scored over the entries the store holds, so a ranking problem and a coverage problem stay apart (`n/a` when no question is answerable). `--set ko` scores the second built-in set instead: 37 invented Korean entries and 38 questions (particle variants, spaced and unspaced compounds, mixed Korean-English terms, Latin abbreviations, short and long tier), with its baseline recorded in `docs/contracts.md` (agent-mem#62). Set format: `docs/contracts.md#recall-evaluation-f13`.
 
+External retrieval measurements for MCP, library search and a plain BM25 baseline are recorded in [LongMemEval S/M](docs/bench/longmemeval.md). The full datasets stay outside the repository; CI runs only synthetic harness fixtures.
+
 The R7 capacity advisor reports this machine's load and proposes capture bounds: `amem capacity [--json]` shows capture size and growth, disk, memory, the rolling `metrics.jsonl` readings and the proposal with its binding constraint; `amem capacity apply [--cap-mb N] [--retention-days N]` saves a preview, and only a matching later `--confirm` writes the home default config. Applying is person-only (agent markers refused, a terminal required); an agent may read the proposal through the library, never apply it. Under the 2026-10-17 owner decision (item 2) the proposal is the largest cap and retention that fit, and it may be above the current values: the cap is the disk-share bound itself (default 2% of free space, `--disk-share`), and retention is the share divided by the measured daily growth, up to a 365-day ceiling (a `ponytail:` constant, a person setting is the upgrade path). A hook p95 over 150 ms or hook RSS over 100 MB halves the proposed cap, and search RSS over 200 MB halves the retention. The reason names every binding constraint: `disk-share retention` or `retention ceiling`, `disk-share cap`, `R3 search RSS`, `R2 hook cost`. A proposal is never written by the advisor, and `apply` still takes `--cap-mb` and `--retention-days` to override it. Benchmark samples stay in the measuring script's synthetic home; only real hook and search invocations feed the advisor's rolling metrics.
 
 ## Repo scope (#15 T4)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Curated, shared memory for coding agents: append-only logs, a derived index, tiers and a typed graph.",
   "license": "MIT",
   "type": "module",

package/src/cli.ts

@@ -43,6 +43,7 @@ import { appendGitattributes, appendRepoLine, boundRepoRoot, planGitattributes,
 import type { Visibility } from "./memory/sync.ts";
 import { applySplit, previewSplit } from "./memory/capacity-split.ts";
 import { evalText, parseKs } from "./memory/eval.ts";
+import { unrankedScoreDetails } from "./memory/search-score.ts";
 import { builtinSet, evalSeeded, evalStore, FIXTURE_PATH, readEvalSet } from "./memory/eval-fixture.ts";
 import { markShown, pendingSummary } from "./memory/candidate-pending.ts";
 import { buildNote, FAIL_TEMPLATE, hasFailLabel, noteAdd, parseFailTemplate, type FailFields } from "./memory/note-add.ts";
@@ -573,7 +574,7 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
       try {
         const result = await importProject(store, { from: options["--from"], project: key, confirm: options["--confirm"] === true,
           allowShared: options["--allow-shared"] === true, policy: note => policy.screenStandalone(note) });
-        const counts = `sources ${JSON.stringify(result.provenance.source)}, peers ${JSON.stringify(result.provenance.peer)}, scopes ${JSON.stringify(result.provenance.scope)}`;
+        const counts = `sources ${JSON.stringify(result.provenance.source)}, peers ${JSON.stringify(result.provenance.peer)}, scopes ${JSON.stringify(result.provenance.scope)}, machines ${JSON.stringify(result.provenance.machine)}`;
         const summary = result.applied ? `imported ${result.added} of ${result.read} curated notes into ${result.project} with their original ids`
           : `preview: ${result.wouldAdd} of ${result.read} curated notes can be imported into ${result.project} with their original ids (re-run with --confirm to write)`;
         return options["--json"] ? JSON.stringify(result, null, 2)
@@ -589,6 +590,7 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
     return options["--json"] ? JSON.stringify(written, null, 2) : `${op === "forget" ? "forgot" : op === "archive" ? "archived" : "unarchived"} ${written.key}${requested !== written.key ? ` (alias ${requested})` : ""}`;
   }
   if (sub === "search" && options["--all-projects"] === true) {
+    if (options["--explain"] === true) throw new Error("--explain applies to current-project ranked search, not --all-projects");
     if (options["--filter"] === true) throw new Error("--filter applies to project-local search, not --all-projects");
     const words = parsed.positionals.join(" ");
     if (!words.trim()) throw new Error("usage: amem search --all-projects <words> [--limit N] [--include-archived] [--json]");
@@ -598,6 +600,11 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
     return [`crossed projects: searched ${result.projects.length} (${result.projects.join(", ")})`, ...(result.hits.length ? result.hits.map(one) : ["(nothing)"])].join("\n");
   }
   if (sub === "search" && options["--include-archived"] === true) throw new Error("--include-archived only applies with --all-projects");
+  if (sub === "search" && options["--explain"] === true) {
+    if (options["--filter"] === true) throw new Error("--explain cannot be combined with --filter");
+    if (options["--history"] === true || options["--as-of"] !== undefined) throw new Error("--explain cannot be combined with --history or --as-of");
+    if (!parsed.positionals.join(" ").trim()) throw new Error("--explain requires a non-empty search query");
+  }
   if (sub === "alias") {
     if (parsed.path[1] === "add") {
       const [from, to] = parsed.positionals;
@@ -686,10 +693,12 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
     const kind = options["--kind"], since = options["--since"], limit = options["--limit"] !== undefined ? Number(options["--limit"]) : 50;
     const rows = read.views.filter(row => options["--tier"] !== "short" && (kind === undefined || row.kind === kind) && (typeof since !== "string" || Date.parse(row.at) >= Date.parse(since))
       && words.every(word => `${row.title ?? ""}\n${row.text}\n${row.about.join(" ")}`.toLowerCase().includes(word))).slice(0, limit);
-    if (options["--json"]) { try { const base = JSON.parse(output) as unknown[]; return JSON.stringify([...base, ...rows], null, 2); } catch { return output; } }
+    const repoDetails = explainSearch ? rows.map(row => ({ ...row, scoreDetails: unrankedScoreDetails("repo", null) })) : rows;
+    if (options["--json"]) { try { const base = JSON.parse(output) as unknown[]; return JSON.stringify([...base, ...repoDetails], null, 2); } catch { return output; } }
     const line = (row: RepoView) => `repo:${row.id.slice(0, 8)}  ${row.at.slice(0, 16).replace("T", " ")}  repo  ${row.kind.padEnd(8)} ${`${row.title ? `${row.title}: ` : ""}${row.text}`.replace(/\s+/g, " ").slice(0, 100)}`;
     const note = read.state === "unsafe" ? [`(repo scope unavailable: ${read.reason})`] : read.skipped.malformed + read.skipped.mismatched + read.skipped.withheld ? [`(${read.skipped.malformed + read.skipped.mismatched} repo lines skipped as invalid, ${read.skipped.withheld} withheld by the screen)`] : [];
-    return [output, ...(rows.length ? ["repo scope (.amem/log.jsonl):", ...rows.map(line)] : []), ...note].join("\n");
+    const lines = explainSearch ? rows.flatMap(row => [line(row), `score: ${JSON.stringify(unrankedScoreDetails("repo", null))}`]) : rows.map(line);
+    return [output, ...(rows.length ? ["repo scope (.amem/log.jsonl):", ...lines] : []), ...note].join("\n");
   };
   const crosses = definition.policyFree === true;
   const cwd = context.cwd ?? process.cwd();
@@ -732,13 +741,14 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
     if (args[index] === "--capture-days") { captureArgs.add(index); captureArgs.add(index + 1); }
     else if (args[index]?.startsWith("--capture-days=")) captureArgs.add(index);
   }
-  // --filter selects the standalone CLI mode; hosts keep their existing raw command arguments.
+  // --filter and --explain select standalone CLI behavior; hosts keep their existing raw command arguments.
   const legacySearch = options["--filter"] === true;
-  const syncArgs = args.filter((arg, index) => arg !== "--if-due" && arg !== "--force" && !captureArgs.has(index) && (!legacySearch || arg !== "--filter"));
+  const explainSearch = sub === "search" && options["--explain"] === true;
+  const syncArgs = args.filter((arg, index) => arg !== "--if-due" && arg !== "--force" && !captureArgs.has(index) && (!legacySearch || arg !== "--filter") && (!explainSearch || arg !== "--explain"));
   let output: string;
   const stop = ifDue ? stopSignal(context.syncDeadlineMs ?? SYNC_IF_DUE_DEADLINE_MS, process) : undefined;
   try {
-    output = await withRepoRows(await rawMemoryCommand(syncArgs, cwd, { person: true, rankedSearch: !legacySearch, project: boundProject(), open, readable: notes => notes, stale: createRecallStalenessProbe({ cwd: recallRoot ?? cwd, rootConfirmed, policy: () => configured }), outputReady: notes => outputReady(notes.map(view => view.id)), importPolicy: () => text => configured.declinesPersonal(text),
+    output = await withRepoRows(await rawMemoryCommand(syncArgs, cwd, { person: true, rankedSearch: !legacySearch, ...(explainSearch ? { explainSearch: true } : {}), project: boundProject(), open, readable: notes => notes, stale: createRecallStalenessProbe({ cwd: recallRoot ?? cwd, rootConfirmed, policy: () => configured }), outputReady: notes => outputReady(notes.map(view => view.id)), importPolicy: () => text => configured.declinesPersonal(text),
       sync: { screen: row => configured.screenStandalone(row), ...(stop ? { signal: stop.signal } : {}) },   // the repository-narrowed policy binds what sync publishes too
       onBridgeStatus: status => { receipt.bridgeStatus = status; } }));
   } catch (error) {

package/src/commands-table.ts

@@ -33,7 +33,7 @@ export const COMMANDS: Record<string, CommandDefinition> = {
     "--all-projects": flag("List every active project's candidates; the reply says it crossed projects"), "--project": text("List one named project's candidates") } },
   list: { description: "List memory", options: { ...filters, ...history } },
   search: { description: "Rank current curated project notes; history/as-of and empty queries retain newest-first filtering", options: { ...filters, ...history,
-    "--filter": flag("Current-project curated notes: match every word as a substring, newest first; not with --all-projects"), "--all-projects": flag("Search every active project; the reply says it crossed projects"),
+    "--filter": flag("Current-project curated notes: match every word as a substring, newest first; not with --all-projects"), "--explain": flag("Include the score factors for ranked project-local results"), "--all-projects": flag("Search every active project; the reply says it crossed projects"),
     "--include-archived": flag("With --all-projects, also read archived projects") }, args: [{ name: "words", variadic: true }] },
   brief: { description: "Read intent/path memory: fails first, then decisions and contracts; untrusted data within a UTF-8 byte cap", options: { ...json,
     "--for": text("Explicit intent"), "--paths": text("Repeatable named path"), "--symbols": text("Repeatable named symbol"), "--bytes": text("Complete brief-body byte cap (1..8192, default 2048)") } },

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./memory/store.ts";
+export type { ScoreFactors } from "./memory/search-score.ts";
 export * from "./memory/capture.ts";
 export { fts5Available, ftsTerms, SearchIndex, captureSearch } from "./memory/search-fts.ts";
 export type { CuratedDoc, RankedRef } from "./memory/search-fts.ts";

package/src/mcp-memory.ts

@@ -187,8 +187,9 @@ export function createMemoryMcp(options: MemoryMcpOptions): MemoryMcp {
         } finally { index.close(); }
       },
       async amem_search(args) {
-        bound(args, ["query", "limit", "since", "includeCapture"]); const query = textOf(args, "query")!, limit = limitOf(args), since = sinceOf(args);
+        bound(args, ["query", "limit", "since", "includeCapture", "explain"]); const query = textOf(args, "query")!, limit = limitOf(args), since = sinceOf(args);
         if (args.includeCapture !== undefined && typeof args.includeCapture !== "boolean") unavailable();
+        if (args.explain !== undefined && typeof args.explain !== "boolean") unavailable();
         if (!await currentPolicy().screen({ query })) unavailable();
         // ponytail: scan all matches into private disposable disk state, keeping one body page in JS.
         // Work scales with matches; a policy-bound cache is the upgrade if this reaches the unchanged watchdog.
@@ -219,7 +220,10 @@ export function createMemoryMcp(options: MemoryMcpOptions): MemoryMcp {
           const repoNotes = (await repoRows()).filter(view => (!since || Date.parse(view.at) >= Date.parse(since)) && (useFts || words.every(word => `${view.title ?? ""}\n${view.text}\n${view.about.join(" ")}`.toLowerCase().includes(word))));
           for (const view of repoNotes) append({ source: "repo", evidence: false, view });
           if (batch.length) index.append(batch);
-          const selected = index.best(query, limit, store.readNow(), useFts).map(({ value, score }) => ({ ...value, score }));
+          const selected = index.best(query, limit, store.readNow(), useFts, args.explain === true).map(({ value, score, scoreDetails }) => {
+            const hit = { ...value, score };
+            return scoreDetails ? { ...hit, scoreDetails: { source: value.source, ...scoreDetails } } : hit;
+          });
           const probe = stale(), result = { engine: useFts ? "fts5" : "substring", hits: selected.map(hit => hit.source === "curated" && "view" in hit && hit.view ? { ...hit, view: decorate(hit.view as View, probe) } : hit) };
           guard(); return observed(result, selected.flatMap(hit => hit.source === "curated" && "view" in hit && hit.view ? [hit.view.id] : []), selected.map(hit => "view" in hit ? hit.view : hit.capture));
         } finally { const position = closers.indexOf(releaseIndex); if (position >= 0) closers.splice(position, 1); releaseIndex(); }

package/src/mcp.ts

@@ -9,7 +9,7 @@ const tool = <Name extends string>(name: Name, description: string, inputSchema:
 
 /** Storage scope comes from startup, never tool arguments; candidate proposals remain person-reviewed. */
 export const MCP_TOOLS = [
-  tool("amem_search", "Search screened memory in this project. Capture results are recall, not curated evidence.", object({ query: string(1000), limit, since: string(40), includeCapture: { type: "boolean" } }, ["query"])),
+  tool("amem_search", "Search screened memory in this project. Capture results are recall, not curated evidence.", object({ query: string(1000), limit, since: string(40), includeCapture: { type: "boolean" }, explain: { type: "boolean" } }, ["query"])),
   tool("amem_evidence", "Return a bounded bundle of cited, live curated entries for a question. Untrusted memory data only: no answer or model call. Capture, repo-only notes, pending candidates and model answers are not evidence.", object({ question: string(1000), limit: { type: "integer", minimum: 1, maximum: 20 }, maxBytes: { type: "integer", minimum: 256, maximum: 8192 } }, ["question"])),
   tool("amem_show", "Show a screened memory entry in this project by its exact id or unique prefix.", object({ id: string(80) }, ["id"])),
   tool("amem_timeline", "Read screened memory near an entry or time in this project.", object({ id: string(80), since: string(40), limit })),

package/src/memory/candidates.ts

@@ -13,6 +13,15 @@ export const CANDIDATE_DB_BUSY_TIMEOUT_MS = 3000;
 /** First line of every note written by accepting a consolidation candidate; `consolidationClusters` reads it to avoid proposing summaries of its own summaries. */
 export const ACCEPTED_CONSOLIDATION_PREFIX = "Accepted consolidation candidate: ";
 export const CANDIDATE_RETENTION = { count: 500, ageMs: 30 * 86400_000 } as const;
+export const CONSOLIDATION_REVIEW_LIMIT = 10_000;
+export class ConsolidationReviewLimit extends Error {
+  readonly code = "consolidation_review_limit";
+  readonly limit = CONSOLIDATION_REVIEW_LIMIT;
+  constructor(readonly project: string, readonly count: number) {
+    super(`consolidation review cap reached: project ${project}, count ${count}, limit ${CONSOLIDATION_REVIEW_LIMIT}; no reviewed identities evicted`);
+    this.name = "ConsolidationReviewLimit";
+  }
+}
 export const COUNTER_RETENTION = { count: 10_000, ageMs: 90 * 86400_000 } as const;
 export type CandidateVerdict = "public" | "private" | "pii" | "unknown";
 export interface CandidateTarget { id: string; revision: string }
@@ -27,6 +36,7 @@ export type CandidateInput = { project: string } & (
 );
 export type CandidateStatus = "pending" | "accepting" | "accepted" | "rejected";
 export interface Candidate { id: string; createdAt: string; status: CandidateStatus; input: CandidateInput; acceptedNoteId: string | null }
+export interface ConsolidationReview { status: Exclude<CandidateStatus, "pending">; acceptedNoteId: string | null }
 export interface CandidateFilter { project: string; status?: CandidateStatus | "all"; kind?: CandidateInput["kind"]; limit?: number }
 export interface CounterKey { entryId: string; project: string; task?: string | null; turn?: string | null; session?: string | null; deliveryId: string }
 export interface CounterValues { rendered?: number | null; delivered?: number | null; cited?: number | null }
@@ -146,13 +156,27 @@ export class CandidateStore {
     // F7 / AC4: when a candidate was first shown to the person. In place and nullable: an older database gains it here, and a reader without it treats every row as unshown.
     // Several processes open this store at once (every `amem mcp` builds it at startup), so the check and the ALTER are one immediate transaction: the loser waits, then sees the column.
     if (!hasShownColumn(this.db)) this.db.transaction(() => { if (!hasShownColumn(this.db)) this.db.run("ALTER TABLE candidates ADD COLUMN shown_at INTEGER"); }).immediate();
+    this.db.run("CREATE TABLE IF NOT EXISTS consolidation_reviews (id TEXT PRIMARY KEY, project TEXT NOT NULL, status TEXT NOT NULL, note_id TEXT)");
     this.db.run("CREATE TABLE IF NOT EXISTS counters (id TEXT PRIMARY KEY, project TEXT NOT NULL, payload TEXT NOT NULL, at INTEGER NOT NULL, rendered INTEGER, delivered INTEGER, cited INTEGER)");
     this.prune();
   }
   close(): void { this.db.close(); }
+  /** Keep only identity and disposition after payload retention, never source text or target lists. */
+  private retainConsolidationReviews(): void {
+    const overflow = this.db.query(`SELECT project, count(*) AS n FROM consolidation_reviews GROUP BY project HAVING count(*) > ?
+      UNION ALL SELECT c.project, count(*) + (SELECT count(*) FROM consolidation_reviews WHERE project = c.project) AS n FROM candidates c LEFT JOIN consolidation_reviews r ON r.id = c.id
+      WHERE c.kind = 'consolidation' AND c.status IN ('accepting', 'accepted', 'rejected') AND r.id IS NULL
+      GROUP BY c.project HAVING count(*) + (SELECT count(*) FROM consolidation_reviews WHERE project = c.project) > ? LIMIT 1`)
+      .get(CONSOLIDATION_REVIEW_LIMIT, CONSOLIDATION_REVIEW_LIMIT) as { project: string; n: number } | null;
+    if (overflow) throw new ConsolidationReviewLimit(overflow.project, overflow.n);
+    this.db.run(`INSERT INTO consolidation_reviews (id, project, status, note_id)
+      SELECT id, project, status, note_id FROM candidates WHERE kind = 'consolidation' AND status IN ('accepting', 'accepted', 'rejected')
+      ON CONFLICT(id) DO UPDATE SET status = excluded.status, note_id = excluded.note_id`);
+  }
   private prune(): void {
     this.db.transaction(() => {
       const now = this.now();
+      this.retainConsolidationReviews();
       // Candidates (AC4, no candidate expires unshown): by age only a decided one, or a pending one that was shown and has had its grace period, goes. By count three tiers decide who is
       // kept: unshown pending first, then shown pending, then decided, so a cap eviction takes decided rows before a shown one (which is owed its grace) and shown ones before an unseen one.
       this.db.query("DELETE FROM candidates WHERE at <= ? AND (status IN ('accepted', 'rejected') OR (shown_at IS NOT NULL AND shown_at <= ?))").run(now - CANDIDATE_RETENTION.ageMs, now - CANDIDATE_SHOWN_GRACE_MS);
@@ -174,10 +198,19 @@ export class CandidateStore {
     // Prune, count, insert and prune again are ONE immediate transaction: concurrent proposers (several agents) cannot all pass the count and then let the cap evict an unseen candidate.
     return this.db.transaction((): string => {
       this.prune();
+      if (input.kind === "consolidation" && this.reviewedConsolidation(id, input.project)) return id;
       // AC4: a new candidate never pushes an unshown one out. With the cap's worth waiting the person has to review first, and the refusal says so (a named error an MCP tool can map).
       const waiting = (this.db.query("SELECT COUNT(*) AS n FROM candidates WHERE project = ? AND status IN ('pending', 'accepting') AND shown_at IS NULL").get(input.project) as { n: number }).n;
       const known = this.db.query("SELECT 1 FROM candidates WHERE id = ?").get(id);
       if (!known && waiting >= CANDIDATE_RETENTION.count) throw new CandidateQueueFull(waiting);
+      if (!known && input.kind === "consolidation") {
+        const allocated = this.db.query(`SELECT (SELECT count(*) FROM consolidation_reviews WHERE project = ?) +
+          (SELECT count(*) FROM candidates c WHERE project = ? AND kind = 'consolidation' AND status IN ('pending', 'accepting')
+            AND NOT EXISTS (SELECT 1 FROM consolidation_reviews r WHERE r.id = c.id)) AS n`).get(input.project, input.project) as { n: number };
+        // ponytail: 10,000 lasting review identities per project; refuse new proposals instead of forgetting a person's decision.
+        // Upgrade with an explicit person-audited receipt archive before increasing this bounded sidecar capacity.
+        if (allocated.n >= CONSOLIDATION_REVIEW_LIMIT) throw new ConsolidationReviewLimit(input.project, allocated.n);
+      }
       this.db.query("INSERT OR IGNORE INTO candidates (id, project, kind, payload, at, status) VALUES (?, ?, ?, ?, ?, 'pending')").run(id, input.project, input.kind, payload, this.now());
       this.prune();
       return id;
@@ -189,6 +222,11 @@ export class CandidateStore {
     const row = this.db.query("SELECT * FROM candidates WHERE id = ? AND project IN (SELECT value FROM json_each(?))").get(id, this.scope(project)) as Parameters<CandidateStore["decode"]>[0] | null;
     return row ? this.decode(row) : undefined;
   }
+  reviewedConsolidation(id: string, project: string): ConsolidationReview | undefined {
+    if (!candidateId(id) || !text(project, 400)) throw new Error("invalid candidate identity");
+    const row = this.db.query("SELECT status, note_id FROM consolidation_reviews WHERE id = ? AND project IN (SELECT value FROM json_each(?))").get(id, this.scope(project)) as { status: ConsolidationReview["status"]; note_id: string | null } | null;
+    return row ? { status: row.status, acceptedNoteId: row.note_id } : undefined;
+  }
   list(filter: CandidateFilter): Candidate[] {
     if (!text(filter.project, 400) || filter.status !== undefined && !["pending", "accepting", "accepted", "rejected", "all"].includes(filter.status) || filter.kind !== undefined && !["correction", "fail", "decay", "memory", "promotion", "consolidation", "model-answer"].includes(filter.kind)) throw new Error("invalid candidate filter");
     const limit = filter.limit ?? CANDIDATE_RETENTION.count;
@@ -221,6 +259,7 @@ export class CandidateStore {
       if (!candidate) throw new Error("candidate unavailable");
       if (candidate.status === "accepted" || candidate.status === "accepting") throw new Error("candidate acceptance already started; inspect its ordinary note before any further action");
       this.db.query("UPDATE candidates SET status = 'rejected' WHERE id = ? AND project IN (SELECT value FROM json_each(?)) AND status = 'pending'").run(id, this.scope(context.project));
+      if (candidate.input.kind === "consolidation") this.retainConsolidationReviews();
     }).immediate();
   }
   accept(id: string, context: CandidateAcceptance): CandidateAcceptanceResult {
@@ -321,7 +360,10 @@ export class CandidateStore {
           // report every confirmed effect; recovery requires person inspection before any replay.
           throw Error(`consolidation interrupted: inspect note ${noteId}; superseded ${applied.join(", ") || "none"}; remaining or uncertain ${data.targets.filter(target => !applied.includes(target.id)).map(target => target.id).join(", ")}`);
         }
-        this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(noteId, candidate.id, this.scope(context.project));
+        this.db.transaction(() => {
+          this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(noteId, candidate.id, this.scope(context.project));
+          this.db.query("UPDATE consolidation_reviews SET status = 'accepted', note_id = ? WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(noteId, candidate.id, this.scope(context.project));
+        }).immediate();
         return { candidateId: candidate.id, noteId, alreadyAccepted: false };
       });
     });
@@ -379,6 +421,7 @@ export class CandidateStore {
       if (current.status !== "pending") throw Error("candidate is rejected or acceptance was interrupted; no automatic replay");
       before?.();
       this.db.query("UPDATE candidates SET status = 'accepting' WHERE id = ? AND project IN (SELECT value FROM json_each(?))").run(id, this.scope(project));
+      if (current.input.kind === "consolidation") this.retainConsolidationReviews();
       return undefined;
     }).immediate();
   }

package/src/memory/commands.ts

@@ -17,6 +17,8 @@ export interface MemoryCommandOptions {
   person?: boolean;
   /** Standalone person CLI opt-in. Hosts omit this to retain their screened substring recall. */
   rankedSearch?: boolean;
+  /** Standalone person CLI opt-in; requires rankedSearch and person intent. */
+  explainSearch?: boolean;
   /** Defaults to amem's own names. */
   names?: CommandNames;
   /** Startup-bound canonical project supplied by a host; no model-facing selector. */
@@ -70,6 +72,10 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
   const names = opts.names ?? AMEM_NAMES, usage = memoryUsage(names.memory);
   if (args.some(arg => arg === "--history" || arg === "--as-of" || arg.startsWith("--history=") || arg.startsWith("--as-of=")) && opts.person !== true) fail("historical recall requires authenticated person intent from the host");
   if (opts.rankedSearch && opts.person !== true) fail("ranked CLI search requires person intent");
+  if (opts.explainSearch && (opts.person !== true || opts.rankedSearch !== true)) fail("score explanation requires ranked search and person intent");
+  if (opts.explainSearch && sub !== "search") fail("score explanation applies only to search");
+  if (args.includes("--explain") && (opts.person !== true || opts.rankedSearch !== true || opts.explainSearch !== true)) fail("score explanation requires ranked search and person intent");
+  for (let index = rest.indexOf("--explain"); index >= 0; index = rest.indexOf("--explain")) rest.splice(index, 1);
   const store = opts.store ?? opts.open();
   const actor = "user";
   const project = opts.project ?? memoryProjectKey(cwd);
@@ -93,12 +99,14 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
         if (limit && !(Number(limit) > 0)) fail("--limit takes a positive number");
         const q = sub === "search" ? rest.join(" ") : undefined;
         const ranked = opts.rankedSearch && q?.trim() && !history && asOf === undefined;
+        if (opts.explainSearch && (!ranked || !q?.trim())) fail("--explain requires a non-empty current-project ranked search without --history or --as-of");
         const state = recallRows(store, project, { person: opts.person, history, asOf, query: ranked ? undefined : q, limit: Number.MAX_SAFE_INTEGER });
         // Retained history has its own snapshot; the current index cannot rank it. Empty queries keep list semantics.
         // ponytail: fetch up to the current curated-view count before display caps, so metadata/readable exclusions consume no slots.
         // Upgrade to paged ranked views if this full-pool person read reaches the R3 ceiling.
-        const candidates = ranked ? store.withDeferredPromotions(() => store.search(q!, { project, includeCapture: false, limit: Math.max(1, state.views.length) }))
-          .hits.flatMap(hit => hit.view ? [hit.view] : []) : state.views;
+        const rankedResult = ranked ? store.withDeferredPromotions(() => store.search(q!, { project, includeCapture: false, limit: Math.max(1, state.views.length), ...(opts.explainSearch ? { explain: true } : {}) })) : undefined;
+        const scoreDetails = opts.explainSearch ? new Map(rankedResult?.hits.flatMap(hit => hit.view && hit.scoreDetails ? [[hit.view.id, hit.scoreDetails] as const] : []) ?? []) : undefined;
+        const candidates = rankedResult ? rankedResult.hits.flatMap(hit => hit.view ? [hit.view] : []) : state.views;
         const all = candidates.filter(view => (!tier || view.tier === tier) && (!kind || view.kind === kind) && (!peer || view.peer === peer) && (!machine || view.machine === machine) && (!since || Date.parse(view.at) >= Date.parse(since)));
         const readable = opts.readable(all), rows = readable.slice(0, limit ? Number(limit) : 50);
         ready(rows);
@@ -108,10 +116,12 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
           const result = { at: state.at, entries: rows.map(decorated), forgotten, relations: state.relations.filter(edge => publicIds.has(edge.from) && publicIds.has(edge.to)), incomplete: emitted.incomplete || readable.length > rows.length || forgotten.length < allForgotten.length, notices: emitted.notices };
           return json ? JSON.stringify(result, null, 2) : [`retained memory as of ${state.at}`, ...result.notices, ...rows.map(view => `${stale(view) ? "(stale?) " : ""}${one(view)}${view.expiresAt && Date.parse(view.expiresAt) <= Date.parse(state.at) ? ` (expired at ${view.expiresAt})` : ""}`), ...forgotten.map(row => `forgotten ${row.id} at ${row.at} (no retained text shown)`), ...(result.incomplete ? ["(retained state is incomplete)"] : [])].join("\n");
         }
-        if (json) return JSON.stringify(rows, null, 2);
+        if (json) return JSON.stringify(opts.explainSearch ? rows.map(view => ({ ...view, ...(scoreDetails?.has(view.id) ? { scoreDetails: scoreDetails.get(view.id) } : {}) })) : rows, null, 2);
         const counted = opts.readable(store.withDeferredPromotions(() => store.list({ project, limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true })));
         const withheld = all.length - readable.length;
-        return [`memory for ${project} on machine ${store.machine.label}: ${counted.filter(view => view.tier === "long").length} long-term, ${counted.filter(view => view.tier === "short").length} short-term`, ...(rows.length ? rows.map(view => `${stale(view) ? "(stale?) " : ""}${one(view)}`) : ["(nothing)"]),
+        return [`memory for ${project} on machine ${store.machine.label}: ${counted.filter(view => view.tier === "long").length} long-term, ${counted.filter(view => view.tier === "short").length} short-term`, ...(rows.length ? opts.explainSearch
+          ? rows.flatMap(view => [`${stale(view) ? "(stale?) " : ""}${one(view)}`, ...(scoreDetails?.has(view.id) ? [`score: ${JSON.stringify(scoreDetails.get(view.id))}`] : [])])
+          : rows.map(view => `${stale(view) ? "(stale?) " : ""}${one(view)}`) : ["(nothing)"]),
           ...(withheld ? [`(${withheld} withheld: they match a PII pattern; the dashboard shows them)`] : [])].join("\n");
       }
       case "show": {

package/src/memory/consolidate.ts

@@ -1,4 +1,4 @@
-import { CandidateStore, candidateInputId, candidateTargetRevision, type CandidateInput } from "./candidates.ts";
+import { CandidateStore, ConsolidationReviewLimit, candidateInputId, candidateTargetRevision, type CandidateInput } from "./candidates.ts";
 import { consolidationClusters } from "./consolidation-clusters.ts";
 import { memoryPolicySnapshot, type StandalonePolicy } from "./policy.ts";
 import { recallViewIsLive } from "./recall.ts";
@@ -20,7 +20,10 @@ export interface ConsolidationReport {
   model?: ModelConsolidationReport;
 }
 export class ConsolidationProposalError extends Error {
-  constructor(readonly proposed: string[]) { super(`consolidation proposal interrupted; candidates already queued: ${proposed.join(", ") || "none"}; no curated notes changed`); this.name = "ConsolidationProposalError"; }
+  constructor(readonly proposed: string[], readonly refusal?: ConsolidationReviewLimit) {
+    super(`consolidation proposal interrupted; candidates already queued: ${proposed.join(", ") || "none"}; no curated notes changed${refusal ? `; ${refusal.message}` : ""}`);
+    this.name = "ConsolidationProposalError";
+  }
 }
 const modelAnswer = (row: View) => row.peer === "amem-model" || row.text.startsWith("Model answer:");
 /** On-demand candidate writes only. Every source is screened once under one policy and source revision. */
@@ -67,12 +70,12 @@ export async function proposeConsolidation(store: MemoryStore, candidates: Candi
     // put() is INSERT OR IGNORE: a candidate the person already accepted or rejected keeps its status, so it is neither written again nor reported as queued.
     for (const input of prepared) {
       check();
-      const known = candidates.get(candidateInputId(input), project);
-      if (known && known.status !== "pending") { report.alreadyReviewed++; continue; }
-      const id = candidates.put(input, "public");
+      const id = candidateInputId(input), known = candidates.get(id, project);
+      if (known && known.status !== "pending" || candidates.reviewedConsolidation(id, project)) { report.alreadyReviewed++; continue; }
+      candidates.put(input, "public");
       report.candidates.push({ id, action: input.action, sources: input.targets.map(target => `mem:${target.id}`) });
     }
     if (options.model !== undefined) report.model = await proposeModelConsolidations(store, candidates, synced, options.model, { project, actor: options.actor, check, policy });
-  } catch { throw new ConsolidationProposalError(report.candidates.map(row => row.id)); }
+  } catch (error) { throw new ConsolidationProposalError(report.candidates.map(row => row.id), error instanceof ConsolidationReviewLimit ? error : undefined); }
   return report;
 }

package/src/memory/consolidation-clusters.ts

@@ -8,9 +8,14 @@ export interface ConsolidationCluster { action: ConsolidationAction; sources: Vi
 export const CONSOLIDATION_SOURCE_LIMIT = 256, CONSOLIDATION_PROPOSAL_LIMIT = 32;
 const words = (row: View) => new Set((`${row.title ?? ""} ${row.text}`.toLowerCase().match(/[\p{L}\p{N}_]{3,}/gu) ?? []).filter(word => !["the", "and", "for", "with", "from", "this", "that", "approach", "symptom", "cause", "evidence", "retry", "when"].includes(word)).slice(0, 128));
 /** A note written by accepting a consolidation candidate. Proposing over one would be a summary of summaries. */
-export const isAcceptedConsolidation = (row: Pick<View, "text">): boolean => row.text.startsWith(ACCEPTED_CONSOLIDATION_PREFIX);
-/** An accepted recurring-fix summary keeps its sources live and quotes them whole, so it overlaps each of them. */
-const isAcceptedRecurringFix = (row: Pick<View, "text">): boolean => isAcceptedConsolidation(row) && /^Action: recurring-fix$/m.test(row.text.split("\n\n", 1)[0] ?? "");
+export function isAcceptedConsolidation(row: Pick<View, "text">): boolean {
+  const end = row.text.indexOf("\n\n"); if (end < 0) return false;
+  const lines = row.text.slice(0, end).split("\n");
+  return lines.length === 3 && lines[0]!.startsWith(ACCEPTED_CONSOLIDATION_PREFIX)
+    && /^[a-f0-9]{64}$/.test(lines[0]!.slice(ACCEPTED_CONSOLIDATION_PREFIX.length))
+    && /^Action: (?:merge|supersession|recurring-fix)$/.test(lines[1]!)
+    && /^Sources: mem:[a-f0-9]{32}(?:, mem:[a-f0-9]{32}){0,7}$/.test(lines[2]!);
+}
 const paths = (row: View) => row.about.filter(node => node.startsWith("path:"));
 const sharedPath = (a: View, b: View) => paths(a).some(node => paths(b).includes(node));
 const overlap = (a: Set<string>, b: Set<string>) => [...a].filter(word => b.has(word)).length / Math.max(1, Math.min(a.size, b.size));
@@ -18,7 +23,7 @@ const overlap = (a: Set<string>, b: Set<string>) => [...a].filter(word => b.has(
 /** Bounded deterministic proposals over already-screened rows. Never mutates a note or runs a model. */
 export function consolidationClusters(input: readonly View[], project: string, now: number): { clusters: ConsolidationCluster[]; truncated: boolean; engine: "fts5" | "substring" } {
   if (!project.trim() || !Number.isFinite(now)) throw Error("consolidation context unavailable");
-  const eligible = input.filter(row => row.project === project && recallViewIsLive(row, now))
+  const eligible = input.filter(row => row.project === project && recallViewIsLive(row, now) && !isAcceptedConsolidation(row))
     .sort((a, b) => b.at.localeCompare(a.at) || a.id.localeCompare(b.id));
   const rows = [...new Map(eligible.map(row => [row.id, row])).values()].slice(0, CONSOLIDATION_SOURCE_LIMIT);
   const index = new SearchIndex(":memory:"), clusters: ConsolidationCluster[] = [], seen = new Set<string>();
@@ -36,15 +41,15 @@ export function consolidationClusters(input: readonly View[], project: string, n
     for (let i = 0; i < rows.length; i++) {
       const row = rows[i]!, candidates = index.available ? new Set(index.query([...terms.get(row.id)!].slice(0, 32).join(" "), rows.length, project).map(hit => hit.ref)) : undefined;
       for (const peer of rows.slice(i + 1)) {
-        if (row.kind !== peer.kind || isAcceptedRecurringFix(row) || isAcceptedRecurringFix(peer)) continue;
+        if (row.kind !== peer.kind) continue;
         const lexical = overlap(terms.get(row.id)!, terms.get(peer.id)!);
         if (row.text === peer.text) add("supersession", [row, peer], "Identical text; review one replacement for both originals.");
         else if ((!candidates || candidates.has(peer.id)) && lexical >= 0.5 && sharedPath(row, peer)) add("merge", [row, peer], "Shared path and overlapping indexed terms; no equivalence is assumed.");
       }
       // A retained supersession chain is context, never a reason to resurrect an old body.
-      if (row.supersedes.length >= 2 && !isAcceptedConsolidation(row)) add("merge", [row], "Current head already replaces multiple originals; review a chain summary.");
+      if (row.supersedes.length >= 2) add("merge", [row], "Current head already replaces multiple originals; review a chain summary.");
     }
-    const failRows = rows.filter(row => row.kind === "fail" && !isAcceptedConsolidation(row)), decisions = rows.filter(row => row.kind === "decision" || row.kind === "contract");
+    const failRows = rows.filter(row => row.kind === "fail"), decisions = rows.filter(row => row.kind === "decision" || row.kind === "contract");
     for (let i = 0; i < failRows.length; i++) for (const peer of failRows.slice(i + 1)) {
       const fail = failRows[i]!;
       if (!sharedPath(fail, peer) || overlap(terms.get(fail.id)!, terms.get(peer.id)!) < 0.5) continue;

package/src/memory/eval-fixture.ts

@@ -79,18 +79,22 @@ export function evalSeeded(set: EvalSet, ks?: readonly number[], rank?: RankFn):
     const base = join(dir, "memory");
     mkdirSync(base, { recursive: true });
     // One entry per day, so the recency weight (a 30-day scale) is exercised, long-tier entries first and short-tier ones last: a short-term note leaves the index 14 days after it is
-    // written, and the clock stops a day after the last entry, so the short ones written in that window are live when the set is searched (a set with more short entries than that
+    // written, and the undated clock stops a day after the last entry, so the short ones written in that window are live when the set is searched (a set with more short entries than that
     // window holds loses its oldest, and a question naming one is then reported as not in the store, like any other missing entry).
+    // Explicit dates override only their entry; undated entries retain their legacy file-order day.
+    // Search a day after the latest actual seed time unless the set supplies its own clock.
     let current = EPOCH;
     store = new MemoryStore({ memoryDir: base, now: () => current, screen: () => "keep" });
     const ids = new Map<string, string>();
     const ordered = [...set.entries.filter(entry => entry.tier !== "short"), ...set.entries.filter(entry => entry.tier === "short")];
+    let latest = -Infinity;
     for (const [index, entry] of ordered.entries()) {
-      current = EPOCH + index * DAY;
+      current = entry.at === undefined ? EPOCH + index * DAY : Date.parse(entry.at);
+      latest = Math.max(latest, current);
       ids.set(entry.key, store.note({ op: "note", project: PROJECT, scope: "project", tier: entry.tier ?? "long", kind: entry.kind ?? "finding", peer: "eval", source: "person",
         ...(entry.title ? { title: entry.title } : {}), text: entry.text, about: entry.about ?? [] }, entry.tier === "short"));
     }
-    current = EPOCH + ordered.length * DAY;
+    current = set.now === undefined ? latest + DAY : Date.parse(set.now);
     const window = Math.max(...(ks ?? [10]));
     const search = rank ? { rank: (question: string) => rank(store!, question, window), engine: () => "custom" } : ranker(store, PROJECT, window);
     // Resolved through `store.get`, so a note that has already expired is absent, not silently present: coverage stays separate from ranking.

package/src/memory/eval.ts

@@ -12,10 +12,10 @@ export const MAX_QUESTIONS = 500, MAX_ENTRIES = 200, MAX_QUESTION_CHARS = 500, M
 export const DEFAULT_KS: readonly number[] = [1, 5, 10];
 
 export const EVAL_KINDS = ["decision", "finding", "contract", "fail"] as const;
-export interface EvalEntry { key: string; title?: string; text: string; kind?: (typeof EVAL_KINDS)[number]; tier?: "short" | "long"; about?: string[] }
+export interface EvalEntry { key: string; title?: string; text: string; kind?: (typeof EVAL_KINDS)[number]; tier?: "short" | "long"; about?: string[]; /** Explicit seed date; absent keeps the legacy positional day. */ at?: string }
 /** `tag` is an optional label for what a question probes (a test counts them); it never changes the scoring. */
 export interface EvalQuestion { q: string; expect: string[]; tag?: string }
-export interface EvalSet { schema: typeof EVAL_SCHEMA; entries?: EvalEntry[]; questions: EvalQuestion[] }
+export interface EvalSet { schema: typeof EVAL_SCHEMA; entries?: EvalEntry[]; questions: EvalQuestion[]; /** Search clock for a self-contained set; defaults to one day after its latest seed. */ now?: string }
 
 const fail = (message: string): never => { throw new Error(`invalid eval set: ${message}`); };
 const object = (value: unknown, what: string): Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : fail(`${what} must be an object`);
@@ -24,17 +24,25 @@ function exact(row: Record<string, unknown>, allowed: readonly string[], what: s
 }
 const text = (value: unknown, what: string, max: number): string => typeof value === "string" && value.trim() !== "" && value.length <= max && !/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value) ? value : fail(`${what} must be a non-empty string of at most ${max} characters`);
 
+/** ISO calendar date or canonical UTC timestamp; reject Date.parse's rollover and locale-dependent forms. */
+function date(value: unknown, what: string): string {
+  if (typeof value !== "string" || !/^[0-9]{4}-[0-9]{2}-[0-9]{2}(?:T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:[.][0-9]{3})?Z)?$/.test(value)) return fail(`${what} must be an ISO date or UTC timestamp`);
+  const ms = Date.parse(value), normalized = value.length === 10 ? value + "T00:00:00.000Z" : value.length === 20 ? value.slice(0, -1) + ".000Z" : value;
+  if (!Number.isFinite(ms) || new Date(ms).toISOString() !== normalized) return fail(`${what} must be a valid ISO date or UTC timestamp`);
+  return value;
+}
+
 /** Strict, bounded parse of untrusted JSON. Unknown keys are errors, so a typo cannot silently change what is measured. */
 export function parseEvalSet(raw: unknown): EvalSet {
   const root = object(raw, "the set");
-  exact(root, ["schema", "entries", "questions"], "the set");
+  exact(root, ["schema", "entries", "questions", "now"], "the set");
   if (root.schema !== EVAL_SCHEMA) fail(`schema must be "${EVAL_SCHEMA}"`);
   const entries: EvalEntry[] = [], keys = new Set<string>();
   if (root.entries !== undefined) {
     if (!Array.isArray(root.entries) || !root.entries.length || root.entries.length > MAX_ENTRIES) fail(`entries must hold 1 to ${MAX_ENTRIES} items when present`);
     for (const [index, item] of (root.entries as unknown[]).entries()) {
       const row = object(item, `entries[${index}]`);
-      exact(row, ["key", "title", "text", "kind", "tier", "about"], `entries[${index}]`);
+      exact(row, ["key", "title", "text", "kind", "tier", "about", "at"], `entries[${index}]`);
       const key = text(row.key, `entries[${index}].key`, 80);
       if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(key)) fail(`entries[${index}].key may use letters, digits, ".", "_" and "-"`);
       if (keys.has(key)) fail(`entries[${index}].key "${key}" repeats`);
@@ -42,9 +50,10 @@ export function parseEvalSet(raw: unknown): EvalSet {
       const kind = row.kind === undefined ? undefined : (EVAL_KINDS as readonly unknown[]).includes(row.kind) ? row.kind as EvalEntry["kind"] : fail(`entries[${index}].kind must be one of ${EVAL_KINDS.join(", ")}`);
       const tier = row.tier === undefined ? undefined : row.tier === "short" || row.tier === "long" ? row.tier : fail(`entries[${index}].tier must be short or long`);
       const about = row.about === undefined ? undefined : Array.isArray(row.about) && row.about.length <= 20 ? (row.about as unknown[]).map((value, at) => text(value, `entries[${index}].about[${at}]`, 200)) : fail(`entries[${index}].about must be a list of at most 20 strings`);
-      entries.push({ key, text: text(row.text, `entries[${index}].text`, MAX_ENTRY_CHARS), ...(row.title === undefined ? {} : { title: text(row.title, `entries[${index}].title`, 200) }), ...(kind ? { kind } : {}), ...(tier ? { tier } : {}), ...(about ? { about } : {}) });
+      entries.push({ key, text: text(row.text, `entries[${index}].text`, MAX_ENTRY_CHARS), ...(row.title === undefined ? {} : { title: text(row.title, `entries[${index}].title`, 200) }), ...(kind ? { kind } : {}), ...(tier ? { tier } : {}), ...(about ? { about } : {}), ...(row.at === undefined ? {} : { at: date(row.at, `entries[${index}].at`) }) });
     }
   }
+  if (root.now !== undefined && !entries.length) fail("now requires self-contained entries");
   if (!Array.isArray(root.questions) || !root.questions.length || root.questions.length > MAX_QUESTIONS) fail(`questions must hold 1 to ${MAX_QUESTIONS} items`);
   const questions = (root.questions as unknown[]).map((item, index): EvalQuestion => {
     const row = object(item, `questions[${index}]`);
@@ -58,7 +67,7 @@ export function parseEvalSet(raw: unknown): EvalSet {
     }
     return { q: text(row.q, `questions[${index}].q`, MAX_QUESTION_CHARS), expect, ...(tag ? { tag } : {}) };
   });
-  return { schema: EVAL_SCHEMA, ...(entries.length ? { entries } : {}), questions };
+  return { schema: EVAL_SCHEMA, ...(entries.length ? { entries } : {}), questions, ...(root.now === undefined ? {} : { now: date(root.now, "now") }) };
 }
 
 /** `--k 1,5,10`: ascending, unique, 1 to MAX_K. */

package/src/memory/external-import.ts

@@ -206,7 +206,14 @@ function title(source: ExternalMemorySource, file: SourceFile, record: RawRecord
 }
 
 function portable(path: string): string { return path.split(sep).join("/"); }
-function claudeProjectDirectory(cwd: string): string { return realPath(cwd).replace(/[/.]/g, "-"); }
+/** Claude Code 2.1.311's project-path encoding, including its long-name suffix. */
+function claudeProjectDirectory(cwd: string): string {
+  const path = realPath(cwd), encoded = path.replace(/[^a-zA-Z0-9]/g, "-");
+  if (encoded.length <= 200) return encoded;
+  let hash = 0;
+  for (let index = 0; index < path.length; index++) hash = (Math.imul(hash, 31) + path.charCodeAt(index)) | 0;
+  return `${encoded.slice(0, 200)}-${Math.abs(hash).toString(36)}`;
+}
 
 export async function importExternalMemory(opts: {
   base: string;

package/src/memory/platform.ts

@@ -103,18 +103,18 @@ export function memoryGitEnv(env: NodeJS.ProcessEnv = process.env, options: { re
 /** spawnSync form of the same call: the env option is merged with memoryGitEnv, everything else passes through. */
 export function memoryGitSync(args: string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string> {
   const argv = memoryGitArgv(args);
-  return childProcess().spawnSync(argv[0]!, argv.slice(1), { ...(ambientGitTimeout !== undefined ? { timeout: ambientGitTimeout, killSignal: "SIGKILL" as const } : {}), ...options, env: memoryGitEnv(options.env ?? process.env) });
+  const timeout = gitTimeoutContext?.getStore();
+  return childProcess().spawnSync(argv[0]!, argv.slice(1), { ...(timeout !== undefined ? { timeout, killSignal: "SIGKILL" as const } : {}), ...options, env: memoryGitEnv(options.env ?? process.env) });
 }
-let ambientGitTimeout: number | undefined;
+let gitTimeoutContext: import("node:async_hooks").AsyncLocalStorage<number> | undefined;
 /**
- * Runs `work` with a timeout on every `memoryGitSync` call that sets none of its own: a synchronous git call blocks the event loop, so a signal sent to this process alone waits for it.
- * A call that times out reads as a failed git (`error` set, no status), which every caller already treats as "unknown". The setting is process-wide while `work` runs, so use it only in a
- * command that does nothing else at the same time (`amem doctor`).
- * ponytail: one global instead of a parameter on every caller between doctor and its git calls (project key, repository root, visibility). Upgrade: thread an options argument through them.
+ * Bound `memoryGitSync` calls inside this async operation unless a call supplies its own timeout.
+ * Nested and concurrent operations keep independent contexts; unrelated host calls retain their own options.
+ * Load async_hooks only when a caller requests a deadline, keeping path-only hook imports unchanged.
  */
 export async function withGitTimeout<T>(ms: number, work: () => Promise<T>): Promise<T> {
-  const prior = ambientGitTimeout; ambientGitTimeout = ms;
-  try { return await work(); } finally { ambientGitTimeout = prior; }
+  gitTimeoutContext ??= new (require("node:async_hooks").AsyncLocalStorage)();
+  return gitTimeoutContext!.run(ms, work);
 }
 
 /**

package/src/memory/project-import.ts

@@ -15,7 +15,7 @@ const NOTE_KEYS = new Set(["schema", "id", "at", "machine", "op", "project", "sc
 const OPERATIONS_WARNING = "Supersede, demote, settle and forget operations are not exported; re-import restores authored note rows only.";
 
 type ImportedNote = { id: string; at: string; machine: string; note: NoteInput };
-type Provenance = { source: Record<string, number>; peer: Record<string, number>; scope: Record<string, number> };
+type Provenance = { source: Record<string, number>; peer: Record<string, number>; scope: Record<string, number>; machine: Record<string, number> };
 export interface ProjectImportResult {
   applied: boolean;
   project: string;
@@ -46,13 +46,18 @@ function increment(counts: Map<string, number>, value: string | undefined): void
 }
 
 function provenance(notes: Iterable<ImportedNote>): Provenance {
-  const source = new Map<string, number>(), peer = new Map<string, number>(), scope = new Map<string, number>();
-  for (const { note } of notes) {
+  const source = new Map<string, number>(), peer = new Map<string, number>(), scope = new Map<string, number>(), machine = new Map<string, number>();
+  for (const { note, machine: origin } of notes) {
     increment(source, note.source);
     increment(peer, note.peer);
     increment(scope, note.scope);
+    increment(machine, origin);
   }
-  return { source: Object.fromEntries(source), peer: Object.fromEntries(peer), scope: Object.fromEntries(scope) };
+  return { source: Object.fromEntries(source), peer: Object.fromEntries(peer), scope: Object.fromEntries(scope), machine: Object.fromEntries(machine) };
+}
+
+function relationTargets(imported: ImportedNote): string[] {
+  return [imported.note.supersedes, imported.note.promotedFrom].filter((target): target is string => typeof target === "string");
 }
 
 function unchangedAfterNormalization(note: NoteInput): boolean {
@@ -71,10 +76,10 @@ export async function importProject(store: MemoryStore, opts: {
   const fd = openSync(opts.from, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
   const stream = createReadStream(opts.from, { fd, encoding: "utf8" });
   const result: ProjectImportResult = { applied: opts.confirm === true, project: opts.project, read: 0, added: 0, wouldAdd: 0,
-    skipped: { invalid: 0, policy: 0, other: 0 }, provenance: { source: {}, peer: {}, scope: {} }, warnings: [OPERATIONS_WARNING] };
+    skipped: { invalid: 0, policy: 0, other: 0 }, provenance: { source: {}, peer: {}, scope: {}, machine: {} }, warnings: [OPERATIONS_WARNING] };
   let header = false, bytes = 0;
   let aliases: string[] = [];
-  const pending = new Map<string, ImportedNote>(), accepted: ImportedNote[] = [];
+  const pending = new Map<string, ImportedNote>(), accepted = new Map<string, ImportedNote>();
   try {
     const stat = fstatSync(fd);
     if (!stat.isFile() || stat.size > PROJECT_IMPORT_MAX_BYTES) throw new Error("project import needs a regular JSONL file of at most 64 MiB");
@@ -121,22 +126,34 @@ export async function importProject(store: MemoryStore, opts: {
     if (!header) throw new Error("project import has no header");
 
     for (const imported of pending.values()) {
-      if (["supersedes", "promotedFrom"].some(field => {
-        const target = imported.note[field as "supersedes" | "promotedFrom"] as string | null | undefined;
-        return target !== undefined && target !== null && !pending.has(target);
-      })) {
+      if (relationTargets(imported).some(target => !pending.has(target))) {
         result.skipped.invalid++;
         continue;
       }
       const screened = stripPrivateDeep(imported.note);
       if (looksSecret(JSON.stringify(screened)) || !await opts.policy(screened)) { result.skipped.policy++; continue; }
-      accepted.push(imported);
+      accepted.set(imported.id, imported);
+    }
+    // A policy-refused target cannot authorize its dependents. Propagate removals before any append,
+    // regardless of file order, in linear time even when a long relation chain is refused.
+    const dependents = new Map<string, string[]>(), refused: string[] = [];
+    for (const imported of accepted.values()) for (const target of relationTargets(imported)) {
+      const rows = dependents.get(target) ?? [];
+      rows.push(imported.id); dependents.set(target, rows);
+      if (!accepted.has(target)) refused.push(imported.id);
+    }
+    for (let at = 0; at < refused.length; at++) {
+      const id = refused[at]!;
+      if (!accepted.delete(id)) continue;
+      result.skipped.invalid++;
+      for (const dependent of dependents.get(id) ?? []) refused.push(dependent);
     }
-    result.provenance = provenance(accepted);
+    result.provenance = provenance(accepted.values());
     const existing = new Set(store.portableNotes(opts.project).map(note => note.id));
-    result.wouldAdd = accepted.filter(note => !existing.has(note.id)).length;
+    result.wouldAdd = [...accepted.keys()].filter(id => !existing.has(id)).length;
     if (opts.confirm === true) {
-      for (const imported of accepted) {
+      store.assertImportable([...accepted.values()].map(imported => imported.note));
+      for (const imported of accepted.values()) {
         const written = store.importNote(imported.note, imported.at, { machine: imported.machine, expectedId: imported.id });
         if (written.added) result.added++;
       }

package/src/memory/search-fts.ts

@@ -1,3 +1,4 @@
+import { rankedScoreSql, rankedScoreSqlDetails, type ScoreFactors } from "./search-score.ts";
 import { Database } from "bun:sqlite";
 import { chmodSync, existsSync } from "node:fs";
 import { join } from "node:path";
@@ -187,6 +188,8 @@ export class SearchIndex {
   close(): void { this.db?.close(); }
 }
 
+const SCREENED_SCORE = rankedScoreSql(), SCREENED_SUBSTRING_SCORE = rankedScoreSql("-1.0");
+
 /** Screened query-local corpus in SQLite-owned TEMP storage, removed even when the process exits. */
 export class ScreenedSearchIndex<T> {
   readonly available = fts5Available();
@@ -222,15 +225,21 @@ export class ScreenedSearchIndex<T> {
     })();
   }
 
-  best(query: string, limit: number, now: number, useFts = this.available): { value: T; score: number }[] {
+  best(query: string, limit: number, now: number, useFts = this.available, explain = false): { value: T; score: number; scoreDetails?: ScoreFactors }[] {
     if (useFts && !ftsTerms(query)) return [];
-    const rank = useFts ? "-bm25(docs)" : "1.0";
+    const score = useFts ? SCREENED_SCORE : SCREENED_SUBSTRING_SCORE;
     const instant = new Date(now).toISOString();
     const where = "WHERE (expires IS NULL OR expires > ?)" + (useFts ? " AND docs MATCH ?" : "");
-    const rows = this.db.query(`SELECT payload, ${rank} * CASE tier WHEN 'long' THEN 1.0 WHEN 'capture' THEN 0.5 ELSE 0.9 END
-      / (1 + max(0, (julianday(?) - julianday(at)) / 30.0)) AS score FROM docs ${where} ORDER BY score DESC, ref LIMIT ?`)
-      .all(instant, now, ...(useFts ? [ftsTerms(query)] : []), limit) as { payload: string; score: number }[];
-    return rows.map(row => ({ value: JSON.parse(row.payload) as T, score: row.score }));
+    const factors = explain ? rankedScoreSqlDetails(useFts ? "bm25(docs)" : "-1.0", useFts) : undefined;
+    const columns = factors ? `, ${factors.rawBm25Rank} AS rawBm25Rank, ${factors.tierFactor} AS tierFactor, ${factors.recencyFactor} AS recencyFactor` : "";
+    const statement = this.db.query(`SELECT payload, ${score} AS score${columns} FROM docs ${where} ORDER BY score DESC, ref LIMIT ?`);
+    const rows = (explain ? statement.all(instant, instant, now, ...(useFts ? [ftsTerms(query)] : []), limit)
+      : statement.all(instant, now, ...(useFts ? [ftsTerms(query)] : []), limit)) as { payload: string; score: number; rawBm25Rank?: number | null; tierFactor?: number | null; recencyFactor?: number | null }[];
+    return rows.map(row => {
+      const hit: { value: T; score: number; scoreDetails?: ScoreFactors } = { value: JSON.parse(row.payload) as T, score: row.score };
+      if (explain) hit.scoreDetails = { rawBm25Rank: row.rawBm25Rank ?? null, tierFactor: row.tierFactor ?? null, recencyFactor: row.recencyFactor ?? null, finalScore: row.score, matchMode: useFts ? "fts5" : "substring" };
+      return hit;
+    });
   }
 
   close(): void {

package/src/memory/search-score.ts

@@ -0,0 +1,66 @@
+/** One fixed score recipe for numeric library ranking and native screened SQL. */
+export interface ScoreFactors {
+  rawBm25Rank: number | null;
+  tierFactor: number | null;
+  recencyFactor: number | null;
+  finalScore: number | null;
+  matchMode: "fts5" | "substring";
+}
+export interface SearchScoreDetails extends ScoreFactors { source: "curated" | "capture" | "repo" }
+
+type ScoreExpr = { op: "rank" | "tier" | "age" } | { op: "constant"; value: number }
+  | { op: "negative" | "reciprocal"; value: ScoreExpr }
+  | { op: "add" | "multiply" | "max"; left: ScoreExpr; right: ScoreExpr };
+const MONTH_DAYS = 30;
+const TIER_WEIGHTS: Readonly<Record<string, number>> = { long: 1, capture: 0.5 };
+const DEFAULT_TIER_WEIGHT = 0.9;
+const TIER_FACTOR: ScoreExpr = { op: "tier" };
+const DENOMINATOR: ScoreExpr = { op: "add", left: { op: "constant", value: 1 }, right: { op: "max", left: { op: "constant", value: 0 }, right: { op: "age" } } };
+const RECENCY_FACTOR: ScoreExpr = { op: "reciprocal", value: DENOMINATOR };
+const SCORE: ScoreExpr = { op: "multiply", left: { op: "multiply", left: { op: "negative", value: { op: "rank" } }, right: TIER_FACTOR }, right: RECENCY_FACTOR };
+// ponytail: this represents only the fixed rank/tier/age recipe, not arbitrary expressions;
+// extend its operations with numeric/SQL parity tests when the ranking contract changes.
+function numeric(expr: ScoreExpr, rank: number, tier: string, at: string, now: number): number {
+  switch (expr.op) {
+    case "rank": return rank;
+    case "tier": return Object.hasOwn(TIER_WEIGHTS, tier) ? TIER_WEIGHTS[tier]! : DEFAULT_TIER_WEIGHT;
+    case "age": return (now - Date.parse(at)) / (MONTH_DAYS * 24 * 3600_000);
+    case "constant": return expr.value;
+    case "negative": return -numeric(expr.value, rank, tier, at, now);
+    case "reciprocal": return 1 / numeric(expr.value, rank, tier, at, now);
+    case "add": return numeric(expr.left, rank, tier, at, now) + numeric(expr.right, rank, tier, at, now);
+    case "multiply": return numeric(expr.left, rank, tier, at, now) * numeric(expr.right, rank, tier, at, now);
+    case "max": return Math.max(numeric(expr.left, rank, tier, at, now), numeric(expr.right, rank, tier, at, now));
+  }
+}
+const real = (value: number): string => Number.isInteger(value) ? `${value}.0` : String(value);
+function sql(expr: ScoreExpr, rank: string): string {
+  const get = (part: ScoreExpr): string => sql(part, rank);
+  switch (expr.op) {
+    case "rank": return rank;
+    case "tier": return `CASE tier ${Object.entries(TIER_WEIGHTS).map(([name, value]) => `WHEN '${name}' THEN ${real(value)}`).join(" ")} ELSE ${real(DEFAULT_TIER_WEIGHT)} END`;
+    case "age": return `((julianday(?) - julianday(at)) / ${real(MONTH_DAYS)})`;
+    case "constant": return real(expr.value);
+    case "negative": return `(-(${get(expr.value)}))`;
+    case "reciprocal": return `(1.0 / ${get(expr.value)})`;
+    case "add": return `(${get(expr.left)} + ${get(expr.right)})`;
+    // Preserve the existing SQL quotient's floating-point order; numeric ranking
+    // retains its original reciprocal product. Both interpret the same recipe.
+    case "multiply": return expr.right.op === "reciprocal" ? `(${get(expr.left)} / ${get(expr.right.value)})` : `(${get(expr.left)} * ${get(expr.right)})`;
+    case "max": return `max(${get(expr.left)}, ${get(expr.right)})`;
+  }
+}
+export function rankedScore(rank: number, tier: string, at: string, now: number): number {
+  return numeric(SCORE, rank, tier, at, now);
+}
+/** SQL uses fixed internal identifiers and bound clock values, never interpolated row/query input. */
+export function rankedScoreSql(rank = "bm25(docs)"): string { return sql(SCORE, rank); }
+export function rankedScoreSqlDetails(rank = "bm25(docs)", useFts = true): { rawBm25Rank: string; tierFactor: string; recencyFactor: string } {
+  return { rawBm25Rank: useFts ? rank : "NULL", tierFactor: sql(TIER_FACTOR, rank), recencyFactor: sql(RECENCY_FACTOR, rank) };
+}
+export function rankedScoreDetails(source: SearchScoreDetails["source"], rank: number, tier: string, at: string, now: number, finalScore: number): SearchScoreDetails {
+  return { source, rawBm25Rank: rank, tierFactor: numeric(TIER_FACTOR, rank, tier, at, now), recencyFactor: numeric(RECENCY_FACTOR, rank, tier, at, now), finalScore, matchMode: "fts5" };
+}
+export function unrankedScoreDetails(source: SearchScoreDetails["source"], finalScore: number | null): SearchScoreDetails {
+  return { source, rawBm25Rank: null, tierFactor: null, recencyFactor: null, finalScore, matchMode: "substring" };
+}

package/src/memory/store.ts

@@ -10,6 +10,8 @@ import { memoryHome } from "./home.ts";
 import { machineId, type Machine } from "./machine.ts";
 import { assertProjectActive } from "./lifecycle.ts";
 export { machineId, type Machine } from "./machine.ts";
+import { rankedScore, rankedScoreDetails, unrankedScoreDetails, type SearchScoreDetails } from "./search-score.ts";
+export type { SearchScoreDetails } from "./search-score.ts";
 import { readWindowSql, readRef, type ReadWindow, type ReadRef, SearchIndex, captureSearch } from "./search-fts.ts";
 import { assertCuratedShardPaths, ensureShardDescriptor, readShardDescriptor, readShardedSelection, aliasedKeys, resolveAlias, resolveShardProfile, shardDir, shardKeyHash, shardMachineDir, userShardDir } from "./shard.ts";
 import { readCaptureConfig, type CaptureRow } from "./capture.ts";
@@ -168,10 +170,12 @@ export interface Filter { project?: string; tier?: Tier; kind?: Kind; peer?: str
 /** #13 search: `Filter` plus the capture-tier switch (on by default; capture is recall, never curated evidence). */
 export interface SearchFilter extends Filter {
   includeCapture?: boolean;
+  /** Attach score factors only when explicitly requested. */
+  explain?: boolean;
   /** A host that writes capture with a `retentionDays` override passes the same value here; files decide otherwise. */
   captureRetentionDays?: number;
 }
-export interface SearchHit { source: "curated" | "capture"; score: number; view?: View; capture?: CaptureRow }
+export interface SearchHit { source: "curated" | "capture"; score: number; scoreDetails?: SearchScoreDetails; view?: View; capture?: CaptureRow }
 export interface SearchResult { engine: "fts5" | "substring"; hits: SearchHit[] }
 export interface Graph { nodes: { id: Node; type: string; label: string; kind?: string; tier?: Tier }[]; edges: { from: Node; to: Node; rel: string }[] }
 
@@ -490,18 +494,30 @@ export class MemoryStore {
   // `ownClock`: a note asked for short-term on purpose expires on its own clock, open task or not, and is never promoted.
   note(n: NoteInput, ownClock = false): string { return this.append(n.tier === "short" && !n.expires && (ownClock || !n.task || this.settled(n.task)) ? { ...n, expires: this.until() } : n, n.tier === "short"); }
 
-  /**
-   * An entry from another store with its own time (`ahub memory import claude-mem`): the same source row always gives
-   * the same id, so a second import writes nothing. Returns the id and whether it was new.
-   */
-  importNote(n: NoteInput, at: string, identity: { machine?: string; expectedId?: string } = {}): { id: string; added: boolean } {
+  /** The already-opened owner of an imported row, shared by preflight and append. */
+  private importOwner(n: NoteInput): MemoryStore {
     if (this.bootstrapOnly) throw new Error("migration bootstrap cannot import memory");
-    if (this.userOverlay && n.scope === "shared") return this.userOverlay.importNote(n, at, identity);
+    if (this.userOverlay && n.scope === "shared") return this.userOverlay.importOwner(n);
     if (this.profile.sharded && !this.profile.shardUser && n.scope === "project" && n.project !== this.profile.shardKey) {
       const owner = this.aliasStores.find(store => store.profile.shardKey === n.project);
-      if (owner) return owner.importNote(n, at, identity);
+      if (owner) return owner.importOwner(n);
     }
     if (this.profile.sharded && (this.profile.shardUser ? n.scope !== "shared" : n.scope !== "project" || n.project !== this.profile.shardKey)) throw new Error("entry does not belong to this curated shard");
+    return this;
+  }
+
+  /** Check every import route before a multi-row caller appends; never creates a missing alias shard. */
+  assertImportable(notes: Iterable<NoteInput>): void {
+    for (const note of notes) this.importOwner(note);
+  }
+
+  /**
+   * An entry from another store with its own time (`ahub memory import claude-mem`): the same source row always gives
+   * the same id, so a second import writes nothing. Returns the id and whether it was new.
+   */
+  importNote(n: NoteInput, at: string, identity: { machine?: string; expectedId?: string } = {}): { id: string; added: boolean } {
+    const owner = this.importOwner(n);
+    if (owner !== this) return owner.importNote(n, at, identity);
     assertSharedV1Op(n.op);
     // A fixed machine: the same observation imported on two machines is one entry once they sync. A project import preserves the exported identity instead.
     const body = { schema: MEMORY_SCHEMA, at, machine: identity.machine ?? "claude-mem", ...n, text: stripPrivateSpans(n.text).slice(0, MAX_TEXT), ...(n.title ? { title: stripPrivateSpans(n.title).slice(0, MAX_TITLE) } : {}) } as Omit<Entry, "id">;
@@ -1057,12 +1073,15 @@ export class MemoryStore {
    */
   search(q: string, f: SearchFilter = {}): SearchResult {
     const limit = f.limit ?? 200;
-    if (!this.searchIndex.available) return { engine: "substring", hits: this.list({ ...f, q }).map((view) => ({ source: "curated" as const, score: 0, view })) };
+    if (!this.searchIndex.available) return { engine: "substring", hits: this.list({ ...f, q }).map(view => {
+      const hit: SearchHit = { source: "curated", score: 0, view };
+      if (f.explain) hit.scoreDetails = unrankedScoreDetails("curated", hit.score);
+      return hit;
+    }) };
     const visible = new Map(this.live(f).filter((v) => (!f.project || this.inScope(v.project, f.project) || v.scope === "shared")
       && (!f.since || Date.parse(v.at) >= Date.parse(f.since)) && (f.includeSuperseded || !v.supersededBy)).map((v) => [v.id, v]));
     for (const store of this.readStores()) store.syncSearchIndex();
     const now = this.now();
-    const recency = (at: string): number => 1 / (1 + Math.max(0, now - Date.parse(at)) / (30 * 24 * 3600_000));
     const hits: SearchHit[] = [];
     // The project filter runs inside the FTS query (its rows plus shared ones), so a busy sibling project can never
     // starve this project's LIMIT.
@@ -1082,7 +1101,9 @@ export class MemoryStore {
           if (!view || seen.has(hit.ref)) continue;
           seen.add(hit.ref);
           found++;
-          hits.push({ source: "curated", score: -hit.rank * (view.tier === "long" ? 1 : 0.9) * recency(hit.at), view });
+          const selected: SearchHit = { source: "curated", score: rankedScore(hit.rank, view.tier, hit.at, now), view };
+          if (f.explain) selected.scoreDetails = rankedScoreDetails("curated", hit.rank, view.tier, hit.at, now, selected.score);
+          hits.push(selected);
         }
         if (ranked.length < page) break;
       }
@@ -1097,12 +1118,18 @@ export class MemoryStore {
       const retained = Number.isFinite(cutoff.getTime()) ? cutoff.toISOString() : undefined;
       const since = f.since && Number.isFinite(Date.parse(f.since)) ? new Date(Date.parse(f.since)).toISOString() : undefined;
       for (const { row, rank } of captureSearch(shard, q, Math.max(limit * 4, 32), since && (!retained || since > retained) ? since : retained)) {
-        hits.push({ source: "capture", score: -rank * 0.5 * recency(row.at), capture: row });
+        const selected: SearchHit = { source: "capture", score: rankedScore(rank, "capture", row.at, now), capture: row };
+        if (f.explain) selected.scoreDetails = rankedScoreDetails("capture", rank, "capture", row.at, now, selected.score);
+        hits.push(selected);
       }
     }
     // Where FTS misses entirely (a stopword-only query, a tokenization edge), the substring filter is the safety net.
     if (!hits.length && q.trim()) {
-      for (const view of this.list({ ...f, q })) hits.push({ source: "curated", score: 0, view });
+      for (const view of this.list({ ...f, q })) {
+        const hit: SearchHit = { source: "curated", score: 0, view };
+        if (f.explain) hit.scoreDetails = unrankedScoreDetails("curated", hit.score);
+        hits.push(hit);
+      }
     }
     const ref = (h: SearchHit): string => h.view?.id ?? String(h.capture?.id ?? 0).padStart(12, "0");
     hits.sort((a, b) => b.score - a.score || ref(a).localeCompare(ref(b)));