OpenClaw记忆机制揭秘(1)

1. 不同文件记忆

OpenClaw 采用分层文件结构管理不同类型的记忆数据，各文件承担明确的职责边界。

1.1 记忆文件分类

1.2 记忆内容划分原则

• 长期记忆（MEMORY.md）：存储具有持续参考价值的信息，如用户偏好、重要决策、项目状态。

  内容应经过筛选和提炼，避免冗余。

• 日常笔记（memory/YYYY-MM-DD.md）：记录原始对话内容和临时上下文，按日期归档。

  适用于短期回溯和长期记忆的素材来源。

• 配置类记忆（TOOLS.md）：存储与环境部署相关的具体参数，如设备标识、服务地址、认证信息等。
• 引导类文件：
• BOOTSTRAP.md：一次性引导文件，仅在全新工作区创建，通过setupCompletedAt标记管理生命周期，完成后删除。
• HEARTBEAT.md：心跳指令文件，存储定期检查任务列表；在心跳运行模式下为唯一保留的引导文件。

2. 记忆加载

2.1 自动注入机制

会话启动时，OpenClaw 运行时自动将以下文件内容注入 System Prompt：

SOUL.md        → 人格原则 

IDENTITY.md      → 身份定义 

USER.md          → 用户信息 

AGENTS.md        → 工作区规则 

MEMORY.md        → 长期记忆（仅主会话） 

注入特性：

• 无需显式调用读取工具。
• 内容占用上下文 Token 配额。
• MEMORY.md在群聊或子代理会话中不注入（安全隔离）。

2.2 主动读取机制

日常笔记文件（memory/YYYY-MM-DD.md）不自动注入，需通过以下方式访问：

• 直接读取：使用read工具指定文件路径。
• 语义搜索：使用memory_search工具进行内容检索。

适用场景：

• 回顾特定日期的对话记录。
• 整理长期记忆时参考原始素材。
• 追溯历史决策的上下文依据。

2.3 上下文刷新策略

当会话上下文接近 Token 上限时，系统按以下优先级进行截断：

1. 1保留最近的消息历史。
2. 2保留自动注入的核心文件（SOUL.md、IDENTITY.md等）。
3. 3截断较早的对话历史片段。

3. 记忆写入

3.1 写入工具

记忆写入通过标准文件操作工具完成：

• 工具：创建新文件或覆盖现有文件。
• 工具：对现有文件进行精确文本替换。

3.2 ReAct 写入流程

Agent 在 ReAct（Reasoning + Acting）模式下执行记忆写入的典型流程：

Step 1: Thought（思考）   识别用户意图中包含记忆需求（如"记住这个偏好"）   评估信息类型，确定目标文件  

Step 2: Action（行动）   调用 write 或 edit 工具   传入目标路径和内容参数 

Step 3: Observation（观察）   接收工具执行结果   验证写入是否成功  

Step 4: Final Answer（响应）   向用户确认记忆已保存   必要时说明存储位置 

3.3 写入位置决策

3.4 写入示例

场景：用户设定代码语言偏好

用户输入："以后写代码默认用 Python"  Agent 决策流程:   

1. 识别为长期偏好设置   

2. 确定写入 MEMORY.md 的"用户偏好"章节   

3. 调用 edit 工具追加记录   

4. 向用户确认保存完成 

4. 向量索引与 memory_search

OpenClaw 提供向量索引和memory_search工具支持记忆的语义检索：

• 向量索引：使用 SQLite 数据库（~/.openclaw/memory/*.sqlite）存储记忆片段的向量嵌入，支持语义相似度搜索。
• memory_search 工具：对MEMORY.md和memory/*.md进行语义搜索，返回与查询意图最相关的片段及相似度评分。

索引在 Gateway 启动时重建或增量更新，搜索操作基于最新可用索引版本。

5. 自动触发记忆写入

OpenClaw 的日常记忆（memory/YYYY-MM-DD.md文件）在特定条件下会自动触发写入，无需 Agent 显式调用写入工具。

5.1 触发条件

当会话的 Token 使用量接近上下文窗口限制时，OpenClaw 触发预压缩记忆刷新机制。

5.2 触发流程

满足条件时，系统执行以下操作：

1. 1运行静默智能体会话：启动一个单独的智能体回合。
2. 2发送记忆提醒：向模型发送提示，要求将持久记忆写入memory/YYYY-MM-DD.md。
3. 3静默执行：该回合默认包含NO_REPLY标记。