membrain-lite

给聊天机器人用的最小记忆内核：会记、会想、会忘。

不是向量数据库的封装，也不是 RAG 模板。它解决的问题是：

一个天天陪你聊天的机器人，三个月后还记不记得你讨厌什么。

核心只有三件事：

1. 写入有取舍 —— 只存「以后用得上」的，一句话能说完就不写一段。

2. 召回有分层 —— 关键词、语义、重要性、新鲜度、图谱五路加权。

3. 遗忘有曲线 —— 不是删掉，是越来越难想起来（三层：习惯 / 可逐渐遗忘 / 边缘）。

零依赖可跑（纯标准库 + SQLite），2 分钟能看到效果。

🤖 如果你是一个 AI agent（DSH / Claude / Codex / Cursor），先读 docs/AGENT-GUIDE.md（中文）或 docs/AGENT-GUIDE.en.md（English）。 那里面是给机器看的：怎么装、文件怎么摆、什么该记什么不该记、怎么调参、 以及装完之后该跟你的主人说什么。这份 README 是给人看的。

三分钟上手（傻瓜版）

不想装、不想配、不想懂 Python 也行：

1. 点右上角绿色的 Code → Download ZIP，解压到任意文件夹；

2. 双击里面的 一键体验.bat（Windows）；

3. 浏览器会自动打开一张会转的图 —— 那就是它的记忆长什么样。

脚本做的事：写入 29 条示例记忆 → 导成图用的数据 → 起一个本地网页 → 打开浏览器。 关掉那个黑窗口，服务就停了。

macOS / Linux 用户：终端里进到目录，跑 python3 -m membrain demo && python3 -m membrain export --out examples/radial/memories.jsonl && python3 -m http.server 8766， 然后打开 http://127.0.0.1:8766/examples/radial/。 需要 Python 3.9+，除了标准库什么都不用装。 （想用 config.toml 改权重/半衰期的话要 3.11+：读配置用的是 tomllib， 低版本会静默忽略配置文件、只跑默认值。）

Related MCP server: Memory Dream Engine

命令行怎么用

python -m membrain init          # 建库
python -m membrain demo          # 写入 29 条示例记忆
python -m membrain recall "阿宁讨厌什么" --explain
python -m membrain eval          # 跑评估集

recall 的输出长这样：

[0.678] (fact) 阿宁讨厌被叫笨蛋，也讨厌被说「你这样不行」
        why: {"semantic": 0.424, "keyword": 0.6, "importance": 0.92,
              "recency": 1.0, "graph": 0.333, "neighbor": false}

--explain 会把每一路的分都摊开，调参时看它，排查「她为什么想起这个」也看它。

它是怎么打分的

score = 语义 * 0.18
      + 关键词 * 0.46
      + 重要度 * 0.14
      + 新鲜度 * 0.11
      + 图谱   * 0.11

几个刻意的选择：

• 关键词权重最高（0.46）。中文场景里，用户问「阿宁讨厌什么」， 真正命中的是「讨厌」两个字，语义向量经常被高频词带偏。

• 语义只用哈希向量兜底。缺省不下载模型，Embedder(model="bge-m3") 可以换成真的 embedding（需要 sentence-transformers）。

• 新鲜度是指数衰减，不是线性：s = 0.5 ** (age_days / 半衰期)。

• 图谱分 = 与种子记忆共享的实体数 / 3，加上邻居记忆的兜底分。

权重、半衰期、去重阈值全在 config.py 的 Weights / Decay， 改完跑一遍 python -m membrain eval 就知道有没有变差。

遗忘：三层与半衰期

• 被想起 5 次以上 且强度够 → 进 habit（习惯层），基本不会掉

• 强度掉到 0.18 以下 → 进 edge（边缘层），还查得到但排得靠后

• 超过 archive_after_days（默认 400 天）→ 归档，不参与召回

python -m membrain tick 手动跑一次衰减（生产环境用 cron 每天一次）。

接进你的机器人

from membrain.config import Config
from membrain.engine import Engine

eng = Engine(Config.load("config.toml"))

eng.remember("阿宁讨厌被叫笨蛋", kind="fact", importance=0.9,
             who="阿宁", topic="边界")
items = eng.recall("阿宁讨厌什么", k=5)      # 召回
brief = eng.brief()                          # 唤醒时注入的那一小段

