@staix/agent-mem 0.9.1 → 0.11.0

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/capture.ts

@@ -619,17 +619,15 @@ export class CaptureStore {
   /** Exact-project, bounded body pages; MCP screens before filling its public candidate window. */
   readPage(window: ReadWindow & { query?: string; match?: "substring" }): { rows: CaptureRow[]; next?: ReadRef; engine?: "fts5" | "substring" } {
     this.checkReadBinding();
-    const { columns, where, bind } = readWindowSql(window, "id");
+    const { columns, where, bind } = readWindowSql(window, "id", "integer");
     if (this.recentReadIds) {
       if (window.query !== undefined) throw new Error("recent capture brief does not support query indexes");
       where.push("id IN (SELECT value FROM json_each(?))"); bind.push(JSON.stringify(this.recentReadIds));
     }
     const engine = window.query === undefined ? undefined : window.match !== "substring" && this.ensureMcpFts() ? "fts5" : "substring";
-    if (window.query !== undefined && engine === "fts5") {
-      const match = ftsTerms(window.query); if (!match) return { rows: [], engine };
-      where.push("id IN (SELECT rowid FROM mcp_fts WHERE mcp_fts MATCH ?)"); bind.push(match);
-    }
-    const rows = this.db.query(`SELECT *, ${columns} FROM rows WHERE ${where.join(" AND ")} ORDER BY candidate_position, candidate_id LIMIT ?`)
+    const plan = captureReadPlan(window, engine, where, bind);
+    if (!plan) return { rows: [], engine };
+    const rows = this.db.query(`SELECT rows.*, ${columns} FROM ${plan.from} WHERE ${where.join(" AND ")} ORDER BY ${plan.order} LIMIT ?`)
       .all(...bind, window.limit) as (RawRow & { candidate_id: string; candidate_position: number })[];
     return { rows: rows.map(toRow), ...(engine ? { engine } : {}), ...(rows.length ? { next: readRef(rows[rows.length - 1]!) } : {}) };
   }
@@ -644,6 +642,26 @@ export class CaptureStore {
   close(): void { this.db.close(); }
 }
 
+/** Keep chronological readers intact while exhaustive search consumes FTS's rowid range directly. */
+function captureReadPlan(window: ReadWindow & { query?: string; match?: "substring" }, engine: "fts5" | "substring" | undefined,
+  where: string[], bind: (string | number)[]): { from: string; order: string } | undefined {
+  let from = "rows", order = "candidate_position, candidate_id";
+  if (window.query !== undefined && engine === "fts5") {
+    const match = ftsTerms(window.query); if (!match) return;
+    if (window.order === "id") {
+      from = "mcp_fts JOIN rows ON rows.id = mcp_fts.rowid"; order = "mcp_fts.rowid";
+      where.push("mcp_fts MATCH ?"); bind.push(match);
+      if (window.after) {
+        const cursor = where.indexOf("id > ?");
+        if (cursor < 0) throw Error("missing capture identity cursor");
+        // Qualify the existing predicate so FTS receives the rowid range, without a second condition/bind.
+        where[cursor] = "mcp_fts.rowid > ?";
+      }
+    } else { where.push("id IN (SELECT rowid FROM mcp_fts WHERE mcp_fts MATCH ?)"); bind.push(match); }
+  }
+  return { from, order };
+}
+
 /** One shard's capture totals for the catalog and the capacity advisor, without opening a writer. */
 export function captureShardStats(dir: string): { rows: number; bytes: number; lastAt: string | null } {
   if (!existsSync(join(dir, "capture.db"))) return { rows: 0, bytes: 0, lastAt: null };

package/src/memory/commands.ts

@@ -15,6 +15,10 @@ export const AMEM_NAMES: CommandNames = { memory: "amem", goal: "amem goal" };
 export interface MemoryCommandOptions {
   /** Host-authenticated person intent. Never accept this from model arguments. Required for retained history/as-of. */
   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. */
@@ -67,6 +71,11 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
   const sub = rest[0] && !rest[0].startsWith("--") ? rest.shift()! : "list";
   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);
@@ -89,8 +98,16 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
         if (kind && !KINDS.includes(kind as Kind)) fail(`--kind takes ${KINDS.join(", ")}`);
         if (limit && !(Number(limit) > 0)) fail("--limit takes a positive number");
         const q = sub === "search" ? rest.join(" ") : undefined;
-        const state = recallRows(store, project, { person: opts.person, history, asOf, query: q, limit: Number.MAX_SAFE_INTEGER });
-        const all = state.views.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 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 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);
         if (history || asOf !== undefined) {
@@ -99,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. */
@@ -88,7 +97,7 @@ export interface EvalQuestionResult {
 /** `recall` and `hit` are null when no question counts (no answerable question), never 0: an empty average is not a measured zero. */
 export interface EvalAggregate { questions: number; recall: Record<number, number | null>; hit: Record<number, number | null>; mrr: number | null }
 export interface EvalReport {
-  /** The search that was scored: the ranked, project-scoped `store.search` (BM25 with tier and recency weights) that MCP and hub recall use, NOT the `amem search` command's substring filter. */
+  /** Ranked project-scoped `store.search` (BM25 with tier and recency weights), the engine used by default current curated `amem search`; `--filter` keeps legacy substring matching. */
   engine: string;
   ks: number[];
   /** Every question. A question whose expected entry is not in the store scores 0, as a search that cannot find it would. */
@@ -142,7 +151,7 @@ const pct = (value: number | null): string => value === null ? "  n/a" : value.t
 export function evalText(report: EvalReport, label: string): string {
   const head = (name: string, row: EvalAggregate) => `${name.padEnd(11)} ${String(row.questions).padStart(4)}  ${report.ks.map(k => `${pct(row.recall[k] ?? null)}/${pct(row.hit[k] ?? null)}`.padStart(13)).join(" ")}  ${pct(row.mrr).padStart(6)}`;
   return [
-    `eval: ${label} (${report.engine === "substring" ? "substring fallback" : "ranked store.search, engine " + report.engine}; this is the ranking MCP and hub recall use, not the \`amem search\` filter)`,
+    `eval: ${label} (${report.engine === "substring" ? "substring fallback" : "ranked store.search, engine " + report.engine}; same ranked search path as default \`amem search\`; \`--filter\` keeps legacy substring matching)`,
     `${"".padEnd(11)} ${"n".padStart(4)}  ${report.ks.map(k => `@${k} recall/hit`.padStart(13)).join(" ")}  ${"MRR".padStart(6)}`,
     head("all", report.all),
     head("answerable", report.answerable),

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/policy.ts

@@ -99,6 +99,7 @@ function literals(value: unknown, label: string): string[] {
 
 function defaultPii(text: string): boolean {
   if (/\b(?:\d{6}-\d{7}|\d{3}-\d{2}-\d{4})\b/.test(text)) return true;
+  if (!text.includes("@")) return false;
   // Bound each email candidate before matching; arbitrary user regexes are never run.
   for (const token of text.split(/[\s<>()\[\]{}",;:]+/)) if (token.includes("@")) {
     if (token.length > 320 || /[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}/i.test(token)) return true;
@@ -106,6 +107,51 @@ function defaultPii(text: string): boolean {
   return false;
 }
 
+interface DefaultPathProbe { names: string[]; segments: string[] }
+
+/** A mandatory literal, not a deny verdict. All other regex grammar uses the canonical checker. */
+function necessaryDenyLiteral(source: string): string | undefined {
+  if (source.length > 256) return;
+  let index = source.startsWith("^") ? 1 : 0, literal = "";
+  for (; index < source.length; index++) {
+    const character = source[index]!;
+    if (/^[A-Za-z0-9_-]$/.test(character)) literal += character;
+    else if (character === "\\" && source[index + 1] === ".") { literal += "."; index++; }
+    else break;
+  }
+  const rest = source.slice(index);
+  return literal && (rest === "" || rest === "$" || rest === "(\\.|$)") ? literal : undefined;
+}
+
+/** Do not add getter reads or assumptions about malformed/mutated exported defaults. */
+function plainDefaultStrings(values: readonly string[]): boolean {
+  if (types.isProxy(values) || !Array.isArray(values) || Object.getPrototypeOf(values) !== Array.prototype || values.length > 64 || Object.getOwnPropertySymbols(values).length || "toJSON" in values) return false;
+  if (Object.getOwnPropertyNames(values).length !== values.length + 1) return false;
+  for (let index = 0; index < values.length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(values, String(index));
+    if (!descriptor || !("value" in descriptor) || typeof descriptor.value !== "string") return false;
+  }
+  return true;
+}
+
+function defaultPathProbe(): DefaultPathProbe | undefined {
+  const needles = DENY_NAMES.map(necessaryDenyLiteral);
+  return needles.every((value): value is string => value !== undefined) ? { names: needles, segments: [...DENY_SEGMENTS] } : undefined;
+}
+
+function containsPathLiteral(text: string, probe: DefaultPathProbe, deny: readonly string[]): boolean {
+  return text.includes("/.") || text.includes("//") || deny.some(entry => text.includes(entry))
+    || probe.segments.some(entry => text.includes(entry)) || probe.names.some(needle => text.includes(needle));
+}
+
+function mayNeedPathCheck(text: string, probe: DefaultPathProbe | undefined, deny: readonly string[]): boolean {
+  if (!probe || containsPathLiteral(text, probe, deny)) return true;
+  // Raw/node/token paths are substrings of text; pathCandidates takes substrings after NFC.
+  // Inspect both: removing ignorables or lowercasing after NFKC can leave a non-NFC result.
+  const canonical = text.normalize("NFC");
+  return canonical !== text && containsPathLiteral(canonical, probe, deny);
+}
+
 /** No filesystem, model, network or storage work occurs while constructing or screening this policy. */
 export function createStandalonePolicy(options: StandalonePolicyOptions = {}): StandalonePolicy {
   if (!options || typeof options !== "object" || types.isProxy(options) || Object.getPrototypeOf(options) !== Object.prototype || Object.getOwnPropertySymbols(options).length) throw new Error("invalid standalone policy options");
@@ -119,16 +165,23 @@ export function createStandalonePolicy(options: StandalonePolicyOptions = {}): S
   // Evict the batch when full; a measured need for better hit rates can upgrade this to an LRU.
   const textChecks = new Map<string, boolean>(); let textBytes = 0;
   let defaultDenyRevision = "";
+  // ponytail: the negative probe supports at most 64 dense default entries and 256-character simple name sources.
+  // Everything else falls back; extend the grammar only with differential proof, never an approximate verdict.
+  let pathProbe: DefaultPathProbe | undefined;
+  let defaultsWerePlain = false;
   const publicText = (text: string): boolean => {
     const cached = textChecks.get(text);
     if (cached !== undefined) return cached;
     const check = () => {
-      if (looksSecret(text) || looksSecret(text.replace(/["']/g, ""))) return false;
+      if (looksSecret(text)) return false;
+      const unquoted = text.replace(/["']/g, "");
+      if (unquoted !== text && looksSecret(unquoted)) return false;
       const normalized = fold(text);
       if (defaultPii(normalized) || pii.some(pattern => normalized.includes(pattern))) return false;
+      if (!mayNeedPathCheck(normalized, pathProbe, deny)) return true;
       const candidates = normalized.includes("/") || /\.[a-z]/.test(normalized) ? pathCandidates(normalized) : [];
       const paths = [normalized, nodePath(normalized), ...candidates, ...normalized.split(/[\s"'`(){}\[\],;:=<>]+/)];
-      return !paths.some(path => path && isDenied(posix.normalize(path), deny));
+      return ![...new Set(paths)].some(path => path && isDenied(posix.normalize(path), deny));
     };
     const allowed = check(), bytes = Buffer.byteLength(text);
     if (bytes <= 1024) {
@@ -140,8 +193,14 @@ export function createStandalonePolicy(options: StandalonePolicyOptions = {}): S
   const standalone = (value: unknown): { ok: boolean; value?: unknown } => {
     try {
       // The exported default lists can be tightened by a host between calls.
+      // A getter can change behavior without changing its first serialized value: validate shape every time.
+      const defaultsPlain = plainDefaultStrings(DENY_NAMES) && plainDefaultStrings(DENY_SEGMENTS);
       const revision = JSON.stringify([DENY_NAMES, DENY_SEGMENTS]);
-      if (revision !== defaultDenyRevision) { textChecks.clear(); textBytes = 0; defaultDenyRevision = revision; }
+      const changed = revision !== defaultDenyRevision;
+      if (changed) { textChecks.clear(); textBytes = 0; defaultDenyRevision = revision; }
+      if (!defaultsPlain) pathProbe = undefined;
+      else if (changed || !defaultsWerePlain) pathProbe = defaultPathProbe();
+      defaultsWerePlain = defaultsPlain;
       const complete = snapshot(value);
       if (!complete) return { ok: false };
       // Only pure text checks are reused. Shape/bounds/private flags and the host's detached