OpenClaw 内存解释：架构、设置及其忘记原因

完整的 OpenClaw 内存架构（3 层解释）

OpenClaw 内存跨三个不同的层运行，每个层都有不同的持久性特征和故障模式。

完整的内存生命周期：

Write → Embed/Index → Search → Compact → Recover
  ↓          ↓           ↓         ↓         ↓
.md file   sqlite-vec  semantic  summary   MEMORY.md
created    indexes it  query     replaces  re-read at
           on save     returns   context   session start
                       chunks    window

该链中的每个阶段都可能独立失败。大多数遗忘问题都可以追溯到一个破碎的阶段。

第 1 层 — 活动上下文窗口

这是模型的工作记忆：当前加载到活动对话上下文窗口中的所有内容。它包括您的系统提示、对话历史记录以及搜索工具检索到的任何内存块。

里面装的是什么：

• 系统提示符（通常很大）
• 检索记忆摘录
• 工具调用历史记录
• 话锋一转

实际限制：假设在系统提示和内存开销之后，您有大约 60-70% 的模型广告上下文窗口可用于实际对话。

第 2 层 — 每日笔记（滚动两天窗口）

每日笔记是以 YYYY-MM-DD 格式命名的仅附加 Markdown 文件，存储在 memory/ 目录中。 OpenClaw 负载 今天和昨天的 在每个会话开始时自动生成文件。

• 有关今天工作、做出的决定和活动任务的事实附加在此处
• 它们不应该被编辑——将它们视为日志
• 两天后，它们超出了自动加载窗口，只能通过语义搜索进行搜索

第 3 层 — 持久内存（MEMORY.md 和 memory-wiki）

跨会话应保留的长期事实（您的姓名、项目上下文、编码偏好、架构决策）属于 MEMORY.md 或结构化 memory-wiki 插件库。

压缩问题——为什么你的指令在任务中消失

压缩是 OpenClaw 中记录最多的故障模式。大多数文章都涉及会话后遗忘。几乎没有地址 长时间运行的自主工作流程中的中期任务压缩 — 当代理执行多步骤任务时，压缩会在 12 步中的第 7 步静默触发，并且第 1 步中的行为指令消失。

压缩的作用是什么：

1. 检测上下文窗口接近容量
2. 将当前对话总结为一个压缩块
3. 用摘要替换原始上下文
4. 继续执行

当它触发时： 默认 memory-core 插件中没有可配置的阈值。它根据令牌计数而不是任务阶段触发。在 2 小时的自主运行中，您预计会有 3-5 个压实周期。

如何构建抗压缩文件架构

将行为指令固定在 MEMORY.md 中，而不是对话中。 任何必须在多个压缩周期中生存的内容都需要保存在持久文件中，该文件在每次压缩后都会重新读取。

推荐的固定模式：

## Agent Behavioral Rules (always active)
- Never overwrite files without showing a diff first
- Write tests before implementation (TDD mode: on)
- Use TypeScript strict mode in all new files

## Project Context
- Stack: Node.js 22, Fastify, PostgreSQL 16
- Repo root: /home/user/project
- Active sprint goal: migrate auth to Clerk

压缩后的命名约定：

• 使用 ## [PINNED] 为关键部分添加前缀 - 摘要器将大写标头视为高优先级
• 尽可能将每个固定事实保留在一行中 - 总结密集的段落，单行事实往往会逐字保留
• 在 MEMORY.md 和今天的每日笔记中重复 3-5 个最关键的行为规则 - 冗余是你的压缩对冲

10 分钟内从零到内存设置（完整文件支架）

这是其他地方不存在的设置指南。复制这个结构，填写你的上下文，然后你就可以运行了。

目录树：

memory/
├── MEMORY.md
├── 2026-04-27.md          ← today's daily note (create manually)
└── wiki/                  ← only if using memory-wiki plugin
    ├── index.md
    ├── project-context.md
    └── decisions.md

启动器MEMORY.md：

# Persistent Memory

## Identity & Preferences
- Name: [your name]
- Role: [your role]
- Preferred response style: concise, no preamble

## Project: [Project Name]
- Stack: [your stack]
- Key constraints: [e.g., no external APIs, TypeScript only]
- Current focus: [active task or sprint goal]

## Behavioral Rules
- [Rule 1]
- [Rule 2]

## Decisions Made
- [YYYY-MM-DD] Decided to use X because Y

入门每日笔记 (2026-04-27.md)：

# 2026-04-27

## Session Goals
- [ ] Task 1
- [ ] Task 2

