开源Agent记忆系统推荐：透明可控的OpenClaw复刻版

2026-06-20阅读 0热度 0

ai 人工智能

揭秘OpenClaw记忆系统的精髓：我们开源了memsearch，让所有Agent都能拥有透明可控的记忆能力。

核心内容：
1. OpenClaw记忆系统的独特设计：透明、可编辑、可移植
2. memsearch如何将这套记忆系统抽离为轻量级插件
3. 开发者可快速集成，为Agent添加持久记忆功能

开源：我们复刻了OpenClaw的mem系统，为所有Agent打造透明、可控的记忆

最近OpenClaw全球刷屏，GitHub近20k stars的成绩背后，很多人都在关注它的多平台对话能力。但坦白说，它跨平台、跨会话的长期AI记忆系统设计，同样值得深挖。在OpenClaw里，AI会自动写daily logs并以md格式存储，人类可以手动维护、提炼长期原则——这让AI记忆变得可控、透明且管理高效。而正是这套记忆系统打动了我们，于是团队做了一件事：把它的核心设计抽离出来，做成memsearch——一个轻量级插件，让任何开发者都能给自家Agent加上持久、透明、可控的记忆，不必被OpenClaw的单一形态所限制。（项目已MIT开源，可直接商用。）

01 先搞懂：OpenClaw的记忆系统，到底牛在哪？

要理解OpenClaw的记忆，首先得分清两个容易混淆的概念：上下文和记忆。先说上下文，它主要包括四部分：静态+条件化的系统提示词、AGENTS.md和SOUL.md这类引导文件的项目上下文、过往的对话历史（包括消息、工具调用记录和压缩摘要），还有当下发的消息。简单说，每次给OpenClaw发请求时，agent能接收到的所有信息，整体内容更精简。

再来看看记忆——存在于本地磁盘的持久化数据，是历史会话、历史文件、用户偏好等的总和，采用全量存储。具体的记忆构建细节，本文不再展开，感兴趣的读者可以查阅相关拆解文章。其中最值得一提的，是OpenClaw的所有记忆都以Markdown格式存储在本地文件中——除了智能体自动写入，你也可以直接手动编辑这些md文件，而向量数据库只是派生索引。只要md文件修改并保存，系统会自动对新内容重新建立索引，无需额外操作。

这种模式相比Mem0、Zep等主流方案（把向量数据库当成唯一记忆来源），有三个明显优势：透明（MD格式，打开就知道AI记了什么）、可编辑（改完直接生效）、可移植（复制文件就能迁移）。但问题也很突出：想用这套记忆系统，你必须运行整个OpenClaw生态——Gateway进程、消息平台连接、工作区配置……对于只想给自家Agent加个持久记忆的开发者来说，门槛太高了。这正是memsearch的初衷：保留OpenClaw的核心记忆理念，去掉所有冗余，做成一个能插在任何Agent框架里的轻量化库。

02 memsearch核心思路：可编辑、插件化、高度透明

memsearch完全继承了OpenClaw的Markdown优先理念。你的所有AI记忆，都以明文形式存在本地文件夹里，结构清晰到不用查文档就能看懂：

~/your-project/
└── memory/
    ├── MEMORY.md              # 手写的长期记忆
    ├── 2026-02-09.md          # 今天的工作日志
    ├── 2026-02-08.md
    └── 2026-02-07.md

建立在此基础上，Milvus只是一个辅助工具，用来给Markdown内容建立索引，加快搜索速度。哪怕删掉向量数据库文件，只要Markdown还在，重新索引5分钟就能恢复所有记忆。记忆存在Markdown文件里——打开就能看懂AI记住了什么，vim改完自动重新索引，git clone就能带走。向量数据库（Milvus）只是个可重建的索引，随时可以删掉重来。

这样设计有几个实打实的好处。

