# OpenClaw Agent 记忆系统研究教程

OpenClaw Agent 记忆系统研究教程

本教程基于对 OpenClaw 项目源代码的深入分析，旨在帮助新手全面理解 Agent 记忆体系的设计原理、实现机制和使用方法。

一、概述与背景

1.1 什么是 OpenClaw 记忆系统

OpenClaw 是一个个人 AI 助手项目，其记忆系统是整个平台的核心组件之一。与传统的简单对话历史记录不同，OpenClaw 采用了基于文件系统的持久化记忆 + 向量语义搜索的混合架构设计。这种设计理念使得 Agent 能够在长期运行过程中保持对用户偏好、项目上下文和历史决策的持续记忆。

记忆系统的核心目标是解决大语言模型固有的"遗忘问题"——即每次对话都是从零开始，无法累积经验和知识。通过将重要信息持久化存储到磁盘，并在需要时通过语义搜索检索相关内容，OpenClaw Agent 能够展现出"真正记住"用户和项目的能力。这种架构的优势在于：数据完全由用户控制存储在本地，不依赖外部云服务；支持跨会话的信息复用；能够处理大量历史信息而不会耗尽上下文窗口。

1.2 记忆系统核心特性

OpenClaw 记忆系统具备多项先进技术特性。首先是语义搜索能力，通过将文本转换为高维向量表示，实现基于含义而非精确关键词的搜索。这意味着即使用户使用不同的措辞表达同一问题，系统也能找到相关的历史记录。其次是混合检索策略，系统同时使用向量相似度和 BM25 关键词匹配两种算法，并智能融合结果，兼顾语义理解和精确匹配。第三是自动索引机制，系统会监控记忆文件的变化，自动触发重新索引，确保搜索结果始终反映最新的记忆内容。此外还有灵活的嵌入提供商选择，支持 OpenAI、Gemini 或本地模型等多种嵌入提供商，用户可以根据隐私需求和性能要求进行选择。

1.3 项目架构定位

从整体项目架构来看，记忆系统位于 Agent 运行时的核心位置。它与多个子系统紧密协作：与配置系统交互获取搜索参数和提供商设置；与文件系统交互读取记忆文件和监控变化；与 SQLite 数据库交互存储和检索向量索引；与 Agent 工具系统集成，提供 memory_search 和 memory_get 两个核心工具供 Agent 调用。这种架构设计使得记忆功能成为 Agent 的"第二天性"，Agent 在处理任何需要回顾历史信息的请求时，都会自动调用记忆搜索工具来获取相关上下文。

二、记忆文件体系

2.1 文件组织架构

OpenClaw 采用简洁直观的文件系统结构来组织记忆内容。所有记忆文件都存放在 Agent 工作区内，默认路径为 ~/.openclaw/workspace，可以通过配置项 agents.defaults.workspace 进行自定义。这种设计遵循了"约定优于配置"的原则，使得用户和 Agent 都能轻松定位和管理记忆文件。

记忆文件分为两个层级，形成长期记忆和短期记忆的层次结构。长期记忆存储在 MEMORY.md 文件中，这是一个可选的、精心维护的持久化记忆库。用户和 Agent 应该将重要的决策、偏好设置、关键事实等写入这个文件。由于它会被持续加载到 Agent 的上下文中，内容应该经过筛选和整理，只保留最有价值的长期信息。短期记忆采用每日日志的形式，存储在 memory/YYYY-MM-DD.md 文件中。这些文件是append-only的追加模式，适合记录日常工作笔记、会议要点、临时决策等时效性强的内容。

2.2 记忆文件命名规范

日期格式采用 ISO 8601 标准（YYYY-MM-DD），确保跨平台兼容性并且便于排序和检索。每个日期文件是独立的，不会在不同日期之间产生混淆。这种设计借鉴了日志系统的最佳实践，通过时间维度自然地将记忆内容分区，便于管理和追溯。系统会在会话开始时自动读取今天和昨天的日期文件，将它们的内容加载到上下文中。这种设计平衡了记忆的连贯性和上下文窗口的占用——近期的记忆被优先保留，而较早的日期文件则可以通过 memory_search 工具按需检索。

