Back to Browse

Brain Core MCP Server

Developer ToolsUse Caution4.6MCP RegistryLocal
Free

Server data from the Official MCP Registry

Memory for a Claude Code agent that survives the session: five tools, a markdown vault, all local.

About

Memory for a Claude Code agent that survives the session: five tools, a markdown vault, all local.

Security Report

4.6
Use Caution4.6High Risk

brain-core is a local stdio memory server with five tools, no required API key, and permissions that mostly match its stated purpose. The main concerns are the curl-pipe-to-bash installer, which fetches and runs a remote script that was not included for review, and the server's read access to Claude Code transcripts, which contain sensitive conversation data. The provided code shows no malicious patterns, and the code is truncated in several places so the review is partial. Supply chain analysis found 5 known vulnerabilities in dependencies (0 critical, 5 high severity). Package verification found 1 issue.

4 files analyzed · 13 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

File System Read

Reads files on your machine. Normal for tools that analyze or process local data.

File System Write

Writes or modifies files on your machine. Check that this is expected for the tool.

HTTP Network Access

Connects to external APIs or services over the internet.

database

Check that this permission is expected for this type of plugin.

process_spawn

Check that this permission is expected for this type of plugin.

env_vars

Check that this permission is expected for this type of plugin.

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "brain-core-mcp": {
      "command": "uvx",
      "args": [
        "brain-core-mcp==0.9.1"
      ]
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

CI License: MIT Python 3.12+ Glama score

brain-core

A memory for your Claude Code agent that survives the session.

Install in one line

macOS and Linux

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

Windows (PowerShell)

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/xy-claude/brain-core/main/install.ps1))) -Agent Atlas -User Alex -Desktop

Atlas is your agent's name, Alex is yours. When the installer finishes:

cd ~/Agents/Atlas
claude

Both lines install the same things: the agent, Hindsight (the vector store, about 2 GB), the daily and weekly jobs, Claude Code, and the connection to the Claude desktop app. No API key is needed.

You wantmacOS and LinuxWindows
The quick install: about a minute, no Hindsightadd --liteadd -Lite
Claude Code only, not the desktop appremove --desktopremove -Desktop

Every step, every flag and the common problems: Install details.


What you get

  • Sessions that start where the last one ended. Each one opens with yesterday's brief, your decisions, the facts that changed and the corrections you gave.
  • Five tools, not thirty. One local MCP server the agent uses by itself.
  • Files you can read. Memory is markdown in a folder on your disk, indexed by SQLite and, optionally, by Hindsight, a self-hosted vector memory.
  • Nothing in someone's cloud. Memory stays on your disk. What does go out: the LLM calls Hindsight makes to reason over memories (none with --lite), one version check a day to PyPI, and the pages you ask it to distill.
  • Search you can check. Every result names its file and date, a weak match is reported as weak, and recall is scored against labelled answers (the labels were written by a model and have not yet been checked by a person). The numbers, including the ones that are not flattering, are in Does it work?

It is for one person running one or more agents on their own computer. It is not a hosted service and not a team product.

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 an eval with labelled answers whose numbers are published below.

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, four hooks (a safety block, the brief at session start, capture of what you said, recall of past fixes when a command fails), 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 for each of the top two missions, the inbox count, and a flag if the previous session crashed. In Claude Code a hook has already put the brief in context (at most 3,000 tokens of it), so the block does not repeat it. 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 SQLite, then Hindsight, and a relation also goes to the relations table; the reply says what each layer did. The agent can pass keys, the other words you might ask for that memory by, and they are saved in the vault and indexed beside the text. A duplicate is skipped. A fact whose value changed gets a ⚠ Fact changed banner, the old line stays, and recall ranks the old value below the new one.
  5. Recall is one query, answered from a keyword index. brain_recall(query) searches one SQLite FTS5 index built from every record in the vault and your notes folders. It matches words, word forms, dates written in words, and the search keys saved with each memory, and ranks by bm25 and recency. Hindsight is asked too, unless stores.hindsight.recall: false turns that off. Each result names its file and date, a replaced value is marked superseded, and the reply is capped at 6k tokens. When nothing holds most of what was asked, the reply says weak_match, so the agent searches again in other words and then teaches the memory the question that missed.
  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, refreshes the mental models, and drafts a rule when the same kind of correction keeps coming back.

