第9课：OpenClaw｜三级记忆存储系统【让OpenClaw拥有“长时记忆”】

你有没有经历过这样的“至暗时刻”：昨天刚刚教会AI处理公司周报的一整套自动化流程，今天开新会话，它又像个失忆的陌生人，一句“我不会，请指导一下”把你气得想摔键盘。你甚至开始怀疑——这个价值几万Tokens教会的大模型，是不是每次看到你都是“初次见面”？

这并不是模型变笨了，也不是你的Prompt写得不够好。根本原因在于OpenClaw始终遵循一条核心原则：模型是无状态的，它唯一“记住”的内容，是已经写入磁盘的那些明文信息。

今天的AI智能体助手，往往被认为能用就足够了。但要让AI真正成为你的数字分身，它必须拥有持久的长时记忆能力。本期课程，我们将完整拆解OpenClaw的三级记忆存储体系：短期会话记忆、每日日志记忆与长期核心记忆，以及背后的混合索引与向量检索机制。你将从源码层面理解它“怎么存、怎么查、怎么在‘记得住’和‘不烧钱’之间找到平衡”。

9.1 短期记忆：Redis实现与上下文缓存

一句话概括：OpenClaw的短期记忆是AI的“瞬时心灵草稿”——基于会话窗口的内存级缓存，用于存储最近N轮对话、当前任务状态与工具调用结果，而Redis作为可选缓存加速组件，能够将响应延迟从5-8秒降至2-3秒，大幅提升复杂Skill场景下系统的实时吞吐能力。

AI的“瞬时草稿纸”

短期记忆是最基础的记忆层，仅在同一个会话窗口有效，相当于AI的临时思维空间。它有几个核心特征：

• 存储位置：内存临时缓存，不写入本地文件
• 有效范围：当前打开的对话窗口，关闭即失效
• 容量限制：存在LLM上下文窗口上限（通常取决于所调用的模型），而非OpenClaw自身的配置
• 典型问题：会话切换后规则丢失、复杂任务执行到后期因上下文窗口溢出而跑偏

短期记忆解决的是“这一轮对话中的连贯性”。用户问“帮我分析这个文件”，Agent调用工具读取文件内容，然后将结果写回短期记忆，再根据文件内容回答用户的下一个问题。如果缺少这一层记忆，每次请求都需要重新读取磁盘上的大段上下文，不仅延迟高，Token消耗也成倍增长。

值得一提的是，OpenClaw在构建短期记忆时，会根据您所选择的LLM（如GPT-4、Claude）自动适配该模型的原生上下文窗口限制。当对话长度超过模型支持的限制时，OpenClaw会自动启用上下文压缩——将过长的历史对话中的关键信息提取出来，作为“近端记忆”保存到磁盘，并从当前上下文中移除冗余内容，确保长期对话不至于溢出模型窗口，同时也能持续保留核心重要信息。

语义理解修正：需要特别明确的是，短期记忆的窗口限制由所调用的底层LLM的原生上下文长度决定。例如，国产商用大模型通常支持32K至128K token不等，而开源本地模型（如通过Ollama运行的Qwen）则取决于您在agents.defaults.contextSize配置中指定的值——此配置项允许您主动设置Agent的最大上下文窗口，完全独立于模型提供商的上限，且与Redis缓存无关。Redis专注于会话状态的跨实例共享与高频读写加速，而非直接放宽上下文窗口。

Redis在短期记忆中的角色

OpenClaw在复杂Skill场景（如浏览器自动化、多步推理任务）中会出现明显的卡顿现象——AI回复从秒级变成了5-10秒，服务器内存使用量持续攀升。这些问题的根源，往往不在CPU或大模型API，而在数据存储层：每次请求都要读写大量上下文和Skill元数据，如果没有缓存机制，磁盘I/O就成了瓶颈。

Redis缓存正是解决这一问题的关键。它将高频读写数据放在内存中，实现“空间换时间”的性能优化。官方的腾讯云技术文档清晰地揭示了Redis带来的三大增效：

功能	无Redis	有Redis
会话上下文	每次从磁盘/DB读取	内存秒级读取
Skill元数据	每次重新解析	缓存复用
多实例共享	不支持	天然支持
用户限流	难以实现	原子计数器

