小龙虾记忆系统研究-虾说蓉城

原文版本：2026-05-08；资料复核：2026-10-13。 源码基线：openclaw/openclaw @ 5584b0ad。 分析的是官方实现与配置，不是峰哥当前环境的运行检查。

一、设计哲学：记忆即文件

OpenClaw 的核心理念可以概括为「把持久记忆写成可审计的文件」，像给助手留一本能翻阅的工作笔记。默认记忆后端以工作空间 Markdown 为重要事实来源：

~/.openclaw/workspace/
├── USER.md               # 稳定用户资料与偏好
├── MEMORY.md             # 精炼的长期事实与决策
├── DREAMS.md             # 梦境日记与审查输出（可选）
└── memory/
    └── YYYY-MM-DD.md     # 详细每日笔记

“没有隐藏状态”是官方描述文件化记忆时的概括，不应理解为整个系统没有会话历史、SQLite 索引、缓存或插件状态。当前对话中尚未落盘的内容也能暂时影响回答；跨会话能否找回，则取决于保存、索引、权限和召回。

用户可查看与编辑笔记，但删除一个文件不一定清掉其他副本、索引或已生成的长期记忆。其他 memory engine 还可能使用外部存储，不能把整个生态都说成只有 Markdown。记忆概览。

二、核心组件总览

