Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
SOLID/DRY refactor - decompose god modules and unify duplicated helpers
Status: draft Author: claude-dev-agent (via feature-release-playbook) Audience: implementation
Problem statement
The codebase has grown to ~500 TypeScript files and ~95k lines through 20+ feature suites, and several hotspots now violate single-responsibility and DRY principles. src/mcp/brain-tools.ts is a 5614-line god module holding 52 tool handlers across 13+ domains while its siblings follow a per-domain split. Eighty-nine CLI verb files repeat the same context-resolution and error-handling boilerplate. Atomic file writes, wikilink parsing, YAML config parsing, and dream sub-phases each exist in duplicated or entangled form. Nothing enforces the layering rule that core modules never talk to the process directly.
Scope
- Split
src/mcp/brain-tools.tsinto per-domain tool modules;brain-tools.tsremains only as the aggregation point exportingBRAIN_TOOLS(the registration seam thattools.tsand tests already import - not a compatibility shim). - Add
withBrainCommandcontext wrapper insrc/cli/brain/and migrate the verb files onto it, deleting the repeated vault/config/try-catch boilerplate. - Unify atomic writes on
src/core/reliability/atomic.ts(the richer API); migratefs-atomic.tscall sites and delete the duplicate implementation. - Create one canonical wikilink module; migrate all seven regex sites onto named, purpose-documented variants. Characterization tests pin current behavior per site before migration.
- Extract the YAML subset parser out of
policy.ts; extract evidence-refresh and reconcile-outcomes out ofdream.tswith explicit input/output interfaces. - Delete
scripts/sync-version.py; add a layering-guard test that scanssrc/coreforprocess.exit/process.stdout/console.*usage.
Out of scope
- Any behavior, output-format, or public-surface change (v1.0.0 froze MCP tool names, CLI verbs, file formats).
- Registry/manifest-driven command frameworks (consultant variant 3) - rejected as scope creep.
- ISO-8601 regex consolidation in
log-jsonl.ts/truth/store.ts- the in-code comments document that writer/reader pairs intentionally do not share constants; respected as-is. .toISOString()toisoSecond()codemod - would change stored timestamp precision; not a pure refactor.- New external dependencies.
Chosen approach
Consultant variant 2: canonical modules with direct call-site migration. For every duplication pick one winning implementation, migrate all call sites in the same commit, and delete the loser. No alias re-export shims; the only surviving indirection is brain-tools.ts as the existing aggregation seam. Each unit is one conventional commit with the full suite green, so units stay independently revertable.
Design decisions
- brain-tools.ts stays as aggregator, not shim:
tools.tsand six test files importBRAIN_TOOLSfrom it; keeping that one seam gives a zero-churn registration point and matches howALL_TOOLSalready concatenates domain arrays. - Domain split by tool cohesion, ~13 modules: feedback/dream writes, review lifecycle, context packing, queries, health, briefs, analytics, entities, knowledge graph, admin, recall/benchmark, procedural, landscape - mirrors the dispatcher groups already present inside the file. A parity test asserts the before/after tool-name set is identical.
reliability/atomic.tswins overfs-atomic.ts: it is the newer API with the validate hook and configurable mode; the exclusive-create primitive fromfs-atomic.tsmoves into it so one module owns temp-file naming + fsync + rename.- Wikilink variants are named, not merged into one regex: the seven sites have three genuinely different contracts (quoted/heading-aware, strict no-newline, alias-capturing). Forcing one regex would change behavior; instead one module exports documented named variants and the two exact duplicates collapse.
- Wrapper does not own flag schemas:
withBrainCommandresolves context (vault, config, json mode) and uniform error formatting only; each verb keeps its ownparse()schema so output strings and exit codes stay byte-identical. - Layering guard is a bun test, not an AST walk: a source scan over
src/core/**forprocess.exit/process.stdout/console.with an explicit allowlist is sufficient, dependency-free, and runs in the normal test suite.
File changes
New files:
src/mcp/brain/domain modules (~13 files) plus shared helpers module for coercion/serialization used by several domains.src/cli/brain/command.ts-withBrainCommandwrapper andCommandContexttype.src/core/brain/wikilink.ts- existing helper module extended with the named regex variants (chosen over a new file: search and core layers already import brain modules, and a secondwikilink.tswould recreate the twin-module problem).src/core/brain/yaml-parse.ts- YAML subset parser moved frompolicy.ts.src/core/brain/dream-refresh.ts,src/core/brain/reconcile-outcomes.ts- extracted fromdream.ts.tests/core/layering.test.ts- layering guard.- Characterization/unit tests for wikilink variants, atomic write paths, extracted modules, tool-set parity.
Modified files:
src/mcp/brain-tools.ts(becomes aggregator),src/mcp/tools.ts(unchanged imports, verify only).src/cli/brain/verbs/*.ts(~89 files migrate to wrapper).src/core/reliability/atomic.ts(absorbs exclusive create), allfs-atomic.tsimporters.src/core/vault.ts,lint-consolidate.ts,link-graph/parse-wikilink.ts,link-graph/format-wikilink.ts,search/links.ts,search/entities.ts,search/query-plan.ts(wikilink imports).src/core/brain/policy.ts,src/core/brain/dream.ts(shrink via extraction).
Deleted files:
src/core/fs-atomic.ts,scripts/sync-version.py.
Risks and open questions
- Wikilink unification could surface latent edge-case differences - mitigated by writing characterization tests against the current behavior of each site before touching imports.
- CLI wrapper migration touches ~89 files in one commit - mitigated by keeping the wrapper minimal (context + catch) and relying on the existing CLI tests that assert output strings and exit codes.
- openclaw bundle (
openclaw/index.js) is a committed build artifact - must be rebuilt viabun run build:openclawif anything it bundles changes, and verified in QA. - plugins/hermes and hooks/ may import moved symbols - grep before each move; anything externally imported keeps its export path through the canonical module.