geneseed 4.3.0 → 4.4.0

package/CHANGELOG.md

@@ -8,6 +8,35 @@ 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.
+
+### Upgrade notes
+- Run `geneseed rebuild-all` once after updating so installed hooks and OpenCode plugins carry the fix.
+- On Claude Code and OpenClaude, a worktree still loads the global `CLAUDE.md` until you commit the `claudeMdExcludes` snippet that `geneseed exclude list` prints into the repo's tracked settings file.
+
+### Fixed
+- **Exclusions cover git worktrees.** A session in a linked worktree of an excluded repo (`git worktree add`, or a tool that keeps worktrees elsewhere on disk) got the whole global harness, because the bypass only matched the working directory's path. The hooks and the three OpenCode plugins now follow the worktree's `.git` file back to the main repository, reading files only. `exclude add` and `exclude list` warn that `settings.local.json` never reaches a worktree and print the snippet to commit; Geneseed writes no tracked file. (#280)
+
 ## [4.3.0] — 2026-10-15
 
 Minor: a performance agent, and Deletion Is Deliberate says what counts as recoverable.

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.0**.
+> 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

@@ -85,17 +85,41 @@ const norm = (p) => {
   }
   return process.platform === "win32" ? s.toLowerCase() : s
 }
+// A linked git worktree of an excluded repo is excluded too, wherever it sits on disk — twin of
+// js/hosts/gitref.mjs `mainWorktreeOf`: the worktree's `.git` FILE names its gitdir, whose
+// `commondir` names the shared `.git`; that directory's parent is the main worktree. null for
+// a main worktree, a submodule, a bare repo's worktree, or anything malformed.
+async function mainWorktreeOf(dir) {
+  try {
+    let root = path.resolve(dir)
+    for (;;) {
+      try { await fs.stat(path.join(root, ".git")); break } catch { /* walk up */ }
+      const up = path.dirname(root)
+      if (up === root) return null
+      root = up
+    }
+    const dotgit = path.join(root, ".git")
+    if (!(await fs.stat(dotgit)).isFile()) return null
+    const m = /^gitdir:\s*(.+?)\s*$/m.exec(await fs.readFile(dotgit, "utf8"))
+    if (!m) return null
+    const gitdir = path.resolve(root, m[1])
+    const common = path.resolve(gitdir, (await fs.readFile(path.join(gitdir, "commondir"), "utf8")).trim())
+    return path.basename(common) === ".git" ? path.dirname(common) : null
+  } catch { return null }
+}
 async function sovereignBypass(cwd) {
   try {
     const cfg = path.dirname(PLUGIN_DIR)           // plugins/ sits directly in <cfg>
     const raw = await fs.readFile(path.join(cfg, "excludes.json"), "utf8")
     const entries = (JSON.parse(raw).excludes) || []
     const here = norm(cwd || process.cwd())
+    const main = await mainWorktreeOf(cwd || process.cwd())
+    const heres = main ? [here, norm(main)] : [here]
     for (const e of entries) {
       const p = typeof e === "string" ? e : e && e.path
       if (typeof p !== "string" || !p.trim()) continue
       const base = norm(p.trim()).replace(/[\\/]+$/, "")
-      if (here === base || here.startsWith(base + path.sep)) return true
+      if (heres.some((h) => h === base || h.startsWith(base + path.sep))) return true
     }
   } catch { /* degrade to active */ }
   return false
@@ -213,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-guard.js

@@ -72,17 +72,41 @@ const norm = (p) => {
   }
   return process.platform === "win32" ? s.toLowerCase() : s
 }
