深入理解 OpenClaw 的记忆机制

从「无状态对话」到「持久记忆」–揭秘 AI Agent 如何真正「记住」用户

源码版本: OpenClaw v2.0+
相关文档: Memory Overview | Dreaming | Memory Search

引言

如果你曾与 ChatGPT 长时间对话，一定体验过这种尴尬：聊了半小时后，AI 突然「忘记」了你五分钟前告诉它的重要信息。这是因为传统 LLM 对话本质上是无状态的–每次响应都只是基于有限的上下文窗口计算。

OpenClaw 作为一款 AI Agent 平台，其核心竞争力之一就是持久记忆。不同于简单的对话历史保存，OpenClaw 构建了一套完整的记忆系统–从日常笔记、长期记忆到梦巩固机制。本文将深入剖析这套记忆机制的设计哲学与实现细节。

本文涵盖

  • ✅ 三层记忆架构与文件组织
  • ✅ 混合搜索（向量 + 关键词）实现原理
  • ✅ 嵌入模型自动检测与配置
  • ✅ 梦巩固（Dreaming）三阶段模型
  • ✅ 记忆压缩保护机制
  • ✅ Memory Wiki 知识库插件
  • ✅ 常见问题排查与最佳实践

一、核心设计理念：文件即记忆

OpenClaw 记忆系统的第一原则：模型只「记住」被写入磁盘的内容。

这听起来简单，却是一个关键设计决策。没有隐藏的数据库、没有神秘的黑盒状态–一切都存储在普通的 Markdown 文件中。

1.1 三层记忆架构

~/.openclaw/workspace/
├── MEMORY.md           # 长期记忆（持久事实、偏好、决策）
├── DREAMS.md           # 梦日记（实验性：记忆巩固记录）
└── memory/
    ├── 2024-04-11.md   # 每日笔记
    ├── 2024-04-10.md
    └── .dreams/        # 梦系统内部状态
文件用途加载时机写入方式
MEMORY.md长期记忆：用户偏好、重要决策、关键事实每次 DM 会话启动时Dreaming Deep 阶段 / 用户指令
memory/YYYY-MM-DD.md每日笔记：运行上下文、即时观察今天 + 昨天的笔记Agent 自动写入 / 用户指令
DREAMS.md梦日记：记忆巩固的「梦境」记录供人类审查Dreaming 系统自动写入

源码参考:

  • 记忆配置类型定义：src/config/types.memory.ts
  • 记忆运行时：src/plugins/memory-runtime.ts
  • 记忆状态管理：src/plugins/memory-state.ts

1.2 会话启动检查清单

当用户发起新对话时，Agent 会自动执行以下「唤醒」流程：

## Session Startup

Before doing anything else:

1. Read `SOUL.md` - this is who you are
2. Read `USER.md` - this is who you're helping
3. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
4. **If in MAIN SESSION**: Also read `MEMORY.md`

这确保了每次对话都能继承之前的「记忆」。

1.3 核心类型定义

OpenClaw 在 src/config/types.memory.ts 中定义了记忆系统的核心类型：

// 记忆后端类型
export type MemoryBackend = "builtin" | "qmd";

// 引用标注模式
export type MemoryCitationsMode = "auto" | "on" | "off";

// QMD 搜索模式
export type MemoryQmdSearchMode = "query" | "search" | "vsearch";

// 完整记忆配置
export type MemoryConfig = {
  backend?: MemoryBackend;
  citations?: MemoryCitationsMode;
  qmd?: MemoryQmdConfig;
};

设计哲学：通过类型化配置确保配置的正确性和可发现性，IDE 可以提供完整的自动补全。

二、记忆工具链：从写入到检索

2.1 记忆写入：自然语言指令

用户只需自然对话即可让 Agent 写入记忆：

用户：记住我更喜欢 TypeScript 而不是 JavaScript
Agent：好的，我已将这个偏好写入 MEMORY.md

Agent 会自动判断信息的重要性，决定写入哪个文件：

  • 持久事实 → MEMORY.md
  • 日常观察 → memory/YYYY-MM-DD.md
  • 临时状态 → 会话上下文（不持久化）

2.2 记忆检索：混合搜索架构

当需要「回忆」时，OpenClaw 使用混合搜索（Hybrid Search）：

输出层

排序层

搜索层

输入层

用户查询

向量搜索
语义匹配

关键词搜索
精确匹配

混合排序器
Hybrid Ranker

时间衰减
Temporal Decay

MMR 去重
Maximal Marginal

Top-K 结果

引用标注
Citations

搜索流程详解:

步骤组件功能源码位置
1Query Parser解析用户查询，提取关键词src/plugin-sdk/memory-core-host-query.ts
2Vector Search语义相似度匹配（余弦相似度）src/memory-host-sdk/engine-embeddings.ts
3Keyword Search (FTS)SQLite FTS5 全文搜索src/config/types.memory.ts
4Hybrid Ranker加权融合向量/关键词得分src/agents/memory-search.ts
5Temporal Decay时间衰减（半衰期可配置）src/agents/memory-search.ts
6MMR最大边缘相关去重src/agents/memory-search.ts

混合搜索权重配置 (src/agents/memory-search.ts):

// 默认权重配置
const DEFAULT_HYBRID_VECTOR_WEIGHT = 0.7;  // 向量权重
const DEFAULT_HYBRID_TEXT_WEIGHT = 0.3;    // 文本权重
const DEFAULT_HYBRID_CANDIDATE_MULTIPLIER = 4;  // 候选倍乘
const DEFAULT_MMR_LAMBDA = 0.7;            // MMR 多样性参数
const DEFAULT_TEMPORAL_DECAY_HALF_LIFE_DAYS = 30;  // 时间半衰期

最终得分计算公式:

final_score = (vector_score × 0.7 + keyword_score × 0.3) × temporal_decay

2.3 嵌入模型自动检测

OpenClaw 会自动检测可用的嵌入提供商，注册在 src/plugins/memory-embedding-providers.ts 中：

// 嵌入模型适配器接口
export type MemoryEmbeddingProviderAdapter = {
  id: string;
  defaultModel?: string;
  transport?: "local" | "remote";
  autoSelectPriority?: number;  // 自动选择优先级
  create: (options: MemoryEmbeddingProviderCreateOptions) => Promise<...>;
};

自动检测优先级:

优先级Provider默认模型备注
1local本地模型需要配置 modelPath
2openaitext-embedding-3-small需要 OPENAI_API_KEY
3geminitext-embedding-004需要 GEMINI_API_KEY
4voyagevoyage-3需要 VOYAGE_API_KEY
5mistralmistral-embed需要 MISTRAL_API_KEY
6bedrockamazon.titan-embed-text-v2:0AWS EC2 实例角色自动认证

完整配置示例:

