快速开始

1. 安装 SDK

Python 3.10 或更高版本。在 MetaMemory 项目根目录执行：

python -m pip install ./src/cloud/sdk/metamem

2. 初始化客户端

将项目组件 Key 写入环境变量：

export METAMEM_API_KEY="你的项目组件Key"

import os
from metamem import Client

client = Client(
    api_key=os.environ["METAMEM_API_KEY"],
    base_url="https://metamemory.8-163-122-236.nip.io",
)

3. 保存记忆

messages = [
    {"role": "user", "content": "我在广州工作，喜欢周末去帆船俱乐部。"},
    {"role": "assistant", "content": "我记住你的工作城市和周末爱好了。"},
]

result = client.add(
    messages,
    user_id="user-001",
    memory_component="mem0_platform",
)
print(result)

4. 检索记忆

results = client.search(
    "我在哪个城市工作？周末喜欢做什么？",
    filters={"user_id": "user-001"},
    memory_component="mem0_platform",
)
print(results)

将检索得到的记忆加入宿主智能体的模型上下文。宿主插件负责自动捕获和检索注入时，继续使用宿主的对话入口。

add：保存记忆

使用 metamem SDK 调用；memory_component 选择组件，服务地址填写纯域名。

初始化客户端

from metamem import Client

client = Client(
    api_key="你的项目组件Key",
    base_url="https://metamemory.8-163-122-236.nip.io",
)

消息

messages = [{"role": "user", "content": "我在广州工作。"}]

调用示例

result = client.add(
    messages,
    user_id="user-001",
    metadata={"source": "conversation"},
    memory_component="hindsight",
)

返回后端写入结果。异步写入保留事件或任务标识，完成后再检索；记忆 ID 用于后续管理。

search：检索记忆

使用 metamem SDK 调用；memory_component 选择组件，服务地址填写纯域名。

初始化客户端

from metamem import Client

client = Client(
    api_key="你的项目组件Key",
    base_url="https://metamemory.8-163-122-236.nip.io",
)

调用示例

results = client.search(
    "我的周末爱好是什么？",
    filters={"user_id": "user-001"},
    top_k=5,
    memory_component="hindsight",
)

从返回的 results 读取记忆条目。

get：读取单条记忆

使用 metamem SDK 调用；memory_component 选择组件，服务地址填写纯域名。

初始化客户端

from metamem import Client

client = Client(
    api_key="你的项目组件Key",
    base_url="https://metamemory.8-163-122-236.nip.io",
)

memory_id 填写该组件保存结果或列表中的实际记忆 ID。

调用示例

memory_id 使用保存结果或列表中的实际记忆 ID。

memory = client.get(memory_id, memory_component="hindsight")

get_all：列出记忆

使用 metamem SDK 调用；memory_component 选择组件，服务地址填写纯域名。

初始化客户端

from metamem import Client

client = Client(
    api_key="你的项目组件Key",
    base_url="https://metamemory.8-163-122-236.nip.io",
)

调用示例

memories = client.get_all(
    filters={"user_id": "user-001"},
    page=1,
    page_size=100,
    memory_component="hindsight",
)

按返回的分页信息继续获取后续页。

update：更新记忆

使用 metamem SDK 调用；memory_component 选择组件，服务地址填写纯域名。

初始化客户端

from metamem import Client

client = Client(
    api_key="你的项目组件Key",
    base_url="https://metamemory.8-163-122-236.nip.io",
)

memory_id 填写该组件保存结果或列表中的实际记忆 ID。

调用示例

result = client.update(
    memory_id,
    text="我现在在深圳工作。",
    memory_component="hindsight",
)

如果结果包含 replacement_memory_id，后续操作使用该新 ID。

delete：删除单条记忆

使用 metamem SDK 调用；memory_component 选择组件，服务地址填写纯域名。

初始化客户端

from metamem import Client

client = Client(
    api_key="你的项目组件Key",
    base_url="https://metamemory.8-163-122-236.nip.io",
)

memory_id 填写该组件保存结果或列表中的实际记忆 ID。

调用示例

result = client.delete(memory_id, memory_component="hindsight")

delete_all：删除用户范围内的记忆

使用 metamem SDK 调用；memory_component 选择组件，服务地址填写纯域名。

初始化客户端

from metamem import Client

client = Client(
    api_key="你的项目组件Key",
    base_url="https://metamemory.8-163-122-236.nip.io",
)

调用示例

result = client.delete_all(
    user_id="user-001",
    memory_component="hindsight",
)

history：查询变更历史

