geneseed 4.3.1 → 4.4.1

package/js/cli-table.json

@@ -619,7 +619,7 @@
           ],
           "dest": "consolidate",
           "metavar": null,
-          "help": "rebuild MEMORY.md from the fact files on disk: re-index orphans, prune dead lines, report duplicate descriptions",
+          "help": "rebuild the memory index (MEMORY.md and topics/) from the fact files on disk: re-index orphans, prune dead lines, report duplicate descriptions",
           "choices": null,
           "default": false,
           "required": false,
@@ -909,7 +909,7 @@
     },
     {
       "name": "memory",
-      "help": "manage the memory store: list the facts the agent reads, or remove one by name",
+      "help": "manage the memory store: list the facts the agent reads, or remove one by name (archived into memory/archive/; --purge deletes)",
       "description": "",
       "positionals": [
         {
@@ -957,6 +957,36 @@
           "is_flag": false,
           "type": null,
           "hidden": false
+        },
+        {
+          "names": [
+            "--archived"
+          ],
+          "dest": "archived",
+          "metavar": null,
+          "help": "act on memory/archive/ instead: list the archived facts, or (with --purge) delete one",
+          "choices": null,
+          "default": false,
+          "required": false,
+          "nargs": "0",
+          "is_flag": true,
+          "type": null,
+          "hidden": false
+        },
+        {
+          "names": [
+            "--purge"
+          ],
+          "dest": "purge",
+          "metavar": null,
+          "help": "rm deletes the fact for good instead of archiving it (cannot be undone)",
+          "choices": null,
+          "default": false,
+          "required": false,
+          "nargs": "0",
+          "is_flag": true,
+          "type": null,
+          "hidden": false
         }
       ],
       "mutex": []

package/js/hosts/hooks-context.mjs

@@ -146,6 +146,28 @@ const SEED_SHA256 = new Set([
 ]);
 export { SESSION_FILES, SEED_SHA256 };
 
+// A topic line of the memory map (`js/hosts/memory-files.mjs` writes it) and its fact count.
+const MAP_COUNT_RE = /^- \[([^\]]*)\]\(topics\/[^)]+\.md\) — (\d+) facts?$/;
+// Past this many facts a topic file stops being a quick read, and the curator splits it.
+const CURATE_TOPIC_MAX = 40;
+const CURATE_NUDGE = '[memory] A topic holds over 40 facts, or facts sit in misc: offer the user '
+  + 'to dispatch the memory-curator agent to merge, re-topic and archive this store.';
+export { CURATE_TOPIC_MAX, CURATE_NUDGE };
+
+/**
+ * The one-line curation nudge for a memory map, or ''. Read off the map's own counts, so it
+ * costs no extra file read on the hook path. Both triggers are ones a curation pass clears; a
+ * store that is merely LARGE is not one, since a curated large store would be nagged forever.
+ * The OpenCode context plugin carries the same rule (parity gated in tests/unit/claude.test.mjs).
+ */
+export function memoryNudge(map) {
+  for (const line of map.split('\n')) {
+    const m = MAP_COUNT_RE.exec(line.trim());
+    if (m && (m[1] === 'misc' || Number(m[2]) > CURATE_TOPIC_MAX)) return CURATE_NUDGE;
+  }
+  return '';
+}
+
 /**
  * The session files present under `hookRoot` and changed from their seed, as `{ rel, abs, text }`
  * (text CRLF-folded, trailing newlines trimmed). `$GENESEED_WIKI` overrides the wiki declaration,
@@ -164,7 +186,9 @@ export function sessionFiles(hookRoot) {
     let text;
     try { text = readFileSync(abs, 'utf8').replace(/\r\n/g, '\n'); } catch { continue; }
     if (SEED_SHA256.has(createHash('sha256').update(text).digest('hex'))) continue;
-    found.push({ rel, abs, text: text.replace(/\n+$/, '') });
+    text = text.replace(/\n+$/, '');
+    const nudge = rel.endsWith('MEMORY.md') ? memoryNudge(text) : '';
+    found.push({ rel, abs, text: nudge ? `${text}\n${nudge}` : text });
   }
   return found;
 }

package/js/hosts/hooks-learn.mjs

@@ -1,7 +1,7 @@
 /**
- * `learn` — the Stop/SubagentStop/PreCompact verb: distil notes or a transcript into deduped
- * memory entries through the model CLI `$GENESEED_LLM` names. THE ONE SPAWN in the hook entry's
- * closure; the store's file format it writes through lives in `./memory-files.mjs`, which does
+ * `learn` — the Stop/SubagentStop/PreCompact verb: distil notes or a transcript into memory
+ * entries (a new fact, or an update or archive of a stored one) through the model CLI
+ * `$GENESEED_LLM` names. THE ONE SPAWN in the hook entry's closure; the store's file format it writes through lives in `./memory-files.mjs`, which does
  * not spawn and is what the CLI imports. See `js/hosts/hooks.mjs`'s header for the contract.
  */
 import path from 'node:path';