Is it RAG? Yes: keyword RAG, built for an agent's brain

RAG means retrieval-augmented generation: find the relevant text first, then let the model answer from it. brain-core does that on every brain_recall. It finds the matching records in your files and hands them to the agent with their sources, and the agent answers from those.

What it is not is vector RAG. There is no embedding model and no vector database. Retrieval runs on a keyword index (SQLite FTS5, ranked by bm25), and that is on purpose: it is built for an agent's own memory, and it is built to get better the longer the agent is used.

Why this shape fits an agent's brain. Most RAG is built for a pile of documents nobody wrote for search: manuals, tickets, a wiki. An agent's memory is different. It is short records the agent writes on purpose, one fact, decision or correction at a time, so the work of making a record findable can be done once, at the moment it is saved, by the model that understands it.

How it gets smarter with use.

StepWhat happensWhat it leaves behind
SavingThe agent saves a memory with keys: the other words you might ask for it byA record that answers questions phrased differently from the text
A weak searchbrain_recall says weak_match when nothing holds most of what was askedNo guess passed off as an answer
RepairThe agent searches again in other words, then calls brain_remember(kind='key') with the question that missedThat question finds the record next time, for every later session
Reviewbrain_status lists the questions memory could not answer in the last 30 daysA list of gaps to fill
Measurementtests/eval/from_repairs.py turns repaired misses into labelled eval questionsA test that grows from real use
BriefingMental models are rewritten when one new record matches their questionA summary that stays current

Every miss that gets repaired is a miss that does not happen again, and the repair is a line in a markdown file you can read. In CI, the fixture brain after thirty days of sessions scores higher than the same brain on day one.

Keyword index or vector database.

Keyword index (brain-core)Vector database
How it matchesThe words in the question against the words in the record; rare words count moreText becomes a list of numbers; the closest numbers win
Exact things: names, ports, versions, error textStrong: port 5432 finds the record that says 5432Weaker: returns anything about ports or databases
Different wording with no shared wordsMisses unless the record has search keysStrong: "car" finds "vehicle" with nothing extra saved
A value that changedThe new value ranks first and the old one is marked supersededOld and new look almost identical, so the old one can come back first
SpeedAbout 45 ms a searchAbout 2 s on the self-hosted store measured here
What you runOne SQLite file, rebuilt from the vaultAn embedding model and a vector store (about 2 GB for Hindsight)
Why a result came backYou can see it: these words matchedHard to say: the numbers were close
Large piles of text nobody wrote keys forWeaker: it only knows the words on the pageStrong: the job it was built for

Why brain-core does not ship a vector database today. A first test, on 143 labelled questions from a real seven-month vault, did not show a gain worth its cost:

  • A small static embedding model blended into the ranking found 113 of 143 against 110 for keywords alone: seven questions fixed and four broken, a tie. That is one small model and one way of combining the two, not a verdict on vector search.
  • That blend returned a changed value ahead of its replacement. For a memory, serving the old value is the worst kind of error.
  • Search keys closed the wording gap instead: reworded questions went from 13 of 75 found to 51 of 75, at no cost at query time.
  • Hindsight on the recall path found the same 50 of 75 at about 2 s a query against about 45 ms.
  • A keyword index needs nothing installed or kept alive, so the lite install takes about a minute and the index can be deleted and rebuilt from the files.

The limit is real: about a third of reworded questions still miss, and a vector database is the better tool for a large body of documents nobody has written keys for. Hindsight stays available as an optional second store for anyone who wants one. The full table and method are in Does it work?

Mental models

Search answers a question. A mental model answers a standing one before it is asked: what the priorities are, how you like to work, what was decided and why. Add a models: block to brain.yaml and brain models writes each as a short markdown file in vault/models/:

- No git push unless told. He is sole commit author, one short subject line. [patterns.md:120][corrections.md:149]
- Do only what was asked; never bundle "while I'm at it" edits. [patterns.md:94][patterns.md:112]

