两次调用，让智能体用上记忆

保存一段对话，再取回回答需要的记忆证据。

1. 安装 SDK

下载 Python SDK 预发布安装包 ↓，随后在下载目录执行：

pip install ./metamemory_cloud_sdk-0.1.0a7-py3-none-any.whl

add/search 的末尾可选参数 memory_component 指定记忆组件；省略时使用 Jev-Mem（Jev API）。URL 和账号 Key 保持不变。读取原项目时传入它保存的组件，切换组件不会迁移已有记忆。

2. 配置连接

默认连接 MetaMemory。在应用服务端将控制台签发的组件 Key 设置为 METAMEMORY_API_KEY。SDK 自动连接云端服务，无需填写服务地址。

3. 添加记忆

from time import time
from uuid import uuid4
from metamemory_sdk import MetaMemory

# Reads METAMEMORY_API_KEY from your server environment.
client = MetaMemory()

# Keep this ID when retrying the same write.
request_id = str(uuid4())
timestamp = int(time() * 1000)

result = client.add(
    user_id="<user_id>",
    session_id="<session_id>",
    request_id=request_id,
    messages=[
        {
            "role": "user",
            "timestamp": timestamp,
            "content": "I use Python for backend development.",
        },
        {
            "role": "assistant",
            "timestamp": timestamp,
            "content": "I will tailor code examples to Python.",
        },
    ],
)
print(result)

4. 检索记忆

from metamemory_sdk import MetaMemory

# Reads METAMEMORY_API_KEY from your server environment.
client = MetaMemory()

# Use the same user_id to retrieve their memories.
result = client.search(
    user_id="<user_id>",
    query="Which language should my backend examples use?",
    top_k=5,
)

for memory in result["data"]:
    print(memory["content"])

检索返回的是记忆证据，交给你的智能体生成回答。同一段连续对话写入时使用相同的 session_id；检索只传 user_id，不传 session_id。新对话换 session_id、保留 user_id；切换用户才换 user_id。会话标识描述当前对话，不应默认把长期记忆检索限制在这一段对话内。

写入必须显式提供唯一 request_id；网络故障后再次提交同一笔写入时，应保留原 request_id。记忆处理、时间默认值与存储由服务端负责；真实写入与检索效果需单独验收。

对应 Add。将经历形成记忆；Embedding 是可能采用的内部步骤。普通写入不直接创建全局元记忆知识。下列为已接通的云端接口约定；协议测试不代替模型效果验收。

add 请求

平台为每个记忆分块发送一次请求。响应前存储全部消息，并关联指定的 user_id。session_id 标识来源会话并可用于分组，检索隔离以 user_id 为准。

评测加载时，每个来源会话默认调用一次；超过 20 条消息或 2000 个词，在最近的完整消息或句子边界分段。这是评测端的分段规则，SDK 单次 add 不自动拆分或改写消息。真实对话可在回合结束后提交，连续回合保留同一 session_id，每笔写入使用不同 request_id。

{
  "request_id": "eval:<run_id>:locomo_refined:conv-0:chunk-0",
  "messages": [{
    "role": "user",
    "timestamp": 1704067200000,
    "content": "raw memory text"
  }],
  "user_id": "eval:<run_id>:locomo:conv-0",
  "session_id": "eval:<run_id>:sample:0"
}

不发送 metadata、app_id、agent_id 或 async_mode。消息中的 timestamp 由调用方提供，SDK 保持原值。

add 响应 · HTTP 200

写入持久化并且相关记忆可立即检索后，服务端才能确认成功。即使内部异步处理，也必须等待完成后返回。

{
  "success": true,
  "request_id": "eval:<run_id>:locomo_refined:conv-0:chunk-0",
  "user_id": "eval:<run_id>:locomo:conv-0",
  "session_id": "eval:<run_id>:sample:0"
}

不接受 HTTP 202、task ID 或状态查询地址，响应无需 memory_ids。

Python SDK

receipt = client.add(
    request_id="write-1", user_id="user-1",
    session_id="conversation-1",
    messages=[{"role": "user", "content": "我偏好用 Go 开发后端"}],
)

以上 JSON 为格式示例，不是实际写入回执。客户端校验不能替代服务端的同步可检索性验收。

对应 Search。所有 add 成功后再检索。评测使用问题原文，选择题另传 options；不替换成最终答案，不使用评测金标。