@@ -14,7 +14,7 @@ import {
 } from './hosts.mjs';
 import { readStdin, splitLines, splitWords } from './hooks-prims.mjs';
 import {
-  existingSlugs, writeMemories, consolidateMemory, appendAgentLesson,
+  existingSlugs, readFacts, writeMemories, consolidateMemory, appendAgentLesson,
 } from './memory-files.mjs';
 
 const ROOT = path.resolve(import.meta.dirname, '../..');
@@ -163,13 +163,33 @@ export function readNotes(raw, meta = hookMeta(raw)) {
   return flat;
 }
 
-function buildLearnPrompt(notes, existing) {
+/**
+ * The prompt: the plugin's head, the stored facts as `slug \u2014 description` (so the model can
+ * merge into one or archive it), the topics in use, then the notes.
+ *
+ * THE FACT LINES ARE CAPPED at MAX_STORED_CHARS. A store of hundreds of facts would otherwise
+ * outgrow the notes, and the prompt rides on the model CLI's command line, which Windows caps
+ * at 32 767 characters (16 000 of notes + the head + this stays under it). A fact past the
+ * cap is only unlisted: `writeMemories` still refuses to create its slug. The plugin's
+ * `buildPrompt` is the twin.
+ */
+const MAX_STORED_CHARS = 8000;
+export function buildLearnPrompt(notes, facts) {
   const parts = [learnPromptHead(), ''];
-  if (existing.size) {
-    parts.push('ALREADY STORED \u2014 do NOT emit a memory matching any of these '
-      + 'slugs (skip updates too; only genuinely new facts):');
-    parts.push(...[...existing].sort().map((slug) => `- ${slug}`));
-    parts.push('');
+  if (facts.size) {
+    parts.push('ALREADY STORED \u2014 \'slug \u2014 description\', to update or archive, never to create:');
+    let used = 0;
+    let shown = 0;
+    for (const [slug, { desc }] of facts) {
+      const line = desc ? `- ${slug} \u2014 ${desc}` : `- ${slug}`;
+      if (used + line.length > MAX_STORED_CHARS) break;
+      parts.push(line);
+      used += line.length + 1;
+      shown += 1;
+    }
+    if (shown < facts.size) parts.push(`(${facts.size - shown} more stored facts not shown)`);
+    parts.push('', 'TOPICS IN USE:',
+      [...new Set([...facts.values()].map((f) => f.topic))].sort().join(', '), '');
   }
   parts.push('NOTES:', notes);
   return parts.join('\n');
@@ -329,7 +349,7 @@ export function cmdLearn(args) {
 
   const memDir = resolveMemoryDir(args.memory);
   const existing = memDir ? existingSlugs(memDir) : new Set();
-  const prompt = buildLearnPrompt(notes, existing);
+  const prompt = buildLearnPrompt(notes, memDir ? readFacts(memDir) : new Map());
 
   const llm = process.env.GENESEED_LLM;
   if (!llm) {
@@ -341,11 +361,17 @@ export function cmdLearn(args) {
   const proc = runLlm(llm, prompt);
   const output = proc.stdout;
   if (memDir && output.trim() && output.trim().toUpperCase() !== 'NOTHING') {
-    const written = writeMemories(output, memDir, existing);
-    if (written.length) {
-      err(`[learn] wrote ${written.length} memory file(s) to `
-        + `${memDir}: ${written.join(', ')}\n`);
-    } else {
+    const { created, updated, archived } = writeMemories(output, memDir, existing);
+    if (created.length) {
+      err(`[learn] wrote ${created.length} memory file(s) to `
+        + `${memDir}: ${created.join(', ')}\n`);
+    }
+    if (updated.length) err(`[learn] updated ${updated.length} memory file(s): ${updated.join(', ')}\n`);
+    if (archived.length) {
+      err(`[learn] archived ${archived.length} memory file(s) to `
+        + `${path.join(memDir, 'archive')}: ${archived.join(', ')}\n`);
+    }
+    if (!created.length && !updated.length && !archived.length) {
       err('[learn] nothing new to store (all duplicates).\n');
     }
   } else {

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_219, lean: 39_088 };
 
 const decode = (p) => readText(p).split('\r\n').join('\n');
 

package/js/inspect/inventory.mjs

@@ -94,7 +94,7 @@ export const SKILL_CLASS = {
   loop: 'design', 'brick-forge': 'design',
   'codebase-design': 'design', wayfinder: 'design',
   develop: 'build', refactor: 'build', debug: 'build', dependencies: 'build',
-  'frontend-design': 'build', prototype: 'build',
+  'frontend-design': 'build', prototype: 'build', deck: 'build',
   'forge-mcp': 'build', bruno: 'build', worktree: 'build',
   'geneseed-code-review': 'review', 'fresh-eyes': 'review', 'security-audit': 'review',
   'roast-me': 'review', 'review-response': 'review', ponytail: 'review',