1. 为什么你的 OpenClaw 每次对话都像“第一次见你”如果你已经跟着 OpenClaw 实战系列把飞书、企业微信、Slack 都接上了技能也能跑了Jira 和 Confluence 也能查了那你大概率会遇到一个很尴尬的问题它很能干但它不记得你。上周你刚跟它敲定“用户认证模块用 JWT Refresh Token不要 Session”今天新开一个会话问它“认证模块怎么设计”它又给你推荐 Session。你昨天告诉它“我们生产库是 PostgreSQL 16连接池用 pgBouncer”今天它写代码时还是默认给你max_connections100的裸配置。这不是模型笨而是上下文和记忆是两回事。上下文Context是单次请求里模型能看到的全部内容系统提示、当前消息、最近几轮对话。它的生命周期就是这一次会话会话一关全部归零。记忆Memory是跨会话持久化的信息你的偏好、项目决策、技术栈、历史结论。它应该写到磁盘上下次会话启动时再被召回。OpenClaw 在持久记忆这块的设计思路和主流 RAG 方案不太一样它走的是“文件即真理”The files are the source of truth。所有记忆都是~/Space/memory/下的普通 Markdown 文件你可以用 VS Code 直接打开改可以用git diff看变更历史向量索引只是派生出来的加速层索引丢了可以重建文件丢了才是真灾难。这一点对做知识库构建特别关键你的知识资产是可读、可迁移、可版本管理的纯文本而不是锁在某个向量数据库里的黑盒 Embedding。这篇文章要解决的场景很具体让 OpenClaw 具备持久记忆并且基于本地 Markdown 构建一套可检索的 RAG 知识库。适合谁看已经跑通 OpenClaw 基础接入、想让 AI 跨会话记住项目上下文、想用本地文件而不是云向量库做知识库的开发者。读完之后你能做到写入一条长期记忆重启会话AI 能准确召回日志自动落盘索引按需更新记忆膨胀时自动归档。我试过把这套配置直接搬到一台 2C4G 的小机器上跑索引和召回都正常资源占用比想象中低关键就在于“按需更新”而不是“定时全量重建”。2. OpenClaw 记忆系统前置准备与 QMD 索引安装在动手改配置之前先把环境对齐。OpenClaw 的记忆模块依赖两个东西一个是主程序版本一个是 QMD语义搜索核心。QMD 负责把 Markdown 切片、生成 Embedding、建索引、做混合检索。你可以把它理解成“给文件夹装了一个可语义搜索的搜索引擎”。先确认版本。记忆模块的memorySearch配置在 v2026.2.3 之后才稳定低于这个版本会出现配置项不识别的情况openclaw --version # 期望输出类似openclaw/2026.2.3 linux-x64 node-v20.11.0如果版本偏低先升级npm install -g openclawlatest openclaw --version接着装 QMD。它是全局 CLI 工具装完之后qmd update、qmd search、qmd status这三个命令会贯穿全文npm install -g openclaw/qmd qmd --version # 期望输出qmd/0.9.xEmbedding 提供者这块入门阶段我建议先用 Gemini 的免费额度gemini-embedding-001这个模型对中文技术文本的语义区分度够用而且不用本地显卡。如果你要完全本地化可以装 Ollama 拉一个qwen3或deepseek-r1:7b做本地 Embedding但 7B 模型做 Embedding 的效果和专用 Embedding 模型比还是有差距建议只在离线场景用。# 可选本地模型路线 curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen3:latest然后是目录结构。OpenClaw 的记忆分三层这个结构最好一开始就建对后面脚本都按这个路径写mkdir -p ~/Space/{memory,para-system,life} mkdir -p ~/Space/memory/archives mkdir -p ~/Space/life/{projects,areas,resources,archives}三层分别是MEMORY.md长期精炼记忆人工主导、AI 辅助维护跨会话永久注入YYYY-MM-DD.md日常日志AI 自动写入会话启动时加载今天和昨天archives/归档记忆当MEMORY.md超过阈值时把低相关性内容移进去。初始化MEMORY.md和今日日志cat ~/Space/memory/MEMORY.md EOF # MEMORY.md - 长期精炼记忆 # 用户偏好 - 语言中文优先技术术语保留英文 - 代码风格TypeScript ESLint 严格模式 # 技术栈 - 后端Python 3.11 FastAPI - 数据库PostgreSQL 16 pgBouncer # 活跃项目 - [ ] 用户认证模块重构 EOF today$(date %Y-%m-%d) cat ~/Space/memory/$today.md EOF # $today # 今日进展 # 临时决策 # 待跟进 EOF环境变量按你选的提供者设置。用 Gemini 就设GEMINI_API_KEY用 OpenAI 就设OPENAI_API_KEY。写进~/.bashrc或~/.zshrc让它永久生效echo export GEMINI_API_KEY你的Key ~/.bashrc source ~/.bashrc这里有个坑要提前说QMD 读的是环境变量不是配置文件里的明文 Key。如果你在openclaw.json里写了${GEMINI_API_KEY}但 shell 里没 export索引会静默失败qmd status显示 0 文档。所以先echo $GEMINI_API_KEY确认有值再往下走。3. 可复制的 OpenClaw 记忆配置与 RAG 召回参数这一节是全文的核心配置直接复制就能用。主配置文件在~/.openclaw/openclaw.json记忆模块挂在memory和agents.defaults.memorySearch两个位置。先看完整的 JSON 片段路径和字段名保持和官方一致不要自己改键名{ memory: { enabled: true, paths: { memoryDir: ~/Space/memory, lifeDir: ~/Space/life }, index: { autoUpdate: true, watchDebounceMs: 1500 } }, agents: { defaults: { memorySearch: { enabled: true, provider: gemini, model: gemini-embedding-001, remote: { apiKey: ${GEMINI_API_KEY} }, sync: { watch: true, watchDebounceMs: 1500 }, query: { maxResults: 8, hybrid: { enabled: true, vectorWeight: 0.7, textWeight: 0.3 }, temporalDecay: { enabled: true, halfLifeDays: 30 } }, cache: { enabled: true, maxEntries: 50000 } } } } }几个参数值得单独解释因为它们直接决定召回质量sync.watchDebounceMs: 1500是文件变更后延迟 1.5 秒再触发索引。你编辑 Markdown 时保存动作可能连续触发多次防抖能避免索引被反复重建。query.maxResults: 8是每次检索返回的最大片段数。太小会漏召回太大则会把无关内容塞进上下文稀释有效信息。8 是通用场景的平衡点。hybrid.vectorWeight: 0.7和textWeight: 0.3是混合检索权重。向量检索擅长语义相近但用词不同的情况比如你搜“连接池配置”能召回“pgBouncer 参数”关键词检索擅长精确匹配比如搜selectinload这种函数名。0.7/0.3 适合大多数技术知识库。如果你做的是精确匹配需求强的场景比如查 API 名、错误码可以把textWeight提到 0.5。temporalDecay.halfLifeDays: 30是时间衰减30 天半衰期意味着新记忆权重更高。这对项目日志类知识库很重要三个月前的临时决策不应该和昨天的决策同权。如果你不想指定 provider想让 OpenClaw 自动检测可以简化成{ agents: { defaults: { memorySearch: { enabled: true, sync: { watch: true } } } } }自动检测顺序是 local → openai → gemini → voyage → mistral谁先有可用配置用谁。配置写完后初始化索引并重启网关qmd update --all qmd status openclaw gateway restartqmd status期望看到类似输出QMD 索引状态 总文档数: 12 最后更新: 2026-03-06 10:22:31 索引大小: 1.8 MB如果总文档数是 0先别急着往下走去第 5 节看排查。4. 验证持久记忆写入一条长期记忆后重启会话确认召回配置对不对不靠感觉靠验证。这一节给你一套完整的验证动作写入一条长期记忆 → 重启会话 → 确认 AI 能准确召回。第一步用自然语言让 AI 写入一条记忆。在任意已接入的聊天平台飞书/钉钉/Slack发送记住我们生产环境的 PostgreSQL 连接池用 pgBouncer max_client_conn1000default_pool_size20不要用应用层连接池。发送后检查MEMORY.md是否真的落盘tail -20 ~/Space/memory/MEMORY.md期望能看到类似新增内容## 2026-03-06 新增决策 - 生产环境 PostgreSQL 连接池使用 pgBouncer - max_client_conn1000default_pool_size20 - 不使用应用层连接池如果MEMORY.md没变说明会话结束钩子没配。补上hooks.onSessionEnd{ hooks: { onSessionEnd: { command: ~/Space/para-system/log-conversation.sh \{{summary}}\ \{{keyPoints}}\ } } }第二步手动触发一次索引更新确保新写入的内容进了向量索引qmd update --all qmd search 生产环境连接池配置 --limit 3期望输出搜索: 生产环境连接池配置 找到 3 个相关结果: 1. [memory/MEMORY.md:42] 得分 0.89 生产环境 PostgreSQL 连接池使用 pgBouncer... 2. [memory/2026-03-06.md:18] 得分 0.81 max_client_conn1000default_pool_size20... 3. [life/projects/database-optimization.md:15] 得分 0.67 调整 PostgreSQL max_connections 为 500...第三步也是最关键的一步重启会话。关掉当前对话窗口重新开一个全新会话然后问我们生产环境的数据库连接池是怎么配的如果 AI 回答里出现了pgBouncer、max_client_conn1000、default_pool_size20这些具体参数说明持久记忆和 RAG 召回链路全部打通。如果它回答“我不清楚”或者给了通用建议说明召回没生效去第 5 节对照排查。第四步验证日志自动落盘。随便聊几句技术问题然后看今天的日志文件cat ~/Space/memory/$(date %Y-%m-%d).md期望能看到对话摘要和关键点被追加进去。这一步验证的是“AI 自动写入日常日志”这条链路。第五步验证索引按需更新。修改MEMORY.md加一行等 2 秒然后qmd search 你刚加的那行关键词 --limit 1能搜到就说明sync.watch生效了不需要手动qmd update。这套验证动作跑通你的 OpenClaw 才算真正“记住”了你。后面几节的脚本都是在这条主链路上做增强自动日志、检查点、语义归档、健康监控。5. OpenClaw 记忆检索常见报错排查401、local proxy failed、reading choices记忆模块出问题症状通常很隐蔽AI 不报错只是“装作不记得”。所以排查要从日志和索引状态入手。下面这张表覆盖了我踩过的大部分坑。现象可能原因解决方案qmd status显示 0 文档Embedding API Key 无效或未 exportecho $GEMINI_API_KEY确认有值重新qmd update --all报错401 UnauthorizedKey 过期或 provider 与 Key 不匹配检查provider字段和对应环境变量是否一致报错local proxy failed本地 Embedding 服务未启动ollama list确认模型在ollama serve启动服务报错reading choices返回体结构异常通常是模型名写错核对model字段Gemini 用gemini-embedding-001记忆搜索返回旧数据索引缓存未刷新qmd update --all强制重建MEMORY.md不更新检查点脚本未执行openclaw cron list确认任务存在今日日志不生成hooks.onSessionEnd未配置补上钩子配置并重启网关定时任务不执行网关未运行openclaw gateway status必要时 restart召回结果不相关混合权重不适合当前场景调整vectorWeight/textWeight索引更新太频繁防抖时间太短把watchDebounceMs提到 2000重点说三个高频报错。401 Unauthorized最常见。QMD 读环境变量如果你在openclaw.json里写了${GEMINI_API_KEY}但当前 shell 没 export或者你用的是sudo启动的网关环境变量不继承就会 401。解决方式是确认网关进程能读到 Keyopenclaw gateway status # 看进程环境或者直接在启动脚本里 exportlocal proxy failed出现在你用本地 Embedding 的时候。Ollama 没启动、模型没拉、端口被占都会报这个。按顺序查ollama list ollama serve curl http://localhost:11434/api/tagsreading choices这个报错名字很迷惑它其实是 OpenAI 兼容接口返回体解析失败。90% 的情况是model字段写错了比如把gemini-embedding-001写成了text-embedding-004或者 provider 和 model 不匹配。核对配置里的provider和model是否成对。还有一个隐蔽问题MEMORY.md越来越大召回质量反而下降。因为maxResults: 8返回的 8 个片段里可能 5 个都是过时的临时决策。这时候要么调temporalDecay.halfLifeDays让衰减更快要么跑语义归档把低相关性内容移走。归档脚本在第 6 节。排查完记得重启网关很多配置改动不重启不生效openclaw gateway restart openclaw logs --follow | grep memory盯着日志看几秒正常的话能看到索引加载和召回记录。6. 让记忆不膨胀语义归档、健康检查与 Coding Plan 接入记忆系统跑起来之后最大的敌人不是“记不住”而是“记太多”。MEMORY.md一旦超过 1500 字符注入到系统提示里的内容就开始稀释有效信息召回也会变慢。所以需要一套维护机制检查点提炼、语义归档、健康监控。检查点脚本每 6 小时跑一次从今日日志里提取 3-5 个最关键的信息点追加到MEMORY.md。核心逻辑是调 LLM 做摘要#!/bin/bash MEMORY_FILE$HOME/Space/memory/MEMORY.md TODAY$(date %Y-%m-%d) LOG_FILE$HOME/Space/memory/$TODAY.md [ ! -f $LOG_FILE ] exit 0 EXTRACTED$(ollama run qwen3 从以下日志中提取3-5个最关键的信息点这些信息应该被永久记住如技术决策、项目进展、用户偏好。用 Markdown 列表格式输出\n\n$(cat $LOG_FILE)) { echo echo # $(date %Y-%m-%d) 关键记忆 echo $EXTRACTED } $MEMORY_FILE if [ $(wc -c $MEMORY_FILE) -gt 1500 ]; then ~/Space/para-system/semantic-archive.sh fi语义归档脚本负责把MEMORY.md里与最近 30 天日志相关性最低的 20% 内容移入archives/。思路是按#标题切段对每段算相关性得分保留高分 80%归档低分 20%。实际生产里相关性得分应该调 Embedding API 算脚本里可以先按时间戳和关键词命中做简化。健康检查脚本每天跑一次给记忆系统打分。检查项包括MEMORY.md大小是否超 2000 字节、今日日志是否存在、QMD 索引是否正常、定时任务数量是否够、归档目录是否存在。满分 6 分低于 4 分就该人工介入了。qmd status /tmp/qmd-status 21 if [ $? -eq 0 ]; then echo QMD 索引正常 grep -o 总文档数: [0-9]\ /tmp/qmd-status else echo QMD 索引异常 fi定时任务用 OpenClaw 自带的 cron 系统注册openclaw cron add \ --name Memory Checkpoint \ --schedule every 6h \ --payload systemEvent: 执行智能记忆检查点 \ --target main openclaw cron add \ --name Memory Health Check \ --schedule cron 0 8 * * * \ --payload systemEvent: 运行记忆健康检查 \ --target main如果你打算把这套记忆系统长期跑在编码场景里比如让 OpenClaw 记住你的代码风格、项目结构、历史决策然后持续帮你写代码、做 Code Review那单靠免费额度的 Embedding 可能会在索引重建时遇到限流。这种长期编码和 Agent 场景可以考虑接入 Coding Plan把模型调用和记忆检索的额度稳定下来配置入口在 Coding Plan。最后给一个实用技巧用 Git 管理你的记忆目录。~/Space/memory/和~/Space/life/都是纯文本git init之后每次检查点自动 commit你就能用git log -p memory/MEMORY.md看 AI 的记忆是怎么演变的出问题还能回滚到某个版本。这比任何向量数据库的审计日志都直观。cd ~/Space git init git add memory/ life/ git commit -m 初始化记忆仓库多设备同步用 rsync 或云盘软链都行注意别让两台机器同时写同一个MEMORY.md会冲突。建议一台主写其他只读同步。整套跑下来你的 OpenClaw 就不再是“每次重新开始”的工具而是一个跨会话、跨项目、可审计、可迁移的私人知识助理。记忆文件在你手里索引随时可重建这才是知识库构建该有的样子。