search 请求

{
  "query": "Which answer best matches the memory?",
  "options": ["A. First answer", "B. Second answer"],
  "user_id": "eval:<run_id>:locomo:conv-0",
  "top_k": 100
}

不发送 session_id、request_id、filters、rerank 或 keyword_search。SDK 不额外限定 top_k=100 为所有场景的上限；现有评测适配器仍有 1–100 的实现限制，其他取值的服务端支持待核对。

search 响应 · HTTP 200

{
  "data": [{
    "id": "mem_123",
    "content": "remembered fact text",
    "score": 0.87,
    "created_at": "2026-07-01T12:00:00Z"
  }]
}

服务端完成排序且返回不超过 top_k 条。SDK 返回完整 JSON 对象并保留顺序，不补造分数或时间。评测端忽略 metadata 等未声明字段。示例分数仅说明格式，不代表 MetaMemory 实际调用结果。

{"data": []}

Python SDK

result = client.search(
    user_id="user-1", query="我开发后端偏好什么语言？",
    top_k=100,
)

内部 MemoryEvidenceBundle 在服务适配层映射为上述结构；检索选出的证据不等于完整库存，也不表示删除库存。

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。按所选会话逐个复盘，返回各会话结果。

宿主适配 SDK

使用自己的宿主时，宿主模型费用由你承担；组件调用使用账户的试用、套餐或付费额度。平台内的宿主体验统一使用登录账户的平台资源。

安装 Python SDK → · 快速开始 →

DeerFlow

本地核心 + DeerFlow 适配的安装包与配置基线见 算法工程 SDK 交接（2026-09-13）。

接入点：MemoryManager。回答前由 get_context 检索；add / add_nowait 接收回合消息。

安装与配置：在宿主记忆管理器中绑定云端客户端；保持 user_id 与会话标识来自认证和会话上下文。 2.1.x；其他版本需重新核验。

from metamemory_sdk import MetaMemory

# 从环境读取平台 API Key 与确认的服务地址
memory = MetaMemory()

def deerflow_before_answer(user_id, session_id, question):
    return memory.search(
        user_id=user_id, query=question, top_k=100,
    )

def deerflow_after_answer(user_id, session_id, messages, turn_id):
    return memory.add(
        user_id=user_id, session_id=session_id,
        messages=messages, request_id=turn_id,
    )

Codex

接入点：UserPromptSubmit / Stop。UserPromptSubmit 先检索再记录当前用户消息；Stop 只记录最终助手回复。

安装与配置：由正式插件的 hooks 配置注册事件，检索证据写入 additionalContext。云端插件包尚未发布，不能把下方函数当作可安装插件。 锁定扩展协议，发行版本待验收；其他版本需重新核验。

from metamemory_sdk import MetaMemory

# 从环境读取平台 API Key 与确认的服务地址
memory = MetaMemory()

def codex_before_answer(user_id, session_id, question):
    return memory.search(
        user_id=user_id, query=question, top_k=100,
    )

def codex_after_answer(user_id, session_id, messages, turn_id):
    return memory.add(
        user_id=user_id, session_id=session_id,
        messages=messages, request_id=turn_id,
    )

Claude Code

接入点：UserPromptSubmit / Stop。提交提示时检索并注入上下文；停止时保存最终回答。

安装与配置：通过宿主插件的 hooks 注册回调；使用 hookSpecificOutput.additionalContext 传递证据。云端插件包待发布。 内部核验基线 2.1.241；其他版本需重新核验。

from metamemory_sdk import MetaMemory

# 从环境读取平台 API Key 与确认的服务地址
memory = MetaMemory()

def claude_code_before_answer(user_id, session_id, question):
    return memory.search(
        user_id=user_id, query=question, top_k=100,
    )

def claude_code_after_answer(user_id, session_id, messages, turn_id):
    return memory.add(
        user_id=user_id, session_id=session_id,
        messages=messages, request_id=turn_id,
    )

DeepSeek Harness

接入点：agent/pre-step / turn/end。首个模型步骤前检索；回合持久化完成后编码双方消息。

安装与配置：通过 Cordis 插件接收宿主事件，等待 sessions / sessionPersistence 屏障再读回合内容。云端插件包待发布。 内部核验基线 0.1.0-rc.8；其他版本需重新核验。