可审计来源：USER.md / MEMORY.md / memory/*.md / 允许摄入的会话
        ↓ 索引或引导加载
├── Bootstrap / 运行时记忆指导（受 harness 与隐私门控制）
├── memory_search / memory_get（按需搜索和读原文）
├── 确定性可信触发召回（有限自动注入）
└── Active Memory（需要时升级 blocking 深度召回）
        ↓
本轮上下文 → 主模型回复

Dreaming：后台收集短期信号 → light → REM → deep → 整理 MEMORY.md

这些是相互配合的通道，不是“所有内容先过 Bootstrap，再过搜索、子代理和梦境”的串行管道。检索到、注入了、回答正确是三个不同结果，不能互相替代。

三、Bootstrap 文件注入体系

3.1 工作机制

OpenClaw 从配置的 agent workspace 解析引导材料。非 Codex 路径可以将符合条件的文件放进 Project Context；native Codex 有原生项目发现、线程指导与按需记忆工具，不是每个 turn 统一复制所有文件。

缓存前缀优化也不等于内容不受会话或权限影响。来源、隐私门、prompt mode、截断预算与 refresh 都会影响实际可见内容。System Prompt。

3.2 注入文件列表

不能用“文件名排在前面”判断授权级别。记忆能保留授权背景，实际操作仍由工具策略、审批与沙箱约束。

3.3 截断机制

• agents.defaults.bootstrapMaxChars：当前默认 20,000 字符，原文的 12,000 已过时。
• agents.defaults.bootstrapTotalMaxChars：当前默认 60,000 字符。
• 超预算时截断进入提示词的副本并提示，原文件不被截断。用 /context list / /context detail 查看 raw 与 injected 大小。

memory/*.md 不参加普通 Bootstrap。裸 /new / /reset 的首轮可一次性加载今天、昨天的日期笔记及对应带 slug 的变体；这不是每轮自动加载承诺。

3.4 Sub-agent 差异

当前普通子代理 Bootstrap allowlist 只包含 AGENTS.md，不是原文的 AGENTS.md + TOOLS.md。native Codex 子代理另有宿主继承规则，需与此过滤器分开。过滤源码。

四、长期记忆 — MEMORY.md

4.1 定位与内容

MEMORY.md 保存跨会话仍有价值的非用户画像事实、决策与短摘要；稳定沟通偏好和用户画像更适合 USER.md。详细过程、每日进展放在 memory/*.md，不把长期文件堆成流水账。

4.2 加载时机

不能再写“每个 DM turn 全文自动注入”。非 Codex 的引导路径有预算与隐私限制；native Codex 在记忆工具可用时以小段记忆访问指导和按需读取为主，工具不可用时才走有界回退。看见一份截断副本也不等于完整记住所有条目。

4.3 写入方式

用户要求记住、任务中主动保存、压缩前 memory flush、Dreaming 晋升都可能产生持久化写入。它们各有目标与门控，不是都会直接写 MEMORY.md。当前 Memory Core 的压缩前文件 flush 主要向每日笔记追加新内容；Dreaming 再整理合格长期事实。

4.4 管理原则

保持高信号、记录来源与时间、及时替换过期结论。临时授权要写清生效条件和到期条件，不能把一次许可记成永久授权。

五、每日笔记 — memory/YYYY-MM-DD.md

5.1 定位

每日笔记是工作记录层。它们可以长期留在磁盘上，不因叫“短期记忆”就自动过期或删除。

5.2 加载策略

普通轮次主要通过 memory_search / memory_get 检索和读取；裸 /new / /reset 的启动上下文是近期笔记自动加载的特例。工作空间指令也可能要求模型主动读某些文件，但这与运行时自动注入不是一回事。

5.3 存储位置

默认在工作空间 memory/ 下。Dreaming 可摄入符合条件的材料；未晋升仅表示没有进入长期摘要，不表示原笔记被删除。

六、Active Memory（主动记忆）

6.1 设计动机

主动召回给回复前增加一次找旧资料的机会，适合以前的决策、多会话和时间关系问题。它不是“每次必能想起相关记忆”的保证。

6.2 运行机制

当前默认 mode: "escalate"：

用户消息
→ 确定性可信触发召回
   ├── 强匹配：有限注入
   └── 无强匹配：检查是否有回忆意图
         ├── 无：不调用深度召回子代理
         └── 有且符合会话条件：blocking 子代理 → 摘要 / NONE / unavailable
→ 主回复

always 才保留每个符合条件轮次都调用子代理的模式；off 关闭深度召回，但确定性可信触发通道可以保留。会话类型、agent、聊天范围与插件启用状态都会限制是否触发。官方流程。

6.3 关键配置参数

配置位于 plugins.entries.active-memory，启用开关在外层，召回选项在 config：

完整约束以官方配置表为准。

6.4 Query Modes（查询模式）

• message：只取当前消息，材料较少。
• recent：加入近期用户轮次，适合跟进问题。
• full：提供更多历史，可能帮助消歧，也可能带来噪声与额外开销。

原文的“message 速度最快、full 质量最高”不是已测结论。应按同一批问题测漏检、误检与延迟，而不是把上下文多当成质量必然高。

6.5 Prompt Styles（召回策略）

strict、balanced、contextual、recall-heavy、precision-heavy、preference-only 都是取舍方式。偏好型策略可能更聚焦，但也会漏掉事件或决策；宽召回会增加相关候选，也可能混入不相关内容。

6.6 适用场景

适合有真实历史材料、需要个性化的持续对话；不适合把隐藏个性化带到无关自动化、一次性 API 工作或内部 helper。跨会话召回应按可见性控制，不能把群聊当成私有资料的任意出口。

6.7 会话开关

/active-memory status
/active-memory off
/active-memory on

以上只影响当前会话。当前版本也支持 /active-memory status --global、off --global、on --global，但要求 owner 或 operator.admin。全局形式修改 plugins.entries.active-memory.config.enabled，保留外层插件 enabled，使重新开启的命令仍可用；两层开关不能混为一谈。固定版本会话控制。

七、Dreaming（梦境后台晋升系统）

7.1 定位

Dreaming 是 memory-core 的后台整理机制。当前默认启用，可用 plugins.entries.memory-core.config.dreaming.enabled: false 关闭。原文“默认关闭”的结论已经过时。调度器关闭时，自动调度行为也会受限。固定版本 Dreaming 文档。

7.2 三阶段架构

Light → REM → Deep
暂存     主题反思  评分、来源门控、整理晋升
                  ↓
               MEMORY.md

机器状态：SQLite-backed plugin state
人工审查：DREAMS.md 与可选阶段报告

• Light 摄入与去重短期材料，不写长期记忆。
• REM 产生主题/强化信号，不直接写 MEMORY.md。
• Deep 同时检查 minScore、minRecallCount、minUniqueQueries，重新读取来源，再处理合格条目。
• 当前 Deep 不只有追加：可通过无工具的 completion 选择新增、合并与替代，由写入器按证据组合内容；不合格或不可用的整理决策可回退到追加路径。

“有阈值与审计”降低部分风险，不保证记忆完全真实。重复错误、过期来源或来源误分类仍需要人工检查。

7.3 Deep 排名信号（权重）

这些是该版本实现/默认设计中的基础信号，另有 phase reinforcement 与门控，不是事实真伪评分。Dreaming 排名说明。

7.4 Dream Diary（DREAMS.md）

日记和阶段摘要供人审查，不能作为自己的晋升来源形成反馈循环。机器状态当前在 SQLite，旧 memory/.dreams/*.json 不再是现行权威状态。不要把旧 JSON 路径照搬成新部署架构。

7.5 Grounded Backfill（基于来源回填）

# 预览历史日期笔记的 grounded 输出
openclaw memory rem-harness --path ./memory --grounded

# 生成可审查的日记回填；这是写操作示例
openclaw memory rem-backfill --path ./memory

# 暂存合格候选，不直接晋升长期记忆
openclaw memory rem-backfill --path ./memory --stage-short-term

Grounded 指有原始材料依据，不等于材料中的每句话已被外部证实。本文未执行这些写操作。

7.6 调度

启用时 memory-core 管理 recurring cron sweep，实际阶段顺序为 light → REM → deep。默认 frequency 为 0 3 * * *，须按配置时区理解，不是所有服务器北京时间凌晨三点。模型覆盖还受插件 model-override 信任配置约束。记忆配置参考。

八、Memory Search（记忆搜索）

8.1 工作机制

Builtin 后端可以并行做向量和 BM25，再合并、排序与去重。当前还包含文件名匹配、时效与重要性信号，不只是两条分数相加。

query → 向量 / BM25 / 文件名候选
      → 混合相关性 → 时间与重要性排序 → MMR → 有限结果

单一路径不可用时可能使用其他可用路径。是否降级与显式 provider 设置有关，不应承诺“任何 embedding 错误都自动回退成功”。搜索说明。

8.2 支持的嵌入提供商

当前文档列出 OpenAI、Gemini、Voyage、Mistral、Bedrock、DeepInfra、GitHub Copilot、Local、Ollama、LM Studio、OpenAI-compatible 等适配器。

现行入口是 memory.search.provider。默认 OpenAI；显式选择其他 provider 时还需可用服务、模型和对应授权。原文的“自动检测全表”及 node-llama-cpp 本地后端说明已不宜照搬：当前 local 使用受管理的 llama.cpp provider。凭证存在也不代表索引构建与召回一定成功。

8.3 高级特性

日期笔记可采用 30 天半衰期排序，MEMORY.md / USER.md 等精炼文件保持 evergreen；这是排名衰减，不是删除。MMR 减少相似片段重复，不保证 top 结果覆盖所有关键主题，也不保证答案正确。

8.4 索引机制

当前默认索引与会话数据共用 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite。旧 ~/.openclaw/memory/<agentId>.sqlite 是历史路径，不能当现行默认。

分块、监听、同步与重建受配置和版本影响，原文的“固定约 400 token / 重叠 80 / 1.5 秒”不再作为统一契约。可以用 openclaw memory status 检查状态，必要时才考虑 openclaw memory index --force。Builtin Memory。

九、Compaction（会话压缩）

9.1 触发条件

接近上下文限制、上下文溢出恢复或手动 /compact 都可能触发；运行时与 provider 的原生压缩还会影响具体路径。

9.2 工作机制

旧内容生成摘要，近期内容尽量保留；摘要和活跃上下文会丢失细节。当前内置 transcript 保留原消息，但不能把“磁盘可审计”说成“每轮模型仍看到完整历史”。

9.3 Memory Flush（记忆冲刷）

压缩前的静默 flush 提供保存机会，不保证无损。默认启用，但不可写工作空间、工具限制、取消或失败都可能导致跳过。

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

这是合法 JSON 的局部示例；专用模型不等于本地必然更快，也不证明该模型已安装。官方 flush 行为。

9.4 Compaction vs Pruning

十、Context Engine（可插拔上下文引擎）

10.1 定位

决定模型输入的消息集合与压缩方式，像整理每次开会需要带上的资料，而不是外部记忆数据库本身。

10.2 生命周期钩子

当前必需 info、ingest、assemble、compact；afterTurn、维护与子代理生命周期是可选扩展。涉及持久化，还须遵守宿主的原子提交和幂等边界。

10.3 Legacy Engine（默认）

legacy 保留既有组装和摘要压缩行为；ingest / after-turn 不额外负责记忆写入，assemble 也不自动产生动态召回内容。

10.4 Plugin Engines

可用 registerContextEngine() 注册并在 slot 选择。assemble() 的 systemPromptAddition 可加入召回指导，但 buildMemorySystemPromptAddition() 是构建指导的 helper，不是自动执行检索的保证。官方接口。

十一、会话管理与记忆的交互

11.1 Session 路由规则

Direct / group / thread / cron / webhook 的隔离由 session key 和配置决定。不能一概说所有 DM 共享、所有 cron 每次新建；绑定已有会话、隔离任务与原生 harness 都可能有不同路径。

11.2 Session 生命周期

手动 /new / /reset、保留策略和不同运行时的生命周期需按安装版配置检查。原文的“所有环境默认每日凌晨四点重置”不再作为当前普遍事实。

11.3 Session 与记忆的关系

Transcript 是历史，长期记忆是提炼内容，索引是检索入口。Active Memory 可在获准时查跨会话资料，不只是当前会话内部召回；上下文压缩、会话重置、删除记忆也是不同操作。Session 文档。

十二、Built-in Memory Engine（内置记忆引擎）

12.1 定位

默认 SQLite 后端提供关键词检索；向量能力需对应 embedding 服务。本地向量加速可选，不能把“无需额外依赖”扩大为所有向量 provider 开箱可用。

12.2 提供的能力

FTS/BM25、向量与混合查询，以及可选 sqlite-vec 加速。sqlite-vec 不可用时可以回退进程内余弦计算，但这不解决 embedding 服务本身不可用的问题。

12.3 索引文件位置

~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite

这是本次版本的默认位置，存储目的地配置可能改变它。

十三、Memory Wiki 插件（知识库层）

memory-wiki 增加结构化 claims、evidence、矛盾与时效追踪以及 wiki 工具；它不替换当前选择的 memory provider。

这里“active memory plugin”在部分官方资料中指 plugins.slots.memory 选中的记忆插件，默认 memory-core，不要与名为 active-memory 的深度召回子代理插件混为一谈。召回、Dreaming 和 wiki 是不同职责。官方 Memory 概览。

十四、工具汇总

具体召回工具集合由 provider 与工具 allowlist 决定，不保证所有环境都有 memory_recall。

十五、当前环境状态

15.1 峰哥的 OpenClaw 配置

原报告记录过启用 Dreaming 的配置片段，但这只是 2026-05-08 的历史笔记。本次任务没有读取本机配置、凭证或服务器状态，不以该片段证明当前环境。

15.2 启用状态

当前是否启用 Active Memory、向量索引、Dreaming 或 wiki 都记为未现场核验。没有配置片段不等于功能一定关闭；有 enabled: true 也不等于服务、索引和调度都正常。

十六、总结：OpenClaw 记忆系统架构

可审计文件与允许的历史
       ↓
Builtin / 其他 memory provider
       ├── 显式搜索与原文读取
       ├── 确定性可信触发
       └── Active Memory 按需升级
       ↓
Context Engine + 运行时门控
       ↓
本轮上下文与回复

后台：Dreaming → light → REM → deep → 长期记忆整理

核心设计原则

1. 透明与可审计：文件能阅读，但系统仍有索引、会话和插件状态。
2. 分层职责：引导、显式检索、主动召回、后台整理与压缩各解决一类问题。
3. 可插拔：后端与上下文引擎可替换，能力和隐私边界需重新检查。
4. 召回有界：没有“永不遗忘”保证，要检查来源、过期与漏检。
5. 主动召回是取舍：只在需要时付出额外模型调用与等待。

2026-10-13 资料核对：已读取官方固定提交的 Memory、Dreaming、System Prompt、Context Engine、Session、Builtin/Search 文档，以及 Bootstrap 过滤源码与 Active Memory 配置/流程原文。未运行软件、检索基准、现场配置或延迟测试；历史环境记录未当作当前实测。