2.3 记忆写入时机

何时向记忆文件写入内容是一个需要判断力的操作。根据系统设计指南，应该写入记忆的情况包括：用户明确说"记住这个"或类似表达时；做出可能影响未来交互的重要决策时；发现或确认用户的某个偏好时；需要保留某个有价值的信息片段以供将来参考时。不需要写入记忆的情况包括：纯粹的一次性临时信息；可以通过即时工具调用获取的事实性信息；对话中自然产生的过渡性内容。

系统还提供了自动记忆刷新机制（Memory Flush），这是一个智能功能，会在会话即将触发自动压缩（compaction）之前，悄无声息地提醒 Agent 将重要信息写入记忆文件。这个机制通过配置项 agents.defaults.compaction.memoryFlush 控制，默认处于启用状态。当会话接近上下文窗口上限时，系统会自动插入一个silent turn，让 Agent 有机会保存长期记忆，避免在上下文压缩过程中丢失重要信息。这种设计体现了"预防胜于治疗"的工程哲学。

2.4 记忆文件示例

以下是两种记忆文件的典型内容结构示例。MEMORY.md 的内容应该精炼、有组织：

# 用户偏好

- 偏好使用 TypeScript 而非 JavaScript
- 代码风格：严格类型检查，不使用 any
- 通信风格：简洁直接，避免过多寒暄

# 项目规范

- 提交信息格式：使用 Conventional Commits
- 测试要求：所有新功能必须有测试覆盖
- 代码审查：所有 PR 需要至少一人审批

# 重要联系人

- 后端负责人：张三 (zhangsan@example.com)
- 产品经理：李四

memory/2026-01-31.md 的内容可以更加随意，适合每日记录：

# 2026-01-31

- 开始研究 Agent 记忆系统
- 发现了向量搜索和 BM25 混合检索的巧妙设计
- 记忆文件采用 Markdown 格式，便于阅读和编辑
- 需要进一步了解 sqlite-vec 扩展的使用

下午：

- 与团队讨论了记忆系统的配置选项
- 决定先使用 OpenAI 的嵌入服务进行原型开发
- 计划下一步添加本地嵌入模型支持

三、核心工具与接口

3.1 工具列表与功能

OpenClaw 记忆系统为 Agent 提供了两个核心工具：memory_search 和 memory_get。这两个工具通常配合使用，形成"先搜索定位，再读取内容"的工作流程。memory_search 工具执行语义搜索，从索引的记忆文件中查找与查询相关的片段。它接受查询字符串、可选的最大结果数量和最小相似度分数作为参数。搜索结果包含每个匹配片段的文本内容、文件路径、行号范围和相似度分数。memory_get 工具用于安全地读取记忆文件内容。它接受文件路径、起始行号和读取行数作为参数，支持精确的内容定位。这个工具的设计体现了最小权限原则——Agent 只能读取明确配置的记忆文件路径，不能任意浏览文件系统。

3.2 memory_search 工具详解

memory_search 工具是记忆系统的主要入口，它封装了复杂的向量搜索和结果排序逻辑。从使用角度来看，Agent 在需要回顾历史信息时应该首先调用这个工具。工具的输入参数包括：query（必填）表示搜索的查询文本；maxResults（可选）指定返回的最大结果数量，默认为 6；minScore（可选）设置相似度分数阈值，低于该值的匹配不会被返回。

工具的输出包含以下字段：results 是匹配结果数组，每个结果包含 text（匹配文本片段）、path（文件路径）、from 和 to（行号范围）、score（相似度分数）；provider 指示使用的嵌入提供商；model 显示使用的嵌入模型；fallback 布尔值表示是否从本地模式回退到了远程模式。Agent 在接收到搜索结果后，通常会根据返回的路径和行号，使用 memory_get 工具读取完整的上下文，然后将这些信息整合到回复中。

3.3 memory_get 工具详解

