brain-core

brain-core

A memory for your Claude Code agent that survives the session. One local MCP server, five tools, a markdown vault you can read, an eval that proves recall. Installs with one command.

brain-core gives a Claude Code agent a long-term memory that lives on your disk. You name the agent, you tell it who you are, and from then on every session opens with yesterday's brief, the decisions you made, the facts that changed and the corrections you gave. It remembers by writing markdown files you can open in any editor, and it finds things again through a local SQLite index plus Hindsight, a self-hosted vector memory. Nothing leaves your machine except the LLM calls you already make.

It is for one person running one or more agents on their own computer: a solo developer, a founder, anyone tired of re-explaining their project every morning. It is not a hosted service and not a team product.

Is it an MCP server or a tool?

Both. One Python package, three ways in:

To a Claude Code user: an MCP server with five memory tools and a one-line installer. To a Python developer: a memory library with an MCP front end.

curl -fsSL https://raw.githubusercontent.com/xy-claude/brain-core/main/install.sh | bash -s -- --agent Atlas --user Alex

---

The problem

Every session with a coding agent starts from zero. You explain the project again, the decision you made last week again, the thing it got wrong on Tuesday again. Memory add-ons exist, but they put your notes in someone's cloud, expose 30 tools the agent cannot choose between, and nobody shows you an eval.

brain-core is the opposite: local, five tools, markdown files you own, and a test suite that reports hit rates.

How it works

1. `brain init` scaffolds an agent folder. It writes a CLAUDE.md with the agent's name and yours, five rule files (identity, doctrine, authority, memory, system), three skills, a safety hook, an .mcp.json and an empty vault. Claude Code reads that folder as a project, so the agent knows how to use its memory from the first message.
2. `brain serve` runs as an MCP server inside Claude Code. It exposes exactly five tools. The agent calls them the way it calls any other tool; you never run them by hand.
3. Every session has a shape. The agent opens with brain_session('start'), which returns one block: today's brief, the executive state, the mental models, a recall per active mission, and a flag if the previous session crashed. It closes with brain_session('end'), which files the day's archive and rewrites state for tomorrow.
4. Memory is written, not inferred. When you say something worth keeping, the agent calls brain_remember(text, kind). The text goes to the vault first, then the SQLite index, then Hindsight, then the relations table, and the reply says what each layer did. A duplicate is skipped. A fact whose value changed gets a ⚠ Fact changed banner and the old line stays, so the history is visible.
5. Recall is one query across every store. brain_recall(query) searches the vault, the index and Hindsight at once, deduplicates, ranks by relevance and recency, and caps the reply at 6k tokens so it never floods the context.
6. Two cron jobs do the housekeeping. brain daily writes the next morning's brief and backs up Hindsight. brain weekly archives sessions older than 30 days into a monthly summary and refreshes the mental models.

flowchart LR

CC[Claude Code] -->|MCP, 5 tools| B[brain serve] B --> V[(vault/ markdown)] B --> S[(brain.db SQLite + FTS)] B --> H[(Hindsight vector memory)] B --> G[(relations table)] CRON[brain daily / weekly] --> V CRON --> H

The five tools

Plus brain_status() for health in one call: which stores are up, how many tokens the always-loaded context costs, whether a session is open, and which decisions are waiting on you.

Install

Before you start

Pick two names before you run the command: the agent's name (--agent), which becomes its folder and identity, and your own (--user), which is how the agent addresses you. Both can be changed later by editing CLAUDE.md.

macOS, one line

curl -fsSL https://raw.githubusercontent.com/xy-claude/brain-core/main/install.sh | bash -s -- --agent Atlas --user Alex

In a hurry, or no 2 GB to spare? Add --lite: vault plus SQLite full-text search, no Hindsight, installed in about a minute. Everything in the five tools works; what you give up is semantic recall over paraphrases, mental models and the weekly reflection. The recall numbers in Does it work? are measured on exactly this configuration. Upgrade any time with brain hindsight install, then uncomment the hindsight: block in brain.yaml.

curl -fsSL https://raw.githubusercontent.com/xy-claude/brain-core/main/install.sh | bash -s -- --agent Atlas --user Alex --lite

What it does, in order. Re-running skips what is already there, so after a failure you fix the cause and run the same line again.

== 1/8 Xcode command line tools      present

== 2/8 Homebrew present == 3/8 uv, gh, gitleaks, node, Claude Code == 4/8 brain-core (v0.4.0) installed with uv tool == 5/8 Agent Atlas at ~/Agents/Atlas 31 files written == 6/8 Hindsight (required store) service: healthy == 7/8 Cron daily 06:07, weekly Sun 07:13 == 8/8 Doctor Health check: OK

After the installer

Two things the installer cannot do for you:

export ANTHROPIC_API_KEY=sk-ant-...     # add it to ~/.zshrc too

brain hindsight install # copies the key into ~/.config/hindsight/env (mode 600) and restarts the service claude # sign in to Claude Code once

The installer prints a note if the key was not in your shell when it ran. If you would rather not use an API key, pass --provider claude-code and Hindsight uses your Claude Code login instead. That mode is for personal use only.

Already have an agent?

brain adopt ~/Agents/Atlas --vault ~/Agents/Atlas/vault --bank atlas-brain --user Alex

Adds brain.yaml, the brain MCP server, the four hooks and the memory rule to an existing Claude Code folder, then indexes its facts. CLAUDE.md, skills and the vault are left alone; omit --bank to run lite.

Linux

The same one line. It needs git and curl already present. It then installs uv from astral.sh, installs Claude Code with npm when node is present, runs Hindsight as a systemd --user service, and writes the two jobs into your user crontab as tagged lines it can find and replace on re-run.

Manual, any platform

uv tool install brain-core-mcp   # or: uv tool install git+https://github.com/xy-claude/brain-core@v0.4.0

brain init Atlas --path ~/Agents/Atlas --user Alex brain hindsight install # launchd on macOS, systemd --user on Linux brain cron install ~/Agents/Atlas brain doctor ~/Agents/Atlas

Check it worked

brain doctor ~/Agents/Atlas

It prints the agent name, the config path, row counts per table, and Health check: OK. Store health shows up in the first brain_session('start') reply and in brain_status(). The common problems:

| hindsight unreachable at http://127.0.0.1:8888 | the service i