Skip to main content
Glama
deenkoruzh
ariaxhan

metabrain

by ariaxhan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

metabrain

一个 SQLite 记忆层，专为 AI 智能体设计，会学习什么有效。 零依赖。单文件。

面向智能体

你是一个 AI 编程智能体，正在决定是否安装它。它为你提供跨会话存续的记忆，以及一种证明哪些经验教训真正成立的方式。运行：

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。

面向智能体的完整参考（工具、确切的参数名、一个三次调用的示例，以及何时不应使用本工具）：llms.txt。

Related MCP server: DevFlow MCP

为什么存在

大多数智能体记忆工具只会存储你告诉它们的内容，之后再原样返回。metabrain 也能做到这一点——但它还会闭环：一个你记录足够多次的模式会晋升为假设，你记录的每个结果都会成为支持或反对它的实验，一旦证据达标，它就会再次晋升为经过验证的偏好。你的智能体不再靠猜，而是开始依照它自己赢得的规则运行。

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

这个循环正是全部意义所在。它只依赖 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 循环

❌

工作状态 + 遥测，而不只是召回

✅ units、checkpoints、sessions、events

❌

基础设施

单个 SQLite 文件

向量数据库 / 服务器 / API 密钥

依赖

无（标准库 sqlite3）

多个

召回功能刻意保持简单——子串匹配 + 命中计数器——因为护城河是循环本身，而不是嵌入搜索。（语义召回未来可能会作为可选的 metabrain[embeddings] 附加功能引入；核心将始终保持零依赖。）

为真实、有状态的产品而设计

该循环具有通用性。以下是它专门为之设计的三种形态：

自学习内容引擎。 每篇帖子是一个 unit；互动量就是判定。持续获胜的钩子会晋升为品牌已验证的玩法手册。

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

线索捕获。 每个线索是一个 unit，带有自己的 checkpoint 轨迹；一旦足够多的线索证实了某个关于什么能促成转化的策略，该策略就会晋升。

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

自我改进的求职申请。 每份申请是一个 unit；“以已上线的指标开头”在得到足够多的回复证明之前始终只是猜测，之后才会成为规则。

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

对测试中的 unit/hypothesis 执行 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:") 可获得一个临时的进程内存储（在测试中很方便）。

并发与安全

专为多个智能体共享同一个文件而设计。SQLite 以 WAL 模式运行，并设置了 busy timeout，因此多个进程可以并发读写；在单个进程内，一个连接由锁保护，并且 verdict→graduation 路径是一个临界区，因此并发的 verdict 永远不可能让同一个假设被重复晋升。每个值都作为查询参数绑定——调用方的字符串永远不会进入 SQL 文本。

它可以就地打开并向前迁移旧的 metabrain / base-schema 数据库（learnings、context、errors）。如果某个数据库是由其他工具创建的，其 events/hypotheses/experiments 表结构不兼容，则会在打开时被检测到，并以清晰的 IncompatibleDatabaseError 拒绝，而不会损坏它。

作为 MCP 服务器使用

让 Claude Code、Codex 或任何 MCP 客户端指向一个 metabrain 文件，循环就会在智能体内部运行——无需胶水代码。

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，并在退出时关闭它。七个工具，都是对库的轻量封装：

工具

调用

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 仅在安装 extra 时引入，并且同时兼容 mcp 1.x 和 2.x。

开发

pip install -e ".[dev]"
pytest

许可证

MIT © Aria Han

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Local Memory MCP Server

    danieleugenewilliams
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    Provides persistent local memory functionality for AI assistants, enabling them to store, retrieve, and search contextual information across conversations with SQLite-based full-text search. All data stays private on your machine while dramatically improving context retention and personalized assistance.
    3
    -

  • code-recall

    AbianS
    A
    license
    Not graded
    quality
    C
    maintenance
    Gives AI coding agents persistent memory by storing observations, decisions, and learnings in a local SQLite database with vector search, full-text search, and a rules engine.
    4
    MIT

  • simple-memory-mcp

    chrisribe
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides AI assistants with persistent memory across sessions using local SQLite and keyword search, allowing storage and retrieval of user preferences, project context, and decisions.
    11 npm
    8
    MIT