使用 metamem SDK 调用；memory_component 选择组件，服务地址填写纯域名。

初始化客户端

from metamem import Client

client = Client(
    api_key="你的项目组件Key",
    base_url="https://metamemory.8-163-122-236.nip.io",
)

memory_id 填写该组件保存结果或列表中的实际记忆 ID。

调用示例

changes = client.history(memory_id, memory_component="hindsight")

review 仅用于 MetaMemory 复盘，不属于统一 AML Add/Search，也不会对默认 Jev-Mem 或其他组件执行。

result = client.review(user_id="user-1", session_ids=["conversation-1", "conversation-2"])

必填：user_id 与非空、不重复的 session_ids 列表；可选 request_id。按所选会话逐个复盘，返回各会话结果。

Agent Plugins

为各宿主智能体提供跨会话记忆。选择对应宿主的安装指南。

宿主插件

配置

使用 MetaMemory 账号的组件 Key。SDK 服务地址为 https://metamemory.8-163-122-236.nip.io。METAMEM_MEMORY_COMPONENT 选择记忆组件，默认 mem0_platform。

记忆读写、管理与导入统一经过 MetaMemory。组件特有函数通过扩展接口调用；底层组件地址与凭据由服务端管理。

安装方式

完整插件提供宿主原生工具、技能和自动捕获／召回。独立 MCP 提供远程记忆工具，通过浏览器授权或组件 Key 登录。

• Claude Code
• Codex
• OpenCode
• OpenClaw
• Pi Agent
• DeepSeek Harness
• Hermes Agent
• MetaMemory MCP

Codex

为 Codex 提供自动捕获、自动召回、搜索工具和六个记忆技能。

前置条件

• MetaMemory 账号与组件 Key。
• 支持插件和 MCP 的 Codex。
• Python 3.10+。

export METAMEM_API_KEY="你的MetaMemory组件Key"
export METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io"
export METAMEM_MEMORY_COMPONENT="mem0_platform"

安装

方式 A：插件市场（推荐）

codex plugin marketplace add FoxTamingPrince/metamemory-agent-plugins
codex plugin add metamem@metamem-plugins

也可以添加市场后，在应用的插件目录中选择 MetaMemory Plugins 并安装 metamem。新建会话使插件生效。

方式 B：直接 MCP

codex mcp add metamem --url https://metamemory.8-163-122-236.nip.io/mcp/ --bearer-token-env-var METAMEM_API_KEY

或编辑 ~/.codex/config.toml：

[mcp_servers.metamem]
url = "https://metamemory.8-163-122-236.nip.io/mcp/"
bearer_token_env_var = "METAMEM_API_KEY"

两种方式择一安装，避免重复注册。直接 MCP 提供远程工具；完整插件包含技能与生命周期钩子。

管理插件

codex plugin marketplace upgrade
codex plugin remove metamem@metamem-plugins
codex plugin marketplace remove metamem-plugins

包含的功能

直接 MCP 工具

生命周期钩子

技能

search、status、remember、forget、pause、resume。

使用流程

1. 在项目中讨论架构选择，并完成相关代码工作。
2. 插件记录本轮完成的交互，后台提取项目事实和个人偏好。
3. 新建会话并继续同一项目，首次有效提示召回相关记忆。
4. 使用搜索技能主动查询，使用 remember 技能明确保存约定。

子智能体

Codex 使用原生子智能体。项目中的 .codex/agents 定义仍由 Codex 管理；插件记录子智能体开始、结束及完成结果。主会话继续负责检查并整合结果。

Codex Cloud

云端会话使用远程 MCP 连接。在 Cloud 环境的环境变量中设置 METAMEM_API_KEY，使设置阶段与智能体阶段均可读取。只配置为 Secret 的值在设置结束后会移除，不能用于后续智能体的 MCP 请求。

完整插件与远程 MCP 是两种安装方式：完整插件提供本地捕获、技能和钩子；远程 MCP 提供记忆工具。

MetaMemory MCP

通过 HTTPS 将记忆工具接入支持 MCP 的客户端。

前置条件

MetaMemory 账号；支持 Streamable HTTP 的 MCP 客户端。

快速安装

npx mcp-add --name metamem-mcp --type http --url "https://metamemory.8-163-122-236.nip.io/mcp" --clients "claude code,cursor,windsurf,vscode,opencode"

选择自己使用的客户端，重新启动使配置生效。

登录

方式 1：浏览器登录

客户端打开 MetaMemory 登录页面。填写邮箱和验证码，并确认授权。

方式 2：API Key

通过 Authorization: Bearer <组件Key> 连接。支持 Token 写法。

