07. 记忆系统完全指南

课程信息

• 作者：老金

• GitHub：https://github.com/KimYx0207

• 公众号：老金带你玩AI

• X（Twitter）：老金带你玩AI

• 个人博客：https://aiking.dev

• 难度等级：🟡 进阶

• 阅读时间：25 分钟

• 前置知识：已完成快速开始（03-快速开始指南）

本篇你将学会： 理解 AI 的记忆机制、配置记忆存储、管理和优化 AI 的记忆

小白速通： 只看前 2 节（"为什么 AI 需要记忆"、"记忆架构"），了解概念就够了。OpenClaw 的记忆系统开箱即用，不需要额外配置

2026-09-13 当前基线（v2026.9.4）：v2026.9.3 起记忆检索和冷会话更新的开销降下来了，热提示缓存也会保留；v2026.9.2 起回复能在 Gateway 重启后恢复（活动中、排队中和被委派的回复都算），续跑指令在压缩和重试之后也会保留。

版本口径（核查日：2026-09-13）：v2026.7.1-1 修复了 Memory Core 启动冲突导致的 fatal restart loop（派生的 legacy-index 与 cache-sidecar 冲突现在可以恢复，不再把 Gateway 困在重启循环里；向量库的结构性损坏仍按可重试处理）。更强的状态安全是后面才到的：v2026.8.1 把已证实损坏的 quarantine 决定单独存一份（被隔离的库自身损坏也不会擦掉隔离记录），并提供 openclaw backup sqlite 快照的创建/列出/校验/恢复，同时在遇到比当前版本更新的数据库 schema 时拒绝竞争性改写而不是反复重启。如果你之前因为记忆相关报错而停用，升级后建议先用 openclaw doctor 验证一次再决定是否重新启用。具体行为以本机版本为准。

为什么 AI 需要记忆？

我在 OpenClaw 记忆这篇里保留很多边界提醒，是因为我知道记忆一旦写错，后面所有自动化都会被带偏。

你跟朋友聊天，不需要每次都自我介绍。因为朋友记得你是谁、你喜欢什么、上次聊了什么。

但 AI 不一样。大语言模型本质上是"无状态"的 — 每次对话结束，它就把你忘得一干二净。下次你再说"继续上次的方案"，它会一脸茫然地问你"什么方案？"

这就是记忆系统要解决的核心问题：让 AI 像一个真正的助手一样，记住你是谁、你在做什么、你喜欢什么。

没有记忆的 AI 助手：

你：帮我改一下昨天那个 React 组件
AI：请问你指的是哪个组件？能提供更多上下文吗？
你：……我昨天跟你聊了两个小时啊
AI：抱歉，我没有之前对话的记录。

有记忆的 AI 助手：

你：帮我改一下昨天那个 React 组件
AI：你说的是 UserProfile 组件吧？昨天你提到想把头像上传功能
    从 base64 改成 presigned URL。我来改一下。

差距一目了然。

记忆系统的三大价值

价值

说明

举例

连续性

跨会话保持上下文

记住你正在做的项目、进度、决策

个性化

了解你的偏好和习惯

知道你喜欢 TypeScript、不用分号、偏好函数式风格

效率

减少重复沟通

不用每次都解释你的技术栈、团队结构、工作流程

OpenClaw 记忆架构

OpenClaw 的记忆系统设计哲学非常务实：Markdown 文件 + sqlite-vec（轻量级的向量数据库，用于语义搜索） 向量索引，兼顾透明可控和智能检索。

AI 的记忆源头是写在磁盘上的 Markdown 文件和会话日志。你可以直接用文本编辑器查看、修改、删除 AI 的记忆，完全透明可控。同时，系统使用 sqlite-vec 做向量存储，支持语义搜索、混合搜索（hybrid search）、时间衰减（temporal decay）、最大边际相关性（MMR）和查询扩展（query expansion）等高级检索能力。

三层记忆架构

OpenClaw 把记忆分成三层，各司其职：

┌─────────────────────────────────────────────────┐
│                  会话记忆 (Session Memory)         │
│  存在于当前对话的上下文窗口中                        │
│  当前上下文受预算限制；会话历史另存运行时数据库          │
│  容量：受模型上下文窗口限制                          │
└──────────────────────┬──────────────────────────┘
                       │ compaction（上下文压缩，当对话太长时自动总结之前的内容） 时自动刷新
                       ▼
┌─────────────────────────────────────────────────┐
│                  短期记忆 (Daily Logs)             │
│  memory/YYYY-MM-DD.md                            │
│  每天一个文件，记录当天的笔记和上下文                 │
│  默认加载今天 + 昨天的日志                          │
│  容量：无限制（每天一个文件）                        │
└──────────────────────┬──────────────────────────┘
                       │ 手动或自动整理
                       ▼
┌─────────────────────────────────────────────────┐
│                  长期记忆 (MEMORY.md)              │
│  精选的持久信息                                    │
│  偏好、决策、重要事实、用户画像                      │
│  每次主会话启动时加载                               │
│  容量：建议控制在 2000 行以内                       │
└─────────────────────────────────────────────────┘

记忆源

OpenClaw 的记忆来自三类文件：

~/.openclaw/workspace/
├── MEMORY.md              # 长期记忆（精选的重要信息）
├── USER.md                # 用户画像（姓名、偏好、习惯）
├── SOUL.md                # Agent 人格定义
├── DREAMS.md              # Dreaming 系统产出（v2026.4.5 新增）
├── memory/
│   ├── 2026-02-25.md      # 今天的日志
│   ├── 2026-02-24.md      # 昨天的日志
│   ├── 2026-02-23.md      # 前天的日志
│   └── ...                # 更早的日志

# 活跃会话状态另存于 <agentDir>/openclaw-agent.sqlite；
# 保留的转录产物在 ~/.openclaw/agents/<agent-id>/sessions/，不是 workspace/sessions。

记忆源汇总：

• MEMORY.md — 手动维护的长期记忆

