geneseed 4.3.1 → 4.4.0

package/CHANGELOG.md

@@ -8,6 +8,24 @@ label. For the capability ↔ spec map, see [SHIPPED.md](SHIPPED.md).
 
 ## [Unreleased]
 
+## [4.4.0] — 2026-10-16
+
+Minor: the memory store scales — a two-level index, merge and archive at creation, and a memory-curator agent.
+
+### Upgrade notes
+- Run `geneseed rebuild-all` once after updating. It migrates every existing `memory/MEMORY.md` to the two-level index: only the index files are rewritten, never a fact file.
+- A large or untidy store (a topic over 40 facts, or a `misc` topic) now gets a one-line session nudge to dispatch the memory-curator agent; it merges and archives topic by topic and deletes nothing without your approval.
+- `geneseed memory rm` now archives into `memory/archive/`; pass `--purge` for the old deletion.
+
+### Added
+- **memory-curator agent.** Merges duplicate facts (archiving the merged-away versions), assigns missing topics, archives stale facts, and proposes deletion of archived ones; never touches a `force:` fact without a ruling. (#284)
+- **`geneseed memory list --archived`, `rm --purge`, `rm --archived --purge`.** (#284)
+
+### Changed
+- **Two-level memory index.** `MEMORY.md` is now a small map of topics; each `memory/topics/<topic>.md` lists its facts. A fact's optional `topic:` picks its group, else its `type:`, else `misc`. A flat index of 200+ facts overran the context hook's budget and the newest facts were cut. (#282)
+- **learn merges and archives.** The distiller sees the stored facts with their descriptions and the topics in use; it can update an existing fact (the old version is archived first) or archive a stale one, and tags new facts with a topic. Nothing is ever deleted; facts carrying `force:` are left alone. (#283)
+- **Memory deletion archives by default**, in the CLI and the web console. (#284)
+
 ## [4.3.1] — 2026-10-15
 
 Patch: a folder excluded from the global harness now stays excluded in its git worktrees.

package/README.md

@@ -12,7 +12,7 @@
 [![zero dependencies](https://img.shields.io/badge/deps-zero-success)](package.json)
 [![Themes](https://img.shields.io/badge/themes-14-9cf)](themes/)
 [![Skills](https://img.shields.io/badge/skills-46-blueviolet)](src/skills/)
-[![Agents](https://img.shields.io/badge/agents-19-orange)](src/agents/)
+[![Agents](https://img.shields.io/badge/agents-20-orange)](src/agents/)
 [![Laws and doctrines](https://img.shields.io/badge/laws-9%20%2B%2029%20doctrines-critical)](src/doctrines/)
 [![Plugins](https://img.shields.io/badge/plugins-7-teal)](adapters/opencode/plugins/)
 [![OpenCode · Claude Code · Bob · OpenClaude · AGENT.md](https://img.shields.io/badge/works%20with-OpenCode%20·%20Claude%20Code%20·%20Bob%20·%20OpenClaude%20·%20AGENT.md-1f6feb)](#-supported-harnesses)
@@ -178,7 +178,7 @@ The harness ships as a small set of layers, and the web console's rail is the sa
 | **🧭 Ethos** (`ontology/`) | the mind the rules govern, in four prose sections — **Telos** (the Pact: three ranked laws — protect the user, serve their intent, keep your own honesty), **Evidence** (every claim graded by how it was obtained), **Decisions** (classify and tier by reversibility, show the real forks), **Conduct** (answer what was asked, once). Always in force, never toggleable |
 | **🛡️ Rules** (`laws/`) | 9 universal laws — always in force, never toggleable: sealed-secrets, one-intent-one-act, verify-before-asserting, deletion-is-deliberate, surface-failures, data-not-orders, least-privilege, cure-the-cause, echo-the-intent. Each rule has a permanent id; its number is only its position, and the harness cites rules by name |
 | **📐 Doctrines** (`doctrines/`) | practice packs, chosen per install at build time: **craft** (how code is written), **rigor** (how work is proven), **ops** (how the machine is operated), **process** (how a task is run), **comms** (how answers are presented). A doctrine rule may tighten a Rule, never repeal one, and the user's own `user-rules.md` outranks it. Pick with `geneseed-build --doctrines craft,rigor` (or `none`), a single rule with `--exclude-rules "process 7"`, in the setup wizard, or through the switches on the console's Constitution page; all five pack files ship on disk either way, so a citation into a pack you left out still resolves |
-| **🤖 Agents** (19) | capability specialists: `reviewer`, `tester`, `architect`, `docs`, `security`, `performance`, `explorer`, `researcher`, `developer` — plus a debate **council** the `council` skill convenes: `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`, `user-advocate`, `framer`, `empiricist`, `operator`, `historian` |
+| **🤖 Agents** (20) | capability specialists: `reviewer`, `tester`, `architect`, `docs`, `security`, `performance`, `explorer`, `researcher`, `developer`, `memory-curator` — plus a debate **council** the `council` skill convenes: `advocate`, `skeptic`, `pragmatist`, `steward`, `visionary`, `user-advocate`, `framer`, `empiricist`, `operator`, `historian` |
 | **🛠 Skills** (46) | repeatable workflows: brainstorm · plan · **codebase-design** · **wayfinder** · **develop** · **worktree** · debug · **prototype** · refactor · **ponytail** · **forge-mcp** · **bruno** · geneseed-code-review · **fresh-eyes** · **security-audit** · **dependencies** · **review-response** · commit · **ship** · **release** · **git-history** · document-project · **frontend-design** · **prose** · **ingest** · **research** · **teach** · **quiz** · **learn-mode** · handoff · roast-me · **council** · parallel-agents · **workflow** · **wiki** · **geneseed** · **rule** · **profile** · **skill-forge** · **pipeline** · **loop** · **brick-forge** · **daydream** · **react-view-transitions** · **token-report** · **explain-changes** |
 | **🔌 Plugins** (OpenCode) | `geneseed-context` injects project docs *and your machine wiki* every session (and across compaction); `geneseed-learn` distils memory at session end; `geneseed-guard` enforces the safety Laws and protected wiki folders at the tool boundary; `geneseed-workflow` registers the `workflow` tool that runs saved orchestration scripts; `geneseed-notify` sends a native OS notification when a long run finishes; `geneseed-ponytail` holds a minimal-code mode (`/ponytail lite\|full\|ultra\|off`), opt-in, injecting the laziest-that-works ruleset every turn so it doesn't drift; `geneseed-activity` streams what each session is doing to the web console's Activity view |
 | **🧠 Memory** (`memory/`) | one-fact-per-file durable knowledge, indexed by `MEMORY.md` (git-ignored, personal) |

package/SHIPPED.md

@@ -20,7 +20,7 @@ historical references, not files distributed with the repo.
 > **On version numbers.** [`harness.config.json`](harness.config.json)'s `version` is a
 > human-readable label only. The canonical identity of an installed harness is the
 > **source fingerprint** stamped in `.geneseed-version` (see `geneseed version`), not the
-> string. Current label: **4.3.1**.
+> string. Current label: **4.4.0**.
 
 ## Capabilities
 
@@ -29,7 +29,7 @@ Every row below is present in the tree today; "Spec" names the design record.
 | Capability | What it is | Spec |
 | --- | --- | --- |
 | **Themed generator** | One neutral `src/` → 14 themed bundles via `geneseed-build` (zero dependencies); structure stays theme-independent | [DESIGN.md](DESIGN.md) |
-| **Laws / Agents / Skills / Memory / Notebook** | 9 laws, 19 agents, 46 skills, the memory convention, and the agent's sovereign notebook | `2026-06-11-notebook-sovereign-space` · `2026-06-10-notebook-agent-own-space` |
+| **Laws / Agents / Skills / Memory / Notebook** | 9 laws, 20 agents, 46 skills, the memory convention, and the agent's sovereign notebook | `2026-06-11-notebook-sovereign-space` · `2026-06-10-notebook-agent-own-space` |
 | **Three-tier constitution** | The governance surface splits into an always-on **Ontology** (Telos, Evidence, Decisions, Conduct — the Pact absorbed into Telos), the nine always-on **Invariants**, and five toggleable **Doctrine** packs (craft, rigor, ops, process, comms) addressed `<pack> <n>`. Every rule carries a permanent id; its number is its position, computed at render time, and a citation renders as the rule's principle name. Packs are chosen at build time with `--doctrines` or the setup wizard; the whole catalogue ships on disk either way, so a citation into an inactive pack still resolves. Precedence, in order: Ontology + Invariants, then the user's `user-rules.md`, then the active Doctrines, then `PROFILE.md`. `doctor`'s `constitutionProblems` gates rule ids (declared, unique, never a retired one), the per-rule Principle column, every `{{LAW:<id>}}` / `{{DOCTRINE:<id>}}` citation in `src/`, and the rule that an always-on tier may never cite a toggleable one | `2026-08-19-three-tier-constitution-design` |
 | **`doctor`** | One check: unresolved tokens, dead/non-hermetic links, theme-key parity, authoring gates, rendered-bundle drift | `2026-06-07-theme-aware-doctor-diff` |
 | **`diff` + improvements export** | Deployed-vs-source drift report; export an `improvements.md` back-port | `2026-06-12-improvements-export` |

package/adapters/opencode/plugins/geneseed-context.js

@@ -237,11 +237,28 @@ async function sessionFiles(dir) {
     let text
     try { text = (await fs.readFile(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
 }
 
+// The memory map's curation nudge: same rule, threshold and text as memoryNudge in
+// js/hosts/hooks-context.mjs (tests/unit/claude.test.mjs gates the copy). Read off the map's
+// own counts; a large but curated store is never nagged.
+const MAP_COUNT_RE = /^- \[([^\]]*)\]\(topics\/[^)]+\.md\) — (\d+) facts?$/
+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."
+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 ""
+}
+
 async function readJson(p) {
   try { return JSON.parse(await fs.readFile(p, "utf8")) } catch { return null }
 }

package/adapters/opencode/plugins/geneseed-learn.js

@@ -13,8 +13,8 @@
 // on the first idle would therefore mine just turn 1 and miss the rest. So each idle
 // RE-ARMS a debounce timer (GENESEED_LEARN_DEBOUNCE_MS, default 60s) and the distil
 // runs once the session has been quiet for that long — i.e. at the real end. A
-// continued session simply re-arms and re-distils; slug dedup keeps writes
-// idempotent. (Trade-off: if OpenCode is killed inside the window the final distil
+// continued session simply re-arms and re-distils; a stored slug is never created
+// twice, though a re-distil may update or archive it. (Trade-off: if OpenCode is killed inside the window the final distil
 // is lost — still strictly better than capturing only turn 1, and far cheaper than
 // re-distilling every turn.)
 //
@@ -125,10 +125,22 @@ Markdown memory files in this exact format, separated by a line containing only
 name: <kebab-case-slug>
 description: <one-line summary>
 type: user | feedback | project | reference
+topic: <kebab-case-slug; reuse a topic from TOPICS IN USE below when one fits>
 ---
 <the fact, stated plainly. For 'feedback' and 'project', add **Why:** and
 **How to apply:** lines.>
 
+MERGE BEFORE YOU CREATE. The facts already stored are listed below as
+'slug — description'. Never create a fact under one of those slugs. Instead:
+  - If your memory refines, extends or corrects a stored fact, add the line
+    'action: update' to its frontmatter and use that fact's own name. Your text
+    REPLACES the stored file, so write the merged fact: keep everything the old
+    one says that is still true, then add or correct what the notes show.
+  - If the notes show a stored fact is now false or obsolete, output only
+    frontmatter holding its 'name:' and the line 'action: archive'. It is moved
+    out of the index, never deleted.
+  - With no 'action:' line, the memory is a NEW fact under a NEW slug.
+
 DEFAULT TO 'NOTHING'. Writing a memory is the rare exception, not the norm — most
 sessions should yield zero. Emit AT MOST ONE, and only if it is a GENERAL, reusable
 principle you would want at the START of an unrelated future task.
@@ -252,29 +264,28 @@ function envModel() {
 const RESERVED_STEMS = new Set(["memory", "readme"])
 
 async function existingSlugs(memDir) {
-  const skip = RESERVED_STEMS
-  try {
-    const entries = await fs.readdir(memDir)
-    return new Set(
-      entries
-        .filter((f) => f.endsWith(".md"))
-        .map((f) => f.slice(0, -3))
-        .filter((s) => !skip.has(s.toLowerCase()))
-    )
-  } catch {
-    return new Set()
-  }
+  return new Set((await listMd(memDir)).map((f) => f.slice(0, -3)).filter((s) => !RESERVED_STEMS.has(s.toLowerCase())))
 }
 
-function buildPrompt(notes, existing) {
+// The stored facts' lines are capped at MAX_STORED_CHARS, a twin of buildLearnPrompt in
+// js/hosts/hooks-learn.mjs: a store of hundreds of facts would otherwise outgrow the notes.
+// A fact past the cap is only unlisted — writeMemories still refuses to create its slug.
+const MAX_STORED_CHARS = 8000
+function buildPrompt(notes, facts) {
   const parts = [LEARN_PROMPT_HEAD, ""]
-  if (existing.size) {
-    parts.push(
-      "ALREADY STORED — do NOT emit a memory matching any of these slugs " +
-        "(skip updates too; only genuinely new facts):"
-    )
-    for (const slug of [...existing].sort()) parts.push(`- ${slug}`)
-    parts.push("")
+  if (facts.size) {
+    parts.push("ALREADY STORED — 'slug — description', to update or archive, never to create:")
+    let used = 0
+    let shown = 0
+    for (const [slug, { desc }] of facts) {
+      const line = desc ? `- ${slug} — ${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")
@@ -296,37 +307,158 @@ function parseFrontmatter(chunk) {
 // js/hosts/hooks.mjs, inlined because this file ships standalone.
 const MEMORY_SLUG_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/
 
-// Compared lowercase: on a case-insensitive filesystem (Windows, macOS) `User-Prefs`
-// and `user-prefs` are the same file, so a case variant would overwrite a stored fact.
+// 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")
+}
+
+// A fact with a `force:` is never updated or archived by learn (the memory README's Bridge
+// rule: revised inline with its supersession recorded, a constraint only by the user).
+async function hasForce(memDir, slug) {
+  try {
+    return !!parseFrontmatter((await fs.readFile(path.join(memDir, `${slug}.md`), "utf8")).replace(/\r\n/g, "\n")).force
+  } catch { return false }
+}
+
+// Move <slug>.md into archive/, never over a file already there (-2, -3, ... instead), and
+// never unlink: an archived fact leaves the index but stays on disk.
+async function archiveFact(memDir, slug) {
+  const adir = path.join(memDir, "archive")
+  await fs.mkdir(adir, { recursive: true })
+  let dest = path.join(adir, `${slug}.md`)
+  for (let n = 2; await fs.stat(dest).then(() => true, () => false); n += 1) dest = path.join(adir, `${slug}-${n}.md`)
+  await fs.rename(path.join(memDir, `${slug}.md`), dest)
+}
+
+// The twin of writeMemories in js/hosts/memory-files.mjs: no `action:` creates a NEW slug,
+// `action: update` archives the stored fact and writes the merged text in its place, `action: archive` moves it
+// to archive/. An update or archive of no stored fact, or of one with a `force:`, is skipped,
+// as is any other action, and each slug is acted on once. Compared lowercase: on a case-insensitive filesystem (Windows,
+// macOS) `User-Prefs` and `user-prefs` are the same file, so a case variant acts on the
+// stored spelling and never creates a second fact.
 async function writeMemories(output, 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 output.split(/^---FILE---\s*$/m)) {
     chunk = chunk.trim()
     if (!chunk || chunk.toUpperCase() === "NOTHING") continue
     const fm = parseFrontmatter(chunk)
     const name = (fm.name || "").trim()
     const key = name.toLowerCase()
-    if (!MEMORY_SLUG_RE.test(name) || RESERVED_STEMS.has(key) || taken.has(key)) continue
-    await fs.writeFile(path.join(memDir, `${name}.md`), chunk.replace(/\n+$/, "") + "\n", "utf8")
-    existing.add(name)
-    taken.add(key)
-    written.push(name)
-    const desc = (fm.description || "").trim()
-    indexLines.push(`- [${name}](${name}.md)` + (desc ? ` — ${desc}` : ""))
+    const action = (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" && (await hasForce(memDir, slug))) continue
+    const body = stripAction(chunk).replace(/\n+$/, "") + "\n"
+    if (action === "create" && !slug) {
+      await fs.writeFile(path.join(memDir, `${name}.md`), body, "utf8")
+      existing.add(name)
+      stored.set(key, name)
+      res.created.push(name)
+    } else if (action === "update" && slug) {
+      await archiveFact(memDir, slug) // the old version first: the model never saw its body
+      await fs.writeFile(path.join(memDir, `${slug}.md`), body, "utf8")
+      res.updated.push(slug)
+    } else if (action === "archive" && slug) {
+      await archiveFact(memDir, slug)
+      existing.delete(slug)
+      stored.delete(key)
+      res.archived.push(slug)
+    } else continue
+    done.add(key)
+  }
+  if (res.created.length || res.updated.length || res.archived.length) await rebuildIndex(memDir, new Set(res.updated))
+  return res
+}
+
+// The two-level index, a twin of rebuildIndex in js/hosts/memory-files.mjs (this file ships
+// standalone): MEMORY.md is a map of topics, each topics/<topic>.md lists its facts. A fact
+// already indexed keeps its line (title and hook), a new one gets its description, a topic
+// file no fact uses is deleted, and map lines the build did not generate are carried.
+const MEMORY_SEED = "# Memory Index\n"
+const MAP_HINT = "Each topic file lists its facts; open the one the task needs."
+const FACT_LINE_RE = /^- \[([^\]]*)\]\((?:\.\.\/)?([^/)]+)\.md\)(.*)$/
+const MAP_LINE_RE = /^- \[[^\]]*\]\(topics\/[^)]+\.md\)/
+
+const readLines = async (p) => {
+  try { return (await fs.readFile(p, "utf8")).replace(/\r\n?/g, "\n").replace(/\n$/, "").split("\n") } catch { return null }
+}
+// The core's sortPaths/globMd rule (js/lib/paths.mjs normcase): names fold case on Windows, so
+// the fact order inside a topic file, and which files count as .md, match the harness's.
+const fold = (s) => (process.platform === "win32" ? s.toLowerCase() : s)
+const listMd = async (dir) => {
+  try {
+    return (await fs.readdir(dir)).filter((f) => fold(f).endsWith(".md"))
+      .sort((a, b) => (fold(a) < fold(b) ? -1 : fold(a) > fold(b) ? 1 : 0))
+  } catch { return [] }
+}
+async function writeIfChanged(p, text) {
+  const old = await readLines(p)
+  if (old && old.join("\n") + "\n" === text) return
+  await fs.writeFile(p, text, "utf8")
+}
+// `topic:`, else `type:` (a `type:` nested under `metadata:` reads the same: keys are trimmed).
+function topicOf(fm) {
+  const raw = (fm.topic || fm.type || "").trim()
+  return raw.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "misc"
+}
+
+// Every top-level fact (never archive/ or agents/), in index order: slug -> { desc, topic }.
+async function readFacts(memDir) {
+  const facts = new Map()
+  for (const f of await listMd(memDir)) {
+    const slug = f.slice(0, -3)
+    if (RESERVED_STEMS.has(slug.toLowerCase())) continue
+    let fm
+    try { fm = parseFrontmatter((await fs.readFile(path.join(memDir, f), "utf8")).replace(/\r\n/g, "\n")) } catch { continue }
+    facts.set(slug, { desc: (fm.description || "").trim(), topic: topicOf(fm) })
+  }
+  return facts
+}
+
+// `fresh`: slugs just updated, whose old index line describes a fact that is gone.
+async function rebuildIndex(memDir, fresh = new Set()) {
+  const tdir = path.join(memDir, "topics")
+  const old = new Map()
+  for (const f of [path.join(memDir, "MEMORY.md"), ...(await listMd(tdir)).map((t) => path.join(tdir, t))]) {
+    for (const line of (await readLines(f)) ?? []) {
+      const m = FACT_LINE_RE.exec(line.trim())
+      if (m) old.set(m[2], { title: m[1], rest: m[3] })
+    }
+  }
+  const byTopic = new Map()
+  for (const [slug, { desc, topic }] of await readFacts(memDir)) {
+    const o = 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)
+  }
+  for (const f of await listMd(tdir)) {
+    if (!byTopic.has(f.slice(0, -3))) await fs.unlink(path.join(tdir, f))
   }
-  if (indexLines.length) {
-    const index = path.join(memDir, "MEMORY.md")
-    let current = "# Memory Index\n"
-    try { current = (await fs.readFile(index, "utf8")).replace(/\n+$/, "") + "\n" } catch {}
-    await fs.writeFile(index, current + indexLines.join("\n") + "\n", "utf8")
+  if (byTopic.size) await fs.mkdir(tdir, { recursive: true })
+  else await fs.rmdir(tdir).catch(() => {})
+  const mapLines = []
+  for (const topic of [...byTopic.keys()].sort()) {
+    const lines = byTopic.get(topic)
+    await writeIfChanged(path.join(tdir, `${topic}.md`), `# ${topic}\n\n${lines.join("\n")}\n`)
+    mapLines.push(`- [${topic}](topics/${topic}.md) — ${lines.length} fact${lines.length === 1 ? "" : "s"}`)
   }
-  return written
+  const index = path.join(memDir, "MEMORY.md")
+  const carried = ((await readLines(index)) ?? []).filter((l) => {
+    const t = l.trim()
+    return t && t !== MEMORY_SEED.trim() && t !== MAP_HINT && !MAP_LINE_RE.test(t) && !FACT_LINE_RE.test(t)
+  })
+  const body = [...(mapLines.length ? ["", MAP_HINT, "", ...mapLines] : []), ...(carried.length ? ["", ...carried] : [])]
+  await writeIfChanged(index, body.length ? MEMORY_SEED + body.join("\n") + "\n" : MEMORY_SEED)
 }
 
 // The distil's reply into the store: a child session's one agent lesson, else memory
-// files plus their MEMORY.md lines. Shared by the V1 and V2 runs.
+// files plus their two-level index. Shared by the V1 and V2 runs.
 async function storeDistil(output, { isChild, memDir, agentName, existing }) {
   if (!output.trim() || output.trim().toUpperCase() === "NOTHING") return
   if (isChild) {
@@ -336,9 +468,9 @@ async function storeDistil(output, { isChild, memDir, agentName, existing }) {
     console.error(`[geneseed-learn] agent lesson -> ${f}`)
     return
   }
-  const written = await writeMemories(output, memDir, existing)
-  if (written.length) {
-    console.error(`[geneseed-learn] wrote ${written.length} memory file(s): ${written.join(", ")}`)
+  const res = await writeMemories(output, memDir, existing)
+  for (const [verb, slugs] of [["wrote", res.created], ["updated", res.updated], ["archived", res.archived]]) {
+    if (slugs.length) console.error(`[geneseed-learn] ${verb} ${slugs.length} memory file(s): ${slugs.join(", ")}`)
   }
 }
 
@@ -395,7 +527,7 @@ export const GeneseedLearn = async (ctx) => {
       const existing = await existingSlugs(memDir)
       const prompt = isChild
         ? [AGENT_LESSON_PROMPT, "", "NOTES:", notes].join("\n")
-        : buildPrompt(notes, existing)
+        : buildPrompt(notes, await readFacts(memDir))
 
       // Distil in a throwaway session with the session's own model, then drop it.
       const session = await client.session.create({ body: { title: "geneseed-learn (auto)" } })
@@ -529,7 +661,7 @@ async function setupV2(ctx) {
       const existing = await existingSlugs(memDir)
       const prompt = isChild
         ? [AGENT_LESSON_PROMPT, "", "NOTES:", notes].join("\n")
-        : buildPrompt(notes, existing)
+        : buildPrompt(notes, await readFacts(memDir))
       const reply = await ctx.generate.text({
         prompt, model: { providerID: model.providerID, id: model.id, ...(model.variant ? { variant: model.variant } : {}) },
       })

package/docs/concepts/agents.md

@@ -26,6 +26,7 @@ An **agent** is a specialist the main session can hand a piece of work to. Each
 | `security` | audits changes that touch the security surface |
 | `performance` | measures where time and memory go, names the bottleneck with numbers, proposes the fix |
 | `docs` | writes and updates user-facing documentation after code lands |
+| `memory-curator` | tidies a large memory store: merges duplicates, assigns topics, archives stale facts, proposes deletions for your approval |
 
 ### The council
 

package/docs/concepts/hooks.md

@@ -39,7 +39,7 @@ Geneseed writes its hooks into the host's settings file. Every hook calls one pr
 - A write to a check the project protects gets a prompt citing *External Gate* (on Bob, it is blocked). A project opts in with `.geneseed/protected-checks.txt` at its git root: one repo-relative file or folder per line, `#` for comments — the checks and tests the agent is judged by. A check the agent can edit is not a check. The list protects itself. Only file-write tools are seen: a shell `sed -i` or redirect is not, so run the same checks in CI as the boundary that holds.
 - Ordinary edits pass untouched.
 
-**learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries under `memory/`, skipping duplicates. It needs `GENESEED_LLM` set to a model command, for example:
+**learn.** Takes the tail of the transcript and asks a model to distil what is worth keeping into one-fact-per-file entries under `memory/`. It is shown the facts already stored, so it updates one with the merged text rather than writing a twin (the old version is kept in `memory/archive/`), and moves one the session proved obsolete into `memory/archive/`. It needs `GENESEED_LLM` set to a model command, for example:
 
 ```bash
 export GENESEED_LLM="claude -p"

package/docs/reference/plugin-learn.md

@@ -8,11 +8,11 @@ description: "Distils durable facts into memory/ once a session goes quiet."
 ---
 One of the [OpenCode plugins](opencode-plugins.md). Its switches are also listed in [Context and memory variables](env-context.md).
 
-**What it does.** Distils durable memories from the conversation into the install's `memory/` directory and keeps `MEMORY.md` up to date, de-duplicating against what is already stored. It is the OpenCode counterpart of the Claude Code `Stop` hook, but needs no API key and no model CLI: it distils with the **same model the session used**, through your OpenCode provider config. See [Memory](../concepts/memory.md).
+**What it does.** Distils durable memories from the conversation into the install's `memory/` directory and keeps its two-level index (`MEMORY.md` and `topics/`) up to date. It never writes a twin of a stored fact: it updates that fact with the merged text instead (keeping the old version in `memory/archive/`), and moves one the session proved obsolete into `memory/archive/`. It is the OpenCode counterpart of the Claude Code `Stop` hook, but needs no API key and no model CLI: it distils with the **same model the session used**, through your OpenCode provider config. See [Memory](../concepts/memory.md).
 
 **When it runs.** After the session goes quiet. OpenCode signals "idle" after every turn, so each idle re-arms a timer and the distil runs once nothing has happened for `GENESEED_LEARN_DEBOUNCE_MS` (default 60 s). Trivial sessions are skipped.
 
-**What you see.** On stderr: `[geneseed-learn] wrote N memory file(s): …`, or `skipped: <reason>`. Total silence means it did not load.
+**What you see.** On stderr: `[geneseed-learn] wrote N memory file(s): …` (or `updated` / `archived`), or `skipped: <reason>`. Total silence means it did not load.
 
 **Where it writes** — the first that resolves:
 1. `GENESEED_MEMORY` — an explicit memory dir;

package/docs/understand/a-day.md

@@ -66,13 +66,13 @@ type: project
 The integration tests start Postgres in a container; run `docker info` before the suite.
 ```
 
-and one line is added to `memory/MEMORY.md`:
+and one line is added to its topic file, `memory/topics/project.md` (the topic is the fact's `topic:`, else its `type:`):
 
 ```markdown
-- [integration-tests-need-docker](integration-tests-need-docker.md) — the integration suite needs a running Docker daemon
+- [integration-tests-need-docker](../integration-tests-need-docker.md) — the integration suite needs a running Docker daemon
 ```
 
-Next session, that index is in front of the agent before your first message. Memory stays on your machine. `geneseed memory list` shows every fact and `geneseed memory rm <name>` removes one.
+`memory/MEMORY.md` stays a short map, one line per topic with its fact count. Next session, that map is in front of the agent before your first message, and the agent opens the topic file a task needs. If a later session refines that fact, learn updates the same file instead of adding a twin, keeping the old version in `memory/archive/`; if it shows the fact is obsolete, the file moves to `memory/archive/` and leaves the index. Memory stays on your machine. `geneseed memory list` shows every fact and `geneseed memory rm <name>` moves one to `memory/archive/` (`--purge` deletes it for good). When a topic grows past 40 facts or facts land in `misc`, the session says so in one line, and the `memory-curator` agent tidies the store in bulk.
 
 ---
 

package/docs/understand/machine-claude.md

@@ -20,7 +20,7 @@ What a Claude Code or OpenClaude install writes, piece by piece. The **Kind** wo
 | learn hook | When the agent finishes a reply, and before compaction, distils durable facts from the recent conversation into `memory/`. Off until you set `GENESEED_LLM` to a model command such as `claude -p` | automatic | One model call each time it runs, once enabled | Leave `GENESEED_LLM` unset (the default) |
 | `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~4.1k tokens for names and descriptions; a skill's body loads only when called | No per-skill switch; `geneseed uninstall` removes them all |
 | `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
-| `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context hook injects | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` |
+| `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context hook injects | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` (archives; `--purge` deletes) |
 | `notebook/` | The agent's own working space: plans, scratch notes, and the gate log `gates.jsonl` | automatic | 0 when fresh; its index grows with use | Delete what you do not want; it is git-ignored and yours |
 | hook shim | `~/.geneseed/bin/geneseed-hook`, the one stable path every hook calls, so moving the Geneseed checkout does not break your hooks | automatic | Nothing on its own | Not removed by uninstall, since every install on the machine shares it. `GENESEED_HOME` moves it |
 

package/docs/understand/machine-opencode.md

@@ -24,7 +24,7 @@ What an OpenCode install writes, piece by piece. The **Kind** words are explaine
 | workflow plugin | Adds a `workflow` tool that runs saved orchestration scripts | on demand | Runs only when called | `geneseed uninstall` |
 | `skills/` | Written procedures you call by name, such as `brainstorm` or `plan` | on demand | ~4.1k tokens for names and descriptions; a skill's body loads only when called | No per-skill switch; `geneseed uninstall` removes them all |
 | `agents/` | Specialists the agent can delegate to, such as `reviewer` or `tester` | on demand | ~0.5k tokens | `geneseed uninstall` |
-| `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context plugin injects | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` |
+| `memory/` | Durable facts, one per file, with a `MEMORY.md` index the context plugin injects | automatic | 0 when fresh; grows as facts accumulate | `geneseed memory list`, then `geneseed memory rm <name>` (archives; `--purge` deletes) |
 | `notebook/` | The agent's own working space: plans, scratch notes, and the gate log `gates.jsonl` | automatic | 0 when fresh; its index grows with use | Delete what you do not want; it is git-ignored and yours |
 
 ## Where the files are

package/harness.config.json

@@ -2,5 +2,5 @@
   "_comment": "version is a human-readable release label only; the canonical identity of an installed harness is the source fingerprint stamped in .geneseed-version (see `harness version`), not this string.",
   "theme": "neutral",
   "product": "Geneseed",
-  "version": "4.3.1"
+  "version": "4.4.0"
 }

package/js/README.md

@@ -181,7 +181,7 @@ Verbs that change an install that already exists, as opposed to rendering one.
 | `setup.mjs` | The install wizard, and the CLI's only synchronous stdin readers (`ask`/`confirm`/`askChoice`) |
 | `uninstall.mjs` | Removes or disables an install: manifest-driven reversal, plus stash deactivate/reactivate |
 | `migrate.mjs` | `geneseed migrate` — all-or-nothing re-emit moving installs onto the npm install shape |
-| `memory.mjs` | `geneseed memory list|rm` — CLI-side fact deletion, twin of the web DELETE endpoint |
+| `memory.mjs` | `geneseed memory list|rm` — CLI-side fact removal (archive by default, `--purge` deletes), twin of the web delete endpoint |
 
 **Before editing:** `update.mjs` is the one module that MUST spawn rather than import — the code on
 disk is replaced mid-run, so an in-process call would validate the *old* source and then render it.

package/js/build/bundle.mjs

@@ -12,6 +12,7 @@
  */
 import path from 'node:path';
 import { VERSION_MARKER } from '../hosts/hosts.mjs';
+import { migrateMemoryIndex } from '../hosts/memory-files.mjs';
 import { copyFile, isDir, isFile, readText, writeText } from '../lib/fs.mjs';
 import { jsonDumpsIndent, parseJson, formatReprAscii, isTruthy } from '../lib/json.mjs';
 import { OWNED_SRC_DIRS, SRC_DIRS_MARKER, TMPL_SPEC_RE } from './emit-common.mjs';
@@ -223,6 +224,7 @@ export function build(cfg, themeName, out, { footprint = 'full', nativeCatalog =
   ensureProfileStub(out);
   ensureBundleGitignore(out);
   ensureMemoryIndex(path.join(out, theme[SRC_DIR_TOKENS.memory] ?? 'memory'));
+  migrateMemoryIndex(path.join(out, theme[SRC_DIR_TOKENS.memory] ?? 'memory'));
   ensureNotebookIndex(path.join(out, theme[SRC_DIR_TOKENS.notebook] ?? 'notebook'));
   process.stdout.write(`[geneseed] built theme '${themeName}' -> ${out} (${items.length} files)\n`);
 }

package/js/build/emit-claude.mjs

@@ -7,6 +7,7 @@
  */
 import path from 'node:path';
 import { VERSION_MARKER } from '../hosts/hosts.mjs';
+import { migrateMemoryIndex } from '../hosts/memory-files.mjs';
 import { claimer, loadAgentOverrides, writeNativeLayer } from '../hosts/native.mjs';
 import { ensureAgentOverridesStub, writeAliasCommands } from '../hosts/opencode.mjs';
 import {
@@ -146,6 +147,7 @@ export function emitClaudeRender(cfg, job) {
 
   const memStatus = globalMemory(cfgDir, items, out, cfg.src);
   ensureMemoryIndex(path.join(cfgDir, 'memory'));
+  migrateMemoryIndex(path.join(cfgDir, 'memory'));
   const nbStatus = globalNotebook(cfgDir, items, out, cfg.src);
   ensureNotebookIndex(path.join(cfgDir, 'notebook'));
   // context.json too: the root names it as the project's own manifest, and until 2026-10 this

package/js/build/emit-opencode.mjs

@@ -8,6 +8,7 @@
  */
 import path from 'node:path';
 import { VERSION_MARKER } from '../hosts/hosts.mjs';
+import { migrateMemoryIndex } from '../hosts/memory-files.mjs';
 import { claimer, loadAgentOverrides, writeNativeLayer } from '../hosts/native.mjs';
 import {
   copyPlugins, copyWorkflows, ensureAgentOverridesStub, writeColorThemes, writeCommandLayer,
@@ -233,6 +234,7 @@ export function emitOpencodeGlobalRender(cfg, job) {
 
   const memStatus = globalMemory(cfgDir, items, out, cfg.src);
   ensureMemoryIndex(path.join(cfgDir, 'memory'));
+  migrateMemoryIndex(path.join(cfgDir, 'memory'));
   const nbStatus = globalNotebook(cfgDir, items, out, cfg.src);
   ensureNotebookIndex(path.join(cfgDir, 'notebook'));
   ensureWikiStub(cfgDir);

package/js/build/stubs.mjs

@@ -4,14 +4,18 @@
  *
  * Every stub is a literal here and an `ensure*` beside it, and the pairing is the contract:
  * the writer checks first and returns without writing when the file exists, because these are
- * the USER's files from the moment they exist. A stub body is bytes a recorded corpus compares
- * — changing one is a product change, not a tidy-up.
+ * the USER's files from the moment they exist. One exception: an emit also calls
+ * `migrateMemoryIndex` on the memory store, which rewrites a FLAT MEMORY.md (and its
+ * `topics/` files) into the two-level index once, losslessly, because a flat index overruns
+ * the session-start budget. Fact files are never touched. A stub body is bytes a recorded
+ * corpus compares — changing one is a product change, not a tidy-up.
  */
 import path from 'node:path';
 import { writeText } from '../lib/fs.mjs';
 import { isDir } from '../lib/fs.mjs';
 import { jsonDumpsIndent } from '../lib/json.mjs';
 import { EXCLUDES_FILE } from '../hosts/hosts.mjs';
+import { MEMORY_SEED } from '../hosts/memory-files.mjs';
 import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 
 // ---------------------------------------------------------------------------
@@ -202,7 +206,7 @@ agent-overrides.json
 `;
 
 // ---------------------------------------------------------------------------
-// Seeded stubs — write-once, never overwrite
+// Seeded stubs — write-once, never overwrite (MEMORY.md: see the header's one exception)
 // ---------------------------------------------------------------------------
 
 /**
@@ -276,7 +280,8 @@ export const ensureBundleGitignore = stubWriter('.gitignore', BUNDLE_GITIGNORE);
  * right after the store dir is created, but never invent the dir themselves). */
 const storeIndexWriter = (file, header) => (dir) => { if (isDir(dir)) seed(path.join(dir, file), header); };
 
-const MEMORY_INDEX = '# Memory Index\n';
+// Owned by `js/hosts/memory-files.mjs`, which writes an emptied store back to these bytes.
+const MEMORY_INDEX = MEMORY_SEED;
 const NOTEBOOK_INDEX = '# Notebook Index\n';
 
 /** `_build_render.ensure_memory_index` — only inside an EXISTING store dir. */