@staix/agent-mem 0.7.0 → 0.8.0

package/src/memory/external-import.ts

@@ -0,0 +1,267 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, opendirSync, readSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, extname, join, relative, sep } from "node:path";
+import { aliasedKeys, resolveAlias } from "./aliases.ts";
+import { CandidateQueueFull, CandidateStore, candidateInputId, type CandidateInput } from "./candidates.ts";
+import { pendingSummary, type PendingSummary } from "./candidate-pending.ts";
+import { realPath } from "./platform.ts";
+import { stripPrivateDeep } from "./private-spans.ts";
+import { looksSecret } from "./screen.ts";
+
+/** Discovery and read bounds for one import: at most 256 files, 512 directories, 512 entries per directory, 16 directory levels, 1 MiB per file and 100 new candidates. */
+export const EXTERNAL_IMPORT_LIMITS = { maxFiles: 256, maxDirectories: 512, maxEntriesPerDirectory: 512, maxDepth: 16, maxFileBytes: 1024 * 1024, maxCandidatesPerRun: 100, candidateTextChars: 3000, titleChars: 200 } as const;
+
+export type ExternalMemorySource = "claude-auto" | "codex";
+export interface ExternalImportResult {
+  source: ExternalMemorySource;
+  project: string;
+  files: number;
+  read: number;
+  added: number;
+  queueFull: boolean;
+  limitReached: boolean;
+  skipped: { rules: number; policy: number; invalid: number; truncated: number };
+  pending: PendingSummary;
+}
+
+type SourceFile = { path: string; relative: string };
+type RawRecord = { text: string; title?: string; line?: number };
+type Discovery = { files: SourceFile[]; rules: number };
+
+function entryKind(path: string): "file" | "directory" | "symlink" | "other" | undefined {
+  try {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) return "symlink";
+    if (stat.isFile()) return "file";
+    if (stat.isDirectory()) return "directory";
+    return "other";
+  } catch { return undefined; }
+}
+
+function sourceRoot(path: string): string | undefined {
+  if (entryKind(path) !== "directory") return undefined;
+  try {
+    const root = realPath(path);
+    for (let dir = root;; dir = dirname(dir)) {
+      if (entryKind(dir) !== "directory") return undefined;
+      const parent = dirname(dir);
+      if (parent === dir) return root;
+    }
+  } catch { return undefined; }
+}
+
+function names(path: string): string[] {
+  let dir;
+  try {
+    dir = opendirSync(path);
+    const output: string[] = [];
+    while (output.length < EXTERNAL_IMPORT_LIMITS.maxEntriesPerDirectory) {
+      const entry = dir.readSync();
+      if (!entry) break;
+      output.push(entry.name);
+    }
+    return output;
+  } catch { return []; }
+  finally { dir?.closeSync(); }
+}
+
+function ruleFile(path: string): boolean {
+  const name = basename(path).toLowerCase();
+  return name === "claude.md" || name === "agents.md" || name === "agents.override.md" || name.endsWith(".local.md");
+}
+
+function useful(path: string, source: ExternalMemorySource): boolean {
+  const extension = extname(path).toLowerCase();
+  return source === "claude-auto" ? extension === ".md" : extension === ".md" || extension === ".txt" || extension === ".jsonl";
+}
+
+function discoverClaude(root: string, projectDirectory?: string): Discovery {
+  const files: SourceFile[] = [];
+  let rules = 0, directories = 1;
+  for (const project of projectDirectory === undefined ? names(root) : [projectDirectory]) {
+    if (directories >= EXTERNAL_IMPORT_LIMITS.maxDirectories || files.length >= EXTERNAL_IMPORT_LIMITS.maxFiles) break;
+    const projectPath = join(root, project), projectKind = entryKind(projectPath);
+    if (projectKind === "symlink") { rules++; continue; }
+    if (projectKind !== "directory") continue;
+    directories++;
+    const memoryPath = join(projectPath, "memory"), memoryKind = entryKind(memoryPath);
+    if (memoryKind === "symlink") { rules++; continue; }
+    if (memoryKind !== "directory") continue;
+    if (directories >= EXTERNAL_IMPORT_LIMITS.maxDirectories) break;
+    directories++;
+    for (const name of names(memoryPath)) {
+      if (files.length >= EXTERNAL_IMPORT_LIMITS.maxFiles) break;
+      const path = join(memoryPath, name), kind = entryKind(path);
+      if (kind === "symlink") { rules++; continue; }
+      if (kind !== "file" || !useful(path, "claude-auto")) continue;
+      if (ruleFile(path)) { rules++; continue; }
+      files.push({ path, relative: [project, "memory", name].join("/") });
+    }
+  }
+  return { files, rules };
+}
+
+function discoverCodex(root: string): Discovery {
+  const files: SourceFile[] = [];
+  let rules = 0, directories = 0;
+  const pending: { path: string; relative: string; depth: number }[] = [{ path: root, relative: "", depth: 0 }];
+  while (pending.length && directories < EXTERNAL_IMPORT_LIMITS.maxDirectories && files.length < EXTERNAL_IMPORT_LIMITS.maxFiles) {
+    const current = pending.shift()!;
+    if (entryKind(current.path) !== "directory") continue;
+    directories++;
+    const directoriesToAdd: { path: string; relative: string; depth: number }[] = [];
+    for (const name of names(current.path)) {
+      if (files.length >= EXTERNAL_IMPORT_LIMITS.maxFiles) break;
+      const path = join(current.path, name), relative = current.relative ? `${current.relative}/${name}` : name;
+      const kind = entryKind(path);
+      if (kind === "symlink") { rules++; continue; }
+      if (kind === "directory") {
+        if (basename(path).toLowerCase() === "rules") { rules++; continue; }
+        if (current.depth < EXTERNAL_IMPORT_LIMITS.maxDepth) directoriesToAdd.push({ path, relative, depth: current.depth + 1 });
+        continue;
+      }
+      if (kind !== "file" || !useful(path, "codex")) continue;
+      if (ruleFile(path)) { rules++; continue; }
+      files.push({ path, relative });
+    }
+    pending.push(...directoriesToAdd);
+  }
+  return { files, rules };
+}
+
+function readBounded(path: string, root: string): { text: string; truncated: boolean } | undefined {
+  const tail = relative(root, path);
+  if (!tail || tail === ".." || tail.startsWith(`..${sep}`) || entryKind(path) !== "file") return undefined;
+  for (let dir = dirname(path);; dir = dirname(dir)) {
+    if (entryKind(dir) !== "directory") return undefined;
+    if (dir === root) break;
+    if (dir === dirname(dir)) return undefined;
+  }
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    if (!fstatSync(fd).isFile()) return undefined;
+    const buffer = Buffer.alloc(EXTERNAL_IMPORT_LIMITS.maxFileBytes + 1);
+    let read = 0;
+    while (read < buffer.length) {
+      const count = readSync(fd, buffer, read, buffer.length - read, read);
+      if (!count) break;
+      read += count;
+    }
+    return { text: buffer.subarray(0, Math.min(read, EXTERNAL_IMPORT_LIMITS.maxFileBytes)).toString("utf8"), truncated: read > EXTERNAL_IMPORT_LIMITS.maxFileBytes };
+  } catch { return undefined; }
+  finally { if (fd !== undefined) try { closeSync(fd); } catch { /* already closed */ } }
+}
+
+function records(file: SourceFile, text: string): (RawRecord | undefined)[] {
+  if (extname(file.path).toLowerCase() !== ".jsonl") return [text.trim() && !text.includes("\0") ? { text } : undefined];
+  const lines = text.split(/\r\n|\r|\n/);
+  if (lines.at(-1) === "") lines.pop();
+  return lines.map((line, index): RawRecord | undefined => {
+    try {
+      const value: unknown = JSON.parse(line);
+      if (typeof value === "string") return value.trim() && !value.includes("\0") ? { text: value, line: index + 1 } : undefined;
+      if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+      const record = value as { text?: unknown; title?: unknown };
+      if (typeof record.text !== "string" || !record.text.trim() || record.text.includes("\0") || record.title !== undefined && typeof record.title !== "string") return undefined;
+      return { text: record.text, ...(typeof record.title === "string" ? { title: record.title } : {}), line: index + 1 };
+    } catch { return undefined; }
+  });
+}
+
+function chunks(text: string): string[] {
+  const output: string[] = [];
+  let rest = text.trim();
+  while (rest.length > EXTERNAL_IMPORT_LIMITS.candidateTextChars) {
+    let end = EXTERNAL_IMPORT_LIMITS.candidateTextChars;
+    const newline = rest.lastIndexOf("\n", end);
+    if (newline >= Math.floor(end / 2)) end = newline + 1;
+    if (end > 0 && /[\uD800-\uDBFF]/.test(rest[end - 1]!)) end--;
+    const chunk = rest.slice(0, end).trim();
+    if (chunk) output.push(chunk);
+    rest = rest.slice(end).trimStart();
+  }
+  if (rest) output.push(rest);
+  return output;
+}
+
+function cleanTitle(text: string): string {
+  return text.replace(/[\x00-\x1f\x7f]+/g, " ").replace(/\s+/g, " ").trim();
+}
+
+function boundedTitle(text: string): string {
+  const clean = cleanTitle(text), max = EXTERNAL_IMPORT_LIMITS.titleChars;
+  if (clean.length <= max) return clean;
+  let left = 80, right = max - left - 3;
+  if (/[\uD800-\uDBFF]/.test(clean[left - 1]!)) left--;
+  let tail = clean.length - right;
+  if (tail > 0 && /[\uDC00-\uDFFF]/.test(clean[tail]!)) tail++;
+  return `${clean.slice(0, left)}...${clean.slice(tail)}`;
+}
+
+function title(source: ExternalMemorySource, file: SourceFile, record: RawRecord, part: number, parts: number): string {
+  const location = `${file.relative}${record.line === undefined ? "" : `#${record.line}`}`;
+  const suffix = parts > 1 ? ` (part ${part + 1}/${parts})` : "";
+  return boundedTitle(`${source}: ${location}${record.title?.trim() ? `: ${record.title}` : ""}${suffix}`);
+}
+
+function portable(path: string): string { return path.split(sep).join("/"); }
+function claudeProjectDirectory(cwd: string): string { return realPath(cwd).replace(/[/.]/g, "-"); }
+
+export async function importExternalMemory(opts: {
+  base: string;
+  project: string;
+  source: ExternalMemorySource;
+  from?: string;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  policy: (value: unknown) => boolean | Promise<boolean>;
+}): Promise<ExternalImportResult> {
+  if (opts.source !== "claude-auto" && opts.source !== "codex") throw new Error("unknown external memory source");
+  const env = opts.env ?? process.env, home = env.HOME || homedir();
+  const configured = opts.source === "claude-auto" ? env.CLAUDE_CONFIG_DIR : env.CODEX_HOME;
+  const source = opts.from ?? (configured?.trim() ? join(configured, opts.source === "claude-auto" ? "projects" : "memories") : join(home, opts.source === "claude-auto" ? ".claude/projects" : ".codex/memories"));
+  const root = sourceRoot(source), project = resolveAlias(opts.base, opts.project), aliases = aliasedKeys(opts.base, project);
+  const projectDirectory = opts.from === undefined && opts.source === "claude-auto" ? claudeProjectDirectory(opts.cwd ?? process.cwd()) : undefined;
+  const discovery = root ? opts.source === "claude-auto" ? discoverClaude(root, projectDirectory) : discoverCodex(root) : { files: [], rules: 0 };
+  const result: ExternalImportResult = { source: opts.source, project, files: 0, read: 0, added: 0, queueFull: false, limitReached: false, skipped: { rules: discovery.rules, policy: 0, invalid: 0, truncated: 0 }, pending: { count: 0, oldestExpiresInDays: null, dueWithin7Days: 0, unshown: 0 } };
+  const store = new CandidateStore({ memoryDir: opts.base, reconcile: { canonical: project, aliases } });
+  try {
+    for (const file of discovery.files) {
+      result.files++;
+      const input = readBounded(file.path, root!);
+      if (!input) { result.skipped.invalid++; continue; }
+      if (input.truncated) result.skipped.truncated++;
+      for (const sourceRecord of records(file, input.text)) {
+        result.read++;
+        if (!sourceRecord) { result.skipped.invalid++; continue; }
+        const raw = stripPrivateDeep(sourceRecord);
+        if (!raw.text.trim() || raw.title !== undefined && !raw.title.trim()) { result.skipped.invalid++; continue; }
+        const sourceFile = { ...file, relative: portable(file.relative) };
+        const whole: CandidateInput = { project, kind: "memory", text: raw.text, title: title(opts.source, sourceFile, raw, 0, 1), noteKind: "finding" };
+        if (looksSecret(`${whole.title ?? ""}\n${whole.text}`) || !await opts.policy(whole)) { result.skipped.policy++; continue; }
+        const parts = chunks(raw.text);
+        if (!parts.length) { result.skipped.invalid++; continue; }
+        for (let index = 0; index < parts.length; index++) {
+          if (result.added >= EXTERNAL_IMPORT_LIMITS.maxCandidatesPerRun) { result.limitReached = true; break; }
+          const record = stripPrivateDeep<CandidateInput>({ project, kind: "memory", text: parts[index]!, title: title(opts.source, sourceFile, raw, index, parts.length), noteKind: "finding" });
+          if (record.kind !== "memory" || !record.text.trim() || record.title !== undefined && !record.title.trim()) { result.skipped.invalid++; continue; }
+          if (looksSecret(`${record.title ?? ""}\n${record.text}`) || !await opts.policy(record)) { result.skipped.policy++; continue; }
+          const id = candidateInputId(record);
+          if (store.get(id, project)) continue;
+          try { store.put(record, "public"); }
+          catch (error) {
+            if (!(error instanceof CandidateQueueFull)) throw error;
+            result.queueFull = true;
+            break;
+          }
+          result.added++;
+        }
+        if (result.queueFull || result.limitReached) break;
+      }
+      if (result.queueFull || result.limitReached) break;
+    }
+  } finally { store.close(); }
+  result.pending = pendingSummary(opts.base, [project, ...aliases], Date.now());
+  return result;
+}

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/project-export.ts