可用工具

客户端配置

Claude Desktop

在 Settings → Connectors 中添加自定义连接，URL 填写 https://metamemory.8-163-122-236.nip.io/mcp，随后完成浏览器授权。

Claude Code

npx mcp-add --name metamem-mcp --type http --url "https://metamemory.8-163-122-236.nip.io/mcp" --clients "claude code"

Codex

[mcp_servers.metamem]
url = "https://metamemory.8-163-122-236.nip.io/mcp"
bearer_token_env_var = "METAMEM_API_KEY"

OpenCode

{"mcp":{"metamem":{"type":"remote","url":"https://metamemory.8-163-122-236.nip.io/mcp","oauth":true}}}

选择记忆组件

默认 mem0_platform。自定义连接使用 X-Metamem-Memory-Component 请求头，或在 MCP URL 中设置 ?memory_component=hindsight。SDK 的服务域名保持不变。

Claude Code

为 Claude Code 提供跨会话记忆、自动捕获、自动召回、搜索工具和记忆命令。

前置条件

• MetaMemory 账号与组件 Key。
• 支持插件、子智能体和 worktree 的 Claude Code。
• Python 3.10+、Git。

快速开始

export METAMEM_API_KEY="你的MetaMemory组件Key"
export METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io"
export METAMEM_MEMORY_COMPONENT="mem0_platform"

claude plugin marketplace add FoxTamingPrince/metamemory-agent-plugins
claude plugin install metamem@metamem-plugins --scope user --config api_key="$METAMEM_API_KEY"

重新启动 Claude Code，或运行 /reload-plugins，然后进入 Git 仓库开始工作。

管理插件

claude plugin marketplace update metamem-plugins
claude plugin update metamem@metamem-plugins --scope user
claude plugin uninstall metamem@metamem-plugins

使用方式

自动记忆

钩子在本地记录用户消息、回答及工具结果，后台批量提取记忆；新会话的首次有效提示触发召回。

命令

搜索工具

search_memories 用于会话内显式查询。将问题作为查询文本，按项目或个人范围读取结果。

Sidekick 智能体

metamem:sidekick 在独立 worktree 中执行任务，继承父会话召回的记忆。查看结果后，将需要的改动合入当前工作区。

工作原理

本地捕获 → 后台提取 → 下一会话召回。结束会话或压缩上下文时提交剩余捕获。

记忆范围

搜索范围

repo 搜索整个仓库；dir 聚焦当前目录；mine 聚焦个人记忆。

配置

使用 METAMEM_MEMORY_COMPONENT 选择记忆后端。search_scope 可通过 MEM0_CODE_SEARCH_SCOPE 设置。个人身份依次读取插件设置、MEM0_CODE_USER_ID、MEM0_USER_ID、MEM0_RESOLVED_USER_ID、USER、USERNAME，最后使用默认身份。

存储与发送的数据

捕获保存在本地；提取请求发往配置的 MetaMemory 服务。发送前按插件规则脱敏，用户消息与智能体回答保留各自角色。

自动捕获与召回

用户陈述与智能体建议保留各自角色。项目记忆使用 agent_id 与 app_id，个人记忆使用 user_id 与 app_id；run_id 用于显式会话筛选。

搜索与删除示例

/metamem:search 我们为什么选 PostgreSQL --scope repo --top-k 5
/metamem:search 我的代码风格偏好 --scope mine
/metamem:remember 本项目的数据库迁移必须支持回滚
/metamem:forget 旧数据库约定

删除共享项目记忆时，显式添加 --include-project-memory。

Sidekick 工作流程

1. 将独立任务交给 metamem:sidekick。
2. Sidekick 在独立 worktree 中工作，并继承父会话召回的记忆。
3. 主会话查看完成结果，决定如何合入改动。

默认 worktree 基于主分支；配置 worktree.baseRef=head 可从当前提交创建。未提交的本地改动不会复制到新 worktree。

遥测

设置 MEM0_TELEMETRY=false 关闭遥测。原生遥测记录钩子、版本、系统信息、耗时与状态；仓库和会话标识经过加盐哈希，凭据会被脱敏。

OpenCode

为 OpenCode 提供原生记忆工具、生命周期钩子与技能。

前置条件

MetaMemory 账号、组件 Key 和 OpenCode。

export METAMEM_API_KEY="你的MetaMemory组件Key"
export METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io"
export METAMEM_MEMORY_COMPONENT="mem0_platform"

安装

方式 A：安装插件（推荐）

git clone https://github.com/FoxTamingPrince/metamemory-agent-plugins.git metamem-agent-plugins

opencode plugin ./metamem-agent-plugins/integrations/opencode-plugin

重新启动 OpenCode。插件自动登记原生工具、钩子与 /mem0-* 命令。

方式 B：独立 MCP

在项目或全局 opencode.json 中添加：

{
  "mcp": {
    "metamem": {
      "type": "remote",
      "url": "https://metamemory.8-163-122-236.nip.io/mcp/",
      "headers": {"Authorization": "Token {env:METAMEM_API_KEY}"},
      "oauth": false
    }
  }
}

包含的功能

可用记忆工具

add_memory、search_memories、get_memories、get_memory、update_memory、delete_memory、delete_all_memories、delete_entities、list_entities、get_event_status。

记忆范围

通过 /mem0-scope 切换范围；/mem0-context-loader 载入上下文。全局删除要求显式指定全局范围。

命令

生命周期钩子

范围参数

项目身份优先从 Git remote 取得，随后使用仓库根目录或工作目录。/mem0-scope 将选择保存到 ~/.mem0/settings.json 的 default_scope；每次操作读取配置，无须重启。

全局范围由用户通过 /mem0-scope global 明确选择。全局删除仍需显式指定 scope: "global"。

自动捕获规则

会话开始及用户提示时执行召回。每第三条符合条件的用户提示触发自动捕获，保留脱敏后的完整用户文本。自动写入将会话标识存入 metadata.session_id；显式 session 工具通过 run_id 隔离。

OpenClaw

为 OpenClaw 提供长期记忆、技能提取、自动召回和显式记忆工具。

概览

插件通过 triage 选择需要保存的事实，回答前召回相关记忆。autoRecall、autoCapture 与技能模式可分别配置。

前置条件

OpenClaw 2026.4.25 或更高版本；MetaMemory 账号。

安装

在任意 OpenClaw 聊天入口发送：

Setup MetaMemory from https://metamemory.8-163-122-236.nip.io/claw-setup

配置

userId

使用稳定的个人身份，例如 alice。跨会话使用相同身份。

平台模式

方式 1：聊天安装（推荐）

1. 发送上面的安装指令。
2. 提供邮箱。
3. 提供邮件中的六位验证码。
4. 插件保存账号组件 Key、用户 ID 与技能配置。

方式 2：手动配置

git clone https://github.com/FoxTamingPrince/metamemory-agent-plugins.git metamem-agent-plugins

openclaw plugins install ./metamem-agent-plugins/integrations/openclaw-plugin

在 openclaw.json 中配置：

{
  "plugins": {
    "slots": {"memory": "metamem"},
    "entries": {
      "metamem": {
        "enabled": true,
        "config": {
          "mode": "platform",
          "apiKey": "你的MetaMemory组件Key",
          "userId": "alice",
          "baseUrl": "https://metamemory.8-163-122-236.nip.io",
          "autoRecall": true,
          "autoCapture": true,
          "skills": {
            "triage": {"enabled": true},
            "recall": {"enabled": true}
          }
        }
      }
    }
  }
}

开源模式

方式 1：交互配置

openclaw mem0 init --mode open-source

依次选择模型、embedding、向量库和用户 ID。

方式 2：非交互配置

openclaw mem0 init --mode open-source --oss-llm ollama --oss-embedder ollama --oss-vector qdrant

方式 3：手动配置

在 openclaw.json 中配置原生本地依赖：

{
  "plugins": {
    "slots": {"memory": "metamem"},
    "entries": {
      "metamem": {
        "enabled": true,
        "config": {
          "mode": "open-source",
          "userId": "alice",
          "oss": {
            "llm": {
              "provider": "ollama",
              "config": {"model": "llama3.1:8b", "baseURL": "http://localhost:11434"}
            },
            "embedder": {
              "provider": "ollama",
              "config": {"model": "nomic-embed-text", "baseURL": "http://localhost:11434"}
            },
            "vectorStore": {
              "provider": "qdrant",
              "config": {"host": "localhost", "port": 6333, "collectionName": "metamem"}
            }
          }
        }
      }
    }
  }
}

平台后端选择使用 METAMEM_MEMORY_COMPONENT。

短期与长期记忆

session 表示会话记忆；long-term 表示跨会话记忆；all 同时查询两者。

智能体工具

插件管理

使用 openclaw plugins 管理安装、启用与移除；通过 openclaw mem0 status 查看记忆连接。

隐私与安全

平台模式向 MetaMemory 服务发送记忆操作。本地模式使用配置的模型与向量库。凭据保存在宿主配置中。

配置选项

平台配置使用 apiKey、customInstructions、customCategories。原生开源配置使用 oss.embedder、oss.vectorStore、oss.llm 和 historyDbPath。

CLI 命令

openclaw mem0 add "项目使用 PostgreSQL"
openclaw mem0 search "项目数据库" --scope long-term
openclaw mem0 get <memory_id>
openclaw mem0 list --user-id alice --top-k 20
openclaw mem0 update <memory_id> "项目使用 PostgreSQL 17"
openclaw mem0 delete <memory_id>
openclaw mem0 delete --all --user-id alice --confirm
openclaw mem0 import memories.json
openclaw mem0 config show
openclaw mem0 config get api_key
openclaw mem0 config set user_id alice
openclaw mem0 event list
openclaw mem0 event status <event_id>
openclaw mem0 status

命令支持 --json 输出。升级插件使用 openclaw plugins update metamem。

开源初始化参数

openclaw mem0 init --mode open-source --oss-llm ollama

原生开源模式直接使用所配置的模型与向量库。通过 MetaMemory 选择十一种后端时，使用平台模式与 METAMEM_MEMORY_COMPONENT。

Pi Agent

为 Pi Agent 提供自动捕获、语义召回、仓库范围管理与确认对话框。

概览

每轮对话前读取相关记忆，结束后捕获需要保存的信息。项目身份使用 Git 仓库根目录。

前置条件

Pi Agent、MetaMemory 账号与组件 Key。

export METAMEM_API_KEY="你的MetaMemory组件Key"
export METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io"
export METAMEM_MEMORY_COMPONENT="mem0_platform"

安装

git clone https://github.com/FoxTamingPrince/metamemory-agent-plugins.git metamem-agent-plugins

pi install ./metamem-agent-plugins/integrations/pi-agent-plugin

新建 Pi 会话，运行 /mem0-status。

可选配置

在 ~/.pi/agent/mem0-config.json 配置：

{
  "apiKey": "你的MetaMemory组件Key",
  "userId": "alice",
  "autoCapture": true,
  "defaultScope": "project",
  "searchThreshold": 0.3
}

包含的功能

命令

记忆范围

project 为当前仓库；session 为当前会话；global 为当前用户。删除操作通过 Pi 原生对话框确认。

自动召回与捕获

自动召回服务当前问题；显式工具支持再次搜索。autoCapture 控制完成回合后的捕获。

配置默认值

工具参数

返回内容最多为 200 行或 50 KB。写入和删除需要 Pi 原生确认，取消确认不会修改记忆。

命令参数

自动召回与捕获始终使用项目范围。显式工具使用选择的范围；全局范围由用户通过命令或配置开启。自动捕获不写入顶层 run_id，会话范围工具只查询显式按该会话保存的记忆。

DeepSeek Harness

为 DeepSeek Harness 提供原生记忆工具、回答前召回与完整回合捕获。

前置条件

DeepSeek Harness、MetaMemory 账号与组件 Key。

安装

git clone https://github.com/FoxTamingPrince/metamemory-agent-plugins.git metamem-agent-plugins

export METAMEM_API_KEY="你的MetaMemory组件Key"
export METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io"
export METAMEM_MEMORY_COMPONENT="mem0_platform"

dsh plugin --profile headless add ./metamem-agent-plugins/integrations/deepseek-plugin

配置

在 Harness 的 Cordis 配置中注册已安装包：

- name: "@deepseek-ai/dsh-system-prompt"
- name: "@deepseek-ai/dsh-tools"
- insert:
    - id: metamem
      name: "/你的DSH目录/profiles/headless/node_modules/@metamem/deepseek-plugin/dist/index.js"
      config:
        userId: alice
        host: https://metamemory.8-163-122-236.nip.io
        autoRecall: true
        autoCapture: true

使用同一 profile 加载该配置：

dsh web --patch ./cordis.yml

工作原理

完成的用户与智能体回合用于捕获，召回结果进入模型上下文。

智能体工具

记忆范围

自动捕获和召回使用配置的 userId。需要运行级记忆时，显式保存并查询同一 runId。

遥测

使用 MEM0_TELEMETRY=false 关闭原生插件遥测。

参数默认值

将示例中的模块路径替换为该 profile 的实际安装路径；通过同一个 profile 启动 Harness。

生命周期

自动操作按 userId 保存和检索。显式工具可使用 agentId、runId；子智能体的 preset 需要同样加载插件。

Hermes Agent

为 Hermes Agent 提供外部长期记忆，与内置文件记忆共同工作。

工作原理

当前回合召回

回答前查询当前问题的相关记忆，并在原生等待窗口内注入上下文。

后台事实提取

回合结束后，在后台发送用户消息与回答。显式保存使用 mem0_add。

智能体工具

安装

使用支持独立 memory-provider 插件的 Hermes 和 Python 3.11+。

git clone https://github.com/FoxTamingPrince/metamemory-agent-plugins.git metamem-agent-plugins

export METAMEM_API_KEY="你的MetaMemory组件Key"
export METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io"
export METAMEM_MEMORY_COMPONENT="mem0_platform"

hermes plugins install ./metamem-agent-plugins/integrations/hermes-plugin-metamem
hermes plugins enable metamem
hermes memory setup metamem
hermes memory status

平台配置

方式 1：交互向导（推荐）

hermes memory setup metamem

选择 Platform，填写 MetaMemory 组件 Key。开始新的 Hermes 会话。

方式 2：手动配置

hermes config set memory.provider metamem

在当前 profile 的 .env 中设置：

MEM0_API_KEY=你的MetaMemory组件Key
METAMEM_BACKEND_URL=https://metamemory.8-163-122-236.nip.io
METAMEM_MEMORY_COMPONENT=mem0_platform

当前 profile 的 mem0.json：

{"mode":"platform","host":"","user_id":"alice"}

自托管服务配置

使用原生服务模式时，在 mem0.json 的 host 中填写服务 URL。该模式直接连接对应原生服务；连接 MetaMemory 的多个后端使用平台模式与 METAMEM_MEMORY_COMPONENT。

开源模式配置

交互向导选择 Open Source，并配置模型、embedding 和向量库；或在 mem0.json 中设置 mode: "oss" 与 oss 配置。

切换模式

更新当前 profile 的 mode、服务地址与凭据，然后新建会话。

配置

使用稳定 user_id 保持跨渠道记忆一致。不同 Hermes profile 使用各自配置与凭据。

迁移已有用户

保留原有用户身份、profile 和本地存储路径，选择独立 metamem provider。

可靠性

召回使用原生等待窗口，捕获在后台执行。通过工具结果与 hermes memory status 查看连接。

配置字段

配置文件位于当前 profile 的 ${HERMES_HOME}/mem0.json。

非空文件配置优先于 MEM0_MODE、MEM0_HOST、MEM0_USER_ID、MEM0_AGENT_ID；文件中的 api_key 优先于 MEM0_API_KEY。

原生开源配置示例

{
  "mode": "oss",
  "user_id": "alice",
  "oss": {
    "llm": {
      "provider": "openai",
      "config": {"model": "gpt-5-mini", "is_reasoning_model": true}
    },
    "embedder": {
      "provider": "openai",
      "config": {"model": "text-embedding-3-small"}
    },
    "vector_store": {
      "provider": "qdrant",
      "config": {"path": "~/.hermes/metamem-vector-store"}
    }
  }
}

模型凭据使用对应提供商的环境变量。可分别配置记忆模型与主对话模型。切换模式保留原有用户身份及存储路径；不同模式的记忆不会自动迁移。

工具参数与回合处理

回答前最多等待召回 3 秒，后台捕获在回合完成后执行。设置稳定的 user_id 可在不同渠道间共享个人记忆。

DeerFlow：Mem0 与 metamem 接入对照

安装插件，配置项目 Key、用户 ID 和 memory_component，即可在宿主中使用记忆。

Mem0 与 metamem 配置对照

地址填写服务域名。memory_component 选择记忆组件；自动捕获与检索使用 METAMEM_MEMORY_COMPONENT 配置，插件在请求中携带组件标识。Key 填写 metamem 项目的组件凭据。

export METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io"
export METAMEM_MEMORY_COMPONENT="mem0_platform"

安装插件

记忆配置写在 DeerFlow 根目录的 config.yaml；Key 通过 MEM0_API_KEY 环境变量提供。

1. 启用记忆

把下面的 metamem memory 段合入 config.yaml。

2. 提供 Key

在 DeerFlow 启动进程的环境中设置 MEM0_API_KEY 为平台组件 Key。

export MEM0_API_KEY="你的metamem组件Key"

3. 启动 DeerFlow

按项目原有启动方式启动，再创建会话；会话继续传递同一用户身份。

配置客户端

Mem0：config.yaml

memory:
  enabled: true
  injection_enabled: true
  manager_class: mem0
  mode: middleware
  backend_config:
    api_key_env: MEM0_API_KEY
    base_url: https://api.mem0.ai
    allow_insecure_http: false
    top_k: 8
    timeout_seconds: 30
    failure_policy:
      read: fail_open
      write: log_and_drop