+// A linked git worktree of an excluded repo is excluded too, wherever it sits on disk — twin of
+// js/hosts/gitref.mjs `mainWorktreeOf`: the worktree's `.git` FILE names its gitdir, whose
+// `commondir` names the shared `.git`; that directory's parent is the main worktree. null for
+// a main worktree, a submodule, a bare repo's worktree, or anything malformed.
+async function mainWorktreeOf(dir) {
+  try {
+    let root = path.resolve(dir)
+    for (;;) {
+      try { await fs.stat(path.join(root, ".git")); break } catch { /* walk up */ }
+      const up = path.dirname(root)
+      if (up === root) return null
+      root = up
+    }
+    const dotgit = path.join(root, ".git")
+    if (!(await fs.stat(dotgit)).isFile()) return null
+    const m = /^gitdir:\s*(.+?)\s*$/m.exec(await fs.readFile(dotgit, "utf8"))
+    if (!m) return null
+    const gitdir = path.resolve(root, m[1])
+    const common = path.resolve(gitdir, (await fs.readFile(path.join(gitdir, "commondir"), "utf8")).trim())
+    return path.basename(common) === ".git" ? path.dirname(common) : null
+  } catch { return null }
+}
 async function sovereignBypass(cwd) {
   try {
     const cfg = path.dirname(PLUGIN_DIR)           // plugins/ sits directly in <cfg>
     const raw = await fs.readFile(path.join(cfg, "excludes.json"), "utf8")
     const entries = (JSON.parse(raw).excludes) || []
     const here = norm(cwd || process.cwd())
+    const main = await mainWorktreeOf(cwd || process.cwd())
+    const heres = main ? [here, norm(main)] : [here]
     for (const e of entries) {
       const p = typeof e === "string" ? e : e && e.path
       if (typeof p !== "string" || !p.trim()) continue
       const base = norm(p.trim()).replace(/[\\/]+$/, "")
-      if (here === base || here.startsWith(base + path.sep)) return true
+      if (heres.some((h) => h === base || h.startsWith(base + path.sep))) return true
     }
   } catch { /* degrade to active */ }
   return false

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.)
 //
@@ -67,17 +67,41 @@ const norm = (p) => {
   }
   return process.platform === "win32" ? s.toLowerCase() : s
 }
