@staix/agent-mem 0.6.0 → 0.8.0

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

@@ -99,7 +99,18 @@ export function memoryGitEnv(env: NodeJS.ProcessEnv = process.env, options: { re
 /** spawnSync form of the same call: the env option is merged with memoryGitEnv, everything else passes through. */
 export function memoryGitSync(args: string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string> {
   const argv = memoryGitArgv(args);
-  return childProcess().spawnSync(argv[0]!, argv.slice(1), { ...options, env: memoryGitEnv(options.env ?? process.env) });
+  return childProcess().spawnSync(argv[0]!, argv.slice(1), { ...(ambientGitTimeout !== undefined ? { timeout: ambientGitTimeout, killSignal: "SIGKILL" as const } : {}), ...options, env: memoryGitEnv(options.env ?? process.env) });
+}
+let ambientGitTimeout: number | undefined;
+/**
+ * Runs `work` with a timeout on every `memoryGitSync` call that sets none of its own: a synchronous git call blocks the event loop, so a signal sent to this process alone waits for it.
+ * A call that times out reads as a failed git (`error` set, no status), which every caller already treats as "unknown". The setting is process-wide while `work` runs, so use it only in a
+ * command that does nothing else at the same time (`amem doctor`).
+ * ponytail: one global instead of a parameter on every caller between doctor and its git calls (project key, repository root, visibility). Upgrade: thread an options argument through them.
+ */
+export async function withGitTimeout<T>(ms: number, work: () => Promise<T>): Promise<T> {
+  const prior = ambientGitTimeout; ambientGitTimeout = ms;
+  try { return await work(); } finally { ambientGitTimeout = prior; }
 }
 
 /**

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,157 @@
+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 and F17: `amem project export <key> --to <file>`. One project's capture rows, curated notes, goals and work lists as a portable JSON bundle,
+ * JSONL stream or Markdown document, 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. A failure removes the partial file it created.
+ * ponytail: JSONL capture, goal and work-list rows stream, but curated authored rows are materialized to preserve ids. Add a bounded authored-row iterator before raising shard limits.
+ */
+
+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 type ProjectExportFormat = "json" | "jsonl" | "markdown";
+export interface ExportCounts { capture: number; curated: number; goals: number; workLists: number }
+export interface ExportResult { file: string; project: string; format: ProjectExportFormat; counts: ExportCounts; withheld: number }
+type ExportSection = keyof ExportCounts;
+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);
+}
+
+function markdownInline(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function markdownRecord(section: ExportSection, value: unknown): string {
+  const row = value as Record<string, unknown>;
+  const body = section === "capture" ? row.excerpt : section === "curated" ? row.text : undefined;
+  const identity = typeof row.id === "string" ? ` ${row.id}` : "";
+  const metadata = { ...row };
+  if (section === "capture") delete metadata.excerpt;
+  if (section === "curated") delete metadata.text;
+  const lines = [`### ${section}${identity}`, "", `    ${JSON.stringify(metadata)}`, ""];
+  if (typeof body === "string") lines.push(...body.split(/\r\n|\r|\n/).map(line => `    ${line}`), "");
+  return `${lines.join("\n")}\n`;
+}
+
+export async function exportProject(base: string, key: string, opts: { to: string; policy?: MemoryPolicy; format?: ProjectExportFormat }): Promise<ExportResult> {
+  const project = requireShard(base, key), format = opts.format ?? "json";
+  if (!["json", "jsonl", "markdown"].includes(format)) throw new Error("export format must be json, jsonl or markdown");
+  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 exportedAt = new Date().toISOString();
+  let first = true, section: ExportSection = "capture";
+  const begin = (jsonPrefix: string, next: ExportSection, heading: string) => {
+    section = next; first = true;
+    if (format === "json") out(jsonPrefix);
+    else if (format === "markdown") out(`\n## ${heading}\n\n`);
+  };
+  const emit = (value: unknown) => {
+    if (format === "json") out(`${first ? "" : ","}${JSON.stringify(value)}`);
+    else if (format === "jsonl") out(`${JSON.stringify({ schema: EXPORT_SCHEMA, project, type: section, value })}\n`);
+    else out(markdownRecord(section, value));
+    first = false;
+  };
+  const stores: { close(): void }[] = [];
+  try {
+    if (format === "jsonl") out(`${JSON.stringify({ schema: EXPORT_SCHEMA, project, exportedAt, type: "header", aliases: aliasedKeys(base, project) })}\n`);
+    else if (format === "markdown") out(`# Project export ${markdownInline(JSON.stringify(project))}\n\nExported at ${exportedAt}\n`);
+    begin(`{"schema":${JSON.stringify(EXPORT_SCHEMA)},"project":${JSON.stringify(project)},"exportedAt":${JSON.stringify(exportedAt)},"capture":[`, "capture", "Capture");
+    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; }
+            emit(row); counts.capture++;
+          }
+          if (rows.length < PAGE) break;
+        }
+      } finally { db.close(); }
+    }
+    begin(`],"curated":[`, "curated", "Curated notes");
+    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)]);
+    const authored = format === "jsonl" ? new Map((store?.portableNotes(project) ?? []).map(row => [row.id, row])) : undefined;
+    for (const view of store?.list({ project, limit: Number.MAX_SAFE_INTEGER, includeSuperseded: true }) ?? []) {
+      if (!keys.has(view.project)) continue;
+      const value = format === "jsonl" ? authored!.get(view.id) : view;
+      if (!value) throw new Error("exported note's authored row is unavailable");
+      if (!await allowed(value)) { withheld++; continue; }
+      emit(value); counts.curated++;
+    }
+    begin(`],"goals":[`, "goals", "Goals");
+    for (const goal of store?.goals(project) ?? []) {
+      if (!keys.has(goal.project)) continue;
+      if (!await allowed(goal)) { withheld++; continue; }
+      emit(goal); counts.goals++;
+    }
+    begin(`],"workLists":[`, "workLists", "Work lists");
+    // 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)) { emit(list); counts.workLists++; }
+    }
+    if (format === "json") out(`],"counts":${JSON.stringify(counts)},"withheld":${withheld}}\n`);
+    else if (format === "jsonl") out(`${JSON.stringify({ schema: EXPORT_SCHEMA, project, type: "counts", counts, withheld })}\n`);
+    else out(`\n## Counts\n\n${JSON.stringify({ counts, 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, format, counts, withheld };
+}

package/src/memory/project-import.ts

@@ -0,0 +1,147 @@
+import { createHash } from "node:crypto";
+import { constants, createReadStream, fstatSync, openSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { isDeepStrictEqual } from "node:util";
+import { legacyEntries } from "./bridge.ts";
+import { stripPrivateDeep, stripPrivateSpans } from "./private-spans.ts";
+import { EXPORT_SCHEMA } from "./project-export.ts";
+import { aliasedKeys } from "./shard.ts";
+import { looksSecret, type MemoryStore, type NoteInput } from "./store.ts";
+
+export const PROJECT_IMPORT_MAX_BYTES = 64 * 1024 * 1024;
+export const PROJECT_IMPORT_MAX_LINE_BYTES = 64 * 1024;
+export const PROJECT_IMPORT_FUTURE_SKEW_MS = 5 * 60 * 1000;
+const NOTE_KEYS = new Set(["schema", "id", "at", "machine", "op", "project", "scope", "tier", "kind", "peer", "title", "text", "task", "about", "supersedes", "promotedFrom", "source", "expires"]);
+const OPERATIONS_WARNING = "Supersede, demote, settle and forget operations are not exported; re-import restores authored note rows only.";
+
+type ImportedNote = { id: string; at: string; machine: string; note: NoteInput };
+type Provenance = { source: Record<string, number>; peer: Record<string, number>; scope: Record<string, number> };
+export interface ProjectImportResult {
+  applied: boolean;
+  project: string;
+  read: number;
+  added: number;
+  wouldAdd: number;
+  skipped: { invalid: number; policy: number; other: number };
+  provenance: Provenance;
+  warnings: string[];
+}
+
+function importedNote(value: unknown, projects: readonly string[]): ImportedNote | undefined {
+  try {
+    if (!value || typeof value !== "object" || Array.isArray(value) || !Object.keys(value).every(key => NOTE_KEYS.has(key))) return undefined;
+    const bytes = Buffer.from(`${JSON.stringify(value)}\n`);
+    const [row] = legacyEntries([{ source: "legacy-local", path: "log/project-import.jsonl", bytes, offset: bytes.length,
+      hash: createHash("sha256").update(bytes).digest("hex"), local: false, tailBytes: 0 }], { strict: true });
+    if (row?.op !== "note" || !projects.includes(row.project)) return undefined;
+    const { id, at, machine, ...rest } = row;
+    const note = Object.fromEntries(Object.entries(rest).filter(([key]) => key !== "schema")) as NoteInput;
+    return { id, at, machine, note };
+  } catch { return undefined; }
+}
+
+function increment(counts: Map<string, number>, value: string | undefined): void {
+  const key = value ?? "unspecified";
+  counts.set(key, (counts.get(key) ?? 0) + 1);
+}
+
+function provenance(notes: Iterable<ImportedNote>): Provenance {
+  const source = new Map<string, number>(), peer = new Map<string, number>(), scope = new Map<string, number>();
+  for (const { note } of notes) {
+    increment(source, note.source);
+    increment(peer, note.peer);
+    increment(scope, note.scope);
+  }
+  return { source: Object.fromEntries(source), peer: Object.fromEntries(peer), scope: Object.fromEntries(scope) };
+}
+
+function unchangedAfterNormalization(note: NoteInput): boolean {
+  return stripPrivateSpans(note.text).slice(0, 4000) === note.text
+    && (typeof note.title !== "string" || stripPrivateSpans(note.title).slice(0, 200) === note.title);
+}
+
+/** Preview by default; confirm applies only after every row, relationship, identity and policy decision has passed without a curated write. */
+export async function importProject(store: MemoryStore, opts: {
+  from: string;
+  project: string;
+  confirm?: boolean;
+  allowShared?: boolean;
+  policy: (note: NoteInput) => boolean | Promise<boolean>;
+}): Promise<ProjectImportResult> {
+  const fd = openSync(opts.from, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  const stream = createReadStream(opts.from, { fd, encoding: "utf8" });
+  const result: ProjectImportResult = { applied: opts.confirm === true, project: opts.project, read: 0, added: 0, wouldAdd: 0,
+    skipped: { invalid: 0, policy: 0, other: 0 }, provenance: { source: {}, peer: {}, scope: {} }, warnings: [OPERATIONS_WARNING] };
+  let header = false, bytes = 0;
+  let aliases: string[] = [];
+  const pending = new Map<string, ImportedNote>(), accepted: ImportedNote[] = [];
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > PROJECT_IMPORT_MAX_BYTES) throw new Error("project import needs a regular JSONL file of at most 64 MiB");
+    const lines = createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+      for await (const line of lines) {
+        bytes += Buffer.byteLength(line, "utf8") + 1;
+        if (bytes > PROJECT_IMPORT_MAX_BYTES) throw new Error("project import exceeded 64 MiB while reading");
+        if (Buffer.byteLength(line, "utf8") > PROJECT_IMPORT_MAX_LINE_BYTES) { result.skipped.invalid++; continue; }
+        if (!line.trim()) continue;
+        let row: Record<string, unknown>;
+        try {
+          const parsed: unknown = JSON.parse(line);
+          if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
+          row = parsed as Record<string, unknown>;
+        } catch { result.skipped.invalid++; continue; }
+        if (row.schema !== EXPORT_SCHEMA || row.project !== opts.project) throw new Error("project import schema or project mismatch");
+        if (row.type === "header") {
+          if (header) throw new Error("project import has more than one header");
+          if (!Array.isArray(row.aliases) || !row.aliases.every(alias => typeof alias === "string")) throw new Error("project import aliases are invalid");
+          aliases = [...row.aliases] as string[];
+          const available = aliasedKeys(store.profile.home, opts.project);
+          if (aliases.some(alias => !available.includes(alias))) throw new Error("project import requires the exported aliases in the target home");
+          header = true; continue;
+        }
+        if (!header) throw new Error("project import needs its header first");
+        if (row.type === "counts") continue;
+        if (row.type !== "curated") { result.skipped.other++; continue; }
+        result.read++;
+        const imported = importedNote(row.value, [opts.project, ...aliases]);
+        if (!imported || Date.parse(imported.at) > store.readNow() + PROJECT_IMPORT_FUTURE_SKEW_MS
+          || imported.note.scope === "shared" && opts.allowShared !== true || !unchangedAfterNormalization(imported.note)) {
+          result.skipped.invalid++;
+          continue;
+        }
+        const prior = pending.get(imported.id);
+        if (prior) {
+          if (!isDeepStrictEqual(prior, imported)) throw new Error("project import has conflicting rows for one entry id");
+          continue;
+        }
+        pending.set(imported.id, imported);
+      }
+    } finally { lines.close(); }
+    if (!header) throw new Error("project import has no header");
+
+    for (const imported of pending.values()) {
+      if (["supersedes", "promotedFrom"].some(field => {
+        const target = imported.note[field as "supersedes" | "promotedFrom"] as string | null | undefined;
+        return target !== undefined && target !== null && !pending.has(target);
+      })) {
+        result.skipped.invalid++;
+        continue;
+      }
+      const screened = stripPrivateDeep(imported.note);
+      if (looksSecret(JSON.stringify(screened)) || !await opts.policy(screened)) { result.skipped.policy++; continue; }
+      accepted.push(imported);
+    }
+    result.provenance = provenance(accepted);
+    const existing = new Set(store.portableNotes(opts.project).map(note => note.id));
+    result.wouldAdd = accepted.filter(note => !existing.has(note.id)).length;
+    if (opts.confirm === true) {
+      for (const imported of accepted) {
+        const written = store.importNote(imported.note, imported.at, { machine: imported.machine, expectedId: imported.id });
+        if (written.added) result.added++;
+      }
+      store.refresh();
+    }
+    return result;
+  } finally { stream.destroy(); }
+}