项目地址： https://github.com/breath57/how-ai-agents-remember

---

如下图所示

起因

每个 AI Agent 框架都说自己有「记忆」。

但当我真的去问：它怎么记的？数据存在哪？下次对话怎么取出来？ —— 基本没有一个框架能把这件事讲清楚。

于是我花了两周时间，硬啃了 4 个火爆开源框架的记忆相关源码：

• 🦞 OpenClaw（TypeScript，22+ 渠道接入，插件架构）
• 🐈 nanobot（Python，~4,000 行，港大团队出品）
• ⚡ NullClaw（Zig，678KB 静态二进制，<2ms 冷启动）
• 🦀 OpenFang（Rust，137K LOC，知识图谱）

把每一条数据流都画出来，把每一个设计取舍都记录下来，写成了 36 篇技术文档，全部开源。

---

你会看到什么

🐈 nanobot —— 极简到极致

两个 Markdown 文件，搞定持久化记忆。

MEMORY.md    ← 长期事实，每次对话全量注入 system prompt
HISTORY.md   ← 事件日志，Agent 用 grep 按需检索

记忆写入的逻辑极其优雅：当对话上下文超过阈值，触发一次 LLM 调用，让模型自己提炼「这段对话里什么值得记住」，然后写回 Markdown 文件。

核心洞察：LLM 既是记忆的消费者，也是记忆的策展人。

这套方案的代码实现不超过 200 行，但经过生产验证。复刻成本极低。

---

⚡ NullClaw —— 工程化到极致

如果说 nanobot 是极简主义，NullClaw 就是企业级重炮。

它的检索管线是这样的：

用户输入
  → 查询扩展（同义词/子查询生成）
  → 多路召回（向量搜索 + 全文搜索 + 时间窗口）
  → RRF 融合（Reciprocal Rank Fusion）
  → 时间衰减权重
  → MMR 多样性重排
  → LLM 最终重排
  → 输出 Top-K 记忆

9 个阶段，一个都不少。

背后支撑 10 种可插拔的存储后端：SQLite、PostgreSQL、Redis、LanceDB、HTTP API……每个后端独立可替换。Embedding 提供者有熔断保护，检索策略支持 Shadow/Canary 灰度发布。

这是搜索引擎级别的记忆检索系统。

---

🦞 OpenClaw —— 插件优雅降级

OpenClaw 最有意思的设计是：Markdown 文件才是唯一真相源，数据库只是索引。

用户的记忆内容
  → 存储为 Markdown 文件（本地）
  → 异步建索引到 SQLite + sqlite-vec（向量）
  → 可选挂载 QMD 外部搜索引擎（主力）
       └─ 失败自动降级回内置 SQLite

6 种 Embedding 提供者（OpenAI、Gemini、Ollama 本地、Cohere……）按优先级自动选择，任意一个失败自动切换下一个。

数据库坏了？删掉重建，Markdown 文件还在，一键重新索引。存储层崩了不等于记忆丢了。

---

🦀 OpenFang —— Rust 极简底座

OpenFang 走了一条截然不同的路：一个 SQLite，搞定一切。

MemorySubstrate（统一门面）
├── StructuredStore    → KV 存储
├── SemanticStore      → 向量搜索（余弦相似度，BLOB 存储）
├── KnowledgeStore     → 知识图谱（三元组：Subject-Predicate-Object）
├── SessionStore       → 跨渠道会话（CanonicalSession 机制）
├── ConsolidationEngine → 记忆衰减与合并
└── UsageStore         → 用量遥测

6 个逻辑子存储，共享一个 SQLite（WAL 模式），通过 Arc<Mutex<Connection>> 并发安全访问。启动时自动执行 7 次 Schema 迁移。零外部依赖。

其中最值得借鉴的是知识图谱 + 记忆衰减的组合：

• 实体关系以三元组存储（我 → 工作于 → 小米）
• 每条记忆有置信度分数，7 天后自动衰减
• ConsolidationEngine 周期性合并相似记忆、清理低置信度条目

这是「记住」和「存储」之间最本质的区别。

---

横向对比

	🐈 nanobot	⚡ NullClaw	🦞 OpenClaw	🦀 OpenFang
语言	Python	Zig	TypeScript	Rust
存储	Markdown 文件	10 种后端	SQLite + Markdown	单一 SQLite
向量搜索	❌ grep	✅ 多提供者 + 熔断	✅ 6 种 + 降级	✅ 余弦 (BLOB)
知识图谱	❌	❌	❌	✅ 三元组
记忆衰减	❌	✅ 时间衰减	❌	✅ 置信度衰减
复杂度	⭐	⭐⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐
推荐场景	快速原型	企业级	插件生态	嵌入式/Rust

---

我们总结出的 5 条规律

读完这 4 个框架，有几件事是所有人都做对了的：

1. 每个系统都有两个时钟
短期的（会话/对话）和长期的（持久化事实）。区别只在于它们如何在两者之间架桥。

2. 让 LLM 自己决定记什么
4 个框架全都用 LLM 来判断什么值得记住。基于规则的信息提取扛不住复杂对话。

3. 检索比存储难 10 倍
把记忆存进去很简单。在正确的时间取出正确的记忆，才是真正的工程挑战。NullClaw 的 9 阶段管线就是最好的证明。

4. 优雅降级是刚需
Embedding API 会超时，数据库会损坏。每个生产系统都需要一条降级路径。OpenClaw 的双引擎、NullClaw 的熔断器，都是为此而生。

5. 记忆衰减比你想象的重要
没有衰减，旧的无关记忆会挤掉新的重要信息。OpenFang 基于置信度的衰减机制，是这 4 个框架里最值得借鉴的设计之一。

---

项目结构

how-ai-agents-remember/
├── README.md          ← 中文总览（本文简化版）
├── README.en.md       ← English version
├── nanobot/           # 7 篇文档
├── nullclaw/          # 9 篇文档
├── openclaw/          # 10 篇文档
└── openfang/          # 10 篇文档

每个框架目录下都有：

• 架构总览 —— 分层图、组件关系、核心数据流
• 数据模型 —— Schema 定义、类型结构、存储格式
• 检索机制 —— 从用户输入到记忆命中的完整路径
• 生命周期 —— 整合、衰减、清理
• 复刻指南 —— 在你自己的技术栈中重建这套系统的分步方案

所有架构图用 Mermaid 绘制，GitHub 原生渲染，不依赖任何外部图片。

---

最后

这个项目不是综述，不是推荐列表，也不是营销文章。

它是两周读源码的产物，记录了这 4 个框架里每一个非显而易见的设计决策。如果你在做或者打算做 AI Agent 的记忆系统，这 36 篇文档能帮你省下大量重复劳动。

如果对你有帮助，欢迎给个 ⭐

https://github.com/breath57/how-ai-agents-remember

---

标签：AI Agent 记忆系统 LangGraph OpenClaw nanobot 向量搜索 知识图谱 开源

---

直接复制粘贴到 CSDN 编辑器（选 Markdown 模式）即可，标签建议都加上，有助于搜索收录。