@staix/agent-mem 0.6.0 → 0.8.0

package/src/memory/commands.ts

@@ -2,32 +2,56 @@ import { extractNodes, GOAL_STATES, KINDS, MemoryStore, setMachineLabel, type Go
 import { syncMemory, type SyncOptions } from "./sync.ts";
 import { importClaudeMem } from "./import.ts";
 import { memoryProjectKey, projectChain } from "./project.ts";
+import { recallForViews, recallGraph, recallRows, recallShow } from "./recall.ts";
+import type { GoalPromotionReport } from "./goal-promotion.ts";
+
+/**
+ * What the commands call themselves in their own messages. The default is amem's own surface; a host that exposes the same commands under its own
+ * name (agent-hub's `ahub memory` and `ahub goal`) passes it, so no host name is baked into the library.
+ */
+export interface CommandNames { memory: string; goal: string }
+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;
+  /** Defaults to amem's own names. */
+  names?: CommandNames;
   /** Startup-bound canonical project supplied by a host; no model-facing selector. */
   project?: string;
   store?: MemoryStore;
   sync?: Omit<SyncOptions, "remote">;
   open: () => MemoryStore;
   readable: (notes: View[]) => View[];
+  stale?: (view: View) => boolean | undefined;
+  /** Prepared row ids only: the host must wait for successful output before recording rendered. */
+  outputReady?: (notes: readonly View[]) => void;
   importPolicy: () => (text: string) => boolean;
   /** Explicit person-status receipt; model-facing hosts omit this callback. */
   onBridgeStatus?: (status: { skippedRows: number } | undefined) => void;
 }
 export interface GoalCommandOptions {
+  /** Defaults to amem's own names. */
+  names?: CommandNames;
   project?: string;
   store?: MemoryStore;
   link?: (goal: string, task: string) => Promise<string>;
+  /** Optional host proposal hook; the goal state is saved before it runs. It never grants mutation authority. */
+  onDone?: (goal: GoalView, store: MemoryStore) => Promise<GoalPromotionReport>;
   open: () => MemoryStore;
   clean: (title: string, milestones: string[], project: string) => boolean;
 }
 
 /**
- * #258: `ahub memory`, straight on the machine's store (no hub needed). Reading is anyone's; promote, demote, forget,
+ * #258: the memory commands, straight on the machine's store (no host needed; agent-hub exposes the same as `ahub memory`). Reading is anyone's; promote, demote, forget,
  * supersede and rebuild are a person's (the identity gate refuses agent shells).
  */
-export const MEMORY_USAGE = "usage: ahub memory [list] [--tier short|long] [--kind <kind>] [--peer <p>] [--machine <id>] [--since <iso>] [--limit N] | search <words> | show <id> | graph <id|node> [--hops 1|2] | promote|demote|forget <id> | supersede <old> <new> | rebuild | sync [--remote <url>] | machine [--label <name>] | import claude-mem [--db <path>] [--limit N] [--restart] | dedupe [--apply] | suggestions | confirm|reject <suggestion id>  [--json]";
-export const GOAL_USAGE = "usage: ahub goal [list] [--all] | show <id> | new <title> [--milestone <text>]... [--depends <id>]... [--shared] | link <id> <task id> | state <id> open|active|blocked|done|dropped | done <id> | take <id> [--force]  [--json]";
+/** The usage line of the memory commands under `name` (`amem` by default; agent-hub passes `ahub memory`). */
+export const memoryUsage = (name: string = AMEM_NAMES.memory): string => `usage: ${name} [list] [--tier short|long] [--kind <kind>] [--peer <p>] [--machine <id>] [--since <iso>] [--limit N] | search <words> [--history] [--as-of <UTC>] | show <id> [--history] [--as-of <UTC>] | graph <id|node> [--hops 1|2] [--history] [--as-of <UTC>] | promote|demote|forget <id> | supersede <old> <new> | rebuild | sync [--remote <url>] | machine [--label <name>] | import claude-mem [--db <path>] [--limit N] [--restart] | dedupe [--apply] | suggestions | confirm|reject <suggestion id>  [--json]`;
+export const MEMORY_USAGE = memoryUsage();
+/** The usage line of the goal commands under `name` (`amem goal` by default; agent-hub passes `ahub goal`). */
+export const goalUsage = (name: string = AMEM_NAMES.goal): string => `usage: ${name} [list] [--all] | show <id> | new <title> [--milestone <text>]... [--depends <id>]... [--shared] | link <id> <task id> | state <id> open|active|blocked|done|dropped | done <id> | take <id> [--force]  [--json]`;
+export const GOAL_USAGE = goalUsage();
 
 const fail = (message: string): never => { throw new Error(message); };
 const one = (v: View) => `${v.id.slice(0, 8)}  ${v.at.slice(0, 16).replace("T", " ")}  ${v.tier.padEnd(5)} ${v.kind.padEnd(8)} ${v.peer.padEnd(8)} ${v.scope === "shared" ? "shared " : ""}${`${v.title ? `${v.title}: ` : ""}${v.text}`.replace(/\s+/g, " ").slice(0, 100)}${v.supersededBy ? `  (superseded by ${v.supersededBy.slice(0, 8)})` : ""}`;
@@ -41,64 +65,86 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
   const rest = args.filter((a) => a !== "--json");
   const flag = (name: string) => { const i = rest.indexOf(name); if (i < 0) return undefined; const v = rest[i + 1] ?? fail(`${name} needs a value`); rest.splice(i, 2); return v; };
   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");
   const store = opts.store ?? opts.open();
   const actor = "user";
   const project = opts.project ?? memoryProjectKey(cwd);
-  const need = (v: View | undefined, id: string) => v ?? fail(`no memory entry ${id} (ahub memory list shows the ids)`);
+  const need = (v: View | undefined, id: string) => v ?? fail(`no memory entry ${id} (${names.memory} list shows the ids)`);
+  // #15 D4: this command is bound to one project. Crossing projects is the person's `amem search --all-projects`; here the flags would otherwise read as query words.
+  for (const crossing of ["--all-projects", "--include-archived"]) if (rest.includes(crossing)) fail(`${crossing} crosses projects: run amem search --all-projects; ${names.memory} reads this project only`);
+  // #15 T4: repo scope is the person's `amem promote --to repo`, which screens, previews the committed line and checks the repository's visibility. Here the flag would otherwise be ignored and the note promoted privately.
+  for (const repoOnly of ["--to", "--confirm", "--confirm-public"]) if (rest.includes(repoOnly)) fail(`${repoOnly} belongs to the person's amem promote <id> --to repo; ${names.memory} never writes a repository file`);
+  const stale = (view: View) => { try { return opts.stale?.(view) === true; } catch { return false; } };
+  const ready = (rows: readonly View[]) => { try { opts.outputReady?.(rows); } catch { /* optional output metadata cannot fail recall */ } };
+  const decorated = (view: View) => ({ ...view, ...(stale(view) ? { stale: true } : {}) });
+  if (!["list", "search", "show", "graph"].includes(sub) && (rest.includes("--history") || rest.includes("--as-of"))) fail("history/as-of apply only to memory reads");
   try {
     switch (sub) {
       case "list": case "search": {
-        const tier = flag("--tier"), kind = flag("--kind"), peer = flag("--peer"), machine = flag("--machine"), since = flag("--since"), limit = flag("--limit");
+        const tier = flag("--tier"), kind = flag("--kind"), peer = flag("--peer"), machine = flag("--machine"), since = flag("--since"), limit = flag("--limit"), asOf = flag("--as-of");
+        const history = rest.includes("--history"); if (history) rest.splice(rest.indexOf("--history"), 1);
         if (since !== undefined && Number.isNaN(Date.parse(since))) fail(`--since needs a date or time (ISO 8601), not ${since}`);
         if (tier && tier !== "short" && tier !== "long") fail("--tier takes short or long");
         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(" ") || fail("usage: ahub memory search <words>") : rest.length ? fail(MEMORY_USAGE) : undefined;
-        // Agent shells may run this: notes are screened under this project's current PII policy, as briefs and recall are
-        // (a shared note was accepted under another project's patterns). The dashboard shows a person everything.
-        const all = store.list({ project, ...(tier ? { tier: tier as Tier } : {}), ...(kind ? { kind: kind as Kind } : {}), ...(peer ? { peer } : {}), ...(machine ? { machine } : {}), ...(since ? { since } : {}), ...(q ? { q } : {}), limit: Number.MAX_SAFE_INTEGER });
-        // Screened first, then cut to the limit: withheld entries never crowd out readable ones.
+        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 readable = opts.readable(all), rows = readable.slice(0, limit ? Number(limit) : 50);
+        ready(rows);
+        if (history || asOf !== undefined) {
+          const emitted = recallForViews(state, rows), publicIds = new Set(rows.map(view => view.id)), allForgotten = q?.trim() ? [] : state.forgotten;
+          const forgotten = allForgotten.slice(0, Math.max(0, (limit ? Math.floor(Number(limit)) : 50) - rows.length));
+          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);
-        // 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 counted = opts.readable(store.withDeferredPromotions(() => store.list({ project, limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true })));
         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)"]),
+        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)"]),
           ...(withheld ? [`(${withheld} withheld: they match a PII pattern; the dashboard shows them)`] : [])].join("\n");
       }
       case "show": {
-        const id = rest[0] ?? fail("usage: ahub memory show <id>");
-        const v = need(store.get(id, project), id);
-        if (!opts.readable([v]).length) fail(`${v.id.slice(0, 8)} is withheld: it matches a PII pattern (the dashboard shows it)`);
-        return json ? JSON.stringify(v, null, 2) : detail(v).join("\n");
+        const asOf = flag("--as-of"), history = rest.includes("--history"); if (history) rest.splice(rest.indexOf("--history"), 1);
+        const id = rest[0] ?? fail(`usage: ${names.memory} show <id>`), shown = recallShow(store, project, id, { person: opts.person, history, asOf });
+        if (!shown.ids.length) return fail(`no memory entry ${id} (${names.memory} list shows the ids)`);
+        if (shown.state) {
+          const rows = opts.readable(shown.state.views), ids = new Set(rows.map(view => view.id)); ready(rows);
+          const state = { ...recallForViews(shown.state, rows), views: rows.map(decorated), relations: shown.state.relations.filter(edge => ids.has(edge.from) && ids.has(edge.to)) };
+          return json ? JSON.stringify(state, null, 2) : [`retained memory as of ${state.at}`, ...state.notices, ...rows.flatMap(view => [...(stale(view) ? ["(stale?)"] : []), ...detail(view)]), ...state.forgotten.map(row => `forgotten ${row.id} at ${row.at} (no retained text shown)`), ...(state.incomplete ? ["(retained state is incomplete)"] : [])].join("\n");
+        }
+        const view = need(shown.entry, id); if (!opts.readable([view]).length) fail(`${view.id.slice(0, 8)} is withheld: it matches a PII pattern (the dashboard shows it)`);
+        ready([view]); return json ? JSON.stringify(view, null, 2) : [...(stale(view) ? ["(stale?)"] : []), ...detail(view)].join("\n");
       }
       case "graph": {
         const hops = Number(flag("--hops") ?? 1);
         if (hops !== 1 && hops !== 2) fail("--hops takes 1 or 2");
-        const start = rest[0] ?? fail("usage: ahub memory graph <id|node>");
-        const node = start.includes(":") && !start.startsWith("mem:") ? start : `mem:${need(store.get(start, project), start).id}`;
-        const g = store.graph(project, node, hops);
+        const asOf = flag("--as-of"), history = rest.includes("--history"); if (history) rest.splice(rest.indexOf("--history"), 1);
+        const start = rest[0] ?? fail(`usage: ${names.memory} graph <id|node>`);
+        const g = recallGraph(store, project, start, hops, { person: opts.person, history, asOf });
+        if ((!start.includes(":") || start.startsWith("mem:")) && !g.nodes.length) fail(`no memory entry ${start} (${names.memory} list shows the ids)`);
+        const node = !start.includes(":") || start.startsWith("mem:") ? g.nodes[0]!.id : start;
         return json ? JSON.stringify(g, null, 2) : [`${g.nodes.length} nodes, ${g.edges.length} edges around ${node}`, ...g.edges.map((e) => `${e.from} -${e.rel}-> ${e.to}`)].join("\n");
       }
