Mem0 OpenClaw 插件实战：为 OpenClaw Agent 构建跨会话持久记忆

本文为 OpenClaw 开发者介绍 Mem0 官方插件 @mem0/openclaw-mem0 的完整接入方案：从插件安装、Platform（Mem0 云端）与 Open-Source（自托管）两种模式的配置，到默认的 Skills 模式（triage / recall / dream）工作机制、8 个 Agent 工具、openclaw mem0 CLI 命令，以及完整的配置参考与隐私安全模型。读完后你可以独立为 OpenClaw Agent 配置一套"会话间不忘事"的长期记忆系统，并能基于源码理解记忆注入、去噪过滤与多 Agent 隔离的底层实现。

1. 它解决什么问题

OpenClaw 的 Agent 在会话之间会遗忘所有内容。该插件（插件 ID 为 openclaw-mem0，见 openclaw.plugin.json）通过 Mem0 修复这一问题：存储对话、抽取其中重要的事实，并在相关时将其重新带回到上下文里。

从源码结构看（index.ts），插件注册时一次性挂载三块能力：

• 工具层：通过 registerAllTools 注册 8 个 memory_* 工具，供 Agent 主动调用；
• CLI 层：通过 registerCliCommands 注册 openclaw mem0 <command> 命令族；
• 生命周期钩子层：根据是否启用 Skills 模式，分别注册 before_prompt_build / agent_end 钩子，实现自动召回（auto-recall）与自动捕获（auto-capture）。

插件支持两种后端：

模式	说明	所需凭据
platform（默认）	记忆抽取与检索由 Mem0 云端（api.mem0.ai）完成	MEM0_API_KEY
open-source	自托管，使用本地/自建 LLM、Embedding 与向量库	OpenAI 模式需 OPENAI_API_KEY；Ollama 模式完全本地、无需任何 Key

2. 环境要求与安装

先用 CLI 确认 OpenClaw 版本：

openclaw --version
# OpenClaw 2026.4.25 (aa36ee6)

OpenClaw 版本	插件支持情况
>= 2026.4.25	完全支持

安装插件：

openclaw plugins install @mem0/openclaw-mem0

升级插件以获取最新功能与修复：

openclaw plugins update openclaw-mem0

关键注意点：OpenClaw 的记忆类插件通过独占式 slot 加载，仅仅安装插件并不会激活它，必须在配置中把 plugins.slots.memory 设为 openclaw-mem0（下文所有配置示例均已包含这一步）。

3. 快速上手

3.1 面向 AI Agent 的快速通道

如果你是一个希望自主完成 Mem0 配置（不走人类 Dashboard 注册流程）的 AI Agent，可以用一行命令铸造一个评估用 API Key：

mem0 init --agent --json

无需邮箱、OTP 或浏览器。Key 会被写入 Mem0 CLI 配置并导出为 MEM0_API_KEY，随后将其传给 OpenClaw 的初始化命令即可完成接线：

openclaw mem0 init --api-key $MEM0_API_KEY --user-id <id>

人类所有者之后可执行 mem0 init --email <their-email> 认领所有权：记忆会随账户转移，同一个 API Key 继续有效，Agent 侧无感知。

3.2 Platform 模式（Mem0 Cloud）

1. 通过 OpenClaw CLI 安装插件（见上一节）。

2. 在 Mem0 控制台（app.mem0.ai）的 API Keys 页面创建你的 API Key。

3. 在 openclaw.json 中把插件选定为记忆后端。既可以用 CLI 初始化：

   openclaw mem0 init --api-key <your-key> --user-id <your-user-id>
   

   也可以直接手写完整配置：

   {
     "plugins": {
       "slots": {
         "memory": "openclaw-mem0"
       },
       "entries": {
         "openclaw-mem0": {
           "enabled": true,
           "config": {
             "apiKey": "${MEM0_API_KEY}",
             "userId": "alice",
             "skills": {
               "triage": { "enabled": true },
               "recall": {
                 "enabled": true,
                 "tokenBudget": 1500,
                 "rerank": true,
                 "keywordSearch": true,
                 "identityAlwaysInclude": true
               },
               "dream": { "enabled": true },
               "domain": "companion"
             }
           }
         }
       }
     }
   }
   

配置解析逻辑在 config.ts 中：未知 mode 值会回落到 "platform"；autoCapture / autoRecall 默认均为 true（cfg.autoCapture !== false）；userId 未配置时回落到操作系统用户名；searchThreshold 默认 0.1，topK 默认 5。注意 ${VAR} 语法由 OpenClaw 网关在把 pluginConfig 交给 register() 之前展开，插件自身不做变量替换（见 config.ts 的注释）。