Every claim names the file and line it rests on, and a claim that cites nothing is dropped before the file is written. A model is marked stale only when a record it cited changes or disappears, or when new records match its question. The session start loads them; brain daily rewrites the stale ones. The writing is done by the Anthropic API with your key (runner: api, the default; uv tool install 'brain-core-mcp[api]'), or by your own Claude Code login if you opt in (runner: claude, personal use on your own machine). They are briefings, not memory: recall never returns them, and the cited line is the source.

The five tools

ToolOne call does
brain_session('start')the whole start block: daily brief, executive state, mental models, a recall per mission, inbox count, and a flag if the last session crashed
brain_recall(query, scope)one query over the keyword index of the vault, any stores.notes folders and any stores.archive folders (older memory exported from another tool, ranked below your own records), plus the Claude Code transcripts of this folder and, unless switched off, Hindsight. Deduplicated, ranked by bm25 and recency, capped at 6k tokens. Each result carries its source; weak_match says when nothing really fits; scope='transcript' is what past sessions said and ran, useful on day one
brain_remember(text, kind, keys)writes vault → SQLite → Hindsight (→ relations table for a relation) and reports each layer. keys are extra words to find it by. Near-duplicates are skipped; a changed value gets a ⚠ Fact changed banner and the old line stays. kind='key' teaches an existing memory a question that missed it
brain_distill(source)captures a URL, GitHub repo, YouTube video, PDF, file or pasted text into an immutable raw/ folder for the agent to compile
brain_session('end')drains the queue, closes the day's session file, rewrites state and critique, writes the clean-close marker

The fifth tool is brain_status(), health in one call: which stores are up, how many tokens the always-loaded context costs, whether a session is open, which decisions are waiting on you, the questions memory could not answer in the last 30 days, and the twelve traits with their evidence.

Is it an MCP server or a tool?

Both. One Python package, three ways in:

PieceWhat it isWho uses it
brain servean MCP server that Claude Code starts from the agent's .mcp.json and that exposes five toolsthe agent, every session, without you touching it
brain commanda CLI: brain init, brain adopt, brain doctor, brain version, brain index, brain models, brain graph, brain hindsight install, brain cron install, brain desktop, brain daily, brain weekly; and brain brief, brain capture, brain recall, which the hooks call (brain lessons is an optional fourth)you, once at setup, then cron and the hooks
brain_core.Agentthe Python library both of the above sit onthe eval runner, the demo script, your own scripts

Install details

Before you start

You needWhyCheck
macOS, Linux with systemd, or Windows 10 1809+the installer sets up a background service and cron (Windows: a logon entry and scheduled tasks)uname, or winver
about 2 GB of disk and 10 minutes, or --lite (-Lite on Windows)Hindsight ships an embedded Postgres and a CPU embedding model; lite skips it
a Claude Code login, or an Anthropic API key, or liteHindsight uses an LLM to reason over memories: the key when ANTHROPIC_API_KEY is set, otherwise your Claude Code loginecho $ANTHROPIC_API_KEY
Claude Codethe agent runs inside it; the installer adds it if missingclaude --version

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 --desktop

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, including search keys, which is how a question in other words finds a memory. What you give up is search by meaning, mental models and the weekly reflection. The recall numbers in Does it work? are measured without Hindsight on the recall path. 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 --desktop --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                    installed with uv tool
== 5/8 Agent Atlas at ~/Agents/Atlas  32 files
== 6/8 Hindsight (vector store)      service: healthy
== 7/8 Cron                          daily 06:07, weekly Sun 07:13
== 8/8 Doctor                        Brain: OK
StepWhat happensIf it stops here
1checks for git via the Xcode command line toolsmacOS opens an install dialog; finish it, then re-run
2installs Homebrew if missingHomebrew asks for your password itself
3installs uv, gh, gitleaks, node and Claude Code with Homebrewanything already present is left alone
4installs the brain command from PyPI with uv tool--ref v0.9.0 pins a git tag instead
5runs brain init and writes the agent folderan existing brain.yaml is never overwritten
6installs Hindsight as a launchd service on 127.0.0.1:8888first start downloads the embedding model; give it a few minutes
7installs brain daily and brain weekly as launchd agents
8runs brain doctor on the new agentbrain doctor ~/Agents/Atlas repeats it any time
+with --desktop: connects the agent to the Claude desktop appsee Claude desktop app