-      case "promote": { const v = need(store.get(rest[0] ?? fail(MEMORY_USAGE), project), rest[0]!); if (v.supersededBy) fail(`${v.id.slice(0, 8)} is replaced by ${v.supersededBy.slice(0, 8)}: promote that one instead`); const id = store.promote(v.id, actor, project) ?? fail(v.project !== project ? `${v.id.slice(0, 8)} is another project's note: promote it from that project` : `${v.id.slice(0, 8)} stays short-term: it holds a secret, matches a PII pattern or is about a private path`); return id === v.id ? `${v.id.slice(0, 8)} is already long-term` : `promoted to long-term as ${id.slice(0, 8)}`; }
-      case "demote": { const v = need(store.get(rest[0] ?? fail(MEMORY_USAGE), project), rest[0]!); if (v.tier !== "long") return `${v.id.slice(0, 8)} is already short-term`; store.demote(v.id, actor, project); return `demoted ${v.id.slice(0, 8)}: it expires ${store.get(v.id, project)?.expiresAt ?? "with its short-term lifetime"}`; }
-      case "forget": { const v = need(store.forget(rest[0] ?? fail(MEMORY_USAGE), actor, project), rest[0]!); return `forgot ${v.id.slice(0, 8)}${v.local ? "" : "; it stays in the sync remote's git history until a person rewrites it (docs/memory.md)"}`; }
+      case "promote": { const v = need(store.get(rest[0] ?? fail(usage), project), rest[0]!); if (v.supersededBy) fail(`${v.id.slice(0, 8)} is replaced by ${v.supersededBy.slice(0, 8)}: promote that one instead`); const id = store.promote(v.id, actor, project) ?? fail(v.project !== project ? `${v.id.slice(0, 8)} is another project's note: promote it from that project` : `${v.id.slice(0, 8)} stays short-term: it holds a secret, matches a PII pattern or is about a private path`); return id === v.id ? `${v.id.slice(0, 8)} is already long-term` : `promoted to long-term as ${id.slice(0, 8)}`; }
+      case "demote": { const v = need(store.get(rest[0] ?? fail(usage), project), rest[0]!); if (v.tier !== "long") return `${v.id.slice(0, 8)} is already short-term`; store.demote(v.id, actor, project); return `demoted ${v.id.slice(0, 8)}: it expires ${store.get(v.id, project)?.expiresAt ?? "with its short-term lifetime"}`; }
+      case "forget": { const v = need(store.forget(rest[0] ?? fail(usage), actor, project), rest[0]!); return `forgot ${v.id.slice(0, 8)}${v.local ? "" : "; it stays in the sync remote's git history until a person rewrites it (docs/memory.md)"}`; }
       case "supersede": {
-        if (rest.length !== 2) fail("usage: ahub memory supersede <old> <new>");
-        return store.supersede(rest[0]!, rest[1]!, actor, project) ? `${rest[0]} is superseded by ${rest[1]}` : fail("both ids must name different entries, and the newer one must reach as far: shared for a shared entry, long-term for a long-term one (ahub memory promote it first)");
+        if (rest.length !== 2) fail(`usage: ${names.memory} supersede <old> <new>`);
+        return store.supersede(rest[0]!, rest[1]!, actor, project) ? `${rest[0]} is superseded by ${rest[1]}` : fail(`both ids must name different entries, and the newer one must reach as far: shared for a shared entry, long-term for a long-term one (${names.memory} promote it first)`);
       }
       case "sync": {
         const remote = flag("--remote");
-        if (rest.length) fail("usage: ahub memory sync [--remote <private git url>]");
+        if (rest.length) fail(`usage: ${names.memory} sync [--remote <private git url>]`);
         const r = await syncMemory(store, { ...opts.sync, ...(remote ? { remote } : {}) });
         if (json) return JSON.stringify(r, null, 2);
-        if (!r.ok) fail(`hub memory sync: ${r.error}`);
+        if (!r.ok) fail(`${names.memory} sync: ${r.error}`);
         return `synced${r.pushed ? " and pushed" : ""}: ${r.entries} long-term entries visible here${r.warning ? `\nnote: ${r.warning}` : ""}`;
       }
       case "dedupe": {
         const apply = rest.includes("--apply");
-        if (rest.some(arg => arg !== "--apply")) fail("usage: ahub memory dedupe [--apply] [--json]");
+        if (rest.some(arg => arg !== "--apply")) fail(`usage: ${names.memory} dedupe [--apply] [--json]`);
         const result = store.dedupe(project, apply);
         if (json) return JSON.stringify(result, null, 2);
         return [result.groups.length ? `${result.groups.length} duplicate import group(s)${apply ? `; appended ${result.applied} supersede operation(s)` : "; use --apply to reconcile"}` : "no duplicate import groups to reconcile",
@@ -108,7 +154,7 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
         const db = flag("--db"), limit = flag("--limit");
         const restart = rest.includes("--restart");
         if (restart) rest.splice(rest.indexOf("--restart"), 1);
-        if (rest[0] !== "claude-mem" || rest.length !== 1) fail("usage: ahub memory import claude-mem [--db <path>] [--limit N] [--restart]");
+        if (rest[0] !== "claude-mem" || rest.length !== 1) fail(`usage: ${names.memory} import claude-mem [--db <path>] [--limit N] [--restart]`);
         if (limit && !(Number(limit) > 0)) fail("--limit takes a positive number");
         const isPii = opts.importPolicy();
         const key = opts.project ?? memoryProjectKey(cwd);
@@ -120,10 +166,10 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
       case "suggestions": {
         const pending = store.suggestions(project).filter((x) => x.status === "suggested");
         if (json) return JSON.stringify(pending, null, 2);
-        return pending.length ? pending.map((x) => `${x.id.slice(0, 8)}  ${x.from.slice(0, 8)} ${x.rel} ${x.to.slice(0, 8)}  (suggested by the hub's model ${x.at}; not evidence until confirmed)`).join("\n") : "no edge suggestions waiting";
+        return pending.length ? pending.map((x) => `${x.id.slice(0, 8)}  ${x.from.slice(0, 8)} ${x.rel} ${x.to.slice(0, 8)}  (suggested by a model ${x.at}; not evidence until confirmed)`).join("\n") : "no edge suggestions waiting";
       }
       case "confirm": case "reject": {
-        const x = store.judge(rest[0] ?? fail(`usage: ahub memory ${sub} <suggestion id>`), sub, actor, project) ?? fail(`no suggestion ${rest[0]} (ahub memory suggestions lists them)`);
+        const x = store.judge(rest[0] ?? fail(`usage: ${names.memory} ${sub} <suggestion id>`), sub, actor, project) ?? fail(`no suggestion ${rest[0]} (${names.memory} suggestions lists them)`);
         return `${sub === "confirm" ? "confirmed" : "rejected"}: ${x.from.slice(0, 8)} ${x.rel} ${x.to.slice(0, 8)}`;
       }
       case "machine": {
@@ -132,7 +178,7 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
         return json ? JSON.stringify(m) : `this machine: ${m.id} (${m.label})`;
       }
       case "rebuild": { store.rebuild(); const c = store.counts(); return `rebuilt the index from ${c.segments} segment${c.segments === 1 ? "" : "s"}: ${c.long} long-term, ${c.short} short-term entries`; }
-      default: return fail(MEMORY_USAGE);
+      default: return fail(usage);
     }
   } finally {
     try { opts.onBridgeStatus?.(store.bridgeStatus()); }
@@ -140,15 +186,15 @@ export async function rawMemoryCommand(args: string[], cwd: string, opts: Memory
   }
 }
 