好处1：透明可读，调试容易
传统方案：AI回答错了，你也不知道它记住了什么、为什么错。然后得写代码调API查数据库，看到的全是向量和JSON，根本看不懂语义。
memsearch方案：直接打开memory文件夹下的对应Markdown文件，就能看到AI的完整记忆：

## Morning
- Fixed N+1 query issue — switched to selectinload()
- Query count dropped from 152 to 3

如果AI说错话，可能是这段记忆过时了。vim改一下，保存，系统自动重新索引。5秒解决问题。

好处2：版本控制，团队协作
传统方案：记忆存在数据库里，谁改了什么、什么时候改的，只能查审计日志（很多方案甚至没有），协作成本极高。
memsearch方案：直接用Git管理Markdown文件，一行命令就能追溯所有修改记录：

git log memory/MEMORY.md
git diff HEAD~1 memory/2026-02-09.md

团队PR评审时，甚至能直接评审AI的记忆——比如有人新增了架构决策，有人修改了配置信息，所有变更都一目了然：

+ ## Architecture Decision
+ - Use Kafka for event bus instead of RabbitMQ
+ - Reason: better horizontal scaling

好处3：迁移自由，不被锁定
传统方案：如果用了Mem0想换Zep或其他记忆框架，就得导出数据、转换格式、重新导入，还可能出现字段不兼容，迁移一次要折腾大半天。
memsearch方案：记忆是纯明文Markdown，迁移零成本，不用改一行代码。

换电脑：用rsync复制memory文件夹，直接能用
换embedding模型：重新执行索引命令，5分钟搞定，Markdown文件不动
换向量数据库部署模式：只改一行配置，比如从本地切换到云端：

比如你在用Milvus Lite开发，部署到生产时要换成Zilliz Cloud：

开发环境
ms = MemSearch(milvus_uri="~/.memsearch/milvus.db")

生产环境（只改这一行）
ms = MemSearch(milvus_uri="https://xxx.zillizcloud.com")

markdown文件一个字都不用改。

好处4：人机共创，各司其职
传统方案：AI写记忆，人类要改，得懂API接口，写代码更新。
memsearch方案：

AI负责：自动生成每日日志（YYYY-MM-DD.md），记录琐碎的执行细节（比如“部署了v2.3.1，性能提升12%”）
人类负责：手动维护MEMORY.md，提炼长期有效的原则（比如“团队技术栈：Python+FastAPI+PostgreSQL”）

你和AI，本质上是在共同编辑同一套Markdown文档——不用懂代码，打开文件就能修改、补充。这种协作模式，在数据库方案里根本无法实现。

03 架构拆解：四大流程，看懂memsearch怎么工作

memsearch的核心工作流程有4个：Watch（监听）→ Index（索引）→ Search（搜索）→ Compact（压缩）。接下来逐个讲解。

流程1：Watch（监听文件变化）

这一流程用于监听memory文件夹下的所有Markdown文件。当你修改、保存文件后，系统会在1500ms后自动触发重新索引（去抖设计）。1500ms是个实操后的经验值——太短（比如100ms）会导致打字时频繁触发索引，浪费embedding API调用；太长（比如10秒）会影响体验，1500ms刚好平衡响应速度和资源消耗。启动watch进程后，你可以一边写代码，一边手动修改MEMORY.md（比如添加API文档地址），保存后不用重启服务，下一次AI查询就能用到新记忆。

流程2：Index（分块、去重、索引）

Index是memsearch的性能关键，主要做3件事：

第一，分块（Chunking）：按标题（heading）和段落切分。比如一个##标题+它的内容为一个chunk，语义边界更清晰，避免把“Redis配置”之类的表述切成两半导致语义不完整。比如这段markdown：

## Redis Caching
We use Redis for L1 cache with 5min TTL.
The connection pool is configured with max 100 connections.

## Database
PostgreSQL 16 is the primary database.

会被切成3个chunk：