After the installer

One thing the installer cannot do for you:

claude                                  # sign in to Claude Code once

Hindsight needs an LLM to reason over memories, and the installer picks one that works. With ANTHROPIC_API_KEY in your shell it uses that key. Without it, Hindsight uses your Claude Code login, and the installer says so; that mode is for personal use only. To move to a key later:

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
FlagMeaning
--agent NAMEthe agent's name (required)
--user Alexhow the agent addresses you
--dir PATHwhere the agent lives, default ~/Agents/NAME
--provideranthropic, openai, or claude-code (your Claude Code login; personal use only). Left out: anthropic when ANTHROPIC_API_KEY is set, otherwise claude-code. A provider you name needs its key in the shell, or the installer stops before it changes anything
--api-key-env VARread the key from a variable other than <PROVIDER>_API_KEY
--profile DIRa folder copied over the generic rules last, for your own doctrine
--liteskip Hindsight: vault + SQLite only, upgrade later. An agent made lite stays lite when the line is run again
--desktopconnect the agent to the Claude desktop app (macOS; skipped on Linux, which has no build of the app)
--dashboardthe Hindsight web UI on http://localhost:9999
--ref v0.9.0pin a git tag instead of the PyPI release

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, and every record already in the vault becomes searchable on the first recall; omit --bank to run lite.

Linux

The same one line; --desktop is skipped, because the desktop app has no Linux build. 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.

Windows

One line in PowerShell (Windows PowerShell 5.1 or PowerShell 7), with the same flags as on macOS in PowerShell spelling: -Lite for --lite, -Desktop for --desktop. It works under the default Restricted execution policy; nothing has to be changed first.

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/xy-claude/brain-core/main/install.ps1))) -Agent Atlas -User Alex -Desktop

Every step says what it is doing while it does it: downloads count their megabytes, longer steps print "still working" every 15 seconds, and nothing waits without a time limit.

StepWhat it doesGood to know
1checks for Git for Windows; installs it with winget when missingClaude Code runs its hooks in Git Bash. No winget, or a declined install, is reported and the install goes on
2downloads uv from its GitHub release and unpacks it to ~\.local\binabout 15 MB
3installs the brain command on Python 3.12 with uv tooluv fetches Python itself. Running the line again upgrades brain
4runs brain init and writes the agent folder (~\Agents\Atlas)an existing brain.yaml is never overwritten
5installs and starts Hindsight; skipped with -Liteabout 2 GB; runs hidden and starts again at every logon from your own registry Run key
+with -Desktop: adds brain-core to the Claude desktop app's settingsall three places the app may read, including Microsoft Store builds
6registers brain daily and brain weekly in Task Schedulertasks brain-core.atlas.daily and .weekly; they also start on battery
7downloads and installs Claude Codeabout 330 MB, checksum checked
endwith -Desktop: checks that the Claude app has loaded brain-coreif the app was open during the install, the script says how to quit it from the icon near the clock, watches for the restart, and reports what the app did

The last lines are the verdict, one of two:

== Install complete: every step above finished
  memory folder     C:\Users\Alex\Agents\Atlas
  Hindsight         running (provider claude-code)
  desktop app       connected and loaded
  scheduled tasks   created
  Claude Code       installed

or == Install NOT complete: N step(s) did not work, followed by each step that failed, why, and the command to run it again. Running the whole line again is always safe: what is in place is kept, and brain is upgraded.

Add -Lite to skip Hindsight: vault plus SQLite full-text search. The recall numbers below are measured without Hindsight on the recall path. The provider is chosen as on macOS (-Provider, -ApiKeyEnv). An agent made lite stays lite when the line is run again; it upgrades with brain hindsight install, then uncomment the hindsight: block in brain.yaml. Other options: -Dir, -ProfileDir, -Ref. Open a new terminal afterwards so brain is on PATH.

Claude desktop app

The agent's memory also works in the Claude desktop app's chat, on macOS and Windows. The install lines above carry --desktop (macOS) and -Desktop (Windows) for this. To connect an agent you already have:

brain desktop ~/Agents/Atlas

