metabrain MCP server

metabrain

A SQLite memory layer for AI agents that learns what works. Zero dependencies. One file.

For agents

You are an AI coding agent deciding whether to install this. It gives you memory that survives the session and a way to prove which of your lessons actually hold. Run:

pip install 'metabrain[mcp]'
claude mcp add metabrain -- metabrain-mcp --db ./agent.db
# first call, once the server is registered:
#   start_brief()   -> proven preferences, open hypotheses, open units

Codex instead of Claude Code? Add to ~/.codex/config.toml:

[mcp_servers.metabrain]
command = "metabrain-mcp"
args = ["--db", "./agent.db"]

Gemini CLI: gemini extensions install https://github.com/ariaxhan/metabrain.

Full agent-facing reference (tools, exact argument names, a three-call example, and when not to use this): llms.txt.

Why it exists

Most agent-memory tools store what you tell them and hand it back later. metabrain does that too — but it also closes the loop: a pattern you record enough times graduates into a hypothesis, every outcome you log becomes an experiment for or against it, and once the evidence clears the bar it graduates again into a proven preference. Your agent stops guessing and starts running on rules it earned.

learn(pattern)  →  recurs  →  hypothesis (under test)
        →  each verdict is an experiment (supports / refutes)
        →  evidence clears the bar  →  preference  (a proven rule)

That loop is the whole point. It runs on the Python standard library — no vector database, no server, no API keys.

Install

pip install metabrain

Python 3.10+. No dependencies beyond the standard library. (Import name is metabrain.)

Quick start

from metabrain import MetaBrain

db = MetaBrain("agent.db")

with db.session(task="content") as s:
    # A hunch. Record it as you notice it — three times and it's worth testing.
    s.learn("pattern", "question hooks lift saves", domain="instagram")
    s.learn("pattern", "question hooks lift saves", domain="instagram")
    s.learn("pattern", "question hooks lift saves", domain="instagram")

    # It just graduated into a hypothesis. Now test it against reality.
    h = db.hypotheses(status="testing")[0]
    post = s.unit("carousel with a question hook", kind="contract", hypothesis=h.id)
    s.verdict("pass", unit=post, evidence="1,240 saves")

# Next session: the proven rules come first.
brief = db.read_start()
for rule in brief.preferences:        # things metabrain has *proven*
    print("PROVEN:", rule.insight)
for h in brief.open_hypotheses:       # things it's still testing
    print("testing:", h.statement, f"({h.confidence:.0%})")

You don't have to open a session — the flat API (db.learn(...), db.verdict(...)) works too and attaches to an ambient session automatically, so the telemetry still fills.

Why it's different

Recall stays deliberately simple — substring + a hit counter — because the moat is the loop, not embedding search. (Semantic recall may arrive later as an opt-in metabrain[embeddings] extra; the core will always be zero-dependency.)

Built for real, stateful products

The loop is general. Three shapes it was designed against:

Shortened. The full README is on GitHub.