或者直接起 HTTP 服务（标准库，无框架）：

python -m membrain serve --port 8765

GET  /health                  → {"ok": true, "counts": {...}}
GET  /brief                   → {"ok": true, "text": "【关于阿宁的几条硬记忆】…"}
POST /recall   {"query": "…", "k": 5, "explain": true}
POST /remember {"text": "…", "kind": "fact", "importance": 0.9}
POST /tick

会话隔离是硬规矩：每条记忆都带 scope（group:123 / private:456）， recall(scope=...) 只返回同 scope + global 的。群里的记忆不要带去别的群。

装进 DSH / Claude Desktop（MCP）

上面那段是「自己写代码接」。如果你用的是支持 MCP 的客户端（DeepSeek Harness、Claude Desktop 等）， 不用写代码 —— 把 membrain.mcp 当成一个 stdio MCP server 挂上去就行，工具会以 mcp__membrain__remember / mcp__membrain__recall / mcp__membrain__brief 出现。

它只用标准库实现，不需要 pip install mcp。

DeepSeek Harness —— 编辑 ~/.dsh/profiles/web/cordis.patch.yml，在末尾加一段：

- insert:
    - id: mcp-membrain-lite
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: membrain
        transport: stdio
        command: 'C:\Python312\python.exe'          # 换成你自己的：Windows 用 where python，macOS/Linux 用 which python3
        args:
          - '-m'
          - 'membrain.mcp'
        cwd: 'C:\path\to\membrain-lite'             # 换成你解压/克隆的仓库路径
        env:
          PYTHONIOENCODING: 'utf-8'
          MEMBRAIN_HOME: 'C:\path\to\membrain-lite\.membrain'
        toolCallTimeoutMs: 60000

serverName 不能和已有的重名（比如你已经挂了 memory，这里就用 membrain）。 改完重启 DSH（或让它热重载），工具列表里就会出现 membrain 这一家。

Claude Desktop —— claude_desktop_config.json：

{
  "mcpServers": {
    "membrain": {
      "command": "C:/Python312/python.exe",
      "args": ["-m", "membrain.mcp"],
      "cwd": "C:/path/to/membrain-lite",
      "env": { "MEMBRAIN_HOME": "C:/path/to/membrain-lite/.membrain" }
    }
  }
}

自测（不装客户端也能验证协议通不通）：

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| python -m membrain.mcp

正常会吐两行 JSON：先是 serverInfo，再是 5 个工具（remember / recall / brief / tick / stats）。

让别人家的 AI 自己装

如果你不想自己动手，可以把仓库链接丢给你的 AI（DSH / Claude / Codex 都行），让它读：

docs/AGENT-GUIDE.md —— 写给 AI agent 的安装与维护指南（中文） docs/AGENT-GUIDE.en.md —— Agent Install & Maintenance Guide (English) docs/SETUP-CHECK.md —— 设置阶段自检清单（命令版，专治 404 / 死引用）

两份内容逐节对应，按你的 agent 习惯的语言挑一份就行；每份顶部都链着另一份。

那里面是机器视角的完整流程：

• 开始干活之前先跑 docs/SETUP-CHECK.md：一条 python scripts/check_links.py 把文档里的死链、缺文件和骨架缺失全打出来，有 404 当场修或替换，别带着坏引用往前做；

• 怎么装、怎么验活、cordis.patch.yml 里 serverName 不能跟已有的 memory 重名；

• 文件怎么摆（代码 / 数据 / 备份三分，只有 brain.sqlite 必须备份）；

• 什么该 remember、什么别记、kind 和 importance 怎么给、scope 为什么是硬规矩；

• 怎么用 eval 驱动优化，而不是凭感觉调参；

• 一张真实踩过的坑表（BOM、sqlite3.Row、去重、跨会话泄漏……）；

• 最后一段是「请转告你的主人」：一段可以直接念给主人听的白话，加 5 条要提醒的事。

零依赖、不改你的说话习惯、数据只在自己机器上——这几句 AI 会替你解释清楚。

话术模板

prompts/ 下是配套的基础话术，直接抄进你的 system prompt：

这几份比代码更值钱。人格和记忆要解耦：换人格不用动记忆，换记忆不用动人格。

