OpenClaw 长短期记忆体系概览：SQLite、Markdown 与 embedding 的 memory_search 配置骨架

1. 为什么你的 OpenClaw 总是“记不住事”很多人第一次用 OpenClaw 搭本地 Agent 时都会遇到一个很割裂的体验明明上一轮对话里刚说过“以后回答都用中文”下一轮它又切回英文昨天聊过的项目背景今天开个新会话它完全不知道。于是开始怀疑是不是模型太笨或者上下文窗口太小。问题往往不在模型而在记忆体系没配好。OpenClaw 把“记忆”这件事拆成了两层短期记忆是当前这次请求真正发给模型的那段 prompt 加最近几轮对话它存在内存和 JSONL 转录里受上下文窗口约束太长就会被裁剪或压缩长期记忆则是落在磁盘上的 Markdown 文件加向量/全文索引用来跨会话、跨时间“回想”信息。这两层如果只有一层在工作Agent 就会表现得要么健忘要么答非所问。这篇就聚焦落地配置怎么用 SQLite 建索引、Markdown 存本体、embedding 算向量把 memory_search 这条检索链路跑通。适合已经在本地跑 OpenClaw、想让 Agent 真正记住偏好和长期事实的人。我会给出可复制的 config.toml / settings.json 骨架再带你做一次 memory_search 验证最后把常见的坑列清楚。整个链路里模型调用和 embedding 请求都需要一个稳定的 API 通道我这边统一走 TaoToken 的 Key下面配置里会体现。2. 前置把模型与 embedding 通道接进 TaoTokenOpenClaw 的记忆检索里有两个地方会发起外部请求一是对话模型本身二是 embedding provider默认 OpenAI 的 text-embedding-3-small 或 Gemini 的 gemini-embedding-001。如果你本地没有直连条件或者想统一管理 Key可以把这两类请求都指向同一个兼容通道。TaoToken 在这里的角色就是统一 Key/API 通道官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 这个地址不加 UTM。你需要先在控制台建一个 Key控制台地址带 deep linkhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 配置字段对不上时先翻这里。拿到 Key 之后OpenClaw 侧要做两件事把对话模型的 baseURL 指向 TaoToken 的 API 地址把 embedding provider 也指向同一个 baseURL。这样 Markdown 切片算向量、memory_search 查询算 query 向量走的是同一条通道不会出现“索引用一个模型、查询用另一个模型”导致向量空间对不上的问题。注意embedding 模型一旦选定就不要中途换。chunks 表里存了 model 字段meta 表也记了当前索引用的模型和 provider换模型会触发全量重建否则检索结果会明显变差。3. 可复制配置config.toml 与 settings.json 骨架OpenClaw 的配置分两块模型/provider 相关走 config.tomlAgent 的记忆检索行为走 settings.json或等价的 agents.defaults.memorySearch 结构。下面这份骨架可以直接改 Key 后用。先看 config.toml重点是 provider 的 baseURL 和 embedding 段# ~/.openclaw/config.toml [providers.taotoken] type openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoTokenKey # 对话模型 default_model gpt-4o-mini [memory.embedding] provider openai base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model text-embedding-3-small # 向量维度需与模型一致text-embedding-3-small 为 1536 dimensions 1536再看 settings.json这里定义长期记忆的源文件、切片参数和混合检索权重{ agents: { defaults: { memorySearch: { enabled: true, sources: [memory], chunking: { tokens: 400, overlap: 80 }, hybrid: { vectorWeight: 0.7, textWeight: 0.3 }, maxResults: 6, candidateMultiplier: 4, experimental: { sessionMemory: false } } } } }几个参数的分工说清楚sources 里的 memory 指 MEMORY.md 和 memory/YYYY-MM-DD.md 这两类 Markdownchunking.tokens400 是每个 chunk 的目标 token 数overlap80 是相邻 chunk 的重叠避免语义被硬切断hybrid 里 vectorWeight 0.7、textWeight 0.3 是向量检索和 FTS5 全文检索的线性加权前者管语义相近后者管关键词命中。maxResults 控制返回几个 snippetcandidateMultiplier 决定向量检索先捞多少候选再合并排序。如果你想让会话转录 JSONL 也能被语义检索把 experimental.sessionMemory 改成 true同时 sources 加上 sessionssources: [memory, sessions], experimental: { sessionMemory: true }开启后 MemoryIndexManager 会监听 ~/.openclaw/agents//sessions/*.jsonl把 User/Assistant 文本提取出来做 chunk 和 embedding以 sourcesessions 存进同一个 SQLite 索引。搜索时 memory 和 sessions 两个来源可以一起查但两者在结果里仍然区分得清清楚楚。4. 验证跑一次 memory_search 看结果配置写完先别急着聊手动验证一遍检索链路最稳。第一步确认 Markdown 本体存在。默认工作区下应该有 MEMORY.md可选和 memory/当天日期.mdls -la ~/.openclaw/workspace/ # 期望看到 MEMORY.md 和 memory/ 目录 cat ~/.openclaw/workspace/MEMORY.md EOF - 用户偏好回答用中文代码示例用 TypeScript。 - 长期事实项目代号 OpenClaw索引库在 ~/.openclaw/memory/main.sqlite。 EOF第二步确认 SQLite 索引文件生成。保存 Markdown 后 chokidar 会监听到变更防抖约 1.5 秒后后台调用 sync对比文件 hash变了就重切 chunk、重算 embeddingls -la ~/.openclaw/memory/ # 期望看到 main.sqlite sqlite3 ~/.openclaw/memory/main.sqlite .tables # 期望输出chunks chunks_fts chunks_vec embedding_cache files meta第三步直接查索引内容确认 chunk 和向量都写进去了sqlite3 ~/.openclaw/memory/main.sqlite \ SELECT path, start_line, end_line, substr(text,1,40) FROM chunks LIMIT 5;如果能看到 MEMORY.md 的路径和片段文本说明切片和入库正常。第四步触发一次 memory_search。在 OpenClaw 会话里发一句需要回忆长期事实的话比如“我之前说过回答用什么语言”Agent 会调用 memory_search 工具查询文本先 embedQuery 得到 query 向量在 chunks_vec 里找最近邻同时在 chunks_fts 里做 FTS5 MATCH 算 BM25 分数两路按 0.7/0.3 加权合并取前 maxResults 个 snippet 返回每个 snippet 约 700 字符带 path/startLine/endLine 方便回到原文。预期结果是 Agent 回答“中文”并且你能在日志里看到 sourcememory 的命中记录。如果返回空先看 chunks 表有没有数据再看 embedding 请求是否成功——这一步最容易卡在 Key 或 baseURL 上。5. 本篇常见错排查报错一memory_search 返回空chunks 表是空的。多半是 Markdown 没被索引。检查文件是否在 workspace 下、路径是否匹配 memory/YYYY-MM-DD.md 或 MEMORY.md再确认 settings.json 里 sources 包含 memory。如果文件刚改完等 2 秒让防抖计时器走完。报错二embedding 请求 401 或 404。401 是 Key 不对去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 重新确认404 通常是 base_url 写错注意 API 地址是 https://taotoken.net/api 不要多加路径后缀。字段名对不上时翻接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。报错三检索结果语义不相关。先确认索引和查询用的是同一个 embedding 模型。chunks 表有 model 字段meta 表有当前 provider 和模型名两边不一致就删掉 sqlite 重建。另外 chunking.tokens 设太大比如 2000会让单个向量太粗糙语义被稀释400 左右比较均衡。报错四改了 MEMORY.md 但搜索还是旧内容。检查 hash 是否真的变了——如果只是改了空格或换行hash 可能不变sync 会跳过。确认 files 表的 mtime 和 size 已更新。实在不放心就手动触发一次 syncreason 传 watch。报错五sessionMemory 开了但 sessions 来源查不到。确认 sources 里加了 sessions且 JSONL 文件在 ~/.openclaw/agents//sessions/ 下。这个特性是实验性的索引更新有延迟别指望刚聊完立刻能搜到。6. 把记忆链路固定下来的几个习惯配置跑通之后真正决定 Agent 好不好用的其实是写入习惯。我的做法是决定、偏好、长期事实写进 MEMORY.md日常运行笔记和当天情况写进 memory/当天日期.md用户说“记住这个”时显式写盘而不是指望它停留在上下文里。这样即使短期记忆被裁剪或压缩重要信息也已经落到 Markdown 本体下次 memory_search 还能捞回来。另外自动 memory flush 会在上下文接近窗口上限时触发一个隐藏回合提示模型把值得长期记住的内容写进 Markdown没有就回 NO_REPLY。这个机制相当于在短期记忆被摘要之前做一次搬运配合上面的写入习惯长期记忆会越用越准。模型对话和 coding 场景如果也想统一走同一个通道可以看模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 和 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite Key 和 baseURL 复用上面那份 config.toml 就行。