memory_get 工具提供了对记忆文件的安全读取能力。与 memory_search 不同，这个工具不会进行任何搜索或智能匹配，而是精确地读取指定位置的内容。输入参数包括：path（必填）是要读取的文件路径，相对于工作区根目录；from（可选）指定起始行号，从 0 开始计数；lines（可选）指定要读取的行数，省略则读取到文件末尾。

这种设计有多个考量。首先是精确性，通过行号定位可以避免在大文件中迷失，Agent 只需要关注相关的小段内容。其次是安全性，Agent 不能读取工作区之外的任意文件，只能访问明确配置的记忆文件路径（包括 MEMORY.md、memory/ 目录下的文件，以及通过 memorySearch.extraPaths 配置的额外路径）。第三是上下文控制，通过限制读取范围，Agent 不会被过多的无关信息淹没，保持回复的聚焦和简洁。

3.4 工具集成机制

这两个工具并非独立运作，而是嵌入在 OpenClaw 的 Agent 工具系统中。工具的创建通过 createMemorySearchTool 和 createMemoryGetTool 函数完成，这些函数接受配置和会话密钥作为参数，返回符合 Agent 工具接口规范的对象。工具的可用性取决于配置——如果 memorySearch.enabled 被设置为 false，或者配置无法被解析（权限不足等），工具会返回 null 表示不可用。

工具描述（description）中包含重要提示："Mandatory recall step"，强调了在使用前进行记忆搜索的重要性。这个提示会显示在 Agent 的工具列表中，提醒 Agent 在回答关于历史信息的问题前应该先搜索记忆。这种设计通过系统提示将最佳实践编码进去，引导 Agent 正确使用记忆功能。

四、向量搜索原理

4.1 向量表示与嵌入

向量搜索的核心思想是将自然语言文本转换为高维向量（通常称为"嵌入"或"embedding"），使得语义相似的文本在向量空间中彼此接近。OpenClaw 使用这一技术来实现语义搜索——即使用户使用的措辞与记忆中的原始表达不同，只要语义相近，系统就能找到匹配。

嵌入过程由配置的嵌入提供商执行。OpenClaw 支持三种嵌入提供商：OpenAI 使用 text-embedding-3-small 模型，默认情况下自动选择；Gemini 使用 gemini-embedding-001 模型；本地模式可以使用兼容 GGUF 格式的本地模型（如 embeddinggemma-300M-Q8_0.gguf），通过 node-llama-cpp 库加载运行。本地模式的优势是不需要网络连接，数据完全本地处理，但需要更多的计算资源。

4.2 文本分块策略

为了高效地对大量文本进行索引和搜索，OpenClaw 采用了分块（chunking）策略。系统会将记忆文件分割成较小的片段，每个片段独立生成嵌入向量。这种设计的考量包括：控制单个向量的语义粒度（太长的文本可能包含多个主题，向量难以准确捕捉）；支持细粒度的搜索结果返回（用户可以精确找到需要的段落）；管理索引的存储开销（更小的块意味着更多的向量，但通常更实用）。

默认的分块参数设置为：目标 tokens 数 400（约 300 个中文字符左右），重叠 tokens 数 80。重叠设计确保了跨块边界的语义连续性——如果一个概念被分在了两个块的边界处，重叠部分可以保留上下文的完整性。分块过程使用基于 tokens 而非字符的分割，这与大语言模型使用相同的长度计量单位保持一致。

4.3 向量存储与索引

OpenClaw 使用 SQLite 数据库存储向量索引，这是其架构的精妙之处。系统为每个 Agent 在 ~/.openclaw/memory/<agentId>.sqlite 路径创建一个独立的数据库文件。这种设计带来了多重好处：单文件存储便于备份和迁移；SQLite 的 ACID 特性确保数据完整性；内置的索引机制加速查询；支持扩展如 sqlite-vec 实现高效的向量相似度搜索。

数据库包含以下核心表：files 表记录已索引文件的元数据，包括路径、源类型、哈希值、修改时间和大小；chunks 表存储每个文本块的详细信息，包括唯一 ID、所属文件、起止行号、文本内容、嵌入向量和使用的模型；embedding_cache 表缓存嵌入结果，相同内容的重复嵌入可以直接复用，避免冗余计算。