It adds one brain server to the app's claude_desktop_config.json, keeps everything else in that file, and leaves a .bak copy the first time it changes one. Then quit the app fully and reopen it; closing the window is not enough. On Windows the installer watches for that restart and tells you whether the app has loaded brain-core. On Windows a Microsoft Store install keeps its settings in a package folder, and that one is written too when it exists. If the file is somewhere else, open it from the app (Settings, Developer, Edit Config) and pass it with --config.

Claude CodeClaude desktop app
The five tools, on the same vault and databaseyesyes
Brief at session start, capture at the end (hooks)yesno: say "start a brain session" and "close the session"
The rules in CLAUDE.md and .claude/rules/loaded every sessionnot loaded; put what you need in a project's instructions

The desktop app has a memory of its own, kept on Anthropic's servers. The two do not conflict, but a fact can end up in both. For one source of truth, work in a desktop project with "Use account memory" turned off and tell it in the project instructions to use brain_recall and brain_remember.

Manual, any platform

uv tool install --python 3.12 brain-core-mcp   # Python 3.12 to 3.14; or: uv tool install git+https://github.com/xy-claude/brain-core@v0.9.0
brain init Atlas --path ~/Agents/Atlas --user Alex
brain hindsight install          # launchd, systemd --user, or a logon entry on Windows
brain cron install ~/Agents/Atlas    # launchd, crontab or Task Scheduler
brain desktop ~/Agents/Atlas         # optional: the Claude desktop app, macOS and Windows
brain doctor ~/Agents/Atlas

Updating

Nothing updates by itself: the copy you installed stays as it is until you change it. brain-core tells you when there is something newer. brain daily asks PyPI once a day, and when a newer version exists the daily brief and brain doctor say so in one line:

update     brain-core 0.4.25 is available (this is 0.4.23). Update: `uv tool upgrade --no-cache brain-core-mcp`, then restart Claude.

Run that command, or paste the install line again; both keep your agent folder as it is. Restart Claude Code or the Claude desktop app afterwards, since a running one keeps the copy it started with. The daily request sends nothing about you or your memory; it only reads the version number. To stop it, set update_check: false under cron: in brain.yaml.

An update replaces the program, not the files in your agent folder. When a release changes a rule, a hook or a setting in the template, the changelog says what to copy.

Check it worked

brain doctor ~/Agents/Atlas

It prints the agent name, the config path, one line per store, the knowledge lint, the always-loaded context in tokens, the last session start and close, pending decisions, recall misses, and ends with Brain: OK (or Brain: ATTENTION with the store that failed). The same report is brain_status() inside a session. The common problems:

SymptomCauseFix
brain: command not foundthe uv tool bin folder is not on your PATHuv tool update-shell, then open a new terminal
ERROR: no brain.yaml at ...wrong pathpass the agent folder, or the brain.yaml inside it
hindsight unreachable at http://127.0.0.1:8888the service is still starting, or not installedwait a minute; still down, run brain hindsight install
installer note ANTHROPIC_API_KEY is not set in this shellthe key was not in the shell when the service was installedexport it, then brain hindsight install again; it rewrites ~/.config/hindsight/env
Claude Code shows no brain toolsit was started outside the agent foldercd ~/Agents/Atlas && claude, then /mcp to confirm

First session

cd ~/Agents/Atlas && claude

The agent's CLAUDE.md tells it to open with brain_session('start'). What comes back:

{
  "session_id": "s-20261102-a1b2c3",
  "date": "2026-11-02",
  "recovery": null,
  "brief": "# Daily Brief — 2026-11-02 ...",
  "executive_state": "## Primary Objective ... ## Top Missions ... ## Pending Decisions ...",
  "inbox": 0,
  "peers": [],
  "mental_models": {"active-priorities": "..."},
  "missions": {"M-001 first mission": [ ...3 recall hits... ]}
}

On day one the brief is empty and the executive state is the template. That is expected. Spend the first session telling the agent what you are working on: the project, the stack, the decisions already made, how you like to work. Each statement that matters becomes a brain_remember call, and the reply shows what every layer did:

{"status": "written", "id": "9f2c…", "layers": {"vault": {"status": "written", "detail": "facts.md › System"},
                                 "sqlite": {"status": "written"},
                                 "hindsight": {"status": "written", "detail": "op 162bdbaa"}}}

