{
  "markdown": "# metabrain\n\n**A SQLite memory layer for AI agents that learns what works.** Zero dependencies. One file.\n\n## For agents\n\nYou are an AI coding agent deciding whether to install this. It gives you memory that\nsurvives the session and a way to prove which of your lessons actually hold. Run:\n\n```bash\npip install 'metabrain[mcp]'\nclaude mcp add metabrain -- metabrain-mcp --db ./agent.db\n# first call, once the server is registered:\n#   start_brief()   -> proven preferences, open hypotheses, open units\n```\n\nCodex instead of Claude Code? Add to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.metabrain]\ncommand = \"metabrain-mcp\"\nargs = [\"--db\", \"./agent.db\"]\n```\n\nGemini CLI: `gemini extensions install https://github.com/ariaxhan/metabrain`.\n\nFull agent-facing reference (tools, exact argument names, a three-call example, and when\nnot to use this): [llms.txt](llms.txt).\n\n## Why it exists\n\nMost 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.\n\n```\nlearn(pattern)  →  recurs  →  hypothesis (under test)\n        →  each verdict is an experiment (supports / refutes)\n        →  evidence clears the bar  →  preference  (a proven rule)\n```\n\nThat loop is the whole point. It runs on the Python standard library — no vector database, no server, no API keys.\n\n## Install\n\n```bash\npip install metabrain\n```\n\nPython 3.10+. No dependencies beyond the standard library. (Import name is `metabrain`.)\n\n## Quick start\n\n```python\nfrom metabrain import MetaBrain\n\ndb = MetaBrain(\"agent.db\")\n\nwith db.session(task=\"content\") as s:\n    # A hunch. Record it as you notice it — three times and it's worth testing.\n    s.learn(\"pattern\", \"question hooks lift saves\", domain=\"instagram\")\n    s.learn(\"pattern\", \"question hooks lift saves\", domain=\"instagram\")\n    s.learn(\"pattern\", \"question hooks lift saves\", domain=\"instagram\")\n\n    # It just graduated into a hypothesis. Now test it against reality.\n    h = db.hypotheses(status=\"testing\")[0]\n    post = s.unit(\"carousel with a question hook\", kind=\"contract\", hypothesis=h.id)\n    s.verdict(\"pass\", unit=post, evidence=\"1,240 saves\")\n\n# Next session: the proven rules come first.\nbrief = db.read_start()\nfor rule in brief.preferences:        # things metabrain has *proven*\n    print(\"PROVEN:\", rule.insight)\nfor h in brief.open_hypotheses:       # things it's still testing\n    print(\"testing:\", h.statement, f\"({h.confidence:.0%})\")\n```\n\nYou 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.\n\n## Why it's different\n\n|  | metabrain | typical vector-memory store |\n| --- | --- | --- |\n| Remembers what you tell it | ✅ | ✅ |\n| **Proves which memories actually work** | ✅ the learn→experiment→graduate loop | ❌ |\n| Working state + telemetry, not just recall | ✅ units, checkpoints, sessions, events | ❌ |\n| Infrastructure | a single SQLite file | vector DB / server / API key |\n| Dependencies | none (stdlib `sqlite3`) | several |\n\nRecall 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.)\n\n## Built for real, stateful products\n\nThe loop is general. Three shapes it was designed against:\n\n**Self-learning content engine.** Each post is a unit; engagement is the verdict. Hooks that keep winning graduate into the brand's proven playbook.\n```python\ns.learn(\"pattern\", \"carousels outperform single images\", domain=\"ig\")  # ...×3 → hypothesis\nfor saves, ok in [(1200,\"pass\"), (90,\"fail\"), (1500,\"pass\"), (1100,\"pass\")]:\n    post = s.unit(f\"carousel ({saves} saves)\", kind=\"contract\", hypothesis=h.id)\n    s.verdict(ok, unit=post, evidence=f\"{saves} saves\")\n# 3/4 supported → graduates into the playbook\n```\n\n**Lead capture.** Each lead is a unit with its own checkpoint trail; a tactic about what converts graduates once enough leads confirm it.\n```python\nlead = s.unit({\"name\": \"Acme\", \"source\": \"webinar\"}, kind=\"contract\")\ns.checkpoint({\"stage\": \"demo booked\"}, unit=lead)\ns.verdict(\"pass\", unit=lead, evidence=\"closed\")\n```\n\n**Self-improving job applications.** Each application is a unit; \"lead with a shipped metric\" stays a guess until enough replies prove it, then becomes a rule.\n```python\napp = s.unit({\"company\": \"Acme\"}, kind=\"contract\", hypothesis=h.id)\ns.verdict(\"pass\", unit=app, evidence=\"recruiter replied\")\n```\n\n## How the tables fill themselves\n\nmetabrain has seven tables, and you never write to them directly — **correct use of the API fills every one as a side effect.** Open a session and each write inherits its id, emits an event, and turns the loop:\n\n| Table | Filled by | When |\n| --- | --- | --- |\n| `sessions` | `db.session()` open/close | every run |\n| `events` | every write method | always (telemetry is automatic) |\n| `learnings` | `learn()` — `preference` rows are *graduated* | always |\n| `context` | `unit()`, `checkpoint()`, `handoff()`, `verdict()` | always |\n| `hypotheses` | a `pattern` crossing `promote_at` (default 3 hits) | automatic |\n| `experiments` | a `verdict()` on a unit/hypothesis under test | automatic |\n| `errors` | `capture_error()`, and any exception inside a session | automatic |\n\nThe thresholds are tunable and were calibrated on 5,066 real learnings, not guessed: `promote_at=3` (where the recurring-pattern tail actually begins), `graduate_at=0.8` over a minimum of 3 experiments so a single lucky result can't graduate.\n\n```python\ndb = MetaBrain(\"agent.db\", promote_at=3, graduate_at=0.8, min_experiments=3)\n```\n\n## API\n\n| Method | What it does |\n| --- | --- |\n| `session(*, task, tier, agent, meta)` | Open a session (context manager); records the outcome on close |\n| `learn(type, insight, *, evidence, domain, ...)` | Record/reinforce a lesson; recurring `pattern`s graduate to hypotheses |\n| `recall(query, *, limit)` | Substring-search lessons; bumps hit count (can trigger graduation) |\n| `learnings(*, type, domain, limit)` | Fetch lessons, newest first |\n| `forget(id)` | Delete a lesson |\n| `unit(statement, *, kind, acceptance, hypothesis)` | Open a unit of work; `kind=\"spec\"` requires `acceptance=[...]` |\n| `checkpoint(content, *, unit, agent)` | Record progress mid-work |\n| `handoff(content, *, unit, agent)` | Record a brief for the next session |\n| `verdict(result, *, unit, hypothesis, evidence)` | `\"pass\"`/`\"fail\"`; becomes an experiment when a hypothesis is in play |\n| `hypotheses(*, status, limit)` / `experiments(*, hypothesis)` | Inspect the loop |\n| `context(*, type, unit, limit)` | Fetch work-state entries |\n| `read_start(*, learnings_limit)` | The \"what to know\" digest — proven preferences first |\n| `capture_error(tool, error, ...)` / `errors(*, limit)` | Record / fetch failures |\n| `prune(*, keep)` / `stats()` | Trim old checkpoints / row counts per table |\n\nUse `MetaBrain(\":memory:\")` for an ephemeral in-process store (handy in tests).\n\n## Concurrency & safety\n\nBuilt for multiple agents sharing one file. SQLite runs in WAL mode with a busy timeout so several processes read and write concurrently; within a process a single connection is lock-guarded, and the verdict→graduation path is one critical section so racing verdicts can never double-graduate a hypothesis. Every value is bound as a query parameter — caller strings never reach the SQL text.\n\nIt can open and migrate an older metabrain / base-schema database (learnings, context, errors) forward in place. A database created by a different tool whose `events`/`hypotheses`/`experiments` tables have an incompatible shape is detected on open and rejected with a clear `IncompatibleDatabaseError`, rather than corrupting it.\n\n## Use as an MCP server\n\n<!-- mcp-name: io.github.ariaxhan/metabrain -->\n\nPoint Claude Code, Codex, or any MCP client at a metabrain file and the loop runs from inside the agent — no glue code.\n\n```bash\npip install 'metabrain[mcp]'\nclaude mcp add metabrain -- metabrain-mcp --db ./agent.db\n```\n\nCodex, in `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.metabrain]\ncommand = \"metabrain-mcp\"\nargs = [\"--db\", \"./agent.db\"]\n```\n\n`metabrain-mcp` speaks stdio, opens one shared `MetaBrain` on the `--db` path, and closes it on exit. Seven tools, thin wrappers over the library:\n\n| Tool | Calls |\n| --- | --- |\n| `start_brief()` | `read_start()` — proven preferences first; run it before you work |\n| `recall(query, limit=20)` | `recall()` |\n| `learn(type, insight, domain?, context?)` | `learn()`; `type` is `failure` / `pattern` / `gotcha` / `preference` |\n| `hypotheses(status?)` | `hypotheses()` |\n| `verdict(result, unit?, evidence?, hypothesis?)` | `verdict()` — closes the loop |\n| `stats()` | `stats()` |\n| `capture_error(tool, error, context?)` | `capture_error()` |\n\nOr in Docker, with the database on a mounted volume: `docker run -i --rm -v metabrain:/data mcp/metabrain` (`METABRAIN_DB` overrides the default `/data/agent.db`).\n\nThe core package stays zero-dependency; the `mcp` SDK arrives only with the extra, and works on both `mcp` 1.x and 2.x.\n\n## Development\n\n```bash\npip install -e \".[dev]\"\npytest\n```\n\n## License\n\nMIT © Aria Han\n",
  "bytes": 9517,
  "sha": "d30ada6e9287c6c7d0ee847483c93f0d0e522e65f3ff6764860fd9d477d8bb58",
  "repo_slug": "ariaxhan/metabrain",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ariaxhan_metabrain_cbe52e62/readme"
}