DSH HUB
HomePlugin StorePlugin PacksCommunityRankingsResourcesPublish Guide
Plugin source
Back to catalog

1luoyun /

1luoyun/dsh-brain-framework

Topic repository only

基于dsh环境制作,给 AI agent 用的类脑长期记忆:单文件 SQLite、事件是唯一真相、会遗忘(衰减/休眠/提炼)、题集评测。核心零依赖

★ 1 Stars0 Forks0 IssuesN/A Community rating0 Confirmed installs
View on GitHub
READMESource: master@43e898bb

brain — 一个会遗忘的类脑记忆库

给 AI agent 用的长期记忆。单文件 SQLite,零第三方依赖,事件是唯一真相。

它不是向量数据库,也不是知识图谱。它更像一个会老去的笔记本: 记进去的东西会衰减、会休眠、会被提炼,而事故和教训永不遗忘。


它到底解决什么

AI 每次会话都失忆。现在常见的解法有三种,各有各的代价:

  1. 把历史全塞进提示词 —— 越塞越贵,而且模型会忽略中间段("lost in the middle")
  2. 每次对话都把历史丢给 LLM 做摘要 —— 每轮烧 token,还会丢信息
  3. 纯向量检索 —— 能查"相似的",但分不清"三年前的随口一提"和"昨天差点弄坏系统的教训"

这个项目走第四条路:

记忆放在本地,靠查询取用,遗忘是设计而不是 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 最直白。

—/ 5

No ratings yet

Manifest verification required

Commit 43e898bbc86e

Community comments

No comments yet. Be the first to write one.

DSH HUB

A community index for DSH plugins. Not an official GitHub or DeepSeek AI product.

CommunityResourcesAPIAbout