@staix/agent-mem 0.6.0 → 0.7.0

package/src/memory/note-add.ts

@@ -0,0 +1,100 @@
+import { KINDS, type Kind, type MemoryStore, type NoteInput, type Scope, type Tier } from "./store.ts";
+import type { StandalonePolicy } from "./policy.ts";
+
+/**
+ * F6 (agent-mem#40): person note authoring. `amem note add` writes one curated note the person typed, through the configured policy. The note is authored by the
+ * person (`peer: "person"`, `source: "person"`), which is why the command is person-only like every ordinary command (an agent marker is refused before it runs).
+ *
+ * A `fail` note carries structured fields. Its body uses the same labelled lines an accepted `fail` candidate produces, so a note written here and one accepted
+ * from `amem_remember` read alike and `fail` search and the plan guard see one shape.
+ */
+export const NOTE_MAX_CHARS = 4000, NOTE_TITLE_MAX = 200, FAIL_FIELD_MAX = 1000, FAIL_EVIDENCE_MAX = 16;
+
+export interface FailFields { approach: string; symptom: string; cause: string; evidence: string[]; retryWhen: string }
+export interface NoteAddInput { kind: Kind; tier: Tier; scope: Scope; text?: string; title?: string; fail?: Partial<FailFields> }
+export interface NoteAddResult { id: string }
+
+const refuse = (message: string): never => { throw new Error(message); };
+const clean = (value: string | undefined): string => (value ?? "").replace(/\r\n?/g, "\n").trim();
+/** Every character a reader may treat as a line break: LF, CR, VT, FF, NEL and the Unicode line and paragraph separators. A field with any of them could forge a labelled line. */
+export const LINE_BREAKS = /[\n\r\v\f\u0085\u2028\u2029]/;
+export const oneLine = (value: string): string => value.replace(/\s*[\n\r\v\f\u0085\u2028\u2029]+\s*/g, " ");
+
+/** The labelled body of a `fail` note: the exact lines an accepted fail candidate has, without the "Accepted candidate" provenance header. */
+export function failBody(fields: FailFields): string {
+  return `Approach: ${oneLine(fields.approach)}\nSymptom: ${oneLine(fields.symptom)}\nCause: ${oneLine(fields.cause)}\nEvidence: ${fields.evidence.map(oneLine).join(", ")}\nRetry when: ${oneLine(fields.retryWhen)}`;
+}
+
+/** Validate the structured fields and say which are missing, so the person can fix the command rather than guess. */
+function failFields(raw: Partial<FailFields> | undefined): FailFields {
+  const missing = ["approach", "symptom", "cause", "retryWhen"].filter(key => !clean(raw?.[key as keyof FailFields] as string | undefined));
+  const evidence = (raw?.evidence ?? []).map(clean).filter(Boolean);
+  const flags = { approach: "--approach", symptom: "--symptom", cause: "--cause", retryWhen: "--retry-when" } as Record<string, string>;
+  if (missing.length || !evidence.length) refuse(`a fail note needs ${[...missing.map(key => flags[key]!), ...(evidence.length ? [] : ["--evidence"])].join(", ")} (approach, symptom, cause, evidence and retry-when are all required, so the next reader knows when the approach is worth retrying)`);
+  if (evidence.length > FAIL_EVIDENCE_MAX) refuse(`a fail note takes at most ${FAIL_EVIDENCE_MAX} --evidence values`);
+  const out: FailFields = { approach: clean(raw!.approach), symptom: clean(raw!.symptom), cause: clean(raw!.cause), evidence, retryWhen: clean(raw!.retryWhen) };
+  for (const [key, value] of Object.entries(out)) for (const item of Array.isArray(value) ? value : [value]) {
+    if (item.length > FAIL_FIELD_MAX) refuse(`a fail note's ${key} is over ${FAIL_FIELD_MAX} characters`);
+    if (item.includes("\0")) refuse(`a fail note's ${key} holds a NUL byte`);
+  }
+  return out;
+}
+
+/** Build the note a command would write, without writing it (the preview and the write share this). */
+export function buildNote(input: NoteAddInput, project: string): NoteInput {
+  if (!(KINDS as readonly string[]).includes(input.kind)) refuse(`--kind takes ${KINDS.join(", ")}`);
+  if (input.tier !== "short" && input.tier !== "long") refuse("--tier takes short or long");
+  if (input.scope !== "project" && input.scope !== "shared") refuse("--scope takes project or shared");
+  const title = input.title === undefined ? undefined : clean(input.title);
+  if (title !== undefined && (!title || title.length > NOTE_TITLE_MAX || title.includes("\0") || LINE_BREAKS.test(title))) refuse(`--title must be one line of 1 to ${NOTE_TITLE_MAX} characters`);
+  let text: string;
+  if (input.kind === "fail") {
+    // The structured fields ARE the body. A free text is refused with them so there is one answer to "what does this fail note say".
+    if (clean(input.text)) refuse("a fail note takes --approach, --symptom, --cause, --evidence and --retry-when, not free text");
+    text = failBody(failFields(input.fail));
+  } else {
+    if (input.fail && Object.values(input.fail).some(value => (Array.isArray(value) ? value.length : clean(value as string | undefined)))) refuse("--approach, --symptom, --cause, --evidence and --retry-when belong to --kind fail");
+    text = clean(input.text);
+    if (!text) refuse("a note needs text: pass it as an argument, `-` for stdin, or run in a terminal to use $EDITOR");
+    if (text.includes("\0")) refuse("the note text holds a NUL byte");
+  }
+  if (text.length > NOTE_MAX_CHARS) refuse(`the note is ${text.length} characters; the limit is ${NOTE_MAX_CHARS}`);
+  return { op: "note", project, scope: input.scope, tier: input.tier, kind: input.kind, peer: "person", source: "person", ...(title ? { title } : {}), text, about: [] };
+}
+
+/**
+ * Write one note. The configured policy screens the whole note (title and text) first and a decline names no text; a long-term note the policy declines would not
+ * sync, so it is refused here instead of silently staying local. Nothing is written when anything fails.
+ */
+export function noteAdd(store: MemoryStore, project: string, input: NoteAddInput, policy: StandalonePolicy): NoteAddResult {
+  const note = buildNote(input, project);
+  if (!policy.screenStandalone({ ...(note.title ? { title: note.title } : {}), text: note.text, about: note.about })   /* no undefined field: the screen refuses one */) refuse("the note is refused by the configured privacy policy (secrets, personal data, deny paths and the patterns in amem.config.json); edit it or the policy and try again");
+  return { id: store.note(note, input.tier === "short") };
+}
+
+/** What `$EDITOR` opens for a `fail` note given no field flags: five labelled lines the person fills in. */
+export const FAIL_TEMPLATE = "Approach: \nSymptom: \nCause: \nEvidence: \nRetry when: \n";
+const LABELS = [["approach", "Approach"], ["symptom", "Symptom"], ["cause", "Cause"], ["evidence", "Evidence"], ["retryWhen", "Retry when"]] as const;
+/** Whether any line of `text` starts with one of the five labels (case-insensitive). Text that already carries a label is the person's own structure, so it opens as written. */
+export function hasFailLabel(text: string): boolean {
+  return text.replace(/\r\n?|\u0085|\u2028|\u2029|\v|\f/g, "\n").split("\n").some(line => LABELS.some(([, label]) => line.toLowerCase().startsWith(`${label.toLowerCase()}:`)));
+}
+/** Read the labelled template back. A label's value runs to the next label (so it may span lines); evidence splits on commas and newlines. */
+export function parseFailTemplate(raw: string): Partial<FailFields> {
+  const out: Record<string, string> = {};
+  let current: string | undefined;
+  for (const line of raw.replace(/\r\n?|\u0085|\u2028|\u2029|\v|\f/g, "\n").split("\n")) {
+    const hit = LABELS.find(([, label]) => line.toLowerCase().startsWith(`${label.toLowerCase()}:`));
+    if (hit) {
+      // A label given twice would silently keep only the last: refuse it, so no text the person typed is dropped without a word.
+      if (hit[0] in out) throw new Error(`the template repeats the "${hit[1]}:" label; each of the five labels takes one entry`);
+      current = hit[0]; out[current] = line.slice(hit[1].length + 1).trim();
+    }
+    else if (current) out[current] = `${out[current]}\n${line}`;
+  }
+  // Trim first, then test: a blank template line is "" after the trim, never a truthy "\n".
+  const value = (key: string) => (out[key] ?? "").trim();
+  const evidence = value("evidence").split(/[,\n]/).map(item => item.trim()).filter(Boolean);
+  return { ...(value("approach") ? { approach: value("approach") } : {}), ...(value("symptom") ? { symptom: value("symptom") } : {}), ...(value("cause") ? { cause: value("cause") } : {}),
+    ...(evidence.length ? { evidence } : {}), ...(value("retryWhen") ? { retryWhen: value("retryWhen") } : {}) };
+}