Things to try in that first session:

  • State a fact, then change it. "The API listens on 8887." Later: "Correction, it is 8888." The second write returns a ⚠ Fact changed banner and vault/facts.md keeps both lines.
  • Give it a source. Paste a URL or a GitHub repo and ask it to distill it. The page lands in vault/raw/ untouched, and the agent compiles a page in vault/knowledge/.
  • Ask about something from earlier. "What did we decide about the database?" is one brain_recall call, and each hit names the file it came from. Ask for something that was never said and the reply carries weak_match instead of a confident near miss.
  • Open the vault in your editor. Every write you just saw is a line in a markdown file. Edit it if the agent got it wrong.

Say "thanks, we're done" and it runs brain_session('end'). Tomorrow at 06:07 brain daily writes the next brief from what you did today, and the next claude session opens with it.

What is in the agent folder

~/Agents/Atlas
├── CLAUDE.md                 identity and the five-tool protocol (with the rules: about 3k tokens always loaded)
├── .claude/
│   ├── rules/                01-identity 02-doctrine 03-authority 04-memory 05-system
│   ├── skills/               distill, session-end, brain-check
│   ├── hooks/                block-dangerous-bash.sh (rm -rf, force-push, curl|sh …)
│   └── settings.json         wires the hooks: brief at start, capture at stop and before
│                             compaction, recall of past sessions when a command fails
├── .mcp.json                 brain serve . + Hindsight
├── brain.yaml                stores, session files, cron schedule
├── vault/                    facts.md patterns.md decisions_log.md corrections.md
│   ├── record_meta.md        search keys, source and replaced values, by record id
│   ├── sessions/             one file per day (HSAM)
│   ├── knowledge/ raw/       the LLM-wiki: immutable sources, compiled pages
│   └── executive_state.md    objective, missions, pending decisions
└── data/brain.db             SQLite: the FTS5 index of every record, relations, transcript index, event log

Everything is markdown or SQLite. Open the vault in Obsidian, grep it, commit it, delete a line. The agent will not mind.

Does it work?

Two evals, and they answer different questions.

In CI, on a synthetic vault. These prove the plumbing: nothing regresses, writes behave.

SetHits
28 recall tasks on a fixture vault, stratified: 20 single-hop, 2 multi-hop, 1 knowledge-update, 2 abstention, 3 temporal, each run three times (pass^3)28 / 28
11 write scenarios: dedup, value-change banner, relation routing, secret refusal11 / 11
Growth: the fixture brain after thirty days of sessions scores higher than the same brain on day one on every defensible trait signalholds

The recall tasks there are judged by substring, and a question written in the note's own words always passes. They are a regression test, not proof of recall.

On a real vault, against labelled answers. 143 questions on one agent's vault of seven months (about 3,200 records), each labelled with the record that answers it. The questions and the labels were written by a model reading the records (11 use the owner's own past words); no person has checked them yet. A question asked in other words can fail, and many did. "Found" means the right record is in the top ten.

Question type0.40.5.1
Reworded (the memory says it differently)13 / 7551 / 75
Same words as the memory20 / 2020 / 20
A changed value: the new one must come before the old5 / 97 / 9
By date0 / 87 / 8
Needs several records2 / 85 / 8
Not in memory: must be flagged, not answered6 / 1211 / 12

How to read it. The index alone took reworded questions from 13 to 31; search keys took them to 51, and those keys were written by a model that never saw the questions. A vault with no keys starts near 31. A third of reworded questions still miss, which is what miss repair is for. Median recall is about 45 ms on the keyword index; with Hindsight on the recall path it was about 2 s and found the same 50 of 75, which is why it can be switched off (stores.hindsight.recall: false). This is one vault and one set of model-written questions, not a public benchmark.

A small embedding model was tested and tied. With search keys in place, the same 143 questions were run with a local embedding model (potion-retrieval-32M, 3,153 records embedded in 0.1 s) blended into the keyword ranking. The best blend found 7 questions keywords missed and lost 4 that keywords had, for 113 of 143 against 110: a gain inside the noise, paid for with a changed value coming back ahead of its replacement and a missed date question. Meaning alone scored 89. Search keys and this model caught largely the same misses, and keys cost nothing at query time, so brain-core ships no vector index today. The test covers one small static model blended by score. A stronger model used as a second search beside keywords, with the scores never blended, was measured next: see below. The same tie showed with Hindsight on the recall path (50 of 75 both ways).