3.3 Open-Source 模式（自托管）

无需任何 Mem0 Key。向量默认存于本地 SQLite 文件 ~/.mem0/vector_store.db，不依赖外部数据库。默认配置：Embedding 用 OpenAI text-embedding-3-small，事实抽取 LLM 用 OpenAI gpt-5-mini（需要 OPENAI_API_KEY）；若要完全本地化，可把 LLM 与 Embedding 都换成 Ollama。

交互式向导（推荐）

运行 4 步引导式向导：

openclaw mem0 init --mode open-source

向导依次询问：

1. LLM 提供商 — OpenAI（gpt-5-mini）、Ollama（llama3.1:8b，本地）或 Anthropic（claude-sonnet-4-5-20250514）
2. Embedding 提供商 — OpenAI（text-embedding-3-small）或 Ollama（nomic-embed-text，本地）
3. 向量库 — Qdrant（http://localhost:6333）或 PGVector（PostgreSQL）
4. User ID — 你的记忆命名空间标识

每一步在继续之前都会先做连通性测试（Ollama、Qdrant、PGVector）。

非交互式配置

面向 CI/CD、脚本或 Agent 驱动场景，把所有选项作为 flag 传入：

# 全本地：Ollama + Qdrant
openclaw mem0 init --mode open-source \
  --oss-llm ollama --oss-embedder ollama --oss-vector qdrant

# OpenAI + Qdrant
openclaw mem0 init --mode open-source \
  --oss-llm openai --oss-llm-key <key> \
  --oss-embedder openai --oss-embedder-key <key> \
  --oss-vector qdrant

# Anthropic LLM + OpenAI Embedding + PGVector
openclaw mem0 init --mode open-source \
  --oss-llm anthropic --oss-llm-key <key> \
  --oss-embedder openai --oss-embedder-key <key> \
  --oss-vector pgvector --oss-vector-user postgres --oss-vector-password secret

# JSON 输出（面向 LLM Agent）
openclaw mem0 init --mode open-source --oss-llm ollama --oss-embedder ollama --oss-vector qdrant --json

完整 --oss-* flag 一览：

Flag	说明
--oss-llm <provider>	openai、ollama 或 anthropic
--oss-llm-key <key>	LLM 提供商 API Key
--oss-llm-model <model>	覆盖默认 LLM 模型
--oss-llm-url <url>	Base URL（仅 Ollama）
--oss-embedder <provider>	openai 或 ollama
--oss-embedder-key <key>	Embedding 提供商 API Key
--oss-embedder-model <model>	覆盖默认 Embedding 模型
--oss-embedder-url <url>	Base URL（仅 Ollama）
--oss-vector <provider>	qdrant 或 pgvector
--oss-vector-url <url>	Qdrant 服务地址（默认 http://localhost:6333）
--oss-vector-host <host>	PGVector 主机
--oss-vector-port <port>	PGVector 端口
--oss-vector-user <user>	PGVector 用户
--oss-vector-password <pw>	PGVector 密码
--oss-vector-dbname <db>	PGVector 数据库名
--oss-vector-dims <n>	覆盖 Embedding 维度

手工写配置

最小配置（使用 OpenAI 默认值）：

{
  "plugins": {
    "slots": {
      "memory": "openclaw-mem0"
    },
    "entries": {
      "openclaw-mem0": {
        "enabled": true,
        "config": {
          "mode": "open-source",
          "userId": "alice"
        }
      }
    }
  }
}

通过 oss 块自定义 Embedding、向量库或 LLM：

"config": {
  "mode": "open-source",
  "userId": "alice",
  "oss": {
    "embedder": { "provider": "openai", "config": { "model": "text-embedding-3-small" } },
    "vectorStore": { "provider": "qdrant", "config": { "url": "http://localhost:6333" } },
    "llm": { "provider": "openai", "config": { "model": "gpt-5-mini" } }
  }
}

oss 下所有字段均可选。configSchema 定义了 oss.embedder、oss.vectorStore、oss.llm（各含 provider + config）、oss.historyDbPath 与 oss.disableHistory。在子提供商配置中填 API Key 时，建议使用 SecretRef 对象或 ${VAR} 语法而不是明文。

4. 工作机制（How It Works）

4.1 Skills 模式（默认）