## Notes

插件槽配置（2026语法）：

{
  "plugins": {
    "slots": {
      "memory": "memory-core"
    }
  }
}

要完全禁用内存：

{
  "plugins": {
    "slots": {
      "memory": false
    }
  }
}

验证步骤：

1. 运行一次会话并要求客服人员回忆您在上一次会话中告诉过的内容
2. 检查 memory/YYYY-MM-DD.md 是否已写入（它应该有新内容）
3. 直接问经纪人：“你对我了解多少？” — 它应该从 MEMORY.md 中提取

为生产知识库配置内存维基

通过交换插件插槽来启用它：

{
  "plugins": {
    "slots": {
      "memory": "memory-wiki"
    }
  }
}

memory-wiki 在 memory/wiki/ 下生成一个结构化保管库。每个主题都有自己的页面。该插件编译一个 digest.md ，它聚合了高可信度、无矛盾的事实，以便代理在会话开始时加载。

生产代理的实用保险库结构：

memory/wiki/
├── index.md              ← vault table of contents
├── digest.md             ← auto-generated; agent reads this
├── project-context.md    ← stack, goals, constraints
├── decisions.md          ← architectural decisions log
├── team.md               ← stakeholders, contacts
└── domain-knowledge.md   ← business rules, glossary

语义搜索和嵌入——SQLite、sqlite-vec 和 JS Fallback

OpenClaw 使用以下方式索引您的内存文件 带有 sqlite-vec 扩展的 SQLite 用于向量相似性搜索。当您或代理发出内存搜索时，它会嵌入查询并检索语义上最相关的块。

验证您的矢量存储是否正常：

# Check that the memory index exists
ls memory/.index/

# Reset a corrupted index (safe to run — it rebuilds from .md files)
rm -rf memory/.index/ && OpenClaw reindex

如果 sqlite-vec 不可用（在 ARM Linux 和某些 Windows 配置上常见），OpenClaw 会回退到纯 JS 向量扩展。显式强制回退：

{
  "memory": {
    "vectorBackend": "js"
  }
}

特定于段的内存策略

独立开发人员 - 最小的开销，最大的召回率

推荐设置：memory-core 插件、MEMORY.md + 仅每日笔记，无 wiki 库。

• 将 MEMORY.md 保持在 200 行以下 - 较长的文件会减慢会话启动速度
• 积极地添加日常笔记；不要试图保持它们干净
• 每周审查和修剪 MEMORY.md — 过时的事实会降低搜索质量

多代理管道——跨代理共享内存

当多个代理读取和写入同一 memory/ 目录时，您需要明确的所有权规则。

• 一个代理拥有对每个文件的写入 — 并发写入同一个 .md 文件会产生冲突
• 每个代理使用子目录：memory/agent-a/、memory/agent-b/，以及共享的 memory/shared/MEMORY.md
• 使用内存维基作为共享库 - 它的摘要编译比原始文件更好地处理多个编写者之间的新鲜度

长时间运行的自主任务——存活执行时间

对于运行以小时为单位的任务的代理：

• 在检查点强制写入内存 — 在每个主要任务阶段之后，指示代理将其当前状态附加到今天的每日笔记中
• 预载抗压实环境 — 在运行开始之前将完整的任务规范放入 MEMORY.md 中，而不仅仅是在初始消息中
• 设置显式连续标记 在日常笔记中：<!-- RESUME POINT: completed steps 1-4, next: step 5 -->，以便代理可以在压实周期后自我定向

OpenClaw 内存故障排除 — 在 2 分钟内诊断任何遗忘问题

按顺序完成这些步骤：

常见问题解答

最终结论——实际有效的内存设置

为大多数用户推荐的基准： memory-core 插件，在第一次会话之前创建的 memory/ 目录，MEMORY.md 在明确标记的固定部分中包含行为规则，在每个会话中附加每日注释。

您的行动清单：

• 在项目根目录中创建 memory/ 目录
• 复制上面的起始 MEMORY.md 模板并填写您的上下文
• 验证 plugins.slots.memory 设置为 "memory-core" （或您选择的插件）
• 在 MEMORY.md 中的 ## [PINNED] 下添加 3–5 条最关键的行为规则
• 第一次会议后，确认已写下注明日期的每日笔记
• 如果语义搜索感觉不太好，请运行 OpenClaw reindex 来重建向量索引

一旦你理解了它，这个架构就是合理的。大多数遗忘问题会在遵循此清单后 10 分钟内得到解决。