Central Brain

Persistent, goal-oriented memory and work ledger for Claude Code.

Claude sessions forget everything when they end. Central Brain gives them one durable memory that every session, in every project, reads and writes:

• Goals, not tasks. Each piece of work is a goal with a locked contract: objective, scope, constraints and success criteria.

• Evidence, not claims. A goal completes only when each criterion has verified evidence and the converge report is clean.

• Memory that compounds. Decisions, failures and their fixes, learnings and project knowledge are stored, searched and reused.

It is a local SQLite database (~/.central-brain/brain.db) with a CLI, an MCP server for Claude Code, and session hooks that inject context automatically. There are no external services: search is hybrid full-text plus local ONNX embeddings.

The full design is in ARCHITECTURE.md, and the agent operating rules are in CLAUDE.md.

Quickstart

Requirements: Node.js 20+, Claude Code, and jq and sqlite3 on PATH (used by the prompt hook).

git clone https://github.com/localhost-anon/central-brain.git ~/Projects/central-brain
cd ~/Projects/central-brain
npm install
npm run build
npm link            # optional: puts `brain` on your PATH
brain init          # creates ~/.central-brain/brain.db and applies migrations

The hook scripts assume the repo lives at ~/Projects/central-brain. If you clone it somewhere else, edit the paths in hooks/ and bin/brain-claude.

Register the MCP server so Claude Code can call the brain_* tools in every project:

claude mcp add --scope user central-brain -- node ~/Projects/central-brain/dist/mcp/server.js

Wire the hooks in ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart":     [{ "hooks": [{ "type": "command", "command": "~/Projects/central-brain/hooks/session-start.sh" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "~/Projects/central-brain/hooks/user-prompt.sh" }] }],
    "Stop":             [{ "hooks": [{ "type": "command", "command": "~/Projects/central-brain/hooks/stop.sh" }] }],
    "PreCompact":       [{ "hooks": [{ "type": "command", "command": "~/Projects/central-brain/hooks/stop.sh" }] }]
  }
}

Optionally, register your projects with brain project scan ~/Projects, and run brain embed reindex to enable semantic search. The first run downloads a small embedding model to ~/.central-brain/models.

Related MCP server: waypath

How a goal flows

create → intake → lock → plan (work units) → start → work → verify → converge → complete

1. Create. Run brain goal create "<title>" -o "<objective>".

2. Intake. Run brain goal intake <id>. It surfaces related memory and contract gaps, and asks two standing questions:

   • review:behaviour: which user-visible choices does this involve?

   • review:coverage: which areas still need contract lines? The areas are behaviour, data, failure modes, edge cases, non-functional, integration and completion.

   Sessions may add at most 5 material questions of their own, each with a recommended answer. Ask them in one batch.

3. Lock. Run brain goal lock <id>. Lock refuses unless:

   • the contract is complete;

   • every required success criterion states one claim and has a verify method (test | command | api | inspection | manual);

   • every applicable principle is acknowledged (see Principles below).

4. Plan and start. Create work units with --serves <criterion ids>. brain goal start refuses while any required criterion has no work unit serving it.

5. Verify. For each criterion, run brain verify add … --verdict verified|partial|failed with the real observed output. partial never counts as passing, and a verified verdict needs actual output plus a verification type that matches the criterion's verify method.

6. Converge. Run brain goal converge <id>. It lists typed findings:

   • missing, partial or contradicting evidence;

   • stale evidence (recorded before later work finished);

   • unfinished work;

   • open failures;

   • uncovered criteria.

   Fix them until it reports converged.

7. Complete. brain goal complete <id> refuses while CRITICAL or HIGH findings remain. --force needs --reason; the reason is recorded as a decision and the goal is permanently marked as force-completed. A goal that was never locked cannot complete without force.

Failures resolve only with a solution that has --verdict verified and a --reproduction note saying how the original symptom was re-checked. Passing tests alone count as partial.

Principles are durable rules stored as knowledge with category principle, scoped either GLOBAL or to a project (for example "sandbox first"). Link a goal to its project with brain goal link-project. Then acknowledge each principle with brain principle ack, either as honoured or as an exception with a reason; an exception is recorded as a decision.

Rules versions. Goals locked before these rules shipped stay on rules_version 0 and keep the original, simpler completion check. Every goal locked afterwards gets rules_version 1.

Staleness. Open goals with no activity for BRAIN_STALE_DAYS (default 7) are skipped by brain goal current and listed at session start. Close them with goal complete, or retire them with brain goal cancel <id> <reason>.

Command reference

brain <group> --help shows every option. Every command prints JSON.

The MCP server exposes the same operations as brain_* tools. Examples include brain_goal_intake, brain_goal_converge, brain_principle_ack and brain_failure_solution_add. Their descriptions carry the rules above, so sessions learn them from the tool list.

Data and safety

• Location. The database is at ~/.central-brain/brain.db. Override it with BRAIN_DB. The database never lives in the repo.

• No secrets. Do not store secrets in Brain. Reference environment variable or credential names instead.

• No auto-migration. Sessions never migrate the live database. After pulling schema changes, run brain migrate, which snapshots first. Until then, context get returns a "schema update pending" notice.

• Check migrations on a copy. npx tsx scripts/check-migration-on-copy.ts migrates a copy of your database and confirms all goals are unchanged.

Development

npm test            # vitest (in-memory and temp-file databases only)
npx tsc --noEmit    # type check
npm run build       # compile to dist/
npm run db:generate # generate a drizzle migration after editing src/db/schema.ts

The code is organised as follows:

• src/services/: one module per concern.

• src/services/contract-rules.ts: every gate rule, as pure functions.

• src/cli/ and src/mcp/: thin wrappers over the services.

• drizzle/: migrations. They must be additive.

Contributing

main is protected. All changes, including the owner's, go through a pull request, and every PR needs the code owner's approval before it merges. Open a branch, keep npm test and npx tsc --noEmit green, and describe the outcome in the PR.

License

MIT