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.
Brain-centric vault layout - one root, configurable user notes, no legacy siblings
Status: draft Author: @claude-vps-agent (via feature-release-playbook) Audience: implementation
Problem statement
The vault currently has three top-level agent-relevant directories (Brain/, AI Wiki/, Daily/) inherited from successive design iterations. Only Brain/ carries its weight; the other two are vestigial:
AI Wiki/is empty scaffolding for most installations:index.md,hot.md,log.md,identity/user.md,identity/agents.md,_OPEN_SECOND_BRAIN.md,_open-second-brain.yaml. None of these are read or written by any current agent surface; they are leftovers from a v0.1-v0.5 "vault as curated knowledge base" idea that Brain replaced. The only live consumer is Pay Memory (which writes underAI Wiki/payments/,AI Wiki/policies/, ...) - and that placement is a historical accident, not a design choice.Daily/is hardcoded intosrc/core/event-log.ts(writesDaily/<date>.md), into the OPEN_SECOND_BRAIN operating manual template ("chronological event log and human narrative"), and is referenced in five other files as a special case to exclude. The nameDaily/is a user choice - everyone names their daily-notes folder differently or skips it entirely. Hardcoding the name into the agent's write paths violates that.
Concrete pain:
- The README and
docs/how-it-works.mdhave to apologise for three top-level directories where two of them do nothing. - The agent's write contract is unclear: which legacy paths can it touch? The current answer ("Brain/ only - but
event_log_appendstill writesDaily/<date>.md") is contradictory. - Pay Memory sits under
AI Wiki/for no reason other than "that was the only sibling directory at the time". Operators looking for receipts underBrain/find nothing.
Scope
One named subsystem migration, one breaking release (v0.11.0):
- Pay Memory relocation from
AI Wiki/{payments,policies,assets,drafts,reports,_pending}/toBrain/payments/{policies,assets,drafts,reports,_pending}/plus the dated receipt subdirs (YYYY-MM-DD/). - AI Wiki/ removal:
o2b initno longer scaffolds it; existing templates (_OPEN_SECOND_BRAIN.md,_open-second-brain.yaml,index.md,hot.md,log.md,identity/*) retire. The operating manual content folds intoBrain/_BRAIN.md(already present). - Daily/ de-hardcoding: the legacy
event_log_appendwrite path (appendEventinevent-log.tsthat createsDaily/<date>.md) is removed entirely. The CLI verbo2b append-eventretires (its replacemento2b brain notealready ships and writes toBrain/log/<today>.md). User-side daily notes - whatever the operator names them - become configurable read-only inputs. notes.read_pathsconfig: new optional block in_brain.yaml:notes: read_paths: - "Daily" # operator chooses any path or names - "Journal" # omit the block entirely if you do not keep daily noteso2b brain scan-inlineando2b brain import-sessionhonour the list; default is empty (no scanning). Agents never write to these paths - the type isread_pathsfor a reason.- Doctor / manifest cleanup: remove every special-case mention of
AI Wiki/andDaily/. Brain ownsBrain/; nothing else is special.doctor's vault-scope walker usesvault.ignore_paths(existing config) as the only exclusion mechanism. - Migration:
o2b brain upgrade(already exists for similar tasks) gains a migration step that detects an existingAI Wiki/payments/tree and moves it underBrain/payments/. The legacy AI Wiki/ root is left in place if the operator put their own notes there - only Open-Second-Brain-managed files are removed.
Out of scope
- Replacing
o2b brain note(already the right tool; nothing to change). - Changing the Brain/ subdirectory layout itself (
inbox/,preferences/,retired/,log/,.snapshots/stay byte-identical). - Replacing
Brain/_BRAIN.md(already the operating manual; no rename). - Building a generic vault folder taxonomy or a multi-folder MOC system; the user can do whatever they like outside Brain/.
- Removing
second_brain_query(read-only vault page lister) - it serves a real purpose and is not coupled to AI Wiki/.
Chosen approach
A single layered refactor across one PR. The atom layer is src/core/pay-memory/paths.ts plus the new BrainNotesConfig type. The hub is src/core/init.ts (vault bootstrap) and _brain.yaml schema. The helpers are scan-inline, import-session, doctor, manifest. The migration is one new pass in src/core/brain/upgrade.ts.
No new abstractions: the existing BrainConfig already carries optional sub-blocks (temporal:, link_graph:, discipline_report:); notes: is one more. Pay Memory's paths.ts swaps a string constant. Migration is a deterministic file-mover plus a sidecar manifest entry so re-running is a no-op.
Design decisions
- Pay Memory under
Brain/payments/, not its own root. Brain is the agent-writable area; Pay Memory writes (receipts, asset notes, reports). Putting them underBrain/makes the write contract trivial: "the agent writes only under Brain/". A separatePayments/root would re-introduce the same "many top-level dirs" problem this refactor is solving. - No
notes.write_pathsfield. The type carries the rule. If a future feature genuinely needs the agent to write to user-facing notes (brain_capturerebirth?), it is a separate design conversation, not a hidden expansion of this config. notes.read_pathsdefaults to empty, not to["Daily"]. Hardcoding a default would silently re-introduce the same hardcoded path. Empty default means new vaults opt in.event_log_appendandappendEventare removed, not deprecated-with-shim. Both have replacements that ship for years (brain_noteMCP tool,o2b brain noteCLI). A shim that writesDaily/<date>.md"for backward compatibility" would be a crutch and contradict the rule that the agent does not write to user-named notes.- AI Wiki/ removal is irreversible for new vaults but non-destructive for old ones.
o2b initno longer creates AI Wiki/ at all.o2b brain upgrademoves only OSB-managed files out of an existing AI Wiki/, leaves the empty directory or any user-authored content alone. Operators reading the migration log see exactly which files moved. Brain/_BRAIN.mdalready exists - no new operating manual file, no rename. The current_OPEN_SECOND_BRAIN.mdtemplate is deleted; its non-overlapping content gets folded intoBrain/_BRAIN.md(one-paragraph headline + pointer to docs).- Doctor's exclusion list shifts to one mechanism. Today
doctorhas an in-code "deliberately do NOT pull in legacy AI Wiki/ or Daily/" comment block. After this refactor, the only exclusion isvault.ignore_paths(a config-driven list). No path is special by name.
File changes
Atoms and config
- Modify:
src/core/brain/types.ts- addBrainNotesConfig { read_paths: ReadonlyArray<string> }and slot it intoBrainConfig.notes?+ResolvedBrainConfig.notes. - Modify:
src/core/brain/policy.ts- addBRAIN_NOTES_DEFAULTS(empty),resolveNotes(cfg), validator (notes.read_pathsis an array of vault-relative non-empty strings; rejects absolute paths and..traversal). - Modify:
src/core/pay-memory/paths.ts- swap"AI Wiki"constant forposix.join("Brain", "payments").
Init / scaffolding
- Modify:
src/core/init.ts- drop the sevenAI Wiki/...template registrations; bootstrap stops atBrain/(already handled byo2b brain init). The CLI verbo2b initnow only writes the profile config +.open-second-brain/index dir. - Delete:
src/core/brain/templates/_OPEN_SECOND_BRAIN.md.tpland_open-second-brain.yaml.tpl(move any unique content intoBrain/_BRAIN.md.tpl). - Modify:
src/core/brain/templates/_BRAIN.md.tpl- removeDaily/andAI Wiki/paragraphs; add a one-line pointer to the configurablenotes.read_pathsblock (with one example name like"Daily"clearly framed as "if you keep daily notes, list their folder here").
Legacy event log removal
- Delete: the
appendEventfunction insrc/core/event-log.ts(writesDaily/<date>.md). The file retains only the redactor + path safety helpers if they are reused elsewhere; otherwise the file goes too. - Delete: the
o2b append-eventCLI verb (src/cli/append-event.tsor equivalent) and its tests. - Modify:
src/cli/main.ts- drop the subcommand registration.
Migration
- Modify:
src/core/brain/upgrade.ts- add a new step: detect<vault>/AI Wiki/payments/,policies/,assets/,drafts/,reports/,_pending/; atomically move each into<vault>/Brain/payments/. Detect and remove the seven OSB-managed scaffolding files; leave anything else underAI Wiki/untouched. Idempotent via sidecarBrain/.upgrade-history.jsonentry. - Modify:
src/core/brain/upgrade.ts- same step removes top-levelDaily/<date>.mdfiles that were authored byappendEvent(detected by a marker comment we wrote at the top). User-authored daily notes are recognised by the absence of that marker and are left alone.
Scan / import
- Modify:
src/core/brain/inline-scan.ts- resolve scan roots fromnotes.read_paths; default to empty (no work to do, no error). - Modify:
src/core/brain/sessions/import.ts- same pattern for the legacy session-import path scanner if it usedDaily/.
Doctor / manifest
- Modify:
src/core/brain/doctor.ts- drop the AI Wiki/ + Daily/ exclusion paragraph; the only exclusion mechanism isvault.ignore_paths. - Modify:
src/core/brain/manifest.ts- same cleanup. - Modify:
src/core/path-safety.ts- the safety helper no longer needs theAI Wiki/allow-list.
MCP
- Modify:
src/mcp/tools.ts- drop theevent_log_appendhistorical comment block; rewrite thesecond_brain_querydescription to remove the AI Wiki framing. - Modify:
src/mcp/instructions.ts- remove AI Wiki / Daily references. - Modify:
src/mcp/brain-tools.ts- drop theDaily/fallback comment inbrain_note's docstring.
Tests
- 24 tests touch
"AI Wiki"or"Daily/". Each one either:- Updates expected paths from
AI Wiki/payments/...toBrain/payments/.... - Drops the test entirely if it covered the deleted
event_log_appendoro2b append-event. - Adds a new test under
tests/core/brain/upgrade-aiwiki-migration.test.tsthat exercises the migration step.
- Updates expected paths from
- New test:
tests/core/brain/notes-config.test.tscovers the config block validator, defaults, and theread_paths-drivenscan-inlineresolution.
Docs
- Modify:
README.md- drop theAI Wiki/andDaily/mentions, including the line aboutBrain/,AI Wiki/,Daily/in the top features table row 1. - Modify:
docs/how-it-works.md- rewrite the vault layout diagram (onlyBrain/+ the derived index dir + an optional user-notes section); rewrite "Capture surfaces" so that "Inline" reads fromnotes.read_pathsand stops namingDaily/. - Modify:
docs/pay-memory.md- swap everyAI Wiki/...path forBrain/payments/.... - Modify:
docs/cli-reference.md- update the Pay Memory verb descriptions and theinit-pay-memorycommand's docstring; dropo2b append-eventfrom the helper section. - Modify:
docs/architecture.md- drop AI Wiki/ and Daily/ from the layer diagram if mentioned. - Modify:
docs/mcp.md- drop AI Wiki/notes/ from thesecond_brain_querydescription; drop the historicalevent_log_appendreferences. - Modify:
install/prerequisites.md- update the "what gets created in your vault" section.
Release
- Modify:
package.json- version0.11.0(breaking change). - Modify:
CHANGELOG.md- one[0.11.0]entry summarising: removed AI Wiki/, removed Daily/ hardcoding, moved Pay Memory to Brain/payments/, removedevent_log_append/o2b append-event, addednotes.read_pathsconfig,o2b brain upgrademigrates existing installations. - Modify: runtime manifests via
bun run sync-version.
Risks and open questions
- Existing operators with custom content under
AI Wiki/. The migration moves only OSB-managed files; anything user-authored stays. Documented in the[0.11.0]CHANGELOG entry and the post-update doctor warning. - Hermes / Claude Code / Codex plugins on older versions might still reference the retired MCP tool names. The MCP server itself drops the registrations; clients that call
event_log_appendorsecond_brain_captureget a clean tool-not-found error, not a silent no-op. The corresponding tool was already removed from the surface in v0.10.8; this PR removes the now-dead historical comments and the internalappendEventfunction it documented. o2b brain upgradeidempotency under partial failure. If the migration crashes mid-move, re-running picks up where it left off via the sidecar manifest. A pre-run snapshot already covers full rollback.- Naming
Brain/payments/vsBrain/pay/. Going withpayments/(more explicit, matches the existing subdir name under AI Wiki/, eases the migration mental model). - Should
notes.read_pathsaccept globs (Daily/*.md)? No. Each entry is a directory; the scanner walks it. Globs add complexity without solving a real need - if the operator wants to exclude files,vault.ignore_pathsalready exists. - Backward compatibility for users still running
o2b append-eventfrom a shell script. The verb is removed; the script breaks loudly with "unknown subcommand". Better than silently writing to a path the agent contract forbids.