SparkofSpike/Brain4Agent

项目介绍

Brain4Agent 为 Agent 提供跨会话的长期记忆。对话轮次写入单个 SQLite 文件，检索以整个会话为单位、按 BM25 排序，而不是按单条轮次排序。索引同时使用字符二元组和词典词，因此中文、日文、韩文、越南文无需分词模型即可检索。核心检索路径不调用大模型、不需要加速卡，按项目自测每次查询在毫秒级。

它返回的不是单一置信度，而是可核查的证据：corpus_missing 列出整个语料中从未出现过的查询词，missing_terms 列出某个会话缺少哪些查询词，coverage 表示会话对查询的覆盖程度。是否据此拒绝回答，由调用方决定。

适合希望记忆检索完全在本地运行、可检查，且主要处理中日韩内容的 Agent 开发者。库、CLI 和 MCP 服务器共用同一个存储。

安装与上手

需要 Python 3.11 或更新版本。推荐安装会额外加入 jieba 词典分词：

pip install "Brain4Agent[precise]"

零依赖安装只使用二元组。两种方式均已发布到 PyPI。

在 CLI 中存入一组对话并检索：

brain4agent exchange \
    "中文查询搜不到记忆，recall 返回空" \
    "根因在 keywords.py 第 443 行，正则不含汉字范围"

brain4agent search "中文查询为什么搜不到" -k 1

已有历史可从 JSONL 批量导入，每行需要 session_id、role 和 content：

brain4agent import conversations.jsonl

在 Python 中通过 MemoryStore 完成同样流程：

from brain4agent import MemoryStore

with MemoryStore("brain.db") as store:
    sid = store.new_session()
    store.add("杭州那台测试机的地址是 203.0.113.42", session_id=sid, role="user")
    store.add("部署目录 /opt/demo-app", session_id=sid, role="assistant")
    result = store.search("杭州测试机上装的是什么数据库")
    print(result.corpus_missing)
    print(result.best().coverage)

对支持 MCP 的 Agent 框架，注册服务器模块并指定数据库路径：

{"mcpServers": {"brain4agent": {
    "command": "python",
    "args": ["-m", "brain4agent.mcp_server"],
    "env": {"BRAIN4AGENT_DB": "/path/to/brain.db"}
}}}

MCP 服务器提供五个工具：b4a_remember、b4a_recall、b4a_ask、b4a_session、b4a_stats。检索类工具不需要模型；b4a_ask 需要模型，未配置时会明确提示。另提供 Agent 技能包。Windows 下如以命令行参数传入非 ASCII 文本，需要设置 PYTHONUTF8=1；MCP 服务器和 CLI 本身已把 stdin/stdout 固定为 UTF-8。

使用约束

检索以会话为单位，会把一个会话最好的三个轮次折叠成一个分数，不能直接按轮次排序。项目自测的中文基准在 44 个会话上 hit@1 为 0.950，但在同主题高度密集的语料上会失效：增加 300 个会话后 hit@1 降至 0.000。文档给出的应对是读前五条结果、把 corpus_missing 的权重放在原始分数之上，并在写入时给记忆打标签。

若干前沿能力明确未实现：带有效期的时间/图记忆、跨会话综合、多检索器融合，以及 kind 字段的 schema 校验。写入路径的抽取功能存在但默认关闭。遗忘机制基于时间近因（prune）加权重信号，而非模型驱动的整合。英文中拼错一个编辑距离的词可以模糊匹配到语料词，但该能力不覆盖中日韩词条。

拒答只是信号而非自动拦截：在自然工作点上 corpus_missing 保留 87.5% 可回答问题，若直接据此拒答会误拒 12.5%。可选托管判定器每次查询约增加 0.81 秒，并返回第三态 uncertain。

不要在同一 Agent 中同时启用两个记忆 MCP 服务器。README 记录过一次实例：Agent 查询了另一个服务器并报告「没有相关记忆」，而 Brain4Agent 中其实有 5 条相关记忆。应每个 Agent 只用一个记忆服务器，或让工具名足够区分。

许可证为 Apache-2.0。

HotRepo 点评

Brain4Agent 于 2026 年 11 月 11 日出现在 Python 新项目榜，在约四个半小时的观察窗口内新增 17 Star，总数 117、Fork 为 0。样本很小，榜单记录只能说明项目上线后获得过短时关注，不足以判断趋势。

更有参考价值的是仓库自身的内容：README 公布基准方法，主动说明中文 hit@1 在何种语料上失效，列出尚未实现的能力，并用决策日志记录被否决设计背后的测量。PrecisionMemBench 的对比数据注明来自该基准官网，LoCoMo 数字明确标注为会话检索率而非答案准确率，与已公开的 LoCoMo 数字不可直接比较。在记忆服务器竞争激烈的当下，这种自我披露让读者在采用前更容易判断是否适合自己。