@@ -11,14 +11,14 @@ 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
+ * #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. 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.
+ * 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";
@@ -27,8 +27,10 @@ export const EXPORT_SCHEMA = "agent-mem.project-export/v1";
  * 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; counts: ExportCounts; withheld: 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 }
@@ -47,8 +49,25 @@ function destination(base: string, to: string): string {
   return join(parentReal, name);
 }
 
-export async function exportProject(base: string, key: string, opts: { to: string; policy?: MemoryPolicy }): Promise<ExportResult> {
-  const project = requireShard(base, key);
+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);
@@ -59,10 +78,24 @@ export async function exportProject(base: string, key: string, opts: { to: strin
   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 {
-    out(`{"schema":${JSON.stringify(EXPORT_SCHEMA)},"project":${JSON.stringify(project)},"exportedAt":${JSON.stringify(new Date().toISOString())},"capture":[`);
-    let first = true;
+    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");
@@ -76,40 +109,42 @@ export async function exportProject(base: string, key: string, opts: { to: strin
             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++;
+            emit(row); counts.capture++;
           }
           if (rows.length < PAGE) break;
         }
       } finally { db.close(); }
     }
-    out(`],"curated":[`);
+    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)]);
-    first = true;
+    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;
-      if (!await allowed(view)) { withheld++; continue; }
-      out(`${first ? "" : ","}${JSON.stringify(view)}`); first = false; counts.curated++;
+      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++;
     }
-    out(`],"goals":[`);
-    first = true;
+    begin(`],"goals":[`, "goals", "Goals");
     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++;
+      emit(goal); counts.goals++;
     }
-    out(`],"workLists":[`);
-    first = true;
+    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)) { out(`${first ? "" : ","}${JSON.stringify(list)}`); first = false; counts.workLists++; }
+      for (const list of await work.read(undefined, true)) { emit(list); counts.workLists++; }
     }
-    out(`],"counts":${JSON.stringify(counts)},"withheld":${withheld}}\n`);
+    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
@@ -118,5 +153,5 @@ export async function exportProject(base: string, key: string, opts: { to: strin
     for (const store of stores) { try { store.close(); } catch { /* best effort */ } }
   }
   closeSync(fd);
-  return { file, project, counts, withheld };
+  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(); }
+}