-const goalOne = (g: GoalView, me: string) => `${g.id.slice(0, 8)}  ${g.state.padEnd(7)} ${g.title}${g.scope === "shared" ? "  [shared]" : ""}  ${leaseText(g, me)}`;
-function leaseText(g: GoalView, me: string): string {
+const goalOne = (g: GoalView, me: string, goal: string = AMEM_NAMES.goal) => `${g.id.slice(0, 8)}  ${g.state.padEnd(7)} ${g.title}${g.scope === "shared" ? "  [shared]" : ""}  ${leaseText(g, me, goal)}`;
+function leaseText(g: GoalView, me: string, goal: string): string {
   const who = (m: string) => m === me ? "this machine" : `machine ${m.slice(0, 8)}`;
-  if (g.lease.holder) return `held by ${who(g.lease.holder)} until ${g.lease.until}${g.lease.conflict.length ? `, CONFLICT with ${g.lease.conflict.map(who).join(", ")} (the earlier claim holds; a person settles it with ahub goal take --force)` : ""}`;
+  if (g.lease.holder) return `held by ${who(g.lease.holder)} until ${g.lease.until}${g.lease.conflict.length ? `, CONFLICT with ${g.lease.conflict.map(who).join(", ")} (the earlier claim holds; a person settles it with ${goal} take --force)` : ""}`;
   return g.lease.expired ? `free (${who(g.lease.lastHolder!)}'s lease ended ${g.lease.until})` : "free";
 }
 
 /**
- * #258: `ahub goal`, long-term tasks. Listing and showing are anyone's; new, link, state, done and take are a
+ * #258: the goal commands (agent-hub exposes the same as `ahub goal`), long-term tasks. Listing and showing are anyone's; new, link, state, done and take are a
  * person's. A peer links its own board task with hub_task_propose's `goal`.
  */
 export async function rawGoalCommand(args: string[], cwd: string, opts: GoalCommandOptions): Promise<string> {
@@ -156,11 +202,12 @@ export async function rawGoalCommand(args: string[], cwd: string, opts: GoalComm
   const rest = args.filter((a) => a !== "--json");
   const take = (name: string) => { const out: string[] = []; for (let i = rest.indexOf(name); i >= 0; i = rest.indexOf(name)) { out.push(rest[i + 1] ?? fail(`${name} needs a value`)); rest.splice(i, 2); } return out; };
   const sub = rest[0] && !rest[0].startsWith("--") ? rest.shift()! : "list";
+  const names = opts.names ?? AMEM_NAMES, usage = goalUsage(names.goal);
   const store = opts.store ?? opts.open();
   const project = opts.project ?? memoryProjectKey(cwd);
   const me = store.machine.id;
   // Only this project's long-term tasks and shared ones, like every other lookup an agent may run.
-  const need = (id: string | undefined) => store.goalOf(id?.replace(/^goal:/, "") ?? fail(GOAL_USAGE), project) ?? fail(`no long-term task ${id} for this project (ahub goal list shows them)`);
+  const need = (id: string | undefined) => store.goalOf(id?.replace(/^goal:/, "") ?? fail(usage), project) ?? fail(`no long-term task ${id} for this project (${names.goal} list shows them)`);
   const clean = (title: string, milestones: string[], of = project) => opts.clean(title, milestones, of);
   try {
     switch (sub) {
@@ -169,36 +216,43 @@ export async function rawGoalCommand(args: string[], cwd: string, opts: GoalComm
         const listed = store.goals(project).filter((g) => all || (g.state !== "done" && g.state !== "dropped"));
         const goals = listed.filter((g) => clean(g.title, g.milestones, g.project)), withheld = listed.length - goals.length;
         if (json) return JSON.stringify(goals, null, 2);
-        return [...(goals.length ? goals.map((g) => goalOne(g, me)) : [`no ${all ? "" : "open "}long-term tasks for ${project} (ahub goal new <title>)`]),
+        return [...(goals.length ? goals.map((g) => goalOne(g, me, names.goal)) : [`no ${all ? "" : "open "}long-term tasks for ${project} (${names.goal} new <title>)`]),
           ...(withheld ? [`(${withheld} withheld: they match a PII pattern or a private path)`] : [])].join("\n");
       }
       case "show": {
         const g = need(rest[0]);
         if (!clean(g.title, g.milestones, g.project)) fail(`${g.id.slice(0, 8)} is withheld: it matches a PII pattern or a private path`);
         if (json) return JSON.stringify(g, null, 2);
-        return [goalOne(g, me), `${g.id}, project ${g.project}, created ${g.at} on machine ${g.machine.slice(0, 8)}`,
+        return [goalOne(g, me, names.goal), `${g.id}, project ${g.project}, created ${g.at} on machine ${g.machine.slice(0, 8)}`,
           ...g.milestones.map((m) => `milestone: ${m}`), ...g.dependsOn.map((d) => `depends on ${d.slice(0, 8)}`),
           ...(g.links.length ? g.links.map((l) => `board task ${l.task} (linked ${l.at} on machine ${l.machine.slice(0, 8)})`) : ["no board tasks linked yet"])].join("\n");
       }
       case "new": {
         const milestones = take("--milestone"), depends = take("--depends").map((d) => need(d).id);
         const shared = rest.includes("--shared");
-        const title = rest.filter((a) => a !== "--shared").join(" ").trim() || fail(GOAL_USAGE);
+        const title = rest.filter((a) => a !== "--shared").join(" ").trim() || fail(usage);
         if (!clean(title, milestones)) fail("a long-term task syncs to every machine: this one holds a secret, a PII pattern or a private path and is not saved");
         const id = store.goal({ project, scope: shared ? "shared" : "project", title, milestones, dependsOn: depends, actor: "user" });
         return `long-term task ${id.slice(0, 8)} created: ${title}`;
       }
       case "link": {
         const g = need(rest[0]);
-        const task = rest[1] ?? fail("usage: ahub goal link <id> <task id>");
+        const task = rest[1] ?? fail(`usage: ${names.goal} link <id> <task id>`);
         if (!/^\d+$/.test(task)) fail("the task is a board task id of this project");
-        return await (opts.link ?? fail("linking needs this project's hub running (ahub up)"))(g.id, task);
+        return await (opts.link ?? fail("linking a goal to a task needs a host that has a task board; amem alone has none"))(g.id, task);
       }
       case "state": case "done": {
         const g = need(rest[0]);
         const state = (sub === "done" ? "done" : rest[1]) as GoalState;
         if (!GOAL_STATES.includes(state)) fail(`the state is one of ${GOAL_STATES.join(", ")}`);
         store.goalState(g.id, state, "user");
+        if (state === "done" && opts.onDone) {
+          const current = store.goalOf(g.id, project);
+          if (!current || current.id !== g.id || current.state !== "done") return fail("goal state changed before promotion offering");
+          const promotion = await opts.onDone(current, store);
+          if (json) return JSON.stringify({ goalId: current.id, state: current.state, promotion }, null, 2);
+          return `long-term task ${current.id.slice(0, 8)} is done\npromotion candidates: ${promotion.offered} offered, ${promotion.alreadyOffered} already offered, ${promotion.withheld} withheld${promotion.truncated ? "; more linked notes remain (truncated)" : ""}`;
+        }
         return `long-term task ${g.id.slice(0, 8)} is ${state}`;
       }
       case "take": {
@@ -207,7 +261,7 @@ export async function rawGoalCommand(args: string[], cwd: string, opts: GoalComm
         if (!r.ok) fail(`held by machine ${r.holder.slice(0, 8)} until ${r.until}; wait for it to expire or take it over with --force`);
         return `this machine holds long-term task ${g.id.slice(0, 8)} until ${r.until}${rest.includes("--force") ? " (earlier claims are void)" : ""}`;
       }
-      default: return fail(GOAL_USAGE);
+      default: return fail(usage);
     }
   } finally { if (!opts.store) store.close(); }
 }

package/src/memory/config.ts

@@ -0,0 +1,167 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createStandalonePolicy, type StandalonePolicy, type StandalonePolicyOptions } from "./policy.ts";
+
+/**
+ * F4 (agent-mem#40): standalone policy configuration, with no host. Two files, both plain JSON:
+ *
+ * - the machine-local `amem.config.json` in the memory home: the person's own policy (deny paths, PII patterns, the SessionStart brief byte
+ *   budget, the capture excerpt and path caps, the capture size cap and retention, and where the home lives);
+ * - an optional `<repository>/.amem/config`: a repository may only NARROW. It adds deny paths and PII patterns and may lower a byte or count
+ *   budget; it can never remove a machine entry, raise a budget, or move the home. A stricter host policy passed through the library wins over both.
+ *
+ * Either file that exists but is not a bounded plain JSON object of known keys is an error that names it, never a silent default: an unreadable
+ * policy must not read as "no policy". Reading is synchronous and does no model, network or storage work.
+ */
+export const CONFIG_FILE = "amem.config.json";
+export const REPO_CONFIG_DIR = ".amem";
+export const REPO_CONFIG_FILE = "config";
+const MAX_CONFIG_BYTES = 64 * 1024;
+const MACHINE_KEYS = ["home", "denyPaths", "piiPatterns", "briefBytes", "excerptBytes", "capturePaths", "capture"] as const;
+const REPO_KEYS = ["denyPaths", "piiPatterns", "briefBytes", "excerptBytes", "capturePaths"] as const;
+
+export interface AmemConfig {
+  /** The memory home, when the file moves it (a pointer file: see `configuredHome`). `AMEM_HOME` still wins. Machine file only. */
+  home?: string;
+  denyPaths: string[];
+  piiPatterns: string[];
+  /** SessionStart brief byte budget; the built-in hook cap is the ceiling. */
+  briefBytes?: number;
+  /** Capture excerpt cap in bytes-as-characters; the built-in cap is the ceiling. */
+  excerptBytes?: number;
+  /** Capture path-count cap; the built-in cap is the ceiling. */
+  capturePaths?: number;
+  /** The capture tier's own R6 bounds. Machine file only (a repository cannot widen the machine's disk use). */
+  capture: { capMb?: number; retentionDays?: number };
+}
+export interface ConfigSource { machine: string | null; repo: string | null }
+export interface LoadedConfig { config: AmemConfig; source: ConfigSource }
+
+const fail = (file: string, why: string): never => { throw new Error(`${file}: ${why}; fix or remove it (an unreadable policy is never treated as no policy)`); };
+
+/** One bounded read through one descriptor: a link, a non-file or a growing file refuses, and a missing file is `undefined`. */
+function readPlain(path: string, label: string): unknown | undefined {
+  let fd: number;
+  try { fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK); }
+  catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return undefined;
+    return fail(label, code === "ELOOP" ? "is a symbolic link" : "cannot be read");
+  }
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > MAX_CONFIG_BYTES) return fail(label, `is not a plain file within ${MAX_CONFIG_BYTES} bytes`);
+    const text = readFileSync(fd, "utf8");
+    if (Buffer.byteLength(text) > MAX_CONFIG_BYTES) return fail(label, `is not a plain file within ${MAX_CONFIG_BYTES} bytes`);
+    try { return JSON.parse(text) as unknown; } catch { return fail(label, "does not parse as JSON"); }
+  } finally { closeSync(fd); }
+}
+
+function listOf(value: unknown, key: string, label: string): string[] {
+  if (value === undefined) return [];
+  // The standalone policy takes at most 64 literals of 256 bytes without control characters: say so here, by name.
+  if (!Array.isArray(value) || value.length > 64 || !value.every(item => typeof item === "string" && item.trim() !== "" && Buffer.byteLength(item) <= 256 && !/[\x00-\x1f\x7f]/.test(item)))
+    return fail(label, `${key} is not a list of at most 64 non-empty strings of at most 256 bytes without control characters`);
+  return [...new Set(value as string[])];
+}
+function countOf(value: unknown, key: string, label: string, max: number): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1 || value > max) return fail(label, `${key} is not a whole number from 1 to ${max}`);
+  return value;
+}
+
+function parseFile(raw: unknown, label: string, keys: readonly string[]): Partial<AmemConfig> & { capture?: AmemConfig["capture"] } {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return fail(label, "is not a JSON object");
+  const body = raw as Record<string, unknown>;
+  for (const key of Object.keys(body)) if (!keys.includes(key)) fail(label, `unknown key "${key}" (known: ${keys.join(", ")})`);
+  const out: Partial<AmemConfig> & { capture?: AmemConfig["capture"] } = {
+    denyPaths: listOf(body.denyPaths, "denyPaths", label), piiPatterns: listOf(body.piiPatterns, "piiPatterns", label),
+  };
+  const briefBytes = countOf(body.briefBytes, "briefBytes", label, 1_000_000); if (briefBytes !== undefined) out.briefBytes = briefBytes;
+  const excerptBytes = countOf(body.excerptBytes, "excerptBytes", label, 100_000); if (excerptBytes !== undefined) out.excerptBytes = excerptBytes;
+  const capturePaths = countOf(body.capturePaths, "capturePaths", label, 1000); if (capturePaths !== undefined) out.capturePaths = capturePaths;
+  if (body.home !== undefined) {
+    if (typeof body.home !== "string" || !body.home.trim() || body.home.includes("\0") || !body.home.startsWith("/")) return fail(label, "home is not an absolute path");
+    // A file that moves the home is a pointer: the policy is read from the file IN the home it names, so any policy key beside `home` here would be silently lost.
+    const beside = Object.keys(body).filter(key => key !== "home");
+    if (beside.length) return fail(label, `names a home, so it is only a pointer; put ${beside.join(", ")} in ${join(body.home, CONFIG_FILE)}`);
+    out.home = body.home;
+  }
+  if (body.capture !== undefined) {
+    const capture = body.capture;
+    if (!capture || typeof capture !== "object" || Array.isArray(capture) || Object.keys(capture).some(key => !["capMb", "retentionDays"].includes(key))) return fail(label, "capture takes only capMb and retentionDays");
+    const c = capture as Record<string, unknown>;
+    out.capture = {};
+    const capMb = countOf(c.capMb, "capture.capMb", label, 1_048_576), retentionDays = countOf(c.retentionDays, "capture.retentionDays", label, 36_500);
+    if (capMb !== undefined) out.capture.capMb = capMb;
+    if (retentionDays !== undefined) out.capture.retentionDays = retentionDays;
+  }
+  return out;
+}
+
+/** The machine file's `home` before any store exists: the one key read ahead of the home itself. `AMEM_HOME` and the config's `home` name different homes only when the person sets both, and `AMEM_HOME` wins. */
+export function machineConfigPath(base: string): string { return join(base, CONFIG_FILE); }
+export function repoConfigPath(root: string): string { return join(root, REPO_CONFIG_DIR, REPO_CONFIG_FILE); }
+
+/**
+ * The nearest ancestor of `cwd` that holds a `.git` entry, by `lstat` alone: no `git` process, so a hook inside its 150 ms budget can call it.
+ * Bounded to 32 levels. Its `.amem/config` (if any) is the repository's narrowing file.
+ */
+export function repoConfigRoot(cwd: string): string | undefined {
+  try {
+    for (let dir = cwd, depth = 0; depth < 32; dir = dirname(dir), depth++) {
+      if (lstatSync(join(dir, ".git"), { throwIfNoEntry: false })) return dir;
+      if (dir === dirname(dir)) return undefined;
+    }
+  } catch { /* unreadable: no repository file */ }
+  return undefined;
+}
+
+/**
+ * The home the machine configuration redirects to, read from the DEFAULT home's `amem.config.json` only (one level: a redirected home's own file
+ * cannot redirect again, so there is no chain and no loop). Undefined when there is no file or it names no `home`. A malformed file throws.
+ * That file is a pointer: it carries `home` and nothing else, and the policy lives in the file inside the home it names.
+ */
+export function configuredHome(defaultHome: string): string | undefined {
+  const file = machineConfigPath(defaultHome), raw = readPlain(file, file);
+  return raw === undefined ? undefined : parseFile(raw, file, MACHINE_KEYS).home;
+}
+
+const lower = (machine: number | undefined, repo: number | undefined) => machine === undefined ? repo : repo === undefined ? machine : Math.min(machine, repo);
+
+/**
+ * The effective configuration. The repository file can only narrow: its lists are added to the machine's, and a number counts only when it is
+ * lower than the machine's (or the machine has none). It never carries `home` or `capture` (unknown key: an error), so it cannot move the
+ * store or widen the disk bounds.
+ */
+export function loadAmemConfig(base: string, repoRoot?: string): LoadedConfig {
+  const machinePath = machineConfigPath(base);
+  const machineRaw = readPlain(machinePath, machinePath);
+  const machine = machineRaw === undefined ? undefined : parseFile(machineRaw, machinePath, MACHINE_KEYS);
+  let repo: ReturnType<typeof parseFile> | undefined, repoPath: string | null = null;
+  if (repoRoot !== undefined) {
+    const file = repoConfigPath(repoRoot), raw = readPlain(file, file);
+    if (raw !== undefined) { repo = parseFile(raw, file, REPO_KEYS); repoPath = file; }
+  }
+  const union = (a: string[] | undefined, b: string[] | undefined) => [...new Set([...(a ?? []), ...(b ?? [])])];
+  const denyPaths = union(machine?.denyPaths, repo?.denyPaths), piiPatterns = union(machine?.piiPatterns, repo?.piiPatterns);
+  if (denyPaths.length > 64) fail(machinePath, "denyPaths and the repository's denyPaths name more than 64 entries together");
+  if (piiPatterns.length > 64) fail(machinePath, "piiPatterns and the repository's piiPatterns name more than 64 entries together");
+  const config: AmemConfig = { denyPaths, piiPatterns, capture: { ...(machine?.capture ?? {}) } };
+  if (machine?.home !== undefined) config.home = machine.home;
+  for (const key of ["briefBytes", "excerptBytes", "capturePaths"] as const) { const value = lower(machine?.[key], repo?.[key]); if (value !== undefined) config[key] = value; }
+  return { config, source: { machine: machineRaw === undefined ? null : machinePath, repo: repoPath } };
+}
+
+/**
+ * The standalone policy as configured. A host policy passed through the library still wins: it is composed in, never replaced, so the result
+ * declines whatever either declines (`createStandalonePolicy` screens the config, then asks the host).
+ */
+export function configuredPolicyOptions(base: string, cwd?: string, options: StandalonePolicyOptions = {}): StandalonePolicyOptions {
+  const { config } = loadAmemConfig(base, cwd === undefined ? undefined : repoConfigRoot(cwd));
+  const merge = (a: readonly string[] | undefined, b: readonly string[]) => [...new Set([...(a ?? []), ...b])];
+  return { ...options, denyPaths: merge(options.denyPaths, config.denyPaths), piiPatterns: merge(options.piiPatterns, config.piiPatterns) };
+}
+export function configuredPolicy(base: string, cwd?: string, options: StandalonePolicyOptions = {}): StandalonePolicy {
+  return createStandalonePolicy(configuredPolicyOptions(base, cwd, options));
+}

package/src/memory/consolidate.ts

@@ -0,0 +1,78 @@
+import { CandidateStore, 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";
+import type { MemoryStore, View } from "./store.ts";
+import { realPath } from "./platform.ts";
+import { proposeModelConsolidations, type ModelConsolidationOptions, type ModelConsolidationReport } from "./consolidation-model.ts";
+
+export interface ConsolidationOptions {
+  project: string; actor: "person" | "agent"; policy: () => StandalonePolicy; policyVersion: () => string;
+  allowed?: () => boolean; assertCurrent?: () => void;
+  /** Person-enabled host callback only. Absent means no model work or budget reservation. */
+  model?: ModelConsolidationOptions;
+}
+export interface ConsolidationReport {
+  schema: "amem.consolidation/v1"; project: string; candidates: { id: string; action: string; sources: string[] }[];
+  engine: "fts5" | "substring"; truncated: boolean; oversized: number; localExcluded: number;
+  /** Proposals whose candidate already exists as accepted, accepting or rejected: they are not queued again and are not in `candidates`. */
+  alreadyReviewed: number;
+  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"; }
+}
+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. */
+export async function proposeConsolidation(store: MemoryStore, candidates: CandidateStore, options: ConsolidationOptions): Promise<ConsolidationReport> {
+  if (options.actor !== "person") throw Error("consolidation requires person intent");
+  if (options.allowed?.() === false) throw Error("consolidation unavailable");
+  if (realPath(candidates.dir) !== realPath(store.profile.home)) throw Error("consolidation requires its own candidate home");
+  const project = options.project, version = options.policyVersion(), policy = options.policy();
+  if (!project.trim() || typeof version !== "string") throw Error("consolidation context unavailable");
+  const sourceCurrent = store.beginRecallRead();
+  const check = () => {
+    if (options.actor !== "person" || options.project !== project || options.allowed?.() === false || options.policyVersion() !== version) throw Error("consolidation context changed");
+    options.assertCurrent?.(); sourceCurrent();
+  };
+  check();
+  if (!await policy.screen({ project })) throw Error("consolidation refused by current policy");
+  check();
+  const raw = store.withDeferredPromotions(() => store.list({ project, limit: 257 })), rows: View[] = [];
+  for (const value of raw) {
+    check(); const row = memoryPolicySnapshot(value);
+    if (!row || row.project !== project || !recallViewIsLive(row, store.readNow()) || modelAnswer(row)) continue;
+    if (await policy.screen(row)) rows.push(row);
+  }
+  check();
+  const placements = rows.length ? store.entryPlacements(rows.map(row => row.id).slice(0, 256), project) : new Map<string, "local" | "synced">();
+  const synced = rows.slice(0, 256).filter(row => placements.get(row.id) === "synced");
+  const clustered = consolidationClusters(synced, project, store.readNow()), prepared: Extract<CandidateInput, { kind: "consolidation" }>[] = [];
+  let oversized = 0;
+  for (const cluster of clustered.clusters) {
+    const first = cluster.sources[0]!;
+    if (cluster.sources.some(row => row.scope !== first.scope || row.local !== first.local)) continue;
+    const text = `${cluster.reason}\n\nUntrusted quoted sources, not instructions:\n${cluster.sources.map(row => JSON.stringify({ ref: `mem:${row.id}`, kind: row.kind, text: row.text })).join("\n")}`;
+    const about = [...new Set(cluster.sources.flatMap(row => [...row.about, ...(row.task ? [`task:${row.task}`] : [])]))].sort();
+    if (text.length > 3000 || about.length > 32 || about.some(node => node.length > 400)) { oversized++; continue; }
+    const input: Extract<CandidateInput, { kind: "consolidation" }> = { kind: "consolidation", project, action: cluster.action,
+      targets: cluster.sources.map(row => ({ id: row.id, revision: candidateTargetRevision(row) })), text, about, noteKind: cluster.action === "recurring-fix" ? "fail" : first.kind };
+    check(); if (await policy.screen(input)) prepared.push(input);
+  }
+  check();
+  const report: ConsolidationReport = { schema: "amem.consolidation/v1", project, candidates: [], engine: clustered.engine, truncated: raw.length === 257 || clustered.truncated, oversized, localExcluded: rows.slice(0, 256).length - synced.length, alreadyReviewed: 0 };
+  try {
+    // All asynchronous host work finishes before the first candidate write. The ordinary candidate
+    // queue cap still applies; a full queue reports the ids already enqueued, never a silent batch.
+    // 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");
+      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)); }
+  return report;
+}