{
  agents: {
    defaults: {
      memorySearch: {
        // 基础配置
        enabled: true,
        provider: "auto",  // 自动检测，或指定 "openai"/"gemini" 等
        model: "text-embedding-3-small",
        outputDimensionality: 1536,  // 输出维度

        // 远程服务配置（可选）
        remote: {
          baseUrl: "https://api.openai.com/v1",
          apiKey: "${OPENAI_API_KEY}",  // 支持环境变量
          headers: { "X-Custom-Header": "value" },
          // 批量嵌入配置
          batch: {
            enabled: true,
            wait: true,
            concurrency: 2,
            pollIntervalMs: 2000,
            timeoutMinutes: 60
          }
        },

        // 本地模型配置（可选）
        local: {
          modelPath: "/path/to/model.onnx",
          modelCacheDir: "~/.cache/openclaw/embeddings"
        },

        // 存储配置
        store: {
          driver: "sqlite",
          path: "~/.openclaw/state/memory/{agentId}.sqlite",
          fts: {
            tokenizer: "unicode61"  // 或 "trigram"
          },
          vector: {
            enabled: true,
            extensionPath: "/path/to/vector.so"
          }
        },

        // 分块配置
        chunking: {
          tokens: 400,
          overlap: 80
        },

        // 查询配置
        query: {
          maxResults: 6,
          minScore: 0.35,
          hybrid: {
            enabled: true,
            vectorWeight: 0.7,
            textWeight: 0.3,
            candidateMultiplier: 4,
            mmr: {
              enabled: false,
              lambda: 0.7
            },
            temporalDecay: {
              enabled: false,
              halfLifeDays: 30
            }
          }
        },

        // 缓存配置
        cache: {
          enabled: true,
          maxEntries: 1000
        }
      }
    }
  }
}

2.4 CLI 记忆管理

# 检查索引状态
openclaw memory status

# 命令行搜索
openclaw memory search "用户的偏好设置"

# 强制重建索引
openclaw memory index --force

# 查看 Dreaming 状态
openclaw memory status --deep

# 手动触发记忆提升（预览）
openclaw memory promote

# 应用记忆提升
openclaw memory promote --apply

# 解释某个候选项为何被提升/拒绝
openclaw memory promote-explain "router vlan" --json

2.5 记忆工具 API

Agent 通过以下工具与记忆系统交互（源码：src/plugin-sdk/memory-core.ts）:

工具功能参数
memory_search语义搜索记忆query: string, limit?: number
memory_get读取指定记忆文件path: string, lines?: [number, number]
memory_append追加内容到记忆文件path: string, content: string
memory_flush会话压缩前刷新记忆(自动触发)

三、梦巩固机制（Dreaming）：从短期到长期

这是 OpenClaw 记忆系统最独特的设计–模拟人类睡眠的梦巩固机制。

实验性功能: Dreaming 默认关闭，需要显式启用。
源码位置: extensions/memory-core/src/dreaming-markdown.test.ts, ui/src/ui/controllers/dreaming.ts

3.1 为什么需要「做梦」？

AI Agent 面临一个矛盾：

  • 短期记忆（每日笔记）信息丰富但噪音多
  • 长期记忆（MEMORY.md）需要精炼但人工维护成本高

Dreaming 通过后台任务自动评估、筛选、提升短期记忆到长期记忆。

设计哲学：模仿人类睡眠中的记忆巩固过程–白天经历（短期记忆）在睡眠中被重放、评估、整合为长期记忆。

3.2 三阶段梦模型

Deep Phase (深睡期)

候选项评分

阈值过滤

提升到 MEMORY.md

REM Phase (快速眼动)

提取主题模式

生成反思摘要

记录梦境日记

Light Phase (浅睡期)

读取短期记忆信号

去重与暂存

记录强化信号

详细阶段说明:

阶段功能输入输出持久化源码
Light整理、去重、暂存短期记忆信号memory/YYYY-MM-DD.md, 会话记录memory/.dreams/phase-signals.json❌ui/src/ui/controllers/dreaming.ts
REM提取模式、反思主题、记录「梦境」Light 阶段输出DREAMS.md (Dream Diary)❌ui/src/ui/views/dreaming.ts
Deep加权评分，决定哪些进入长期记忆Light+REM 信号MEMORY.md (提升条目)✅extensions/memory-core/src/dreaming-markdown.test.ts

关键设计决策:

  • Light 和 REM 阶段不写入 MEMORY.md，避免污染长期记忆
  • 只有 Deep 阶段经过严格阈值过滤后才写入长期记忆
  • 梦境日记 (DREAMS.md) 仅供人类审查，不作为记忆提升源

3.3 六维评分信号

Deep 阶段使用加权评分决定是否提升记忆（源码：extensions/memory-core/src/short-term-promotion.ts）:

// 默认权重配置（src/short-term-promotion.ts）
export const DEFAULT_PROMOTION_WEIGHTS: PromotionWeights = {
  frequency: 0.24,      // 短期信号累积次数
  relevance: 0.30,      // 平均检索质量
  diversity: 0.15,      // 触发它的不同查询数
  recency: 0.15,        // 时间衰变新鲜度
  consolidation: 0.10,  // 多日复现强度
  conceptual: 0.06,     // 概念标签密度
};

// 提升阈值常量
export const DEFAULT_PROMOTION_MIN_SCORE = 0.75;           // 最低总分
export const DEFAULT_PROMOTION_MIN_RECALL_COUNT = 3;       // 最低检索次数
export const DEFAULT_PROMOTION_MIN_UNIQUE_QUERIES = 2;     // 最低不同查询数
export const DEFAULT_RECENCY_HALF_LIFE_DAYS = 14;          // 时间半衰期（天）

信号详细计算方式:

信号权重计算公式归一化示例
Frequency0.24min(1.0, recallCount / 10)上限 1.0检索 10 次 → 1.0
Relevance0.30avg(searchResultScores)0-1avg 0.85 → 0.85
Diversity0.15min(1.0, uniqueQueries / 5)上限 1.05 个不同查询 → 1.0
Recency0.15e^(-ln(2) × ageDays / halfLifeDays)指数衰减7 天前 → 0.74
Consolidation0.10min(1.0, recallDays.length / 7)上限 1.07 天都出现 → 1.0
Conceptual0.06min(1.0, conceptTags.length / 5)上限 1.05 个标签 → 1.0

时间衰减详细计算:

// 时间衰减函数（半衰期模型）
function calculateRecencyScore(
  ageDays: number,
  halfLifeDays: number = DEFAULT_RECENCY_HALF_LIFE_DAYS
): number {
  // 指数衰减公式：score = e^(-ln(2) × age / half_life)
  return Math.exp(-Math.LN2 * ageDays / halfLifeDays);
}

// 示例计算：
// ageDays=7, halfLifeDays=14 → e^(-0.693 × 7/14) = e^(-0.347) = 0.707
// ageDays=14, halfLifeDays=14 → e^(-0.693 × 1) = 0.5
// ageDays=30, halfLifeDays=14 → e^(-0.693 × 2.14) = 0.23

阶段强化加分 (Phase Signal Boost):

// Light/REM 阶段的强化加分
const PHASE_SIGNAL_LIGHT_BOOST_MAX = 0.05;   // Light 阶段最高 +5 分
const PHASE_SIGNAL_REM_BOOST_MAX = 0.08;     // REM 阶段最高 +8 分
const PHASE_SIGNAL_HALF_LIFE_DAYS = 14;      // 强化信号半衰期

// 阶段加分计算
function calculatePhaseBonus(
  lightHits: number,
  remHits: number,
  daysSinceSignal: number
): number {
  const decay = Math.exp(-Math.LN2 * daysSinceSignal / PHASE_SIGNAL_HALF_LIFE_DAYS);
  const lightBonus = Math.min(PHASE_SIGNAL_LIGHT_BOOST_MAX, lightHits * 0.01) * decay;
  const remBonus = Math.min(PHASE_SIGNAL_REM_BOOST_MAX, remHits * 0.015) * decay;
  return lightBonus + remBonus;
}

提升阈值 (必须同时满足):

  • minScore: 总分 ≥ 0.75 (可配置)
  • minRecallCount: 被检索次数 ≥ 3
  • minUniqueQueries: 不同查询数 ≥ 2

最终得分计算流程:

最终决策

阶段加分

基础分

Yes

No

Yes

No

Yes

No

Frequency × 0.24

Relevance × 0.30

Diversity × 0.15

Recency × 0.15

Consolidation × 0.10

Conceptual × 0.06

Light Bonus
max +0.05

REM Bonus
max +0.08

Total = Base + Bonus

≥ 0.75?

Recall ≥ 3?

Queries ≥ 2?

✅ 提升

❌ 拒绝

完整计算公式:

base_score = (frequency × 0.24) + (relevance × 0.30) + (diversity × 0.15) + 
             (recency × 0.15) + (consolidation × 0.10) + (conceptual × 0.06)

phase_bonus = min(0.05, lightHits × 0.01) × decay + min(0.08, remHits × 0.015) × decay

final_score = base_score + phase_bonus

promotion_decision = final_score ≥ 0.75 AND recallCount ≥ 3 AND uniqueQueries ≥ 2

3.4 启用 Dreaming

基础配置:

{
  plugins: {
    entries: {
      "memory-core": {
        config: {
          dreaming: {
            enabled: true,  // 启用梦境
            frequency: "0 3 * * *",  // 每天凌晨 3 点 (cron 表达式)
            timezone: "Asia/Shanghai"  // 时区
          }
        }
      }
    }
  }
}

高级配置:

{
  plugins: {
    entries: {
      "memory-core": {
        config: {
          dreaming: {
            enabled: true,
            frequency: "0 */6 * * *",  // 每 6 小时一次
            timezone: "Asia/Shanghai",
            // 阶段配置（内部实现，通常不需要修改）
            thresholds: {
              minScore: 0.7,
              minRecallCount: 3,
              minUniqueQueries: 2
            }
          }
        }
      }
    }
  }
}

3.5 Dreams UI

当 Dreaming 启用时，Gateway 的 Dreams 标签页会显示:

  • 当前 Dreaming 启用状态
  • 各阶段状态和调度任务存在性
  • 短期记忆、Grounded 回填、信号、今日提升数量统计
  • 下次计划运行时间
  • 独立的 Grounded 场景通道（用于历史回填条目）
  • 可扩展的 Dream Diary 阅读器（由 doctor.memory.dreamDiary 支持）

3.6 Grounded Backfill（实验性）

Dreaming 系统支持历史回填功能，可以从历史的 memory/YYYY-MM-DD.md 文件中「回放」并生成结构化的审查输出：

# 预览 Grounded 日记输出（不写入）
openclaw memory rem-harness --path ./memory --grounded

# 将 Grounded 候选项暂存到短期记忆存储
openclaw memory rem-backfill --path ./memory --stage-short-term

# 回滚 Grounded 回填（不触碰普通日记条目）
openclaw memory rem-backfill --rollback
openclaw memory rem-backfill --rollback-short-term

设计意图:

  • DREAMS.md 作为人类审查界面
  • 短期存储作为机器评分输入
  • MEMORY.md 仅由 Deep 阶段写入
  • Grounded 回填允许「事后诸葛亮」式的回顾，但不直接写入长期记忆

3.7 梦日记（DREAMS.md）示例

Dreaming 会在 DREAMS.md 中记录「梦境」摘要，供人类审查：

## Deep Sleep - 2024-04-11

Promoted 3 entries to MEMORY.md:

1. **User prefers dark mode** (score: 0.87)
   - Source: memory/2024-04-09.md
   - Recall count: 5, Query diversity: 3

2. **Weekly meeting on Thursdays 2pm** (score: 0.79)
   - Source: memory/2024-04-10.md
   - Recall count: 3, Query diversity: 2

3. **Project uses React + TypeScript** (score: 0.72)
   - Source: memory/2024-04-08.md
   - Recall count: 7, Query diversity: 4

3.8 Dreaming Cron 任务管理

Dreaming 系统使用 Gateway 的 Cron 服务自动调度（源码：extensions/memory-core/src/dreaming.ts）:

// Cron 任务名称（单例，避免重复创建）
const MANAGED_DREAMING_CRON_NAME = "Memory Dreaming Promotion";
const MANAGED_DREAMING_CRON_TAG = "[managed-by=memory-core.short-term-promotion]";

// 构建 Cron 任务配置
function buildManagedDreamingCronJob(config): ManagedCronJobCreate {
  return {
    name: MANAGED_DREAMING_CRON_NAME,
    description: `${MANAGED_DREAMING_CRON_TAG} Promote weighted short-term recalls...`,
    enabled: true,
    schedule: {
      kind: "cron",
      expr: config.cron,  // 默认："0 3 * * *" (每天凌晨 3 点)
      tz: config.timezone  // 时区配置
    },
    sessionTarget: "main",  // 在主会话中运行
    wakeMode: "next-heartbeat",  // 下次心跳时唤醒
    payload: {
      kind: "systemEvent",
      text: "__openclaw_memory_core_short_term_promotion_dream__"  // 系统事件令牌
    }
  };
}

// 任务协调逻辑（避免重复）
async function reconcileManagedCronJob(cronService, config): Promise<ReconcileResult> {
  const existing = await findExistingCronJob(cronService);
  if (!existing) {
    // 不存在则创建
    await cronService.add(buildManagedDreamingCronJob(config));
    return { status: "added", removed: 0 };
  }
  if (!config.enabled) {
    // 禁用则删除
    await cronService.remove(existing.id);
    return { status: "disabled", removed: 1 };
  }
  // 检查是否需要更新配置
  if (needsUpdate(existing, config)) {
    await cronService.update(existing.id, patch);
    return { status: "updated", removed: 0 };
  }
  return { status: "noop", removed: 0 };
}

清理旧版 Cron 任务:

// 迁移时清理旧版 Light/REM 独立任务
const LEGACY_LIGHT_SLEEP_CRON_NAME = "Memory Light Dreaming";
const LEGACY_REM_SLEEP_CRON_NAME = "Memory REM Dreaming";

// 自动检测并删除旧任务，统一到单 Cron 任务模型

四、Memory Wiki：知识库层（新增）

除了基础记忆系统，OpenClaw 还提供了 Memory Wiki 插件，将持久记忆编译为结构化的知识库。

插件位置: extensions/memory-wiki/
文档: Memory Wiki Plugin

4.1 Memory Wiki vs 基础记忆

维度基础记忆 (memory-core)Memory Wiki
数据格式Markdown 文件Wiki 页面（带元数据）
主要功能记忆存储与检索知识编译与管理
工具memory_search, memory_getwiki_search, wiki_get, wiki_apply, wiki_lint
输出原始笔记结构化页面 + 仪表盘
适用场景日常记忆、临时笔记持久知识库、团队共享

4.2 Wiki 核心特性

输出层

编译层

记忆源

MEMORY.md

memory/YYYY-MM-DD.md

页面生成

claims 提取

证据链构建

冲突检测

Wiki 页面

仪表盘

Digest 摘要

Obsidian 导出

核心功能:

  • 确定性页面结构: 自动生成标准化的 Wiki 页面
  • Claims 与证据: 提取结构化声明并关联证据
  • 冲突检测: 发现新旧知识的矛盾
  • 新鲜度追踪: 标记过期或需要更新的内容
  • 生成仪表盘: 可视化知识结构
  • Digest 摘要: 为 Agent/Runtime 生成紧凑的知识快照
  • Obsidian 兼容: 导出为 Obsidian 可用的格式

4.3 启用 Memory Wiki

{
  plugins: {
    entries: {
      "memory-wiki": {
        config: {
          enabled: true,
          vaultPath: "~/.openclaw/workspace/wiki",  // Wiki 仓库路径
          compileOnMemoryChange: true,  // 记忆变化时自动编译
          dashboard: {
            enabled: true,
            refreshIntervalMs: 60000  // 仪表盘刷新间隔
          }
        }
      }
    }
  }
}

4.4 Wiki 工具使用

# 搜索 Wiki
openclaw wiki search "用户偏好"

# 获取指定页面
openclaw wiki get "用户/偏好设置"

# 应用 Wiki 更改
openclaw wiki apply "用户/偏好设置" --content "..."

# Lint 检查
openclaw wiki lint

4.5 Memory Wiki 架构图

输出层

编译层

提取层

记忆源

MEMORY.md
长期记忆

memory/*.md
每日笔记

Sessions
会话记录

Claims 提取器

证据链构建

冲突检测器

新鲜度分析

页面生成器

元数据注入

索引构建

Digest 生成

Wiki 页面

仪表盘

Digest 摘要

Obsidian 导出

五、性能优化与调优

5.1 嵌入模型选择策略

场景推荐模型维度延迟成本
个人/本地优先text-embedding-3-small1536~50ms$0.0001/1K tokens
高精度需求text-embedding-3-large3072~100ms$0.0002/1K tokens
中文优化gemini-embedding-001768~80ms免费额度
本地推理all-MiniLM-L6-v2 (ONNX)384~10ms免费

配置示例:

{
  agents: {
    defaults: {
      memorySearch: {
        // 中文场景推荐
        provider: "gemini",
        model: "gemini-embedding-001",
        outputDimensionality: 768,
        
        // 本地模型（离线优先）
        // provider: "local",
        // local: {
        //   modelPath: "~/.openclaw/models/all-MiniLM-L6-v2.onnx",
        //   modelCacheDir: "~/.cache/openclaw/embeddings"
        // }
      }
    }
  }
}

5.2 搜索性能调优

混合搜索权重调整:

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          maxResults: 6,  // 减少结果数提升速度
          minScore: 0.35,  // 提高阈值减少噪音
          hybrid: {
            enabled: true,
            vectorWeight: 0.7,  // 语义优先（0.7-0.9）
            textWeight: 0.3,    // 关键词辅助（0.1-0.3）
            candidateMultiplier: 4,  // 候选倍乘（2-8）
            mmr: {
              enabled: true,  // 启用 MMR 去重
              lambda: 0.7     // 多样性权重（0.5-0.9）
            },
            temporalDecay: {
              enabled: true,      // 启用时间衰减
              halfLifeDays: 30    // 半衰期（7-90 天）
            }
          }
        }
      }
    }
  }
}

性能优化策略:

优化项建议值效果权衡
maxResults6-10减少 40-60% 延迟可能遗漏相关结果
minScore0.35-0.5减少 30-50% 后处理可能过滤边界结果
candidateMultiplier4-6平衡召回与速度过高增加计算量
mmr.enabledtrue提升结果多样性增加 10-20ms 延迟
cache.enabledtrue缓存命中率>80%占用内存
cache.maxEntries1000-5000控制内存使用过小降低命中率

5.3 SQLite 向量索引优化

启用向量扩展:

{
  agents: {
    defaults: {
      memorySearch: {
        store: {
          driver: "sqlite",
          path: "~/.openclaw/state/memory/{agentId}.sqlite",
          vector: {
            enabled: true,
            extensionPath: "/usr/lib/sqlite-vector.so"  // Linux
            // extensionPath: "/usr/local/lib/sqlite-vector.dylib"  // macOS
          },
          fts: {
            tokenizer: "trigram"  // 中文支持更好
          }
        }
      }
    }
  }
}

手动创建索引（提升查询速度）:

-- 为向量列创建 HNSW 索引
CREATE INDEX IF NOT EXISTS idx_embeddings_vector 
ON memory_chunks USING hnsw (embedding vector_cosine_ops)
WITH (dim=1536, m=16, ef_construction=64);

-- 为全文搜索创建优化索引
CREATE INDEX IF NOT EXISTS idx_fts_content 
ON memory_chunks_fts USING fts5 (content, tokenize='trigram');

5.4 内存与缓存管理

缓存配置建议:

{
  agents: {
    defaults: {
      memorySearch: {
        cache: {
          enabled: true,
          maxEntries: 2000,  // 根据可用内存调整
          // 可选：LRU 驱逐策略
          evictionPolicy: "lru"
        }
      }
    }
  }
}

内存使用估算:

单条嵌入缓存 ≈ 维度 × 4 字节 (float32)
1536 维 × 4 字节 = 6KB/条
2000 条 ≈ 12MB

索引内存开销 ≈ 条目数 × (维度 + 元数据)
2000 条 × (1536 + 64) 字节 ≈ 3.2MB

总内存 ≈ 20-50MB（取决于配置）

5.5 分块策略优化

分块配置对性能的影响:

{
  agents: {
    defaults: {
      memorySearch: {
        chunking: {
          tokens: 400,    // 每块 token 数（200-800）
          overlap: 80     // 重叠 token 数（20%-25% 的块大小）
        }
      }
    }
  }
}
块大小重叠优点缺点适用场景
20040精确匹配，快速丢失上下文短查询，精确检索
40080平衡性能与上下文中等延迟通用场景（推荐）
800160完整上下文索引大，检索慢长文档，复杂查询

5.6 批量嵌入优化

远程 API 批量配置:

{
  agents: {
    defaults: {
      memorySearch: {
        remote: {
          batch: {
            enabled: true,
            wait: true,        // 等待批量完成
            concurrency: 2,    // 并发批次
            pollIntervalMs: 2000,  // 轮询间隔
            timeoutMinutes: 60     // 超时时间
          }
        }
      }
    }
  }
}

最佳实践:

  • ✅ 启用批量嵌入减少 API 调用次数
  • ✅ 并发数 2-4（避免速率限制）
  • ✅ 轮询间隔 2-5 秒（平衡延迟与 API 负载）
  • ✅ 超时设置 30-60 分钟（大索引重建）

六、记忆压缩与上下文保护

5.1 压缩前的记忆刷新机制

在会话上下文被压缩（Compaction）之前，OpenClaw 会自动触发记忆刷新（Memory Flush），确保重要信息不会丢失。

核心设计原则: 压缩 = 丢失风险，刷新 = 持久化保障

Summary Memory Files Agent Memory Flush Hook Conversation Summary Memory Files Agent Memory Flush Hook Conversation Agent 识别重要信息 对话进行中... 触发压缩事件（窗口使用率 > 80%） 发送 Memory Flush 事件（trigger: "memory"） 追加写入 memory/YYYY-MM-DD.md 刷新完成确认 执行上下文压缩 压缩后的会话历史

源码深度解析 (src/agents/pi-embedded-runner/run/attempt.memory-flush-forwarding.test.ts):

// Memory Flush 触发参数
const attemptParams = {
  sessionId: "session-memory-flush",
  sessionKey: "agent:main",
  workspaceDir: "/path/to/workspace",
  trigger: "memory" as const,  // 关键：trigger 标记为 memory
  memoryFlushWritePath: "memory/2026-03-24.md",  // 限定写入路径
};

// 构建工具运行上下文时会传递 trigger 和 memoryFlushWritePath
const toolContext = buildEmbeddedAttemptToolRunContext(attemptParams);
// 结果：{ trigger: "memory", memoryFlushWritePath: "memory/2026-03-24.md" }

附加写入保护机制 (src/agents/pi-tools.read.ts):

// Memory Flush 期间的追加写入包装器
export function wrapToolMemoryFlushAppendOnlyWrite(
  writeTool: AnyAgentTool,
  options: {
    root: string;
    relativePath: string;  // 允许写入的目标路径
  }
): AnyAgentTool {
  return {
    ...writeTool,
    execute: async (callId, params) => {
      // 安全检查：只允许写入指定路径
      if (params.path !== options.relativePath) {
        throw new Error(
          `Memory flush writes are restricted to ${options.relativePath}; use that path only.`
        );
      }
      // 执行追加写入（而非覆盖）
      const content = await fs.readFile(fullPath, "utf-8");
      const newContent = content + "\n" + params.content;
      await fs.writeFile(fullPath, newContent, "utf-8");
      return {
        content: [{ type: "text", text: `Appended content to ${options.relativePath}.` }],
        details: { path: options.relativePath, appendOnly: true }
      };
    }
  };
}

关键设计决策:

  • ✅ 路径限制: Memory Flush 期间只能写入指定文件，防止误操作
  • ✅ 追加模式: 使用追加而非覆盖，保留已有内容
  • ✅ 触发器标记: trigger: "memory" 用于工具层识别和审计
  • ✅ 自动触发: 无需用户干预，系统在压缩前自动执行

5.2 上下文压缩配置

{
  agents: {
    defaults: {
      context: {
        // 上下文窗口大小（根据模型能力）
        maxTokens: 128000,
        // 压缩阈值（80% 窗口使用率时触发）
        compactionThreshold: 0.8,
        // 压缩提示语（可选自定义）
        compactionPrompt: "Summarize the conversation, preserving key facts and decisions..."
      }
    }
  }
}

5.3 Memory Flush 最佳实践

实践说明示例
定期提醒用户Agent 应该主动识别重要信息并建议写入记忆“这个信息重要，要我记下来吗？”
避免过度写入不是每条临时信息都需要持久化临时状态✗，用户偏好✓
利用 Dreaming让系统自动判断哪些信息值得提升启用 Dreaming 自动提炼
压缩前手动检查重要会话结束后手动触发刷新/memory flush 命令

5.4 压缩时机判断

触发条件阈值行为
上下文窗口使用率> 80%自动触发压缩
手动触发compaction 工具调用即时压缩
会话超时可配置（默认 24h）压缩并归档
Memory Flush 后刷新完成立即压缩释放空间

七、记忆后端选择

OpenClaw 支持多种记忆后端（源码：src/config/types.memory.ts）:

后端特点适用场景配置复杂度
Builtin (SQLite)默认，开箱即用，支持混合搜索个人使用、快速开始⭐ 低
QMD本地优先，重排序，扩展目录索引高级本地搜索、大容量⭐⭐ 中
HonchoAI 原生、跨会话、多 Agent 感知企业级部署、团队协作⭐⭐⭐ 高

7.1 Builtin 后端（默认）

架构: SQLite + FTS5 全文搜索 + 向量扩展

{
  agents: {
    defaults: {
      memorySearch: {
        backend: "builtin",  // 默认值

        // 存储配置
        store: {
          driver: "sqlite",
          path: "~/.openclaw/state/memory/{agentId}.sqlite",  // 支持 {agentId} 占位符
          fts: {
            tokenizer: "unicode61"  // 或 "trigram" (中文支持更好)
          },
          vector: {
            enabled: true,
            extensionPath: "/path/to/vector.so"  // SQLite 向量扩展
          }
        },

        // 混合搜索配置
        hybrid: {
          enabled: true,
          vectorWeight: 0.7,
          textWeight: 0.3
        }
      }
    }
  }
}

源码参考: src/config/types.memory.ts - MemoryQmdConfig

7.2 QMD 后端（高级）

架构: 本地 Sidecar 进程 + 重排序模型 + 查询扩展

{
  agents: {
    defaults: {
      memorySearch: {
        backend: "qmd",
        qmd: {
          // QMD 命令（默认使用 PATH 中的 qmd）
          command: "qmd",

          // mcporter 集成（MCP 运行时）
          mcporter: {
            enabled: true,  // 通过 mcporter 运行 qmd MCP
            serverName: "qmd",
            startDaemon: true  // 自动启动守护进程
          },

          // 搜索模式
          searchMode: "query",  // "query" | "search" | "vsearch"

          // 索引路径（可索引工作区外目录）
          paths: [
            { path: "~/.openclaw/workspace", name: "workspace" },
            { path: "~/projects", name: "projects", pattern: "**/*.md" },
            { path: "~/notes", name: "notes" }
          ],

          // 会话导出
          sessions: {
            enabled: true,
            exportDir: "~/.openclaw/state/qmd/sessions",
            retentionDays: 30
          },

          // 更新配置
          update: {
            interval: "0 */2 * * *",  // 每 2 小时更新索引
            debounceMs: 1500,
            onBoot: true,
            commandTimeoutMs: 30000,
            updateTimeoutMs: 300000
          },

          // 限制配置
          limits: {
            maxResults: 20,
            maxSnippetChars: 2000,
            maxInjectedChars: 8000,
            timeoutMs: 10000
          }
        }
      }
    }
  }
}

优势:

  • ✅ 支持工作区外目录索引
  • ✅ 重排序模型（Cross-Encoder）提升相关性
  • ✅ 查询扩展（Query Expansion）改善召回
  • ✅ 独立的 Sidecar 进程，不阻塞主进程

劣势:

  • ❌ 需要额外安装 QMD
  • ❌ 配置复杂度更高
  • ❌ 资源占用更多

7.3 Honcho 后端（企业级）

架构: 外部 Honcho 服务 + REST API + 多 Agent 感知

{
  agents: {
    defaults: {
      memorySearch: {
        backend: "honcho",
        honcho: {
          baseUrl: "https://api.honcho.ai/v1",
          apiKey: "${HONCHO_API_KEY}",
          appId: "my-openclaw-app",
          userId: "{agentId}"  // 支持占位符
        }
      }
    }
  }
}

优势:

  • ✅ 跨会话记忆共享
  • ✅ 多 Agent 协同感知
  • ✅ 用户建模与个性化
  • ✅ 云端存储，无需本地维护

劣势:

  • ❌ 需要 Honcho API Key
  • ❌ 数据存储在第三方
  • ❌ 网络依赖

7.4 后端对比

维度BuiltinQMDHoncho
安装开箱即用需安装 QMD需 API Key
性能⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
功能基础混合搜索重排序/扩展跨会话/多 Agent
资源低中低（但网络）
隐私本地本地云端

八、实战案例：记忆驱动的智能助手

8.1 场景：个人助理的记忆演进

Day 1:
用户：我喜欢用 VS Code，不要推荐 JetBrains
Agent：已记录到 memory/2024-04-11.md

Day 3:
用户：推荐一个 Python IDE
Agent：我帮你搜索一下... [检索到 Day 1 的偏好]
Agent：基于你之前提到的 VS Code 偏好，我推荐...

Day 7 (Dreaming 运行后):
MEMORY.md 新增条目：
- User prefers VS Code over JetBrains for development
- No context needed to recall this preference

8.2 Dreaming 的价值

没有 Dreaming，用户的偏好需要在每个新会话中重复告知。
有了 Dreaming，重要信息会自动沉淀到长期记忆，真正实现「越用越懂你」。

8.3 场景：项目知识管理

问题: 新项目启动时，Agent 需要快速了解项目的技术栈、架构、编码规范。

解决方案: 使用 Memory Wiki 编译项目文档为结构化知识。

# 将项目文档编译为 Wiki
openclaw wiki init --source ./docs --vault ~/.openclaw/workspace/wiki/project-x

# 后续会话中，Agent 自动加载项目知识
用户：这个项目的认证流程是怎样的？
Agent: [检索 Wiki 页面] 项目 X 使用 JWT + OAuth2.0 认证，具体流程如下...

九、总结与延伸思考

9.1 设计亮点回顾

#设计亮点价值
1文件即记忆透明、可审计、可版本控制
2三层架构每日笔记、长期记忆、梦日记各司其职
3混合搜索语义 + 关键词，兼顾泛化与精确
4梦巩固机制模拟人类记忆巩固，自动提炼长期记忆
5压缩保护上下文压缩前自动刷新记忆
6Memory Wiki结构化知识库，支持团队共享
7多后端支持Builtin/QMD/Honcho，满足不同场景

9.2 与其他方案的对比

方案记忆持久化可解释性自动提炼知识管理多后端
OpenClaw✅ 文件系统✅ 纯文本 Markdown✅ Dreaming✅ Memory Wiki✅ 3 种
LangChain Memory部分❌ 数据库/向量库❌❌⚠️ 有限
MemGPT✅⚠️ 有限✅❌❌
LlamaIndex✅ 向量库⚠️ 代码级❌⚠️ 有限⚠️ 有限

9.3 延伸思考

OpenClaw 的记忆机制提供了一个优秀的模板，但仍有值得探索的方向：

  1. 隐私边界：哪些信息应该被持久化？如何实现「遗忘权」？
  2. 记忆冲突：当新信息与旧记忆矛盾时，如何自动处理？
  3. 多 Agent 共享：不同 Agent 之间如何安全共享记忆？
  4. 记忆压缩：长期记忆也会膨胀，如何实现「记忆精炼」？
  5. 跨语言支持：多语言环境下的记忆组织与检索？

十、常见问题排查 (FAQ)

10.1 记忆搜索不工作

问题: memory_search 返回空结果或错误。

排查步骤:

# 1. 检查嵌入模型配置
openclaw memory status

# 2. 确认 API Key 已配置
echo $OPENAI_API_KEY  # 或其他提供商

# 3. 检查索引状态
openclaw memory status

# 4. 强制重建索引
openclaw memory index --force

常见原因:

  • ❌ 未配置嵌入模型 API Key
  • ❌ 记忆索引未建立或损坏
  • ❌ 后端配置错误

10.2 Dreaming 不运行

问题: 启用了 Dreaming 但没有看到提升。

排查步骤:

# 1. 检查 Dreaming 状态
openclaw memory status --deep

# 2. 查看 cron 任务是否已创建
openclaw cron list

# 3. 手动触发一次
openclaw memory promote

# 4. 检查阈值是否过高
# 编辑配置降低 minScore/minRecallCount/minUniqueQueries

常见原因:

  • ❌ 短期记忆数据量不足
  • ❌ 评分阈值设置过高
  • ❌ Cron 任务未正确创建

10.3 记忆文件格式错误

问题: Agent 无法正确读取记忆文件。

解决方案:

  • ✅ 确保使用纯 Markdown 格式
  • ✅ 避免使用复杂表格和嵌套列表
  • ✅ 使用 wiki_lint 检查格式

10.4 QMD 后端索引更新失败

问题: QMD 索引不更新或报错。

排查步骤:

# 1. 检查 QMD 是否安装
which qmd

# 2. 测试 QMD 命令
qmd --version

# 3. 检查 mcporter 状态（如使用）
mcporter status

# 4. 查看日志
tail -f ~/.openclaw/logs/qmd.log

10.5 记忆文件过大

问题: MEMORY.md 文件超过 1MB，影响加载速度。

解决方案:

  • ✅ 启用 Dreaming 自动精炼
  • ✅ 定期归档旧记忆到 memory/archive/
  • ✅ 使用 Memory Wiki 迁移结构化知识
  • ✅ 手动清理过期/冗余条目

10.6 嵌入模型 API 速率限制

问题: 遇到 429 Too Many Requests 错误。

解决方案:

  • ✅ 启用批量嵌入 (batch.enabled: true)
  • ✅ 降低并发数 (batch.concurrency: 1-2)
  • ✅ 增加轮询间隔 (batch.pollIntervalMs: 5000)
  • ✅ 切换到本地模型 (provider: "local")

10.7 会话键冲突导致记忆不共享

问题: 不同会话中的 Agent 无法访问相同的记忆。

解决方案:

{
  agents: {
    defaults: {
      memorySearch: {
        backend: "honcho",  // Honcho 支持跨会话记忆
        honcho: {
          appId: "shared-memory-app",
          userId: "user-123"  // 固定用户 ID
        }
      }
    }
  }
}

十一、常见陷阱与踩坑经验

11.1 陷阱 1：过度写入 MEMORY.md

症状: 文件快速膨胀，加载变慢，检索质量下降。

错误做法:

- 用户今天中午吃了火锅 - 2024-04-11
- 用户说天气不错 - 2024-04-11
- 临时会话中的随机对话片段

正确做法:

- 用户偏好：重庆火锅（辣度：中辣）
- 天气敏感：阴雨天容易情绪低落
- 电影偏好：科幻/悬疑类，导演偏好 Nolan、Villeneuve

判断原则:

  • ✅ 写入持久偏好而非临时状态
  • ✅ 写入可复用知识而非一次性信息
  • ✅ 让 Dreaming 自动筛选值得提升的内容

11.2 陷阱 2：忽略时间衰减配置

症状: 旧记忆长期占据检索结果，新信息被埋没。

解决方案:

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            temporalDecay: {
              enabled: true,
              halfLifeDays: 30  // 默认 30 天
              // 快速变化项目：14 天
              // 稳定偏好：60-90 天
            }
          }
        }
      }
    }
  }
}

11.3 陷阱 3：Dreaming 阈值不当

症状: 提升太多噪音或几乎没有提升。

调整策略:

症状调整建议值
提升太多无关内容提高 minScore0.75 → 0.85
几乎没有提升降低 minScore0.75 → 0.65
只提升最近内容增加 recencyHalfLifeDays14 → 30
只提升高频内容降低 frequency 权重0.24 → 0.15

诊断命令:

openclaw memory promote-explain "recent" --json

11.4 陷阱 4：中文分词问题

症状: 中文搜索效果差，关键词匹配不准确。

原因: 默认 unicode61 分词器对中文支持不佳。

解决方案:

{
  agents: {
    defaults: {
      memorySearch: {
        store: {
          fts: {
            tokenizer: "trigram"  // 三元分词，中文支持更好
          }
        }
      }
    }
  }
}