4.4 sqlite-vec 扩展

当系统检测到 sqlite-vec 扩展可用时，会自动利用它来加速向量搜索。sqlite-vec 是一个 SQLite 扩展，提供了原生的向量存储和相似度查询功能。与在 JavaScript 中遍历所有向量进行计算相比，sqlite-vec 可以在数据库引擎内部执行向量距离计算，大大减少了数据传输和计算开销。

配置方式是在配置文件中指定扩展路径：

{
  agents: {
    defaults: {
      memorySearch: {
        store: {
          vector: {
            enabled: true,
            extensionPath: "/path/to/sqlite-vec"
          }
        }
      }
    }
  }
}

如果扩展无法加载或不存在，系统会优雅降级到 JavaScript 内的向量计算模式，不会导致功能完全失效。这种容错设计确保了系统在各种环境下都能正常工作。

4.5 混合搜索策略

仅靠向量搜索在某些场景下表现不佳——例如搜索精确的标识符、代码符号或错误信息时，语义相似度可能无法区分高度相关和略微相关的结果。OpenClaw 采用 混合搜索策略，将向量搜索与 BM25 全文检索相结合。

混合搜索的工作流程如下：首先分别从向量和 BM25 两个检索器获取候选结果；然后将 BM25 排名转换为 0-1 范围内的分数；接着合并两个结果集，对同时出现在两个列表中的项进行加权融合；最后按综合分数排序返回最终结果。权重配置默认为向量权重 70%、文本权重 30%，这个比例可以通过配置调整：

{
  agents: {
    defaults: {
      memorySearch: {
        query: {
          hybrid: {
            enabled: true,
            vectorWeight: 0.7,
            textWeight: 0.3,
            candidateMultiplier: 4
          }
        }
      }
    }
  }
}

candidateMultiplier 参数控制候选池的大小——系统会获取比最终结果数量更多的候选，然后通过融合筛选出最佳的 N 个结果。这种设计确保了融合阶段有足够的选择空间，避免因候选不足而导致的质量下降。

五、配置系统详解

5.1 配置层次结构

OpenClaw 的记忆搜索配置采用层次化的继承结构，从全局默认值到 Agent 特定覆盖。配置解析过程首先读取 agents.defaults.memorySearch 作为全局配置，然后对于特定 Agent，读取其 agents.<agentId>.memorySearch 配置，最后将两者合并。这种设计允许在保持合理默认行为的同时，为不同的 Agent 设置差异化的搜索策略。

5.2 核心配置项

enabled 布尔值控制记忆搜索功能的总体开关，默认为 true。当设置为 false 时，系统不会创建记忆搜索工具，Agent 将无法使用记忆功能。provider 指定嵌入提供商，可选值为 "openai"、"gemini"、"local" 或 "auto"。"auto" 模式会按优先级自动选择：如果配置了本地模型路径且文件存在则使用本地；否则尝试 OpenAI；最后尝试 Gemini。这种智能选择简化了上手体验，用户不需要深入了解各个提供商的配置。

model 配置项指定使用的嵌入模型。对于 OpenAI，默认使用 text-embedding-3-small；对于 Gemini，默认使用 gemini-embedding-001。使用自定义 OpenAI 兼容端点时，可以在这里指定任意模型名称。remote 配置节包含远程 API 的连接参数：baseUrl 是 API 端点 URL；apiKey 是认证密钥；headers 是额外的 HTTP 请求头；batch 子配置控制批量索引行为，包括是否启用批量模式、并发数、轮询间隔和超时时间。

5.3 本地嵌入配置

本地嵌入模式允许用户在不依赖外部 API 的情况下运行向量搜索，这有助于保护隐私并可能降低成本。配置本地模式需要设置：

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "local",
        model: "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf",
        local: {
          modelPath: "/path/to/model.gguf",
          modelCacheDir: "/path/to/cache"
        }
      }
    }
  }
}

