openclaw memory¶

管理语义记忆索引、搜索、提升到 MEMORY.md，以及基于溯源信息的删除。 由内置的 memory-core 插件提供，当 plugins.slots.memory 选择 memory-core（默认）时可用。其他记忆插件暴露各自的 CLI 命名空间。

相关：Memory 概念、Dreaming、Memory 配置参考、Memory Wiki、wiki、Plugins。

JSON 可用性¶

使用 --json 时，search、promote、promote-explain、rem-harness、rem-backfill 和 session-backfill 会在任何工作运行之前报告记忆后端是否不可用：

• 禁用的记忆返回 {"agentId":"main","status":"disabled"}，并以成功状态退出。
• 后端获取失败会返回标准的 {"ok":false,"error":{"type":"cli_error","message":"..."}} 响应结构，外加 agentId，并以退出码 1 退出。

无效的命令输入以及命令执行期间的错误也使用标准 CLI JSON 失败响应结构，并以退出码 1 退出。失败消息说明命令错误；人类可读的诊断信息保留在 stderr 中。

在读取命令的正常结果字段之前，请先处理这些结果。启用的搜索即使没有匹配项，仍会返回 {"results":[]}。status --json 会保留其可用代理的聚合数组，包括全部禁用时的 []；获取失败仍会设置非零退出码。

memory status¶

openclaw memory status [--agent <id>] [--deep] [--index] [--fix] [--json] [--verbose]

如果没有 --agent，则对 agents.entries 中的每个代理运行；如果没有配置代理列表，则回退到默认代理。

使用本地 llama.cpp 嵌入时，--deep 和 --index 还会显示可用的服务器、模型、能力和端点诊断信息。

如果 Dreaming 行在 dreaming.enabled: true 的情况下仍保持 off，或者定时扫描似乎从未运行，那么受管的 dreaming cron 依赖于默认代理的心跳触发来执行协调。有关调度详情，请参阅 Dreaming。

状态还会列出 memory.search.extraPaths 中的任何额外搜索路径。存储诊断显示共享代理数据库文件、WAL、可重用空闲页，以及保留的嵌入缓存负载字节数和条目数，包括缓存被禁用时的情况。按来源的文本+嵌入总计仅描述已索引的块。这些数字有重叠：不要将负载或可重用字节加到文件大小上。数据库还保存会话和其他代理状态；WAL 可能包含尚未检查点写入主文件的较新页面。JSON 在 status.storage 下暴露这些事实。字节检查仅用于显式诊断，不用于普通记忆搜索。

对于在初始化时发现其默认模型的提供程序，普通的 memory status 会将模型身份检查推迟到该模型已知时。使用 --deep 初始化提供程序，并根据现有索引验证模型和提供程序设置。

memory index¶

openclaw memory index [--agent <id>] [--force] [--verbose]

作用域与 status 相同，也是按代理划分。--force 执行全量重新索引，而不是增量重新索引。--verbose 在显示索引进度之前打印每个代理的提供程序、模型、来源和额外路径详细信息。完成消息报告已索引的文件数。空语料库是一个成功的空操作：命令报告解析后的工作区路径以及未索引任何内容，并将缺失的 memory/ 目录留给第一次记忆写入时创建。内部的 dreaming-narrative、cron 和心跳会话记录被排除在索引之外，包括其原始会话不再活动的保留压缩叙事归档。先前由 memory forget 选择的会话也继续保持排除状态。--force 会删除这两组的过期的索引记录，而不会重新索引其保留的记录。普通保留、重置和删除的用户会话归档在明确针对之前仍然符合索引资格。

完整重建会先等待临时数据库清理完成，再报告完成。文件移除以异步方式运行，因此清理不会阻塞 Gateway 事件循环。

当嵌入提供方对索引进行限流时，每次嵌入操作最多可尝试五次。重试会遵循提供方有效的冷却提示，每次等待上限为 60 秒。其他瞬时错误则保持较短的三次尝试预算。没有冷却提示的永久配额错误会停止该操作。详细输出会显示每次重试的等待时间。

交互式 memory_search 保留三次尝试，重试休眠总计最多八秒，且须在代理工具 30 秒的截止时间内完成。被取消的调用方会中断其重试等待。