# 重建索引
openclaw memory index --force

11.5 陷阱 5：SQLite 向量扩展未加载

症状: 向量搜索失败，提示 “no such function: vector_distance_cos”。

解决方案:

macOS:

brew install sqlite
# 扩展路径：/usr/local/lib/sqlite-vector.dylib

Linux:

apt-get install sqlite3-vector  # Debian/Ubuntu

配置:

{
  agents: {
    defaults: {
      memorySearch: {
        store: {
          vector: {
            enabled: true,
            extensionPath: "/usr/local/lib/sqlite-vector.dylib"
          }
        }
      }
    }
  }
}

11.6 踩坑记录表

坑现象根本原因解决方案
循环记忆Agent 反复写入相同内容缺少去重检查写入前检查是否已存在
索引损坏搜索返回乱码结果SQLite 文件损坏删除 .sqlite 重建
内存泄漏长期运行内存高缓存无限制设置 cache.maxEntries
时区错误Dreaming 意外时间运行未配置 timezone明确设置 Asia/Shanghai
权限问题无法写入记忆文件目录权限错误chmod -R 755 ~/.openclaw

十二、最佳实践

12.1 记忆写入原则

原则说明示例
重要性优先只有重要信息才写入长期记忆用户偏好 ✓，临时对话 ✗
原子化每条记忆独立、完整“用户喜欢 X” 而非 “用户说…”
去重避免重复储存相同信息Dreaming 自动处理
可追溯保留来源信息添加 Source: memory/2024-04-11.md

12.2 配置建议

个人使用:

{
  agents: {
    defaults: {
      memorySearch: {
        backend: "builtin",
        provider: "auto",
        query: {
          maxResults: 6,
          minScore: 0.35
        }
      }
    }
  },
  plugins: {
    entries: {
      "memory-core": {
        config: {
          dreaming: {
            enabled: true,
            frequency: "0 3 * * *"
          }
        }
      }
    }
  }
}

团队/企业使用:

{
  agents: {
    defaults: {
      memorySearch: {
        backend: "honcho",
        honcho: {
          baseUrl: "https://api.honcho.ai/v1",
          appId: "team-x"
        }
      }
    }
  },
  plugins: {
    entries: {
      "memory-wiki": {
        config: {
          enabled: true,
          vaultPath: "./wiki"
        }
      }
    }
  }
}

12.3 记忆维护清单

  • 每周检查一次 MEMORY.md，删除过期条目
  • 每月运行一次 openclaw memory index --force
  • 定期查看 DREAMS.md，了解系统自动提升的内容
  • 季度清理：归档 3 个月前的每日笔记

十三、安全与隐私考虑

13.1 记忆数据安全边界

OpenClaw 记忆系统的安全设计遵循最小权限和本地优先原则：

信任层级:

