geneseed 4.3.0 → 4.4.0

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

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/gitref.mjs

@@ -6,7 +6,7 @@
  * launched-loop evidence reader were duplicated in `js/hosts/hooks.mjs` (the hook's
  * `loopExempt`) and `js/loop/cli.mjs` (the CLI's commit-message writer) — two copies of the
  * same worktree-following walk that could silently drift apart. Both now import this one.
- * `js/hosts/hooks.mjs` is NOT a safe shared home for it: it pulls in `node:child_process`
+ * `js/hosts/hooks.mjs` is NOT a safe shared home for it: it pulls in `child_process`
  * (`spawnSync`, for the destructive-act guard's own concerns) and the hook-dispatch
  * machinery (`jsonDumpsCompact`, the ledger), none of which `js/loop/cli.mjs` — under a hard
  * `child_process` ban like every other closure that feeds `bin/geneseed-cli.mjs` — may ever
@@ -54,6 +54,30 @@ export function gitDirOf(root) {
   return dotgit;
 }
 
+/**
+ * The MAIN worktree's root when `cwd` stands in a LINKED worktree (`git worktree add`), else
+ * null — a main worktree, a submodule (its gitdir has no `commondir`), a bare repository's
+ * worktree, no repo, or a malformed link. Never throws.
+ *
+ * WHY: a linked worktree can live anywhere on disk (Orca puts them under its own workspaces
+ * folder), so a path-prefix test against the repo the user EXCLUDED never matches it, and the
+ * global harness woke up inside a sovereign repo's worktree. The worktree's `.git` FILE names
+ * `<common>/.git/worktrees/<n>`, whose `commondir` (relative to it, usually `../..`) names the
+ * shared `.git`; that directory's parent is the main worktree. Read off disk, never by
+ * spawning git: `sovereignBypass` runs on every hook call and feeds the CLI's `child_process` ban.
+ */
+export function mainWorktreeOf(cwd) {
+  try {
+    const root = gitRootOf(cwd);
+    if (!root || !statSync(path.join(root, '.git')).isFile()) return null;
+    const gitdir = gitDirOf(root);
+    const common = path.resolve(gitdir, readFileSync(path.join(gitdir, 'commondir'), 'utf8').trim());
+    return path.basename(common) === '.git' ? path.dirname(common) : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The branch checked out in `cwd`, read from .git/HEAD without spawning git. null on
  * anything unexpected (detached HEAD, no repo, a malformed worktree link, unreadable) — the

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/hosts.mjs

@@ -19,6 +19,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { printErr, withDiscardableStderr, isDir, isFile, readText } from '../lib/fs.mjs';
 import { toPlatformPath, normcase } from '../lib/paths.mjs';
+import { mainWorktreeOf } from './gitref.mjs';
 
 /** `_build_global.GLOBAL_MANIFEST` — the file whose presence means "a global install". */
 export const GLOBAL_MANIFEST = '.geneseed-manifest.json';
@@ -39,6 +40,11 @@ export const GATE_LEDGER = path.join('notebook', 'gates.jsonl');
  * under the transitive `child_process` ban that `hooks.mjs`'s `learn` verb breaks). A
  * second copy in `js/inspect/` was the alternative, and a copy is what let the `~user`
  * refusal diverge between the two CLIs once already (see `hooks.mjs`'s header).
+ *
+ * A LINKED GIT WORKTREE OF AN EXCLUDED REPO IS EXCLUDED TOO, wherever it sits on disk: the
+ * cwd matches, or the main worktree `mainWorktreeOf` reads off the `.git` file does. An
+ * exclusion names a repository the user keeps sovereign, not a folder; a worktree elsewhere
+ * (Orca's workspaces) otherwise woke the full global harness inside it.
  */
 export function sovereignBypass(root) {
   if (!root) return false;
@@ -49,12 +55,16 @@ export function sovereignBypass(root) {
   } catch {
     return false;
   }
-  let cwd;
+  let heres;
   try {
-    cwd = normcase(resolvePath(process.cwd()));
+    heres = [normcase(resolvePath(process.cwd()))];
   } catch {
     return false;
   }
+  try {
+    const main = mainWorktreeOf(process.cwd());
+    if (main) heres.push(normcase(resolvePath(main)));
+  } catch { /* an unresolvable main worktree degrades to the cwd test alone */ }
   for (const entry of entries) {
     const raw = (entry && typeof entry === 'object' ? entry.path : entry) || '';
     if (typeof raw !== 'string' || !raw.trim()) continue;
@@ -67,7 +77,7 @@ export function sovereignBypass(root) {
       // and this caller catches: the reference prints nothing here, so replaying the
       // message would be a stderr divergence on every hook call for one bad entry.
       //
-      // `resolvePath`, the same resolution as `cwd` above: symlinks and junctions are followed on
+      // `resolvePath`, the same resolution as `heres` above: symlinks and junctions are followed on
       // BOTH sides, so an entry spelled through a link matches the real directory the session
       // stands in (and the OpenCode plugins' `norm` applies the identical rule).
       base = withDiscardableStderr(
@@ -79,7 +89,7 @@ export function sovereignBypass(root) {
       // Skipping errs toward the gate staying ACTIVE, which is the safe direction.
       continue;
     }
-    if (cwd === base || cwd.startsWith(base + path.sep)) return true;
+    if (heres.some((h) => h === base || h.startsWith(base + path.sep))) return true;
   }
   return false;
 }