文件结构

membrain/
  config.py    权重、半衰期、路径（tomllib 读 config.toml）
  store.py     SQLite：memories / vectors / entities / links / meta
  embed.py     向量（默认 char-bigram 哈希，可选 sentence-transformers）
  decay.py     遗忘曲线与层级
  engine.py    remember / recall / tick / brief
  mirror.py    导出成人能读的 markdown（记忆速查、人物、话题、日记）
  api.py       标准库 HTTP 服务
  cli.py       命令行
  mcp.py       MCP server（stdio，零依赖，给 DSH / Claude Desktop 用）
  evalrun.py   评估（recall@1 / @3）
prompts/       五份话术模板
data/          seed_demo.jsonl 示例数据（29 条）
eval/          cases.jsonl 评估集
tests/         单元测试
examples/radial/  记忆放射图网页（零依赖）
docs/          架构说明、隐私说明、**给 AI agent 的安装指南（中 / 英）**
scripts/       backup.py（一致性快照备份 + 轮转）、import_from_old_store.py（从旧库迁移）、
               check_privacy.py（公开前查隐私）、check_links.py（设置阶段查死链/缺文件）

演示：记忆放射图

examples/radial/ 里有一个零依赖的网页（纯 canvas，没有 CDN、没有构建）：

• 内圈是被反复想起的（habit），中圈在慢慢淡（fading），外圈最早被忘掉（edge）；

• 颜色是记忆类型：事件 / 事实 / 反思 / 技能 / 道理；

• 菱形孤岛是实体（人、群、话题），连线表示这条记忆提到了它；

• 拖拽旋转、滚轮缩放、悬停看详情、点图例按类型隐藏、搜索框高亮命中。

（静态版：docs/screenshot-radial.png）

跑起来，一行就够（Windows 之外）：

python -m membrain demo && python -m membrain export --out examples/radial/memories.jsonl && python -m http.server 8766

Windows 直接双击 一键体验.bat。想看某个固定角度，可以加 URL 参数：

http://127.0.0.1:8766/examples/radial/#yaw=120&pitch=-18&auto=0&zoom=1.1

页面直接 fetch('memories.jsonl')；直接双击打开（file://）会被浏览器拦， 所以页面里内置了一份示例数据兜底 —— 打开就能看见效果。

设计取舍（为什么不做成别的样子）

• 为什么不用向量库？ 几万条记忆用 SQLite 足够，numpy 都不需要。 真正难的是打分和遗忘，不是存储。

• 为什么不默认下载 embedding 模型？ 骨架要能 pip install 完就跑。

• 为什么把「忘」做成三层而不是删？ 删了就真的没了； 分层的意义是「还查得到，但排在后面」——这才像人。

• 为什么话术单独放 md？ 代码里写死人格，改一次要发版。

路线图

• 核心：写入 / 五路召回 / 衰减 / 镜像 / HTTP / CLI / 评估

• 话术模板五件套

• 多人格（同一份记忆，多套 prompts）

• 记忆冲突检测（同一件事两种说法，标出来给人判断）

• 导出为 JSONL 增量备份

• 一个最小 Web 演示页（记忆放射图）

已知局限（说实话）

• 中文两字词靠字面命中。缺省哈希向量对「熬夜 vs 半夜」这种同义改写几乎无能， 真正的语义召回要自己接 sentence-transformers（pip install .[embed]）。

• 评估集只有 8 条，100% 只是「没写崩」，不代表好用。 真想调准，扩到 40 条以上，覆盖「该想起却想不起」的反例。

• 没做冲突检测。同一件事两种说法会并存，谁排前面看分数。

• 抽取靠调用方。remember() 只负责「存好」，把一段对话切成几条是上层的事。

隐私

仓库里的示例数据全是编的（小满 / 阿宁 / 阿吉 / 老周 / 阳台种菜群）， 没有真实 QQ 号、真实群名或真实聊天记录，详见 docs/PRIVACY.md。

自己往里加数据以后，提交前跑一下：

python scripts/check_privacy.py

它会扫私人称呼、凭据形态、手机号/QQ 号，命中就返回非零。

许可

MIT。拿去用，改，卖都行，别来找我。

如果它对你有用，告诉我一声你拿它做了什么 —— 比 star 有意思。