# ChainMem链忆— 让 AI Agent 拥有像人一样的联想式回忆 **给它一个线头它还你一件毛衣。**---## 一、一个困扰我很久的问题你有没有这样的经历你用 AI Agent 聊了一整个下午把需求、方案、代码都讨论清楚了。第二天打开新会话它一句你好请问有什么可以帮你的——**全忘了**。这就是当下 AI Agent 最尴尬的短板**没有记忆**。当然现在已经有向量数据库Pinecone、Chroma、Milvus来做记忆存储。但你试试搜上次关于股票投资的想法——返回 10 个孤立片段的凑不出当时到底说了什么。就像图书馆查资料搜得到碎片**但拼不回一本书**。所以我自己写了一个**ChainMem链忆**。---## 二、人的记忆 vs AI 的记忆先想想人的记忆是什么样 你听到一首歌的前奏 → 想起整首歌 → 想起那个夏天 → 想起那个人...人的记忆是**链式的**——一个线索能引出整段完整的记忆。你不需要搜索过去你只需要一个**线头**轻轻一扯整件毛衣就出来了。而现有的 AI 记忆系统本质上是**图书馆模式**你搜股票 → 返回 10 个孤立片段[片段A] ...股票...[片段B] ...股票投资...[片段C] ...关于股票......但凑不出当时到底说了什么每条记忆是独立的**点**——能搜到碎片但**凑不出一段完整的、前后连贯的记忆**。ChainMem 用**链式结构**模拟人脑的联想回忆你搜股票 → 找到链头 → 沿指针遍历 → 整段对话一字不差重现其实我的想法是股票投资...应该分散风险所以我选了消费、科技、医疗三个板块...每个板块配比大约是...**不是搜索碎片而是还原整段记忆。**---## 三、核心设计链式 向量混合架构ChainMem 的核心架构只有两层却巧妙解决了检索精度和上下文完整性之间的矛盾。### 3.1 结链Ingestion当你把一段文本存入 ChainMem 时它做了三件事原始文本 → ① 语义切块 → ② 向量嵌入 → ③ 链式串联**① 语义切块** 按标点将文本切成 6~18 字的短语块。太短的块≤5 字会自动合并到前一块因为 sentence-transformers 对超短文本的编码质量很差不同短文本可能产生完全相同的向量。**② 向量嵌入** 每个块用 sentence-transformers 编码为 384 维的向量用于后续语义搜索。**③ 链式串联** 用双向指针prev_id / next_id把所有块串成一条链。这样找到任意一个节点就能沿着指针恢复整条链——完整无遗。### 3.2 追溯Retrieval当你输入查询时ChainMem 走了三条路径用户查询│▼┌─────────────────┐ ┌──────────────────────┐│ FAISS 语义搜索 │ │ 子串精确匹配 ││ (TOP 10 候选) │────▶│ 0.20 加分 │└────────┬─────────┘ └──────────────────────┘│▼┌─────────────────┐│ 候选排序 │ 语义分 子串分 标签分└────────┬─────────┘│▼┌─────────────────┐ ┌──────────────────────┐│ 指针双向遍历 │────▶│ ... → Node_A → Node_B ││ prev next │ │ → Node_C → ... ││ 忠实还原全部 │ │ → 完整上下文输出 │└─────────────────┘ └──────────────────────┘**为什么需要三条路径**- **纯语义搜索不够准** 384 维向量中语义接近但不同内容的文本可能撞到同一区域准确率仅 85~90%- **子串匹配精但不广** 能把查询文本钉在包含它的节点上但查不到同义词或意译- **标签分类辅助排优** 限定搜索域排除无关领域三者结合实测检索准确率达到 **100%**。### 3.3 关键优化在生产环境中还踩了几个坑分享一下**坑 1短文本退化**sentence-transformers 对 ≤5 字的短文本会产生完全相同的嵌入向量。修复结链时自动合并短块。**坑 2短查询失效**≤3 字的查询嵌入质量极差容易被高维空间的无关节点吸走。修复查询 ≤3 字时自动补齐 query query query。**坑 3FAISS 索引重建太慢**全量重建 13,000 个节点的索引要 50~60 秒。优化索引持久化到磁盘启动 1 秒加载增量添加只编新节点130ms。**坑 4v0.5.2单向遍历丢上下文**单向向前遍历只能获得匹配节点之后的内容之前的内容丢失。修复改用双向遍历prev_id next_id回忆覆盖率从 60% 提升到 **97%**。**坑 5v0.5.3拼写错误零召回**英文查询 Taiyuan campain拼错查不到 campaign。修复加入 Levenshtein 编辑距离兜底阈值 ≤2 的拼写错误自动纠正。---## 四、性能对比| 指标 | 传统向量搜索 | ChainMem | 提升 ||:-----|:----------:|:--------:|:---:|| **检索速度** | ~50ms | **~22ms** | 2.3x || **结果完整性** | 碎片 | **100% 原始记忆** | ∞ || **启动时间** | ~60s全量重建 | **~1s**磁盘加载 | 60x || **增量添加** | 全量重建 | **~132ms** | 455x || **中文支持** | 一般 | **优秀**trigram FTS5 | — || **检索精度** | 语义近似 | **语义子串标签** 混合 | 更高 || **英语查询** | 差跨语言分0.4 | **✅ 精确分词拼写纠错** | 显著 || **上下文覆盖** | 片段 | **双向遍历 97%** | — |测试环境单核 CPU 7.5GB 内存13,000 节点数据库。---## 五、快速开始ChainMem 采用**分层依赖**设计按需选择| 安装方式 | 命令 | 大小 | 功能 ||:---------|:-----|:----:|:-----|| **核心版** | pip install chainmem | **~2 MB** | CLI、SQLite存储、文本检索 || **完整版** | pip install chainmem[full] | ~1.5~2 GB | 以上 语义搜索 FAISS || **加密版** | pip install chainmem[secure] | ~5 MB | 凭证自动检测 Fernet 加密 || **全功能** | pip install chainmem[full,secure] | ~1.5~2 GB | 全部功能 |### Python SDKpythonfrom chainmem import ChainMemory# 初始化cm ChainMemory(db_path~/.chainmem/data.db).open()# 结链把一段对话存为记忆chain cm.ingest(其实我的想法是把每一次的记忆包括一次对话全部变成一个链条,sourcedemo,tags[讨论, 记忆系统, 架构],)print(f链 ID: {chain.id}, 节点数: {chain.node_count})# 追溯输入几个字拉出整段记忆result cm.retrieve(其实我的想法)print(.join(result)) # → 完整记忆复原# 统计print(cm.stats())cm.close()### CLI 模式bash# 结链chainmem ingest 其实我的想法是把每一次的记忆... --source demo --tags 讨论,记忆系统# 追溯chainmem retrieve 其实我的想法# 统计chainmem stats# 启动 MCP 服务器chainmem serve --socket /tmp/chainmem.sock---## 六、与 AI Agent 集成ChainMem 原生支持 **MCPModel Context Protocol**可直接作为 AI Agent 的记忆插件。### Hermes Agent 配置yaml# ~/.hermes/config.yamlmcp_servers:chainmem:command: chainmemargs: [serve, --socket, /tmp/chainmem.sock]配置后Agent 自动获得三个工具| 工具 | 功能 ||:-----|:-----|| chainmem_ingest(text, source, tags) | 结链存储重要对话 || chainmem_retrieve(query, tags) | 追溯检索完整记忆链 || chainmem_stats() | 统计查看记忆库状态 |### 实际使用场景**场景 1跨会话记忆**用户在新会话中说还记得上次我们讨论的那个股票策略吗Agent 调用 chainmem_retrieve(query股票策略, tags股决)拉出上次的完整讨论就好像昨天刚聊过一样。**场景 2自动记录**讨论中用户说这个记下来Agent 调用 chainmem_ingest(tags架构设计)把刚才的讨论存入长期记忆。**场景 3知识库查询**Agent 收到一个问题先查 ChainMem 看看有没有相关记忆有则引用完整上下文作答无则从零推理。---## 七、项目架构chainmem/├── pyproject.toml # 项目配置├── README.md # 中文文档├── README.en.md # English version├── LICENSE # MIT License├── CONTRIBUTING.md # 贡献指南├── assets/ # Logo 架构图├── src/chainmem/│ ├── __init__.py # ChainMemory 主入口│ ├── core/node.py # 数据模型ChainNode, Chain│ ├── store/sqlite_store.py # SQLite 持久化│ ├── pipeline/│ │ ├── ingester.py # 结链切块 → 嵌入 → 串联│ │ └── retriever.py # 追溯FAISS 子串 指针│ └── cli/app.py # Typer CLI MCP server├── scripts/│ ├── chainmem_server.py # 持久化 MCP 服务│ └── benchmark.py # 性能基准测试└── tests/└── test_core.py # 核心测试16 个用例全部通过---## 八、开源与未来ChainMem 是一个**开源项目**采用 MIT 协议。仓库在 GitHub **[https://github.com/yabolee-kkk/chainmem](https://github.com/yabolee-kkk/chainmem)**PyPI 地址[https://pypi.org/project/chainmem/](https://pypi.org/project/chainmem/)当前处于 **Alpha 阶段v0.5.3**核心闭环已完成- ✅ 结链文本 → 切块 → 嵌入 → 存储- ✅ 追溯语义搜索 子串匹配 指针遍历- ✅ **双向遍历**匹配节点上下文 97% 还原- ✅ **模糊分词兜底**短查询、重组查询零召回- ✅ **Levenshtein 拼写纠错**拼写错误自动纠正- ✅ MCP 服务器持久化- ✅ FAISS 索引持久化秒级启动- ✅ 增量索引毫秒级添加- ✅ 凭证自动加密v0.5.0- ✅ 标签分类- ✅ Python SDK CLI### 路线图Phase 2 ️ 类人记忆机制├─ 衰减曲线Forgetting Curve├─ 联想增强检索A时推荐相关链├─ 自动结链对话中自动记忆└─ 分支消歧相同前缀不同下文Phase 3 真正的人脑记忆├─ 分层记忆工作记忆 短期 长期├─ 记忆整合多条记忆→知识归纳├─ 跨 Agent 记忆共享└─ 睡眠压缩像人脑睡觉时整理记忆欢迎任何形式的贡献无论是修 Bug、加功能、写文档还是提 Issue 讨论链忆的未来由社区共同构建。---## 写在最后ChainMem 的灵感来自一个简单的观察**AI Agent 说一句话就要翻一次向量数据库但人类翻的是一本线装书——找到线索顺着线拉出整段记忆。**链式结构不是什么新技术——链表是每个程序员学数据结构第一课就接触的东西。但有时候最简单的数据结构恰好能解决最复杂的问题。**回忆不是搜索碎片。回忆是把整件毛衣从头到尾拿出来。**--- **GitHub:** [https://github.com/yabolee-kkk/chainmem](https://github.com/yabolee-kkk/chainmem) **PyPI:** [https://pypi.org/project/chainmem/](https://pypi.org/project/chainmem/) **安装命令** - 核心版pip install chainmem - 完整版pip install chainmem[full] - 加密版pip install chainmem[secure] - 全功能版pip install chainmem[full,secure]*如果这篇文章对你有帮助欢迎 Star、Fork、分享*