package/src/memory/path-glob.ts

@@ -0,0 +1,94 @@
+/**
+ * `pii.paths` matching, ported from agent-hub (`src/hub/path-policy.ts`: `policyPaths`, `patternScope`, `matchesPolicyLexically`; `src/hub/memory-policy.ts`:
+ * `mentionsPrivatePath`) so the repo scope screens with the semantics the project's own config was written for: exact paths and subtrees, `*`, `?` and
+ * whole-segment `**` globs, case and Unicode folded like a case-insensitive disk. amem imports no agent-hub code, so this is a port, and
+ * `test/path-policy-parity.test.ts` pins it to values produced by the hub's real matcher (`scripts/gen-path-policy-parity.ts`).
+ *
+ * Lexical only. The hub's `matchesPolicy` also resolves real paths and symlink aliases against the filesystem; a note merely names a path, so nothing here
+ * reads the disk. The port keeps the hub's `includeParents` stance (a directory that could hold a protected descendant counts), the over-protective side:
+ * for a file that exists the hub is narrower, never broader.
+ * ponytail: no symlink alias discovery. Upgrade: ask the host (agent-hub) for the verdict through the library API once amem has a host policy port for paths.
+ */
+import { posix } from "node:path";
+import { nodePath, pathCandidates } from "./project.ts";
+
+/** One spelling per name, as a case-insensitive disk sees it (agent-hub `foldSegment`). */
+const foldSegment = (segment: string): string => segment.normalize("NFKC").replace(/\p{Default_Ignorable_Code_Point}/gu, "").toLowerCase().toUpperCase().toLowerCase();
+
+/** Bounded project-relative exact paths/subtrees or `*`, `?` and whole-segment `**` globs (agent-hub `policyPaths`). Throws on anything the hub would refuse. */
+export function policyEntries(raw: unknown, field: string): string[] {
+  const bad = raw === undefined ? false : !Array.isArray(raw) || raw.length > 64 || raw.some(p => typeof p !== "string" || !p || p.length > 200 || posix.isAbsolute(p) || /^[A-Za-z]:/.test(p) || /[\[\]{}!]/.test(p) || /[\x00-\x1f\x7f]/.test(p) || p.split(/[\\/]/).includes("..")
+    || (/[?*]/.test(p) && (p.includes("\\") || (p.match(/[?*]/g)?.length ?? 0) > 16 || p.split("/").some(s => s.includes("**") && s !== "**"))));
+  if (bad) throw new Error(`${field} takes up to 64 bounded project-relative paths or *, ? and whole-segment ** patterns of at most 200 characters (no absolute paths, .., brackets, braces or !)`);
+  if (raw === undefined) return [];
+  return [...new Set((raw as string[]).map(p => p.replace(/\/+/g, "/").replace(/\/$/, "") || "."))];
+}
+
+const within = (path: string, root: string) => path === root || path.startsWith(root.endsWith("/") ? root : `${root}/`);
+const beneath = (path: string, root: string) => within(path.toLowerCase(), root.toLowerCase()) || within(foldSegment(path), foldSegment(root));
+
+/** Either spelling protects: the lowercase comparison keeps `?` matching one code point whose fold expands, the folded one catches NFD/NFC and compatibility aliases. */
+const segmentMatches = (pattern: string, name: string): boolean => wildcard(pattern.toLowerCase(), name.toLowerCase()) || wildcard(foldSegment(pattern), foldSegment(name));
+/** Linear-space wildcard DP, no regex backtracking on untrusted paths. */
+function wildcard(pattern: string, name: string): boolean {
+  const chars = [...name];
+  let previous = new Array<boolean>(chars.length + 1).fill(false); previous[0] = true;
+  for (const char of pattern) {
+    const next = new Array<boolean>(chars.length + 1).fill(false);
+    next[0] = char === "*" && previous[0]!;
+    for (let i = 1; i <= chars.length; i++) next[i] = char === "*" ? previous[i]! || next[i - 1]! : previous[i - 1]! && (char === "?" || char === chars[i - 1]);
+    previous = next;
+  }
+  return previous[chars.length]!;
+}
+function closure(pattern: string[], states: Set<number>): Set<number> {
+  const out = new Set(states);
+  for (const i of out) if (pattern[i] === "**") out.add(i + 1);
+  return out;
+}
+function advance(pattern: string[], states: Set<number>, name: string): Set<number> {
+  const next = new Set<number>();
+  for (const i of closure(pattern, states)) {
+    if (pattern[i] === "**") next.add(i);
+    else if (pattern[i] !== undefined && segmentMatches(pattern[i]!, name)) next.add(i + 1);
+  }
+  return closure(pattern, next);
+}
+function patternScope(pattern: string[], path: string, includeParents: boolean): boolean {
+  if (posix.isAbsolute(path) || path === ".." || path.startsWith("../")) return false;
+  let states = closure(pattern, new Set([0]));
+  if (states.has(pattern.length)) return true;
+  for (const name of path.split("/").filter(p => p && p !== ".")) {
+    states = advance(pattern, states, name);
+    if (states.has(pattern.length)) return true; // a matched directory protects its entire subtree
+    if (!states.size) return false;
+  }
+  return includeParents && states.size > 0; // this scope can contain a future protected descendant
+}
+
+const ROOT = "/project";
+const segments = (entry: string) => entry.split("/").filter(p => p && p !== ".");
+
+/** Whether `path` (project-relative as written in a note) falls under any entry: the hub's `matchesPolicy` without the filesystem. */
+export function matchesEntries(path: string, entries: readonly string[], includeParents = true): boolean {
+  if (!entries.length) return false;
+  try {
+    if (path.length > 4096) return true;
+    const lexical = posix.resolve(ROOT, path), relative = posix.relative(ROOT, lexical);
+    return entries.some(entry => {
+      if (/[?*]/.test(entry)) return patternScope(segments(entry), relative, includeParents);
+      const target = posix.resolve(ROOT, entry);
+      return beneath(lexical, target) || includeParents && beneath(target, lexical) || patternScope([...segments(entry), "**"], relative, includeParents);
+    });
+  } catch { return true; }
+}
+
+/** Whether a note's text or its path links name a private path (agent-hub `mentionsPrivatePath`): written paths, and an entry's literal part written out. */
+export function mentionsPrivatePath(text: string, about: readonly string[], entries: readonly string[]): boolean {
+  if (!entries.length) return false;
+  const nfc = (value: string) => value.normalize("NFC"), body = nfc(text), policy = entries.map(nfc);
+  const paths = [...about.map(nodePath), ...pathCandidates(body)].filter((p): p is string => p !== undefined).map(nfc);
+  if (paths.some(path => matchesEntries(path, policy, true))) return true;
+  // The entry's literal part (up to its first glob character) written out: catches a path a word split breaks (a space).
+  return policy.some(entry => { const literal = entry.replace(/^\.\//, "").split(/[*?[\]{}]/)[0]!.replace(/\/+$/, ""); return /[/\s]/.test(literal) && body.includes(literal); });
+}

package/src/memory/plan-guard.ts

@@ -0,0 +1,47 @@
+import { extractNodes, type View } from "./store.ts";
+import { nodePath } from "./project.ts";
+
+export interface PlanGuardContext { cwd: string; project: string; repo: string; deny?: string[]; now?: () => number }
+/** Structural input accepts host task adapters without importing a host or a task board. */
+export interface PlanGuardInput {
+  paths?: readonly string[]; symbols?: readonly string[];
+  refs?: { paths?: readonly string[] };
+  plan?: { paths?: readonly string[]; symbols?: readonly string[] };
+}
+export function normalizeMemorySymbolInput(value: string): string {
+  const at = value.lastIndexOf("@"), name = at < 0 ? value : value.slice(0, at);
+  const normalized = name.startsWith("section ") || name.startsWith("source ") ? name : name.replace(/\s*\(.*$/, "").trim();
+  return at < 0 ? normalized : `${normalized}@${value.slice(at + 1)}`;
+}
+/** Explicit inputs only. Per-input extraction retains more than v1's 64-node extraction cap. */
+export function planGuardNodes(input: PlanGuardInput, context: PlanGuardContext): string[] {
+  const nodes = new Set<string>();
+  for (const path of [...input.paths ?? [], ...input.refs?.paths ?? [], ...input.plan?.paths ?? []]) {
+    for (const node of extractNodes("", { ...context, paths: [path], checkExists: false })) nodes.add(node);
+  }
+  const only = nodes.size === 1 ? nodePath([...nodes][0]!) : undefined;
+  for (const symbol of [...input.symbols ?? [], ...input.plan?.symbols ?? []]) {
+    if (typeof symbol !== "string") continue;
+    const at = symbol.lastIndexOf("@");
+    const explicitPath = at < 0 ? undefined : extractNodes("", { ...context, paths: [symbol.slice(at + 1)], checkExists: false })[0];
+    if (at >= 0 && !explicitPath) continue;
+    const qualified = explicitPath ? `${symbol.slice(0, at)}@${nodePath(explicitPath)}` : symbol;
+    for (const form of new Set([qualified, normalizeMemorySymbolInput(qualified)])) {
+      for (const node of extractNodes("", { ...context, paths: only ? [only] : [], symbols: [form], checkExists: false })) nodes.add(node);
+    }
+  }
+  return [...nodes].sort();
+}
+const samePath = (a: string, b: string) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+/** Symbols require name and file identity; path scopes intersect only on whole components. */
+export function planNodesIntersect(left: string, right: string): boolean {
+  if (left === right) return true;
+  if (left.startsWith("symbol:") && right.startsWith("symbol:")) return normalizeMemorySymbolInput(left.slice(7)) === normalizeMemorySymbolInput(right.slice(7));
+  const a = nodePath(left), b = nodePath(right);
+  return !!a && !!b && samePath(a, b);
+}
+/** Callers screen complete live notes first; this pure matcher performs no I/O or writes. */
+export function matchingPlanFails<T extends Pick<View, "kind" | "about" | "supersededBy"> & Partial<Pick<View, "expiresAt">>>(input: PlanGuardInput, notes: readonly T[], context: PlanGuardContext): T[] {
+  const nodes = planGuardNodes(input, context), now = (context.now ?? Date.now)();
+  return nodes.length && Number.isFinite(now) ? notes.filter(note => note.kind === "fail" && !note.supersededBy && (note.expiresAt == null || Number.isFinite(Date.parse(note.expiresAt)) && Date.parse(note.expiresAt) > now) && note.about.some(about => nodes.some(node => planNodesIntersect(node, about)))) : [];
+}

package/src/memory/policy.ts

@@ -6,6 +6,18 @@ import { nodePath, pathCandidates } from "./project.ts";
 
 /** True means the complete value is public. Hosts may narrow, never replace, standalone policy. */
 export interface MemoryPolicy { screen(value: unknown): Promise<boolean> }
+/**
+ * The standalone policy. `screenStandalone` is its own part only (secrets, default PII, configured PII patterns and deny paths) as a synchronous
+ * answer, for callers that cannot await (the store's promotion screen); it never asks the host, so a caller with a host uses `screen`.
+ */
+export interface StandalonePolicy extends MemoryPolicy {
+  screenStandalone(value: unknown): boolean;
+  /**
+   * Only the personal-data and configured-pattern and deny-path part of `screenStandalone`, without the secret screen, for a caller that counts secrets
+   * separately (the claude-mem import reports `pii` and `secret` skips as two numbers). True means the value names personal data or something configured.
+   */
+  declinesPersonal(text: string): boolean;
+}
 export interface StandalonePolicyOptions {
   denyPaths?: readonly string[];
   /** Case-insensitive literal substrings, not executable regular expressions. */
@@ -14,7 +26,7 @@ export interface StandalonePolicyOptions {
 }
 
 const MAX_DEPTH = 16, MAX_NODES = 4096, MAX_BYTES = 256 * 1024, MAX_STRING_BYTES = 16 * 1024;
-const fold = (text: string) => text.normalize("NFKC").replace(/\p{Default_Ignorable_Code_Point}/gu, "").toLowerCase().replace(/\\/g, "/");
+export const fold = (text: string) => text.normalize("NFKC").replace(/\p{Default_Ignorable_Code_Point}/gu, "").toLowerCase().replace(/\\/g, "/");
 const flags = new Set(["private", "pii", "privateturn", "isprivate", "ispii"]);
 
 /** Inspect descriptors, not getters/toJSON, and build the only value a host is allowed to see. */
@@ -67,6 +79,9 @@ function snapshot(value: unknown): { value: unknown; texts: string[] } | undefin
   catch { return undefined; }
 }
 
+/** Safe structural data copy for optional readers, before any getters/toJSON can run. It is not a public verdict. */
+export function memoryPolicySnapshot<T>(value: T): T | undefined { return snapshot(value)?.value as T | undefined; }
+
 function literals(value: unknown, label: string): string[] {
   if (value === undefined) return [];
   if (types.isProxy(value) || !Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype || value.length > 64 || Object.getOwnPropertySymbols(value).length) throw new Error(`invalid ${label}`);
@@ -92,7 +107,7 @@ function defaultPii(text: string): boolean {
 }
 
 /** No filesystem, model, network or storage work occurs while constructing or screening this policy. */
-export function createStandalonePolicy(options: StandalonePolicyOptions = {}): MemoryPolicy {
+export function createStandalonePolicy(options: StandalonePolicyOptions = {}): StandalonePolicy {
   if (!options || typeof options !== "object" || types.isProxy(options) || Object.getPrototypeOf(options) !== Object.prototype || Object.getOwnPropertySymbols(options).length) throw new Error("invalid standalone policy options");
   const descriptors = Object.getOwnPropertyDescriptors(options);
   for (const [key, descriptor] of Object.entries(descriptors)) if (!["denyPaths", "piiPatterns", "host"].includes(key) || !("value" in descriptor)) throw new Error("invalid standalone policy options");
@@ -100,20 +115,36 @@ export function createStandalonePolicy(options: StandalonePolicyOptions = {}): M
   const pii = literals(descriptors.piiPatterns?.value, "PII patterns");
   const host = descriptors.host?.value as MemoryPolicy | undefined;
   if (host !== undefined && (!host || typeof host.screen !== "function")) throw new Error("invalid host policy");
+  const standalone = (value: unknown): { ok: boolean; value?: unknown } => {
+    try {
+      const complete = snapshot(value);
+      if (!complete) return { ok: false };
+      for (const text of complete.texts) {
+        if (looksSecret(text) || looksSecret(text.replace(/["']/g, ""))) return { ok: false };
+        const normalized = fold(text);
+        if (defaultPii(normalized) || pii.some(pattern => normalized.includes(pattern))) return { ok: false };
+        const candidates = normalized.includes("/") || /\.[a-z]/.test(normalized) ? pathCandidates(normalized) : [];
+        const paths = [normalized, nodePath(normalized), ...candidates, ...normalized.split(/[\s"'`(){}\[\],;:=<>]+/)];
+        for (const path of paths) if (path && isDenied(posix.normalize(path), deny)) return { ok: false };
+      }
+      return { ok: true, value: complete.value };
+    } catch { return { ok: false }; }
+  };
+  const personal = (text: string): boolean => {
+    const normalized = fold(text);
+    if (defaultPii(normalized) || pii.some(pattern => normalized.includes(pattern))) return true;
+    const candidates = normalized.includes("/") || /\.[a-z]/.test(normalized) ? pathCandidates(normalized) : [];
+    const paths = [normalized, nodePath(normalized), ...candidates, ...normalized.split(/[\s"'`(){}\[\],;:=<>]+/)];
+    return paths.some(path => path && isDenied(posix.normalize(path), deny));
+  };
   return {
+    screenStandalone: value => standalone(value).ok,
+    declinesPersonal: text => personal(text),
     async screen(value: unknown): Promise<boolean> {
       try {
-        const complete = snapshot(value);
-        if (!complete) return false;
-        for (const text of complete.texts) {
-          if (looksSecret(text) || looksSecret(text.replace(/["']/g, ""))) return false;
-          const normalized = fold(text);
-          if (defaultPii(normalized) || pii.some(pattern => normalized.includes(pattern))) return false;
-          const candidates = normalized.includes("/") || /\.[a-z]/.test(normalized) ? pathCandidates(normalized) : [];
-          const paths = [normalized, nodePath(normalized), ...candidates, ...normalized.split(/[\s"'`(){}\[\],;:=<>]+/)];
-          for (const path of paths) if (path && isDenied(posix.normalize(path), deny)) return false;
-        }
-        return host === undefined || await host.screen(complete.value) === true;
+        const own = standalone(value);
+        if (!own.ok) return false;
+        return host === undefined || await host.screen(own.value) === true;
       } catch { return false; }
     },
   };

package/src/memory/private-spans.ts

@@ -0,0 +1,32 @@
+/**
+ * `<private>...</private>` spans (the claude-mem convention) are dropped before anything else reads the text, so they are never screened, counted or
+ * stored. A leaf module with no imports: capture shaping, the candidate and work-list boundaries, notes, goals and imports all use it.
+ *
+ * Tags match the way an HTML reader would, so a variant cannot slip a span through: the name is case-insensitive, an opening tag may carry attributes
+ * (`<private class="x">`), whitespace before the name (`< private>`) and a self-closing slash (`<private/>`, which opens a span like any other opening
+ * tag, since a person who typed it meant what follows to stay private). A closing tag is `</private>` with the same latitude. Nested spans close from the
+ * inside out. An unclosed span drops everything to the end of the text. A stray closing tag is kept as plain text. `<privateer>` is not a tag.
+ */
+const TAG = /<\s*(\/?)\s*private(?=[\s/>])[^<>]*>/gi;
+
+export function stripPrivateSpans(text: string): string {
+  if (!/<\s*\/?\s*private(?=[\s/>])/i.test(text)) return text;
+  let out = "", depth = 0, last = 0, match: RegExpExecArray | null;
+  TAG.lastIndex = 0;
+  while ((match = TAG.exec(text))) {
+    const closing = match[1] === "/", stray = closing && depth === 0;
+    if (depth === 0) out += text.slice(last, stray ? match.index + match[0].length : match.index);   // a stray closer is plain text: keep it
+    if (closing) { if (depth > 0) depth--; } else depth++;
+    last = match.index + match[0].length;
+  }
+  if (depth === 0) out += text.slice(last);
+  return out;
+}
+
+/** The same strip over every string inside a plain value (one level of arrays and objects, as the callers' inputs are), leaving other values as they are. */
+export function stripPrivateDeep<T>(value: T, depth = 0): T {
+  if (typeof value === "string") return stripPrivateSpans(value) as T;
+  if (depth > 4 || value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(item => stripPrivateDeep(item, depth + 1)) as T;
+  return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([key, item]) => [key, stripPrivateDeep(item, depth + 1)])) as T;
+}

package/src/memory/project-export.ts

@@ -0,0 +1,122 @@
+import { Database } from "bun:sqlite";
+import { closeSync, constants, existsSync, lstatSync, openSync, rmSync, statSync, writeSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { walkShards } from "./catalog.ts";
+import { openCuratedForRead, requireShard } from "./curated-read.ts";
+import { projectState } from "./lifecycle.ts";
+import { realPath } from "./platform.ts";
+import { createStandalonePolicy, type MemoryPolicy } from "./policy.ts";
+import { looksSecret } from "./screen.ts";
+import { aliasedKeys, shardDir } from "./shard.ts";
+import { WorkListStore } from "./work-lists.ts";
+
+/**
+ * #15 T5 / D3: `amem project export <key> --to <file>`. One project's capture rows, curated notes, goals and work lists as one portable JSON bundle,
+ * written once to a new file with mode 0600. It changes no content file of the home: it opens the capture databases read-only and the curated store only to
+ * read, and only derived files (the curated `index.db`, `search.db`, SQLite sidecars) may refresh, as they do for any read. A destination inside the home is refused.
+ *
+ * The bundle leaves the home, so it is screened like sync and promotion are: a secret-looking value is withheld, and so is anything the host policy (when
+ * one is passed) declines. `withheld` counts the capture rows, notes and goals left out; a work list the policy declines is left out silently by its own store.
+ * A forgotten project cannot be exported (the person's decision stands); an archived one can. The write streams row by row, so a shard at its cap never has to
+ * fit in memory, and a failure removes the partial file it created.
+ */
+
+export const EXPORT_SCHEMA = "agent-mem.project-export/v1";
+/**
+ * ponytail: a seam, not a lock. The destination is checked (for the message) and then claimed with O_EXCL (for the guarantee); a test sets `afterCheck` to create
+ * the file in the gap between them, which is the only way to show that O_EXCL, not the check, keeps an export from replacing someone else's file.
+ */
+export const exportHooks: { afterCheck?: (file: string) => void } = {};
+export interface ExportCounts { capture: number; curated: number; goals: number; workLists: number }
+export interface ExportResult { file: string; project: string; counts: ExportCounts; withheld: number }
+const PAGE = 500;
+
+interface CaptureRowRaw { id: number; at: string; project: string; agent: string; event: string; tool: string | null; paths: string; status: string | null; excerpt: string }
+
+function destination(base: string, to: string): string {
+  if (typeof to !== "string" || !to.trim()) throw new Error("export needs --to <file>");
+  const file = resolve(to), parent = dirname(file), name = basename(file);
+  if (!name || file === parent) throw new Error("--to names a file, not a directory root");
+  let parentReal: string;
+  try { if (!statSync(parent).isDirectory()) throw new Error(); parentReal = realPath(parent); }
+  catch { throw new Error("the destination directory does not exist"); }
+  let homeReal = base;
+  try { homeReal = realPath(base); } catch { /* a home that is not there yet holds nothing to collide with */ }
+  if (parentReal === homeReal || parentReal.startsWith(homeReal + sep)) throw new Error("the destination is inside the memory home; choose a folder outside it");
+  if (lstatSync(file, { throwIfNoEntry: false })) throw new Error("the destination exists; export never overwrites");
+  return join(parentReal, name);
+}
+
+export async function exportProject(base: string, key: string, opts: { to: string; policy?: MemoryPolicy }): Promise<ExportResult> {
+  const project = requireShard(base, key);
+  if (projectState(base, project) === "forgotten") throw new Error(`project ${project} is forgotten: it cannot be exported`);
+  const file = destination(base, opts.to), policy = opts.policy ?? createStandalonePolicy();
+  exportHooks.afterCheck?.(file);
+  const allowed = async (value: unknown): Promise<boolean> => !looksSecret(JSON.stringify(value)) && await policy.screen(value);
+  const counts: ExportCounts = { capture: 0, curated: 0, goals: 0, workLists: 0 };
+  let withheld = 0;
+  let fd: number;
+  try { fd = openSync(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
+  catch { throw new Error("the destination exists; export never overwrites"); }
+  const out = (text: string) => { writeSync(fd, text); };
+  const stores: { close(): void }[] = [];
+  try {
+    out(`{"schema":${JSON.stringify(EXPORT_SCHEMA)},"project":${JSON.stringify(project)},"exportedAt":${JSON.stringify(new Date().toISOString())},"capture":[`);
+    let first = true;
+    const shard = walkShards(base).find(candidate => candidate.key === project);
+    for (const dir of shard?.machineDirs ?? []) {
+      const dbFile = join(dir, "capture.db");
+      if (!existsSync(dbFile)) continue;
+      const db = new Database(dbFile, { readonly: true });
+      try {
+        db.run("PRAGMA busy_timeout = 3000");
+        for (let after = 0; ;) {
+          const rows = db.query("SELECT id, at, project, agent, event, tool, paths, status, excerpt FROM rows WHERE id > ? ORDER BY id LIMIT ?").all(after, PAGE) as CaptureRowRaw[];
+          for (const r of rows) {
+            after = r.id;
+            const row = { at: r.at, agent: r.agent, event: r.event, tool: r.tool, paths: JSON.parse(r.paths) as string[], status: r.status, excerpt: r.excerpt };
+            if (!await allowed(row)) { withheld++; continue; }
+            out(`${first ? "" : ","}${JSON.stringify(row)}`); first = false; counts.capture++;
+          }
+          if (rows.length < PAGE) break;
+        }
+      } finally { db.close(); }
+    }
+    out(`],"curated":[`);
+    const store = openCuratedForRead(base, project);
+    if (store) stores.push(store);
+    // The project's own rows and those of a key aliased to it; another project's shared note is not this project's and stays out of its bundle.
+    const keys = new Set([project, ...aliasedKeys(base, project)]);
+    first = true;
+    for (const view of store?.list({ project, limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true }) ?? []) {
+      if (!keys.has(view.project)) continue;
+      if (!await allowed(view)) { withheld++; continue; }
+      out(`${first ? "" : ","}${JSON.stringify(view)}`); first = false; counts.curated++;
+    }
+    out(`],"goals":[`);
+    first = true;
+    for (const goal of store?.goals(project) ?? []) {
+      if (!keys.has(goal.project)) continue;
+      if (!await allowed(goal)) { withheld++; continue; }
+      out(`${first ? "" : ","}${JSON.stringify(goal)}`); first = false; counts.goals++;
+    }
+    out(`],"workLists":[`);
+    first = true;
+    // The bundle holds what the project's own reads show: the canonical work log and that of every key aliased to it (the same reconciliation the CLI, MCP and brief use).
+    const workKeys = [project, ...aliasedKeys(base, project)];
+    if (workKeys.some(key => existsSync(join(shardDir(base, key), "work")))) {
+      const work = new WorkListStore({ base, project, policy: allowed, aliases: workKeys.slice(1) });
+      stores.push({ close: () => work.close() });
+      for (const list of await work.read(undefined, true)) { out(`${first ? "" : ","}${JSON.stringify(list)}`); first = false; counts.workLists++; }
+    }
+    out(`],"counts":${JSON.stringify(counts)},"withheld":${withheld}}\n`);
+  } catch (error) {
+    try { closeSync(fd); } catch { /* already closed */ }
+    rmSync(file, { force: true });          // the file is ours: O_EXCL created it, so a partial bundle is removed, never left behind
+    throw error;
+  } finally {
+    for (const store of stores) { try { store.close(); } catch { /* best effort */ } }
+  }
+  closeSync(fd);
+  return { file, project, counts, withheld };
+}

package/src/memory/recall-staleness.ts

@@ -0,0 +1,56 @@
+import { lstatSync, type Stats } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { isDenied } from "./platform.ts";
+import { fold, type StandalonePolicy } from "./policy.ts";
+import { nodePath } from "./project.ts";
+import type { View } from "./store.ts";
+
+export interface RecallStalenessOptions {
+  cwd: string; rootConfirmed?: boolean; deny?: readonly string[]; policy?: () => StandalonePolicy;
+  /** Host-only lexical glob/private-path checks run before any filesystem probe. */
+  allowedPath?: (path: string) => boolean;
+  maxProbes?: number;
+  probe?: (path: string) => Pick<Stats, "isSymbolicLink" | "isDirectory" | "mtimeMs">;
+}
+type PathState = { state: "present"; mtime: number } | { state: "missing" | "unknown" };
+/** Call-scoped metadata hint only. Unknown/denied paths never become a marker or a filesystem query. */
+export function createRecallStalenessProbe(options: RecallStalenessOptions): (view: Pick<View, "about" | "at">) => boolean | undefined {
+  const root = resolve(options.cwd), cache = new Map<string, PathState>(), requested = options.maxProbes ?? 32;
+  let remaining = Number.isSafeInteger(requested) && requested >= 0 ? Math.min(requested, 32) : 0;
+  const allowed = (path: string): boolean => {
+    try { return !isDenied(path, [...options.deny ?? []]) && !isDenied(fold(path), [...options.deny ?? []].map(fold)) && options.allowedPath?.(path) !== false && (!options.policy || options.policy().screenStandalone({ path })); }
+    catch { return false; }
+  };
+  const inspect = (path: string): PathState => {
+    if (!path || path.length > 4096 || isAbsolute(path) || /[\p{Cc}\p{Cf}\\]/u.test(path) || path.split("/").includes("..") || !allowed(path)) return { state: "unknown" };
+    const target = resolve(root, path), rel = relative(root, target); let current = root;
+    if (!rel || rel.startsWith("../") || isAbsolute(rel)) return { state: "unknown" };
+    const chainAllowed = () => { let at = root; for (const part of rel.split("/")) { at = join(at, part); if (!allowed(relative(root, at))) return false; } return true; };
+    if (!chainAllowed()) return { state: "unknown" };
+    if (cache.has(path)) return cache.get(path)!;
+    for (const component of rel.split("/")) {
+      current = join(current, component); const name = relative(root, current);
+      if (remaining < 1 || !allowed(name)) return { state: "unknown" };
+      remaining--;
+      try {
+        const stat = (options.probe ?? lstatSync)(current);
+        if (stat.isSymbolicLink() || current !== target && !stat.isDirectory()) return { state: "unknown" };
+        if (current === target) { const value: PathState = Number.isFinite(stat.mtimeMs) ? { state: "present", mtime: stat.mtimeMs } : { state: "unknown" }; if (!chainAllowed()) return { state: "unknown" }; cache.set(path, value); return value; }
+      } catch (error) { const value: PathState = { state: (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "unknown" }; if (!chainAllowed()) return { state: "unknown" }; cache.set(path, value); return value; }
+    }
+    return { state: "unknown" };
+  };
+  // ponytail: same-user ancestor swaps are outside the current metadata-only fence. Descriptor-relative traversal
+  // is required before treating concurrent hostile filesystem mutation as supported. No source/symbol index is stored.
+  return view => {
+    const at = Date.parse(view.at); if (!Number.isFinite(at)) return undefined;
+    let known = false;
+    for (const node of view.about) {
+      const path = nodePath(node); if (path === undefined) continue;
+      const state = inspect(path);
+      if (state.state === "missing" && options.rootConfirmed === true || state.state === "present" && state.mtime > at) return true;
+      known ||= state.state === "present";
+    }
+    return known ? false : undefined;
+  };
+}

package/src/memory/recall.ts

@@ -0,0 +1,74 @@
+import type { MemoryStore, RecallStateOptions, RetainedRecallState, Graph, View } from "./store.ts";
+
+export interface RecallOptions extends RecallStateOptions { query?: string; limit?: number }
+/** Only public read semantics; mutation and exact-revision callers continue to use Store.get directly. */
+export function recallViewIsLive(view: View, now: number): boolean {
+  return !view.supersededBy && Number.isFinite(Date.parse(view.at))
+    && (view.expiresAt === null || Number.isFinite(Date.parse(view.expiresAt)) && Date.parse(view.expiresAt) > now);
+}
+const PROMOTION_NOTICE = "promotion time unknown: tier before promotion cannot be recovered";
+/** Narrow promotion uncertainty to emitted rows while retaining independent source diagnostics. */
+export function recallForViews(state: RetainedRecallState, views: View[]): RetainedRecallState {
+  const notices = state.notices.filter(notice => notice !== PROMOTION_NOTICE || views.some(view => view.promotedFrom));
+  return { ...state, views, notices, incomplete: state.sourceIncomplete === true || state.malformed > 0 || notices.length > 0 };
+}
+function personRecall(options: RecallStateOptions): void {
+  if ((options.history || options.asOf !== undefined) && options.person !== true) throw Error("historical recall requires authenticated person intent from the host");
+}
+export function recallRows(store: MemoryStore, project: string, options: RecallOptions = {}): RetainedRecallState {
+  personRecall(options);
+  const limit = options.limit ?? 5000;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > Number.MAX_SAFE_INTEGER) throw Error("recall limit must be a positive safe integer");
+  const state: RetainedRecallState = options.history || options.asOf !== undefined ? store.recallState(project, options)
+    : store.withDeferredPromotions(() => ({ at: new Date(store.readNow()).toISOString(), views: store.list({ project, limit: Number.MAX_SAFE_INTEGER }).filter(view => recallViewIsLive(view, store.readNow())), forgotten: [], relations: [], malformed: 0, incomplete: false, notices: [] }));
+  const words = options.query?.toLowerCase().split(/\s+/).filter(Boolean) ?? [];
+  const rows = state.views.filter(view => words.every(word => `${view.title ?? ""}\n${view.text}\n${view.about.join(" ")}`.toLowerCase().includes(word)))
+    .sort((a, b) => b.at.localeCompare(a.at) || a.id.localeCompare(b.id));
+  const selected = recallForViews(state, rows.slice(0, limit));
+  return { ...selected, incomplete: selected.incomplete || rows.length > limit };
+}
+export interface RecallShown { entry?: View; state?: RetainedRecallState; ids: string[] }
+export function recallShow(store: MemoryStore, project: string, rawId: string, options: RecallStateOptions = {}): RecallShown {
+  personRecall(options);
+  const id = rawId.replace(/^mem:/, "");
+  if (!/^[a-f0-9]{6,32}$/.test(id)) return { ids: [] };
+  if (!options.history && options.asOf === undefined) {
+    const view = store.withDeferredPromotions(() => store.get(id, project));
+    return view && recallViewIsLive(view, store.readNow()) ? { entry: view, ids: [view.id] } : { ids: [] };
+  }
+  const state = store.recallState(project, options), known = [...new Set([...state.views.map(view => view.id), ...state.forgotten.map(row => row.id)])];
+  const matches = known.includes(id) ? [id] : known.filter(value => value.startsWith(id));
+  if (matches.length !== 1) return { ids: [] };
+  const selected = new Set(matches), queue = [...matches], knownIds = new Set(known);
+  if (options.history) for (let index = 0; index < queue.length && queue.length <= 64; index++) {
+    for (const edge of state.relations) for (const next of edge.from === queue[index] ? [edge.to] : edge.to === queue[index] ? [edge.from] : []) {
+      if (knownIds.has(next) && !selected.has(next)) { selected.add(next); queue.push(next); }
+    }
+  }
+  if (queue.length > 64) throw Error("recall history chain exceeds 64 retained entries");
+  const views = state.views.filter(view => selected.has(view.id));
+  return { entry: views.find(view => view.id === matches[0]), ids: [...selected], state: { ...recallForViews(state, views), forgotten: state.forgotten.filter(row => selected.has(row.id)), relations: state.relations.filter(edge => selected.has(edge.from) && selected.has(edge.to)) } };
+}
+
+/** Public graph over live recall rows; retained history requires host-authenticated person intent. */
+export function recallGraph(store: MemoryStore, project: string, start: string, hops = 1, options: RecallOptions = {}, readable: (rows: View[]) => View[] = rows => rows): Graph {
+  personRecall(options);
+  const rows = readable(recallRows(store, project, { ...options, limit: Number.MAX_SAFE_INTEGER }).views);
+  let node = start;
+  if (!start.includes(":") || start.startsWith("mem:")) {
+    const id = start.replace(/^mem:/, ""), exact = rows.find(view => view.id === id), matches = exact ? [exact] : id.length >= 6 ? rows.filter(view => view.id.startsWith(id)) : [];
+    if (matches.length !== 1) return { nodes: [], edges: [] };
+    node = `mem:${matches[0]!.id}`;
+  }
+  return store.withDeferredPromotions(() => store.graph(project, node, hops, 200, rows));
+}
+
+/** One prepared snapshot; its revision guard rejects changes after asynchronous host policy work. */
+export function createIntentBriefSource(store: MemoryStore, project: string): { notes(): View[]; assertCurrent(): void; truncated(): boolean } {
+  let snapshot: ReturnType<MemoryStore["intentSnapshot"]> | undefined;
+  return {
+    notes: () => { snapshot ??= store.intentSnapshot(project); return snapshot.rows; },
+    assertCurrent: () => { if (!snapshot) throw Error("intent snapshot has not been prepared"); snapshot.assertCurrent(); },
+    truncated: () => snapshot?.truncated ?? false,
+  };
+}