- Chunk 1: "## Redis Caching\nWe use Redis for L1 cache..."
- Chunk 2: "## Database\nPostgreSQL 16 is the primary database."
- Chunk 3 可能是下一段内容

第二，去重（Dedup）：计算每个chunk的SHA-256哈希，重复内容只索引一次——比如两处都提到“PostgreSQL 16”，只调用一次embedding API，能省20%以上的成本（具体测算：500KB文本，去重后每月可省$0.15，大规模使用可省数百美元）。

第三，Chunk ID设计：格式为「hash(source_path:start_line:end_line:content_hash:model_version)」。这里面包含所有关键信息：哪个文件、文件的哪几行、内容的哈希值（用于去重）、用的哪个embedding模型。换embedding模型时，系统能自动识别过期索引，无需手动清理。

流程3：Search（混合搜索）

这里采用向量搜索（70%权重）+ BM25关键词搜索（30%权重）的混合模式，兼顾语义相似和精确匹配。如果你的查询偏向精确匹配（查错误码、函数名），可以提高BM25权重到50%。几个关键细节：

向量搜索：负责语义匹配，比如查询“Redis缓存配置”，能匹配到“Redis L1 cache with 5min TTL”（用词不同但语义一致）；
BM25搜索：负责精确匹配，比如查询“PostgreSQL 16”，不会匹配到“PostgreSQL 15”，适合查错误码、函数名；
渐进式披露：搜索返回Top-K（默认3）个chunk摘要（截断200字），需要时通过命令查看完整内容，节省LLM上下文窗口。

流程4：Compact（压缩旧记忆）

Agent运行久了，旧的记忆会占满上下文，增加成本也干扰大模型回答的准确率。Compact会调用LLM总结所有历史记忆，生成精简摘要，然后删除/归档原始文件。可手动触发，也可配置定时自动执行。

04 实操指南

memsearch支持Python API和CLI工具两种方式，适配不同开发场景。数据库选型建议如下：

Milvus Lite（默认）：本地 .db 文件，零配置，适合个人使用。
Milvus Server：自托管服务，支持多Agent共享数据，适合团队环境。
Zilliz Cloud：全托管，自动扩容、备份，适合生产环境。

开发时用Lite，部署时换Cloud，三种模式代码接口完全一致，改一个配置项就行。同时支持多种embedding提供商（OpenAI、Google、Voyage、Ollama、本地模型）。

第一步：快速安装

pip install memsearch

第二步：两种使用方式

方式1：Python API（集成到Agent框架）

一个完整的带记忆的Agent循环示例（可直接复制修改）：

from openai import OpenAI
from memsearch import MemSearch

llm = OpenAI()
ms = MemSearch(paths=["./memory/"])

async def agent_chat(user_input: str) -> str:
    # 1. Recall — 搜索相关记忆
    memories = await ms.search(user_input, top_k=3)
    context = "\n".join(f"- {m['content'][:200]}" for m in memories)
    
    # 2. Think — 调用 LLM
    resp = llm.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": f"Memories:\n{context}"},
            {"role": "user", "content": user_input},
        ],
    )
    
    # 3. Remember — 写入 markdown，更新索引
    sa ve_memory(f"## {user_input}\n{resp.choices[0].message.content}")
    await ms.index()
    return resp.choices[0].message.content

核心逻辑：Recall（搜索记忆）→ Think（LLM推理）→ Remember（写入记忆），闭环完整，可集成到任何Agent框架（LangChain、AutoGPT、自研框架等）。

方式2：CLI工具（快速操作，适合调试）

memsearch index ./docs/              # 索引文件
memsearch search "Redis caching"     # 搜索
memsearch watch ./docs/              # 监听文件变化
memsearch compact                    # 压缩旧记忆

05 和其他方案对比：我们到底不一样在哪？

很多开发者会问：市面上已有Mem0、Zep等记忆方案，为什么还要用memsearch？这里总结了一张选型表供参考。