geneseed 4.3.0 → 4.4.0

package/js/hosts/memory-files.mjs

@@ -5,11 +5,12 @@
  * SPLIT FROM `learn` FOR THE CLI's SAKE. `learn` spawns the model CLI, and the web console
  * (`js/web/api.mjs`, `js/web/actions.mjs`), `geneseed memory` (`js/maintain/memory.mjs`) and the
  * loop catalogue (`js/loop/catalog.mjs`) imported the hook module only for `frontmatter` and
- * `memoryDropIndex` — which dragged `node:child_process` into `bin/geneseed-cli.mjs`'s closure
+ * `memoryDropIndex` — which dragged Node's child-process module into `bin/geneseed-cli.mjs`'s
+ * closure (the generator now imports this file too, and its spawn ban greps for that literal)
  * and made the hook module a row in `tests/unit/hook_cli.test.mjs`'s spawn allow-list for a
  * spawn the CLI never makes. Everything here is fs-only; `hooks-learn.mjs` is the one spawner.
  */
-import { existsSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, renameSync, rmdirSync, unlinkSync } from 'node:fs';
 import path from 'node:path';
 import { readText, writeText } from '../lib/fs.mjs';
 import { normcase } from '../lib/paths.mjs';
@@ -24,6 +25,25 @@ const FILE_SEP_RE = /^---FILE---[^\S\n]*$/m;
 const MEMORY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/;
 const MAX_AGENT_BULLETS = 100;
 