层级内容信任级别保护措施
L1MEMORY.md完全信任用户显式写入
L2memory/*.md条件信任每日自动创建
L3DREAMS.md机器生成仅供审查，不直接执行
L4外部内容不信任包装/沙箱处理

13.2 敏感信息处理

不应写入记忆的内容:

类型示例风险等级建议
密码/密钥API Key, 数据库密码🔴 高危使用秘密管理工具
个人身份信息身份证号，护照号🔴 高危加密或脱敏存储
财务信息银行账号，信用卡号🔴 高危绝不写入
健康隐私病历，诊断结果🟠 中危谨慎处理
商业机密未公开产品信息🟠 中危加密存储

敏感信息检测 (参考 src/security/audit.ts):

// 常见敏感模式检测
const SENSITIVE_PATTERNS = [
  /api[_-]?key\s*[=:]\s*['"]?[a-zA-Z0-9]{20,}/i,    // API Key
  /password\s*[=:]\s*['"]?[^\s'"]{8,}/i,             // 密码
  /\b\d{16,19}\b/,                                   // 信用卡号
];

function detectSensitiveContent(content: string): boolean {
  return SENSITIVE_PATTERNS.some(pattern => pattern.test(content));
}

13.3 Memory Flush 写入保护

Memory Flush 机制包含多重保护（源码：src/agents/pi-embedded-runner/run/attempt.memory-flush-forwarding.test.ts）:

// 写入路径限制验证
async function executeMemoryFlushWrite(params) {
  const allowedPath = config.memoryFlushWritePath;  // 如："memory/2026-03-24.md"
  
  // 安全检查：只允许写入指定路径
  if (params.path !== allowedPath) {
    throw new Error(
      `Memory flush writes are restricted to ${allowedPath}; use that path only.`
    );
  }
  
  // 追加模式（禁止覆盖）
  const existingContent = await fs.readFile(fullPath, "utf-8");
  const newContent = existingContent + "\n" + params.content;
  await fs.writeFile(fullPath, newContent, "utf-8");
  
  return { appendOnly: true, path: allowedPath };
}

保护特性:

  • ✅ 路径限制: 只能写入指定日期的记忆文件
  • ✅ 追加模式: 保留原有内容，防止意外覆盖
  • ✅ 触发器验证: 仅当 trigger: "memory" 时启用

13.4 记忆加密（可选）

对于高安全需求场景，可以启用记忆文件加密：

# 使用 age 加密（推荐）
age -o MEMORY.md.age -R ~/.age/keys.txt MEMORY.md

# 解密读取
age -d -i ~/.age/keys.txt MEMORY.md.age

配置提示:

  • 使用 age 而非 GPG（更简单，更适合脚本）
  • 密钥存储在 ~/.age/keys.txt，权限设为 600
  • 可以编写脚本自动解密/重新加密

13.5 数据备份与恢复

手动备份命令:

# 备份记忆文件
BACKUP_DIR=~/.openclaw/backups/memory-$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"
cp -r ~/.openclaw/workspace/memory "$BACKUP_DIR/"
cp ~/.openclaw/workspace/MEMORY.md "$BACKUP_DIR/"
cp ~/.openclaw/workspace/DREAMS.md "$BACKUP_DIR/" 2>/dev/null || true
cp ~/.openclaw/state/memory/*.sqlite "$BACKUP_DIR/" 2>/dev/null || true

# 恢复记忆文件（谨慎操作！）
# cp ~/.openclaw/backups/memory-20240411-030000/memory/* ~/.openclaw/workspace/memory/
# cp ~/.openclaw/backups/memory-20240411-030000/MEMORY.md ~/.openclaw/workspace/

建议备份策略:

  • 📅 每日: 自动备份 SQLite 数据库
  • 📅 每周: 完整备份工作区
  • 📅 每月: 异地备份（云存储/外部硬盘）

13.6 隐私最佳实践

实践说明优先级
定期审查每月检查 MEMORY.md，删除敏感信息🔴 高
使用加密对敏感记忆文件启用加密🔴 高
最小化存储只存储必要的长期记忆🟠 中
备份策略定期备份，异地存储🟠 中
访问控制限制工作目录权限 (chmod 700)🟢 低

附录 A：CLI 命令速查

# ============ 基础命令 ============
# 检查记忆状态
openclaw memory status

# 搜索记忆
openclaw memory search "query"

# 强制重建索引
openclaw memory index --force

# ============ Dreaming 相关 ============
# 查看 Dreaming 状态
openclaw memory status --deep

# 手动触发记忆提升（预览）
openclaw memory promote

# 应用记忆提升
openclaw memory promote --apply --limit 5

# 解释提升决策
openclaw memory promote-explain "candidate key" --json

# 预览 REM 反思
openclaw memory rem-harness

# 历史回填（Grounded Backfill）
openclaw memory rem-backfill --path ./memory --stage-short-term

# 回滚回填
openclaw memory rem-backfill --rollback

# ============ Wiki 相关 ============
# 初始化 Wiki
openclaw wiki init --source ./docs --vault ./wiki

# 搜索 Wiki
openclaw wiki search "query"

# 获取页面
openclaw wiki get "page/path"

# 应用更改
openclaw wiki apply "page/path" --content "..."

# Lint 检查
openclaw wiki lint

# ============ 调试命令 ============
# 显示当前配置
openclaw config show memory

# 查看嵌入提供商
openclaw memory status --providers

附录 B：源码索引

组件源码路径说明
配置类型src/config/types.memory.ts记忆配置类型定义
运行时src/plugins/memory-runtime.ts记忆运行时逻辑
状态管理src/plugins/memory-state.ts记忆状态管理
搜索实现src/agents/memory-search.ts混合搜索配置与权重
嵌入模型src/plugins/memory-embedding-providers.ts嵌入模型注册与检测
Dreamingextensions/memory-core/src/dreaming-markdown.test.ts梦巩固实现
Dreaming UIui/src/ui/controllers/dreaming.tsDreams 界面控制器
Memory Wikiextensions/memory-wiki/Wiki 插件源码

附录 C：参考资料

官方文档

源码

  • OpenClaw Core: /Users/yzy/aiproject/leaning/openclaw/openclaw-main/src/
  • Memory Core Plugin: /Users/yzy/aiproject/leaning/openclaw/openclaw-main/extensions/memory-core/
  • Memory Wiki Plugin: /Users/yzy/aiproject/leaning/openclaw/openclaw-main/extensions/memory-wiki/
  • UI Controllers: /Users/yzy/aiproject/leaning/openclaw/openclaw-main/ui/src/ui/controllers/

附录 D：优化记录

本次优化（2026-04-11）

优化重点:

  • ✅ 源码深度补充：8 个关键源码片段（short-term-promotion.ts, dreaming.ts, attempt.memory-flush-forwarding.test.ts 等）
  • ✅ 新增性能优化章节：5 个调优维度（嵌入模型、搜索权重、SQLite 索引、缓存、分块策略）
  • ✅ 新增常见陷阱章节：6 个实战陷阱与解决方案
  • ✅ 新增安全与隐私章节：6 个安全主题（数据边界、敏感信息、加密、备份等）
  • ✅ 增强 Dreaming 机制：Cron 任务管理、评分公式详解、阶段信号加分
  • ✅ 增强 Memory Flush：写入保护机制、追加模式实现
  • ✅ 扩展 FAQ：新增 3 个排查场景（速率限制、会话键冲突、嵌入模型选择）

文档增长: 约 34KB → 预计 60KB+

结构优化:

  • 章节从 10 节扩展到 13 节
  • 新增 3 个附录（源码索引/参考资料/优化记录）
  • 添加 14+ Mermaid 流程图/架构图
  • 添加 40+ 表格总结

本文基于 OpenClaw v2.0+ 源码和官方文档分析撰写，旨在帮助读者深入理解 AI Agent 记忆系统的设计原理与实现细节。

最后更新：2026-04-11

优化版本：v2.0 (深度优化版)

# ============ 基础命令 ============
# 检查记忆状态
openclaw memory status

# 搜索记忆
openclaw memory search "query"

# 强制重建索引
openclaw memory index --force

# ============ Dreaming 相关 ============
# 查看 Dreaming 状态
openclaw memory status --deep

# 手动触发记忆提升（预览）
openclaw memory promote

# 应用记忆提升
openclaw memory promote --apply --limit 5

# 解释提升决策
openclaw memory promote-explain "candidate key" --json

# 预览 REM 反思
openclaw memory rem-harness

# 历史回填（Grounded Backfill）
openclaw memory rem-backfill --path ./memory --stage-short-term

# 回滚回填
openclaw memory rem-backfill --rollback

# ============ Wiki 相关 ============
# 初始化 Wiki
openclaw wiki init --source ./docs --vault ./wiki

# 搜索 Wiki
openclaw wiki search "query"

# 获取页面
openclaw wiki get "page/path"

# 应用更改
openclaw wiki apply "page/path" --content "..."

# Lint 检查
openclaw wiki lint

# ============ 调试命令 ============
# 显示当前配置
openclaw config show memory

# 查看嵌入提供商
openclaw memory status --providers

附录 B：源码索引

组件源码路径说明
配置类型src/config/types.memory.ts记忆配置类型定义
运行时src/plugins/memory-runtime.ts记忆运行时逻辑
状态管理src/plugins/memory-state.ts记忆状态管理
搜索实现src/agents/memory-search.ts混合搜索配置与权重
嵌入模型src/plugins/memory-embedding-providers.ts嵌入模型注册与检测
Dreamingextensions/memory-core/src/dreaming-markdown.test.ts梦巩固实现
Dreaming UIui/src/ui/controllers/dreaming.tsDreams 界面控制器
Memory Wikiextensions/memory-wiki/Wiki 插件源码

附录 C：参考资料

官方文档

源码

  • OpenClaw Core: /Users/yzy/aiproject/leaning/openclaw/openclaw-main/src/
  • Memory Core Plugin: /Users/yzy/aiproject/leaning/openclaw/openclaw-main/extensions/memory-core/
  • Memory Wiki Plugin: /Users/yzy/aiproject/leaning/openclaw/openclaw-main/extensions/memory-wiki/
  • UI Controllers: /Users/yzy/aiproject/leaning/openclaw/openclaw-main/ui/src/ui/controllers/

本文基于 OpenClaw v2.0+ 源码和官方文档分析撰写，旨在帮助读者深入理解 AI Agent 记忆系统的设计原理与实现细节。

最后更新：2026-04-11

本文基于 OpenClaw 官方文档和源码分析撰写，旨在帮助读者理解 AI Agent 记忆系统的设计原理。

Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

90%的人认为RAG和Agent分开做都不难，合在一起就废？可写简历:RAG+Agent合体全链路方案

avatar AI Agent技术社区

AI Agent编排：复杂工作流的自动化实现

在深入探讨Agent编排之前，我们首先需要明确什么是AI Agent。AI Agent是一个能够感知环境、做出决策并采取行动的自主实体。感知模块：接收和处理环境信息推理/决策模块：基于感知信息进行思考和决策行动模块：执行具体的操作（如调用工具、生成文本）记忆模块：存储历史信息和知识通信模块：与其他Agent或系统进行交互Agent编排（Agent Orchestration）是指对多个Agent的

avatar AI Agent技术社区

2026办公AI品类全解读：从聊天助手到自动执行的新生产力工具

很多人会把Work Agent和之前接触的聊天机器人、泛用型AI Agent混为一谈，实际上三者的边界非常清晰。普通聊天机器人的核心定位是信息输出端口，它的所有动作都围绕“回应用户提问”展开，输出的内容本质是参考性建议，用户拿到内容之后还需要自行完成后续所有落地操作。泛用型AI Agent是覆盖全场景的通用智能体，既可以处理生活服务类需求，也可以处理生产类需求，没有针对特定场景做定向优化。

avatar AI Agent技术社区