@staix/agent-mem 0.1.1 → 0.2.0

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.1.1. Requires Bun 1.4.2 or later; no runtime dependencies.
+Version: 0.2.0. Requires Bun 1.4.2 or later; no runtime dependencies.
 
 ## Install
 
@@ -46,6 +46,29 @@ amem sync --remote <private-git-url> --policy-free
 
 Use `ahub memory` for the policy-applying path. `--policy-free` does not bypass the secret screen or the sync remote's privacy checks. Forgetting a shared note appends an operation; its previous content remains in the remote's git history.
 
+## Candidate review
+
+`amem review` lists this project's pending machine-local candidates. They are proposals, not memory notes and not evidence. Use JSON to inspect the complete candidate payload before accepting or rejecting its full 64-character ID:
+
+```sh
+amem review --json
+amem review list --kind correction --status all --limit 50 --json
+amem review accept <full-candidate-id> --policy-free --json
+amem review reject <full-candidate-id> --json
+```
+
+All review commands remain person-only; acceptance and rejection require a terminal on stdin. Acceptance additionally requires `--policy-free`, acknowledging that the standalone CLI cannot apply a host's privacy policy; use `ahub memory` for the host policy path. The CLI refuses secret-looking candidate input or proposed note content. Listing does not open the ordinary memory index, and acceptance defers unrelated held-note promotions.
+
+Candidates live in `candidates.db` beside the memory logs. This sidecar is machine-local: it is never synced, imported, or read by recall, briefs, ask or graph evidence. Hosts must supply an explicit public privacy verdict before putting candidates or counters; private, PII and unknown verdicts are refused. Library APIs are available, but this phase adds no automatic candidate producer or telemetry consumer. Candidate retention is 500 per project and 30 days; counters retain 10,000 per project and 90 days. Candidate payloads are capped at 16 KiB.
+
+Acceptance creates ordinary v1 memory data. A correction retains its target's scope, project and storage reach, writes the corrected note and applies the existing `supersede` operation; its exact current target revision must match. A local target stays short-term; a synced target stays synced, including a demoted target whose effective tier is short. A fail becomes a long-term project note. The accepted text binds the candidate ID, target revision and target ID; a fail proposal without a target records `none` for both target fields. Both paths require the actual MemoryStore promotion screen to return `promote` at acceptance time; `keep`, `skip` or an absent screen refuses acceptance without falling back to short-term storage. Accepted v1 notes and operations follow the existing storage and sync rules; the candidate/counter sidecar remains local and outside evidence. No new v1 operation is introduced. Decay candidates are listing-only and cannot be accepted; a person may separately choose `ahub memory demote` or `forget`. The sidecar receipt, note append and correction's supersede append are separate durable writes. An interrupted acceptance can leave a note without its supersede; it is held for explicit inspection and never replayed automatically.
+
+The library entry exports `CandidateStore({ home?, now? })`, `put(input, verdict)`, `recordCounter(key, values, verdict)`, and `accept(id, { project, actor, verdict, store, policy })`. `home` retains the parent-home convention (`<home>/memory`); the default uses `memoryHome()`. The host must authenticate person intent, bind the current project and privacy verdict, and supply a current acceptance policy plus the ordinary store's actual promotion screen. An `actor` string or caller-supplied public verdict alone is not authentication. Counter writes are idempotent snapshots for the same contextual key, not increments: observed `0` stays zero, while `null` means unknown (a later unknown value does not erase an observed value).
+
+Open a review-only `MemoryStore` with `deferPromotions: true` to prevent unrelated automatic promotions during construction and reads. Explicit candidate acceptance still runs its promotion screen. This package registers no capture observer or host candidate tools; capture exclusion and authenticated producers must be established by the host before those integrations are enabled.
+
+Acceptance normalizes its note once, including timestamp, content ID and short-term expiry, then screens and appends that exact body. The final target-revision check and correction appends hold the same machine-local `mutation-lock.db` writer transaction used by this version's ordinary memory, import and sync writers. This lock is independent of the derived index, so an ordinary write still persists when SQLite is busy. External or older writers that edit segments without this lock do not participate in serialization. The logs remain authoritative after an interrupted acceptance; the next read refreshes the derived index.
+
 ## Shell completion
 
 Generate completion for `zsh`, `bash`, or `fish` with `amem completion <shell>`. Generation prints a script to stdout; it does not install files or edit shell configuration. The following commands are for a person's terminal.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staix/agent-mem",
-  "version": "0.1.1",
+  "version": "0.2.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

@@ -1,6 +1,8 @@
 import { readFileSync } from "node:fs";
 import { MemoryStore, looksSecret } from "./memory/store.ts";
 import { rawMemoryCommand, rawGoalCommand } from "./memory/commands.ts";
+import { memoryProjectKey } from "./memory/project.ts";
+import { CandidateStore, type CandidateFilter } from "./memory/candidates.ts";
 
 import { commandHelp, parseCommand } from "./commands-table.ts";
 import { completionScript } from "./completion.ts";
@@ -31,12 +33,39 @@ export async function runCli(argv: readonly string[], context: CliContext = {}):
     throw error;
   }
   const { definition, options, rawArgs: args } = parsed;
