metabrain

metabrain

为 AI Agent 提供的 SQLite 记忆层，能从有效做法中学习。零依赖。单个文件。

面向 Agent

你是一名 AI 编码 Agent，正在决定是否安装这个工具。它能让记忆跨会话保留，还能证明你总结的哪些经验确实行之有效。运行：

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 而不是 Claude Code？添加到 ~/.codex/config.toml：

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

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

完整的 Agent 参考文档（工具、确切的参数名称、一个包含三次调用的示例，以及何时不该使用此工具）：llms.txt。

为什么要开发它

大多数 Agent 记忆工具都会存储你告诉它们的内容，以后再交还给你。metabrain 也会这样做，但它还会形成闭环：你记录足够多次的模式会晋升为假设；你记录的每个结果都会成为支持或反驳该假设的实验；证据达到门槛后，它又会晋升为经验证的偏好。你的 Agent 不再靠猜测，而是依据自己验证出的规则行事。

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

这个闭环就是 metabrain 的核心。它基于 Python 标准库运行，无需向量数据库、服务或 API 密钥。

安装

pip install metabrain

Python 3.10+。除标准库外无其他依赖。（导入名称为 metabrain。）

快速开始

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%})")

你不必打开会话——扁平 API（db.learn(...)、db.verdict(...)）也能正常工作，并会自动关联到当前会话，因此遥测数据仍会持续填充。

有何不同

	metabrain	典型的向量记忆存储
记住你告诉它的内容	✅	✅
证明哪些记忆确实行之有效	✅ learn→experiment→graduate 闭环	❌
工作状态和遥测数据，而不仅是检索	✅ 单元、检查点、会话、事件	❌
基础设施	单个 SQLite 文件	向量数据库／服务／API 密钥
依赖项	无（标准库 sqlite3）	多个

检索功能刻意保持简单——子字符串匹配加命中计数——因为真正的优势在于闭环，而不是向量嵌入搜索。（未来可能会通过可选的 metabrain[embeddings] 扩展支持语义检索；核心始终保持零依赖。）

为真正的有状态产品而构建

这个闭环适用于各种场景。以下是设计时参考的三种模式：

自学习内容引擎。 每篇帖子都是一个单元；互动情况就是判定结果。持续奏效的吸引点会晋升为品牌经验证的内容策略。

s.learn("pattern", "carousels outperform single images", domain="ig")  # ...×3 → hypothesis
for saves, ok in [(1200,"pass"), (90,"fail"), (1500,"pass"), (1100,"pass")]:
    post = s.unit(f"carousel ({saves} saves)", kind="contract", hypothesis=h.id)
    s.verdict(ok, unit=post, evidence=f"{saves} saves")
# 3/4 supported → graduates into the playbook

潜在客户获取。 每条潜在客户记录都是一个单元，并有自己的检查点轨迹；关于哪些做法能促成转化的策略，会在得到足够多潜在客户的验证后晋升。

lead = s.unit({"name": "Acme", "source": "webinar"}, kind="contract")
s.checkpoint({"stage": "demo booked"}, unit=lead)
s.verdict("pass", unit=lead, evidence="closed")

自我改进的求职申请。 每份申请都是一个单元；“开头突出已交付的指标”在得到足够多回复的验证前都只是猜测，验证后便会成为规则。

app = s.unit({"company": "Acme"}, kind="contract", hypothesis=h.id)
s.verdict("pass", unit=app, evidence="recruiter replied")

表如何自动填充

metabrain 有七张表，你无需直接写入其中任何一张——正确使用 API，就会在每次操作的副作用中填充所有表。 打开会话后，每次写入都会继承会话 ID、发出事件，并推动闭环运行：

表	由什么填充	何时
sessions	打开／关闭 db.session()	每次运行
events	每个写入方法	始终（遥测会自动记录）
learnings	learn()——preference 行由晋升产生	始终
context	unit()、checkpoint()、handoff()、verdict()	始终
hypotheses	pattern 达到 promote_at（默认 3 次命中）	自动
experiments	对正在测试的单元／假设调用 verdict()	自动
errors	capture_error()，以及会话中发生的任何异常	自动