Hybrid recall (optional, experimental). stores.vectors adds a second search by meaning beside the keyword index, and recall.judge: model lets a model read the best candidates and pick the ones that answer, or say that none does. Both are off unless you set them, and without them recall is exactly the keyword recall above.

stores:
  vectors: {model: Qwen/Qwen3-Embedding-0.6B}   # pip install "brain-core-mcp[vectors]", then `brain index`
recall:
  judge: model          # default: agent (the calling agent reads the list itself)
  runner: claude        # your own Claude Code login; `api` needs a key
  # model: claude-haiku-5-5   # the default, and the model the numbers below were measured with

With the judge on, every recall sends the question and up to 50 records to that model; with it off, recall sends nothing anywhere. docs/THREAT_MODEL.md lists what each feature sends.

Measured on the same vault with a larger set: 446 questions (299 to tune on, 147 held out and opened once per stage), each run compared with the one before it question by question. The 143 above are in it; the other 303 were drafted by a model from the records and each answerable one was checked once by a second model. No person has checked the labels yet, and the judge is a model of the same family, so read the numbers as a comparison between settings, not as an absolute score. These are the figures of 0.9.0.

RecallTuning set (299)Held out (147)Broken against keywords
Keywords and search keys (the default)19798
+ vector search, joined by rank2311154 and 1
+ a model judge (claude-haiku-5-5)2641340 and 0

How large the gain is depends on who wrote the question. With everything on, the 143 older questions go from 110 to 127 (12 points) and the 303 drafted ones from 185 to 271 (28 points). On the 11 questions in the owner's own past words it is 8 to 10, too few to conclude from. Expect something between 12 and 28 points on a vault like this one, and less on a vault whose records carry no search keys: the question set over-samples records that have them.

What moved, on the held-out questions: reworded 30 to 47 of 53, questions that need several records 8 to 14 of 17, changed values 7 to 11 of 12, questions whose answer is not in memory correctly refused 14 to 19 of 19, exact identifiers 17 to 18 of 18.

The three ways a recall goes wrong, on all 446 questions:

Keywords+ vectors+ judge
False answer: not in memory, and not flagged19 of 5719 of 572 of 57
False refusal: answerable, flagged as a miss104 of 389104 of 38912 of 389
Missed with no warning: answerable, the right record not returned, nothing says so70 of 38942 of 38936 of 389

The last row is the one that matters most and the judge does not remove it: about one answerable question in eleven comes back without its record and without a warning. It is an upper bound (a label can miss a second record that also answers), and it is why not_in_memory and thin_recall tell the agent to search again in other words before it answers.

How it works. Each search puts forward its best 150 records and the lists are joined by rank, never by score. A record holding an exact identifier from the question (a port, a version, a file name) goes first. A day named in the question adds that day's records. A record another one replaced never stands above its replacement. Then the judge reads the best 50 with their dates and returns the numbers of the ones that answer; it can only point at records it was shown, and if it fails or takes longer than recall.judge_timeout (60 s), recall returns its own order and says so. Reading 100 instead of 50 was measured: 403 against 398 of 446 (13 fixed, 8 broken, p 0.38) for twice the tokens, so the default stays 50 (recall.judge_candidates).

What it costs. The embedding model is held by one small worker per machine, shared by every agent, started on the first call and gone after five idle minutes: about 1.6 GB of memory while it answers (2.7 GB during a full index), 1.3 GB on disk, plus the library (about 850 MB). On an Apple Silicon GPU a question takes about 45 ms to embed once the worker is up and a 5,400-record vault indexes in about five minutes; on CPU alone indexing is too slow to be practical. A recall takes about 45 ms on keywords, 150 ms with vectors, and about 4 s with the judge, which is one model call of roughly 7,000 tokens per recall. Unix only for now: on Windows the vector search stays off and recall answers from keywords.

Documentation truncated — see the full README on GitHub.

Reviews

No reviews yet

Be the first to review this server!