在 OpenClaw 索引格式升级后，首次搜索会先重建索引，再返回结果。重建可能需要更长时间，并且搜索结果会提示使用所配置嵌入提供方可能产生的费用。由更新版本 OpenClaw 写入的索引会保持暂停状态；请升级 OpenClaw 或显式重新索引。后续搜索会复用修复后的索引；仅检查状态不会重建索引。并发搜索会等待当前修复完成。修复缓慢可能超出交互式工具的截止时间；该工具会在已受理的索引工作完成期间报告不可用。如果格式修复在发布前失败，搜索会报告已记录的同步错误，并保留先前的索引。重试前，请使用 memory status --deep 检查该失败。

如果在更改嵌入设置后状态报告了索引身份警告，请检查受影响代理的提供方、模型、来源和额外路径，然后重建：

openclaw memory status --deep --agent <id>
openclaw memory index --force --agent <id>
openclaw memory status --agent <id>

openclaw memory status --index --agent <id> 同样会重建不兼容的索引。这两个修复命令都会替换派生的记忆索引，同时保留其他代理状态。使用 --agent 可将修复范围限制在受影响的代理上。

memory reset¶

清除内置记忆索引和嵌入缓存，且不删除会话、转录文本或记忆文件。

openclaw memory reset [--agent <id>] [--yes]

与 status 和 index 相同的代理作用域：未指定 --agent 时，reset 会对每个已配置的代理运行；当未配置列表时，则回退到默认代理。该命令会请求确认。--yes 可跳过提示，并且在非交互式终端中是必需的。

reset 会以原子方式仅删除并重建 agents/<agentId>/agent/openclaw-agent.sqlite 中记忆所拥有的派生表，清除已索引内容和缓存的嵌入，同时保留所需的修订簿记。非记忆数据库表和记忆源文件不受影响。对于没有索引的代理，重置会成功执行无操作。reset 会与现有的记忆维护工作相协调，并且不会重启 Gateway；正在运行的 Gateway 之后可以重新索引保留的来源。如果索引正忙，请等待其完成后再重试 reset。

之后从保留的来源重建：

openclaw memory reset --agent main --yes
openclaw memory index --agent main

reset 不会缩小数据库文件，也不会恢复因删除该文件而已经丢失的数据。要回收磁盘空间，请在重建之前遵循磁盘空间回收中的步骤。它并非隐私清理：请使用 memory forget 移除从所选会话派生的受跟踪记忆，并防止重新摄取。

memory search¶

openclaw memory search [query] [--query <text>] [--agent <id>] [--max-results <n>] [--min-score <n>] [--json]

• 查询：位置参数 [query] 或 --query <text>。如果同时设置两者，则以 --query 为准。如果两者均未设置，命令会报错。
• --agent <id>：默认为默认代理（而非完整代理列表）。
• --max-results <n>：限制结果数量（正整数）。
• --min-score <n>：过滤掉低于此分数的匹配项。

常规索引可以在搜索返回后继续运行，并且不会添加警告。如果自动索引失败，或索引身份不兼容，人类可读输出会警告匹配结果可能不完整。使用 --json 时，响应会添加 stale: true，以及 warning 和 action 字段。仅当 stale 不存在时，才可将空的 results 数组视为权威结果。

Control UI 的 Memories 标签页会与过期的搜索结果一同显示相同的警告和恢复指导，并在新的搜索后清除它们。

memory forget¶

移除从所选会话派生的可识别记忆产物，并在一个代理的存储中将那些会话记录为已遗忘。关于血缘、准入策略和删除覆盖范围之间的关系，请参阅记忆溯源与删除。

先进行预览：

openclaw memory forget --agent <agent-id> --session <id-or-key> --dry-run --json
openclaw memory forget --agent <agent-id> --hook-source gmail --dry-run --json
openclaw memory forget --agent <agent-id> --participant <actor-id> --dry-run --json

检查报告后，在不加 --dry-run 的情况下重复执行预期命令。

会话选择¶

至少需要一个选择器。重复的值和不同的选择器 类型以 OR 组合：匹配任一选择器的会话都会被选中，但受 --since 约束。选择器匹配已记录的标识符，而不是消息中的 名称或文本。参与者选择器会选择整个会话，包括其他 参与者的贡献。