openclaw mem0 init 会自动启用 Skills 模式：由 Agent 通过三个技能控制记忆的写入（triage）、召回（recall）与定期清理（dream），对应的协议文档分别位于 skills/memory-triage/SKILL.md、skills/memory-triage/recall-protocol.md 和 skills/memory-dream/SKILL.md。

• Triage（分诊） — 用结构化协议从对话中抽取持久事实。类别、重要性门槛与领域叠加（domain overlay）共同决定什么值得存。协议文档定义了"四道决策门"（未来效用、新颖性、事实性、安全性），核心问题是："一个没有任何上下文的新 Agent，知道这条信息是否有益？"多数回合应当零写入，这是正常且预期的。
• Recall（召回） — 每个回合之前，把用户消息改写为搜索查询，带重排地检索相关记忆并注入上下文。
• Dream（梦境巩固） — 周期性记忆巩固：合并重复、解决冲突、修剪过期条目。

Skills 模式激活时，内置的 session-memory hook 会被禁用以避免冲突；autoRecall 与 autoCapture 在 init 后仍默认为 true，与 Skills 模式并存。

从源码看 Skills 模式的实际执行路径（index.ts）：

1. 插件在 before_prompt_build 钩子中把静态协议文本放进 prependSystemContext（可被提供商缓存，无每回合成本），把动态召回结果放进 prependContext（每回合变化）；
2. recall.strategy 控制自动搜索强度：always（每回合长期 + 会话双搜索）、smart（仅长期搜索，默认）、manual（不自动召回，Agent 用 memory_search 全权控制）；
3. 非交互触发（cron、heartbeat、automation，见 isolation.ts）与系统引导提示词会被跳过，避免污染记忆。

召回引擎的核心实现是 recall.ts，它并非简单的"把搜索结果全倒出来"，而是：阈值过滤（默认 0.4）→ 按类别优先级排序（identity、configuration、rule 优先，见 DEFAULT_CATEGORY_ORDER）→ 重要性次排序 → 相关性分数末排序 → Token 预算控制（默认 1500 tokens，按约 4 字符/token 估算）→ 按类别分组格式化注入。其中 identityAlwaysInclude（默认开）会让 identity / configuration 类记忆绕过预算检查始终注入。

自动 Dream 也有门控（index.ts）：先做廉价的本地文件检查（checkCheapGates：时间、会话数门槛），通过后才调用 API 检查记忆数量门槛，再加锁触发；在 agent_end 时校验模型是否真正执行了写工具（memory_add / memory_update / memory_delete），没有写操作则释放锁并在后续合格回合重试。

4.2 Auto-Recall 与 Auto-Capture（Skills 之外的兜底）

未配置 Skills 时，插件走传统的自动召回/自动捕获双钩子：

• Auto-Recall — Agent 响应前，插件搜索 Mem0 中相关记忆并注入上下文。源码中的实现细节包括：召回超时 8 秒保护（超时即跳过、不阻塞对话）、动态阈值过滤（丢弃分数低于最高分 50% 的长尾弱匹配）、新会话冷启动时对短提示词追加一次宽泛搜索（"recent decisions, preferences, active projects, and configuration"）。
• Auto-Capture — Agent 响应后，对话经过一条去噪管线（实现在 filtering.ts，会整条丢弃心跳、纯 JSON 消息、"ok/sure/done" 类应答、时间戳与工具调用噪音，并剥离 TUI 注入的 Sender 元数据）后发送给 Mem0；新事实被存储、过期事实被更新、重复被合并。

去噪之外的两个防重复机制值得注意：如果 Agent 在本回合已经显式调用了 memory_add / memory_update / memory_delete，自动捕获会跳过，避免双重写入（index.ts）；subagent 会话的捕获也被跳过（其临时 UUID 命名空间只写不读，由主 Agent 捕获合并后的结果）。

可以通过 autoRecall: false 或 autoCapture: false 分别关闭二者。无论这些开关如何，Agent 都可以显式调用记忆工具（memory_add、memory_search 等）。

4.3 记忆作用域

• Session（短期） — 通过 run_id 绑定到当前对话，召回时与长期记忆一并返回；
• User（长期） — 跨所有会话持久保存，是 memory_add 的默认作用域。

4.4 多 Agent 隔离

每个 Agent 自动获得独立的记忆命名空间：会话键路由把 agent:<name>:<uuid> 映射为 userId:agent:<name>，单 Agent 部署完全不受影响。这一逻辑集中在 isolation.ts 的 extractAgentId / effectiveUserId / resolveUserId 三个纯函数中，工具参数中显式的 agentId 优先级最高。

5. Agent 工具清单

插件为 Agent 注册 8 个工具（在 openclaw.plugin.json 的 contracts 中声明）：

工具	说明
memory_search	自然语言查询搜索。支持 scope（session、long-term、all）、categories、filters、agentId
memory_add	存储事实。接受 text 或 facts 数组、category、importance、longTerm、metadata
memory_get	按 ID 获取单条记忆
memory_list	列出所有记忆。可按 userId、agentId、scope 过滤
memory_update	原地更新记忆文本，保留编辑历史
memory_delete	按 memoryId、query（搜后删）或 all: true（需 confirm: true）删除
memory_event_list	列出近期后台处理事件。仅 Platform 模式
memory_event_status	按 ID 查询特定事件状态。仅 Platform 模式

各工具的参数细节（含 memory_add 支持的 8 个类别 identity / preference / decision / rule / project / configuration / technical / relationship）在 skills/memory-triage/SKILL.md 中有完整定义。

6. CLI 命令

所有命令形如 openclaw mem0 <command>，且全部支持 --json 机器可读输出（面向 LLM Agent）：

# 记忆操作
openclaw mem0 add "User prefers TypeScript over JavaScript"
openclaw mem0 search "what languages does the user know"
openclaw mem0 search "preferences" --scope long-term
openclaw mem0 get <memory_id>
openclaw mem0 list --user-id alice --top-k 20
openclaw mem0 update <memory_id> "Updated preference text"
openclaw mem0 delete <memory_id>
openclaw mem0 delete --all --user-id alice --confirm
openclaw mem0 import memories.json

# 管理
openclaw mem0 init                                          # 交互式配置
openclaw mem0 init --mode open-source --oss-llm ollama      # 非交互式 OSS
openclaw mem0 init --api-key <key> --user-id alice          # 非交互式 platform
openclaw mem0 status
openclaw mem0 config show
openclaw mem0 config get api_key
openclaw mem0 config set user_id alice

# 事件（仅 Platform 模式）
openclaw mem0 event list
openclaw mem0 event status <event_id>

# 记忆巩固
openclaw mem0 dream
openclaw mem0 dream --dry-run

# JSON 输出（任意命令）
openclaw mem0 search "preferences" --json
openclaw mem0 list --json
openclaw mem0 status --json
openclaw mem0 help --json                                   # 发现全部命令与 flag

一个便利的设计：即使尚未配置 API Key，插件也会注册 CLI 并仅让 init 子命令可用（index.ts），从而保证 openclaw mem0 init 始终可以作为引导配置的入口，而不是遇到"无凭据即整体不可用"的死局。

7. 配置参考

7.1 通用项

键	类型	默认值	说明
mode	"platform" | "open-source"	"platform"	后端模式
userId	string	OS 用户名	用户标识，所有记忆都按此值作用域化
autoRecall	boolean	true	每回合前注入相关记忆；设置 skills 时被忽略
autoCapture	boolean	true	每回合后抽取并存储事实；设置 skills 时被忽略
topK	number	5	每次召回返回的最大记忆数
searchThreshold	number	0.1	最低相似度分数（0-1）

7.2 Skills 模式（推荐）

openclaw mem0 init 期间默认启用；autoRecall 与 autoCapture 同时默认为 true，与 Skills 模式并存。

键	类型	默认值	说明
skills.triage.enabled	boolean	true	启用从对话中抽取事实
skills.recall.enabled	boolean	true	启用每回合前记忆召回
skills.recall.tokenBudget	number	1500	注入记忆的最大 token 数
skills.recall.rerank	boolean	true	对搜索结果做相关性重排
skills.recall.keywordSearch	boolean	true	附加关键词搜索
skills.recall.identityAlwaysInclude	boolean	true	identity 记忆始终包含
skills.dream.enabled	boolean	true	启用周期性记忆巩固
skills.domain	string	"companion"	triage 规则的领域叠加

configSchema 中还定义了若干进阶项：skills.recall.strategy（always / smart / manual）、skills.recall.maxMemories（源码默认 15）、skills.recall.threshold（源码默认 0.4）、skills.recall.categoryOrder（类别排序，源码默认 identity/configuration/rule 优先）、skills.dream.auto / minHours / minSessions / minMemories（自动 dream 门槛）、skills.triage.importanceThreshold / credentialPatterns 以及 skills.customRules.include/exclude。

7.3 Platform 模式

键	类型	默认值	说明
apiKey	string	—	必填。 Mem0 API Key（支持 ${MEM0_API_KEY}）
customInstructions	string	(内置)	自定义抽取规则
customCategories	object	(12 个默认)	类别名到描述文本的映射

内置的默认抽取指令与 12 个默认类别（identity、preferences、goals、projects、technical、decisions、relationships、routines、life_events、lessons、work、health）都定义在 config.ts。默认指令要求：以"新 Agent 是否受益"为判断标准、时间敏感事实必须带 "As of YYYY-MM-DD" 时间锚点、以第三人称书写、"记结果而非意图"、永不存储密码 / API Key / Token（只记录"凭据已配置"这一事实）、保留对话原始语言。

7.4 Open-Source 模式

所有字段均可选。默认值：text-embedding-3-small Embedding、本地 SQLite 向量库（~/.mem0/vector_store.db）、gpt-5-mini LLM。

键	类型	默认值	说明
customPrompt	string	(内置)	抽取提示词
oss.embedder.provider	string	"openai"	Embedding 提供商
oss.embedder.config	object	—	提供商配置（apiKey、model、baseURL）
oss.vectorStore.provider	string	"memory"	向量库提供商
oss.vectorStore.config	object	—	提供商配置（host、port、collectionName、dbPath）
oss.llm.provider	string	"openai"	LLM 提供商
oss.llm.config	object	—	提供商配置（apiKey、model、baseURL）
oss.historyDbPath	string	—	编辑历史的 SQLite 路径

8. 隐私与安全

8.1 数据流向

模式	数据去向	所需凭据
Platform	对话内容发送到 api.mem0.ai 做记忆抽取与检索	MEM0_API_KEY
Open-Source（OpenAI）	LLM/Embedding 调用走 OpenAI API；向量存于本地 ~/.mem0/vector_store.db	OPENAI_API_KEY
Open-Source（Ollama）	完全本地 — LLM、Embedding 与向量全部在本机	无

8.2 凭据存储

插件配置存放在 ~/.openclaw/openclaw.json。使用聊天配置流程或 openclaw mem0 init 时，API Key 与 user ID 会写入该文件。为避免明文凭据，二选一：

• 环境变量引用："apiKey": "${MEM0_API_KEY}"
• SecretRef："apiKey": {"source": "env", "provider": "default", "id": "MEM0_API_KEY"}

openclaw.plugin.json 中 apiKey、userEmail 及所有 oss.*.apiKey 字段都标记为 sensitive，并给出同样的 SecretRef 提示。

8.3 记忆处理路径

Skills 模式（openclaw mem0 init 后的默认）下，Agent 通过 triage、recall、dream 结构化协议决定存什么、取什么，内置 session-memory hook 被禁用以避免冲突。未启用 Skills 时，autoCapture 与 autoRecall 默认均开启：前者在每回合结束后把（经去噪的）对话内容发到所配置的后端，后者在每回合响应前查询记忆库并把结果注入上下文。Platform 模式下对话内容会发送到 api.mem0.ai 处理 —— 如果你的数据不愿存放在 Mem0 云端，请勿使用 Platform 模式。

8.4 持久化位置一览

文件	用途
~/.openclaw/openclaw.json	插件配置（API Key、user ID、设置项）
~/.mem0/vector_store.db	本地向量库（仅 Open-Source 模式）
~/.mem0/history.db	记忆编辑历史（仅 Open-Source 模式）
<pluginStateDir>/dream-state.json	记忆巩固（dream）状态

9. 小结

@mem0/openclaw-mem0 把 Mem0 的记忆能力完整接入了 OpenClaw 的插件体系：Platform 模式一行 init 即可用，Open-Source 模式可以用 Ollama + Qdrant 做到零外部依赖、全本地运行。默认开启的 Skills 模式让 Agent 以"四道门分诊 + Token 预算召回 + 定期梦境巩固"的结构化协议管理自己的记忆，而 8 个 memory_* 工具、全量 --json CLI 与多 Agent 自动命名空间隔离则保证了人工与自动化运维两条路径都可执行。若要深入某个环节，建议按此顺序阅读仓库源码：config.ts（配置解析与默认抽取规则）→ index.ts（钩子注册与双模式分叉）→ recall.ts（召回排序与预算）→ isolation.ts（命名空间路由）→ filtering.ts（去噪管线），并配合 tests/ 目录下的对应测试用例验证行为。插件以 Apache 2.0 协议发布（LICENSE）。