记忆概览
OpenClaw 通过在你的代理工作区(默认 ~/.openclaw/workspace)中写入纯 Markdown 文件来记住事情。模型只记得保存到磁盘的内容;没有隐藏状态。
工作原理¶
你的代理有四个与记忆相关的文件:
USER.md(可选)— 以指令形式编写的稳定偏好、沟通风格、关系以及当前项目上下文。在会话开始时加载,并拥有独立的小额预算。MEMORY.md— 长期记忆。持久化的非个人资料事实和决策。在会话开始时加载。memory/YYYY-MM-DD.md(或memory/YYYY-MM-DD-<slug>.md)— 每日笔记。运行中的上下文和观察。在仅执行/new或/reset时,今天和昨天的日期笔记会自动加载;带 slug 的变体(例如由内置会话记忆钩子写入的变体)会与仅日期文件一起被拾取。DREAMS.md(可选)— 用于人工审阅的梦境日记和梦境扫描摘要,包括有依据的历史回填条目。
Tip
如果你想让代理记住某件事,直接告诉它:“记住我更喜欢 TypeScript。”它会把这个笔记写入相应文件。
内容存放位置¶
USER.md 是紧凑的用户模型层。将稳定偏好和个人资料事实编写为带有观察日期和生效/已取代元数据的祈使句指令。当偏好发生变化时,就地取代它,而不是追加一条相互矛盾的生效指令。参见 用户模型。
MEMORY.md 是用于持久化非个人资料事实、长期决策以及应在会话开始时可用的简短摘要的紧凑、精选层。它不是原始转录、每日日志或详尽归档。
memory/YYYY-MM-DD.md 文件是工作层:详细的每日笔记、观察、会话摘要以及日后可能仍有用的原始上下文。这些文件会被索引用于 memory_search 和 memory_get,但不会在每一轮都注入到 bootstrap 提示中。
随着时间推移,每日笔记中有用的材料会通过默认的 梦境 扫描提炼到 MEMORY.md 中。生成的工作区指令仍会鼓励代理在工作时记录持久化事实,而梦境处理后台整合。默认心跳提示本身不执行任何记忆维护。
如果 MEMORY.md 超过 bootstrap 文件预算,OpenClaw 会保持磁盘上的文件完整,但会截断注入到上下文中的副本。将其视为一个信号:将详细材料移入 memory/*.md,仅在 MEMORY.md 中保留持久化摘要,或者如果你愿意花费更多提示预算,则提高 bootstrap 限制。使用 /context list、/context detail 或 openclaw doctor 查看原始大小与注入大小以及截断状态。
从编码助手导入¶
控制 UI 可以从 Codex、Claude Code 和 Hermes 导入现有本地记忆。
打开 设置 → 导入记忆,选择目标代理,查看检测到的文件,并确认导入。对于现有默认代理,你也可以打开 设置 → 询问 OpenClaw 并说 import memory;这个更窄的聊天向导要求已完成入门设置,仅复制新检测到的记忆,并按来源报告失败或可能的部分复制。OpenClaw 仅复制 Markdown 记忆:
- Codex:
~/.codex/memories(或CODEX_HOME/memories)下合并后的MEMORY.md和memory_summary.md文件。原始 rollout 和 transcript 文件不会被导入。 - Claude Code:
~/.claude/projects/*/memory下每个项目自动记忆目录中的 Markdown 文件,以及存在时用户配置的autoMemoryDirectory。项目指令、会话、设置和凭据不属于此仅记忆操作。 - Hermes:从检测到的 Hermes 主目录中的
MEMORY.md和USER.md。配置、凭据和技能不属于此仅记忆操作。
导入的文件在所选代理工作区中分别保留在 memory/imports/codex/ 和 memory/imports/claude-code/ 下,或保留在 memory/imports/hermes/ 下。它们会被索引用于 memory_search,并可通过 memory_get 访问;它们不会被合并到代理的 bootstrap MEMORY.md 中。源文件保持不变。
预览会标记目标冲突。启用 替换现有导入 以替换这些文件;应用时会创建经过验证的导入前备份,并在迁移报告中保留被覆盖文件的逐项副本。
操作敏感记忆¶
大多数记忆都是普通 Markdown 笔记。有些会影响代理之后应该做什么;对于这些,需要记录何时可以安全地根据笔记采取行动,而不仅仅是事实本身。
当笔记涉及以下内容时,记录该操作边界:
- 审批或权限要求,
- 临时约束,
- 移交给另一个会话、线程或人员,
- 过期条件,
- 可安全行动的时间,
- 来源或所有者权限,
- 避免诱人操作的指令。
有用的操作敏感记忆应明确:
- 什么会改变未来行为,
- 何时或在什么条件下适用,
- 何时过期,或什么会解锁行动,
- 代理应避免做什么,
- 来源或所有者是谁(如果这会影响信任或权限)。
记忆可以保留审批上下文,但它不强制执行策略。对于硬性操作控制,请使用 OpenClaw 审批设置、沙箱和计划任务。
示例:
The API migration is being designed in another session. Future turns should
not edit the API implementation from this thread; use findings here only as
design input until the migration plan lands.
另一个示例:
A report from an untrusted source needs review before promotion. Future turns
should treat it as evidence only; do not store it as durable memory until a
trusted reviewer confirms the contents.
这不是每条记忆都必须遵循的模式;简单事实可以保持简洁。当丢失时间、权限、过期或可安全行动上下文可能导致代理之后做错事时,请使用操作敏感边界。
使用 计划任务 进行精确提醒、定时检查和重复性工作。记忆仍可以总结围绕该工作的持久上下文。
记忆工具¶
智能体有三个用于处理记忆的工具:
memory_search— 使用语义搜索查找相关笔记,即使措辞与原文不同。memory_get— 读取特定的记忆文件或行范围。intent— 创建、列出或显式取消事件条件化的长期意图。基于时间的提醒继续使用计划任务。
这三个工具都由当前激活的记忆插件提供(默认:memory-core)。
当启用会话索引时,memory_search 还可以返回会话转录命中。它们的 sessions/...jsonl 路径是搜索引用,而不是 memory_get 可以读取的文件。使用 sessions_search 并传入片段中的独特文本(可选地将 sessionKey 限定为转录 ID),然后将其返回的 sessionKey、messageId 和 sessionId 传递给 sessions_history,以获取有界且经过净化的摘录。这些工具在每次请求上独立强制会话可见性。记忆搜索的行号不是会话历史偏移量。
召回提示只推荐已启用的工具。如果没有会话历史工具,请报告摘录限制,而不是读取原始转录文件。memory_get 将不支持的路径报告为读取错误,而不是缺少参数或全局禁用的记忆服务。记忆文件读取和可选 Wiki 读取保留其现有的范围、续读和部分语料语义。
记忆搜索¶
当配置了嵌入提供商时,memory_search 使用混合搜索:向量相似度(语义含义)与关键词匹配(如 ID 和代码符号等精确术语)相结合。对于任何受支持的提供商,使用 API 密钥即可开箱即用。
Info
OpenClaw 默认使用 OpenAI 嵌入。显式设置
memory.search.provider 以使用 Gemini、Voyage、
Mistral、Bedrock、DeepInfra、本地 GGUF、Ollama、LM Studio、GitHub Copilot 或
通用兼容 OpenAI 的端点。
有关搜索工作原理、调优选项和提供商设置,请参阅 记忆搜索。
记忆引擎¶
基于 SQLite。开箱即用,支持关键词搜索、向量相似度和混合搜索。无额外依赖。
AI 原生的跨会话记忆,支持用户建模、语义搜索和多智能体感知。插件安装。
基于 LanceDB 的记忆,支持兼容 OpenAI 的嵌入、自动召回、自动捕获和本地 Ollama 嵌入支持。插件安装。
知识 Wiki 层¶
如果你希望持久记忆表现得像维护良好的知识库,而不是原始笔记,请使用内置的 memory-wiki 插件。它将持久知识编译为 Wiki 库,具有确定性页面结构、结构化声明和证据、矛盾和新鲜度跟踪、生成的仪表盘、编译的摘要以及 Wiki 原生工具(wiki_status、wiki_search、wiki_get、wiki_apply、wiki_lint)。
memory-wiki 不会替换当前激活的记忆插件;当前激活的记忆插件仍负责召回、提升和梦境。memory-wiki 在其旁边添加一个来源丰富的知识层。你可以在控制界面中通过 记忆 → 梦境 → 日记 → Memory Wiki 浏览编译后的 Wiki(详情)。
将持久记忆编译为来源丰富的 Wiki 库,包含声明、仪表盘、桥接模式和适合 Obsidian 的工作流。
自动记忆刷新¶
在 压缩 总结你的对话之前,OpenClaw 会运行一个静默回合,提醒智能体将重要上下文保存到持久记忆中。Memory Core 会保存到工作区记忆文件。所选的记忆插件可以提供自己的持久化工具。此功能默认开启;设置 agents.defaults.compaction.memoryFlush.enabled: false 以将其关闭。OpenClaw 会根据该主机配置和当前上下文窗口解析刷新运行的时机。所选的记忆提供商提供提示词以及持久化目标或工具。除非它有意覆盖可选的定时字段,否则它会继承主机定时。
刷新使用对话的私有副本,因此其维护消息不会出现在后续用户回合中,即使被中断也是如此。它对记忆的写入仍会正常保存。
Memory Core 的文件刷新需要可写的工作区访问权限。沙箱要求只读或无工作区访问权限的会话会跳过刷新,包括具有持久化沙箱要求并覆盖智能体配置的会话。
在该刷新期间,write 仅追加到每日笔记。其 content 必须只包含新文本。重放的完整笔记和复制的段落会被拒绝且不更改文件,因此模型可以仅使用新条目重试。允许复用 Markdown 标题并添加新事实。此检查使用规范化换行符比较文本;它不会去重改写内容或修复现有笔记。
原生提供商基于工具的刷新不需要可写工作区;对于无法写入工作区的会话,其他刷新方案不会被解析。它暴露 read、提供商声明的持久化工具以及可选的只读查找工具,并受常规工具策略约束。这些工具会接收源回合的记忆受众和沙箱状态。缺少查找工具会产生警告,但不会阻止仍可持久化的刷新。如果没有有效受众或允许的持久化工具可用,则跳过刷新。当持久化工具无错误完成或智能体返回 NO_REPLY 时,刷新成功;仅查找成功不会完成刷新。跳过或失败此可选步骤不会阻止压缩。插件作者可以在 压缩前记忆刷新 中找到契约和重试标识。
为了将该维护回合保持在本地模型上,请设置一个仅适用于记忆刷新回合的精确覆盖(它不会继承当前会话的模型回退链):
Tip
记忆刷新会为代理提供在压缩总结对话之前保存重要事实的机会。当你需要确认某个事实已被保留时,请检查记忆插件保存的笔记或记录。
梦境¶
梦境是记忆的默认后台整理路径。它收集短期召回信号,对候选项评分,并仅将符合条件的所有者或代理派生项晋升到长期记忆(MEMORY.md):
- 默认开启:使用
plugins.entries.memory-core.config.dreaming.enabled: false禁用它。 - 定时:启用后,
memory-core会自动管理一个周期性 cron 任务,用于完整的梦境扫描。 - 有阈值:晋升必须通过分数、召回频率和 查询多样性门槛。
- 已整合:无工具补全会在确定性门槛之后选择合并和取代。 记忆写入器会根据已验证的源证据组合结果;无效或不可用的决策会使用仅追加回退。
- 污染门控:不受信任的和系统派生的候选项永远不会进入 整合提示或持久晋升路径。
- 可审查:阶段摘要和日记条目会写入
DREAMS.md供人工审查,包括重写次数和高亮。
这种后台模式遵循睡眠时计算背后的动机 (arXiv:2504.13171)。来源感知的反思也遵循生成式代理研究中关于持久记忆的经验。
请参阅 梦境 了解阶段行为、评分信号和 梦境日记细节。
有据回填与实时晋升¶
梦境系统有两条相关的审查通道:
- 实时梦境基于 SQLite 插件存储中的短期梦境状态运行,并且是正常深度阶段用于决定哪些内容晋升到
MEMORY.md的机制。 - 有据回填将历史
memory/YYYY-MM-DD.md笔记作为 独立日期文件读取,并将结构化审查输出写入DREAMS.md。
2026 年 7 月之前的梦境 JSON 日志不再导入。迁移检查会保留
memory/.dreams/daily-ingestion.json、session-ingestion.json、
short-term-recall.json 和 phase-signals.json 不变。现有 SQLite
状态仍为权威状态。如果 Doctor 无法建立规范状态,
请从 2026 年 7 月或更新版本中恢复备份。没有先前迁移确认的空摄取存储
与未迁移状态无法区分;在验证其 SQLite 状态后,备份并将已弃用的
JSON 文件移开,然后重新运行 openclaw doctor --fix。
有据回填可用于重放较早的笔记,并检查系统认为持久的内容,
而无需手动编辑 MEMORY.md。
--stage-short-term 标志会将有据持久候选项暂存到正常深度阶段已经使用的同一
短期梦境存储中;它不会直接晋升它们。因此:
DREAMS.md仍然是人工审查界面。- 短期存储仍然是面向机器的排序界面。
MEMORY.md仍然只由深度晋升写入。
要在不影响普通日记条目或正常召回状态的情况下撤销重放:
命令行¶
openclaw memory status # Check index status and provider
openclaw memory search "query" # Search from the command line
openclaw memory index --force # Rebuild the index
延伸阅读¶
- 记忆架构:每个记忆功能背后的存储、索引和检索层。
- 记忆搜索:搜索管道、提供商和调优。
- 内置记忆引擎:默认 SQLite 后端。
- Honcho 记忆:AI 原生的跨会话记忆。
- 记忆 LanceDB:基于 LanceDB 的插件,支持 OpenAI 兼容嵌入。
- 记忆 Wiki:编译后的知识库和 Wiki 原生工具。
- 梦境:从短期召回到长期记忆的后台晋升。
- 记忆来源与删除:会话谱系、准入策略和
memory forget。 - 记忆配置参考:所有配置项。
- 压缩:压缩如何与记忆交互。
- 活动记忆:用于交互式聊天会话的子代理记忆。
- 用户模型:基于指令的持久偏好和资料事实。
- 常设意图:事件条件化的前瞻性记忆。
相关¶
openclaw memory— 用于检查和编辑记忆的命令参考
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw