3.2 Memory System¶
本节摘要
从State Management角度看，OpenClaw Memory 系统的核心特点是：文件即 Memory——所有 Memory以人类可读的 Markdown 文件落盘，没有隐藏的黑箱状态。本节按「记了什么 → 怎么写入 → 怎么召回」展开。
一、记了什么：工作区 Markdown 文件¶
Memory 全部落盘到 workspace 目录下的固定路径文件：
| 文件 | 记录什么 | 谁来写 |
|---|---|---|
MEMORY.md |
长期知识：项目约定、关键决策、重要 Context | Agent 主动写入 |
memory/YYYY-MM-DD.md |
日笔记：当天对话中提取的 Memory | Agent 按日期自动分片 |
SOUL.md |
人格定义：角色、语气、价值观 | 用户/管理员编辑 |
AGENTS.md |
行为规则：Session Startup、Red Lines | 用户/管理员编辑 |
DREAMS.md |
梦境/反思记录 | Agent 自动生成 |
设计优势：Memory 天然持久化（无需数据库）、用户可直接编辑、Git 版本控制天然适用、透明可审计。
与 Claude Code 的对比¶
Claude Code 把所有持久状态塞进 CLAUDE.md 的五层体系（Managed → User → Project → Local → AutoMem），统一但复杂。OpenClaw 将人格（SOUL）、行为（AGENTS）、知识（MEMORY）拆成独立文件——职责更清晰，但缺乏层级覆盖的灵活性。
二、怎么写入：Memory Flush 安全网¶
OpenClaw Memory 写入的最关键机制是 Memory Flush——在压缩发生前，自动将当前对话中的重要信息写入磁盘，防止压缩摘要丢失细节。
触发决策链¶
graph LR
A["shouldRunMemoryFlush()"] -->|"门控检查"| B{"通过？"}
B -->|"否"| C["跳过"]
B -->|"是"| D["resolveMemoryFlushPlan()"]
D --> E["写入 MEMORY.md\nmemory/*.md"]
E --> F["更新 SessionEntry\nmemoryFlushCompactionCount++"]门控条件：
- 当前会话是否有足够的新内容
- 距离上次 flush 是否经过了足够多的交互轮次
memoryFlushCompactionCount是否低于当前compactionCount
这种「先保存再压缩」的策略是 OpenClaw 防御性编程哲学的典型体现——即使压缩生成的摘要质量不高，关键信息也已经安全写入磁盘。
三、怎么召回：被动向量检索¶
Memory 检索通过可插拔的 memory 插件实现（同一时刻只能有一个 memory 插件 active）：
| 工具 | 模式 | 实现 |
|---|---|---|
memory_search |
向量检索 / 混合检索 | LanceDB 或 sqlite-vec |
memory_get |
精确获取 | 按路径直接读取Memory 文件 |
被动检索 vs 主动预取¶
与 Claude Code（每 turn 自动用 Sonnet 预取）不同，OpenClaw 的Memory 检索是被动的——需要 LLM 主动决定调用 memory_search：
| 维度 | Claude Code（主动预取） | OpenClaw（被动检索） |
|---|---|---|
| 触发 | 每 turn 自动 | LLM 主动调用工具 |
| 召回率 | 100%（每 turn 必触发） | 不确定（依赖模型判断） |
| 成本 | 高（每 turn 一次 Sonnet） | 低（按需检索） |
| 延迟 | 并行预取，不阻塞 | 串行工具调用，增加 1 turn |
| 精度 | 高（LLM 理解语义） | 中（依赖 Embedding 质量） |
四、Memory 与 System Prompt 的集成¶
Memory 文件在系统提示构建阶段被加载（loadWorkspaceBootstrapFiles）——MEMORY.md、SOUL.md 等内容直接注入 Bootstrap 段落。
压缩后通过 readPostCompactionContext 重新注入 AGENTS.md 中的 Session Startup 和 Red Lines——确保 Agent 的核心行为规则不会因压缩而丢失。
关键文件索引¶
| 文件 | 职责 |
|---|---|
src/agents/workspace.ts |
Bootstrap 文件加载（MEMORY/SOUL/AGENTS.md） |
src/agents/pi-embedded-runner/attempt.ts |
压缩触发 + Memory Flush |
docs/concepts/memory.md |
Memory 概念文档 |
docs/reference/memory-config.md |
Memory 配置参考 |