记忆概览

OpenClaw 通过在你的代理工作区（默认 ~/.openclaw/workspace）中写入纯 Markdown 文件来记忆事物。模型只记住已保存到磁盘的内容；没有隐藏状态。

工作原理¶

你的代理有四个与记忆相关的文件：

USER.md（可选）——稳定的偏好、沟通风格、人际关系和当前项目上下文，以指令形式写出。在会话开始时以单独的小预算加载。
MEMORY.md——长期记忆。持久的非个人档案类事实和决策。在会话开始时加载。
memory/YYYY-MM-DD.md（或 memory/YYYY-MM-DD-<slug>.md）——每日笔记。持续更新的上下文和观察。在干净的 /new 或 /reset 时，今天和昨天的日期笔记会自动加载；带 slug 的变体（例如由内置的 session-memory hook 写入的那些）会与仅含日期的文件一起被拾取。
DREAMS.md（可选）——供人工审阅的梦境日记（Dream Diary）和 dreaming 扫描摘要，包括基于事实的历史回填条目。

Tip

如果你希望你的代理记住某件事，直接告诉它：“记住我更偏好 TypeScript。” 它会将笔记写入相应的文件。

内容放置位置¶

USER.md 是紧凑的用户模型层。请将稳定的偏好和档案事实写成祈使指令，并带有观察日期和 active/superseded 元数据。当偏好发生变化时，应就地替换（supersede）它，而不是追加一条相互矛盾的 active 指令。参见用户模型。

MEMORY.md 是紧凑、精选的层次，用于保存持久的非档案类事实、长期决策和简短摘要，这些内容应在会话开始时可用。它不是原始记录、每日日志或详尽归档。

memory/YYYY-MM-DD.md 文件是工作层：包含详细的每日笔记、观察、会话摘要以及日后可能仍有用的原始上下文。这些文件会被 memory_search 和 memory_get 索引，但不会在每次轮次中被注入到 bootstrap prompt 中。

随着时间的推移，日常笔记中的有用材料会由默认的 dreaming 扫描提炼到 MEMORY.md 中。生成的工作区指令仍鼓励代理在工作时记录持久的事实，而 dreaming 负责后台整合。默认的 heartbeat prompt 本身不执行任何记忆维护。

如果 MEMORY.md 超过 bootstrap 文件预算，OpenClaw 会保持磁盘上的文件完整，但会截断注入到上下文中的副本。请将此视为一个信号：将详细材料移入 memory/*.md，仅在 MEMORY.md 中保留持久摘要；或者，如果你愿意投入更多 prompt 预算，可以提高 bootstrap 限制。使用 /context list、/context detail 或 openclaw doctor 查看原始大小与注入大小以及截断状态。

从编码助手导入¶

Control UI 可以从 Codex、Claude Code 和 Hermes 导入现有的本地记忆。打开设置 → 导入记忆，选择目标代理，查看检测到的文件，然后确认导入。对于现有的默认代理，你也可以打开 设置 → 询问 OpenClaw 并说 import memory；这个更精简的聊天向导要求完成入门（onboarding），只复制新检测到的记忆，并报告每个来源的失败或可能的部分副本。OpenClaw 只复制 Markdown 记忆：

Codex：位于 ~/.codex/memories（或 CODEX_HOME/memories）下的整合后的 MEMORY.md 和 memory_summary.md 文件。原始的 rollout 和 transcript 文件不会被导入。
Claude Code：来自 ~/.claude/projects/*/memory 下每个项目的自动记忆（auto-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 中。源文件保持不变。

预览会标记目标冲突。启用 替换现有导入 以替换这些文件；应用（apply）会创建经过验证的导入前备份，并在迁移报告中保留被覆盖文件的逐项副本。

对操作敏感的记忆¶

大多数记忆是普通的 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。开箱即用，支持关键词搜索、向量相似度和混合搜索。无需额外依赖。

Honcho

AI 原生的跨会话记忆，支持用户建模、语义搜索和多智能体感知。通过插件安装。

LanceDB

基于 LanceDB 的记忆，支持 OpenAI 兼容嵌入、自动召回、自动捕获和本地 Ollama 嵌入。通过插件安装。

知识 Wiki 层¶