这些阈值可以调整，且经过 5,066 条真实学习记录的校准，并非凭空猜测：promote_at=3（重复模式的长尾实际从此处开始），graduate_at=0.8，且至少需要 3 次实验，这样单次侥幸的结果就无法促成晋升。

db = MetaBrain("agent.db", promote_at=3, graduate_at=0.8, min_experiments=3)

API

方法	功能
session(*, task, tier, agent, meta)	打开一个会话（上下文管理器）；关闭时记录结果
learn(type, insight, *, evidence, domain, ...)	记录/强化一条经验；反复出现的 pattern 会升级为假设
recall(query, *, limit)	按子字符串搜索经验；增加命中次数（可能触发升级）
learnings(*, type, domain, limit)	获取经验，按最新优先排序
forget(id)	删除一条经验
unit(statement, *, kind, acceptance, hypothesis)	打开一个工作单元；kind="spec" 时必须提供 acceptance=[...]
checkpoint(content, *, unit, agent)	在工作过程中记录进度
handoff(content, *, unit, agent)	为下一次会话记录简报
verdict(result, *, unit, hypothesis, evidence)	"pass"/"fail"；如果涉及假设，则会成为一项实验
hypotheses(*, status, limit) / experiments(*, hypothesis)	检查循环
context(*, type, unit, limit)	获取工作状态条目
read_start(*, learnings_limit)	“需要了解的内容”摘要——已验证的偏好优先
capture_error(tool, error, ...) / errors(*, limit)	记录/获取错误
prune(*, keep) / stats()	清理旧检查点/统计各表的行数

测试时，可使用 MetaBrain(":memory:") 创建临时的进程内存储。

并发与安全性

专为多个 Agent 共享同一个文件而构建。SQLite 以 WAL 模式运行，并设置了忙碌超时，因此多个进程可以同时读写；在单个进程内，单个连接受锁保护，判定→升级流程属于一个临界区，因此并发判定绝不会导致假设被重复升级。所有值都通过查询参数绑定——调用方的字符串不会进入 SQL 文本。

它可以就地打开并迁移较旧的 metabrain / base-schema 数据库（learnings、context、errors）。打开时，如果检测到由其他工具创建、且其 events/hypotheses/experiments 表结构不兼容的数据库，会拒绝打开并明确报错 IncompatibleDatabaseError，而不会破坏数据。

用作 MCP 服务

让 Claude Code、Codex 或任何 MCP 客户端连接到 metabrain 文件，即可在 Agent 内运行整个循环——无需编写胶水代码。

pip install 'metabrain[mcp]'
claude mcp add metabrain -- metabrain-mcp --db ./agent.db

Codex，在 ~/.codex/config.toml 中：

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

metabrain-mcp 使用 stdio 通信，在 --db 路径上打开一个共享的 MetaBrain，并在退出时关闭。提供 7 个工具，是该库的轻量封装：

工具	调用
start_brief()	read_start() — 已验证的偏好优先；开始工作前运行
recall(query, limit=20)	recall()
learn(type, insight, domain?, context?)	learn()；type 为 failure / pattern / gotcha / preference
hypotheses(status?)	hypotheses()
verdict(result, unit?, evidence?, hypothesis?)	verdict() — 完成闭环
stats()	stats()
capture_error(tool, error, context?)	capture_error()

也可以在 Docker 中使用，并将数据库放在挂载卷上：docker run -i --rm -v metabrain:/data mcp/metabrain（METABRAIN_DB 可覆盖默认值 /data/agent.db）。

核心包保持零依赖；只有安装额外组件时才会引入 mcp SDK，并且兼容 mcp 1.x 和 2.x。

开发

pip install -e ".[dev]"
pytest

许可证

MIT © Aria Han