默认的本地模型是 embeddinggemma-300M-Q8_0.gguf，大小约 600MB。系统会在首次使用时自动下载该模型到缓存目录。运行本地嵌入需要系统支持 node-llama-cpp 库，这可能需要额外的编译步骤（pnpm approve-builds 后 pnpm rebuild node-llama-cpp）。

5.4 索引范围配置

sources 配置项控制索引的数据源范围。默认只包含 "memory"，即只索引记忆文件。如果启用了实验性的 sessionMemory 功能，可以将 "sessions" 添加到源列表中，这样会话转录也会被索引。extraPaths 配置允许索引工作区之外的其他 Markdown 文件，这对于需要引用团队文档或项目文档的场景很有用。

{
  agents: {
    defaults: {
      memorySearch: {
        sources: ["memory", "sessions"],
        extraPaths: ["../team-docs", "/srv/shared-notes/overview.md"]
      }
    }
  }
}

需要注意的是，extraPaths 中的路径必须是绝对路径或相对于工作区的路径；只有 Markdown 文件会被索引；符号链接会被忽略以避免意外行为。

5.5 同步与缓存配置

sync 配置节控制索引的更新策略：onSessionStart 决定会话开始时是否执行同步；onSearch 决定搜索时是否执行挂起的同步；watch 启用文件系统监控，自动检测文件变化；watchDebounceMs 设置文件变化的去抖动延迟；intervalMinutes 设置定期同步的间隔（0 表示禁用定期同步）。会话相关的同步还有两个特殊参数：deltaBytes 和 deltaMessages，控制会话转录的增量索引阈值。

cache 配置节控制嵌入缓存：enabled 开关默认开启；maxEntries 设置缓存条目的最大数量。嵌入缓存通过避免对相同内容的重复嵌入计算，显著提升性能并降低成本。缓存按条目过期时间自动管理，老旧的缓存条目会被清理。

六、数据库架构

6.1 数据库位置与结构

每个 Agent 的记忆索引存储在独立的 SQLite 数据库文件中，路径默认为 ~/.openclaw/memory/<agentId>.sqlite。这个路径可以通过 memorySearch.store.path 配置进行自定义，路径字符串支持 {agentId} 占位符来插入 Agent 标识符。这种设计确保了不同 Agent 之间的记忆隔离——每个 Agent 只能搜索到属于自己范围的记忆内容。

6.2 核心表结构

数据库中包含以下核心表。meta 表存储键值对形式的元数据，用于记录数据库版本、配置指纹等管理信息。files 表记录已索引文件的信息，包括主键 path（文件路径）、source（来源类型，如 "memory" 或 "sessions"）、hash（文件内容哈希）、mtime（修改时间戳）和 size（文件大小）。这个表用于跟踪哪些文件已被索引，以及检测文件是否发生了变化。

chunks 表是最核心的表，存储所有已分块的文本及其嵌入向量。字段包括：id（唯一标识符）、path（所属文件）、source（来源）、start_line 和 end_line（起止行号）、hash（内容哈希，用于检测变化）、model（使用的嵌入模型）、text（原始文本内容）和 embedding（序列化后的向量）。索引 idx_chunks_path 和 idx_chunks_source 分别加速按路径和来源的查询。

6.3 全文检索支持

如果平台支持 FTS5（Full-Text Search 5）扩展，系统会创建一个虚拟表用于 BM25 全文检索。FTS5 表的结构包含与 chunks 表相同的核心字段，但不存储嵌入向量。创建 FTS5 表是尝试性的——如果底层 SQLite 编译不支持 FTS5，系统会记录错误信息但继续正常工作，只是会回退到纯向量搜索模式。

FTS5 表的优势在于其高效的关键词匹配能力。对于包含精确术语的查询（如错误代码、API 路径、变量名等），FTS5 的 BM25 算法通常能比向量搜索返回更相关的结果。系统通过混合搜索策略融合两种检索方式的结果，发挥各自的优势。

6.4 向量存储方式