--participant 有意匹配跨身份命名空间的原始 actor ID； 它不是仅限资料的选择器。报告的 participantMatches 显示 与每个请求 ID 匹配的带类型身份，包括歧义匹配。 删除前，请在 --dry-run --json 中审查这些身份和所选的整个会话。 资料合并不会静默重新解释原始选择器。

显式 ID 和键针对已配置 session.store 中的实时会话和保留归档进行解析， 包括自定义和共享存储。匹配 仍限定于所选 agent。 报告将每个结果标记为 live、archived 或 unresolved。 未解析的显式值会按字面记录为会话 ID，用于未来 排除；它不能证明已找到所请求的会话。ID 精确 且区分大小写匹配，包括匹配保留归档名称时。 缩写不会选择更长的会话 ID。

钩子来源和参与者选择器需要实时元数据；仅归档 记录不保留这些事实。通过完整 ID 或键选择这些归档。 钩子来源匹配是精确的：IMAP 使用 email，Gmail 钩子使用 gmail， 通用 webhook 使用 webhook。当原始精确来源丢失时，仅包含粗略 webhook 分类的旧保留记录无法区分 IMAP 和通用 webhook； 请改为通过完整 ID 选择这些会话。 --since 使用实时会话的创建时间或归档的创建时间， 而不是单个消息的时间戳。未解析的显式 ID 没有时间戳， 并且仍会被选中。

阅读报告¶

预览和应用使用相同的匹配逻辑，但每次都会读取当前状态； 预览不是不可变的计划，也不是对后续写入的锁。应用 与记忆插件的暂存和文件变更相协调。它在准备后重新检查 所选谱系，如果谱系发生变化则刷新计划，同时 保留已识别为属于所选会话的条目。索引 会丢弃过期结果，而不是恢复已清除的块或缓存的嵌入； 重新运行报告来源变更的索引命令。直接 agent 编辑和 外部写入器不共享该锁，因此在敏感 清理期间暂停它们。之后重新运行预览。空选择或零计数不能 证明没有相关数据残留。

如果删除失败¶

删除不是跨文件和存储的单个事务。索引和插件状态 清理（包括重写备份）在记忆文件编辑之前运行；语料库和 来源证据最后移除，以便重试可以识别剩余产物。 如果清除失败，解决报告的存储或文件系统错误，并使用相同的选择器重新运行 相同命令。不要手动删除其语料库或来源 记录。成功后，使用 --dry-run 重复该命令以 审查剩余内容。

已移除的产物¶

清除操作会从扫描的记忆文件、选定的会话语料行以及选定会话的转录索引块中移除匹配的晋升标记条目和会话引用部分。它会清除关联的全文行和向量行、匹配的短期状态、摄取 seen-hash 范围以及来源行。匹配内容会从 dreaming 重写备份中擦除，而不是删除所有备份。

对于非空会话选择，Forget 还会清除所选代理的整个 embedding 缓存，包括从未完成索引重建中保留的结果。这些结果可能尚未链接到已发布的索引块。无关的已发布索引条目仍可使用，但后续索引可能需要重新生成其缓存的 embedding。试运行报告包含整个缓存的移除数量；试运行或空会话选择不会清除缓存。

整合会保留被替换晋升标记的来源，同时保留的重写前像引用它们。这些来源只有在活动条目、保留的前像、日记摘录和索引快照不再引用这些键时才会被修剪。新的整合历史摘录携带替换条目的谱系，并随其一起移除。只要摘录仍存在，其来源就会保留，即使在备份轮换之后；日记历史没有自动过期。在共享工作区中，针对另一个代理的后续清除也会检查其索引快照，即使第一次清除已经移除了共享文件内容。

当选择非空时，它还会清除内部 dreaming-narrative、cron 或 heartbeat 会话的过期索引记录。因此，索引清理可能包含所选会话之外的内容，并且来自已更改记忆文件的所有块都可能被失效，以便后续重新索引。

artifacts 计数器包括：

• memoryFiles、memoryEntries、memoryLines：已更改的记忆文件、已移除的标记条目或会话引用部分，以及包含精确选定语料片段的额外整行。
• sessionCorpusFiles、sessionCorpusLines：已更改的语料文件和已移除的语料行。
• indexChunks、indexSources、ftsRows、vectorRows、embeddingCacheRows：已移除的索引和缓存记录。
• shortTermEntries、seenHashScopes、backups、originRows：已移除的短期条目和去重范围、重写的备份记录，以及已删除的来源行。