-  const goal = parsed.path[0] === "goal", sub = goal ? parsed.path[1]! : parsed.path[0]!;
+  const goal = parsed.path[0] === "goal", review = parsed.path[0] === "review", sub = goal || review ? parsed.path[1]! : parsed.path[0]!;
   const policyFree = options["--policy-free"] === true;
   const mutating = definition.mutates === true || definition.mutates === "apply" && options["--apply"] === true || definition.mutates === "label" && options["--label"] !== undefined;
   if (mutating && !(context.stdinTTY ?? process.stdin.isTTY)) throw new Error("mutating commands require a terminal on stdin");
   if (definition.policyFree && !policyFree) {
-    throw new Error(`${sub} requires --policy-free; use ahub memory ${sub} to apply the host's privacy policy`);
+    throw new Error(review ? "review accept requires --policy-free; use ahub memory to apply the host's privacy policy" : `${sub} requires --policy-free; use ahub memory ${sub} to apply the host's privacy policy`);
+  }
+  if (review) {
+    const id = parsed.positionals[0];
+    if (sub !== "list" && (!id || !/^[a-f0-9]{64}$/.test(id))) throw new Error("review accept/reject requires a full 64-character candidate id");
+    const project = memoryProjectKey(context.cwd ?? process.cwd()), candidates = new CandidateStore();
+    try {
+      if (sub === "list") {
+        const rows = candidates.list({ project, ...(options["--status"] ? { status: options["--status"] as CandidateFilter["status"] } : {}),
+          ...(options["--kind"] ? { kind: options["--kind"] as CandidateFilter["kind"] } : {}), ...(options["--limit"] ? { limit: Number(options["--limit"]) } : {}) });
+        return options["--json"] ? JSON.stringify(rows, null, 2) : rows.length ? rows.map(candidate => `${candidate.id}  ${candidate.input.kind}  ${candidate.status}  ${candidate.createdAt}`).join("\n") : "no candidates waiting for review";
+      }
+      if (sub === "reject") {
+        candidates.reject(id!, { project, actor: "person", verdict: "public" });
+        return options["--json"] ? JSON.stringify({ candidateId: id, status: "rejected" }, null, 2) : `rejected candidate ${id}`;
+      }
+      const candidate = candidates.get(id!, project);
+      if (!candidate) throw new Error("candidate unavailable");
+      if (candidate.input.kind === "decay") throw new Error("decay candidates are listing-only; use ahub memory demote or forget after review");
+      // Candidate acceptance uses the actual secret screen; the core defers unrelated automatic promotions.
+      const store = new MemoryStore({ deferPromotions: true, screen: note => looksSecret(`${note.title ?? ""}\n${note.text}`) ? "keep" : "promote" });
+      try {
+        const result = candidates.accept(id!, { project, actor: "person", verdict: "public", store,
+          policy: (proposal, _target, note) => !looksSecret(JSON.stringify(proposal.input)) && !looksSecret(JSON.stringify(note)),
+        });
+        return options["--json"] ? JSON.stringify(result, null, 2) : `accepted candidate ${id} as ordinary v1 note ${result.noteId}`;
+      } finally { store.close(); }
+    } finally { candidates.close(); }
   }
   // ponytail: board task links need the host's authenticated task boundary; add a host bridge before supporting them here.
   if (goal && sub === "link") throw new Error("goal link needs host integration; use ahub goal link");

package/src/commands-table.ts

@@ -47,6 +47,14 @@ export const COMMANDS: Record<string, CommandDefinition> = {
     done: { description: "Complete a goal", args: [{ name: "id" }], mutates: true },
     take: { description: "Take a goal lease", options: { "--force": flag("Override the prior lease") }, args: [{ name: "id" }], mutates: true },
   } },
+  review: { description: "Review machine-local non-evidentiary candidates", options: json, defaultCommand: "list", commands: {
+    list: { description: "List review candidates", options: {
+      "--status": { description: "Candidate status", value: ["pending", "accepting", "accepted", "rejected", "all"] },
+      "--kind": { description: "Candidate kind", value: ["correction", "fail", "decay"] }, "--limit": text("Maximum candidates (1..500)"),
+    } },
+    accept: { description: "Accept one candidate through the current memory policy", options: policy, args: [{ name: "full-candidate-id" }], mutates: true, policyFree: true },
+    reject: { description: "Reject one candidate", args: [{ name: "full-candidate-id" }], mutates: true },
+  } },
   completion: { description: "Print static shell completion", args: [{ name: "shell", values: ["zsh", "bash", "fish"] }] },
   help: { description: "Show help" }, version: { description: "Show version" },
 };

package/src/index.ts

@@ -5,3 +5,4 @@ export * from "./memory/project.ts";
 export * from "./memory/home.ts";
 export * from "./memory/platform.ts";
 export * from "./memory/commands.ts";
+export * from "./memory/candidates.ts";

package/src/memory/candidates.ts