向量的存储方式取决于 sqlite-vec 扩展的可用性。当扩展可用时，向量存储在专门的虚拟表 vec0 中，该表支持原生的向量距离计算。当扩展不可用时，向量以 JSON 序列化的字符串形式存储在 chunks.embedding 字段中，搜索时需要在 JavaScript 中加载所有向量并计算余弦相似度。

两种方式的性能差异显著。sqlite-vec 扩展利用 SQLite 的查询优化和 C 级别计算，通常能快数量级。JavaScript 回退模式在向量数量较少时仍可接受，但当索引包含数千个块时，搜索延迟会明显增加。因此，对于生产环境使用，建议配置并启用 sqlite-vec 扩展。

6.5 嵌入缓存表

embedding_cache 表用于存储嵌入计算的结果缓存，避免对相同内容的重复计算。表的主键由 provider（提供商）、model（模型）、provider_key（提供商特定的键，如 OpenAI 的 input text）和 hash（内容哈希）共同组成。这种多级键设计确保了不同提供商/模型组合的嵌入不会混淆。

缓存表还记录 dims（向量维度）和 updated_at（更新时间戳），便于后续的缓存清理和管理。系统会为缓存表创建按更新时间的索引，支持按时间顺序清理过期条目。

七、数据流与生命周期

7.1 索引更新流程

记忆索引的更新遵循一套精细编排的流程。当文件发生变化时（编辑保存或外部修改），文件监控组件检测到变化并标记相关索引为"脏"（dirty）。系统有一个 1.5 秒的去抖动窗口，合并短时间内的多次修改，避免频繁的重新索引。

索引更新有多种触发方式：会话开始时的首次同步；搜索前的挂起同步；文件系统监控自动触发；定时器周期性触发。更新过程首先扫描所有需要索引的文件，检测哪些文件发生了变化（通过比较哈希值和时间戳）；然后将变化的文件重新分块，生成新的嵌入向量；最后更新数据库中的对应记录。

7.2 搜索执行流程

一次完整的搜索请求经历以下步骤。首先是查询向量化——用户输入的查询文本被发送到嵌入提供商，转换为查询向量。然后是候选检索——系统并行执行向量搜索和 BM25 搜索，获取各自的候选结果集。接下来是分数融合——将两种检索结果按配置的权重进行融合，计算每个候选的综合分数。最后是结果返回——按分数降序排列，返回前 N 个结果给调用方。

整个流程是异步的，不会阻塞 Agent 的主处理线程。搜索结果返回后，Agent 可以选择性地调用 memory_get 工具读取完整的相关片段，然后将这些信息整合到上下文中生成回复。

7.3 会话记忆索引

对于启用了 sessionMemory 实验功能的系统，会话转录也会被索引。不同于一次性写入的记忆文件，会话转录是持续增长的，系统采用增量索引策略来高效处理。当会话转录的累积变化量超过配置阈值（默认 100KB 或 50 条消息）时，系统触发后台索引任务，只处理新增的部分而不是整个历史。

这种设计平衡了索引的及时性和计算成本。变化较小时等待合并，变化较大时及时处理。搜索结果中的会话片段标注为 source: "sessions"，与普通的记忆文件来源区分开，帮助 Agent 理解信息的性质和时效性。

7.4 配置变更检测

系统会追踪嵌入配置的关键参数（提供商、模型、端点、分块参数等），并将这些信息存储在数据库的 meta 表中。当配置发生变化时，系统检测到指纹不匹配，自动触发全量重新索引。这种机制确保了配置变更后搜索结果的一致性——使用新配置重新处理所有内容，而不是混用新旧两种索引逻辑。

八、最佳实践指南

8.1 记忆文件组织建议

为了最大化记忆系统的效用，建议遵循以下组织原则。在 MEMORY.md 中，应该只保留真正长期有效的信息，包括：用户的核心偏好和通信风格；项目的技术决策和架构选择；重要的联系人和关系；长期目标和约束条件。避免将临时信息、待办事项或会快速过时的内容放入长期记忆。

在每日日志文件中，可以更加自由地记录，包括：工作进展和发现；会议要点和决策；问题和解决方案；待办事项和想法。这种分层设计使得长期记忆保持精简，而每日日志提供了丰富的历史细节供搜索回顾。