metamem：config.yaml

memory:
  enabled: true
  injection_enabled: true
  manager_class: mem0
  mode: middleware
  backend_config:
    api_key_env: MEM0_API_KEY
    base_url: https://metamemory.8-163-122-236.nip.io
    allow_insecure_http: false
    top_k: 8
    timeout_seconds: 30
    failure_policy:
      read: fail_open
      write: log_and_drop

4. 接入后怎么用

无需安装一个新的 DeerFlow 插件。沿用内置 mem0 manager，改变服务地址和 Key；自动对话写入与记忆注入继续由 DeerFlow 管理。

5. 怎样确认记忆生效

1. 在一个项目会话中说：“请记住，这个项目的测试口令是蓝鲸-731。”
2. 等待记忆写入完成，然后在同一项目新建会话。
3. 问：“这个项目的测试口令是什么？”并查看记忆查询结果是否包含“蓝鲸-731”。

判断依据是实际记忆查询结果；仅看到模型回答或插件已启用，还不能确认保存成功。

返回 Mem0／metamem 接入总览

算法工程 SDK 交接（2026-09-13）

为算法工程师准备的本地核心 + DeerFlow 适配安装包、源码快照与构建验证记录。

下载（Cloud SDK 2026-09-28 / Core 2026-09-13）

校验和文件：metamemory-handoff-SHA256SUMS-20260928.txt（覆盖上表三个安装包/快照）。随包 README 仅作包内辅助参考，不作为独立文档入口。

云客户端（HTTP API）

面向 HTTP API 场景使用 metamemory_cloud_sdk（0.1.0a7）。安装后导入：

import os
from metamemory_sdk import MetaMemory

client = MetaMemory(
    api_key=os.environ["METAMEMORY_API_KEY"],      # 从环境读取，页面不内置真实 Key
)

三个核心操作：add、search、review。巩固与记忆维护由组件内部调度。

本地核心 + DeerFlow 适配

使用新构建的 metamemory_plugin 0.1.0+handoff20260913 wheel：

pip install ./metamemory_plugin-0.1.0+handoff20260913-py3-none-any.whl

要求 Python >= 3.11、依赖 cryptography>=49,<51（本次按 --no-deps 构建，宿主环境需自备该依赖）。旧 0.1.0（2026-08-30 构建）wheel 缺少 metamemory_core.adapters 子模块，不能用于当前 DeerFlow 接入，不要作为 DeerFlow 安装推荐。

DeerFlow 对接版本按现有官方项目内 host README 锁定基线：DeerFlow 2.1.0 / commit 72ba661b84452ed3b8271d77749b3f0e036e2809（这是本适配文档锁定的验收基线，非本次重新查询的最新版本）。

最小安装与配置

把插件装进 DeerFlow 使用的同一 Python 环境：

uv pip install -e /path/to/agent-memory-plugin   # 或直接 pip install 上面的 handoff wheel

把 plugins/metamemory-plugin/host_adapters/deerflow/config.example.yaml 中的 memory 段合入 DeerFlow 根目录 config.yaml，关键入口：

memory:
  enabled: true
  injection_enabled: true
  mode: middleware
  manager_class: metamemory_core.adapters.deerflow:MetaMemoryDeerFlowManager
  backend_config:
    data_root: .deer-flow/metamemory
    host_id: host:deerflow:company-platform
    profile: textual
    scope_mode: agent
    latency_class: interactive_fast
    max_context_items: 12
    max_context_chars: 16000
    max_cached_principals: 64
    read_failure: fail_open
    write_failure: fail_open

启动时 DeerFlow 会验证 manager_class 指向的类确实继承其 MemoryManager；入口解析失败应启动报错，不能回落另一套记忆后端。

本地最小 encode → retrieve（本地核心离线链路已实跑通过；真实 DeerFlow 宿主两轮仍未验证）

以下片段取自 examples/local/metamemory_quickstart.py（一次性本地状态、规则语义化、无模型调用）：

from pathlib import Path
from uuid import uuid4

from metamemory_core import MetaMemory
from metamemory_core.runtime.service import MetaMemoryRuntime
from metamemory_core.protocol.knowledge import ScopeRef
from metamemory_core.protocol.episodic import EpisodeInput
from metamemory_core.protocol.retrieval import RetrievalRequest, RetrievalLatencyBudget

now = __import__('datetime').datetime.now(__import__('datetime').timezone.utc).isoformat().replace('+00:00', 'Z')
scope = ScopeRef(principal_id='sample-user', scope_type='project', scope_id='sample-project')
runtime = MetaMemoryRuntime.open_principal(
    data_root=Path('/path/to/data-root'), principal_id=scope.principal_id,
    semanticizer=RuleBasedEpisodeSemanticizer(), incremental_semanticizer=RuleBasedEpisodeSemanticizer(),
)
memory = MetaMemory(runtime)
try:
    memory.encode(kind='episodes', request_id=str(uuid4()), scope=scope,
        episodes=(EpisodeInput(source_id='message-1', speaker='user',
            content='I prefer Go for backend development.',
            event_time=now, recorded_time=now, session_ref='session-1', turn_index=0,),),)
    memory.integrate(request_id=str(uuid4()), scope=scope, integration_time=now)
    bundle = memory.retrieve(RetrievalRequest(request_id=str(uuid4()), scope=scope,
        query='Which language do I prefer for backend development?',
        purpose='answer_question', profile='textual',
        latency_budget=RetrievalLatencyBudget.default('interactive_balanced'), top_k=5,))
    print(bundle)
finally:
    runtime.close()

本地链路已实跑（2026-09-13）：用 installed 目录（PYTHONPATH 指向隔离 --no-index --no-deps 安装产物）单次执行上方第 3 节示例，唯一改动是 data_root 指向本地包内目录：exit 0、stderr 为空、无第二次尝试，按 encode → integrate → retrieve → review 完成。检索真实非空：returned_count=1，rank 1 证据内容即原文 I prefer Go for backend development.（source_id=message-1，tier=observed，retrieval_reasons=hashed_bm25+recency）。回执 result_status=partial、completeness=0.25、stop_reason=required_evidence_missing_at_current_capability、scheduled_review_pending=true，covered 仅 fact_recall——这是核心对单一合成 episode 的诚实覆盖评估，不是空返回、也不是检索失败。语义化用离线 RuleBasedEpisodeSemanticizer（semanticizer 与 incremental_semanticizer 两处显式传入），无网络、无模型调用。仍未验证：真实 DeerFlow 宿主 agent loop 两轮对话、宿主插件加载与端到端 agent 会话；不得把此次单次检索回执时长当完整链路性能指标。详情见 downloads/VALIDATION.md 与 downloads/LOCAL-VALIDATION.json。

本次构建与安装验证（真实记录）

来自 VALIDATION.md（详见 downloads/VALIDATION.md）：

未验证：真实 DeerFlow 宿主两轮对话（真实 LLM agent loop）、真实 DeerFlow Gateway 启动、认证中间件向 user_id 的生产注入、真实并发基线；云客户端 encode/retrieve 的真实云端写入与检索效果也未定位到已核两轮记录。本地核心最小链路已按上方记录实跑通过（离线规则、合成输入），但不代表宿主端到端已验收。以上均需单独验收。

DeerFlow Manager 实际验证

2026-09-13 完成的一次真实运行核验。范围仅限宿主侧 DeerFlow Manager：真实 DeerFlow factory 加载、MemoryManager 继承、跨 thread 召回与 Agent 隔离。本节不覆盖 LLM agent loop 两轮行为，也未联网调用模型，未安装生产依赖或重启服务。

版本说明：本次验证所用 harness 源码短 SHA 为 9ce6fdcb；新版 wheel 为 0.1.0（handoff 2026-09-13），从隔离的 installed 环境加载，接口开关 DEERFLOW_MANAGER_INTERFACE_AVAILABLE=true，说明真实 DeerFlow factory 加载与 MemoryManager 继承成立。原适配 README 标注的 2.1.0 与 72ba661b84452ed3b8271d77749b3f0e036e2809 仅为旧文档基线，本次结果不归属该版本。

• SDK session fa59ed5c-d3a7-44a6-bc1e-56e5ed9e8052：成功。
• 真实测试函数 test_locked_deerflow_factory_loads_and_isolates_metamemory：以 canonical Python 3.12.13 运行，EXIT=0、stderr 为空、断言全部通过。
• 实际写入内容：用户消息 “Factory-loaded memory codename is Quartz.”，助手消息 “Quartz recorded.”（均为合成内容，非真实用户数据）。
• 跨 thread 召回：lead-agent 在 next-thread 调用 get_context 时返回两条 episodic 原文。
• Agent 隔离：other-agent 执行 search('Quartz') 返回 []。
• 未验证边界：不是 LLM agent loop 两轮；未联网调用模型；未安装生产依赖或重启服务。

机器可读摘要见 downloads/DEERFLOW-MANAGER-VALIDATION.json。