如果你希望持久记忆更像一个持续维护的知识库而不是原始笔记，请使用随附的 memory-wiki 插件。它将持久知识编译到 wiki 仓库中，具有确定性的页面结构、结构化主张和证据、矛盾和新鲜度跟踪、生成的仪表板、编译摘要以及 wiki 原生工具（wiki_status、wiki_search、wiki_get、wiki_apply、wiki_lint）。

memory-wiki 不会取代当前活动的记忆插件；活动的记忆插件仍然负责召回、提升和梦境处理。memory-wiki 在其旁边增加了一个富含来源追踪的知识层。你可以在 Control UI 的 Memory → Dreams → Diary → Memory Wiki 下浏览编译后的 wiki（详情）。

Memory Wiki

将持久记忆编译为富含来源追踪的 wiki 仓库，支持主张、仪表板、桥接模式和 Obsidian 友好的工作流程。

自动记忆刷新¶

在压缩总结你的对话之前，OpenClaw 会运行一个静默回合，提醒智能体将重要上下文保存到记忆文件中。此功能默认开启；设置 agents.defaults.compaction.memoryFlush.enabled: false 可将其关闭。

刷新过程使用对话的私有副本，因此其维护消息永远不会出现在后续的用户回合中，即使被中断也是如此。它对记忆文件的写入仍然正常保存。

记忆刷新需要可写的工作区访问权限。沙盒要求只读或没有工作区访问权限的会话会跳过刷新，包括具有持久化沙盒要求并覆盖智能体配置的会话。

要让该维护回合在本地模型上运行，请设置一个仅适用于记忆刷新回合的精确覆盖（它不会继承当前会话的模型回退链）：

{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "model": "ollama/qwen3:8b"
        }
      }
    }
  }
}

Tip

记忆刷新可防止压缩期间出现上下文丢失。如果你的智能体在对话中有关键事实尚未写入文件，它们会在总结发生之前自动保存。

梦境处理¶

梦境处理是记忆的默认后台整合路径。它收集短期召回信号，对候选进行评分，并且只将有资格的属主或智能体派生项目提升到长期记忆（MEMORY.md）：

默认开启：通过 plugins.entries.memory-core.config.dreaming.enabled: false 禁用它。
计划调度：启用后，memory-core 自动管理一个用于完整梦境扫描的循环 cron 任务。
阈值过滤：提升必须通过分数、召回频率和查询多样性门槛。
整合处理：在确定性门槛之后，一个无工具的完成阶段会选择合并和取代。记忆写入器根据经过验证的源证据组成结果；无效或不可用的决策使用仅追加的回退方式。
污染门控：不受信任和系统派生的候选永远不会进入整合提示或持久提升路径。
可审查：阶段摘要和日记条目写入 DREAMS.md 供人工审查，包括重写次数和亮点。

此后台模式遵循睡眠时间计算（sleep-time compute，arXiv:2504.13171）背后的动机。溯源感知的反思（provenance-aware reflection）也借鉴了生成式智能体（Generative Agents）研究在持久记忆方面的经验。

有关阶段行为、评分信号和梦境日记（Dream Diary）的详细信息，请参阅梦境处理。

基于笔记的回填与实时晋升¶

梦境系统有两条相互关联的审查通道：

实时梦境处理：基于 SQLite 插件存储中的短期梦境状态工作，也是常规深度阶段决定哪些内容晋升至 MEMORY.md 时所使用的机制。Doctor 负责迁移 memory/.dreams/ 中的旧版梦境 JSON 状态；使用旧状态前，请先运行 openclaw doctor --fix。
基于笔记的回填：将历史 memory/YYYY-MM-DD.md 笔记作为独立日文件读取，并将结构化审查输出写入 DREAMS.md。

基于笔记的回填适用于重放较旧笔记，并检查系统认为哪些内容具有持久性，而无需手动编辑 MEMORY.md。

openclaw memory rem-backfill --path ./memory --stage-short-term

--stage-short-term 标志会将基于笔记的持久化候选暂存到常规深度阶段已使用的同一个短期梦境存储中；它不会直接晋升这些候选。因此：

DREAMS.md 仍作为人工审查界面。
短期存储仍作为面向机器的排序界面。
MEMORY.md 仍仅由深度晋升写入。

如需在不触碰普通日记条目或正常回忆状态的情况下撤销重放：

openclaw memory rem-backfill --rollback
openclaw memory rem-backfill --rollback-short-term

命令行接口¶

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