这里的“会话上下文”指的是当前会话窗口内非常活跃的状态信息，例如最近几轮对话的完整记录，在每次LLM调用时都需要加载。将这些信息缓存在Redis中，可以显著减少磁盘I/O的压力。而Skill元数据则是指各个技能（如文件系统、浏览器控制）的SKILL.md文件内容解析结果，在首次读取Skill文档之后，如果没有Redis，Agent每次调用该Skill都需要重新解析完整的Markdown文档（这本身包含上下文信息），而有了Redis缓存，这些已经解析过的“Skill知识”可以被复用。

多实例共享这一优势尤为关键——当多个Gateway实例同时运行时，使用Redis充当集中式会话存储层，可以让不同节点共享会话状态。同时，Redis的原子计数器还能方便地对用户进行限流控制，防止恶意用户过度消耗API资源。

Redis部署实战

在OpenClaw中集成Redis主要有两种部署模式。

模式A：同机部署，适用入门场景

# Docker方式部署Redis
docker run -d \
  --name redis \
  --restart unless-stopped \
  -p 127.0.0.1:6379:6379 \
  -v redis-data:/data \
  redis:7-alpine \
  redis-server --requirepass your-strong-password \
  --appendonly yes \
  --maxmemory 512mb \
  --maxmemory-policy allkeys-lru

参数解读：

• --requirepass：设置密码，生产环境必设
• --appendonly yes：开启持久化，防止重启丢数据
• --maxmemory 512mb：限制最大内存（2GB服务器推荐256-512MB，4GB推荐512MB，8GB推荐1GB）
• --maxmemory-policy allkeys-lru：内存满时自动淘汰最少使用的数据
• 127.0.0.1:6379：只监听本机地址（localhost），不暴露到公网，这是默认的安全做法

⚠️ 安全红线：Redis务必只绑定localhost（127.0.0.1），而非0.0.0.0，并设置强密码。切勿将6379端口直接暴露到公网，否则极易招致数据泄露或服务器被入侵的风险。

模式B：使用云托管Redis（推荐生产环境）

如果并发量较大或对高可用性有要求，建议使用云服务商提供的Redis托管服务（如阿里云Redis、腾讯云Redis等），彻底省去版本维护与故障恢复的运维开销。

连接配置：

在OpenClaw的环境变量或配置文件中添加Redis连接信息：

# .env 或环境变量
REDIS_URL=redis://:your-strong-password@127.0.0.1:6379/0

验证Redis是否生效：

# 检查连接
docker exec -it redis redis-cli -a your-strong-password ping
# 应返回 PONG

# 查看缓存命中率
docker exec -it redis redis-cli -a your-strong-password info stats | grep hit
# 关注 keyspace_hits 和 keyspace_misses，命中率建议在80%以上

从测试数据来看，加入Redis后复杂对话的平均响应速度从5-8秒缩短到了2-3秒，用户体验提升非常明显。

避坑指南：Redis配置仅解决会话状态和Skill元数据的高频读写加速问题，不会替代MEMORY.md组成的持久化知识记忆层——这两层是互补关系。“短期记忆”中的“短期”是指相对于永久记忆（MEMORY.md）而言，但通过Redis缓存的活跃会话状态可能在会话结束后就被清理，而写入MEMORY.md的内容则永久存在。因此，切勿将重要长期知识直接写入Redis中。

9.2 长期记忆：知识图谱构建（Neo4j）

一句话概括：OpenClaw的长期记忆分为两个互补层次——MEMORY.md提供轻量级确定性持久存储，而基于Neo4j的知识图谱插件则为企业级场景提供实体关系建模、跨Agent记忆共享和毫秒级向量检索能力。

日常级长期记忆：MEMORY.md

在进入企业级知识图谱之前，先了解OpenClaw自带的长期记忆基础层——MEMORY.md。

MEMORY.md是OpenClaw默认的唯一长期记忆载体，位于Workspace根目录。所有跨会话的持久化规则都必须存在于此。它的加载机制是：每次主会话启动时自动加载，存储内容包括用户偏好、禁止行为决策、固定流程和常用工具配置。

# MEMORY.md 标准模板

## 基础偏好
- 输出语言：优先使用中文，简洁专业，不冗余
- 技术栈偏好：TypeScript > JavaScript，后端使用Node.js
- 沟通风格：先用一句话总结结论，再用分点展开说明

## 决策记录
- 2026-04-01：团队决定迁移至OpenClaw构建个人AI办公助手
- 2026-04-15：强制规定所有外部API调用必须有重试机制

## 永久禁用行为列表
- 绝对禁止执行 rm -rf 命令（除非用户明确授权且属于指定隔离路径）
- 禁止未经确认就删除工作空间外的文件

MEMORY.md的设计理念是“文件即真理”——所有记忆以明文Markdown存储于本地工作区，模型仅保留写入磁盘的内容，无隐藏数据库或黑盒状态。这种设计保证了记忆的完全可审计、可编辑和可迁移。

核心实战提醒：很多用户配置失败的核心原因在于“只在对话里口头告诉AI规则，但没有写入MEMORY.md”。AI第二天新开会话再次面对同样的对话，自然不可能永久保留规则。如您的Agent会话已接入企业微信或飞书等IM环境，请在默认dmScope: main模式下测试MEMORY.md中的规则是否会首次加载时生效——确保AI始终“认识您”。

企业级知识图谱：Neo4j+Graphiti集成

当对话规模扩大到需要跨多个Agent共享记忆、需要建模实体间的复杂关系（如客户与订单、项目与文档）、或者需要时间维度的记忆追溯时，单一的MEMORY.md就不够了。OpenClaw通过openclaw-graphiti-plugin，将Neo4j用于图存储、Qdrant用于向量搜索的Graphiti服务集成到系统中，打造出支持时间感知的知识图谱。

知识图谱插件的核心能力包括：

能力维度	具体实现
知识图谱工具	graphiti_search和graphiti_ingest可作为Agent工具，按需查询实体/关系和手动摄入
自动捕获（Auto-capture）	自动将对话内容摄入知识图谱（在ContextEngine模式下每轮写入，在hooks模式下在压缩/重置时写入），通过Graphiti的LLM pipeline异步提取实体和关系
自动索引（Auto-index）	当文件被写入memory/目录时，自动在Graphiti中创建索引片段，将基于文件的记忆与知识图谱打通
自动回忆（Auto-recall）	可选地在每轮对话前注入相关事实（默认为关闭状态，按需开启）
CLI命令	`openclaw graphiti status	search	episodes	ingest	backfill`
Slash命令	/graphiti快速检查知识图谱健康状态

一个特别值得注意的设计哲学是：Graphiti插件并不强制占用OpenClaw的“记忆槽位（memory slot）”。官方推荐的最佳实践是让memory-core（基于Markdown文件的混合检索）和graphiti插件同时运行，互相补充——memory-core负责基于文件系统的BM25+向量混合搜索，graphiti负责时间感知的知识图谱查询，两者在不同的数据源上独立运作，共同构建更完整的长期记忆能力。

Graphiti部署实操

要集成Graphiti知识图谱，您需要准备一个运行中的Graphiti服务栈，包括Neo4j和Qdrant。官方提供了预配置的docker-compose部署文件。

Step 1：搭建Graphiti服务栈

# docker-compose.yml (Graphiti核心组件)
services:
  neo4j:
    image: neo4j:5
    environment:
      - NEO4J_AUTH=neo4j/your-password
    volumes:
      - neo4j-data:/data

  qdrant:
    image: qdrant/qdrant:latest
    volumes:
      - qdrant-storage:/qdrant/storage

  graphiti-server:
    image: getzep/graphiti:latest
    environment:
      - NEO4J_URI=bolt://neo4j:7687
      - NEO4J_USER=neo4j
      - NEO4J_PASSWORD=your-password
      - QDRANT_URL=http://qdrant:6333
      - OPENAI_API_KEY=your-openai-key  # Graphiti需要OpenAI API Key进行实体提取
    ports:
      - "8001:8001"

⚠️ 重要提示：Graphiti服务需要OpenClaw自己的API Key之外独立的OPENAI_API_KEY，用于从对话中提取实体和关系。如果在Graphiti服务中缺少这个Key，数据摄取请求会返回202 Accepted（表示接受请求），但后台的实体提取永远不会执行，也就不会产生任何图谱中的片段。

Step 2：安装插件

openclaw plugins install @robertogongora/graphiti

插件安装后，Graphiti可以从~/.openclaw/extensions/目录下自动发现。手动安装（通过克隆仓库并创建符号链接）也同样支持。

Step 3：在配置文件中启用

在~/.openclaw/openclaw.json中添加如下配置：

{
  "plugins": {
    "slots": {
      "memory": "memory-core"
    },
    "entries": {
      "memory-core": {
        "enabled": true
      },
      "graphiti": {
        "enabled": true,
        "config": {
          "url": "http://localhost:8001",
          "groupId": "core",
          "autoCapture": true,
          "autoRecall": false
        }
      }
    }
  }
}

这里autoCapture: true让系统自动将每轮对话中的相关信息摄入知识图谱（作为实体）；autoRecall: false保持按需召回——避免每轮都注入大量历史事实造成Token浪费，仅在需要时由Agent主动调用graphiti_search工具进行查询。

MEMORY.md vs 知识图谱的选择

那当您的业务或Agent到了什么阶段，才真正需要知识图谱呢？请参考下表：

维度	MEMORY.md（日常级）	知识图谱插件（企业级）
存储规模	中小规模（几MB到几十MB）	大规模（千万级实体）
查询能力	全文关键词+语义搜索	实体关系查询+时间维度追溯
跨Agent共享	不支持	支持（同一userId共享记忆）
运维复杂度	零运维	需要管理Neo4j+Qdrant+Graphiti服务
典型场景	个人助理、开发调试	企业知识库、客户关系管理

9.3 记忆中继存储访问协议的设计

一句话概括：OpenClaw的记忆访问通过标准化的工具接口（Memory Tools）+ 统一的Markdown真相源 + 独立的二级缓存SQLite倒排索引三层结构，以“文件即真相”为核心，确保记忆操作的一致性、可审计性和高性能。

文件即真相：设计哲学

OpenClaw记忆系统的底层设计哲学叫做“文件即真相”（Files as Source of Truth）：

• 所有记忆以明文Markdown存储在本地工作区（~/.openclaw/workspace/）
• 模型仅保留写入磁盘的内容，没有隐藏的数据库状态或黑盒状态
• 所有修改立即同步写入磁盘（通过fsync确保极端断电情况下数据不丢失）
• 用户拥有对记忆数据的完全控制权

这种设计的优势显而易见：记忆完全可审计（随意打开Markdown文件查看）、可手动编辑（用任何文本编辑器修改AI的记忆）、可迁移（复制工作区目录即可搬到新机器），且不会因为AI模型切换或框架升级而失忆。

记忆访问的三层工具模型

OpenClaw为Agent提供了两个核心记忆工具：

工具名	功能	语法示例
memory_search	语义搜索（混合BM25+向量）	memory_search("用户上次提到的API Key问题")
memory_get	直接读取指定文件或行范围	memory_get("MEMORY.md") / memory_get("memory/2026-05-05.md", lines=10-20)

memory_search的强大之处在于，它支持混合搜索——同时利用关键词精确匹配（BM25评分）和向量语义相似度，从Markdown文件中查找最相关的记忆片段。当与向量索引配合时，即使提问的措辞和原文完全不同（例如问“那次方案讨论”而非“2026年4月的架构评审会”），也能准确命中目标。

SQLite索引结构深度解析

在Markdown文件之外，OpenClaw还维护了一层独立的SQLite数据库，实现对记忆的高效检索。这个SQLite数据库对用户来说是隐形的——用户始终与Markdown文件交互，Agent通过memory_search工具查询的内容，背后其实是SQLite在做检索加速。

每个Agent对应一个独立的SQLite数据库，位于~/.openclaw/memory/{agentId}.sqlite。核心表结构如下：

-- 文件元数据表：记录每个记忆文件的修改时间和哈希值
CREATE TABLE files (
  id INTEGER PRIMARY KEY,
  path TEXT UNIQUE,
  mtime INTEGER,      -- 修改时间，用于增量索引
  size INTEGER,
  hash TEXT           -- 内容哈希，用于去重
);

-- 文本块存储表
CREATE TABLE chunks (
  id INTEGER PRIMARY KEY,
  file_id INTEGER,
  start_line INTEGER,
  end_line INTEGER,
  text TEXT,
  hash TEXT UNIQUE,   -- 文本哈希，跨文件去重
  embedding TEXT      -- JSON序列化的向量
);

-- 全文搜索虚拟表（FTS5）
CREATE VIRTUAL TABLE chunks_fts USING fts5(
  text,
  content=chunks
);

-- 向量搜索虚拟表（sqlite-vec）
CREATE VIRTUAL TABLE chunks_vec USING vec0(
  embedding float[1536]      -- 向量维度
);

这里的几个关键设计体现了工程上的深思熟虑：

• 增量索引：通过mtime（文件修改时间）和hash字段，系统每次启动或文件有变动时，只重新索引那些实际变更过的文件，而非全量重建。
• 去重存储：相同文本块（通过hash去重）只存一次向量，大幅节省存储空间。
• 优雅降级：如果sqlite-vec扩展没有成功加载，系统会自动回退到JavaScript暴力计算（在内存中遍历所有分块并逐一计算向量相似度）。性能会下降很多，但功能不受影响。

避坑指南：SQLite数据库存储量随daily log和MEMORY.md文件数量而线性增长。当长期记忆库膨胀到数GB级别时，检索性能会显著下降，建议配合openclaw memory index --force定期重建索引，或使用HEARTBEAT定时任务实现自动索引刷新。

自动记忆刷新：压缩不丢记忆

OpenClaw还有一个容易被忽略但极其重要的机制——自动记忆刷新（Auto Memory Flush） 。在系统对过长对话进行“上下文压缩”总结之前，OpenClaw会先运行一个静默回合，提醒Agent将重要上下文保存到记忆文件中。该功能默认开启，用户无需任何配置。

这个设计防止了压缩操作带来的“记忆泄漏”：如果Agent的对话中有重要事实尚未写入文件（MEMORY.md或memory/YYYY-MM-DD.md），它们会在摘要发生前被自动保存下来。这也是为什么OpenClaw在长对话场景中比大多数Agent框架更“有记性”的底层原因之一。

9.4 会话状态变更的预写式日志（WAL）机制

一句话概括：OpenClaw采用SQLite的WAL（预写日志）模式管理会话状态变更——所有写入操作先在日志文件中“预演”，再在适当时机同步到主数据库，确保断电或崩溃时即使主数据库尚未来得及更新，系统仍能从日志中恢复会话状态，实现进程退出即可零数据丢失。

为什么需要WAL？

在传统的“回滚日志”（Rollback Journal，简称为WAL技术的“前身”）模式下，每次修改需要先复制主数据库副本，写操作完成后再覆盖回去，写入速度慢且容易因为中间状态的意外中断而产生无法恢复的损坏（如只覆盖了一半数据）。OpenClaw基于SQLite构建的内存数据库，在频繁写入会话日志时同样面临这些问题——每次Agent会话的每一步更新，都涉及活动日志的修改写入。

WAL（Write-Ahead Logging）将所有修改先写入独立的日志文件中（WAL文件），而不是直接写入主数据库。直到某个触发点（如日志文件达到一定阈值），系统才将这些修改“批量回放”到主数据库中（这一操作称为“Checkpoint/检查点”）。这种机制带来的好处是：

• 更高的写入性能：追加写入日志比覆写数据库页面快得多
• 更优的并发性：读操作可以与写操作同时进行（但要注意的是，SQLite的事务隔离级别在全库范围，同一时刻只有一个写操作在执行）
• 更强的崩溃恢复能力：系统重启后会自动从WAL文件恢复未提交的更改，确保数据不丢失

官方文档明确指出，OpenClaw对SQLite WAL副文件会通过定期检查点和关闭时检查点进行限制，避免日志文件无限膨胀。

WAL机制下的会话持久化

在OpenClaw的会话管理流程中，每一次Agent工具调用结果、每一次新的用户消息确认、每一项会话元数据的更新，都会通过append-only的方式追加写入对应的会话日志中。同时，对sessions.json的状态索引也会以JSON进行更新。底层SQLite将这些修改操作先累积在WAL文件中，在合适时机统一落盘，并通过updateSessionStoreEntry()同步更新会话元数据。

这种设计保证了Agent在瞬间崩溃后可以安全恢复——重启后系统从磁盘上最后一次完整的WAL检查点状态获得一致性快照，再从WAL文件中加载尚未检查点的增量变更。不会出现“Agent说自己已写完的报告，重启后找不到了”这种数据不一致的问题。

9.5 记忆检索：语义搜索与混合检索

一句话概括：OpenClaw的记忆检索不依赖第三方外部索引工具，而是内置了一套轻量级但强大的混合检索引擎（Hybrid Search Engine）——通过BM25关键词匹配与向量语义搜索并行执行，再以加权融合的方式合并两路结果，使Agent即便在CPU-only的个人服务器上也能提供接近商业RAG系统的检索体验。

为什么需要混合检索？

单一搜索策略往往力不从心——全文关键词搜索能精确命中特定短语，但可能错过语义相近的内容；纯向量语义搜索能理解大意，却可能遗漏精确的技术标识符（如API Key、函数名）。OpenClaw的混合检索引擎正是为了解决这个问题而设计的：两条腿并行，同时走路，再归一化融合，实现高召回率（关键词确保关键信息不丢失）+ 高相关性（向量确保语义匹配）[13†L9-L10]。

检索架构：双路并行

当用户向Agent发送一个意图不明的记忆查询（例如“上周二提到的那个API文档在哪？”），系统在内部执行以下检索流程：

1. 生成查询向量（Query Vector） ：使用同一套嵌入模型将用户查询转换为向量表示
2. 并行执行两条路：
   • FTS5全文搜索：利用SQLite的FTS5扩展和BM25评分算法，对memory_chunks表中的文本字段进行关键词匹配
   • 向量相似度搜索：利用sqlite-vec扩展的向量距离函数，搜索语义相近的记忆分块
3. 归一化与融合：将两路结果的得分分别归一化到0-1区间，然后按默认70%向量权重 + 30%全文权重进行加权求和
4. 去重排序：合并来自两路的结果，去除重复分块，按融合得分排序后返回Top K个结果

这种加权方式经大量测试证明为最佳平衡点，既保证了视觉趋势，又避免了丢失精确术语。

向量搜索的嵌入提供商配置

OpenClaw的内置记忆引擎会自动检测嵌入提供商。可用的提供商包括OpenAI、Gemini、Voyage、Mistral、DeepInfra、Ollama和内置本地嵌入。自动检测会按列表顺序选择第一个能够解析其API密钥的提供商。

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",        // 可选值：openai/gemini/ollama/local
        "enabled": true
      }
    }
  }
}

对于希望完全离线的本地部署场景，用户需要安装node-llama-cpp运行时，并配置local.modelPath指向Embedding模型GGUF文件的本地路径。

实战调优：可以使用openclaw memory status --deep查看当前索引状态，用openclaw memory index --force执行全量重建。向量嵌入维度越高（如1536），对内存和显存的压力越大。选择时需在硬件资源与搜索精度之间权衡。

9.6 配置记忆模块的实战步骤

一句话概括：从默认的本地记忆到企业级云端存储，OpenClaw的记忆模块配置有明确的递进路径——按需选用，不必一开始就追求企业级方案。

诊断当前记忆系统

# 查看当前记忆状态
openclaw memory status --deep

# 查看特定Agent的索引信息
openclaw memory status --agent main

Step 1：确认MEMORY.md基础配置

这是最优先的配置层级，启动独立部署方式时无需额外安装任何依赖。

# 检查workspace/MEMORY.md是否存在
ls -la ~/.openclaw/workspace/MEMORY.md

# 如未自动生成，可手动创建基础模板
cat > ~/.openclaw/workspace/MEMORY.md << 'EOF'
# 我的永久记忆

## 基础偏好
- 输出语言：中文优先
- 技术栈偏好：TypeScript, Node.js

## 重要决策
- [待填写]
EOF

Step 2：启用向量搜索（可选增强）

如果您需要让Agent具备语义搜索能力，建议配置memorySearch启用向量搜索，支持混合检索。

通过Ollama本地运行向量模型（完全离线的部署方式） ：

# 安装 node-llama-cpp（负责本地运行嵌入模型）
npm install -g node-llama-cpp

# 下载嵌入模型（例如Qwen/Qwen3-Embedding-0.6B GGUF格式）
# 可选用各类GGUF文件，包括但不限于文中推荐的国内开源模型，只要配置路径正确即可

# 配置 OpenClaw 使用本地嵌入提供商
{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "local",
        "fallback": "none",
        "local": {
          "modelPath": "~/.node-llama-cpp/models/embeddinggemma-300m-qat-Q8_0.gguf"
        }
      }
    }
  }
}

通过云端嵌入提供商（API 服务） ：

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "openai",    // 或 gemini / ollama / mistral
        "model": "text-embedding-3-small"
      }
    }
  }
}

通过Ollama独立服务提供嵌入 ：

# 确保Ollama服务已安装并运行
curl -fsSL https://ollama.com/install.sh | sh
ollama pull nomic-embed-text

# 配置 OpenClaw
{
  "agents": {
    "defaults": {
      "memorySearch": {
        "provider": "ollama",
        "model": "nomic-embed-text"
      }
    }
  }
}

Step 3：强制重建索引

openclaw memory index --force --agent main

Step 4：验证混合搜索是否生效

通过WebUI或Telegram发送一条测试消息：“搜索我记忆中关于项目架构的讨论”。观察Agent是否返回了相关记忆（如果没有返回，请参考前序章节确认MEMORY.md中是否有足够的可检索内容，或索引是否已正确建立）。

如果返回内容相关性不足，请确认：

• MEMORY.md 或 daily log 中是否确实存在相关的语义信息
• 是否已启用正确的嵌入提供商（openclaw memory status会显示当前使用的provider）
• 重建索引后有无重启Gateway（openclaw gateway restart）

9.7 记忆扩展：集成外部向量数据库

一句话概括：OpenClaw支持通过插件体系无缝集成三种主流外部向量数据库——基于向量相似度的LanceDB（原生生态）、具备企业级读写QoS的Tablestore（阿里云托管）、以及支持图向量混合的Mem0（对象化记忆），分别应对本地开发、企业生产与复杂知识库的不同诉求。

当本地SQLite索引不再满足大规模记忆需求时（例如百万级文档的企业知识库、需要跨地域共享记忆、或要求毫秒级并发响应），OpenClaw提供了一系列向量数据库集成方案。

LanceDB：OpenClaw官方唯一的原生第三方Memory插件

LanceDB是为AI长期记忆与语义向量检索设计的开源向量数据库，专为企业级大文本嵌入向量持久化和近似最近邻查询而生。其核心优势是列式存储与零拷贝架构，可高效处理千万级向量的大规模检索，尤其适合海量对话数据、企业内部文档的索引场景。

Tablestore + Mem0：阿里云企业级托管方案

Tablestore是阿里云的全托管NoSQL数据库，通过@tablestore/openclaw-mem0插件集成，为Agent提供云端长期记忆能力。主要优势：

• 云托管免运维：Tablestore为全托管服务，无需自建和运维Vector DB集群
• 跨Agent记忆共享：同一userId下多个Agent记忆互通，上下文压缩（Compact）不影响历史记忆保留
• 混合检索召回：向量相似度与BM25关键词检索并用，毫秒级响应
• 结构化提取：自动从对话中抽取姓名、偏好、决策等关键事实，不堆积原始对话内容

自动安装方法最为简单。直接在OpenClaw对话中输入以下提示，Agent会自动读取安装说明并引导完成配置：

请阅读 tablestore-doc.oss-cn-hangzhou.aliyuncs.com/aliyun-tabl… plugin 用于 OpenClaw。安装完成后告诉我你能做什么。

⚠️ 安装提示：由于@tablestore/openclaw-mem0包含约7000个文件，Node.js的tar解压模块（默认引擎）可能触发120秒超时。官方建议使用一种绕过机制：先用npm下载插件包（npm pack @tablestore/openclaw-mem0），再用系统的tar命令解压，最后从本地路径完成安装。

AnalyticDB for MySQL + Mem0：可无限扩展的企业级大脑

对于需要大规模数据处理能力的企业用户，还可以将AnalyticDB for MySQL作为持久化记忆后端，构建可无限扩展的跨Agent长期大脑。该方案适合多设备协同共享、混合云部署、实时高效检索场景，读写响应时间达到毫秒级。

各扩展方案选择建议

场景	推荐方案	理由
本地开发/个人助理	内置SQLite	零运维，开箱即用
中小规模团队分享记忆	LanceDB	原生生态，部署灵活，无需云依赖
企业对数据管理有合规性要求	Tablestore + Mem0	阿里云全托管，跨Agent共享，免运维
大数据量高并发企业	AnalyticDB + Mem0	无限扩展，毫秒级查询，支持混合云
需要时间感知的知识图谱	Neo4j+Graphiti	实体关系建模、时间维度追溯

9.8 本节小结

本节课系统性地拆解了OpenClaw的三级记忆存储体系。我们从核心目录结构出发深刻理解了“文件即真相”的设计理念，逐步深入到SQLite+向量索引的混合存储实现。回顾核心知识点：

• 三级记忆分层：短期记忆（会话窗口）、每日日志（memory/YYYY-MM-DD.md自动加载今日+昨日）、长期记忆（MEMORY.md跨会话永久持久化）构成时间与重要性的双重维度分层，仅让最相关的记忆加载到LLM上下文，而非无限堆砌。
• Redis加速短期缓存：通过部署Redis作为内存级缓存（可选），在高频读写场景下提升系统整体响应速度，改善多实例共享和用户限流控制。
• 知识图谱扩展：通过Neo4j+Graphiti插件构建企业级长期记忆，支持实体关系建模、时间感知检索和跨Agent记忆共享。
• WAL机制：SQLite预写日志与并发检查点，确保会话状态变更——即使进程崩溃，所有已发生的会话交互也能从日志中恢复。
• 混合检索（Hybrid Search）：BM25关键词匹配 + 向量语义搜索，默认70%向量+30%全文的加权融合策略，兼顾精确命中与语义理解。
• 自动化记忆管理：自动记忆刷新（压缩前静默保存上下文）+ Dreaming（可选后台整合）——将符合条件的候选内容升迁到MEMORY.md，使长期记忆保持高信噪比。
• 外部存储器扩展：LanceDB（原生插件）、Tablestore + Mem0（阿里云全托管）、AnalyticDB + Mem0（企业级无限扩展），按需选择。

记忆系统是整个专栏的中场核心章。在此基础上，第10课将系统地剖析Skill技能系统的骨架与扩展，连接Agent的“记忆”与“行动”。当你的AI既能“记”又能“做”，它就真正具备了数字代理的完整能力——不再是“一问一答的玩具”，而是“越用越强的伙伴”。

9.9 课后习题

1. 观察你的记忆目录

在你的OpenClaw运行环境中执行ls -la ~/.openclaw/workspace/memory/，列出所有YYYY-MM-DD.md文件。选择一个文件，查看其中记录了哪些对话内容。你认为哪些内容应该被“提升”到MEMORY.md中，为什么？

2. MEMORY.md配置对比实验

创建一个新的Agent，配置一个简单的MEMORY.md（如“始终用中文简洁回答”）。在新会话中测试AI的行为是否遵守了此规则。重置会话后再测试一次，观察规则是否依然生效。

3. 混合检索性能测试

在Agent对话中手动写入以下几类记忆标记：“项目A使用React框架”、“项目B用Vue编写”、“API地址是api.example.com/v1”。之后分别用语义…

4. Dreaming机制探索

在OpenClaw配置中启用Dreaming背景记忆整合（agents.defaults.dreaming.enabled: true），观察新生成的DREAMS.md文件与MEMORY.md的区别。长期运行后统计，哪些记忆被升迁了，哪些被过滤了。

5. 扩展环境搭建

按照9.7节Tabstore自动安装的提示，尝试将Agent连接到全托管云端长期存储。注意对敏感数据脱敏（例如将包含商业机密的原始对话替换为示例测试数据）。测试“今天的对话明天能召回吗？”——观察跨Agent共享是否生效。如果连接不上，优先检查API Key权限和网络连接状态。

🔗《30节课精通 OpenClaw》系列课程导航

去订阅

第一部分（第1-5课） ：基础认知与入门部署——解决“这是什么、怎么搭建”的问题；

第二部分（第6-10课）：核心原理深度剖析——解决“底层怎么工作”的问题；

第三部分（第11-15课） ：应用场景与平台集成——解决“能用来做什么”的问题；

第四部分（第16-21课） ：技能开发与定制扩展——解决“如何自己扩能力”的问题；

第五部分（第22-26课）：高级特性与性能优化——解决“怎么用得更好”的问题；

第六部分（第27-30课） ：安全、运维与生态进阶——解决“如何安全可靠地规模化”的问题；