具有混合谱系的条目会被整体删除；该命令不会重写它们以仅保留未选定的贡献。幸存的来源可能稍后支持新条目，但不保证重新生成。

重新准入与保留数据¶

实际清除会在移除产物之前，在代理的 SQLite 数据库中记录所选会话 ID 为已遗忘。自动 dreaming 摄取、memory session-backfill 以及转录索引（包括 memory index --force）会检查这些记录。自动摄取会记录原因 forgotten。重复清除不会移除排除，删除准入策略规则也不会撤销它。具有新 ID 的未来会话不会被之前的清除排除。

新的 session-backfill 日记事实和反思携带条目标记和来源，包括由失败的 apply 留下的 REM 预览和日记块。遗忘会移除每个匹配行，包括已转换或合并的声明；无关行保留。历史未标记的 backfill 文本没有可重建的谱系。在 DREAMS.md 和 memory/dreaming/**/*.md 等梦境日记中的精确语料引用可以作为整行移除。未跟踪的转述无法可靠归属，因此保留。

单独的 curatedWrites 记录不会删除文件或其自由格式编辑。最新的文件级 write-observer 记录以及保留转录中受支持的 write、edit 和 apply_patch 调用会标识需要审查的文件。这不是对 shell 写入或外部编辑器的完整审计。已报告的文件仍可能因单独的标记、会话引用或精确引用清理而更改。

memory promote¶

从 memory/YYYY-MM-DD.md 对短期候选项进行排名，并可选地将顶级条目追加到 MEMORY.md。

openclaw memory promote [--agent <id>] [--limit <n>] [--min-score <n>] \
  [--min-recall-count <n>] [--min-unique-queries <n>] [--apply] [--include-promoted] [--json]

CLI 和计划执行的 dreaming 扫描共享以下深度阶段默认值。 显式 CLI 标志会覆盖这些默认值，用于一次性手动运行。

具有 untrusted 或 system 来源的条目会在排序前被排除，因此它们不会占用预览限制，也不会出现在 promote-explain 中。晋升在写入前仍会重新检查当前来源。

排序信号包括：召回频率、检索相关性、查询多样性、时间新近性、跨天整合以及派生概念丰富度，这些数据来自记忆召回和每日摄取流程，并为重复的 dreaming 回访提供浅睡眠/REM 阶段强化加成。写入前，晋升会重新读取实时每日笔记，因此排序之后对短期片段的编辑或删除会被尊重，而不是从过期快照中晋升。

memory promote-explain¶

解释一个晋升候选项的得分明细。

openclaw memory promote-explain <selector> [--agent <id>] [--include-promoted] [--json]

<selector> 匹配候选项的键（精确或子串）、路径或片段文本。

memory rem-harness¶

预览 REM 反思、候选真相以及深度阶段晋升输出，且不写入任何内容。

openclaw memory rem-harness [--agent <id>] [--path <file-or-dir>] [--grounded] [--include-promoted] [--json]

• --path <file-or-dir>：从历史 YYYY-MM-DD.md 每日文件而不是实时工作区为 harness 提供种子。
• --grounded：还会根据历史笔记渲染一个基于事实的 What Happened / Reflections / Possible Lasting Updates 预览。

memory rem-backfill¶

将基于事实的历史 REM 摘要写入 DREAMS.md 以供 UI 审阅。 可逆。

openclaw memory rem-backfill --path <file-or-dir> [--agent <id>] [--stage-short-term] [--json]
openclaw memory rem-backfill --rollback [--rollback-short-term] [--json]

• --path <file-or-dir>：除非设置了 --rollback/--rollback-short-term，否则必填。用于回填的历史每日记忆文件或目录。
• --stage-short-term：还会将基于事实的持久候选项放入实时短期晋升存储，以便正常深度阶段对其进行排序。
• --rollback：从 DREAMS.md 中移除之前写入的基于事实的日记条目。
• --rollback-short-term：移除之前暂存的基于事实的短期候选项。

memory session-backfill¶

将保留的会话历史提炼为基于事实的短期候选项。它与 dreaming 共享转录信任分类、准入策略和语料存储。暂存的候选项会保留每个贡献会话的来源，以便 memory forget 之后可以选择它们。配置的排除项适用于预览、REM 和 apply 模式；已遗忘的会话在所有模式下都保持排除。默认是只读预览，按从最旧的未处理日期到最新的顺序排列。

