`openclaw memory` 命令完全指南：语义记忆索引、状态探测与搜索实战

人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载openclaw memory是 OpenClaw 中负责语义记忆索引与检索的管理命令包含status、index、search三个子命令用于查看记忆搜索索引状态、探测嵌入模型可用性、触发重新索引以及执行语义检索。本文以该命令为核心结合 memory-core 插件的源码实现完整讲解每个子命令的选项、输出字段、底层执行流程与典型排障场景帮助你快速诊断和调优 OpenClaw 的记忆系统。背景OpenClaw 记忆系统的核心设计在深入命令之前先理解它管理的对象。OpenClaw 的记忆是智能体工作空间中的纯 Markdown 文件文件本身就是唯一的事实来源——模型只记住写入磁盘的内容这一设计详见 docs/zh-CN/concepts/memory.md。默认工作空间agents.defaults.workspace默认~/.openclaw/workspace使用两个记忆层memory/YYYY-MM-DD.md每日日志仅追加会话开始时读取今天和昨天的内容MEMORY.md精心整理的长期记忆仅在主要的私人会话中加载绝不在群组上下文中加载。围绕这些 Markdown 文件OpenClaw 暴露两个面向智能体的工具memory_search对已索引片段做语义召回和memory_get按路径/行范围定向读取记忆文件。而记忆搜索工具及本命令本身都由活跃的记忆插件提供。默认插件是memory-core见 extensions/memory-core/index.ts 中的definePluginEntry({ id: memory-core, kind: memory })若想禁用可将配置设为plugins.slots.memory none。命令总览与示例openclaw memory的命令级描述是Search, inspect, and reindex memory files搜索、检查并重建记忆索引在 extensions/memory-core/src/cli.ts 中注册。以下示例覆盖了三个子命令的典型用法openclaw memory status openclaw memory status --deep openclaw memory status --deep --index openclaw memory status --deep --index --verbose openclaw memory index openclaw memory index --verbose openclaw memory search release checklist openclaw memory status --agent main openclaw memory index --agent main --verbose此外cli.ts的帮助文本中还展示了更多实用形态如脚本化输出与限制结果数量openclaw memory status --json openclaw memory index --force openclaw memory search meeting notes openclaw memory search --query deployment --max-results 20子命令一memory status—— 查看记忆索引状态memory status是诊断记忆系统健康度的第一入口功能是Show memory search index status。支持的选项选项类型说明--agent id字符串限定到单个智能体不传时对所有已配置智能体逐个检查--json布尔以机器可读 JSON 输出适合脚本解析--deep布尔深入探测向量存储和嵌入模型的可用性--index布尔在存储有未同步变更时运行重新索引隐含--deep--verbose布尔在探测和索引期间输出详细日志输出的核心字段结合 extensions/memory-core/src/cli.runtime.ts 的实现非 JSON 模式会按智能体分组打印Provider当前实际使用的嵌入提供方如local、openai、gemini、voyage、mistral、ollama、qmd并标注(requested: ...)请求值Model使用的嵌入模型名Sources索引来源memory、sessions取决于配置Extra paths通过memorySearch.extraPaths配置的所有额外路径源码formatExtraPaths会展开并做~缩写索引进度已索引文件数/磁盘文件总数 files · chunks 数 chunks数据库路径与工作空间路径若发生从本地到远程嵌入的回退会以Fallback字段给出警示。--deep模式下源码会依次执行两步探测进度条显示为 Probing vector… 与 Probing embeddings…probeVectorAvailability()探测向量存储sqlite-vec 扩展是否可用是否就绪probeEmbeddingAvailability()探测嵌入提供方及其密钥能否解析成功。--deep --index组合则在探测之后调用manager.sync({ reason: cli, force })执行增量同步仅在索引存在脏标记有未同步变更时重建若后端不支持手动重建会明确提示 Memory backend does not support manual reindex.。--json模式下结果通过defaultRuntime.writeJson(allResults)输出为结构化数组每个智能体一条含status、embeddingProbe、indexError、scan方便 CI 脚本或监控工具消费。子命令二memory index—— 手动触发重新索引memory index的功能是 Reindex memory files当文件被修改、但 watcher 尚未触发同步或你想强制重建全部索引时使用。支持的选项选项类型说明--agent id字符串限定到单个智能体不传时遍历所有已配置智能体--force布尔强制全量重建索引默认仅增量同步--verbose布尔打印每个阶段的详细信息--verbose下源码会输出每个阶段的详细诊断Provider/Model/Sources/Extra paths/Fallback 来源并在索引期间以每秒刷新显示elapsed已耗时与eta预计剩余时间索引完成后还会给出 QMD 后端下的索引文件摘要QMD index: 路径 (size bytes)并打印 Memory index updated ( ). 作为成功标志。需要说明的是日常使用中重新索引多数是自动完成的OpenClaw 会在会话启动、搜索时或按固定间隔异步同步当索引存储的嵌入 Provider/Model 端点指纹 分块参数任一发生变化时例如换了一个嵌入模型系统会自动重置并全量重建整个索引库。memory index --force是当自动机制异常或你想立即落盘时的主动手段。子命令三memory search—— 语义检索记忆memory search的功能是 Search memory files用自然语言对已索引的 Markdown 片段做语义查询即使措辞与原文不同也能命中相关笔记。支持的选项选项类型说明[query]位置参数直接跟在命令后的搜索词--query text字符串搜索词的替代写法与位置参数二选一--agent id字符串限定到单个智能体--max-results n数字返回结果数上限--min-score n数字结果的最低相似度分数阈值--json布尔以 JSON 输出{ results: [...] }注意若同时未提供位置参数和--query命令会报错 Missing search query. Provide a positional query or use --query. 并以退出码 1 结束见 cli.runtime.ts。默认情况下maxResults为 6、minScore为 0.35这两个默认值定义在 src/agents/memory-search.ts。非 JSON 模式下每条结果按以下格式输出score path:startLine-endLine snippet即相似度分数保留三位小数、命中的文件路径与行号范围、以及片段文本直接可读可溯源。--json模式则返回结构化结果便于二次加工。通用选项与多智能体行为两个通用选项作用于所有子命令--agent id限定到单个智能体。若不传status/index会遍历agents.list中所有已配置的智能体并逐个输出search则默认解析到默认智能体resolveDefaultAgentId。--verbose输出详细日志。在status/index的探测与索引阶段打印 Provider、Model、Sources、批处理活动等中间信息。实现上每个智能体对应一个独立的内存搜索管理器per-agent SQLite 索引默认位于~/.openclaw/memory/agentId.sqlite可通过agents.defaults.memorySearch.store.path配置并支持{agentId}令牌因此多智能体场景下索引互不干扰。从源码看命令执行流程以memory status为例完整调用链为cli.runtime.ts密钥解析loadMemoryCommandConfig通过resolveCommandSecretRefsViaGateway解析命令相关的秘密引用目标项为agents.defaults.memorySearch.remote.apiKey与agents.list[].memorySearch.remote.apiKey任何解析告警会以[secrets]前缀输出智能体解析resolveAgentIds决定遍历范围管理器获取withMemoryManagerForAgent获取该智能体的内存搜索管理器后端可能是内置 SQLite 索引器或 QMD 边车探测与同步probeVectorAvailability→probeEmbeddingAvailability→ 若--indexsync结果输出按智能体聚合状态JSON 或人类可读文本。memory search与memory index复用同一套管理器管线区别仅在同步/搜索阶段。这套实现同时支撑了doctor中的记忆健康检查见 src/commands/doctor-memory-search.ts纯配置检查、无网络调用因此openclaw doctor的 Memory search 检查项与openclaw memory status --deep结论应当一致。配置联动memory status背后到底探测了什么memory status --deep的嵌入可用性探测结果直接取决于agents.defaults.memorySearch.*配置。理解自动选择与回退规则才能准确解读 status 输出Provider 自动选择当memorySearch.provider未设置时OpenClaw 按序自动选择①local配置了local.modelPath且文件存在→ ②openai可解析 OpenAI 密钥→ ③gemini可解析 Gemini 密钥→ ④voyage→ ⑤mistral→ ⑥ 否则记忆搜索保持禁用直到配置完成。memorySearch.provider ollama也支持本地/自托管 Ollama 嵌入/api/embeddings但不会被自动选中。密钥来源远程嵌入需要 API 密钥可从 auth 配置文件、models.providers.*.apiKey或环境变量解析。注意Codex OAuth 只覆盖聊天/补全不满足记忆搜索的嵌入需求。Gemini 用GEMINI_API_KEY或models.providers.google.apiKeyVoyage 用VOYAGE_API_KEYMistral 用MISTRAL_API_KEY自定义 OpenAI 兼容端点时设置memorySearch.remote.apiKey及可选的remote.headers。回退memorySearch.fallback可设为openai、gemini、voyage、mistral、ollama、local或none仅当主 Provider 失败时启用。额外路径memorySearch.extraPaths允许索引默认布局之外的 Markdown 文件绝对或工作空间相对路径目录递归扫描.md符号链接被忽略。这正是memory status中Extra paths字段的内容来源。混合检索与重排memorySearch.query.hybrid默认开启向量权重 0.7 BM25 文本权重 0.3可独立启用 MMR 多样性重排lambda默认 0.7与时间衰减默认半衰期 30 天MEMORY.md与无日期文件名永不过期详情参见 docs/zh-CN/concepts/memory.md。向量加速与缓存sqlite-vec 可用时在 SQLite 虚拟表vec0中执行向量距离查询嵌入缓存默认开启maxEntries默认 50000避免重复文本反复嵌入。会话记忆实验性experimental.sessionMemory: true配合sources: [memory, sessions]可索引会话转写阈值默认deltaBytes: 100000、deltaMessages: 50。QMD 后端设memory.backend qmd可切换到 QMD 本地搜索边车BM25 向量 重排此时status().backend qmd诊断输出会标记实际服务引擎QMD 失败时会自动回退到内置 SQLite 管理器。上述默认值分块 400 token / 80 重叠、watcher 去抖 1500ms、批处理并发 2、轮询间隔 2000ms、超时 60 分钟等均可从 src/agents/memory-search.ts 的常量定义逐一核实。典型排查场景结合 docs/zh-CN/cli/memory.md 的定位调试记忆可用性或索引问题几个高频场景与对应命令记忆搜索完全不可用先openclaw memory status --deep确认Provider是否为空或提示未配置密钥若为本地模式检查local.modelPath的 GGUF 是否已下载node-llama-cpp会自动下载可能需要先pnpm approve-builds完成原生构建。索引滞后、搜不到刚写入的笔记openclaw memory status --deep --index触发未同步变更的重新索引再openclaw memory search 关键词验证。结果冗余或陈旧在memorySearch.query.hybrid中开启mmr减少近重复片段、开启temporalDecay让新笔记排名更高调整后openclaw memory index --force --verbose重建并观察各阶段输出。脚本化监控openclaw memory status --json输出结构化状态可接入 CI 或告警openclaw memory search --query ... --max-results 20 --json适合批量校验检索质量。总结openclaw memory以三个子命令覆盖了语义记忆的完整生命周期status负责健康诊断探测向量存储与嵌入提供方、显示 extraPaths 与索引进度、index负责主动重建--force全量、--verbose全阶段可见、search负责语义召回支持分数阈值与结果数控制、JSON 输出。其能力边界完全由agents.defaults.memorySearch.*配置与 memory-core 插件决定——理解 Provider 自动选择顺序、密钥解析规则和回退机制是读懂status输出并快速定位记忆不可用/索引不新鲜/结果不理想这三类问题的关键。赞分享人工智能大模型LLM 网关AI Agent即时通讯【免费下载链接】openclaw-zero-tokenOpenClaw: Use All Major AI Models NO API Token! Claude/ChatGPT/Gemini/DeepSeek/Doubao/Grok/Qwen/Manus/Kimi项目地址https://gitcode.com/gh_mirrors/op/openclaw-zero-token点击查看免费下载相关推荐OpenClaw clawdbot memory 命令完全指南语义记忆索引与检索实战OpenClaw clawdbot memory 命令完全指南语义记忆索引与检索实战 导读 clawdbot memory 是 OpenClaw 中管理 语义人工智能AI Agent即时通讯后端本地部署语音OpenClaw memory 命令实战status / index / search 语义记忆索引与检索指南OpenClaw memory 命令实战status / index / search 语义记忆索引与检索指南 openclaw memory 是 OpenC人工智能大模型LLM 网关AI Agent即时通讯OpenClaw 记忆搜索Memory Search完全指南混合检索、Embedding 供应商与排序调优OpenClaw 记忆搜索Memory Search完全指南混合检索、Embedding 供应商与排序调优 OpenClaw 的 memory_searcAI 应用AI Agent交互助手后端即时通讯网关上一篇仓颉编程语言 stdx.crypto.x509 结构体全解析DerBlob、Pem 编解码与证书验证配置实战下一篇NCCL Multimem 设备端 API 实战单内核融合分布式 RMSNormReduce-Scatter → RMSNorm → All-Gather创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考