nanobot源码解析（四）：Markdown驱动的记忆系统

type

Post

status

Published

date

Mar 12, 2026

slug

nanobot-source-code-analysis-4

summary

本文深入拆解 Agent 框架 nanobot 的核心记忆系统。不同于传统向量数据库方案，nanobot 采用独特的纯 Markdown 驱动设计，通过 MEMORY.md（事实库）与 HISTORY.md（日志库）构建两层架构，配合 AI 主动更新与异步固化机制，实现了透明、轻量且可控的个人 Agent 长期记忆。文章详细解析了记忆的“自我固化”流程，并对比了 Markdown 方案与主流向量数据库（如 mem0）的优劣，为开发者探索个人 AI 助手的高效记忆构建思路提供了务实的极简主义参考。

1. 记忆的两层架构：事实与日志

nanobot 的记忆系统（nanobot/agent/memory.py）采用了精妙的两层架构，分别对应不同的存储需求：

第一层：MEMORY.md（长期事实） 这是 Agent 的“知识库”。它存储的是经过提炼的、持久的事实。例如： - “用户的名字是肥肥旭。” - “用户更喜欢使用 Python 进行开发。” - “项目 A 的部署地址是 xxx。”

第二层：HISTORY.md（搜索日志） 这是 Agent 的“流水账”。它存储的是过去对话的简要总结，按时间顺序排列。它的作用是提供上下文线索，方便通过简单的 grep 搜索来找回细节。

2. nanobog记忆逻辑

1. 主动触发（基于模型判断）

当模型认为当前对话中出现了需要长期记忆的信息时，它会主动读取 MEMORY.md 文件，并使用 edit_file 工具进行更新。

执行流程示例（以用户输入“我喜欢王楚然”为例）：

第一步：模型判断需要了解当前记忆，调用 read_file 读取 MEMORY.md。

第二步：模型判断需要更新记忆，调用 edit_file 将“Likes Wang Churan (王楚然)”写入文件。

第三步：模型回复用户确认信息。

MEMORY.md文件变更对比：

2. 条件触发（系统自动维护）

核心机制：记忆固化（Consolidation），下面两种情况会触发记忆固化逻辑：

基于消息阈值：在 nanobot/agent/loop.py 的 _process_message 方法中，系统会实时计算当前会话中“未固化的消息数量”： unconsolidated = len(session.messages) - session.last_consolidated 当这个数量达到或超过设定的阈值（memory_window，默认为 100）时，且当前没有正在进行的固化任务，系统就会自动启动异步固化流程。

手动执行 /new 命令：当你输入 /new 命令开启新会话时，系统会强制对当前会话中尚未固化的所有消息进行一次“归档式”固化，确保旧会话的上下文被妥善保存到 MEMORY.md 和 HISTORY.md 中，然后再清空当前会话。

固化流程：AI 的自我总结，我以/new命令来看一下具体的固化逻辑 固化的核心逻辑在nanobot/agent/memory.py中的consolidate方法，这是一个非常“元”的过程：nanobot 会启动一个专门的记忆固化 Agent，并给它下达指令：

读取历史消息：取出即将被移出窗口的旧对话。会从workspace/sessions中读取session_name.jsonl历史对话，我这里总共是25条。

读取当前记忆：加载现有的 MEMORY.md 内容。

系统提示词和记忆固话提示词

系统提示词(system_prompt)：

记忆固话提示词(user_prompt)：这块内容比较长，这里只展示关键部分，将步骤1、步骤2中的内容结合起来，形成一个完整的提示词。

user_prompt中明确指明调用 save_memory 工具：

history_entry：要求 AI 将这段旧对话总结成 2-5 句话，存入 HISTORY.md。

memory_update：要求 AI 根据新对话更新 MEMORY.md。如果发现了新事实，就添加进去；如果旧事实有误，就修正它。

调用大模型，传入messages和tools：

获取大模型的回复：

解析大模型工具调用结果：

history_entry: 追加写入 workspace/memory/HISTORY.md

memory_update: 更新 workspace/memory/MEMORY.md

结束：

历史消息清除：旧对话从 workspace/sessions 中移除，释放空间。

返回给用户结果：“New session started.”

⚠️ 这里调用大模型的时候虽然传入了tool，但是并没有后续的tool执行步骤。只是利用了tool的特性，让大模型生成工具调用的参数。本质上通过调整提示词让大模型输出json格式一样能满足要求。

💡 深度解读：为什么我们要用 Tool Calling 做“假”工具调用？

nanobot 在这里通过 save_memory 工具调用来做记忆固化，本质上并不是为了“执行”一个物理操作，而是利用了 LLM 厂商对 Function Calling 接口的结构化 Schema 强制约束力。相比传统的“要求 LLM 输出 JSON 字符串”的 Prompt Engineering，这种模式在工程实践中具备显著优势： 1. Schema 的确定性与强制性：LLM 厂商针对工具调用接口进行了专门的 Fine-tuning，其输出被严格限制在定义好的 Schema 结构内，天然排除了 Markdown 标记、未闭合的括号或前后废话干扰。这使得写入文件的内容高度可预测，极大提升了系统的鲁棒性。 2. “零解析”架构：利用 SDK 直接获取结构化的 args 字典（Dict），无需开发者编写复杂的正则表达式或 JSON 解析器来处理不规范的 LLM 输出。这不仅降低了代码复杂度，也减少了因解析失败带来的潜在崩溃风险。

3. 开发者视角：如何观察记忆的演变？

如果你想观察这个过程，可以留意 ~/.nanobot/workspace/memory/ 目录下的变化。AI 记住了什么，一目了然。AI记错了，手动编辑一下即可。

每当对话达到一定长度，你会发现 HISTORY.md 多了一条带时间戳的记录，而 MEMORY.md 的内容也随之变得更加丰富。

4. nanobot记忆系统与主流记忆系统比如mem0的优缺点对比

将 nanobot 这种“纯 Markdown 驱动 + LLM 自我总结”的记忆系统，与目前主流 Agent 框架（如 mem0、LangChain、AutoGen 等普遍采用的 向量数据库 Vector DB + Embedding 检索 方案）进行对比，可以看出 nanobot 走的是一条“反直觉但极其务实”的极简主义路线。

比较维度	nanobot (纯 Markdown 驱动)	主流框架 (Vector DB / mem0)	核心差异分析
基础设施依赖	零依赖。仅需本地文件系统。	重度依赖。需部署 Chroma、Qdrant 等数据库服务。	nanobot 部署成本极低，开箱即用；传统框架运维成本高。
透明度与可干预性	100% 透明。用记事本即可打开、阅读、修改、删除。	黑盒状态。高维向量数据对人类不可读，难以精准修改。	nanobot 将控制权交还给人类；传统框架纠错困难。
上下文密度与冲突	高密度，无冲突。每次固化由大模型主动合并、覆盖旧事实。	易冲突，召回冗余。基于切片召回，新旧矛盾观点可能同时被喂给模型。	nanobot 保持“最新的一致状态”；传统框架容易让 AI“精神分裂”。
版本控制 (Git)	原生支持。直接 `git commit` 即可回滚或追踪记忆演变。	极难实现。向量数据库的状态回滚复杂且繁琐。	nanobot 让记忆成为代码/文档资产的一部分。
系统容量 (Scalability)	受限于模型上下文窗口。长期使用可能导致单文件过大，增加每次 API 成本。	几乎无上限。支持百万级文档，按需 Top-K 召回。	传统框架适合企业级海量知识库；nanobot 适合个人极客使用。
检索能力 (Retrieval)	关键词精确匹配。基于 `grep` 等传统搜索，无法理解语义。	强大的语义检索。通过 Embedding 支持模糊搜索和概念联想。	传统框架能“心领神会”；nanobot 必须“字面对应”。
细节保真度	有损压缩。大模型在定期固化（总结）时，会不可避免地丢失细枝末节。	无损全量保存。原汁原味地保留了用户的每一句原始对话。	传统框架是“录音笔”；nanobot 是“会议纪要”。

通过对比可以发现，nanobot 的记忆系统并不是为了解决“海量企业级知识库管理 (Enterprise RAG)”问题而设计的。它的核心受众是个人开发者和极客。对于个人 AI 助手而言，“懂我”、“透明”、“轻量不折腾”的优先级，远远高于“支持百万级文档检索”。

总结

nanobot 的记忆系统再次印证了它的设计哲学：用最简单的工具（Markdown + LLM 自我总结），实现最实用的功能。 它不追求技术的堆砌，而是追求人类对 AI 行为的可理解和可控制。