openclaw长期记忆实现方式：SQLite+向量索引的混合搜索落地

1. openclaw 长期记忆为什么不能只靠上下文窗口很多人第一次给 AI 工具加记忆直觉做法是把历史对话全塞进 prompt。聊到第三轮还行聊到第三十轮就开始出问题token 账单飙升、模型开始遗忘中间内容、响应变慢。我试过把 20 轮对话硬塞进上下文结果模型对最早那几轮的信息几乎完全忽略等于白存。openclaw 长期记忆的核心思路是分层把稳定信息沉淀到磁盘文件把可检索信息建成索引只在需要时把最相关的片段捞回上下文。这样上下文窗口只承载「当前任务 召回片段」而不是全部历史。对于需要为 AI 工具构建可持久记忆的开发者来说这套 SQLite 向量索引的混合搜索方案是能直接落地抄作业的。具体拆开看openclaw 的长期记忆由三层组成。第一层是给人看的明文文件比如MEMORY.md存稳定偏好和固定流程memory/YYYY-MM-DD.md按天记日志。第二层是给机器查的 SQLite 索引库位于~/.openclaw/memory/{agentId}.sqlite把 Markdown 切块后生成向量索引和 FTS5 全文索引。第三层是检索工具memory_search和memory_get负责在对话中按需召回。为什么是 SQLite 而不是独立向量数据库因为 openclaw 的记忆规模通常在几万到几十万块之间SQLite 单文件足够扛还省去了额外服务进程。向量检索用sqlite-vec扩展全文检索用内置 FTS5两者在同一个数据库里协同事务和备份都简单。这个选型对个人开发者和中小团队特别友好不需要维护 Milvus、Qdrant 这类独立服务。混合搜索要解决的问题是纯向量搜索对精确标识符不敏感你搜DB_PASSWORD它可能返回一堆语义相近但无关的内容纯关键词搜索又抓不住「运行网关的机器」和「Mac Studio」这种语义关联。所以 openclaw 同时跑两路再按权重合并。下面我会给出可复制的建表语句、索引配置和混合检索参数并附上召回效果的验证动作。2. TaoToken 前置把模型调用和记忆检索串起来openclaw 的长期记忆本身是本地存储和检索但记忆的写入判断、召回后的摘要、以及对话生成都要调用大模型。也就是说你需要一个稳定的模型接入点。TaoToken 在这里的角色是提供统一的 API 入口让 openclaw 的模型调用和记忆链路解耦。先明确几个地址后面配置会用到。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。模型对话调试页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。为什么记忆系统要关心模型接入因为 openclaw 的「记忆冲刷」机制依赖模型判断哪些内容值得写入。当会话接近上下文上限时系统会静默触发一个 AI 回合让模型把重要信息写进当天日志。如果模型调用不稳定或超时这个冲刷就会失败导致长对话中的信息静默丢失。所以把模型接入配稳是长期记忆可靠性的前提。TaoToken 的接入方式兼容 OpenAI 风格的接口openclaw 里配置模型时把 Base URL 指向https://taotoken.net/api填入在控制台申请的 Key再指定 Model ID 即可。控制台在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。如果你打算长期跑编码类 Agent记忆会持续累积调用量也不小可以看下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它更适合需要持续记忆和长周期任务的场景。下面进入具体的建表和索引配置。3. 可复制配置SQLite 建表与向量索引落地这一节给出可以直接复制的配置片段。openclaw 的索引库路径是~/.openclaw/memory/{agentId}.sqlite每个 AI 助手一个独立库。我们先建三张核心表块表、向量表、全文索引表。先看建表语句。块表存切分后的文本块和元信息向量表存 embeddingFTS5 表存全文索引。注意sqlite-vec扩展需要先加载不同平台的加载方式略有差异下面用 SQL 和 Python 混合展示。-- 加载向量扩展路径按实际安装位置调整 -- .load ./vec0 -- 1. 文本块表存切分后的记忆块 CREATE TABLE IF NOT EXISTS memory_chunks ( id INTEGER PRIMARY KEY AUTOINCREMENT, agent_id TEXT NOT NULL, file_path TEXT NOT NULL, -- 来源文件如 MEMORY.md start_line INTEGER NOT NULL, -- 起始行号供 memory_get 精确读取 end_line INTEGER NOT NULL, content TEXT NOT NULL, -- 块文本 created_at INTEGER NOT NULL, -- unix 时间戳 updated_at INTEGER NOT NULL ); -- 2. 向量索引表sqlite-vec 虚拟表 CREATE VIRTUAL TABLE IF NOT EXISTS memory_vec USING vec0( chunk_id INTEGER PRIMARY KEY, embedding FLOAT[1536] -- 维度按你的 embedding 模型调整 ); -- 3. 全文索引表FTS5 CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5( content, chunk_id UNINDEXED, tokenize unicode61 ); -- 4. 普通索引加速按文件和时间过滤 CREATE INDEX IF NOT EXISTS idx_chunks_agent ON memory_chunks(agent_id); CREATE INDEX IF NOT EXISTS idx_chunks_file ON memory_chunks(file_path); CREATE INDEX IF NOT EXISTS idx_chunks_created ON memory_chunks(created_at);建完表后写入流程是先把 Markdown 按标题或固定行数切块插入memory_chunks拿到chunk_id再调用 embedding 接口生成向量写入memory_vec同时把文本写入memory_fts。这三步最好放在一个事务里避免索引不一致。import sqlite3, time, struct def insert_chunk(conn, agent_id, file_path, start_line, end_line, content, embedding): now int(time.time()) cur conn.cursor() cur.execute( INSERT INTO memory_chunks(agent_id,file_path,start_line,end_line,content,created_at,updated_at) VALUES(?,?,?,?,?,?,?), (agent_id, file_path, start_line, end_line, content, now, now) ) chunk_id cur.lastrowid # 向量写入sqlite-vec 接受 float 列表或二进制 cur.execute( INSERT INTO memory_vec(chunk_id, embedding) VALUES(?, ?), (chunk_id, struct.pack(f{len(embedding)}f, *embedding)) ) cur.execute( INSERT INTO memory_fts(content, chunk_id) VALUES(?, ?), (content, chunk_id) ) conn.commit() return chunk_id混合检索的参数是重点。openclaw 默认向量权重 0.7、BM25 权重 0.3这个比例适合大多数语义关键词混合场景。如果你的记忆里标识符、变量名、路径特别多可以把 BM25 权重提到 0.4 到 0.5。检索时两路各取 topK合并去重后按加权分排序。def hybrid_search(conn, query, query_vec, top_k10, vec_weight0.7, bm25_weight0.3): # 向量路 vec_rows conn.execute( SELECT chunk_id, distance FROM memory_vec WHERE embedding MATCH ? ORDER BY distance LIMIT ?, (struct.pack(f{len(query_vec)}f, *query_vec), top_k) ).fetchall() # BM25 路 fts_rows conn.execute( SELECT chunk_id, bm25(memory_fts) AS score FROM memory_fts WHERE memory_fts MATCH ? ORDER BY score LIMIT ?, (query, top_k) ).fetchall() scores {} for cid, dist in vec_rows: scores[cid] scores.get(cid, 0) vec_weight * (1.0 / (1.0 dist)) for cid, score in fts_rows: scores[cid] scores.get(cid, 0) bm25_weight * (1.0 / (1.0 abs(score))) ranked sorted(scores.items(), keylambda x: x[1], reverseTrue)[:top_k] return ranked如果你用 Claude Code 或 Cline 这类工具配合 openclaw配置里要写全三件套Base URL 填https://taotoken.net/apiKey 填控制台生成的Model ID 按文档选。CC Switch 里切换配置时确保记忆库路径和模型配置指向同一个 agentId否则会出现「记忆写进去了但检索不到」的错觉。4. 验证请求召回效果怎么测才算通过配置写完不能只看「没报错」要验证召回质量。我一般用三个动作写入已知内容、发起语义查询、检查返回块是否命中。第一步往MEMORY.md写一条测试记忆比如「运行网关的机器是 Mac Studio环境变量 DB_PASSWORD 存在 keychain」。然后触发索引重建让切块和 embedding 落库。# 假设 openclaw 提供索引重建命令按实际 CLI 调整 openclaw memory reindex --agent default第二步用语义查询测向量路。查询「网关跑在哪台机器上」期望召回包含「Mac Studio」的块。如果返回的是无关内容说明 embedding 维度或切块粒度有问题。# 语义查询验证 q 网关跑在哪台机器上 q_vec get_embedding(q) # 调用你的 embedding 接口 results hybrid_search(conn, q, q_vec, top_k5) for cid, score in results: row conn.execute(SELECT content FROM memory_chunks WHERE id?, (cid,)).fetchone() print(score, row[0][:80])第三步用精确查询测 BM25 路。查询DB_PASSWORD期望精确定位到那条环境变量记忆。如果向量路返回了语义相近但无关的内容BM25 路应该把它拉回来。# 精确查询验证 q DB_PASSWORD results hybrid_search(conn, q, get_embedding(q), top_k5)判断标准语义查询的 top3 里应包含目标块精确查询的 top1 应是目标块。如果语义查询命中率低检查 embedding 模型是否和建表时的维度一致如果精确查询命中率低检查 FTS5 的 tokenize 配置中文场景建议用unicode61并配合分词预处理。还有一个容易忽略的点memory_get的精确读取依赖start_line和end_line。召回块后如果模型需要完整上下文会按文件路径和行号去读原文。所以切块时行号必须准确否则读出来的内容是错位的。验证时可以手动调一次memory_get对比返回内容和源文件。def memory_get(conn, chunk_id): row conn.execute( SELECT file_path, start_line, end_line FROM memory_chunks WHERE id?, (chunk_id,) ).fetchone() file_path, start, end row with open(file_path, r, encodingutf-8) as f: lines f.readlines() return .join(lines[start-1:end])实测下来只要切块行号准确、embedding 维度一致、FTS5 分词合理混合搜索的召回率能稳定在可用水平。接下来看常见报错。5. 常见错排查401、local proxy failed、reading choices、OAuth记忆链路跑起来后报错通常不在 SQLite 本身而在模型调用和工具衔接上。下面按真实报错对照排查。401 Unauthorized模型调用返回 401说明 Key 无效或没带上。检查 openclaw 配置里的 Base URL 是否为https://taotoken.net/apiKey 是否从控制台正确复制。注意 API 地址不带 UTM 参数别把官网链接直接填进去。如果用的是环境变量确认变量名和代码读取的一致。local proxy failed这个报错通常出现在本地代理或网络层。先确认没有配置额外的本地转发规则openclaw 直连 API 基址即可。检查~/.openclaw/config里是否有残留的 proxy 字段有就删掉。另外确认防火墙没有拦截出站请求。reading choices 相关报错这类错误一般是响应结构解析失败常见原因是模型返回了非预期格式或者流式响应被中断。检查 Model ID 是否拼写正确有些模型名大小写敏感。如果开了流式确认客户端能正确处理 SSE。记忆冲刷场景下如果模型超时导致响应截断也会触发类似错误可以适当调大超时时间。OAuth 相关报错如果你用 Claude Code 或类似工具接入OAuth 流程失败通常是回调地址或 token 过期。重新走一遍授权确认回调地址和配置一致。如果工具支持 API Key 直连优先用 Key 方式少一层 OAuth 就少一类问题。记忆写入了但检索不到先查memory_chunks里有没有数据再查memory_vec和memory_fts是否同步写入。常见原因是三步写入没放同一事务向量写失败但块写成功了。修复方式是重建索引并给写入加事务。召回结果重复或错位检查切块逻辑同一段内容被切到多个块会导致重复召回。行号错位会导致memory_get读错内容。建议切块时以 Markdown 标题为边界块大小控制在 200 到 500 字。向量维度不匹配建表时写了FLOAT[1536]但 embedding 接口返回 1024 维插入会失败或检索异常。统一维度改表或换模型。排查顺序建议先确认模型调用通401 类再确认索引写入完整事务类最后确认召回质量权重和切块类。这样能快速定位问题层。6. 长期记忆落地从能跑到好用把 openclaw 长期记忆跑通只是第一步真正影响体验的是日常维护。几个实用动作定期浏览MEMORY.md删掉过时偏好避免它膨胀后每次私聊都加载一堆无用内容配置HEARTBEAT.md让 AI 定时巡检记忆整理和归档对重要规则直接手动编辑文件比对 AI 说「记住这个」更可靠。混合搜索的权重不是固定的。记忆库早期内容少向量权重高一点效果好内容多了、标识符多了适当提高 BM25 权重。可以每隔一段时间用一组已知查询测召回根据命中情况微调。如果你需要长期跑编码 Agent记忆会持续累积模型调用也更频繁Coding Plan 比按量更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入文档里有完整的配置示例https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。需要调试模型对话时用这个入口https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 。最后提醒一个坑记忆库和 agentId 绑定换 agentId 等于换了一套记忆。迁移时记得把~/.openclaw/memory/{agentId}.sqlite和对应的 workspace 文件一起搬只搬数据库不搬 Markdownmemory_get会找不到源文件。