@@ -0,0 +1,196 @@
+import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { chmodSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { memoryHome } from "./home.ts";
+import { realPath } from "./platform.ts";
+import { MemoryStore, type NoteInput, type View } from "./store.ts";
+
+export const CANDIDATE_DB_BUSY_TIMEOUT_MS = 3000;
+export const CANDIDATE_RETENTION = { count: 500, ageMs: 30 * 86400_000 } as const;
+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 }
+export type CandidateInput = { project: string } & (
+  | { kind: "correction"; target: CandidateTarget; proposedText: string; reason: string; noteKind?: "decision" | "contract" | "fail" }
+  | { kind: "fail"; target?: CandidateTarget; approach: string; symptom: string; cause: string; evidenceRefs: string[]; retryWhen: string }
+  | { kind: "decay"; target: CandidateTarget; reason: string }
+);
+export type CandidateStatus = "pending" | "accepting" | "accepted" | "rejected";
+export interface Candidate { id: string; createdAt: string; status: CandidateStatus; input: CandidateInput; 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 }
+export interface Counter extends CounterValues { id: string; key: CounterKey; createdAt: string; rendered: number | null; delivered: number | null; cited: number | null }
+export interface CandidateAcceptance {
+  project: string;
+  /** The host binds this to authenticated person intent; it is not an authentication token. */
+  actor: "person" | "agent";
+  verdict: CandidateVerdict;
+  store: MemoryStore;
+  policy: (candidate: Candidate, target: View | undefined, note: NoteInput) => boolean;
+}
+export interface CandidateAcceptanceResult { candidateId: string; noteId: string; alreadyAccepted: boolean }
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.entries(value).filter(([, v]) => v !== undefined).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(",")}}`;
+  return JSON.stringify(value);
+}
+const hash = (value: unknown) => createHash("sha256").update(canonical(value)).digest("hex");
+const text = (value: unknown, max = 4000): value is string => typeof value === "string" && value.trim().length > 0 && value.length <= max && !value.includes("\0");
+const entryId = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{32}$/.test(value);
+const candidateId = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const publicOnly = (verdict: CandidateVerdict) => { if (verdict !== "public") throw new Error("candidate data refused by host privacy verdict"); };
+const personOnly = (actor: string) => { if (actor !== "person") throw new Error("candidate acceptance and rejection require a person"); };
+const validTarget = (value: CandidateTarget | undefined) => value !== undefined && entryId(value.id) && candidateId(value.revision);
+function validate(input: CandidateInput): void {
+  if (!input || !text(input.project, 400)) throw new Error("invalid candidate project");
+  if (input.kind === "correction") {
+    if (!validTarget(input.target) || !text(input.proposedText) || !text(input.reason) || input.noteKind !== undefined && !["decision", "contract", "fail"].includes(input.noteKind)) throw new Error("invalid correction candidate");
+  } else if (input.kind === "fail") {
+    if (input.target !== undefined && !validTarget(input.target) || ![input.approach, input.symptom, input.cause, input.retryWhen].every(x => text(x)) || !Array.isArray(input.evidenceRefs) || input.evidenceRefs.length < 1 || input.evidenceRefs.length > 16 || !input.evidenceRefs.every(x => text(x, 400))) throw new Error("invalid fail candidate");
+  } else if (input.kind === "decay") {
+    if (!validTarget(input.target) || !text(input.reason)) throw new Error("invalid decay candidate");
+  } else throw new Error("invalid candidate kind");
+  if (Buffer.byteLength(canonical(input), "utf8") > 16_384) throw new Error("candidate payload exceeds 16 KiB");
+}
+
+/** Includes current lifecycle state, so a changed promotion, supersession or demotion makes a proposal stale. */
+export function candidateTargetRevision(target: View): string {
+  return hash({ ...target, about: [...target.about].sort(), supersedes: [...target.supersedes].sort() });
+}
+
+function counterKey(key: CounterKey): CounterKey {
+  if (!key || !entryId(key.entryId) || !text(key.project, 400) || !text(key.deliveryId, 200)) throw new Error("invalid counter key");
+  for (const value of [key.task, key.turn, key.session]) if (value !== undefined && value !== null && !text(value, 400)) throw new Error("invalid counter context");
+  return { entryId: key.entryId, project: key.project, task: key.task ?? null, turn: key.turn ?? null, session: key.session ?? null, deliveryId: key.deliveryId };
+}
+
+/** Explicitly opened machine-local data. Importing this module never opens a store or registers a consumer. */
+export class CandidateStore {
+  readonly dir: string;
+  readonly path: string;
+  private readonly db: Database;
+  private readonly now: () => number;
+  constructor(options: { home?: string; now?: () => number } = {}) {
+    this.dir = options.home === undefined ? memoryHome() : join(options.home, "memory");
+    this.now = options.now ?? Date.now;
+    mkdirSync(this.dir, { recursive: true, mode: 0o700 }); chmodSync(this.dir, 0o700);
+    this.path = join(this.dir, "candidates.db");
+    this.db = new Database(this.path, { create: true });
+    this.db.run(`PRAGMA busy_timeout = ${CANDIDATE_DB_BUSY_TIMEOUT_MS}`);
+    chmodSync(this.path, 0o600); this.db.run("PRAGMA journal_mode = WAL");
+    this.db.run("CREATE TABLE IF NOT EXISTS candidates (id TEXT PRIMARY KEY, project TEXT NOT NULL, kind TEXT NOT NULL, payload TEXT NOT NULL, at INTEGER 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(); }
+  private prune(): void {
+    this.db.transaction(() => {
+      for (const [table, retention] of [["candidates", CANDIDATE_RETENTION], ["counters", COUNTER_RETENTION]] as const) {
+        this.db.query(`DELETE FROM ${table} WHERE at <= ?`).run(this.now() - retention.ageMs);
+        this.db.query(`DELETE FROM ${table} WHERE rowid IN (SELECT rowid FROM (SELECT rowid, row_number() OVER (PARTITION BY project ORDER BY at DESC, rowid DESC) AS rank FROM ${table}) WHERE rank > ?)`).run(retention.count);
+      }
+    }).immediate();
+  }
+  private decode(row: { id: string; payload: string; at: number; status: CandidateStatus; note_id: string | null }): Candidate {
+    const input = JSON.parse(row.payload) as CandidateInput; validate(input);
+    if (hash({ schema: "agent-mem.candidate/v1", input }) !== row.id) throw new Error("candidate content hash mismatch");
+    return { id: row.id, createdAt: new Date(row.at).toISOString(), status: row.status, input, acceptedNoteId: row.note_id };
+  }
+  put(input: CandidateInput, verdict: CandidateVerdict): string {
+    publicOnly(verdict); validate(input); this.prune();
+    const payload = canonical(input), id = hash({ schema: "agent-mem.candidate/v1", input });
+    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;
+  }
+  get(id: string, project: string): Candidate | undefined {
+    if (!candidateId(id) || !text(project, 400)) throw new Error("invalid candidate identity");
+    this.prune();
+    const row = this.db.query("SELECT * FROM candidates WHERE id = ? AND project = ?").get(id, project) as Parameters<CandidateStore["decode"]>[0] | null;
+    return row ? this.decode(row) : 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"].includes(filter.kind)) throw new Error("invalid candidate filter");
+    const limit = filter.limit ?? CANDIDATE_RETENTION.count;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > CANDIDATE_RETENTION.count) throw new Error("candidate limit must be 1..500");
+    this.prune();
+    const where = ["project = ?"], bind: (string | number)[] = [filter.project];
+    if (filter.status === undefined) where.push("status IN ('pending', 'accepting')"); else if (filter.status !== "all") { where.push("status = ?"); bind.push(filter.status); }
+    if (filter.kind) { where.push("kind = ?"); bind.push(filter.kind); }
+    return (this.db.query(`SELECT * FROM candidates WHERE ${where.join(" AND ")} ORDER BY at DESC, rowid DESC LIMIT ?`).all(...bind, limit) as Parameters<CandidateStore["decode"]>[0][]).map(row => this.decode(row));
+  }
+  recordCounter(key: CounterKey, values: CounterValues, verdict: CandidateVerdict): string {
+    publicOnly(verdict); const normalized = counterKey(key);
+    for (const value of [values.rendered, values.delivered, values.cited]) if (value !== undefined && value !== null && (!Number.isSafeInteger(value) || value < 0)) throw new Error("counter values must be nonnegative integers or unknown");
+    this.prune(); const id = hash({ schema: "agent-mem.counter/v1", key: normalized });
+    this.db.query(`INSERT INTO counters (id, project, payload, at, rendered, delivered, cited) VALUES (?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET rendered = coalesce(excluded.rendered, counters.rendered), delivered = coalesce(excluded.delivered, counters.delivered), cited = coalesce(excluded.cited, counters.cited)`)
+      .run(id, normalized.project, canonical(normalized), this.now(), values.rendered ?? null, values.delivered ?? null, values.cited ?? null);
+    this.prune(); return id;
+  }
+  counters(project: string, entry?: string): Counter[] {
+    if (!text(project, 400) || entry !== undefined && !entryId(entry)) throw new Error("invalid counter filter");
+    this.prune();
+    const rows = this.db.query("SELECT * FROM counters WHERE project = ? ORDER BY at DESC, rowid DESC").all(project) as { id: string; payload: string; at: number; rendered: number | null; delivered: number | null; cited: number | null }[];
+    return rows.map(row => ({ id: row.id, key: JSON.parse(row.payload) as CounterKey, createdAt: new Date(row.at).toISOString(), rendered: row.rendered, delivered: row.delivered, cited: row.cited })).filter(row => !entry || row.key.entryId === entry);
+  }
+  reject(id: string, context: { project: string; actor: "person" | "agent"; verdict: CandidateVerdict }): void {
+    personOnly(context.actor); publicOnly(context.verdict);
+    this.db.transaction(() => {
+      const candidate = this.get(id, context.project);
+      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 = ? AND status = 'pending'").run(id, context.project);
+    }).immediate();
+  }
+  accept(id: string, context: CandidateAcceptance): CandidateAcceptanceResult {
+    personOnly(context.actor); publicOnly(context.verdict);
+    if (realPath(context.store.dir) !== realPath(this.dir) || typeof context.policy !== "function") throw new Error("candidate acceptance requires its memory store and a current host policy");
+    return context.store.withDeferredPromotions(() => this.acceptDeferred(id, context));
+  }
+  private acceptDeferred(id: string, context: CandidateAcceptance): CandidateAcceptanceResult {
+    const candidate = this.get(id, context.project);
+    if (!candidate) throw new Error("candidate unavailable");
+    if (candidate.status === "accepted") return { candidateId: id, noteId: candidate.acceptedNoteId!, alreadyAccepted: true };
+    if (candidate.status !== "pending") throw new Error("candidate is rejected or acceptance was interrupted; no automatic replay");
+    if (candidate.input.kind === "decay") throw new Error("decay candidates are listing-only; no automatic mutation is available");
+    const resolve = () => {
+      const target = candidate.input.target;
+      if (!target) return undefined;
+      const current = context.store.get(target.id, context.project);
+      if (!current || current.id !== target.id || candidateTargetRevision(current) !== target.revision) throw new Error("candidate target revision is stale");
+      return current;
+    };
+    const target = resolve(), data = candidate.input;
+    const body = data.kind === "correction" ? `${data.proposedText}\n\nReason: ${data.reason}`
+      : `Approach: ${data.approach}\nSymptom: ${data.symptom}\nCause: ${data.cause}\nEvidence: ${data.evidenceRefs.join(", ")}\nRetry when: ${data.retryWhen}`;
+    const note: NoteInput = { op: "note", project: data.kind === "correction" ? target!.project : context.project,
+      scope: data.kind === "correction" ? target!.scope : "project",
+      // A demoted synced target is logically short, but replacing it locally would narrow its reach (X04).
+      tier: data.kind === "correction" && target!.local ? "short" : "long",
+      kind: data.kind === "fail" ? "fail" : data.noteKind ?? (target?.kind === "contract" || target?.kind === "fail" ? target.kind : "decision"), peer: "person", source: "person", about: [...target?.about ?? []],
+      text: `Accepted candidate: ${id}\nTarget revision: ${data.target?.revision ?? "none"}\nTarget entry: ${data.target?.id ?? "none"}\n\n${body}` };
+    if (note.text.length > 4000) throw new Error("accepted candidate text exceeds the v1 note limit");
+    if (context.policy(structuredClone(candidate), target && structuredClone(target), structuredClone(note)) !== true) throw new Error("candidate refused by current host policy");
+    return context.store.withAcceptedNote(note, append => {
+      resolve(); // Recheck under the same mutation lock as the note and supersede appends.
+      const started = this.db.transaction(() => {
+        const current = this.get(id, context.project);
+        if (!current) throw new Error("candidate unavailable");
+        if (current.status === "accepted") return current.acceptedNoteId!;
+        if (current.status !== "pending") throw new Error("candidate is rejected or acceptance was interrupted; no automatic replay");
+        this.db.query("UPDATE candidates SET status = 'accepting' WHERE id = ? AND project = ?").run(id, context.project);
+        return undefined;
+      }).immediate();
+      if (started) return { candidateId: id, noteId: started, alreadyAccepted: true };
+      // ponytail: the sidecar receipt and v1 append are not one transaction. An interrupted 'accepting' row refuses
+      // automatic replay; add explicit person-audited recovery before offering background acceptance retries.
+      const noteId = append();
+      if (data.kind === "correction" && !context.store.supersede(target!.id, noteId, "person", context.project)) throw new Error("candidate replacement refused; inspect the accepted note before recovery");
+      this.db.query("UPDATE candidates SET status = 'accepted', note_id = ? WHERE id = ? AND project = ?").run(noteId, id, context.project);
+      return { candidateId: id, noteId, alreadyAccepted: false };
+    });
+  }
+}

package/src/memory/commands.ts

@@ -55,7 +55,9 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
         // Screened first, then cut to the limit: withheld entries never crowd out readable ones.
         const readable = opts.readable(all), rows = readable.slice(0, limit ? Number(limit) : 50);
         if (json) return JSON.stringify(rows, null, 2);
-        const c = store.counts(project);
+        // Preserve project-wide header semantics, but count only rows the host policy lets this reader see.
+        const counted = opts.readable(store.list({ project, limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true }));
+        const c = { machine: store.machine, long: counted.filter(v => v.tier === "long").length, short: counted.filter(v => v.tier === "short").length };
         const withheld = all.length - readable.length;
         return [`hub memory for ${project} on machine ${c.machine.label}: ${c.long} long-term, ${c.short} short-term`, ...(rows.length ? rows.map(one) : ["(nothing)"]),
           ...(withheld ? [`(${withheld} withheld: they match a PII pattern; the dashboard shows them)`] : [])].join("\n");

package/src/memory/mutation.ts

@@ -0,0 +1,22 @@
+import { Database } from "bun:sqlite";
+import { chmodSync } from "node:fs";
+import { join } from "node:path";
+
+export const MUTATION_BUSY_TIMEOUT_MS = 3000;
+// ponytail: older hubs (before consuming this agent-mem), raw/legacy log writers and any segment editor
+// that bypasses this lock are not serialized. Require every writer to take it, or make segment appends API-only.
+/** An empty, machine-local SQLite file used only for crash-safe writer exclusion, never for memory data. */
+export function mutationDatabase(dir: string): Database {
+  const file = join(dir, "mutation-lock.db"), db = new Database(file, { create: true });
+  chmodSync(file, 0o600);
+  db.run(`PRAGMA busy_timeout = ${MUTATION_BUSY_TIMEOUT_MS}`);
+  return db;
+}
+
+/** Sync holds a separate connection across awaits; an unrelated call on the same MemoryStore cannot bypass it. */
+export function acquireMutation(dir: string): (() => void) | undefined {
+  const db = mutationDatabase(dir);
+  try { db.run("BEGIN IMMEDIATE"); }
+  catch { db.close(); return undefined; }
+  return () => { try { db.run("ROLLBACK"); } finally { db.close(); } };
+}

package/src/memory/store.ts

@@ -3,6 +3,7 @@ import { createHash, randomBytes } from "node:crypto";
 import { appendFileSync, chmodSync, closeSync, existsSync, fstatSync, linkSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, normalize } from "node:path";
 import { isDenied } from "./platform.ts";
+import { mutationDatabase } from "./mutation.ts";
 import { memoryHome } from "./home.ts";
 
 /**
@@ -173,15 +174,17 @@ export type PromotionScreen = (v: View) => "promote" | "keep" | "skip";
  * `screen`: applied to every promotion. Without one, automatic promotions (a settlement, a held note whose replacement
  * went) wait for a process that has one; a person's explicit promote goes through.
  */
-export interface StoreOptions { home?: string; ttlMs?: number; now?: () => number; log?: (line: string) => void; screen?: PromotionScreen }
+export interface StoreOptions { home?: string; ttlMs?: number; now?: () => number; log?: (line: string) => void; screen?: PromotionScreen; deferPromotions?: boolean }
 
 export class MemoryStore {
   readonly dir: string;
   readonly machine: Machine;
   private readonly db: Database;
+  private readonly mutationDb: Database;
   private readonly ttl: number;
   private readonly now: () => number;
   private readonly log: (line: string) => void;
+  private readonly deferPromotions: boolean;
 
   constructor(opts: StoreOptions = {}) {
     this.dir = opts.home === undefined ? memoryHome() : join(opts.home, "memory");
@@ -193,6 +196,7 @@ export class MemoryStore {
     this.now = opts.now ?? Date.now;
     this.log = opts.log ?? (() => {});
     this.screen = opts.screen;
+    this.deferPromotions = opts.deferPromotions ?? false;
     const db = new Database(join(this.dir, "index.db"), { create: true });
     db.run(`PRAGMA busy_timeout = ${MEMORY_DB_BUSY_TIMEOUT_MS}`);
     db.run("PRAGMA journal_mode = WAL");
@@ -210,11 +214,51 @@ export class MemoryStore {
     db.run("CREATE TABLE IF NOT EXISTS edges (src TEXT NOT NULL, dst TEXT NOT NULL, PRIMARY KEY (src, dst))");
     db.run("CREATE INDEX IF NOT EXISTS edges_dst ON edges (dst)");
     this.db = db;
+    this.mutationDb = mutationDatabase(this.dir);
     try { chmodSync(join(this.dir, "index.db"), 0o600); } catch { /* best effort */ }
     this.refresh();
   }
 
-  close(): void { this.db.close(); }
+  close(): void { this.db.close(); this.mutationDb.close(); }
+
+  /** A synchronous host-authorized mutation whose reads must not implicitly promote unrelated notes. */
+  withDeferredPromotions<T>(work: () => T): T {
+    const previous = this.promoting;
+    this.promoting = true;
+    try { return work(); } finally { this.promoting = previous; }
+  }
+
+  private withMutation<T>(work: () => T): T {
+    return this.mutationDb.transaction(work).immediate();
+  }
+
+  /** Serialize current-store writers, screen one normalized body, and expose a one-shot append of that body. */
+  withAcceptedNote<T>(note: NoteInput, work: (append: () => string) => T): T {
+    try { return this.withMutation(() => {
+      // Ordinary writes may defer indexing, but accepting an exact target revision must have a current index.
+      this.db.transaction(() => this.refresh()).immediate();
+      const at = new Date(this.now()).toISOString();
+      const normalized = structuredClone({ ...note, text: note.text.slice(0, MAX_TEXT),
+        ...(note.title ? { title: note.title.slice(0, MAX_TITLE) } : {}),
+        ...(note.tier === "short" && !note.expires ? { expires: new Date(Date.parse(at) + this.ttl).toISOString() } : {}) });
+      const body = { schema: MEMORY_SCHEMA, at, machine: this.machine.id, ...normalized } as const;
+      const view: View = { ...normalized, id: entryId(body), at, machine: body.machine, title: normalized.title ?? null,
+        task: normalized.task ?? null, about: [...normalized.about], supersededBy: null,
+        supersedes: normalized.supersedes ? [normalized.supersedes] : [], promotedFrom: normalized.promotedFrom ?? null,
+        expiresAt: normalized.expires ?? null, local: normalized.tier === "short" };
+      if (this.screen?.(view) !== "promote") throw new Error("candidate refused by current promotion screen");
+      let appended = false;
+      return work(() => {
+        if (appended) throw new Error("accepted note already appended");
+        appended = true;
+        return this.appendBody(body, normalized.tier === "short");
+      });
+    }); } catch (error) {
+      // A callback can fail after a durable JSONL append; ensure the derived index catches up.
+      this.stale = true;
+      throw error;
+    }
+  }
 
   /** When a short-term entry written now leaves the index. */
   private until(): string { return new Date(this.now() + this.ttl).toISOString(); }
@@ -223,12 +267,18 @@ export class MemoryStore {
   private append(entry: NoteInput | OpInput | GoalInput, local: boolean, at = new Date(this.now()).toISOString(), machine = this.machine.id): string {
     const capped = entry.op === "note" ? { ...entry, text: entry.text.slice(0, MAX_TEXT), ...(entry.title ? { title: entry.title.slice(0, MAX_TITLE) } : {}) } : entry;
     const body = { schema: MEMORY_SCHEMA, at, machine, ...capped } as Omit<Entry, "id">;
-    const id = entryId(body);
-    appendFileSync(join(this.dir, local ? "local" : "log", `${this.machine.id}.jsonl`), JSON.stringify({ ...body, id }) + "\n", { mode: 0o600 });
-    // The line is written, so the entry is saved: an index that cannot be updated now (a busy database) catches up on the
-    // next read, and the caller is never told it failed.
-    try { this.refresh(); } catch (e) { this.stale = true; this.log(`hub memory index not updated yet: ${(e as Error).message}`); }
-    return id;
+    return this.appendBody(body, local);
+  }
+
+  private appendBody(body: Omit<Entry, "id">, local: boolean): string {
+    // Lock the authoritative log independently: a busy derived index must never prevent an ordinary append.
+    return this.withMutation(() => {
+      const id = entryId(body);
+      appendFileSync(join(this.dir, local ? "local" : "log", `${this.machine.id}.jsonl`), JSON.stringify({ ...body, id }) + "\n", { mode: 0o600 });
+      // The line is durable even if indexing fails; the next refresh catches up from the authoritative log.
+      try { this.refresh(); } catch (e) { this.stale = true; this.log(`hub memory index not updated yet: ${(e as Error).message}`); }
+      return id;
+    });
   }
 
   /** A note: short-term ones stay on this machine, long-term ones go to the synced log. The caller has screened it. */
@@ -244,11 +294,13 @@ export class MemoryStore {
     // A fixed machine: the same observation imported on two machines is one entry once they sync.
     const body = { schema: MEMORY_SCHEMA, at, machine: "claude-mem", ...n, text: n.text.slice(0, MAX_TEXT), ...(n.title ? { title: n.title.slice(0, MAX_TITLE) } : {}) } as Omit<Entry, "id">;
     const id = entryId(body);
-    // The source tuple also recognizes legacy ids whose nodes depended on the checkout or extractor version.
-    const known = this.db.query("SELECT id FROM entries WHERE id = ? OR (source = 'claude-mem' AND project = ? AND at = ? AND text = ?)").get(id, n.project, at, n.text.slice(0, MAX_TEXT)) as { id: string } | null;
-    if (known) return { id: known.id, added: false };
-    appendFileSync(join(this.dir, n.tier === "short" ? "local" : "log", `${this.machine.id}.jsonl`), JSON.stringify({ ...body, id }) + "\n", { mode: 0o600 });
-    return { id, added: true };
+    return this.withMutation(() => {
+      // The source tuple also recognizes legacy ids whose nodes depended on the checkout or extractor version.
+      const known = this.db.query("SELECT id FROM entries WHERE id = ? OR (source = 'claude-mem' AND project = ? AND at = ? AND text = ?)").get(id, n.project, at, n.text.slice(0, MAX_TEXT)) as { id: string } | null;
+      if (known) return { id: known.id, added: false };
+      appendFileSync(join(this.dir, n.tier === "short" ? "local" : "log", `${this.machine.id}.jsonl`), JSON.stringify({ ...body, id }) + "\n", { mode: 0o600 });
+      return { id, added: true };
+    });
   }
 
   /** A person's or the hub's op on an entry; it goes where the entry lives, so forgetting a long-term entry syncs. */
@@ -368,7 +420,7 @@ export class MemoryStore {
    * settlement a crash cut short, or a replacement that was forgotten or expired).
    */
   private promoteHeld(): void {
-    if (this.promoting) return;
+    if (this.promoting || this.deferPromotions) return;
     this.promoting = true;
     try {
       const settled = new Set((this.db.query("SELECT target FROM ops WHERE op = 'settle'").all() as { target: string }[]).map((r) => r.target));
@@ -487,11 +539,20 @@ export class MemoryStore {
 
   /**
    * Every live note with its derived state; an expired one is left out as soon as its deadline passes, before any
-   * prune. ponytail: computed in memory over all rows; push the filters into SQL when the store grows.
+   * prune. Lifecycle relations still fold globally; SQL selects full rows before View/JSON materialization.
+   * ponytail: lifecycle metadata is still scanned on every read; measure before adding a revision cache.
    */
-  private views(expired = false): View[] {
-    const now = this.now();
-    const rows = this.db.query("SELECT * FROM entries").all() as Record<string, string | null>[];
+  private views(expired = false, selection?: Filter, expiredOnly = false): View[] {
+    // Metadata, ops and candidate bodies must describe one WAL snapshot, even if another process indexes a copy.
+    return this.db.transaction(() => this.viewRows(expired, selection, expiredOnly)).deferred();
+  }
+
+  private viewRows(expired: boolean, selection: Filter | undefined, expiredOnly: boolean): View[] {
+    const now = this.now(), selecting = selection !== undefined || expiredOnly;
+    // Relations may cross projects and promoted copies: fold their small metadata globally, never filtered bodies.
+    const rows = this.db.query(selecting
+      ? "SELECT id, at, tier, kind, task, expires, supersedes, promoted_from FROM entries"
+      : "SELECT * FROM entries").all() as Record<string, string | null>[];
     const ops = this.db.query("SELECT op, at, target, by FROM ops ORDER BY at, id").all() as { op: string; at: string; target: string; by: string | null }[];
     const forgotten = new Set(ops.filter((o) => o.op === "forget").map((o) => o.target));
     // Deadlines were fixed when the entries were written, so every process (whatever its own TTL) prunes the same rows.
@@ -550,8 +611,37 @@ export class MemoryStore {
     }
     const supersedes = new Map<string, string[]>(); // the reverse: what each newer entry replaced
     for (const [old, newer] of superseded) supersedes.set(newer, [...(supersedes.get(newer) ?? []), old]);
+    let candidates = rows;
+    if (selecting) {
+      const hidden: string[] = [], expiredIds: string[] = [];
+      for (const r of rows) {
+        const id = r.id!;
+        if (forgotten.has(id) || (r.promoted_from && forgotten.has(r.promoted_from)) || promoted.has(id)) { hidden.push(id); continue; }
+        const at = expiry(r);
+        if (at !== null && Date.parse(at) <= now) expiredIds.push(id);
+      }
+      const where: string[] = [], bind: string[] = [];
+      const ids = (values: Iterable<string>, exclude: boolean) => {
+        const entries = [...values];
+        if (entries.length || !exclude) { where.push(`id ${exclude ? "NOT IN" : "IN"} (SELECT value FROM json_each(?))`); bind.push(JSON.stringify(entries)); }
+      };
+      ids(hidden, true);
+      if (expiredOnly) ids(expiredIds, false); else if (!expired) ids(expiredIds, true);
+      if (selection) {
+        if (selection.project) { where.push("(project = ? OR scope = 'shared')"); bind.push(selection.project); }
+        if (selection.tier) {
+          if (demoted.size) { where.push("CASE WHEN id IN (SELECT value FROM json_each(?)) THEN 'short' ELSE tier END = ?"); bind.push(JSON.stringify([...demoted.keys()]), selection.tier); }
+          else { where.push("tier = ?"); bind.push(selection.tier); }
+        }
+        for (const key of ["kind", "peer", "machine"] as const) if (selection[key]) { where.push(`${key} = ?`); bind.push(selection[key]!); }
+        if (!selection.includeSuperseded) ids(superseded.keys(), true);
+      }
+      // No SQL LIMIT: a host may screen the complete matching set before its own caps or visible counts.
+      // Date parsing, Unicode query matching, locale order and slice semantics stay in JavaScript.
+      candidates = this.db.query(`SELECT * FROM entries${where.length ? ` WHERE ${where.join(" AND ")}` : ""}`).all(...bind) as Record<string, string | null>[];
+    }
     const out: View[] = [];
-    for (const r of rows) {
+    for (const r of candidates) {
       const id = r.id!;
       // A forgotten entry is gone, and so is its promoted copy's source or copy: forgetting either forgets both.
       if (forgotten.has(id) || (r.promoted_from && forgotten.has(r.promoted_from)) || promoted.has(id)) continue;
@@ -571,7 +661,7 @@ export class MemoryStore {
    */
   prune(): number {
     const now = this.now();
-    const expired = this.views(true).filter((v) => v.expiresAt !== null && Date.parse(v.expiresAt) <= now);
+    const expired = this.views(true, undefined, true).filter((v) => v.expiresAt !== null && Date.parse(v.expiresAt) <= now);
     // A copy that expires (it was demoted) takes its whole hidden promotion ancestry with it, or an ancestor would reappear.
     const parent = new Map((this.db.query("SELECT id, promoted_from FROM entries WHERE promoted_from IS NOT NULL").all() as { id: string; promoted_from: string }[]).map((r) => [r.id, r.promoted_from]));
     const gone = new Set<string>();
@@ -591,9 +681,9 @@ export class MemoryStore {
    * What a read sees: rows that expired and promotions that became due while the store sat idle are settled first, so a
    * read, and the index after it, never differ from a rebuild.
    */
-  private live(): View[] {
+  private live(selection?: Filter): View[] {
     this.ensureFresh();
-    this.prune(); this.promoteHeld(); return this.views();
+    this.prune(); this.promoteHeld(); return this.views(false, selection);
   }
   /** A write whose index update failed: the next read refreshes first. */
   private stale = false;
@@ -601,7 +691,7 @@ export class MemoryStore {
   /** Entries visible from `project` (its own, and `shared` ones of any project), newest first, filtered. */
   list(f: Filter = {}): View[] {
     const q = f.q?.toLowerCase().split(/\s+/).filter(Boolean) ?? [];
-    return this.live().filter((v) => (!f.project || v.project === f.project || v.scope === "shared") && (!f.tier || v.tier === f.tier) && (!f.kind || v.kind === f.kind)
+    return this.live(f).filter((v) => (!f.project || v.project === f.project || v.scope === "shared") && (!f.tier || v.tier === f.tier) && (!f.kind || v.kind === f.kind)
       && (!f.peer || v.peer === f.peer) && (!f.machine || v.machine === f.machine) && (!f.since || Date.parse(v.at) >= Date.parse(f.since)) && (f.includeSuperseded || !v.supersededBy)
       && q.every((w) => `${v.title ?? ""}\n${v.text}\n${v.about.join(" ")}`.toLowerCase().includes(w)))
       .sort((a, b) => b.at.localeCompare(a.at) || a.id.localeCompare(b.id)).slice(0, f.limit ?? 200);

package/src/memory/sync.ts

@@ -1,6 +1,7 @@
 import { closeSync, existsSync, openSync, readFileSync, rmSync, writeFileSync, writeSync } from "node:fs";
 import { join } from "node:path";
 import { memoryGitArgv, memoryGitEnv, processLiveness, processSignature } from "./platform.ts";
+import { acquireMutation } from "./mutation.ts";
 import type { MemoryStore } from "./store.ts";
 
 /**
@@ -78,7 +79,10 @@ export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Pr
   if (!opts.remote && !existsSync(join(dir, ".git"))) return fail(noRemote); // never set up: nothing to do, nothing created
   const release = lock(dir);
   if (!release) return fail("another sync is running on this machine");
+  let releaseMutation: (() => void) | undefined;
   try {
+    releaseMutation = acquireMutation(dir);
+    if (!releaseMutation) return fail("another memory mutation is running on this machine");
     // Holding sync.lock, no other git runs in this repository: what a killed one left behind is stale.
     rmSync(join(dir, ".git", "index.lock"), { force: true });
     if (existsSync(join(dir, ".git", "MERGE_HEAD"))) await git(dir, ["merge", "--abort"]);
@@ -136,9 +140,11 @@ export async function syncMemory(store: MemoryStore, opts: SyncOptions = {}): Pr
       pushed = true;
     }
     if (opts.signal?.aborted) return fail("stopped");
-    store.refresh();
-    return { ok: true, pushed, entries: store.counts().long, ...(warning ? { warning } : {}) };
+    return store.withDeferredPromotions(() => {
+      store.refresh();
+      return { ok: true, pushed, entries: store.counts().long, ...(warning ? { warning } : {}) };
+    });
   } catch (e) {
     return fail((e as Error).message.slice(0, 200));
-  } finally { release(); }
+  } finally { try { releaseMutation?.(); } finally { release(); } }
 }