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.
Project: Open Second Brain
A local-first memory layer for coding agents: a Bun and TypeScript CLI
(o2b), an MCP server, agent plugins (Claude Code, Codex, Hermes,
OpenClaw) and skills. CLAUDE.md and AGENTS.md at the repository root
are the map of versioning, plugin mirrors and gates; read them before any
change.
This openspec/ directory is committed with the code. Changes use the
project schema osb (openspec/schemas/osb/): brainstorm with an
independent agent, proposal, specs, design, tasks, independent review of
the artifacts, then apply. tasks.md is a self-contained brief for the
agent that implements the change, which may be a different agent than
the author; implementation starts only on the review's "Ready for
implementation: yes". Each change maps to one pull request. Before the
pull request of a change is pushed, the change is archived (openspec archive <change> --yes) and the archive and
the updated openspec/specs/ ship in that pull request, so
openspec/specs/ always describes main. The multi-phase change
brain-store-and-topics predates these rules: it keeps the schema it was
written with and is archived once all its phases are released; its
remaining tasks move into changes of their own.
Conventions that apply to every change here:
- English only in code, docs, comments and commit messages. No exclamation marks in docs. The product is written "Open Second Brain" in full, never abbreviated, in anything public.
- Test first: write the failing test, run it and see it fail, then the code. A test proves behaviour through public seams; no test-only production seams beyond the existing hook patterns.
- Never read or write the real user state in tests: not
~/.config/open-second-brain/config.yaml, not~/vault, not the real~/.local/state/open-second-brain. Tests get temp directories (the preload intests/isolates the state dirs). - No personal settings in the repository: no machine paths, host names, model preferences or account names in code, docs, examples or tests.
- Every path must work on Linux, macOS and Windows (path separators, locks, fsync, case folding). CI runs the suite on Windows.
- Source files stay under 700 lines; split a module before it grows past that.
- Version bumps:
package.jsononly, thenbun run scripts/sync-version.ts, inside the pull request that ships the release (seeCLAUDE.md). - After changing a skill or
hooks/hooks.json, runbun run sync-plugin-mirrors; never edit the mirrored copies.
The local gate, run before a change is called done:
bun run test
bunx tsc --noEmit -p .
bun run lint
bun run fmt:check
bun run check:paths
bun run sync-plugin-mirrors:check
bun run scripts/sync-version.ts --check
When src/ code that the OpenClaw bundle includes changes, rebuild it with
bunx [email protected] run build:openclaw (the Bun version CI pins) and commit openclaw/index.js.