+// A linked git worktree of an excluded repo is excluded too, wherever it sits on disk — twin of
+// js/hosts/gitref.mjs `mainWorktreeOf`: the worktree's `.git` FILE names its gitdir, whose
+// `commondir` names the shared `.git`; that directory's parent is the main worktree. null for
+// a main worktree, a submodule, a bare repo's worktree, or anything malformed.
+async function mainWorktreeOf(dir) {
+  try {
+    let root = path.resolve(dir)
+    for (;;) {
+      try { await fs.stat(path.join(root, ".git")); break } catch { /* walk up */ }
+      const up = path.dirname(root)
+      if (up === root) return null
+      root = up
+    }
+    const dotgit = path.join(root, ".git")
+    if (!(await fs.stat(dotgit)).isFile()) return null
+    const m = /^gitdir:\s*(.+?)\s*$/m.exec(await fs.readFile(dotgit, "utf8"))
+    if (!m) return null
+    const gitdir = path.resolve(root, m[1])
+    const common = path.resolve(gitdir, (await fs.readFile(path.join(gitdir, "commondir"), "utf8")).trim())
+    return path.basename(common) === ".git" ? path.dirname(common) : null
+  } catch { return null }
+}
 async function sovereignBypass(cwd) {
   try {
     const cfg = path.dirname(PLUGIN_DIR)           // plugins/ sits directly in <cfg>
     const raw = await fs.readFile(path.join(cfg, "excludes.json"), "utf8")
     const entries = (JSON.parse(raw).excludes) || []
     const here = norm(cwd || process.cwd())
+    const main = await mainWorktreeOf(cwd || process.cwd())
+    const heres = main ? [here, norm(main)] : [here]
     for (const e of entries) {
       const p = typeof e === "string" ? e : e && e.path
       if (typeof p !== "string" || !p.trim()) continue
       const base = norm(p.trim()).replace(/[\\/]+$/, "")
-      if (here === base || here.startsWith(base + path.sep)) return true
+      if (heres.some((h) => h === base || h.startsWith(base + path.sep))) return true
     }
   } catch { /* degrade to active */ }
   return false
@@ -101,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.
@@ -228,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")
@@ -272,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) {
@@ -312,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(", ")}`)
   }
 }
 
@@ -371,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)" } })
@@ -505,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/exclusions.md

@@ -42,6 +42,8 @@ What "dormant" means per host:
 
 `geneseed exclude remove` undoes all of it.
 
+**Git worktrees.** A linked worktree of an excluded repo (`git worktree add`) is excluded too, wherever it sits on disk: the hooks and plugins follow its `.git` file back to the main repository. The global `CLAUDE.md` is the exception on Claude Code and OpenClaude: `settings.local.json` is gitignored, so a worktree never gets it. Geneseed writes no tracked file in a repo you told it to leave alone, so `exclude add` and `exclude list` print the snippet to commit yourself in the repo's tracked `.claude/settings.json` (`.openclaude/` for OpenClaude): `"claudeMdExcludes": ["<path to the global CLAUDE.md>"]`.
+
 **Limits.** Globally installed skills and agents stay *listed* by the host — no host offers a per-repo switch for them. And a global install created *after* you added exclusions starts with an empty list: run `geneseed exclude add` again (`geneseed exclude list` flags installs whose lists differ).
 
 The web console has the same controls in the **Excluded folders** card on the Harness page, shown once a global install exists.

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/concepts/host-matrix.md

@@ -19,7 +19,7 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
 | Consent before every commit and push | 🔒 permission ask | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
 | Rule-or-memory write needs your call | ⚙️ speed bump³ | 🪝 ask | 🪝 warning¹ | 🪝 ask² |
 | User-only skills hidden from the model | 🔒 `permission.skill` deny | ✅ `disable-model-invocation` | ✅ `/`-command, no skill | ✅ `disable-model-invocation` |
-| Sovereign-repo exclusions | ⚙️ plugins stand down | ✅ `claudeMdExcludes` | ✅ rules shadow stub | ✅ `claudeMdExcludes` |
+| Sovereign-repo exclusions⁵ | ⚙️ plugins stand down | ✅ `claudeMdExcludes` | ✅ rules shadow stub | ✅ `claudeMdExcludes` |
 | MCP server wiring | ✅ `mcp` | ✅ `mcpServers` | ✅ `mcp.json` | ✅ `mcpServers` |
 | Colour themes · LSP · workflow runner · primary agent · `/`-commands | ✅ | ➖ | ➖ | ➖ |
 
@@ -29,6 +29,7 @@ Every [host](hosts.md) gets the same content. This table is what each one lets G
 ² **OpenClaude** is a Claude Code fork and gets Claude's hooks and verdicts verbatim, in `~/.openclaude/settings.json` (global) or `.openclaude/settings.local.json` (per repo). **Unverified live** for the same reason.
 ³ OpenCode's plugin hook can only allow or throw — there is no "ask the user" — so this check stops the first such write once rather than prompting.
 ⁴ The checks differ in shape: OpenCode's guard plugin blocks writes *to* private-key and credential files by path; the Claude-shaped hook looks at the *content* being written for credential-shaped strings (cloud keys, tokens, private-key blocks) and asks. A `.env` file is exempt on the hook side — that is where a secret is allowed to live.
+⁵ A linked git worktree of an excluded repo is excluded too: the hooks and plugins follow its `.git` file back to the main repository. `claudeMdExcludes` is the exception — it lives in the gitignored `settings.local.json`, which a worktree never gets — so `geneseed exclude add` and `exclude list` print the snippet to commit yourself. See [Exclusions](exclusions.md).
 
 ## The one conditional row
 

package/docs/reference/opencode-plugins.md

@@ -35,4 +35,4 @@ If a plugin seems silent on OpenCode 2, check that `~/.config/opencode/plugins/`
 
 ## Excluded folders
 
-`geneseed-context`, `geneseed-guard` and `geneseed-learn` go dormant inside a folder listed in the global install's `excludes.json` (managed by `geneseed exclude`). See [Exclusions](../concepts/exclusions.md).
+`geneseed-context`, `geneseed-guard` and `geneseed-learn` go dormant inside a folder listed in the global install's `excludes.json` (managed by `geneseed exclude`), and inside any linked git worktree of such a folder. See [Exclusions](../concepts/exclusions.md).

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.
 
 ---