• workspace/memory/*.md — 每日日志

• DREAMS.md — Dreaming 系统自动整理的记忆产出（v2026.4.5 新增）

• <agentDir>/openclaw-agent.sqlite 与保留的转录产物 — 会话状态与历史；是否用于检索还取决于检索配置

各层记忆详解

会话记忆 (Session Memory)

会话记忆就是当前对话的上下文。你跟 AI 说的每一句话、AI 的每一个回复，都在会话记忆里。

特点：

• 速度最快，AI 可以直接引用

• 容量有限，受模型上下文窗口约束（通常 128K-200K tokens）

• 开新会话不自动继承全部旧上下文；历史仍可保存在 Agent 的 SQLite 状态与转录产物中

• 对话太长时会触发 compaction（压缩），旧消息会被摘要

你：我的项目用 Next.js 14
AI：好的，Next.js 14。（这句话现在在会话记忆里）

... 聊了 200 条消息 ...

AI：（compaction 触发，早期消息被压缩成摘要）

短期记忆 (Daily Logs)

每天一个 Markdown 文件，记录当天的重要信息。

<!-- memory/2026-02-25.md -->
# 2026-02-25

## 上午
- 讨论了新的认证方案，决定用 NextAuth.js v5
- 用户提到下周三有产品评审会

## 下午
- 修复了 UserProfile 组件的头像上传 bug
- 用户要求把所有 API 响应格式统一为 { data, error } 结构

加载策略：

• 每次新会话启动时，自动加载今天和昨天的日志

• 裸 /new 或 /reset 会读取今天和昨天的日期笔记及相应带 slug 的文件；不是每轮把所有日志注入提示

长期记忆 (MEMORY.md)

精选的、持久的重要信息。这是 AI 的"核心记忆"。

<!-- MEMORY.md -->
# 长期记忆

## 用户偏好
- 编程语言：TypeScript，不用分号
- 框架：Next.js 14 + React 18
- 代码风格：函数式优先，避免 class
- 编辑器：VS Code + Vim 键位

## 项目信息
- 当前项目：电商平台重构
- 部署环境：Vercel (前端) + Railway (后端)
- 数据库：PostgreSQL + Prisma ORM

## 重要决策
- 2026-02-20：决定从 REST 迁移到 tRPC
- 2026-02-22：选择 Stripe 作为支付方案

记忆存储与检索

OpenClaw 的记忆系统使用 sqlite-vec 作为向量存储后端，结合 Markdown 文件实现透明可控的记忆管理。

向量存储：sqlite-vec

⏭️ 小白可跳过 — 这部分是技术深入分析，记忆系统默认配置已经够用

sqlite-vec 是 OpenClaw 的默认向量存储方案。它基于 SQLite 扩展，零配置、单文件，同时支持向量语义搜索。

sqlite-vec 是可选的向量查询加速。通常使用内置默认值；扩展加载失败时可退回内存余弦计算。它不替代 embedding provider：没有可用 embedding 时，默认路径可以只做关键词搜索。实际状态分别查看 vector store 与 embeddings。

优点：

• 零配置，开箱即用（enabled 默认为 true）

• 单文件数据库，不需要安装额外服务

• 支持向量语义搜索和 BM25 混合搜索

• 记忆源文件（Markdown）仍然可以直接用编辑器查看和修改

• 如果 sqlite-vec 扩展加载失败，自动回退到 JS 内存中的余弦相似度计算

Embedding 提供商

⏭️ 小白可跳过 — 这部分是技术深入分析，记忆系统默认配置已经够用

sqlite-vec 需要配合 embedding（把文本转换成数字向量的技术，让 AI 能理解语义相似性） 模型将文本转为向量。OpenClaw 支持多种 embedding 提供商：

提供商

说明

OpenAI

text-embedding-3-small 等

Gemini

Google 的 embedding 模型

Mistral

Mistral 的 embedding 模型

Voyage

Voyage AI 的 embedding 模型

{
  memory: { search: { provider: "openai", model: "text-embedding-3-small" } },
}

当前共享配置使用 memory.search。默认选择 OpenAI embedding；希望本地推理时明确选择 local、ollama 或 lmstudio，并配置所需服务。未配置 provider 或 local 不可用时可能使用关键词检索；显式指定其他 provider 却认证或连接失败，会报告不可用，不能依赖它静默换到另一家云端。

高级检索能力

⏭️ 小白可跳过 — 这部分是技术深入分析，记忆系统默认配置已经够用

OpenClaw 的记忆检索不是简单的关键词匹配，而是一套完整的智能检索系统：

能力

说明

Hybrid Search（混合搜索）

同时使用关键词匹配和向量语义搜索，综合排序

Temporal Decay（时间衰减）

越新的记忆权重越高，旧记忆逐渐淡化

MMR（最大边际相关性）

搜索结果去重，避免返回高度相似的内容

Query Expansion（查询扩展）

自动扩展搜索词，提高召回率

关键词检索可直接使用；语义与混合检索需要可用的 embedding。时间衰减、MMR 等排序选项应按实际配置核对，不能把支持某种能力理解成每项都默认开启。

v2026.4.24 更新： 混合搜索现在在结果中暴露原始的 vectorScore（向量语义分数）和 textScore（关键词匹配分数），方便调试搜索质量。会话记录搜索也新增了可见性和 Agent 间策略控制。

记忆配置详解

记忆系统的行为可以通过 ~/.openclaw/openclaw.json（JSON5 格式）精细控制。

基础配置

记忆系统默认启用，不需要额外配置。OpenClaw 通过 memory-core 插件提供记忆功能（默认加载）。

如果你想关闭记忆系统：

如果要彻底关闭记忆插件，沿用前文 plugins.slots.memory = "none" 的配置即可；这里不重复贴完整 JSON，避免读者误以为这是另一种配置格式。

记忆文件存储在 workspace 目录下（默认 ~/.openclaw/workspace），可以通过 agents.defaults.workspace 修改 workspace 路径。记忆系统默认加载今天和昨天的日志（memory/YYYY-MM-DD.md）以及长期记忆（MEMORY.md，仅在私聊会话中加载）。

Compaction 与记忆刷新

这是 OpenClaw 记忆系统最聪明的设计之一。当对话越来越长，上下文窗口快要满的时候，OpenClaw 会触发 compaction（压缩）。在压缩之前，它会自动提醒 AI 把重要信息存到记忆文件里。

// ~/.openclaw/openclaw.json
{
  "agents": {
    "defaults": {
      "compaction": {
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000
        }
      }
    }
  }
}

工作流程：上下文使用率达到阈值 → 触发 memoryFlush（隐藏的 Agent 轮次）→ AI 自动把重要信息写入日志 → 执行 compaction 压缩旧消息 → 对话继续。

你也可以在对话中手动触发压缩，使用聊天命令 /compact。

字段

说明

memoryFlush.enabled

启用压缩前的记忆刷新轮次

softThresholdTokens

距离压缩还有多少 tokens 时触发记忆刷新

记忆加载行为

每次会话启动时，OpenClaw 自动加载以下记忆：

• MEMORY.md — 长期记忆（仅在私聊会话中加载，群聊中不加载）

• memory/YYYY-MM-DD.md — 今天和昨天的日志

这个行为是内置的，不需要额外配置。如果你想让记忆搜索覆盖更多文件（比如 workspace 外的 Markdown），可以通过 extraPaths 扩展搜索范围：

{
  "memory": {
    "search": {
      "extraPaths": [
        "../team-docs",
        "/srv/shared-notes/overview.md"
      ]
    }
  }
}

路径可以是绝对路径或相对于 workspace 的路径。目录会被递归扫描，但只索引 Markdown 文件（.md）。

为什么要注意记忆大小？因为记忆也占上下文窗口。日志写得太详细时，会挤占正常对话的空间。建议 MEMORY.md 控制在 3000 tokens 以内。

按 Agent 配置记忆

不同的 Agent 可以有不同的记忆行为。通过给每个 Agent 配置独立的 workspace，实现记忆隔离：

// ~/.openclaw/openclaw.json
{
  "agents": {
    "entries": {
      "coding": {
        "default": true,
        "workspace": "~/.openclaw/workspace-coding"
      },
      "social": {
        "workspace": "~/.openclaw/workspace-social"
      }
    }
  }
}

每个 Agent 的 workspace 下有独立的 MEMORY.md 和 memory/ 目录。如果某个 Agent 完全不需要记忆功能，可以在它的 workspace 里不放任何记忆文件即可。

对话上下文管理

上下文窗口是 AI 的"工作记忆"，想用好记忆系统，先得理解它怎么工作。

什么是上下文窗口？

上下文窗口就是模型一次能"看到"的所有文本。包括：

┌─────────────────────────────────────────┐
│ 系统提示词 (System Prompt)               │  ← 固定占用
│ - Agent 人格 (SOUL.md)                  │
│ - 技能指令                               │
│ - 工具定义                               │
├─────────────────────────────────────────┤
│ 记忆注入                                 │  ← 启动时加载
│ - MEMORY.md                             │
│ - USER.md                               │
│ - 最近几天的日志                          │
├─────────────────────────────────────────┤
│ 对话历史                                 │  ← 动态增长
│ - 用户消息                               │
│ - AI 回复                               │
│ - 工具调用结果                            │
├─────────────────────────────────────────┤
│ 剩余空间                                 │  ← 给 AI 生成回复用
└─────────────────────────────────────────┘

常见模型的上下文窗口差异很大，而且会随 provider 更新。写课程和配置前，先查当前 OpenClaw models 输出和 provider 文档，不要把旧数字当永久事实。

滑动窗口策略

当对话越来越长，上下文窗口快满了怎么办？OpenClaw 使用滑动窗口策略：

正常对话：  [系统提示 | 记忆 | 消息1 | 消息2 | ... | 消息N]
接近上限：  [系统提示 | 记忆 | [摘要:消息1-50] | 消息51 | ... | 消息N]
继续对话：  [系统提示 | 记忆 | [摘要:消息1-50] | 消息51 | ... | 消息N+M]

compaction 的过程：检测到上下文使用率超过阈值 → 触发 memoryFlush，AI 保存重要信息到记忆文件 → 将早期消息压缩成摘要 → 释放上下文空间，继续对话。

上下文预算管理

OpenClaw 通过 compaction 机制自动管理上下文空间。keepRecentTokens 设置压缩时近期对话的保留预算；它不是触发压缩的阈值。下面的 20000 是官方默认预算的示例：

// ~/.openclaw/openclaw.json
{
  "agents": {
    "defaults": {
      "compaction": {
        "keepRecentTokens": 20000
      }
    }
  }
}

keepRecentTokens 越大，压缩时尝试保留的近期对话越多。自动压缩还要为系统提示、工具定义、待处理输入和输出留空间，实际可能保留更少；工具调用与结果也会成对保留。

💡 实用建议： 如果记忆文件太大导致上下文空间不足，最有效的做法是精简 MEMORY.md 的内容（建议控制在 3000 tokens 以内），而不是调整配置参数。

用户画像和偏好记忆

OpenClaw 有一个专门的文件 USER.md 来存储用户画像。这跟 MEMORY.md 不同 — MEMORY.md 存的是各种杂项记忆，USER.md 专门描述"你是谁"。

USER.md 结构

<!-- ~/.openclaw/workspace/USER.md -->
# 用户画像

## 基本信息
- 姓名：老金 | 时区：Asia/Shanghai | 语言：中文为主

## 技术偏好
- 主力语言：TypeScript（不用分号，单引号，2 空格缩进）
- 前端：React + Next.js | 后端：Node.js + Fastify
- 数据库：PostgreSQL | 部署：Docker + Railway

## 沟通偏好
- 喜欢简洁直接的回答，代码示例比文字解释更有用
- 遇到问题先给方案，再解释原因

## 日程习惯
- 工作时间：9:00-18:00
- 每周一 10:00 团队周会 | 每周五 15:00 代码评审

自动学习用户偏好

OpenClaw 没有专门的"自动学习"配置开关。用户偏好的记录依赖于 AI 模型自身的判断 — 当你在对话中表达偏好时，AI 会主动将其写入 USER.md 或 MEMORY.md。

你可以通过 SOUL.md（Agent 人格文件）来引导 AI 更主动地记录偏好：

<!-- ~/.openclaw/workspace/SOUL.md 中添加 -->
## 记忆习惯
- 当用户表达偏好或习惯时，主动写入 USER.md
- 当用户做出重要决策时，记录到 MEMORY.md
- 每次对话结束前，检查是否有值得记录的信息

这种方式比配置文件更灵活 — 你可以用自然语言精确描述 AI 应该记住什么、怎么记住。

主动让 AI 记住

直接告诉 AI 你想让它记住什么：

记住：我的 GitHub 用户名是 laojin-dev
记住：项目部署在 Hetzner 的 VPS 上
记住：我不喜欢在代码里用分号
记住：跟我说话不用太客气，直接说重点

AI 会根据内容类型，自动决定写入 MEMORY.md 还是 USER.md：

• 个人偏好、习惯 → USER.md

• 项目信息、决策、事实 → MEMORY.md

• 临时笔记、当天事项 → memory/YYYY-MM-DD.md

记忆工具

AI 有专门的工具来操作记忆：

memory_search — 语义搜索

从所有记忆文件中搜索相关内容。

用户：我之前说过用什么支付方案来着？
AI：（调用 memory_search("支付方案")）
    → 找到 MEMORY.md 中的记录：2026-02-22 决定用 Stripe
AI：你在 2 月 22 号决定用 Stripe 作为支付方案。

搜索范围：

• MEMORY.md — 长期记忆

• USER.md — 用户画像

• memory/*.md — 所有日志文件

memory_get — 精确读取

读取某个记忆文件的特定内容。

用户：看看我昨天的笔记
AI：（调用 memory_get("memory/2026-02-24.md")）
    → 返回昨天日志的完整内容

记忆写入

AI 通过普通的文件写入工具来更新记忆文件。没有专门的"记忆写入"工具 — 这是故意的设计，保持简单。

用户：记住，我们决定用 Stripe
AI：（调用 write 或 edit，更新 MEMORY.md）
    好的，已记录到长期记忆中。

知识库集成 (RAG)

当你需要 AI 记住大量结构化知识（比如公司文档、产品手册、代码库），普通的记忆文件就不够用了。这时候需要 RAG（Retrieval-Augmented Generation，检索增强生成）。

什么是 RAG？

简单说：AI 回答问题之前，先从知识库里搜索相关内容，然后带着这些内容去回答。

传统方式：
用户提问 → AI 凭记忆回答（可能瞎编）

RAG 方式：
用户提问 → 搜索知识库 → 找到相关文档 → AI 基于文档回答（有据可查）

OpenClaw 的 RAG 实现

OpenClaw 的记忆搜索本身就具备 RAG 能力，通过 memory.search 配置索引 workspace 下的 Markdown 文件；语义检索还需要可用的 embedding。索引 workspace 之外的文件，可以通过 memory.search.extraPaths 扩展：

{
  "memory": {
    "search": {
      "extraPaths": [
        "~/Documents/company-wiki",
        "~/projects/myapp/README.md"
      ]
    }
  }
}

v2026.9.4 已移除 QMD memory backend。新配置使用内置 SQLite 检索，不要再安装 QMD 或设置 memory.backend: "qmd"。旧配置先备份，再按 doctor 的迁移提示处理；官方迁移会把旧 QMD collection 路径保留为 memory.search.extraPaths，重新构建的是派生索引。

索引外部文档可以这样写：

{
  memory: {
    search: { extraPaths: [{ path: "~/notes", pattern: "**/*.md" }] },
  },
}

目录会递归扫描；MEMORY.md、现有 USER.md 和 memory/ 是默认记忆来源。外部共享目录宜只读，索引范围不等于文件访问授权。需要语义检索时另行配置 embedding provider。

知识库与记忆管理命令

记忆索引和知识库都通过 openclaw memory 子命令管理：

# 记忆索引管理
openclaw memory status             # 查看记忆索引状态
openclaw memory index              # 重建记忆索引
openclaw memory search "部署"       # 搜索记忆（支持语义搜索）

记忆 vs 知识库

维度

记忆系统

知识库 (RAG)

内容来源

对话中产生

预先准备的文档

更新方式

AI 自动写入

手动索引或监控

搜索方式

混合搜索（关键词 + 语义）

语义向量搜索

适合内容

偏好、决策、笔记

文档、手册、代码

数据量

小（几十个文件）

大（成百上千个文件）

记忆的增删改查操作

通过 CLI 操作

# 查看记忆索引状态
openclaw memory status

# 重建记忆索引（当记忆文件有变动时）
openclaw memory index

# 搜索记忆（支持语义搜索）
openclaw memory search "React 组件"

记忆文件本身是 Markdown，可以直接用编辑器查看和修改：

code ~/.openclaw/workspace/MEMORY.md                    # VS Code
vim ~/.openclaw/workspace/memory/2026-02-25.md          # Vim

修改后运行 openclaw memory index 重建索引，下次会话启动时 AI 就能看到更新的内容。

通过对话操作

直接跟 AI 说就行：

你：记住，我们的 API 基础 URL 是 https://api.example.com/v2    → 写入
你：我之前说过 API 地址是什么？                                  → 查询
你：API 地址改了，新地址是 https://api.example.com/v3            → 更新
你：把关于旧项目的记忆都删掉                                     → 删除
你：帮我整理一下长期记忆，删掉过时的信息                          → 整理

AI 会自动调用对应的记忆工具完成操作。

记忆隐私和安全

记忆文件里可能包含敏感信息。OpenClaw 提供了多层保护机制。

敏感信息过滤

OpenClaw 没有内置的记忆内容自动过滤配置。防止敏感信息写入记忆文件的最佳做法是通过 SOUL.md 明确告诉 AI：

<!-- ~/.openclaw/workspace/SOUL.md 中添加 -->
## 安全规则
- 永远不要将密码、API Key、Token、身份证号、银行卡号写入记忆文件
- 如果用户要求记住敏感信息，提醒用户使用环境变量或密钥管理器
- 记忆文件中的敏感信息用 [REDACTED] 替代

这种方式利用 AI 模型自身的判断力来过滤敏感内容，比正则匹配更智能（能识别上下文中的敏感语义，而不仅仅是模式匹配）。

记忆文件安全

OpenClaw 的记忆文件是纯文本 Markdown，存储在本地磁盘上，没有内置加密功能。如果你需要保护记忆文件：

• 磁盘加密：使用操作系统级别的磁盘加密（macOS FileVault、Linux LUKS、Windows BitLocker）

• 文件权限：确保 ~/.openclaw/workspace/ 目录权限为 700（仅所有者可读写）

• Git 忽略：如果 workspace 在 Git 仓库中，将记忆文件加入 .gitignore

# 设置 workspace 目录权限（macOS/Linux）
chmod 700 ~/.openclaw/workspace

不应该存入记忆的内容

无论有没有加密，密码、API Key、JWT Token、身份证号、银行卡号等敏感信息都不应该写入记忆文件。用环境变量或密钥管理器代替。

记忆操作追踪

OpenClaw 没有内置的记忆审计日志配置。但你可以通过以下方式追踪记忆变更：

• Git 版本控制：将 workspace 初始化为 Git 仓库，每次记忆变更都有完整历史

• 会话日志：OpenClaw 的会话日志（sessions/*.jsonl）记录了所有工具调用，包括文件写入操作

# 用 Git 追踪记忆变更
cd ~/.openclaw/workspace
git init
git add MEMORY.md USER.md memory/
git commit -m "memory snapshot"

这比内置审计日志更强大 — 你可以用 git diff 看到每次记忆变更的具体内容。

记忆系统调优

⏭️ 小白可跳过 — 这部分是技术深入分析，记忆系统默认配置已经够用

记忆文件大小控制

MEMORY.md 不应该无限增长。OpenClaw 没有内置的自动归档配置，但有以下最佳实践：

• MEMORY.md：建议控制在 500 行（约 3000 tokens）以内。内容太多会挤占对话上下文

• 每日日志：每天自动创建新文件，天然不会过大

• 手动归档：超过 30 天的日志可以手动移到归档目录

# 手动归档旧日志
# 归档目录应在 memory/ 及 extraPaths 之外；先备份并检查同名文件
mkdir -p ~/.openclaw/memory-archive
find ~/.openclaw/workspace/memory -maxdepth 1 -name "20*.md" -mtime +30 -exec mv -i {} ~/.openclaw/memory-archive/ \;

定期整理 MEMORY.md 是保持 AI 助手高效的关键 — 过时的信息不仅浪费上下文空间，还可能让 AI 产生错误判断。

记忆搜索优化

如果记忆文件很多，搜索会变慢。优化建议：

1. 运行 openclaw memory index 确保索引是最新的

2. 若要减少检索文件数量，把不再检索的日志移到 memory/ 之外、也不在 extraPaths 内的归档目录；memory/archive 仍在递归索引范围内。

3. 给记忆内容加标签方便精确搜索：## 项目信息 [tags: project, tech-stack]

记忆加载性能

如果启动时加载记忆太慢，可以优化以下方面：

1. 精简 MEMORY.md — 删除过时内容，控制在 500 行以内

2. 减少日志文件数量 — 归档超过 30 天的旧日志

3. 重建索引 — 运行 openclaw memory index 确保索引是最新的

内置引擎管理文件监听和同步，通常不需要手写刷新定时器。更换 embedding provider 或模型后，旧向量索引可能不兼容，先检查状态，再在准备好成本和权限后重新索引：

openclaw memory status --agent main
openclaw memory index --agent main --force

重新 embedding 可能产生 API 费用。本教程没有实际运行此操作。

多用户记忆隔离

如果多个人共用一个 OpenClaw 实例（比如家庭成员或小团队），记忆必须隔离。

通过多 Agent 隔离

最简单的方案：每个用户一个 Agent，配置独立的 workspace。

// ~/.openclaw/openclaw.json
{
  "agents": {
    "entries": {
      "alice": {
        "default": true,
        "workspace": "~/.openclaw/workspace-alice"
      },
      "bob": {
        "workspace": "~/.openclaw/workspace-bob"
      }
    }
  }
}

每个 Agent 默认使用独立 workspace，记忆文件按目录分开。目录分开不保证硬访问隔离；文件工具、会话工具和共享插件的实际访问仍由权限、sandbox 及可见性配置决定：

~/.openclaw/
├── workspace-alice/
│   ├── MEMORY.md          # Alice 的长期记忆
│   ├── USER.md            # Alice 的用户画像
│   └── memory/            # Alice 的日志
└── workspace-bob/
    ├── MEMORY.md          # Bob 的长期记忆
    ├── USER.md            # Bob 的用户画像
    └── memory/            # Bob 的日志

通过消息路由绑定

配合多 Agent 路由，让不同联系人的消息自动路由到对应 Agent。在顶层 bindings 配置中设置 channel、contact 和 agent 的映射关系即可（bindings 是顶层配置，不嵌套在 channels 内部）。详见 08. 多 Agent 路由。

共享记忆方案

如果需要多个 Agent 共享部分记忆，可以用符号链接指向同一个 MEMORY.md 文件，但要注意并发写入可能导致冲突。更安全的做法是通过独立 workspace 隔离，仅在需要时手动同步。

记忆插件系统

默认插件：memory-core

OpenClaw 默认使用 memory-core 插件提供记忆功能。这个插件包含：

• 记忆文件的读写操作

• memory_search 和 memory_get 工具

• compaction 时的自动记忆刷新

• 日志文件的自动创建和管理

关闭记忆功能

如果你不需要记忆（比如一次性的问答场景）：

// ~/.openclaw/openclaw.json
{
  "plugins": {
    "slots": {
      "memory": "none"
    }
  }
}

多语言记忆（v2026.2.22 新功能）

v2026.2.22 为 FTS 检索模式新增了西班牙语和葡萄牙语的停用词过滤，改善这两种语言的对话召回：

• 西班牙语

• 葡萄牙语

这两种语言的对话在 FTS 模式下召回更准；记忆文件本身用什么语言写入不受此限制。

Dreaming 记忆整理系统

v2026.9.4 的 Dreaming 默认开启，是后台整理路径：从短期记录中筛选符合来源、分数和召回条件的内容，合并或提升到 MEMORY.md。DREAMS.md 是给人审阅的阶段摘要和日记，不是另一份自动加载的长期记忆库。

启用时 memory-core 管理一个周期任务。需要关闭时设置：

{
  plugins: { entries: { "memory-core": { config: { dreaming: { enabled: false } } } } },
}

不同阶段的职责与可用配置以 官方 Dreaming 说明为准。记忆变旧降低检索排名，不等于原文件被删除；删除敏感事实还需要检查来源和派生状态。手动维护 MEMORY.md、USER.md 仍然有价值。

Active Memory、Standing Intent 和记忆导入

记忆不只有 Markdown 搜索。Active Memory 是较深的历史召回路径：默认 escalate 模式只在问题需要回忆过去、普通检索又没有可信强匹配时运行召回子 Agent。它可能增加模型调用和等待时间，不负责自动把所有聊天写进长期记忆。先阅读 Active Memory 配置，核对是否启用、允许的 Agent 和聊天类型，再用一条确实需要跨会话回忆的问题验证。

“以后有人提到发布，就提醒我核对回滚负责人”属于事件条件型记忆，可以由识别为 channel owner 的发送人在已认证的渠道对话中请 Agent 建立 Standing Intent。它检查后续符合范围的消息，不是时钟任务，也不是持续监听所有外部系统。默认有冷却、次数和有效期；取消必须明确提出。管理员或本地 CLI 可以查看、取消，但创建需要对应的渠道与发送人身份。定时提醒仍用 cron。详见 Standing Intents。

已有 Codex、Claude Code 或 Hermes 记忆时，可以在 Control UI 的 Settings → Import Memory 选择目标 Agent，审阅检测结果后导入 Markdown。来源文件不会被改动，导入内容保留在 memory/imports/，不会直接拼进 MEMORY.md，也不导入凭据、原始会话或项目设置。先核对冲突提示，再决定是否替换已有导入文件。

记忆最佳实践

1. 定期整理 MEMORY.md

MEMORY.md 是 AI 每次启动都会加载的文件。如果它太大太杂，会浪费上下文空间，还可能让 AI 混淆。

建议：

• 每周花 5 分钟整理一次

• 删除过时的信息（比如已完成的项目）

• 合并重复的条目

• 保持分类清晰

2. 善用日志文件

日常的临时信息写入日志，不要塞进 MEMORY.md：

# 好的做法
MEMORY.md → 只放长期有效的信息
memory/2026-02-25.md → 今天的临时笔记

# 不好的做法
MEMORY.md → 什么都往里塞，越来越臃肿

3. 让 AI 主动记录

重要对话后，主动让 AI 记录：

你：把今天讨论的技术方案要点记下来
AI：好的，我把以下要点写入了今天的日志：
    1. 认证方案选择 NextAuth.js v5
    2. 数据库从 MySQL 迁移到 PostgreSQL
    3. 缓存层用 Redis，TTL 设为 1 小时

4. 分类存储

在 MEMORY.md 中用清晰的标题分类：

## 技术栈
...

## 项目决策
...

## 团队信息
...

## 工作流程
...

5. 不要存敏感信息

密码、API Key、Token 等敏感信息不要写入记忆文件。用环境变量或密钥管理器。

6. 备份记忆

记忆文件可以用 Git 管理或定期导出。下面只备份实际存在的记忆文本，不打包工作空间中的凭据、数据库或会话转录。自定义工作空间时，先替换 workspace 的路径：

set -e
umask 077
workspace="$HOME/.openclaw/workspace"
backup_dir="$HOME/backups"
cd "$workspace"
set --
for item in MEMORY.md USER.md memory DREAMS.md; do
  [ ! -e "$item" ] || set -- "$@" "$item"
done
[ "$#" -gt 0 ] || { echo "没有可备份的记忆文件" >&2; exit 1; }
mkdir -p "$backup_dir"
archive="$backup_dir/memory-$(date +%Y%m%d_%H%M%S).tar.gz"
[ ! -e "$archive" ] || { echo "同名归档已存在，请另选文件名" >&2; exit 1; }
tar -czf "$archive" "$@"
printf '记忆归档：%s\n' "$archive"

归档内使用相对路径，恢复时先按下文“迁移记忆”流程解到独立工作空间并核对文件。需要恢复整个实例时，使用已验证的完整备份和匹配版本，不把这份记忆包当成完整恢复点。

工坊：给自己的 OpenClaw 做一次记忆整理

记忆系统真正好用，因为它知道什么应该长期保留，什么只应该进入当天日志，什么应该完全不写。下面这次练习会把 USER.md、MEMORY.md、每日记忆和索引命令串起来。

先查看当前记忆状态：

openclaw memory status

打开工作空间：

cd ~/.openclaw/workspace
ls

工作空间中可能有以下文件，是否已生成取决于使用情况：

MEMORY.md
USER.md
DREAMS.md
memory/

缺少尚未生成的记忆文件时，按练习需要新建即可。活跃会话状态在 <agentDir>/openclaw-agent.sqlite，保留的转录产物在 ~/.openclaw/agents/<agent-id>/sessions/，不在默认工作空间的 sessions/ 中。

第一步，整理 USER.md。它只放长期稳定的用户偏好，不放项目临时事项：

# 用户画像

## 沟通偏好

- 希望回答先给结论，再给步骤。
- 不喜欢把内部检查标准写进面向读者的文章。
- 写中文教程时偏好自然、具体、可操作的表达。

## 技术偏好

- 代码修改前先阅读现有结构。
- 文档教程要有真实命令、真实案例、排错路径。

第二步，整理 MEMORY.md。它放长期项目事实和持续有效的决策：

# 长期记忆

## OpenClaw 学习环境

- Gateway 默认端口使用 18789。
- 常用配置文件位于 `~/.openclaw/openclaw.json`。
- 本地工作空间位于 `~/.openclaw/workspace/`。

## 文档写作原则

- 教程内容面向读者，不写内部交付标准。
- 遇到平台能力差异时，要明确说明边界，不把 Claude Code 或 Codex 的能力硬套到 OpenClaw。

第三步，把今天的临时工作写入每日日志，而不是塞进长期记忆：

# 2026-06-09

## OpenClaw 文档整理

- 检查了技能系统、记忆系统、多 Agent、Docker、安全配置几章。
- 发现 FAQ 编号需要按章节重新从 Q1 开始。
- 下一步继续补充可执行工坊和排错案例。

第四步，重建索引：

openclaw memory index
openclaw memory status

第五步，用自然语言测试召回：

我写 OpenClaw 教程时有哪些原则？

如果 OpenClaw 把当天临时事项误当成长期原则，说明 MEMORY.md 写得太杂；如果它完全召回不到文档写作原则，说明索引未更新、文件位置不对，或内容写得太抽象。

记忆分层决策：一句话应该写到哪里

很多记忆污染来自一个小问题：用户说“记一下”，Agent 不知道写到哪里。你可以用下面这张表做判断。

信息类型

推荐位置

示例

长期稳定偏好

USER.md

“我喜欢先结论后步骤”

长期项目事实

MEMORY.md

“Gateway 默认端口是 18789”

当天进展

memory/YYYY-MM-DD.md

“今天修了 FAQ 编号”

会议整理产物

单独的会议纪要文档

“会议决定下周迁移部署方式”

外部知识资料

知识库 / RAG

“某 API 文档内容”

凭证、token、个人隐私

不写入记忆

API Key、身份证号、私聊原文

判断时可以问三个问题：

1. 三个月后还会有效吗？

2. 每次启动都应该让 Agent 看到吗？

3. 如果这个信息被另一个 Agent 看到，会不会造成隐私或误操作风险？

三个问题都偏“是”，才适合进入 MEMORY.md。只对今天有用，就写每日日志。只对某个材料检索有用，就进知识库。涉及凭证和隐私，直接不要写。

遗忘流程：删除、覆盖和降权

“让 AI 忘记”不是一句魔法咒语。OpenClaw 的记忆主要来自文件和索引，所以遗忘也要回到文件和索引。

如果你只是想删除一条明确内容：

cd ~/.openclaw/workspace

打开 MEMORY.md 或对应日期日志，删除那段内容，然后重建索引：

openclaw memory index

如果信息在多处出现，用搜索定位：

rg "旧项目 X|old-project-x|相关关键词" ~/.openclaw/workspace

逐处删除后，再问一次：

你还记得旧项目 X 的哪些信息？

如果 OpenClaw 仍然召回，可能来自会话历史、DREAMS.md 或知识库。继续搜索这些位置：

rg "旧项目 X|old-project-x|相关关键词" ~/.openclaw

如果要让旧信息不再主导回答，可以在 MEMORY.md 写清楚新的事实：

## 项目状态

- 旧项目 X 已归档，不再作为当前默认项目。
- 当前默认项目是 OpenClaw 文档课程。

这种做法适合项目迁移、偏好变化、职责变化。删除适合敏感信息和错误事实；覆盖适合“以前是真的，现在变了”的事实。

按来源遗忘一段会话带来的记忆

只删除 MEMORY.md 的一段文字，可能留下索引、Dreaming 派生条目或其他可追溯记忆。9.4 提供了按会话来源清理的命令，先选择正确 Agent 并预览：

openclaw memory forget --agent main --session <session-id-or-key> --dry-run --json

核对预览中将被删除的来源和条目；混合来源的条目可能被整条删除。

v2026.9.5+ 的额外影响：实际执行且选中的会话非空时，会同时清空这个 Agent 的整个 embedding cache，包括尚未发布的索引重建缓存；不是只清所选会话的缓存，也不是清所有 Agent。其他已发布的索引条目仍可检索，但之后索引可能重新生成 embedding，并向你配置的提供商发起计费请求。先看 --dry-run --json 报告中的 embeddingCacheRows；预览或空选择不会清缓存。这项清理随本次 Forget 执行，官方步骤没有要求为它另行重启 Gateway。详见当前 memory forget 范围和9.5 发布说明。

暂停相关写入者后，去掉 --dry-run 才会执行，命令没有额外的确认开关。该流程清理受追踪的记忆及索引来源，防止被遗忘会话再次导入；它不等于删除原始会话转录、所有自由文本或外部备份。敏感资料清理仍要核对这些独立副本。见 官方 memory CLI。完成后再运行一次相同的 --dry-run --json，检查剩余条目；若先前暂停了写入者，复核后按原管理方式恢复。

冲突处理：当 USER.md、MEMORY.md 和每日日志互相打架

记忆冲突很常见。例如：

USER.md：用户希望回答简短。
MEMORY.md：OpenClaw 教程需要写得厚。
memory/2026-06-09.md：今天要把安全章节补成详细工坊。

这三条并不矛盾。用户沟通偏好是“跟用户说话简短”，文档产物要求是“课程内容厚”。如果 Agent 把它们混起来，就会出现“教程也写得很短”的问题。

整理冲突时，用“适用范围”消解：

## 沟通偏好

- 和用户汇报进度时保持简短。
- 写课程正文时根据主题充分展开，不因为聊天偏好压缩教程内容。

再比如：

MEMORY.md：默认使用本地模型。
memory/2026-06-09.md：今天为了测试模型配置，临时使用 OpenAI provider。

这里应该把 MEMORY.md 改成：

## 模型策略

- 默认使用本地模型处理隐私材料。
- 做公开文档示例或非敏感测试时，可以临时切换云端 provider。

记忆冲突不能简单越删越好。把“默认规则”“例外情况”“适用场景”写清楚是更有效的整理方式。

迁移记忆：从个人机器到新环境

换电脑、换服务器、把 OpenClaw 从本地迁到 Docker，都会遇到记忆迁移。记忆迁移最重要的不是复制目录，而是避免把旧机器的凭证和会话垃圾一起带过去。

推荐迁移这些：

~/.openclaw/workspace/MEMORY.md
~/.openclaw/workspace/USER.md
~/.openclaw/workspace/memory/
~/.openclaw/workspace/DREAMS.md

谨慎迁移这些：

~/.openclaw/agents/<agent-id>/agent/openclaw-agent.sqlite
~/.openclaw/agents/<agent-id>/sessions/（保留转录产物）
旧版 auth-profiles.json（仅作迁移来源）

不要直接打包整个 ~/.openclaw 扔到新机器，除非你非常确定新旧环境的用户、路径、权限、模型 provider 都一致。

更稳的迁移流程：

# 旧机器：只打包记忆和用户画像
cd ~/.openclaw/workspace
set --
for item in MEMORY.md USER.md memory DREAMS.md; do
  [ ! -e "$item" ] || set -- "$@" "$item"
done
[ "$#" -gt 0 ] || { echo "没有可导出的记忆文件" >&2; exit 1; }
umask 077
tar -czf ~/openclaw-memory-clean.tar.gz "$@"

# 新机器：解压到工作空间
mkdir -p ~/.openclaw/workspace
tar -xzf ~/openclaw-memory-clean.tar.gz -C ~/.openclaw/workspace

# 新机器：重建索引
openclaw memory index
openclaw memory status

如果你有多个 Agent，不要把所有记忆合并成一个大文件。按 Agent 迁移：

main      -> ~/.openclaw/workspace/
coding    -> ~/.openclaw/workspace-coding/
support   -> ~/.openclaw/workspace-support/

迁移后分别测试：

你是谁？你负责什么？

如果 coding Agent 回答了 support Agent 的职责，说明工作空间或 SOUL/MEMORY 文件放错了。

记忆卫生：每周 10 分钟维护法

记忆系统不需要每天大扫除，但需要固定维护。每周花十分钟就够：

1. 打开 MEMORY.md，删除已经完成或过期的项目。

2. 把重复偏好合并成一条。

3. 把“今天做了什么”移到对应日期日志。

4. 搜索 key、token、password、secret，确认没有敏感信息。

5. 运行 openclaw memory index。

6. 问一个和当前工作有关的问题，看召回是否准确。

可以用命令快速找风险词：

rg -l "key|token|password|secret|AKIA|sk-" ~/.openclaw/workspace  # 先列文件名，再在本地审查

如果命中的是示例，也要确认已经脱敏：

sk-*** 或 ${OPENAI_API_KEY}

记忆文件是给未来的 Agent 看的。写得越像“可执行上下文”，未来越省力；写得越像聊天碎片，未来越容易误导。

记忆工坊：把项目上下文交给新 Agent

很多人使用记忆系统，是为了让新会话不用从零解释项目。下面练习把一个项目上下文整理成 Agent 能长期使用的记忆。

假设你正在维护一个开源课程项目。你希望 OpenClaw 以后知道：

- 课程面向中文读者。
- 文档要有真实命令和排错路径。
- 不在正文里写内部质量检查。
- FAQ 编号按每个分类从 Q1 开始。
- OpenClaw 的功能不能照搬 Claude Code 或 Codex。

不要把这些话全部塞进一段长文本。拆成 USER.md 和 MEMORY.md。

USER.md：

# 用户偏好

## 写作偏好

- 中文教程要自然、具体、可操作。
- 汇报时先说结论，再给关键数据。
- 不喜欢机械堆叠固定模板。

## 协作偏好

- 修改文档前先读现有结构。
- 发现问题要直接修，不只给建议。

MEMORY.md：

# 项目记忆

## OpenClaw 课程原则

- 教程正文只写读者需要的课程内容。
- 不写内部交付口径、打分表和自检话术。
- 不放空图说明或未提供的图片提示。
- FAQ 分类内编号从 Q1 开始。
- 不能虚构 OpenClaw 功能，能力边界要按本项目文档确认。

## 课程结构

- 00 阅读指南：学习路径。
- 01 项目介绍：产品心智模型。
- 02 安装部署：安装、升级、迁移。
- 03 快速开始：第一条消息和日志。
- 04 模型配置：provider、fallback、成本。
- 05 消息平台：Channel、Pairing、日志。
- 06 技能系统：Skill 编写和调试。
- 07 记忆系统：USER/MEMORY/日志。
- 08 多 Agent：路由和协作。
- 09 Docker：长期部署。
- 10 安全：加固和事故响应。
- 11 FAQ：问题定位。

写完后重建索引：

openclaw memory index

测试：

我写 OpenClaw 课程时有哪些不能做的事？

理想回答应该提到课程正文只保留读者需要的内容、不放空图提示、不虚构功能、FAQ 编号规则。如果它只泛泛回答“要写得清楚”，说明记忆写得太抽象。

记忆模板：个人、项目、团队三类分开

你可以直接复用下面三种模板。

个人偏好模板

适合 USER.md：

# 用户画像

## 沟通偏好

- ...

## 写作偏好

- ...

## 技术偏好

- ...

## 不喜欢的做法

- ...

## 需要提醒我的事

- ...

不要写：

- 密码。
- token。
- 家庭住址。
- 身份证。
- 私聊原文。

项目事实模板

适合 MEMORY.md：

# 项目记忆

## 项目目标

- ...

## 技术栈

- ...

## 目录结构

- ...

## 长期决策

- ...

## 当前约束

- ...

## 不要做

- ...

这里的关键是“长期”。今天临时修一个错别字，不该进入项目长期记忆；“FAQ 编号规则”这种会持续影响写作的规则，才适合放进去。

团队协作模板

适合共享记忆或团队 Agent：

# 团队工作记忆

## 频道

- 支持频道：
- 公告频道：
- 内部讨论：

## 升级流程

- ...

## 安全边界

- ...

## 转交规则

- ...

## 常用 Runbook

- ...

团队记忆要写得更克制。不要把个人偏好、私聊、客户原文混进去。团队 Agent 只需要完成工作所需的信息。

记忆质量自查：一条记忆是否值得长期保存

每次准备写入长期记忆前，问五个问题：

1. 这条信息三个月后还有效吗？
2. 它会影响未来多次回答吗？
3. 它是否可以被另一个 Agent 看到？
4. 它是否包含敏感信息？
5. 它是否比“今天的日志”更稳定？

例子：

句子

放哪里

原因

“用户喜欢先结论后步骤”

USER.md

长期沟通偏好

“今天修了 Docker 章节”

每日日志

临时进展

“Gateway 默认端口是 18789”

MEMORY.md

长期事实

“API Key 是 sk-xxx”

不保存

敏感凭证

“下周可能换模型”

每日日志

未确定计划

“团队禁止 Bot 自动发布公告”

MEMORY.md / 团队记忆

长期安全边界

记忆写得好，Agent 像了解你的同事；记忆写得乱，Agent 像翻过一堆旧聊天记录的人。

多 Agent 记忆分工

多 Agent 场景下，不建议所有 Agent 共享同一份 MEMORY.md。每个 Agent 应该记住自己职责内的信息。

例如：

main Agent:
用户偏好、全局安全边界、当前主要项目。

support Agent:
常见安装问题、排查流程、公开文档链接。

docs Agent:
文档结构、写作规范、术语表。

ops Agent:
运行手册、部署路径、告警解释规则。

目录可以这样：

~/.openclaw/workspace/
~/.openclaw/workspace-support/
~/.openclaw/workspace-docs/
~/.openclaw/workspace-ops/

如果需要共享事实，不要复制粘贴到每个 MEMORY.md，可以写一个共享文件：

~/.openclaw/shared/project-facts.md

然后在各 Agent 的 SOUL.md 中说明只读引用：

## 共享项目事实

需要项目通用背景时，读取 `~/.openclaw/shared/project-facts.md`。
不要修改该文件；如果发现过时信息，向 main Agent 或用户提出更新建议。

这样能减少冲突。共享记忆越少，越容易维护；共享事实越清楚，越不容易互相污染。

记忆与知识库的边界

记忆和知识库都能让 AI “知道更多”，但它们用途不同。

类型

适合放

不适合放

记忆

用户偏好、项目事实、长期决策

大量文档、完整日志、外部网页

知识库

API 文档、产品手册、FAQ、长资料

私人偏好、临时计划

每日日志

当天进展、临时结论、待办

永久规则、凭证

如果你有一份 200 页的产品手册，不要塞进 MEMORY.md。它应该进知识库或 RAG。MEMORY.md 只需要记：

## 产品资料

- 产品手册位于知识库 `product-manual`。
- 回答产品功能问题时优先检索该知识库。
- 不确定时引用资料位置，不编造。

这样长期记忆保持轻，知识库负责大资料。

临时对话：Incognito 不写会话历史，但会到期

当前版可在 Control UI 的 New thread 页面先开启 Incognito，再开始临时对话。用一段你允许发送给所选模型的普通材料做练习，确认正在 Incognito 线程，避免误在长期会话里输入。

从 v2026.9.7 起，它在创建后 24 小时或 Gateway 重启时到期，以先发生的条件为准；继续聊天不会延长期限。到期会停止活动工作并丢弃会话，不生成归档。关闭或重载页面还会丢失未发送的草稿和附件。所以需要保留结果时，在结束或维护前主动保存获准保留的内容；不要把长时间任务放进去期待重启后恢复。

Incognito 跳过自动记忆和学习，会话内容保存在进程内存；它不会限制正常工具，显式写文件仍然能留下数据，模型提供商仍会收到请求。升级后旧 UI 标签页要重载才有新增的浏览器保护，先保存草稿；旧日志不会自动消失。想立即结束，先停止当前工作，再结束/删除该临时线程，新建普通对话后再继续需要长期保留的任务。详细数据边界见官方会话管理。

常见问题

Q1：AI 怎么突然不记得之前说的话了？

最常见的原因是 compaction。当对话太长，早期消息会被压缩成摘要，细节可能丢失。

解决方案：

• 重要信息主动让 AI 写入记忆文件

• 开启 memoryFlush，compaction 前自动保存

• 若需要保留更多近期历史，先检查模型上下文和 bootstrap 大小，再考虑 agents.defaults.compaction.keepRecentTokens；这是保留预算，实际保留范围仍受上下文容量约束。

Q2：记忆文件太大了怎么办？

用 openclaw memory status 查看索引状态，直接编辑 ~/.openclaw/workspace/MEMORY.md 整理内容。超过 30 天的日志可以归档到 memory/ 和 extraPaths 之外的目录；memory/archive/ 仍会被默认递归索引。建议 MEMORY.md 控制在 500 行以内。

Q3：能不能让 AI 忘记某些事？

可以。直接编辑记忆文件删除对应内容，或者告诉 AI：

你：忘掉关于旧项目 X 的所有信息
AI：好的，我已从记忆中删除了关于项目 X 的 5 条记录。

Q4：多个 Agent 能共享记忆吗？

默认不共享。每个 Agent 有独立的 workspace 和记忆文件。

如果需要共享，可以用符号链接：

# 让 coding Agent 共享 main Agent 的 MEMORY.md
ln -s ~/.openclaw/workspace/MEMORY.md ~/.openclaw/workspace-coding/MEMORY.md

但要注意并发写入可能导致冲突。更安全的做法是通过独立 workspace 隔离，仅在需要时手动同步。

Q5：记忆搜索不准确怎么办？

OpenClaw 使用 sqlite-vec 支持混合搜索（关键词 + 语义），搜索质量通常不错。如果仍然不够精确：

1. 运行 openclaw memory index 确保索引是最新的

2. 开启 RAG + 知识库插件，扩大搜索范围

3. 给记忆内容加标签，提高匹配精度

Q6：换了电脑怎么迁移记忆？

按前面的“迁移记忆”流程导出当前 workspace 中实际存在的 MEMORY.md、USER.md、memory/ 和 DREAMS.md，用相对归档路径解压到新 Agent 的 workspace，再检查索引和召回。多个 Agent 分开导出，别把凭据、活跃数据库或完整转录混进记忆包。需要迁移整个运行环境时，用已验证的完整备份和匹配版本，按官方离线恢复步骤处理。

Q7：记忆系统会影响响应速度吗？

影响很小。主要开销在启动时加载记忆文件（通常 < 1 秒）和 memory_search 搜索。如果觉得慢，精简 MEMORY.md 内容、归档旧日志文件，或运行 openclaw memory index 重建索引。

下一步

记忆系统搞定了，你的 AI 助手现在能记住你是谁、你在做什么、你喜欢什么。去 08. 多 Agent 路由 学习如何运行多个 AI 助手，让它们各司其职。