openclaw memory session-backfill --agent <id> [--from YYYY-MM-DD] [--to YYYY-MM-DD] \
  [--limit-days <n>] [--archive-files <path...>] [--rem | --apply] [--json]
openclaw memory session-backfill --agent <id> --rollback [--json]

该命令读取所选 agent 的规范会话存储，包括会话轮换保留的 SQLite 转录标识。它使用与实时会话摄取相同的已跟踪消息哈希和每次运行上限，因此重复的 --apply 运行会跳过已摄取的消息。规范存储中的所有者和 agent 行符合条件；工具输出、网页或非所有者输入，以及没有可靠所有者来源的轮次会被排除。外部归档文件没有经过身份验证的所有者来源契约，因此其嵌入的所有权字段仍不受信任，无法暂存。之前使用 memory forget 清除的会话会持续保持排除，即使其原始转录仍然存在或其已跟踪哈希已被清除。

--apply 在一次调用中将所选历史处理到完成，同时让每个有界批次保持在自己的事务中。人类可读输出和 JSON 输出会报告每个批次的进度，以及总批次数、候选项数和暂存条目数。因此，成功 apply 后立即预览会报告零个新候选项。它只写入 memory/.dreams/ 下的会话语料、短期暂存状态，以及 DREAMS.md 中的可逆日记条目。它从不写入 MEMORY.md 或 USER.md；持久晋升仍然是单独的 memory promote 或 dreaming 决策。--rem 和 --apply 互斥。

两种写入模式都会在发布文本前记录日记来源，因此后续应用失败不会留下无法追溯的日记引用。REM 仅保留日记及其来源记账信息：它不会保留会话语料库、暂存候选项、推进摄取游标，或调用模型。

回填回滚有意与 memory rem-backfill 共享：两个命令使用相同的仅限 grounded 的暂存类和日记标记。仅当你打算清除该工作区中两个命令的 grounded 回填产物时，才运行 session-backfill --rollback。回滚还会移除由会话回填添加的受跟踪哈希，并回退受影响的转录游标，因此幸存的合格候选项可以再次预览和应用。回滚不会删除已遗忘会话记录，也不会重新接纳已清除的会话。

做梦¶

做梦是后台记忆整合系统，具有三个协作阶段，按顺序在一个计划上运行：light（排序/暂存短期材料）、REM（反思并浮现主题）、deep（将持久事实提升到 MEMORY.md）。只有 deep 会写入 MEMORY.md。

• 通过 plugins.entries.memory-core.config.dreaming.enabled: true 启用（默认 true）；memory-core 会自动管理清扫 cron 任务，无需手动执行 openclaw cron add。
• 在聊天中使用 /dreaming on|off 切换；使用 /dreaming status 检查（或 /dreaming//dreaming help）。on/off 需要频道所有者身份或网关 operator.admin；status 和帮助对任何能够调用该命令的人都可用。
• 人类可读的阶段输出会写入 DREAMS.md（或已存在的 dreams.md）。默认情况下（dreaming.storage.mode: "separate"），每个阶段还会将独立报告写入 memory/dreaming/<phase>/YYYY-MM-DD.md；将 mode: "inline" 设置为内联，可将报告折叠到每日记忆文件中，或设置为 "both" 以同时使用两者。
• 计划任务和手动 memory promote 运行共享相同的 deep 阶段排名信号和默认阈值；显式 CLI 标志仍为单次运行覆盖。
• 计划运行会扇出到每个已配置代理的记忆工作区。

计划默认值（plugins.entries.memory-core.config.dreaming）：

{
  "plugins": {
    "entries": {
      "memory-core": {
        "config": {
          "dreaming": {
            "enabled": true
          }
        }
      }
    }
  }
}

完整键列表和阶段详情：做梦、Memory 配置参考。

SecretRef 网关依赖¶

如果当前 memory 远程 API 密钥字段被配置为 SecretRefs，memory 命令会从当前网关快照中解析它们；如果网关不可用，命令会快速失败。这需要支持 secrets.resolve 方法的网关；旧版网关会返回未知方法错误。

相关¶

• CLI 参考
• Memory 概览