from metamemory_sdk import MetaMemory

# 从环境读取平台 API Key 与确认的服务地址
memory = MetaMemory()

def deepseek_before_answer(user_id, session_id, question):
    return memory.search(
        user_id=user_id, query=question, top_k=100,
    )

def deepseek_after_answer(user_id, session_id, messages, turn_id):
    return memory.add(
        user_id=user_id, session_id=session_id,
        messages=messages, request_id=turn_id,
    )

OpenClaw

接入点：before_prompt_build / agent_end。构造提示前取证据；agent_end 后编码本轮双方消息。

安装与配置：通过原生 memory slot 注册插件，并由管理员允许会话访问。云端插件包待发布。 内部核验基线 2026.7.2；其他版本需重新核验。

from metamemory_sdk import MetaMemory

# 从环境读取平台 API Key 与确认的服务地址
memory = MetaMemory()

def openclaw_before_answer(user_id, session_id, question):
    return memory.search(
        user_id=user_id, query=question, top_k=100,
    )

def openclaw_after_answer(user_id, session_id, messages, turn_id):
    return memory.add(
        user_id=user_id, session_id=session_id,
        messages=messages, request_id=turn_id,
    )

Hermes

接入点：MemoryProvider。prefetch 检索；回合写入、压缩前补录和结束事件负责保存与记忆巩固。

安装与配置：注册外部 MemoryProvider，设置 memory.provider；云端 provider 的分发与注册名待发布确认。 内部核验基线 0.19.0；其他版本需重新核验。

from metamemory_sdk import MetaMemory

# 从环境读取平台 API Key 与确认的服务地址
memory = MetaMemory()

def hermes_before_answer(user_id, session_id, question):
    return memory.search(
        user_id=user_id, query=question, top_k=100,
    )

def hermes_after_answer(user_id, session_id, messages, turn_id):
    return memory.add(
        user_id=user_id, session_id=session_id,
        messages=messages, request_id=turn_id,
    )

Pi

接入点：before_agent_start / agent_end。before_agent_start 检索并注入隐藏上下文；agent_end 保存最终回合。

安装与配置：通过扩展加载器注册生命周期回调；云端扩展包待发布。 内部核验基线 0.80.10；其他版本需重新核验。

from metamemory_sdk import MetaMemory

# 从环境读取平台 API Key 与确认的服务地址
memory = MetaMemory()

def pi_before_answer(user_id, session_id, question):
    return memory.search(
        user_id=user_id, query=question, top_k=100,
    )

def pi_after_answer(user_id, session_id, messages, turn_id):
    return memory.add(
        user_id=user_id, session_id=session_id,
        messages=messages, request_id=turn_id,
    )

Mem0 与 metamem：宿主接入对照

metamem 统一记忆组件的底层接口，并为每种宿主提供专用 SDK／插件。宿主继续使用自己的原生工具、生命周期事件和权限流程，通过 metamem 选择记忆后端。

先看两者的区别

固定地址与组件参数

memory = Client(api_key=component_key, base_url="https://metamemory.8-163-122-236.nip.io")
memory.add(messages, user_id="user-001", memory_component="hindsight")
memory.search(query, filters={"user_id": "user-001"}, memory_component="hindsight")

宿主插件启动前设置 METAMEM_BACKEND_URL 为固定服务地址，METAMEM_MEMORY_COMPONENT 为所选组件。宿主原生捕获与召回流程负责调用 Add/Search。

标准 SDK 函数

省略 memory_component 时使用客户端默认组件。调用 for_component("hindsight") 可绑定该组件的 Dream 和扩展函数，服务地址保持不变。

三层架构

请求方向为“宿主 → 专用插件 → metamem → 记忆后端”，检索结果沿原路返回并由宿主加入模型上下文。更换后端时，保留宿主接入方式，调整项目的组件配置。

选择你的宿主，查看接入对照

宿主版本、插件版本和插件依赖的 SDK 版本分别管理。各宿主的事件、配置格式与命令保持各自原生形式。

十一种记忆后端

1. MetaMemory
2. InvMem
3. HyMemory
4. ReFind
5. ActiveMemoryIndex
6. FlowGrid
7. Mem0 本地版
8. Mem0 Platform
9. Jev-Mem
10. Hindsight
11. EverMind / EverOS

• 公共接口：采用 Mem0 格式。
• 特有函数：通过组件扩展接口提供。
• 模型与 embedding：可共用部分使用项目统一配置。
• 专有参数：保留在各后端配置中。

各记忆后端的函数

标准函数

✓ 提供标准接口。get_all 要求完整库存，单条管理使用已登记的记忆 ID。

组件扩展函数

通过 backend_extension(函数名, ...) 调用；native_get 等管理扩展也可使用 native("get", ...)。

后台 Dream 配置

后台使用各组件的原生机制，宿主继续使用 Add/Search。组件不支持开关或配置条件不满足时，返回具体原因。

Mem0 Platform 原生 Dream 查询

配置支持原生 reflection_mode=batch/direct，可单独更新模式；省略开关时保持开关原值。模式配置不表示立即执行巩固。配置写入通过 Idempotency-Key 标识请求，SDK 的 request_id 映射到此请求头，未知结果不自动重放。

Python 客户端通过 dream_read(operation, org_id=..., project_id=..., resource_id=..., limit=..., cursor=...) 访问这些 Mem0 Platform 原生接口，保留官方 JSON、来源和生命周期字段。其它后端通过各自组件扩展提供特有查询，宿主工具定义保持原样。

公共记忆接口

Mem0 后端保留这八个接口的参数和结果，包括 latest_only、include_merged、lifecycle_state、replacement_memory_id。其它组件由能力接口提供对应的公共操作和原生扩展。

组件能力与接口适配

公共接口定义相同，实际操作由组件能力表提供。InvMem 原生实现 Add/Search；管理接口通过其持久化记录适配；更新同时修改内容与检索向量，删除同步清理检索记录。组件能力表用于选择工具和页面操作。组件专有操作通过扩展接口调用。

项目与身份配置

1. 创建项目，选择宿主、记忆组件和模型配置。
2. 选择 metamem 接入模式；平台绑定账号、项目、宿主和组件。
3. 在宿主插件中配置组件端点、组件凭据与记忆身份。
4. 通过宿主正常对话或原生工具使用记忆。

平台配置使用 host、principalId、workspace、component 定位绑定。user_id 标识记忆所有者，agent_id、app_id 和 run_id 保留其实体含义。不同项目与组件使用独立的运行状态、会话和记忆范围。服务端保存凭据，浏览器通过登录会话执行操作。

执行与结果

集成体验通过 POST /api/metamemory-demo/metamem/execute 提交回合，返回 job_id；客户端通过 status 查询结果，使用 request_id 恢复首次响应丢失的请求。权限选择返回同一待处理的原生回调。页面分别显示宿主回答、记忆执行结果和异步事件状态。

记忆巩固与扩展

巩固由所选后端执行。Mem0 Platform 云端 Dream 包括写入时的 Supersede／Merge，以及项目启用后在后台运行的 Synthesis；宿主在后续检索时读取更新后的内容。Synthesis 使用仅带 user_id 的记忆。插件 mem0-dream 属于宿主技能，与云端调度分别配置。Hindsight 提供 consolidation、reflect 和 mental models。组件能力接口决定可调用的扩展及其参数。

错误处理

配置错误返回配置问题；权限操作等待宿主确认；异步写入通过事件接口查询完成状态。结果为 pending 或 unknown 时，保留原 request_id 查询结果，避免重复提交写入。组件未提供某项操作时，返回 unsupported_operation。

Codex：Mem0 与 metamem 接入对照

这页按原版 Mem0 和 metamem 并排说明。先选接入方式，再按配置位置填写地址、Key 和用户 ID。

1. 两种接入有什么区别

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

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

2. 安装及配置放在哪里

服务地址、Key、用户 ID 设置为启动 Codex 的环境变量；插件登记写在项目的 .agents/plugins/marketplace.json。

1. 把交付插件放进项目

将完整的 Codex metamem 插件目录复制到项目的 plugins/metamem-codex，保留其中的 hooks、skills、core 和插件清单。

2. 登记插件

在项目根目录创建 .agents/plugins/marketplace.json；已有该文件时，将下面的插件项合入 plugins 数组。

{
  "name": "metamem-local",
  "plugins": [{
    "name": "metamem",
    "source": {"source": "local", "path": "./plugins/metamem-codex"},
    "policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
    "category": "Productivity"
  }]
}

3. 设置记忆连接

在启动 Codex 的终端中使用下面的 metamem 配置。

4. 安装并启用

在项目根目录登记本地插件源，启动 Codex 后输入 /plugins，选择 metamem-local 中的 metamem 并安装、启用；然后新建会话。

codex plugin marketplace add .
codex
# 在 Codex 中输入：/plugins

3. Mem0 与 metamem 配置示例

Mem0：启动前设置

export MEM0_API_URL="https://api.mem0.ai"
export MEM0_API_KEY="你的Mem0云端Key"
export MEM0_USER_ID="user-001"

metamem：启动前设置

export MEM0_API_URL="https://metamemory.8-163-122-236.nip.io/metamem"
export MEM0_API_KEY="你的metamem组件Key"
export MEM0_USER_ID="user-001"
export PLUGIN_ROOT="$(pwd)/plugins/metamem-codex"
export PLUGIN_DATA="$HOME/.local/share/metamem/codex"

4. 接入后怎么用

插件在回答前读取相关记忆，把完成的对话放入后台写入队列。保存需要等待后台写入完成；新会话仍使用同一用户 ID 和项目。

5. 怎样确认记忆生效

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

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

Codex 插件源、安装与启用方式见 OpenAI 官方插件指南。安装后新建会话，见 官方插件使用说明。

返回 Mem0／metamem 接入总览

Claude Code：Mem0 与 metamem 接入对照

这页按原版 Mem0 和 metamem 并排说明。先选接入方式，再按配置位置填写地址、Key 和用户 ID。

1. 两种接入有什么区别

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

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

2. 安装及配置放在哪里

服务地址、Key、用户 ID 设置为启动 Claude Code 的环境变量；用 --plugin-dir 指定交付插件目录。

1. 放置插件

将完整的 Claude Code metamem 插件放到 ~/plugins/metamem-claude。

2. 设置连接

在终端中使用下面的 metamem 配置。

3. 启动

在需要保存项目记忆的仓库中运行：

claude --plugin-dir "$HOME/plugins/metamem-claude"

3. Mem0 与 metamem 配置示例

Mem0：启动前设置

export MEM0_API_URL="https://api.mem0.ai"
export MEM0_API_KEY="你的Mem0云端Key"
export MEM0_USER_ID="user-001"

metamem：启动前设置

export MEM0_API_URL="https://metamemory.8-163-122-236.nip.io/metamem"
export MEM0_API_KEY="你的metamem组件Key"
export MEM0_USER_ID="user-001"
export CLAUDE_PLUGIN_DATA="$HOME/.local/share/metamem/claude"

4. 接入后怎么用

插件读取相关记忆并补充到回答上下文，后台保存完成的对话。命令前缀从 mem0 改为 metamem，个人记忆与项目记忆仍按各自范围管理。

5. 怎样确认记忆生效

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

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

返回 Mem0／metamem 接入总览

OpenCode：Mem0 与 metamem 接入对照

这页按原版 Mem0 和 metamem 并排说明。先选接入方式，再按配置位置填写地址、Key 和用户 ID。

1. 两种接入有什么区别

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

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

2. 安装及配置放在哪里

插件入口放在 ~/.config/opencode/opencode.json 的 plugin 数组；Key、用户 ID、后端地址设置为进程环境变量。

1. 放置插件

将 OpenCode metamem 分发目录放到固定位置，记下 dist/index.js 的绝对路径。

2. 登记入口

将以下项合入 ~/.config/opencode/opencode.json 的 plugin 数组。把示例路径换成实际绝对路径。

{"plugin": ["file:///absolute/path/metamem-opencode/dist/index.js"]}

3. 设置连接并启动

使用下面的 metamem 环境配置，然后在项目目录运行 opencode。

opencode

3. Mem0 与 metamem 配置示例

Mem0：启动前设置

export MEM0_API_KEY="你的Mem0云端Key"
export MEM0_USER_ID="user-001"

metamem：启动前设置

export METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io/metamem"
export MEM0_API_KEY="你的metamem组件Key"
export MEM0_USER_ID="user-001"

4. 接入后怎么用

安装包名称改为 metamem；保留 /mem0-* 命令名称和原有范围选择。插件在对话时召回相关记忆并捕获需要保存的内容。

5. 怎样确认记忆生效

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

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

返回 Mem0／metamem 接入总览

OpenClaw：Mem0 与 metamem 接入对照

这页按原版 Mem0 和 metamem 并排说明。先选接入方式，再按配置位置填写地址、Key 和用户 ID。

1. 两种接入有什么区别

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

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

2. 安装及配置放在哪里

配置写在 ~/.openclaw/openclaw.json 的 plugins 段，合并到已有配置中。

1. 安装本地插件

将交付的 OpenClaw metamem 插件目录交给 OpenClaw 安装。

openclaw plugins install /absolute/path/metamem-openclaw

2. 填写配置

将下面的 metamem 配置合入 openclaw.json，填写你的组件 Key 和用户 ID。

3. 启动会话

重新加载该 OpenClaw 实例配置，再新建会话。

3. Mem0 与 metamem 配置示例

Mem0：openclaw.json

{
  "plugins": {
    "slots": {
      "memory": "openclaw-mem0"
    },
    "entries": {
      "openclaw-mem0": {
        "enabled": true,
        "config": {
          "mode": "platform",
          "apiKey": "你的Mem0云端Key",
          "userId": "user-001",
          "baseUrl": "https://api.mem0.ai",
          "autoRecall": true,
          "autoCapture": true
        }
      }
    }
  }
}

metamem：openclaw.json

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

4. 接入后怎么用

memory 槽和插件 ID 改成 metamem；工具名称仍为 memory_*。autoRecall 控制回答前召回，autoCapture 控制回答后捕获。

5. 怎样确认记忆生效

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

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

返回 Mem0／metamem 接入总览

Pi：Mem0 与 metamem 接入对照

这页按原版 Mem0 和 metamem 并排说明。先选接入方式，再按配置位置填写地址、Key 和用户 ID。

1. 两种接入有什么区别

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

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

2. 安装及配置放在哪里

身份与自动记忆设置写在 ~/.pi/agent/mem0-config.json；metamem 地址通过 METAMEM_BACKEND_URL 环境变量设置。

1. 加载扩展

使用交付目录中的 dist/entry.js 作为 Pi 扩展入口。

pi -e /absolute/path/metamem-pi/dist/entry.js

2. 填写配置

创建或合并 ~/.pi/agent/mem0-config.json；路径名保留 mem0，里面的 Key 换成 metamem 组件 Key。

{
  "apiKey": "你的组件Key",
  "userId": "user-001",
  "autoCapture": true,
  "defaultScope": "project",
  "searchThreshold": 0.3
}

3. 设置后端地址

在启动 Pi 的终端中设置下面的 metamem 环境配置，再用上述 -e 命令启动。

3. Mem0 与 metamem 配置示例

Mem0：启动前设置

export MEM0_API_KEY="你的Mem0云端Key"
export MEM0_USER_ID="user-001"

metamem：启动前设置

export METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io/metamem"
export MEM0_API_KEY="你的metamem组件Key"
export MEM0_USER_ID="user-001"

4. 接入后怎么用

Pi 在回答前检索记忆，回合结束后自动捕获。保留 /mem0-* 命令；项目范围使用同一仓库身份，便于跨会话回忆。

5. 怎样确认记忆生效

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

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

返回 Mem0／metamem 接入总览

DeepSeek Harness：Mem0 与 metamem 接入对照

这页按原版 Mem0 和 metamem 并排说明。先选接入方式，再按配置位置填写地址、Key 和用户 ID。

1. 两种接入有什么区别

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

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

2. 安装及配置放在哪里

插件入口及记忆设置写在 Cordis 补丁文件，例如 memory-plugin.yml；Key 通过 MEM0_API_KEY 环境变量提供。

1. 放置插件

准备交付插件的 dist/index.js，记下绝对路径。

2. 写入 Cordis 配置

将下面的 metamem 示例保存为 memory-plugin.yml，替换插件路径和用户 ID。

3. 提供 Key 并加载配置

将 MEM0_API_KEY 设为 metamem 组件 Key；在已安装 Harness 的项目中加载补丁。

pnpm dsh web --patch ./memory-plugin.yml

3. Mem0 与 metamem 配置示例

Mem0：memory-plugin.yml

- name: "@deepseek-ai/dsh-system-prompt"
- name: "@deepseek-ai/dsh-tools"
- insert:
    - id: mem0
      name: "/absolute/path/mem0-deepseek/dist/index.js"
      config:
        userId: "user-001"
        host: "https://api.mem0.ai"
        allowUserOverride: false
        autoRecall: true
        autoCapture: true

metamem：memory-plugin.yml

- name: "@deepseek-ai/dsh-system-prompt"
- name: "@deepseek-ai/dsh-tools"
- insert:
    - id: metamem
      name: "/absolute/path/metamem-deepseek/dist/index.js"
      config:
        userId: "user-001"
        host: "https://metamemory.8-163-122-236.nip.io/metamem"
        allowUserOverride: false
        autoRecall: true
        autoCapture: true

4. 接入后怎么用

原生宿主工具是 add_memory 和 search_memory；回答前自动召回、完成回合后自动捕获。更丰富的管理操作通过 metamem 后端接口提供。

5. 怎样确认记忆生效

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

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

返回 Mem0／metamem 接入总览

Hermes：Mem0 与 metamem 接入对照

这页按原版 Mem0 和 metamem 并排说明。先选接入方式，再按配置位置填写地址、Key 和用户 ID。

1. 两种接入有什么区别

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

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

2. 安装及配置放在哪里

provider 写在 $HERMES_HOME/config.yaml；行为设置写在 $HERMES_HOME/mem0.json；Key 和后端地址写在 $HERMES_HOME/.env。

1. 放置 provider

将交付的 metamem provider 目录放到 $HERMES_HOME/plugins/metamem。

2. 选择 provider

将以下内容合入 config.yaml。原版 provider 值为 mem0，metamem 值为 metamem。

memory:
  provider: metamem

3. 填写记忆设置

将以下内容合入 mem0.json。

{
  "mode": "platform",
  "user_id": "user-001",
  "agent_id": "hermes",
  "rerank": false,
  "sync_max_chars": 450
}

4. 设置连接并启动

在实例的 .env 中设置下面的字段，然后启动该 Hermes 实例。

3. Mem0 与 metamem 配置示例

Mem0：.env

MEM0_API_KEY="你的Mem0云端Key"
MEM0_USER_ID="user-001"

metamem：.env

MEM0_API_KEY="你的metamem组件Key"
MEM0_USER_ID="user-001"
METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io/metamem"

4. 接入后怎么用

选择 metamem provider 后，仍保留 mem0_* 工具。宿主通过 provider 在会话过程中读写、同步记忆。

5. 怎样确认记忆生效

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

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

返回 Mem0／metamem 接入总览

DeerFlow：Mem0 与 metamem 接入对照

这页按原版 Mem0 和 metamem 并排说明。先选接入方式，再按配置位置填写地址、Key 和用户 ID。

1. 两种接入有什么区别

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

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

2. 安装及配置放在哪里

记忆配置写在 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

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

3. Mem0 与 metamem 配置示例

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/metamem
    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。

错误处理与重试

接口使用标准 HTTP 状态码，错误信息便于排查且不包含密钥。平台业务错误通常采用以下格式；字段校验失败可返回 HTTP 422 结构化明细。

{"detail": {"reason": "invalid_request"}}

自动重试范围

encode：408、409、425、429、500、502、503、504。retrieve：相同范围，但不含 409。网络超时和传输错误也有限重试；不跟随重定向。review 不自动重试。

当前 SDK 默认最多重试 2 次（总共 3 次尝试），退避为 0.5 秒、1 秒；这是本客户端配置，不是官方规定的次数。初始化可设置 max_retries=0 关闭。重试复用同一请求正文及 request_id，服务端必须保障幂等；最终超时仍需确认写入结果。

格式错误立即终止

即使 HTTP 200，encode 的 success 不是 true、三个 ID 缺失或不匹配，或者 retrieve 的 data 不是数组、证据缺少 id/content，均立即失败，不重试。HTTP 202 也不能算写入成功。

Python 客户端抛出 MetaMemoryError，保留 status_code 与本地请求关联标识；不会把错误正文中的密钥或记忆内容带入异常。公网已实测 Key 撤销后返回 status_code=401；幂等与错误协议单测不代替真实模型失败恢复验收。

对齐依据：AML Add / Search 文档。仅方法名称对应为 encode / retrieve，其余三个操作属于 MetaMemory 扩展。