8.2 搜索优化技巧

要获得更好的搜索结果，可以尝试以下技巧。首先是使用自然语言——向量搜索擅长理解语义，用完整的句子描述你寻找的内容比使用关键词更有效。例如，搜索"用户偏好的代码风格是什么"比搜索"代码风格 偏好"更可能找到相关内容。

其次是适当缩小范围——如果知道信息可能在某个特定时间段的日志中，可以在查询中包含时间限定词，如"关于 X 的讨论在 2026 年 1 月"。向量搜索会利用这些时间相关的语义线索。

第三是迭代精化——如果首次搜索结果不理想，可以调整查询措辞再次尝试。尝试用不同的词表达同一概念，系统通常能返回不同的相关结果。

8.3 隐私与安全考量

记忆系统存储的信息可能包含敏感内容，需要注意以下安全要点。首先是文件系统权限——数据库文件和记忆文件存储在用户目录下，操作系统的文件权限是主要的访问控制层。确保只有可信用户可以访问这些文件。

其次是网络传输——如果使用远程嵌入服务（OpenAI 或 Gemini），查询内容会通过网络发送到外部服务。评估这是否与隐私需求兼容。对于最高隐私要求，应该使用本地嵌入模式。

第三是会话隔离——每个 Agent 有独立的记忆索引，配置正确的情况下不同 Agent 之间不会共享记忆。在群组或共享场景中要特别注意不要将不适合共享的信息写入可能被其他人查看的记忆文件。

8.4 故障排查

遇到记忆搜索相关问题时，可以按以下步骤排查。首先确认配置是否正确——检查 memorySearch.enabled 是否为 true，provider 配置是否有效，apiKey 等认证信息是否正确设置。其次查看日志——OpenClaw 的 Gateway 日志（通过 openclaw doctor 查看）会记录记忆系统的重要事件和错误。

如果搜索返回空结果，可能是以下原因：索引尚未建立（等待同步完成或手动触发）；没有匹配的内容（尝试调整查询）；相似度阈值过高（降低 minScore 或检查返回的分数）。如果性能下降明显，可能是索引过于庞大，考虑清理旧的每日日志或启用更激进的缓存策略。

8.5 性能调优建议

对于大规模使用的场景，以下调优建议可能有帮助。启用 sqlite-vec 扩展可以显著提升搜索性能，特别是在向量数量较多时。合理设置 candidateMultiplier 参数——较高的值（4-6）在候选阶段保留更多选择，可能提升最终结果质量，但也会增加计算开销。

如果使用远程嵌入，启用批量模式（remote.batch.enabled: true）可以在大量索引操作时降低成本和提高速度。如果嵌入服务是性能瓶颈，考虑迁移到本地嵌入模式。对于索引了大量历史内容的系统，定期清理过时的每日日志文件可以控制索引规模，维持搜索性能。

九、总结

OpenClaw 的 Agent 记忆系统是一个精心设计的复杂系统，它通过简洁的文件系统接口提供了强大的记忆和检索能力。核心设计理念包括：基于 Markdown 的纯文本存储确保了可读性和可移植性；向量语义搜索实现了跨表述的智能匹配；混合检索策略兼顾了语义理解和精确匹配；本地优先的数据存储保护了用户隐私。

对于新手用户，建议从以下步骤开始使用记忆系统：首先理解记忆文件的两个层级结构（长期记忆和每日日志）；然后在日常使用中有意识地记录重要信息；遇到需要回顾的信息时，养成使用 memory_search 的习惯。随着使用深入，可以逐步探索配置选项，如切换嵌入提供商、启用会话记忆或配置本地嵌入，以满足特定需求。

记忆系统是 OpenClaw Agent"成长"的基础——它使得 Agent 能够真正"记住"与用户的互动历史，而不是每次都是从零开始的陌生人。通过正确使用这个系统，Agent 可以逐渐积累对用户偏好、项目背景和领域知识的理解，提供越来越个性化和有效的辅助。