+/**
+ * The seed MEMORY.md body. `js/build/stubs.mjs` seeds it from here, and an emptied store is
+ * written back to exactly these bytes, so the context hook's seed hash keeps skipping it.
+ */
+export const MEMORY_SEED = '# Memory Index\n';
+
+/**
+ * THE INDEX HAS TWO LEVELS. MEMORY.md is a map of topics, injected every session. Each
+ * `topics/<topic>.md` lists the facts under that topic, and the agent opens it on demand.
+ * A flat one-line-per-fact index overran the context hook's session budget at about 200
+ * facts and lost the newest ones, which is why it was split.
+ */
+const TOPICS = 'topics';
+const MAP_HINT = 'Each topic file lists its facts; open the one the task needs.';
+// A fact pointer: `- [title](slug.md)` in a legacy flat index, `- [title](../slug.md)` in a
+// topic file. The slug may not hold a `/`, so a map line (`topics/x.md`) is never a fact.
+const FACT_LINE_RE = /^- \[([^\]]*)\]\((?:\.\.\/)?([^/)]+)\.md\)(.*)$/;
+const MAP_LINE_RE = /^- \[[^\]]*\]\(topics\/[^)]+\.md\)/;
+
 /** `append_agent_lesson` — one dated bullet, capped at the newest MAX_AGENT_BULLETS. */
 export function appendAgentLesson(memDir, agent, lesson) {
   const d = path.join(memDir, 'agents');
@@ -77,45 +97,247 @@ function globMd(dir) {
 /** Stems that name the store's own files, never a fact — `MEMORY` is the index itself. */
 const RESERVED_STEMS = new Set(['memory', 'readme']);
 
-/** `_existing_slugs` — slugs already stored, so learn never re-emits a known fact. */
+/**
+ * `_existing_slugs` — slugs already stored. learn never CREATES one of these; it may only
+ * update or archive it by name (`writeMemories`).
+ */
 export function existingSlugs(memDir) {
   return new Set(globMd(memDir).map(stem).filter((s) => !RESERVED_STEMS.has(s.toLowerCase())));
 }
 
+/** Lines of a text file, or null when it cannot be read. */
+function readLines(p) {
+  try { return splitLines(readText(p)); } catch { return null; }
+}
+
+/**
+ * Write `text` only when the file does not already hold it. A second run of a rebuild then
+ * touches nothing, which keeps `golden --idempotent` green and leaves the user's mtimes alone.
+ */
+function writeIfChanged(p, text) {
+  const old = readLines(p);
+  if (old && `${old.join('\n')}\n` === text) return;
+  writeText(p, text);
+}
+
+/** A topic name as a file stem: `[a-z0-9-]`, any other run becomes `-`, empty becomes `misc`. */
+function topicSlug(raw) {
+  return raw.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '') || 'misc';
+}
+
 /**
- * `_write_memories` — split the model output into files, write each NEW one, and append a
- * pointer line to MEMORY.md. `existing` is MUTATED, so a reply carrying the same slug
- * twice writes it once.
+ * The topic a fact files under: `topic:`, else `type:`, else `misc`.
+ *
+ * NESTED `type:` IS ACCEPTED ON PURPOSE. The flat frontmatter parser trims keys, so Claude
+ * Code's own memory shape, with `type:` indented under `metadata:`, reads as `type`.
+ */
+const topicOf = (fm) => topicSlug(fmGet(fm, 'topic') || fmGet(fm, 'type'));
+
+/**
+ * Every fact on disk, in the index's sort order: slug -> { desc, topic }. Top level only, so
+ * `archive/` and `agents/` are never facts. Exported for learn's prompt, which lists them.
+ */
+export function readFacts(memDir) {
+  const facts = new Map();
+  for (const name of sortPaths(globMd(memDir))) {
+    const s = stem(name);
+    if (RESERVED_STEMS.has(s.toLowerCase())) continue;
+    try {
+      const [fm] = frontmatter(readText(path.join(memDir, name)));
+      facts.set(s, { desc: fmGet(fm, 'description').trim(), topic: topicOf(fm) });
+    } catch { continue; }
+  }
+  return facts;
+}
+
+/**
+ * Every fact pointer the index holds now, from a flat MEMORY.md and from the topic files:
+ * slug -> { title, rest }. `rest` is everything after the link, hook text included.
+ */
+function indexedFacts(memDir) {
+  const found = new Map();
+  const tdir = path.join(memDir, TOPICS);
+  const files = [path.join(memDir, 'MEMORY.md'), ...globMd(tdir).map((f) => path.join(tdir, f))];
+  for (const f of files) {
+    for (const line of readLines(f) ?? []) {
+      const m = FACT_LINE_RE.exec(line.trim());
+      if (m) found.set(m[2], { title: m[1], rest: m[3] });
+    }
+  }
+  return found;
+}
+
+/**
+ * Rewrite MEMORY.md as the map: one line per topic file with its fact count.
+ *
+ * LINES THE MAP DID NOT GENERATE ARE CARRIED, so a note the user wrote into the index
+ * survives. `dropFlat` also drops legacy flat fact pointers; a rebuild passes it because it
+ * has just moved them into topic files. With no topic and nothing carried, the file goes
+ * back to the seed.
+ */
+function writeMap(memDir, dropFlat) {
+  const idx = path.join(memDir, 'MEMORY.md');
+  const carried = (readLines(idx) ?? []).filter((l) => {
+    const t = l.trim();
+    return t && t !== MEMORY_SEED.trim() && t !== MAP_HINT && !MAP_LINE_RE.test(t)
+      && !(dropFlat && FACT_LINE_RE.test(t));
+  });
+  const tdir = path.join(memDir, TOPICS);
+  const topics = globMd(tdir).map(stem).sort().map((t) => {
+    const n = (readLines(path.join(tdir, `${t}.md`)) ?? [])
+      .filter((l) => FACT_LINE_RE.test(l.trim())).length;
+    return `- [${t}](${TOPICS}/${t}.md) — ${n} fact${n === 1 ? '' : 's'}`;
+  });
+  const body = [...(topics.length ? ['', MAP_HINT, '', ...topics] : []),
+    ...(carried.length ? ['', ...carried] : [])];
+  writeIfChanged(idx, body.length ? `${MEMORY_SEED}${body.join('\n')}\n` : MEMORY_SEED);
+}
+
+/** Remove the topics dir when nothing is left in it. */
+function pruneTopicsDir(memDir) {
+  try { rmdirSync(path.join(memDir, TOPICS)); } catch { /* not empty, or absent */ }
+}
+
+/**
+ * Rebuild both index levels from the fact files on disk.
+ *
+ * A fact the index already points at keeps its existing line, title and hook included,
+ * unless `refresh` is set. That makes a migration or a learn run lossless. `consolidate`
+ * passes `refresh`, because it exists to re-read the descriptions; learn passes the slugs
+ * it just UPDATED as `fresh`, because their old line describes a fact that is gone. Topic
+ * files no topic uses any more are deleted: they are generated, never facts.
+ */
+function rebuildIndex(memDir, refresh, fresh = new Set()) {
+  const facts = readFacts(memDir);
+  const old = indexedFacts(memDir);
+  const byTopic = new Map();
+  for (const [slug, { desc, topic }] of facts) {
+    const o = refresh || fresh.has(slug) ? null : old.get(slug);
+    const line = o ? `- [${o.title}](../${slug}.md)${o.rest}`
+      : `- [${slug}](../${slug}.md)${desc ? ` — ${desc}` : ''}`;
+    if (!byTopic.has(topic)) byTopic.set(topic, []);
+    byTopic.get(topic).push(line);
+  }
+  const tdir = path.join(memDir, TOPICS);
+  for (const f of globMd(tdir)) {
+    if (!byTopic.has(stem(f))) unlinkSync(path.join(tdir, f));
+  }
+  if (byTopic.size) mkdirSync(tdir, { recursive: true });
+  for (const [topic, lines] of byTopic) {
+    writeIfChanged(path.join(tdir, `${topic}.md`), `# ${topic}\n\n${lines.join('\n')}\n`);
+  }
+  if (!byTopic.size) pruneTopicsDir(memDir);
+  writeMap(memDir, true);
+  return { facts, old };
+}
+
+/**
+ * Move a flat MEMORY.md to the two-level index, once, at emit time.
+ *
+ * Acts only when MEMORY.md still holds a flat fact pointer and at least one fact exists, so
+ * a seed-only store and an already-migrated store are left alone. It rewrites MEMORY.md and
+ * `topics/*.md` only, never a fact file, and it keeps each pointer's own title and hook.
+ */
+export function migrateMemoryIndex(memDir) {
+  const lines = readLines(path.join(memDir, 'MEMORY.md'));
+  if (!lines?.some((l) => FACT_LINE_RE.test(l.trim())) || !existingSlugs(memDir).size) return false;
+  rebuildIndex(memDir, false);
+  return true;
+}
+
+/** The chunk without its frontmatter `action:` line, which is an instruction, not the fact. */
+function stripAction(chunk) {
+  const lines = chunk.split('\n');
+  const close = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+  if (lines[0].trim() !== '---' || close < 0) return chunk;
+  return lines.filter((l, i) => i === 0 || i >= close || !/^\s*action\s*:/.test(l)).join('\n');
+}
+
+/**
+ * Whether the stored fact carries a `force:`. Such a fact is never updated or archived by
+ * learn: the memory README's Bridge rule has it revised inline with its supersession
+ * recorded, a `constraint` only by the user, and the model sees no fact's body or `force:`.
+ */
+function hasForce(memDir, slug) {
+  try { return !!fmGet(frontmatter(readText(path.join(memDir, `${slug}.md`)))[0], 'force'); } catch {
+    return false;
+  }
+}
+
+/**
+ * Move `<slug>.md` into `archive/`, never over a file already there: a taken name gets
+ * `-2`, `-3`, ... A counter rather than a date, so a second archive the same day cannot
+ * collide. RENAME, never unlink: an archived fact leaves the index but stays on disk.
+ * Returns the path it landed at. The index is the caller's: `geneseed memory rm` drops the
+ * line (`memoryDropIndex`), learn rebuilds both levels.
+ */
+export function archiveFact(memDir, slug) {
+  const adir = path.join(memDir, 'archive');
+  mkdirSync(adir, { recursive: true });
+  let dest = path.join(adir, `${slug}.md`);
+  for (let n = 2; existsSync(dest); n += 1) dest = path.join(adir, `${slug}-${n}.md`);
+  renameSync(path.join(memDir, `${slug}.md`), dest);
+  return dest;
+}
+
+/**
+ * `_write_memories` — split the model output into files and apply each, then rebuild the
+ * two-level index from disk with the same builder `consolidate` uses. A rebuild rather than
+ * an append, so a legacy flat index is migrated on the way and a topic count can never
+ * drift from its file. `existing` is MUTATED to match the store afterwards.
+ *
+ * A chunk's frontmatter `action:` says what to do with its `name:`:
+ *   - none (or `create`): write a NEW fact; a slug already stored is skipped;
+ *   - `update`: archive the stored fact (`archiveFact`), then write this text, which the
+ *     model has merged, in its place. The model sees only the description, so the old
+ *     body, links and extra frontmatter survive in `archive/` and every update is reversible;
+ *   - `archive`: move the stored fact to `archive/` (`archiveFact`).
+ * An update or archive naming no stored fact, or one carrying a `force:` (`hasForce`), is
+ * skipped, as is any other action, and each slug is acted on once per reply.
  *
  * A reserved stem is refused (`name: MEMORY` would overwrite the index), and names compare
  * LOWERCASE: on Windows and macOS `User-Prefs.md` and `user-prefs.md` are one file, so a
- * case variant of a stored slug would overwrite it.
+ * case variant of a stored slug would overwrite it. An update or archive therefore acts on
+ * the STORED spelling, whatever case the model used.
+ *
+ * Returns `{ created, updated, archived }`, each a list of slugs.
  */
 export function writeMemories(modelOutput, memDir, existing) {
-  const taken = new Set([...existing].map((s) => s.toLowerCase()));
-  const written = [];
-  const indexLines = [];
+  const stored = new Map([...existing].map((s) => [s.toLowerCase(), s]));
+  const done = new Set();
+  const res = { created: [], updated: [], archived: [] };
   for (let chunk of modelOutput.split(FILE_SEP_RE)) {
     chunk = chunk.trim();
     if (!chunk || chunk.toUpperCase() === 'NOTHING') continue;
     const [fm] = frontmatter(chunk);
     const name = fmGet(fm, 'name').trim();
     const key = name.toLowerCase();
-    if (!MEMORY_SLUG_RE.test(name) || RESERVED_STEMS.has(key) || taken.has(key)) continue;
-    writeText(path.join(memDir, `${name}.md`), `${chunk.replace(/\n+$/, '')}\n`);
-    existing.add(name);
-    taken.add(key);
-    written.push(name);
-    const desc = fmGet(fm, 'description').trim();
-    indexLines.push(`- [${name}](${name}.md)${desc ? ` \u2014 ${desc}` : ''}`);
+    const action = fmGet(fm, 'action').trim().toLowerCase() || 'create';
+    if (!MEMORY_SLUG_RE.test(name) || RESERVED_STEMS.has(key) || done.has(key)) continue;
+    const slug = stored.get(key);
+    if (slug && action !== 'create' && hasForce(memDir, slug)) continue;
+    const body = `${stripAction(chunk).replace(/\n+$/, '')}\n`;
+    if (action === 'create' && !slug) {
+      writeText(path.join(memDir, `${name}.md`), body);
+      existing.add(name);
+      stored.set(key, name);
+      res.created.push(name);
+    } else if (action === 'update' && slug) {
+      archiveFact(memDir, slug);   // the old version first: the model never saw its body
+      writeText(path.join(memDir, `${slug}.md`), body);
+      res.updated.push(slug);
+    } else if (action === 'archive' && slug) {
+      archiveFact(memDir, slug);
+      existing.delete(slug);
+      stored.delete(key);
+      res.archived.push(slug);
+    } else continue;
+    done.add(key);
   }
-  if (indexLines.length) {
-    const index = path.join(memDir, 'MEMORY.md');
-    const current = existsSync(index) ? `${readText(index).replace(/\n+$/, '')}\n`
-      : '# Memory Index\n';
-    writeText(index, `${current}${indexLines.join('\n')}\n`);
+  if (res.created.length || res.updated.length || res.archived.length) {
+    rebuildIndex(memDir, false, new Set(res.updated));
   }
-  return written;
+  return res;
 }
 
 /**
@@ -134,57 +356,58 @@ export function writeMemories(modelOutput, memDir, existing) {
  * so a hand-written index in a different shape still loses its entry. And the file is only
  * REWRITTEN when something actually changed, which keeps a delete of an unindexed fact from
  * touching the user's mtime.
+ *
+ * BOTH LEVELS: the `(<name>.md)` line of a legacy flat MEMORY.md, and the `(../<name>.md)`
+ * line of whichever topic file holds it. A topic file left with no fact is deleted, and the
+ * map's counts are refreshed only when a topic file changed. Matching the two exact forms
+ * keeps `b` from taking `ab.md` with it.
  */
 export function memoryDropIndex(memDir, name) {
-  const idx = path.join(memDir, 'MEMORY.md');
-  let lines;
-  try {
-    lines = splitLines(readText(idx));
-  } catch {
-    return;                       // the reference's `except OSError: return`
+  dropLines(path.join(memDir, 'MEMORY.md'), `(${name}.md)`);
+  const tdir = path.join(memDir, TOPICS);
+  let touched = false;
+  for (const f of globMd(tdir)) {
+    const p = path.join(tdir, f);
+    const left = dropLines(p, `(../${name}.md)`);
+    if (!left) continue;
+    touched = true;
+    if (!left.some((l) => FACT_LINE_RE.test(l.trim()))) {
+      try { unlinkSync(p); } catch { /* as below */ }
+    }
   }
-  const keep = lines.filter((ln) => !ln.includes(`(${name}.md)`));
-  if (keep.length === lines.length) return;
+  if (!touched) return;
+  pruneTopicsDir(memDir);
+  try { writeMap(memDir, false); } catch { /* the reference swallows OSError here too */ }
+}
+
+/** Drop every line holding `needle`; the kept lines when something went, else null. */
+function dropLines(p, needle) {
+  const lines = readLines(p);
+  if (!lines) return null;        // the reference's `except OSError: return`
+  const keep = lines.filter((ln) => !ln.includes(needle));
+  if (keep.length === lines.length) return null;
   try {
-    writeText(idx, `${keep.join('\n')}\n`);
+    writeText(p, `${keep.join('\n')}\n`);
   } catch { /* the reference swallows OSError here too */ }
+  return keep;
 }
 
 /**
- * `consolidate_memory` — rebuild MEMORY.md from the fact files actually on disk: index
- * orphans, prune dead lines, report duplicate descriptions (never auto-merge — nuance is
- * the user's to keep).
+ * `consolidate_memory` — rebuild both index levels from the fact files actually on disk:
+ * index orphans, prune dead lines, refresh each line from its fact's description, report
+ * duplicate descriptions. It REPORTS them and never merges: merging is a judgement, made by
+ * the model at learn time (`writeMemories`'s `update`) or by the user, never by this rebuild. `added` and
+ * `pruned` compare against the pointers of BOTH levels, so a migration counts as neither.
  */
 export function consolidateMemory(memDir) {
-  const skip = RESERVED_STEMS;
-  const facts = new Map();
-  for (const name of sortPaths(globMd(memDir))) {
-    const s = stem(name);
-    if (skip.has(s.toLowerCase())) continue;
-    try {
-      facts.set(s, fmGet(frontmatter(readText(path.join(memDir, name)))[0], 'description').trim());
-    } catch { continue; }
-  }
-  const index = path.join(memDir, 'MEMORY.md');
-  const oldSlugs = new Set();
-  if (existsSync(index)) {
-    for (const line of splitLines(readText(index))) {
-      const m = /^- \[[^\]]*\]\(([^)]+)\.md\)/.exec(line.trim());
-      if (m) oldSlugs.add(m[1]);
-    }
-  }
-  const lines = ['# Memory Index', ''];
-  for (const [slug, desc] of facts) {
-    lines.push(`- [${slug}](${slug}.md)${desc ? ` \u2014 ${desc}` : ''}`);
-  }
-  writeText(index, `${lines.join('\n')}\n`);
+  const { facts, old } = rebuildIndex(memDir, true);
   const seen = new Map();
   const dups = [];
-  for (const [slug, desc] of facts) {
+  for (const [slug, { desc }] of facts) {
     if (desc && seen.has(desc)) dups.push([seen.get(desc), slug]);
     if (!seen.has(desc)) seen.set(desc, slug);
   }
-  const added = [...facts.keys()].filter((s) => !oldSlugs.has(s)).sort();
-  const pruned = [...oldSlugs].filter((s) => !facts.has(s)).sort();
+  const added = [...facts.keys()].filter((s) => !old.has(s)).sort();
+  const pruned = [...old.keys()].filter((s) => !facts.has(s)).sort();
   return { added, pruned, duplicates: dups };
 }

package/js/inspect/checks-build.mjs

@@ -196,7 +196,8 @@ export function colorThemeProblems() {
  * rebuild able to clear it.
  *
  * Host-state files (context.json, MEMORY.md, the markers) are created once and never
- * rendered, so they are not in the render set and are correctly ignored. Notebook files
+ * rendered (MEMORY.md's one later write is `migrateMemoryIndex` moving a flat index to
+ * topics), so they are not in the render set and are correctly ignored. Notebook files
  * except its `.gitignore` are seed-once and agent-owned after the first build, so they are
  * compared only for EXISTENCE.
  */

package/js/inspect/cost.mjs

@@ -28,7 +28,7 @@ import { isFile, readText } from '../lib/fs.mjs';
  * console draws it on the cost chart, so it lives here, once, where both read it. Raise it by
  * exactly the measured overrun and say why in that test's docblock, which keeps its history.
  */
-export const CARRIER_CEILING = { full: 62_076, lean: 38_890 };
+export const CARRIER_CEILING = { full: 62_107, lean: 38_976 };
 
 const decode = (p) => readText(p).split('\r\n').join('\n');
 

package/js/inspect/excludes.mjs

@@ -32,6 +32,28 @@ import { normcase, toPlatformPath } from '../lib/paths.mjs';
 const localSettings = (repo, host) =>
   path.join(repo, HOSTS.find((h) => h.host === host).projectMarker, 'settings.local.json');
 
+/** The `claudeMdExcludes` entry naming a Claude-family global install's CLAUDE.md, as wired. */
+const claudeMdEntry = (cfg) => resolvePath(path.join(cfg, 'CLAUDE.md')).split(path.sep).join('/');
+
+/**
+ * The worktree caveat, or null when it does not apply: a Claude-family install and an
+ * excluded folder that is a git repository (a `.git` there — no repo, no worktrees).
+ *
+ * WHY A WARNING AND NOT A WRITE: `settings.local.json` is gitignored, so a `git worktree add`
+ * of the excluded repo never carries it and the global CLAUDE.md loads there again (the hooks
+ * do stand down — `sovereignBypass` follows the worktree to its main repo). The one durable
+ * fix is the repo's TRACKED `settings.json`, and the user decided (2026-10) Geneseed never
+ * writes a tracked file in a repo it was told to leave alone — so it prints the snippet.
+ */
+function worktreeNote(host, cfg, repo) {
+  if (host !== 'claude' && host !== 'openclaude') return null;
+  if (!existsSync(path.join(repo, '.git'))) return null;
+  const marker = HOSTS.find((h) => h.host === host).projectMarker;
+  return `${host}: git worktrees of this repo do not get the gitignored `
+    + `${marker}/settings.local.json and still load the global CLAUDE.md — to stop that, commit `
+    + `to the repo's ${marker}/settings.json: "claudeMdExcludes": ["${claudeMdEntry(cfg)}"]`;
+}
+
 /** `_global_installs` — every host whose GLOBAL config dir carries a Geneseed manifest. */
 function globalInstalls() {
   const out = [];
@@ -112,8 +134,7 @@ export function excludeAdd(target) {
     const priorWired = (isDict(prior) ? get(prior, 'wired') : null) || {};
     const wired = {};
     if ((host === 'claude' || host === 'openclaude') && isDir(repo)) {
-      const entry = resolvePath(path.join(cfg, 'CLAUDE.md')).split(path.sep).join('/');
-      const added = wireClaudeExcludes(localSettings(repo, host), [entry]);
+      const added = wireClaudeExcludes(localSettings(repo, host), [claudeMdEntry(cfg)]);
       if (added.length) {
         wired.claude_md_excludes = added;
       } else if (get(priorWired, 'claude_md_excludes')) {
@@ -126,6 +147,8 @@ export function excludeAdd(target) {
       // own project-bypasses-global wiring, or a bailed write) — do NOT fabricate ownership,
       // or a later excludeRemove would strip wiring we never created.
       if (!added.length) messages.push(`${host}: claudeMdExcludes already present (kept)`);
+      const note = worktreeNote(host, cfg, repo);
+      if (note) messages.push(note);
     }
     if (host === 'bob' && isDir(repo)) {
       const stub = path.join(repo, '.bob', 'rules', 'geneseed.md');
@@ -249,6 +272,14 @@ export function cmdExclude(args) {
       const flag = missing.length
         ? `  (MISSING from: ${missing.join(', ')} — re-run \`geneseed exclude add\`)` : '';
       printOut(`  ${rec.path}  [${rec.hosts.slice().sort().join(', ')}]${flag}\n`);
+      for (const { host, cfg } of snap.installs) {
+        if (!rec.hosts.includes(host)) continue;
+        let note = null;
+        try {
+          note = worktreeNote(host, cfg, toPlatformPath(rec.path));
+        } catch { /* a broken resolver: the listing itself must still print */ }
+        if (note) printOut(`    note: ${note}\n`);
+      }
     }
     return 0;
   }

package/js/maintain/memory.mjs

@@ -25,11 +25,16 @@
  *
  * `memoryDropIndex` is the hook module's, not a copy: writing the fact and unwriting its
  * index line are two halves of one format, and the half that writes lives there.
+ *
+ * `rm` ARCHIVES BY DEFAULT. A removed fact moves into `archive/` (`archiveFact`, the helper
+ * learn uses), so a slip of the keyboard or a click in the console is reversible; only
+ * `--purge` unlinks. `--archived` points `list` and `rm` at `archive/` itself, and a file
+ * there can only be purged — it has nowhere further to go.
  */
 import { readdirSync, unlinkSync } from 'node:fs';
 import path from 'node:path';
 
-import { memoryDropIndex } from '../hosts/memory-files.mjs';
+import { archiveFact, memoryDropIndex } from '../hosts/memory-files.mjs';
 import { resolveMemoryDir } from '../hosts/hosts.mjs';
 import { printOut, printErr, isFile } from '../lib/fs.mjs';
 
@@ -58,13 +63,28 @@ export function memoryFacts(dir) {
     .map((n) => n.slice(0, -3)).filter(isFactName).sort();
 }
 
-/** `api_memory_delete`, minus the HTTP: the file, then its line in the index. */
-export function memoryDelete(dir, name) {
-  if (!isFactName(name)) return false;
+/**
+ * Take a fact out of the store and its line out of the index. Archived into `archive/` unless
+ * `purge`, which unlinks it. Returns where it went (the archive path, or '' when purged), or
+ * null when `name` is not a fact here.
+ */
+export function memoryDelete(dir, name, purge = false) {
+  if (!isFactName(name)) return null;
   const p = path.join(dir, `${name}.md`);
+  if (!isFile(p)) return null;
+  let dest = '';
+  if (purge) unlinkSync(p);
+  else dest = archiveFact(dir, name);
+  memoryDropIndex(dir, name);
+  return dest;
+}
+
+/** Unlink `archive/<name>.md`. True when a file went. The archive has no index to update. */
+export function memoryPurgeArchived(dir, name) {
+  if (!isFactName(name)) return false;
+  const p = path.join(dir, 'archive', `${name}.md`);
   if (!isFile(p)) return false;
   unlinkSync(p);
-  memoryDropIndex(dir, name);
   return true;
 }
 
@@ -78,13 +98,14 @@ export function cmdMemory(args) {
       + 'or run this from a directory with a memory/ store.\n');
     return 1;
   }
+  const where = args.archived ? path.join(dir, 'archive') : dir;
   if (args.action === 'list') {
-    const facts = memoryFacts(dir);
+    const facts = memoryFacts(where);
     if (!facts.length) {
-      printOut(`[memory] ${dir}: no facts.\n`);
+      printOut(`[memory] ${where}: no facts.\n`);
       return 0;
     }
-    printOut(`[memory] ${dir}\n`);
+    printOut(`[memory] ${where}\n`);
     for (const name of facts) printOut(`  ${name}\n`);
     return 0;
   }
@@ -92,14 +113,20 @@ export function cmdMemory(args) {
     printErr('[memory] rm needs the name of a fact.\n');
     return 2;
   }
-  if (!memoryDelete(dir, args.name)) {
+  if (args.archived && !args.purge) {
+    printErr('[memory] an archived fact can only be purged: add --purge to delete it.\n');
+    return 2;
+  }
+  const done = args.archived ? (memoryPurgeArchived(dir, args.name) ? '' : null)
+    : memoryDelete(dir, args.name, Boolean(args.purge));
+  if (done === null) {
     // ONE MESSAGE FOR BOTH REFUSALS, which is the endpoint's shape too — it raises the same
     // `NotFound(name)` for a reserved name, a name with a separator and a fact that is not
     // there. Telling a caller that `MEMORY` exists but is protected is a distinction this
     // verb has no reason to draw.
-    printErr(`[memory] no such fact '${args.name}' in ${dir}.\n`);
+    printErr(`[memory] no such fact '${args.name}' in ${where}.\n`);
     return 1;
   }
-  printOut(`[memory] deleted ${args.name}.\n`);
+  printOut(done ? `[memory] archived ${args.name} -> ${done}\n` : `[memory] deleted ${args.name}.\n`);
   return 0;
 }

package/js/web/actions.mjs

@@ -276,7 +276,8 @@ export function apiPickFolder(done) {
 // ---- memory ------------------------------------------------------------------------------
 
 /**
- * One fact file, and its line in the MEMORY.md index.
+ * One fact file, and its line in the MEMORY.md index. The file is ARCHIVED into
+ * `memory/archive/`, never unlinked: the console has no purge, `geneseed memory rm --purge` does.
  *
  * `name` is a BARE SLUG: a path separator, or one of the two reserved names, is refused, so
  * this can only ever remove a fact inside the resolved memory dir. MEMORY.md is the index the
@@ -290,9 +291,9 @@ export function apiMemoryDelete(state, name) {
   // `memoryDelete` is the `geneseed memory rm` engine, and its reserved-name check is
   // CASE-FOLDED: this endpoint's own compared `MEMORY` exactly, so on Windows and macOS `memory`
   // resolved to MEMORY.md, passed, and deleted the index the agent reads at session start.
-  if (!memoryDelete(d, name)) throw new NotFound(name);
+  if (memoryDelete(d, name) === null) throw new NotFound(name);
   state.refresh();
-  return { deleted: name };
+  return { archived: name };
 }
 
 // ---- sovereign-repo exclusions -------------------------------------------------------------

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "Every field here is argued and gated in tests/unit/package_manifest.test.mjs. `files`, `bin` and `engines` each have a test that fails when reality drifts from this file; `version` mirrors harness.config.json and is gated too. Read that docblock before editing this one.",
   "name": "geneseed",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "A portable, theme-able harness you implant once and use everywhere to grow a disciplined AI coding agent.",
   "keywords": [
     "ai",

package/registry.json

@@ -57,6 +57,13 @@
       "added": "2026-06-08",
       "last_verified": ""
     },
+    "agents/memory-curator": {
+      "status": "experimental",
+      "version": "1.0.0",
+      "owner": "Guillaume Lemer",
+      "added": "2026-10-16",
+      "last_verified": ""
+    },
     "agents/operator": {
       "status": "approved",
       "version": "1.0.0",

package/src/AGENT.md.tmpl

@@ -166,6 +166,7 @@ Active packs: {{DOCTRINES_LIST}}{{EXCLUDED_RULES_LINE}}
 | [performance]({{DIR_AGENTS}}/performance.md) | something is reported slow or heavy, or a diff touches a hot path — measured, never guessed |
 | [explorer]({{DIR_AGENTS}}/explorer.md) | you must sweep many files for an answer but only want the conclusion |
 | [researcher]({{DIR_AGENTS}}/researcher.md) | a question needs the open web — fetched, cross-checked, and returned as sourced findings, not pages |
+| [memory-curator]({{DIR_AGENTS}}/memory-curator.md) | the {{MEMORY}} store needs bulk curation |
 | [advocate]({{DIR_AGENTS}}/advocate.md) | a council debate needs the strongest case **for** the motion argued in isolation |
 | [skeptic]({{DIR_AGENTS}}/skeptic.md) | a council debate needs a devil's advocate to attack the motion's failure modes |
 | [pragmatist]({{DIR_AGENTS}}/pragmatist.md) | a council debate needs the cost, effort, and complexity weighed against the payoff |