brain — 一个会遗忘的类脑记忆库
给 AI agent 用的长期记忆。单文件 SQLite,零第三方依赖,事件是唯一真相。
它不是向量数据库,也不是知识图谱。它更像一个会老去的笔记本: 记进去的东西会衰减、会休眠、会被提炼,而事故和教训永不遗忘。
它到底解决什么
AI 每次会话都失忆。现在常见的解法有三种,各有各的代价:
- 把历史全塞进提示词 —— 越塞越贵,而且模型会忽略中间段("lost in the middle")
- 每次对话都把历史丢给 LLM 做摘要 —— 每轮烧 token,还会丢信息
- 纯向量检索 —— 能查"相似的",但分不清"三年前的随口一提"和"昨天差点弄坏系统的教训"
这个项目走第四条路:
记忆放在本地,靠查询取用,遗忘是设计而不是 bug。
- 会话开始只读一页「当前状态」(几百字),不是整段历史
- 需要细节时现查(
recall),不是每轮都带 - 记过的坑会在动手之前主动拦你(
brief),不是等你想起
跟别的方案有什么不同
| 方案 | 它回答什么 | 本项目的区别 |
|---|---|---|
| 向量数据库(Chroma / Pinecone / Qdrant) | "哪几条和我最像" | 只看相似度。没有时间、没有权重、不会遗忘 —— 三年前的随口一提和昨天的教训等权 |
| 知识图谱(Neo4j / Graphiti) | "实体之间什么关系" | 要先定义 schema。本项目不预设任何实体,结构是从事件里长出来的 |
| RAG 流水线(LangChain 那类) | "从文档里捞相关的段落喂给模型" | RAG 是只读管道。本项目是可写、会衰减、会自省的记忆体 |
| agent 记忆层(Mem0 / Letta/MemGPT) | 同类问题 | 它们靠调用 LLM 来管理记忆;本项目的检索是纯本地词法 + 可选向量,不调 LLM,一次查询几十毫秒 |
| 把历史全塞进提示词 | —— | 越塞越贵;而且塞得越满,模型越容易忽略中间内容 |
一句话区别:别人在优化「怎么找到」,这个项目在优化「找到之后该不该信」。
一分钟看懂数据怎么流
写 remember ──────────────► events ← 唯一真相,只有这里会写错
│
派生 episode.py 分段 │ 全是派生视图
consolidate 提炼事实/程序 │ 随时可以整个删掉重建
embed.py 算向量 │
assoc.py 建语义关联 ▼
读 recall ── 事件 / 事实 / 程序 三层一起出
brief ── 动手前的简报:禁令、步骤、教训、同类事故、风险
忘 forget ── 衰减(降权)→ 休眠(不参与检索)
distill ── 提炼正文(压缩,不删条目)
守 health ── 体检(表/派生一致性/孤儿引用/备份新鲜度…)
eval ── 检索评测,改检索必须跑前后对比
为什么 events 是唯一真相:只有一处会写错,修一处就够。派生视图坏了直接重建, 不用担心"哪个是真数据"。这条约束贯穿全部代码。
给 AI agent 的速览
把下面这段直接放进系统提示,agent 就知道该怎么用:
你有一个本地记忆库(brain),命令是 `python brain.py <cmd>`。
★ 四件事必须在动手前查:
1. 要报数字 → 先跑命令,不凭印象
2. 提到"之前/上次/我们说过" → recall "关键词"
3. 要改配置 / 删东西 / 动生产 → brief --about "我要做什么"
4. 冒出"应该/大概/可能" → 那是没查的信号
★ 五件事做完必须写:
remember --kind accident|correction|decision|learn|done --title "一句话"
★ 判据:只记"发生了什么 + 结论",不记"我复查了一遍"这种流水账。
★ 不确定就说不知道,不用"可能"填空。错了就认,不复述不找台阶。
这段不是装饰。这个项目最初就是为了解决"agent 明明记过,下次照样犯"这个具体问题。
三条设计原则
| 原则 | 具体 | 为什么 |
|---|---|---|
| events 是唯一真相 | 事实 / 情节段 / 程序 / 向量全是派生视图,随时可重建 | 只有一处会写错,修一处就够 |
| 记忆会遗忘 | 衰减(降权)→ 休眠(不参与检索)→ 提炼(压缩正文);事故与教训永久保护 | 只增不减的库最后全是噪音 |
| 检索有绝对尺子 | 自带评测集(精确 / 模糊 / 否定三类),改检索必须跑前后对比 | 凭感觉调参必然越调越差 |
第三条尤其重要。这个项目自己的历史里,有四次"以为改好了、实际更差"的回退 (换更大的向量模型、融合两路排序、加二次重排、调阈值),全部靠评测集当场打回。 没有那把尺子,四种退化会一起上线。
快速开始
# 1. 建库(首次运行自动建表)
python brain.py stats
# 2. 记一件事
python brain.py remember --kind accident --title "改配置把服务弄挂了" --weight 95
# 3. 查
python brain.py recall "配置改坏了"
# 4. 动手前先问一嘴:这类事我以前出过什么事?
python brain.py brief --about "要改线上配置了"
只要 Python 3.8+ 和标准库(sqlite3、json)。没有第三方依赖。
命令
| 命令 | 作用 |
|---|---|
remember |
写一条事件(唯一写入点) |
recall |
检索(事件 / 事实 / 程序三层一起出) |
brief |
动手前的简报:禁令、步骤、教训、同类事故、风险等级 |
decide |
决策留痕:备选 / 选了谁 / 为什么 |
drop |
作废一条记错的(不物理删除,留痕并可追溯) |
working |
当下该注意什么(含警觉度与情绪档位) |
forget |
衰减与休眠(默认 dry-run) |
distill |
提炼正文(默认 dry-run) |
rehearse |
预演:这件事做过几次、出过几次事 |
review |
定期回看:最近 N 天哪些事改变了我 |
source |
按时间回原始对话取证 |
backup |
在线快照(不锁库,自带轮转) |
proc / proc-add |
查 / 记一套步骤(这类事该怎么做、错在哪一步) |
派生视图(需要时单独跑):
python episode.py --apply # 情景分段
python consolidate.py --apply # 提炼事实与程序
python assoc.py --build # 建语义关联边
可选:语义检索
默认是纯词法(FTS5 + IDF 加权覆盖率)。想要"换个说法也能搜到",装向量层:
pip install torch transformers numpy
python embed.py --build # 建索引(首次自动下载 bge-small-zh,约 92 MB)
python brain.py recall "..." # 词法覆盖率低时自动走向量
实现细节值得说明:这不是"词法 + 向量两路融合投票",而是级联—— 先跑词法,只有当词面覆盖率低于阈值时才跑向量。原因是实测发现融合会引入 "融合税":两路都参与的题反而变差。级联的代价是可能漏掉"换个说法"的查询, 但它保住了那些精确匹配的题。
常驻服务(省掉每次加载模型的开销):python embed_server.py --start。
可选:接进 DSH(DeepSeek Harness)
仓库不含 DSH 插件代码——那部分跟宿主的插件体系绑死。 本项目最初就是长在 DSH 里的:插件负责「每轮注入一页自我」和「把命令暴露成工具」, 本仓库只提供那个被注入、被调用的引擎。
不带插件也能用:把「给 AI agent 的速览」那段塞进你的系统提示, agent 自己会在合适的时候调命令。
测试
python test_brain.py # 隔离沙盘跑完整链路:写入 / 检索 / 分段 / 衰减 / 保护 / 备份
python eval.py # 检索评测(题集见 examples/eval_cases.example.json)
python health.py # 体检(表层 + 数据 + 代码自检)
python health.py --selftest # 造坏样本,验证体检真的会红
python brain_audit.py # 对账:schema 里画的表,代码里有没有通往它的路
python brain_audit.py --selftest
test_brain.py 绝不碰你的真库:它在脚本同级建 .test-sand/,跑完删掉。
评测题集需要自己造——示例只演示格式,expect 里的 id 要换成你库里真实存在的。
一条经验:一条永远报 OK 的闸门比没有闸门更糟,因为它给人虚假的安心。 所以
health.py带--selftest:它注入坏数据,确认每个检查真的会失败。 新增检查时必须同步加夹具,否则不许合并。
环境变量
| 变量 | 默认 | 作用 |
|---|---|---|
BRAIN_DB |
同目录 brain.db |
数据库位置 |
BRAIN_EMBED_MODEL |
BAAI/bge-small-zh-v1.5 |
向量模型(HF 名或本地目录) |
BRAIN_EMBED_PORT |
7799 | 向量服务端口 |
BRAIN_EVAL_CASES |
eval_cases.json |
评测题集 |
版本
当前 v0.3.0(开发期,API 还会变)。改动记录见 CHANGELOG.md。
版本号遵循语义化版本:主.次.补丁 —— 不兼容的改动加主版本,向下兼容的新功能加次版本,修 bug 加补丁。
许可
AGPL-3.0。简单说:
- 你可以用、可以改、可以商用
- 但改了要开源,做成对外服务也要开源(这正是它和 MIT 的区别)
- 保留版权声明
选它而不是 MIT,是因为不想让「套壳闭源」和「拿去做成服务收费」变成合法行为。
用之前请读一眼 schema.sql——数据长什么样、哪些字段是派生视图,都在里面写着。
为什么没有做 pip 包
因为它不是库,是一个长在你自己电脑上的记忆体:有状态、会写盘、要备份。
装成包反而增加一层距离。直接用 git clone + python brain.py 最直白。
No comments yet. Be the first to write one.