跳转至

记忆概览

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。开箱即用,支持关键词搜索、向量相似度和混合搜索。无额外依赖。

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 在其旁边添加一个来源丰富的知识层。你可以在控制界面中通过 记忆 → 梦境 → 日记 → Memory Wiki 浏览编译后的 Wiki(详情)。

Memory Wiki

将持久记忆编译为来源丰富的 Wiki 库,包含声明、仪表盘、桥接模式和适合 Obsidian 的工作流。

自动记忆刷新

在 压缩 总结你的对话之前,OpenClaw 会运行一个静默回合,提醒智能体将重要上下文保存到持久记忆中。Memory Core 会保存到工作区记忆文件。所选的记忆插件可以提供自己的持久化工具。此功能默认开启;设置 agents.defaults.compaction.memoryFlush.enabled: false 以将其关闭。OpenClaw 会根据该主机配置和当前上下文窗口解析刷新运行的时机。所选的记忆提供商提供提示词以及持久化目标或工具。除非它有意覆盖可选的定时字段,否则它会继承主机定时。

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

Memory Core 的文件刷新需要可写的工作区访问权限。沙箱要求只读或无工作区访问权限的会话会跳过刷新,包括具有持久化沙箱要求并覆盖智能体配置的会话。

在该刷新期间,write 仅追加到每日笔记。其 content 必须只包含新文本。重放的完整笔记和复制的段落会被拒绝且不更改文件,因此模型可以仅使用新条目重试。允许复用 Markdown 标题并添加新事实。此检查使用规范化换行符比较文本;它不会去重改写内容或修复现有笔记。

原生提供商基于工具的刷新不需要可写工作区;对于无法写入工作区的会话,其他刷新方案不会被解析。它暴露 read、提供商声明的持久化工具以及可选的只读查找工具,并受常规工具策略约束。这些工具会接收源回合的记忆受众和沙箱状态。缺少查找工具会产生警告,但不会阻止仍可持久化的刷新。如果没有有效受众或允许的持久化工具可用,则跳过刷新。当持久化工具无错误完成或智能体返回 NO_REPLY 时,刷新成功;仅查找成功不会完成刷新。跳过或失败此可选步骤不会阻止压缩。插件作者可以在 压缩前记忆刷新 中找到契约和重试标识。

为了将该维护回合保持在本地模型上,请设置一个仅适用于记忆刷新回合的精确覆盖(它不会继承当前会话的模型回退链):

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

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。

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

延伸阅读

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw