@staix/agent-mem 0.6.0 → 0.7.0

package/src/memory/capture.ts

@@ -7,7 +7,10 @@ import { normalizeCaptureFields, type CaptureFields } from "./capture-input.ts";
 export { CAPTURE_MAX_EXCERPT, CAPTURE_MAX_PATHS } from "./capture-input.ts";
 import { memoryBase } from "./home.ts";
 import { captureShardDir, ensureShardDescriptor, readShardDescriptor, resolveAlias, shardKeyHash } from "./shard.ts";
+import { assertProjectActive } from "./lifecycle.ts";
 import { machineId } from "./machine.ts";
+import { loadAmemConfig, repoConfigRoot } from "./config.ts";
+import { fold } from "./policy.ts";
 import { readWindowSql, readRef, type ReadWindow, type ReadRef, ftsTerms, fts5Available } from "./search-fts.ts";
 
 /**
@@ -81,6 +84,15 @@ export interface CaptureOptions {
   recentReadRows?: boolean;
   /** Excerpt screen; defaults to the built-in secret screen. A host passes its stricter policy. */
   screen?: (text: string) => boolean;
+  /** Caps a caller may lower (F4); the built-in caps and the person's configured caps are the ceiling, so a larger value is ignored (a host can tighten, never loosen). */
+  excerptBytes?: number; capturePaths?: number;
+  /** The working directory the capture belongs to: its repository's `.amem/config` narrows the policy (deny paths, caps) for this store. Absent: the machine configuration only. */
+  cwd?: string;
+  /**
+   * #15 T5: a writable open of an archived or forgotten project is refused (the person took it out of recall; `amem project unarchive` brings an archived one back).
+   * `ignore` is for the maintenance that must still reach the shard (gc, export): it never appends.
+   */
+  lifecycle?: "enforce" | "ignore";
 }
 export interface CaptureAppendOptions {
   /** Opaque stable source receipt for deterministic transcript replay. Requires an explicit source timestamp. */
@@ -125,13 +137,17 @@ export function writeCaptureConfigFile(path: string, config: Partial<CaptureConf
   return next;
 }
 
-/** The effective R6 settings for a shard directory: shard config over the home default over the built-in defaults. */
+/**
+ * The effective R6 settings for a shard directory: the shard's config over the home default (`capture-config.json`, which the capacity advisor writes)
+ * over the person's machine configuration (`amem.config.json` `capture`, F4) over the built-in defaults. A malformed machine configuration throws.
+ */
 export function readCaptureConfig(dir: string, base?: string): CaptureConfig {
   const homeDefault = base === undefined ? {} : readCaptureConfigFile(join(base, "capture-config.json"));
   const shard = readCaptureConfigFile(join(dir, "config.json"));
+  const machine = base === undefined ? {} : loadAmemConfig(base).config.capture;
   return {
-    capMb: shard.capMb ?? homeDefault.capMb ?? CAPTURE_DEFAULT_CAP_MB,
-    retentionDays: shard.retentionDays ?? homeDefault.retentionDays ?? CAPTURE_DEFAULT_RETENTION_DAYS,
+    capMb: shard.capMb ?? homeDefault.capMb ?? machine.capMb ?? CAPTURE_DEFAULT_CAP_MB,
+    retentionDays: shard.retentionDays ?? homeDefault.retentionDays ?? machine.retentionDays ?? CAPTURE_DEFAULT_RETENTION_DAYS,
   };
 }
 
@@ -157,6 +173,7 @@ export class CaptureStore {
   private readonly db: Database;
   private readonly now: () => number;
   private readonly screen: (text: string) => boolean;
+  private readonly caps: import("./capture-input.ts").CaptureCaps;
   private readonly capMb: number;
   private readonly retentionDays: number;
   /** Set when the schema setup itself met the lock: appends spool without touching the database again. */
@@ -179,6 +196,7 @@ export class CaptureStore {
     if (this.readOnly && !/^[a-f0-9]{16}$/.test(machine)) throw new Error("capture machine identity unavailable");
     this.requestedKey = opts.project;
     this.key = resolveAlias(this.base, opts.project);
+    if (!this.readOnly && opts.lifecycle !== "ignore") assertProjectActive(this.base, this.key);
     if (this.readOnly) {
       const descriptor = lstatSync(join(this.base, "projects", shardKeyHash(this.key), "project.json"));
       if (!descriptor.isFile() || descriptor.isSymbolicLink() || descriptor.size > 4096
@@ -197,7 +215,14 @@ export class CaptureStore {
     this.capMb = opts.capMb ?? config.capMb;
     this.retentionDays = opts.retentionDays ?? config.retentionDays;
     this.now = opts.now ?? Date.now;
-    this.screen = opts.screen ?? looksSecret;
+    const configured = loadAmemConfig(this.base, opts.cwd === undefined ? undefined : repoConfigRoot(opts.cwd)).config;
+    // F4: the person's PII patterns screen every excerpt and their deny paths filter every path, whoever appends (hook, ingest or library). A host's own `screen` replaces only the secret part.
+    const patterns = configured.piiPatterns.map(fold).filter(Boolean);
+    const base = opts.screen ?? looksSecret;
+    this.screen = patterns.length ? (text: string) => base(text) || patterns.some(pattern => fold(text).includes(pattern)) : base;
+    const lowest = (a: number | undefined, b: number | undefined) => a === undefined ? b : b === undefined ? a : Math.min(a, b);
+    this.caps = { excerptBytes: lowest(opts.excerptBytes, configured.excerptBytes), paths: lowest(opts.capturePaths, configured.capturePaths),
+      ...(configured.denyPaths.length ? { denyPaths: configured.denyPaths } : {}) };
     const file = join(this.dir, "capture.db");
     if (this.readOnly) {
       // Refuse absent/cold state without authoring machine, shard, schema, FTS or spool metadata.
@@ -412,7 +437,7 @@ export class CaptureStore {
 
   /** The one place input becomes a row: caps fields, deny-filters paths, screens the excerpt, counts its bytes. */
   private normalize(input: CaptureInput): NormalizedCapture {
-    const { at, agent, event, tool, paths, status, excerpt, bytes } = normalizeCaptureFields(input, () => this.now(), text => this.screen(text));
+    const { at, agent, event, tool, paths, status, excerpt, bytes } = normalizeCaptureFields(input, () => this.now(), text => this.screen(text), this.caps);
     return { at, project: input.project, agent, event, tool, paths, status, excerpt, bytes };
   }
 

package/src/memory/catalog.ts

@@ -1,11 +1,12 @@
 import { Database } from "bun:sqlite";
-import { chmodSync, existsSync, readdirSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { memoryBase } from "./home.ts";
 import { effectiveAliases, readShardDescriptor, SHARDED_SCHEMA } from "./shard.ts";
 import { readProfileJSON, validGeneration } from "./generation.ts";
 import { captureShardStats, readCaptureConfig } from "./capture.ts";
 import { openShardStore } from "./store.ts";
+import { lifecycleResolver, type LifecycleState } from "./lifecycle.ts";
 
 /**
  * #15 D3 (storage part only): the user-level catalog of project shards. `catalog.db` in the memory home is derived
@@ -20,12 +21,16 @@ export interface CatalogProject {
   captureRows: number; captureBytes: number; captureLastAt: string | null;
   curatedEntries: number | null; curatedLastAt: string | null; curatedAvailable: boolean;
   capMb: number; retentionDays: number;
+  /** #15 T5: the person's lifecycle decision (`lifecycle.jsonl`); forgotten projects stay in the scan so the state is visible, and listings leave them out. */
+  state: LifecycleState;
+  /** Bytes the shard directory holds on disk (its logs, indexes, capture and work lists), counting files and never following a link. */
+  diskBytes: number;
 }
 
-interface CatalogRow { hash: string; key: string; local: number; aliases: string; capture_rows: number; capture_bytes: number; capture_last_at: string | null; curated_entries: number | null; curated_last_at: string | null; cap_mb: number; retention_days: number }
+interface CatalogRow { hash: string; key: string; local: number; aliases: string; capture_rows: number; capture_bytes: number; capture_last_at: string | null; curated_entries: number | null; curated_last_at: string | null; cap_mb: number; retention_days: number; state: string; disk_bytes: number }
 
 const fromRow = (r: CatalogRow): CatalogProject => ({ hash: r.hash, key: r.key, local: r.local === 1, aliases: JSON.parse(r.aliases) as string[],
-  captureRows: r.capture_rows, captureBytes: r.capture_bytes, captureLastAt: r.capture_last_at, curatedEntries: r.curated_entries, curatedLastAt: r.curated_last_at, curatedAvailable: r.curated_entries !== null, capMb: r.cap_mb, retentionDays: r.retention_days });
+  captureRows: r.capture_rows, captureBytes: r.capture_bytes, captureLastAt: r.capture_last_at, curatedEntries: r.curated_entries, curatedLastAt: r.curated_last_at, curatedAvailable: r.curated_entries !== null, capMb: r.cap_mb, retentionDays: r.retention_days, state: r.state === "archived" || r.state === "forgotten" ? r.state : "active", diskBytes: r.disk_bytes });
 
 /** Interrupted splits expose capture facts, but cannot authorize any curated store open or initialization. */
 function capturedSelection(base: string): boolean {
@@ -41,7 +46,7 @@ function curatedStats(base: string, hash: string, key: string, captured: boolean
   const dir = join(base, "projects", hash);
   // A capture-only descriptor is not permission to initialize a curated store while listing the catalog.
   if (!existsSync(join(dir, "generation.json")) && !existsSync(join(dir, "generation-seal.json"))) return { entries: 0, lastAt: null };
-  const store = openShardStore({ memoryDir: base, project: key, deferPromotions: true });
+  const store = openShardStore({ memoryDir: base, project: key, deferPromotions: true, lifecycle: "ignore" });
   try {
     const db = new Database(join(dir, "index.db"), { readonly: true });
     try {
@@ -52,6 +57,23 @@ function curatedStats(base: string, hash: string, key: string, captured: boolean
   } finally { store.close(); }
 }
 
+/** Bytes of regular files under a shard directory. A link is not followed (counted as nothing), an unreadable entry as nothing: the figure is a lower bound, never a guess. */
+export function directoryBytes(dir: string, depth = 0): number {
+  if (depth > 12) return 0;
+  let total = 0;
+  let entries: import("node:fs").Dirent[] = [];
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return 0; }
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    try {
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isDirectory()) total += directoryBytes(path, depth + 1);
+      else if (entry.isFile()) total += lstatSync(path).size;
+    } catch { /* vanished or unreadable: not counted */ }
+  }
+  return total;
+}
+
 /** Every readable shard with its machine-scope directories; the walk behind the catalog and the capacity advisor. */
 export function walkShards(base: string): { hash: string; key: string; local: boolean; machineDirs: string[] }[] {
   const projectsDir = join(base, "projects");
@@ -75,6 +97,7 @@ export function scanCatalog(base: string): CatalogProject[] {
   const captured = capturedSelection(base);
   // The latest op per alias (a removal included): an alias lists only under the key it currently points at, never under a past target or after `alias remove`.
   const latest = effectiveAliases(base);
+  const stateOf = lifecycleResolver(base);
   const out: CatalogProject[] = [];
   for (const shard of walkShards(base)) {
     let rows = 0, bytes = 0, lastAt: string | null = null;
@@ -88,11 +111,17 @@ export function scanCatalog(base: string): CatalogProject[] {
     const curated = curatedStats(base, shard.hash, shard.key, captured);
     out.push({ hash: shard.hash, key: shard.key, local: shard.local,
       aliases: [...latest.entries()].filter(([, key]) => key === shard.key).map(([alias]) => alias).sort(),
-      captureRows: rows, captureBytes: bytes, captureLastAt: lastAt, curatedEntries: curated.entries, curatedLastAt: curated.lastAt, curatedAvailable: curated.entries !== null, capMb: config.capMb, retentionDays: config.retentionDays });
+      captureRows: rows, captureBytes: bytes, captureLastAt: lastAt, curatedEntries: curated.entries, curatedLastAt: curated.lastAt, curatedAvailable: curated.entries !== null, capMb: config.capMb, retentionDays: config.retentionDays,
+      state: stateOf(shard.key), diskBytes: directoryBytes(join(base, "projects", shard.hash)) });
   }
   return out.sort((a, b) => a.key.localeCompare(b.key));
 }
 
+/** A fresh scan of the shards for a read-only command (`amem usage`, `amem projects`): it writes nothing, `catalog.db` included. */
+export function readCatalogFresh(base: string): CatalogProject[] {
+  return scanCatalog(base);
+}
+
 /** Rewrite `catalog.db` from the shards in one transaction: the same shards always reproduce the same rows. */
 export function rebuildCatalog(opts: { home?: string } = {}): CatalogProject[] {
   const base = memoryBase(opts.home);
@@ -105,12 +134,13 @@ export function rebuildCatalog(opts: { home?: string } = {}): CatalogProject[] {
     db.transaction(() => {
       const columns = db.query("PRAGMA table_info(projects)").all() as { name: string; notnull: number }[];
       // This database is disposable. Rebuild older derived schemas instead of coercing unavailable into zero.
-      if (columns.length && (!columns.some(column => column.name === "curated_entries" && column.notnull === 0) || !columns.some(column => column.name === "curated_last_at"))) db.run("DROP TABLE projects");
+      if (columns.length && (!columns.some(column => column.name === "curated_entries" && column.notnull === 0) || !columns.some(column => column.name === "curated_last_at")
+        || !columns.some(column => column.name === "state") || !columns.some(column => column.name === "disk_bytes"))) db.run("DROP TABLE projects");
       db.run(`CREATE TABLE IF NOT EXISTS projects (hash TEXT PRIMARY KEY, key TEXT NOT NULL, local INTEGER NOT NULL, aliases TEXT NOT NULL,
-        capture_rows INTEGER NOT NULL, capture_bytes INTEGER NOT NULL, capture_last_at TEXT, curated_entries INTEGER, curated_last_at TEXT, cap_mb REAL NOT NULL, retention_days REAL NOT NULL)`);
+        capture_rows INTEGER NOT NULL, capture_bytes INTEGER NOT NULL, capture_last_at TEXT, curated_entries INTEGER, curated_last_at TEXT, cap_mb REAL NOT NULL, retention_days REAL NOT NULL, state TEXT NOT NULL DEFAULT 'active', disk_bytes INTEGER NOT NULL DEFAULT 0)`);
       db.run("DELETE FROM projects");
-      for (const p of projects) db.query("INSERT INTO projects (hash, key, local, aliases, capture_rows, capture_bytes, capture_last_at, curated_entries, curated_last_at, cap_mb, retention_days) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
-        .run(p.hash, p.key, p.local ? 1 : 0, JSON.stringify(p.aliases), p.captureRows, p.captureBytes, p.captureLastAt, p.curatedEntries, p.curatedLastAt, p.capMb, p.retentionDays);
+      for (const p of projects) db.query("INSERT INTO projects (hash, key, local, aliases, capture_rows, capture_bytes, capture_last_at, curated_entries, curated_last_at, cap_mb, retention_days, state, disk_bytes) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+        .run(p.hash, p.key, p.local ? 1 : 0, JSON.stringify(p.aliases), p.captureRows, p.captureBytes, p.captureLastAt, p.curatedEntries, p.curatedLastAt, p.capMb, p.retentionDays, p.state, p.diskBytes);
     }).immediate();
   } finally { db.close(); }
   return projects;
@@ -127,8 +157,11 @@ export function readCatalog(opts: { home?: string } = {}): CatalogProject[] {
     db = new Database(file, { readonly: true });
     db.run("PRAGMA busy_timeout = 3000");
     const columns = new Set((db.query("PRAGMA table_info(projects)").all() as { name: string }[]).map(column => column.name));
-    if (!columns.has("curated_entries") || !columns.has("curated_last_at")) throw new Error("catalog schema needs rebuild");
+    if (!columns.has("curated_entries") || !columns.has("curated_last_at") || !columns.has("state") || !columns.has("disk_bytes")) throw new Error("catalog schema needs rebuild");
+    // The state is the person's decision in lifecycle.jsonl, which changes without touching a shard: read it live, never from the cached row.
+    const stateOf = lifecycleResolver(base);
     return (db.query("SELECT * FROM projects ORDER BY key").all() as CatalogRow[]).map(fromRow)
+      .map(project => ({ ...project, state: stateOf(project.key) }))
       .map(project => captured ? { ...project, curatedEntries: null, curatedLastAt: null, curatedAvailable: false } : project);
   } catch { return rebuildCatalog(opts); }
   finally { db?.close(); }

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(); }
 }