快速开始

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. 确认写入后检索

Mem0 Platform 返回 PENDING 时先等待事件成功，再执行下面的 search。完整等待代码见 add；不要重复提交对话。

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

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

add：保存记忆

把有顺序的对话发送给记忆组件。infer=True 时由组件提取值得长期保留的信息；infer=False 时请求原样存储。add 保存记忆，不生成聊天回答；一段对话可能产生零条、一条或多条记忆。

receipt = client.add(
    [
        {"role": "user", "content": "I work in Guangzhou and prefer Python."},
        {"role": "assistant", "content": "Understood."},
    ],
    user_id="alice",
    app_id="project-sailing",
    run_id="conversation-1",
    metadata={"source": "conversation"},
)
print(receipt)

身份与范围

组件 Key 决定账户授权；user_id 标识业务用户，不能用它绕过账户权限。app_id 标识项目，agent_id 标识智能体，run_id 标识会话／运行。memory_component 选择后台组件：mem0_platform 为 Mem0 Platform，mem0 为本地 Mem0 OSS。它们是不同记忆库。

写入时身份放在顶层；search 和 get_all 的身份放在 filters 中。只传 user_id 可跨该用户的项目检索；限定 app_id 可隔离项目；新会话复用相同 user_id 和 app_id、使用新的 run_id。跨会话检索不要把 filters.run_id 限定为新会话，否则会排除旧会话记忆。metadata.session_id 是来源标签，不能代替顶层 run_id 的实体范围。

提交与完成

Mem0 Platform 的 Add 返回 event_id 和 PENDING 表示已接收，不表示记忆可检索。需查询事件，确认 SUCCEEDED；FAILED 是写入失败。宿主自身后台提交与服务器后台提取是两层异步。超时／断线可能发生在提交后，应先确认事件结果，不要直接重复 add。

from time import monotonic, sleep
from urllib.parse import quote

def wait_for_write(client, receipt, timeout=60):
    # A synchronous backend may return its final result without an event_id.
    event_id = receipt.get("event_id")
    if not event_id:
        return receipt
    deadline = monotonic() + timeout
    while monotonic() < deadline:
        response = client.client.get(
            "/v1/event/" + quote(event_id, safe="") + "/"
        )
        response.raise_for_status()
        event = response.json()
        if event.get("status") == "SUCCEEDED":
            return event
        if event.get("status") == "FAILED":
            raise RuntimeError("Memory write failed")
        sleep(1)
    raise TimeoutError("Write outcome is still pending; do not repeat add")

当前固定 Python SDK 没有 get_event_status 方法；上面通过 SDK 已认证的 HTTP transport 查询事件，不额外创建客户端或泄露 Key。事件响应保留原生字段；同步组件的最终写入回执不强制转换为 PENDING。

组件能力边界

相同方法名不代表每个组件支持相同高级参数。自定义提取指令、过期条目、合并历史和 latest_only 的支持取决于所选组件；尚未实现的参数会明确报错，不会静默忽略或换组件。当前 MetaMemory 的 latest_only 仅支持 True。具体管理能力以服务返回的组件 capability 为准。

错误与重试

401：Key 缺失、无效或已停用；403：身份／项目越权；404：不存在或未授权的记录／事件；422：参数无效或超出组件范围；501：能力未实现；上游／网络错误：结果可能未确认。以实际错误码和请求标识诊断，不把 HTTP 200 或工具注册当作记忆效果验证。

Mem0 add reference

search：检索记忆

在生成回答前找到相关记忆证据。search 返回记忆条目和组件提供的分数／元数据，不替宿主生成最终回答。宿主把结果加入上下文，再调用对话模型。search 不等于列出所有记忆；浏览已有记忆使用 get_all。

results = client.search(
    "Which city does Alice work in?",
    filters={"AND": [
        {"user_id": "alice"},
        {"app_id": "project-sailing"},
    ]},
    top_k=5,
)
for hit in results.get("results", []):
    print(hit.get("id"), hit.get("memory"), hit.get("score"))

身份与范围

组件 Key 决定账户授权；user_id 标识业务用户，不能用它绕过账户权限。app_id 标识项目，agent_id 标识智能体，run_id 标识会话／运行。memory_component 选择后台组件：mem0_platform 为 Mem0 Platform，mem0 为本地 Mem0 OSS。它们是不同记忆库。

写入时身份放在顶层；search 和 get_all 的身份放在 filters 中。只传 user_id 可跨该用户的项目检索；限定 app_id 可隔离项目；新会话复用相同 user_id 和 app_id、使用新的 run_id。跨会话检索不要把 filters.run_id 限定为新会话，否则会排除旧会话记忆。metadata.session_id 是来源标签，不能代替顶层 run_id 的实体范围。

组件能力边界

相同方法名不代表每个组件支持相同高级参数。自定义提取指令、过期条目、合并历史和 latest_only 的支持取决于所选组件；尚未实现的参数会明确报错，不会静默忽略或换组件。当前 MetaMemory 的 latest_only 仅支持 True。具体管理能力以服务返回的组件 capability 为准。

错误与重试

401：Key 缺失、无效或已停用；403：身份／项目越权；404：不存在或未授权的记录／事件；422：参数无效或超出组件范围；501：能力未实现；上游／网络错误：结果可能未确认。以实际错误码和请求标识诊断，不把 HTTP 200 或工具注册当作记忆效果验证。

Mem0 search reference

get：读取单条记忆

按真实 memory_id 获取一条记忆，不执行语义检索。ID 来自所选组件的写入／列表／检索结果，不是会话 ID 或事件 ID。

memory = client.get(memory_id)
print(memory)

返回该组件的真实记录，包括可用的内容和元数据。不存在或不属于当前授权范围的记录会拒绝读取；不同组件的 ID 不能混用。

get_all：浏览记忆

按实体范围列出已保存的记忆，不需要 query。适合记忆库浏览、导出准备和写入确认；它不按当前问题进行相关度排序。

page = client.get_all(
    filters={"AND": [{"user_id": "alice"}, {"app_id": "project-sailing"}]},
    page=1, page_size=100,
)
print(page)

分页结果通常包含 count、next、previous 和 results；以实际组件回执为准，继续读取下一页，不把第一页当成全部记忆。包含过期或合并条目的筛选不跨组件承诺一致。

身份与范围

组件 Key 决定账户授权；user_id 标识业务用户，不能用它绕过账户权限。app_id 标识项目，agent_id 标识智能体，run_id 标识会话／运行。memory_component 选择后台组件：mem0_platform 为 Mem0 Platform，mem0 为本地 Mem0 OSS。它们是不同记忆库。

写入时身份放在顶层；search 和 get_all 的身份放在 filters 中。只传 user_id 可跨该用户的项目检索；限定 app_id 可隔离项目；新会话复用相同 user_id 和 app_id、使用新的 run_id。跨会话检索不要把 filters.run_id 限定为新会话，否则会排除旧会话记忆。metadata.session_id 是来源标签，不能代替顶层 run_id 的实体范围。

组件能力边界

相同方法名不代表每个组件支持相同高级参数。自定义提取指令、过期条目、合并历史和 latest_only 的支持取决于所选组件；尚未实现的参数会明确报错，不会静默忽略或换组件。当前 MetaMemory 的 latest_only 仅支持 True。具体管理能力以服务返回的组件 capability 为准。

update：修改单条记忆

根据 memory_id 明确修改已保存的内容。它不是继续添加对话，也不会自动把所有冲突记忆同时改写。更新前先读取目标记录。

result = client.update(memory_id, text="Alice now works in Shenzhen.")
print(result)

返回原生更新结果；如有 replacement_memory_id，后续使用新 ID。内容、元数据或过期日期是否可独立修改以组件能力为准。更新历史不等于自动恢复旧版本。

组件能力边界

相同方法名不代表每个组件支持相同高级参数。自定义提取指令、过期条目、合并历史和 latest_only 的支持取决于所选组件；尚未实现的参数会明确报错，不会静默忽略或换组件。当前 MetaMemory 的 latest_only 仅支持 True。具体管理能力以服务返回的组件 capability 为准。

delete：删除单条记忆

删除指定 memory_id 的记录。它不是删除来源会话、整个用户或整个项目；不同组件对关联图谱记录的处理不同。确认目标和组件后再调用。

result = client.delete(memory_id)
print(result)

以实际删除回执为准；返回事件时要查询最终状态。超时不是删除失败证明，不要盲目重复写操作。

delete_all：清空指定范围

批量删除明确身份范围内的记忆。只指定 user_id 会覆盖该用户的全部项目；指定 app_id 限定项目，run_id 限定会话，具体组合必须受组件支持。此操作需要业务端确认。

result = client.delete_all(
    user_id="alice", app_id="project-sailing", run_id="conversation-1",
)
print(result)

不会删除 MetaMemory 账户、空间或 API Key。不要去掉范围字段来规避“不支持”的错误；批量能力未实现时应停止。

组件能力边界

相同方法名不代表每个组件支持相同高级参数。自定义提取指令、过期条目、合并历史和 latest_only 的支持取决于所选组件；尚未实现的参数会明确报错，不会静默忽略或换组件。当前 MetaMemory 的 latest_only 仅支持 True。具体管理能力以服务返回的组件 capability 为准。

history：查看记忆变更

查询指定 memory_id 的记录变更历史，用于追踪创建、修改和删除证据。它不是当前会话的聊天记录，也不是异步事件状态查询。

changes = client.history(memory_id)
print(changes)

原生历史与网关观察日志会注明来源；观察日志只能证明经本服务观察到的操作，不应解释为组件完整内部历史。程序性记忆的注册／验证／状态转换属于原生生命周期记录。

组件能力边界

相同方法名不代表每个组件支持相同高级参数。自定义提取指令、过期条目、合并历史和 latest_only 的支持取决于所选组件；尚未实现的参数会明确报错，不会静默忽略或换组件。当前 MetaMemory 的 latest_only 仅支持 True。具体管理能力以服务返回的组件 capability 为准。

Dream：Mem0 Platform 后台治理

Dream 是 Mem0 Platform 的后台能力，不是每轮宿主对话都运行的模型调用，也不是开源 Memory 自动拥有的功能。

三个独立动作

Synthesis 的范围与等待时间

仅使用 user_id 单独范围：同时带 app_id、agent_id 或 run_id 的记忆不参加用户 Synthesis。启用之后新创建的记忆才有资格，不会立即重处理全部历史；至少 20 条记忆。Pro 每个用户 7 天一次，Enterprise 通常每日且可配置；计划任务启动后结果仍可能约需 24 小时。

本页 Add 示例与许多宿主原生写入包含项目／智能体／会话实体，因此不能仅凭启用了 Dream 就声称这些记录会参与官方 Synthesis。MetaMemory 的平台 Pro 额度也不自动授予上游 Mem0 Platform 的 Pro 套餐。不要为启用 Synthesis 而删除原有隔离字段。

检索与历史行为

Platform 默认检索包括 active 和 superseded，隐藏 merged；latest_only=True 只取 active，include_merged=True 可包含合并记录。这些是供应商 Platform 语义，不代表其他后端已实现同样筛选。

SDK 配置与观察

platform = client.for_component("mem0_platform")
print(platform.get_dream_config())
print(platform.dream_read("stats"))
# Preview reads evidence; it does not start a Dream run.
print(platform.dream_read("preview"))

get_dream_config／update_dream_config 操作项目设置；dream_read 读取真实状态、活动、运行及来源。配置请求成功只表示设置被接受，preview 不是执行回执。后端未支持时明确拒绝；不模拟一个成功的 Dream。

Mem0 Platform Dream reference

组件扩展与复盘

review 不是统一 Mem0 Add/Search 或当前 Client 的标准方法。组件特有复盘、巩固等操作仅在明确声明的扩展能力中提供；未完成的能力不能作为通用接口承诺。

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
• DeerFlow
• MetaMemory MCP

Codex：Mem0 Platform 接入

本指南对应 Codex 0.160.0、冻结官方 Mem0 Codex 插件 0.3.3，以及平台候选 metamem 0.1.0。候选保留原版工具、六个技能和八个钩子的策略，仅调整插件身份与认证传输。安装成功、宿主回答成功、远端记忆写入成功分别核验。

配置

需要 MetaMemory 组件 Key、Python 3.10+、支持插件与钩子的固定 Codex 版本。完整插件在本地运行 Python，不要求安装 Mem0 Python SDK。

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

METAMEM_BACKEND_URL 是 Mem0 兼容 API 的基地址，保留 /metamem/mem0_platform。Key 必须在启动 Codex 的进程环境中可读。候选把这些配置转为原版 MEM0_API_KEY / MEM0_API_URL；原生 stdio MCP 的环境白名单也转发三项配置。不要把 Key 写入提示、仓库或公开回执。

原版用 MEM0_USER_ID 指定个人身份、MEM0_PROJECT_ID 指定项目身份。平台托管会话由服务绑定账户与项目；本地安装需要稳定且真实的身份，不使用 *。仓库 app_id 由原生插件解析 Git 仓库，目录范围另使用 metadata.dirs。

安装固定制品

使用交付回执列出的本地市场包及 SHA256。市场根目录需包含 .agents/plugins/marketplace.json 和 integrations/codex-plugin/，插件目录包含 .codex-plugin/plugin.json、.mcp.json、hooks/、core/、skills/、README.md 与制品来源回执。

codex --version
codex plugin marketplace add /绝对路径/metamem-codex-marketplace
codex plugin add metamem@metamem-plugins --json
codex plugin list --json

安装输出应显示 metamem / metamem-plugins / 0.1.0。在 Codex 的钩子管理界面逐项审阅并信任八个钩子，启用 hooks，随后新建会话。保留 Codex 生成的信任记录；不要跳过信任检查或手工编造 trusted_hash。若只看见搜索工具而没有自动捕获，先检查钩子是否实际启用和信任。

上述 CLI 命令由固定版本实测核对，并参照 OpenAI 官方插件命令。远程 Git 市场是否已发布及其版本另行确认，不能用仓库名称代替本次制品回执。

管理本地插件：

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

原生能力

完整插件的原生 MCP 只有一个工具：search_memories。参数是 query、top_k（1–20）、category、scope（repo / dir / mine）和 run_id。原版没有独立的 Add、库存、Update、Delete 工具；写入由钩子捕获，范围删除由 forget 技能调用本地命令。

repo 联合仓库共享项目记忆与自己的偏好；mine 只取自己的偏好；在子目录使用 dir 会缩小共享项目分支，个人偏好仍属于仓库。category 使用工具 schema 的类别枚举。run_id 筛选事实来源会话，应使用已知原生会话 ID。

自动捕获与召回

<!-- NATIVE SEQUENCE BEGIN -->

调用时序

sequenceDiagram
    participant H as Codex
    participant P as 原生插件与本地证据库
    participant G as MetaMemory 兼容 API
    participant M as Mem0 Platform
    H->>P: SessionStart / UserPromptSubmit
    P->>G: POST /v3/memories/search/ + 原生范围过滤
    G->>M: 账户与项目绑定后的 Search
    M-->>P: 原生记忆证据
    P-->>H: 注入首次召回上下文
    H->>P: PostToolUse / Stop / PreCompact / SessionEnd
    P->>P: 落本地证据并交给 flush worker
    P->>G: Add（原生捕获策略）
    G->>M: 提交提取
    M-->>P: event_id / 最终事件状态
    P->>P: 保留 queued / succeeded / failed / unknown

remember 的可见回复是提取输入之一。后台 HTTP 接收不等于提取成功，提取成功也不保证产生非空记忆。验收须检查事件完成及新会话真实返回的记录或代号。暂停后不应产生新的捕获；恢复后重新产生原生事件。

<!-- NATIVE SEQUENCE END -->

forget 的确认与范围

forget 技能要求先在当前对话确认。原生 CLI 在没有 --yes 时返回拒绝，不执行本地或远端删除。默认远端删除仅自己的当前仓库记忆；共享项目记忆保留，除非用户明确要求并添加 --include-project-memory。仅清本地证据时不加 --remote。

python3 "${PLUGIN_ROOT}/core/memory_cli.py" --harness codex --plugin-data-dir "${PLUGIN_DATA}" forget --remote --yes

确认后才能执行此命令。原版分页列出当前身份的记忆，按当前仓库 app_id 及其子目录筛选，再逐条删除。CLI 的 --yes 是命令门槛；对话确认由技能与智能体遵守，并非远程服务签发的一次性批准令牌。不要把取消、命令拒绝与远端删除成功混为一项。

错误与恢复

先通过 $metamem:status 和 doctor 区分 Key 缺失 / 失效、钩子未启用、暂停、本地队列和远端提取失败。原生搜索失败可能返回空上下文，不能据此认定服务成功或没有记忆。平台保留原始错误、事件与本地状态；宿主答案成功不代表记忆写入成功。

在已有 request_id 或写入结果 unknown 时只观察原始状态，不重放请求、不补造成功、不改写旧证据。重新测试使用新身份、新项目和新请求，清理只删除确认归属的测试记录。固定原版的网络重试行为另与平台的不可重放边界区分。

直接远程 MCP

只需要远程组件工具时可另行配置 MCP：

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

这条路径使用服务端提供的工具，不包含本地六技能与八钩子，也不等同完整插件验收。完整插件和直接 MCP 选择一种入口，避免重复连接造成调用混淆。Cloud 会话的远程 MCP 配置与本地完整插件生命周期分别验收。

本宿主的真实通过、失败、未测项、固定制品摘要与逐步验收见交付时附带的独立 Codex 验收记录。用户验收与研发交付分别记录。

Mem0 原生 Codex 集成说明

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 2.1.289、官方 Mem0 插件 0.3.3；MetaMemory 候选名为 metamem，版本 0.1.0。候选保留官方记忆策略，调整产品命名、配置别名和网关传输。本页只覆盖 mem0_platform，与 Mem0 OSS 分开存储。Sidekick matcher、MCP 工具名和 skill 交叉命令同步替换插件注册名称，不改变记忆算法。

从固定制品安装

需要 MetaMemory 账号及 Mem0 Platform 组件 Key、Python 3.10+、Git。组件 Key 从本人的账户授权获得。

下载 Claude 固定插件包，解压为 metamem-claude-20261008/。包内有本地 marketplace、plugin/ 和来源回执；按交付验收文档核对 ZIP SHA256。

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

claude --version
claude plugin marketplace add "$PWD/metamem-claude-20261008"
claude plugin install metamem@metamem-claude-20261008 --scope user
python3 -c 'import json,os; print(json.dumps({"api_key":os.environ["METAMEM_API_KEY"]}))' |
  claude plugin configure metamem@metamem-claude-20261008 --values-stdin
claude plugin list
claude plugin details metamem@metamem-claude-20261008

重新启动 Claude，或执行 /reload-plugins，在 Git 项目中使用。其它 CLI 版本需另行验证。清单应包含 6 个 skills、1 个 Sidekick、9 类 hooks 和 1 个 mem0 MCP server。远端 marketplace 的当前版本不能代替固定包及回执。

卸载：claude plugin uninstall metamem@metamem-claude-20261008。解压目录留存用于来源核对。

原生能力

插件没有原生库存、更新、指定 ID 删除或事件查询工具。后台诊断和平台 SDK 的接口不扩展为 Claude 插件工具。

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

forget 不接受“只删包含某个词的记录”。官方 CLI 按用户／仓库清理：forget --yes 清本机 evidence 与队列；加 --remote 才删云端个人记忆；再加 --include-project-memory 才包含团队共享记忆。远程清理枚举本范围 ID 后逐条删除，部分失败保留输出与原始状态。

捕获、召回与生命周期

sequenceDiagram
    participant H as Claude Code
    participant P as Official-derived plugin
    participant G as MetaMemory gateway
    participant M as Mem0 Platform
    H->>P: SessionStart / UserPromptSubmit
    P->>G: First-prompt search
    G->>M: Authorize and translate scoped filters
    M-->>P: Native evidence through gateway
    P-->>H: Additional context before answer
    H->>P: PostToolUse / PostToolUseFailure / Stop
    P->>P: Local SQLite evidence
    H->>P: PreCompact / SessionEnd
    P->>G: Background flush Add
    G->>M: Store and poll event
    M-->>P: Terminal event receipt

SessionStart 匹配 startup|resume|clear|compact；其余 hooks 为 UserPromptSubmit、PostToolUse、PostToolUseFailure、SubagentStart、SubagentStop、Stop、PreCompact、SessionEnd。

原生 flush 与真实事件终态才能确认写入。会话回答“已记住”、异步接收、插件启用或 HTTP 200 均不足以证明后台提取成功。

身份与范围

平台先绑定 owner／project，再隔离映射公共身份。目录过滤不提供任意文件路径授权，更换 user_id 也不能越权。

METAMEM_* 别名只存在于候选；官方对照使用原生环境变量。插件数据目录保存 pause、evidence 和 pending flush；不得合并不同 owner 的目录。

平台权限与 Sidekick

网页通过官方 Claude SDK 执行原生插件。Bash 仅允许完整的官方记忆控制命令；带 --yes 的 forget 须由当前工具调用的一次性页面确认批准。取消或 60 秒过期都会拒绝；确认绑定账户、项目、会话、请求及工具调用，不能刷新后复用。共享删除还需单独勾选共享项目确认。终端插件遵循官方 skill 的对话确认规则；网页 broker 与终端原生界面分别验收。

平台由服务端 project_sidekick_scopes 对全新 owner／workspace 精确启用 Sidekick。平台生成独立 Git 工作目录，开放本插件 Agent，并将子智能体读写限制在该目录／worktree。用户不能传任意 cwd，配置与凭据在目录之外。旧绑定默认关闭；已有 native session 的项目不能切换目录。Sonnet 别名由本项目所选 canonical 网关模型解析，不保证 Anthropic Sonnet 的行为或价格。

平台不复制原工作区未提交改动。终端 Sidekick 在实际项目的官方 worktree 中工作，遵循 worktree.baseRef 与用户权限。

错误、恢复与验收

401／失效 Key 应显示鉴权失败，不能解释成“没有记忆”。显式搜索失败保留原生失败结果；首次自动搜索超时可无上下文继续。pause／resume 是本机状态，不代表远端删除。

平台每个请求仅分发一次。超时或终态缺失保留 pending／unknown；同一请求不重放，改查询或模型也不能绕过标记。官方插件另有队列恢复策略，遇到运行中任务应先检查原始 evidence 与事件状态，不能手动重跑写入。

用户先核对版本和制品，再写专用事实、检查 flush 终态、新建会话检索，随后测试 scope、pause／resume、forget 取消／批准、Sidekick。每项区分真实宿主事件、直接 hook callback 和静态证据；未知、失败与未测保留，用户签收另记。

设置 MEM0_TELEMETRY=false 关闭官方遥测。本机 SQLite evidence 仍按原生策略保存。

Mem0 官方 Claude Code 指南

OpenCode 接入 Mem0 Platform

本页针对 OpenCode 1.18.34、官方 @mem0/opencode-plugin 0.4.1 派生的 @metamem/opencode-plugin 0.1.0。后端选用 mem0_platform。插件保留官方命令、工具、捕获和压缩策略，传输连接 MetaMemory 平台。

安装与配置

取得本轮验收交付的 OpenCode 插件目录，保留其中 dist/、opencode-skills/、package.json 和 metamem-provenance.json。在项目的 opencode.json 或全局 ~/.config/opencode/opencode.json 中合并以下配置，路径换成实际绝对路径：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["file:///absolute/path/opencode/dist/index.js"]
}

只安装这一份记忆插件，避免与 @mem0/opencode-plugin 同时注册同名工具。启动前设置组件 Key：

export METAMEM_API_KEY="你的 MetaMemory 组件 Key"
export METAMEM_MEMORY_COMPONENT="mem0_platform"
opencode --version
opencode

从项目仓库目录启动，修改配置后重启 OpenCode。默认平台为 https://metamemory.8-163-122-236.nip.io；受控本机测试可设置 METAMEM_BACKEND_URL=http://127.0.0.1:52943。组件 Key 不写入 opencode.json。插件传输适配兼容原有 MEM0_API_KEY，优先使用 METAMEM_API_KEY。

OpenCode 官方采用 plugin 配置加载插件。固定二进制也支持 opencode plugin <module> 安装命令；本页给出已用于验收的显式配置方式。独立 MCP 不包含本页的生命周期钩子和技能，也不作为这次原生插件验收路径。

工具与命令

七个命令为 /mem0-remember、/mem0-search、/mem0-tour、/mem0-status、/mem0-scope、/mem0-forget、/mem0-context-loader。它们加载相应官方技能，由模型执行；固定包没有 /mem0-dream 或 /mem0-pin。

平台内嵌宿主会把 shell 操作交给原生权限对话框；无人确认时记录实际拒绝，不自动放宽权限。候选网关分支开放十个工具；共享官方 Mem0 凭据的对照分支仍封锁三个无独立授权的管理工具。删除测试请使用专用项目与测试身份，并核对实际 ID、范围和删除结果。

范围与生命周期

项目身份由 Git remote、仓库根目录或当前目录产生。/mem0-scope 把默认范围保存到 ~/.mem0/settings.json，每次工具操作重新读取。跨项目操作须先显式启用 /mem0-scope global；全局删除还须明确传 scope:"global"。平台验证账户身份并映射到后端隔离空间。global_search:true 是跨用户搜索，平台共享凭据路径不开放。

自动捕获只保存选中用户提示的脱敏全文，不保存完整助手会话；来源会话在 metadata.session_id，没有顶层 run_id，因此 session 检索不包含这些自动写入。每轮结束不等待后台提取完成。压缩写入也是异步提交；必须检查事件与实际记录，PENDING、HTTP 200 或模型说已保存都不足以证明持久化。

用户验收

1. /mem0-status 核对连接和当前身份，/mem0-scope project 确认范围。
2. 用 add_memory 和 infer:false 保存唯一测试码，查看实际事件和记忆 ID。
3. 新开会话，用 /mem0-search 查回同一测试码；核对新会话与工具结果。
4. 分页浏览、更新、按 ID 读取，再用 /mem0-forget 只删除该记录，确认读取不到。
5. 在专用测试项目分别测试 project/session/global 隔离；批量删除和实体删除仅针对自己创建的测试空间。
6. 连续三条有效提示测试自动捕获，再核对后端 auto_capture 来源；压缩、错误召回和权限拒绝分别检查真实行为。

逐项验收结果及剩余缺口见项目研究文档《metamem宿主验收-OpenCode-20261008》，不能用基础 Add/Search 通过代替完整功能通过。

Mem0 官方集成说明 · OpenCode 官方插件配置

OpenClaw 接入 Mem0 Platform

MetaMemory 为 OpenClaw 提供固定版本的 Mem0 插件适配。记忆保存、检索、工具和记忆策略沿用官方插件；平台负责组件 Key 鉴权及账号、项目的存储隔离。

固定版本与验收状态

本轮固定 OpenClaw 2026.9.8、官方 Mem0 插件 1.2.1、mem0ai 3.0.7。MetaMemory 候选包名为 @metamem/openclaw-plugin，插件 ID 为 metamem，版本 0.1.0。本指南针对 mem0_platform。

本轮各项工程检查、实际证据和待验边界记录在仓库中的《metamem宿主验收-OpenClaw-20261008》。安装或连接成功不能代替工具、自动捕获／召回、范围、权限及公共页面的逐项验收。

安装

准备固定版本的 OpenClaw、MetaMemory 账号及具有 mem0_platform 使用权限的组件 Key。下载本轮提供的 metamem-openclaw-plugin-0.1.0-20261008.tgz 后执行：

openclaw --version
npm_config_legacy_peer_deps=true openclaw plugins install --accept-capabilities --force ./metamem-openclaw-plugin-0.1.0-20261008.tgz
openclaw plugins list

平台安装设置 npm 的 legacy peer 解析，安装冻结 SDK 的平台依赖。SDK 3.0.7 还声明了多种模型／向量库 peer，默认 npm 解析会安装整组依赖，实际安装耗时和包数量会明显增大。本轮固定 SDK 版本保持 3.0.7。

固定宿主要求本地来源确认；核对提供的 SHA256 和 provenance 后，--force 明确确认已审阅该来源，--accept-capabilities 接受包声明的能力。安装应在自己的 OpenClaw 配置中操作。不要同时占用同一个 memory slot 的其它插件。

在宿主配置 openclaw.json 中设置：

{
  "plugins": {
    "slots": {"memory": "metamem"},
    "entries": {
      "metamem": {
        "enabled": true,
        "hooks": {"allowConversationAccess": true},
        "config": {
          "mode": "platform",
          "apiKey": "${METAMEM_API_KEY}",
          "userId": "alice-project-a",
          "baseUrl": "https://metamemory.8-163-122-236.nip.io/metamem/mem0_platform",
          "skills": {
            "triage": {"enabled": true},
            "recall": {"enabled": true, "strategy": "smart"}
          }
        }
      }
    }
  }
}

将自己的完整组件 Key 通过宿主的私有环境／凭据配置提供给 METAMEM_API_KEY。上面的 ${METAMEM_API_KEY} 是 OpenClaw 的环境引用，插件也保留官方 MEM0_API_KEY 配置习惯；不要把凭据写入聊天、安装包或共享日志。固定包内没有组件 Key。

userId 应在同一项目内跨会话保持稳定。平台 Playground 的身份由服务器绑定账号和项目，聊天请求不能选择密钥、端点或宿主路径。原生工具中的 userId／agentId 只在当前已授权账号和组件范围内生效。

原生会话访问授权

OpenClaw 2026.9.8 默认禁止非内置插件访问会话钩子。上述 hooks.allowConversationAccess:true 是对当前 metamem 插件的显式授权，允许它在回答前处理提示、在轮次结束后处理对话以完成记忆功能。未授权时宿主会阻止 before_prompt_build 和 agent_end；工具已加载也不代表自动召回／捕获已启用。请仅在自己的专用配置中授予需要的权限。

两种原生记忆策略

skills 模式不受 autoCapture／autoRecall 控制，应通过 skills.recall.enabled 和 strategy 控制召回。legacy 模式会跳过 cron、heartbeat、automation、schedule 等非交互触发；子智能体不能新增或删除记忆。当前轮若已调用新增／更新／删除工具，legacy 会跳过重复自动捕获。

自动捕获会过滤噪声、清理凭据和工具上下文，并要求有效用户内容至少 50 字符。显式工具和 CLI 会把用户提供的内容发送给平台，应自行避免录入敏感凭据。异步提交和“Stored”提示不是最终持久化证明，需要读取记忆或查询事件终态。

原生工具

OpenClaw 2026.9.8 可通过宿主的 tool_search／tool_call 分发这些工具。memory_add 默认 longTerm:true；设为 false 时写入当前宿主会话的 run_id。agentId 对应派生用户命名空间 基础userId:agent:智能体ID，不是单独的 Mem0 agent_id 字段。

scope:"session" 需要当前宿主 sessionKey；未建立会话时不返回会话库存。按用户查询的 long-term 原生路线没有额外排除带 run_id 的记录，不能据名称推断它只包含长期记录。平台会话 ID 与原生 sessionKey 不可互换。

删除确认与权限

原生单条 ID 删除不额外弹窗；按查询删除在只有一条匹配或第一条得分大于 0.9 时会直接删除，否则返回候选，需再指定 ID。全量工具删除要求明确 confirm:true。CLI 全量删除在非交互环境必须传 --confirm；交互环境会要求输入 yes，其它输入取消。

平台仍按组件 Key、账号和归属校验每次请求。工具确认门槛与平台权限是两层不同控制；跨账号 ID、超范围过滤、已撤销或过期的 Key 应被拒绝。

CLI 与配置

候选保留原生命令前缀 openclaw mem0：

openclaw mem0 add "项目数据库使用 PostgreSQL"
openclaw mem0 search "项目数据库" --scope long-term --json
openclaw mem0 get <memory_id> --json
openclaw mem0 list --json
openclaw mem0 update <memory_id> "项目数据库使用 PostgreSQL 17" --json
openclaw mem0 delete <memory_id> --json
openclaw mem0 delete --all --user-id alice-project-a --confirm --json
openclaw mem0 event list --json
openclaw mem0 event status <event_id> --json
openclaw mem0 status --json
openclaw mem0 config get user_id --json
openclaw mem0 config set auto_recall false --json

status 的 connected:true 只证明相应连接探测。CLI 可能以进程退出码 0 返回带 ok:false 的错误，验收需同时检查 JSON 和实际库存。

候选的配置命令读取 plugins.entries.metamem.config，优先使用 OPENCLAW_CONFIG_PATH，其次 OPENCLAW_STATE_DIR/openclaw.json，最后宿主默认配置。与较早候选相比，这修正了仍读取旧插件身份和默认目录的问题；不同项目请使用独立宿主配置。

rerank、keywordSearch 等字段保留在冻结配置 Schema 中，不代表该版本召回实现实际执行了这些步骤。CLI init 的账号验证码流程尚未完成本轮端到端验收，本轮安装使用现有 MetaMemory 组件 Key 的手动配置。

错误与恢复

对 401、额度不足、撤销 Key、未知写入结果，保留原始终态，不自动换 Key、替换后端或重发写入。原生召回失败可能降级为不注入记忆，模型回答完成不能证明记忆功能成功；查看工具错误和实际库存。

平台运行器按请求 ID 记录回执。同一请求只在内容指纹一致时复用已有回执；未闭合的 in-flight 标记返回 unknown，不重放。需恢复时先只读核对事件／库存，再决定是否创建新的明确操作。

用户逐项验收

1. 核对固定宿主、候选包和 SDK 版本及包的 SHA256；确认插件原生加载并出现 8 个工具。
2. 同一项目保存新事实，新会话不提示工具名称地提问；核对答案、原生召回证据和实际记录。
3. 分别验证 skills 显式保存与 legacy 自动捕获，确认模式切换按配置生效。
4. 核对 session、另一个会话、另一个项目和智能体命名空间的哨兵记录，验证范围。
5. 对专用测试记忆执行读取、列表、更新、删除与事件查询，确认最终库存；验证全量取消／确认。
6. 校验配置写入正确候选插件和指定目录；验证外部项目、无权限及撤销 Key 的拒绝结果。
7. 在平台原生页面完成当前制品的安装绑定、保存和跨会话召回；完成后清理专用记录、撤销测试 Key。

Pi Agent：Mem0 Platform 集成

本页对应 Pi 1.0.3、官方 @mem0/pi-agent-plugin 0.3.2、MetaMemory 候选包 @metamem/pi-plugin 0.1.0+pi20261008 和 mem0ai 3.3.1。候选包保留官方工具、命令、技能与生命周期，仅将 Mem0 客户端接到 MetaMemory 的 mem0_platform 入口。

候选安装、命令、单条管理、自动捕获、范围检索、新会话召回与三种范围的批量删除均已有真实证据。开发功能检查已完成，完整用户验收仍待完成。mem0_platform 是 Mem0 Platform 存储，本页不涵盖 Mem0 OSS。

安装候选包

使用本次交付的 metamem-pi-plugin-0.1.0-pi20261008.tgz，核对交付收据中的 SHA-256。尚无本页承诺的 npm 发布地址；不要用未固定 Git 分支替代该制品。

pi --version
# 本次验收版本：1.0.3
tar -xzf metamem-pi-plugin-0.1.0-pi20261008.tgz
mv package metamem-pi-plugin
cd metamem-pi-plugin
npm install --omit=dev --ignore-scripts --legacy-peer-deps
cd ..
pi install ./metamem-pi-plugin

本地目录安装不会自动安装该目录的 npm 依赖，因此先运行上面的 npm install。Pi 自己提供 peer dependencies；交付包的 mem0ai 固定为 3.3.1。安装后保留该目录，Pi 的设置引用它。官方原包与候选包会注册同名工具及命令，同一 Pi 会话只启用一个。

配置候选包实际读取的环境变量：

read -rsp 'MetaMemory 组件 Key: ' MEM0_API_KEY
echo
export MEM0_API_KEY
export MEM0_USER_ID="pi-acceptance-your-unique-test-user"
export METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io/metamem/mem0_platform"

MEM0_API_KEY 放 MetaMemory 组件 Key。METAMEM_BACKEND_URL 必须包含 /metamem/mem0_platform；网站根 URL 会被此包拒绝。此候选包不读取 METAMEM_API_KEY 或 METAMEM_MEMORY_COMPONENT。启动新 Pi 会话，执行 /mem0-status，核对连接、用户、项目与数量。

配置

可选文件为 ~/.pi/agent/mem0-config.json：

{
  "userId": "pi-acceptance-your-unique-test-user",
  "autoCapture": true,
  "contextInjection": true,
  "defaultScope": "project",
  "searchThreshold": 0.3
}

自动捕获与自动召回固定使用 project，即使显式默认范围改为 session 或 global。自动写入不带 run_id。修改配置后新建会话，以便重新加载。

原生功能

包中六个技能为 context-loader、remember、search、forget、tour、status。它们提供使用指导；已验证 Pi 安装后能发现全部六个技能。Pi 工具名为 mem0_memory：

0.3.2 的实包支持 update。官方网页仍显示 0.3.0，工具表未列出 update；本页按固定安装包的运行时能力说明。

范围与确认边界

同一仓库的子目录共享项目身份。不同 Git 仓库如根目录同名，原生 app_id 也相同；该检测方式不等于按完整路径唯一隔离。MetaMemory 的托管会话另有账号/项目身份绑定。

/mem0-forget 的单条确认取消后不会删除；多个匹配使用选择框，选中后立即删除，不再出现第二个确认框；取消选择不会删除。本次单条确认与多条选择的取消/批准均通过真实原生 UI 通道脚本验证，尚未将用户亲自在终端/浏览器点选的验收记为完成。

工具 add/update/delete/delete_all 不会自动弹出确认框。 单条 update/delete 按后端记录 ID 操作；提供 scope 不会让官方工具先查询并验证该 ID 所属范围。

平台批量删除保护： 官方原包直连 Platform 的组合 deleteAll 会扩大到其它实体范围，本次真实对照保留了这个失败。MetaMemory 网关对组合身份先以 AND 检索库存、严格核对实体归属，再按确切 ID 删除并验证终态；兼容后端返回的 session_id 会归一为 run_id，冲突或外来身份仍被拒绝。这是平台对原版删除语义的有意保护，Pi 原生插件代码保持不变。本轮全新隔离用户的 session 删除保留三个控制记录，project 删除保留其它项目和 global，显式 global 删除后为空，三项均通过。删除依据验证过的库存快照，不宣称会包含删除过程中并发新增的记录。

自动捕获与召回

before_agent_start 先调用 project 搜索，把结果和策略加入 system prompt；agent_end await Add 提交。Add 可能返回 PENDING，插件不自动轮询 event_id，所以“Memory stored.” 或提交完成不等于提取已经成功。验收必须在新会话查到同一事实。

自动捕获仅提取用户与助手的文本，脱敏后保存，不再采用原来的每条 6000 字符截断。自动召回上下文也脱敏；显式 /mem0-remember 原样保存，显式工具结果不保证再次脱敏。工具展示保留原生 200 行 / 50 KB 截断，并可能附加截断提示。

sequenceDiagram
    participant H as Pi 1.0.3
    participant P as Mem0 plugin 0.3.2
    participant G as MetaMemory
    participant M as Mem0 Platform
    H->>P: before_agent_start
    P->>G: project search
    G->>M: 已认证身份映射与查询
    M-->>P: 记忆证据
    P-->>H: 策略与召回上下文
    H->>P: agent_end
    P->>G: Add 提交
    G->>M: 保存 / 提取
    M-->>P: 原生响应，可能 PENDING

用户逐项验收

在专用测试身份、测试仓库中进行，使用自己生成的唯一代号：

1. /mem0-status 核对身份与连接；确认六个命令、六个技能可用。
2. /mem0-remember PI-YOUR-UNIQUE-CODE 是测试验收代号，随后 /mem0-search PI-YOUR-UNIQUE-CODE，核对原文、分类与 ID。
3. 新建会话，只问“测试验收代号是什么”，核对答案来自记忆；不要把代号放进问题。
4. /mem0-tour project，再让代理用 get_all 浏览；对自己刚创建的单条 ID 执行 update，查回新内容。
5. /mem0-forget PI-YOUR-UNIQUE-CODE，先取消后重新搜索应仍存在；再确认删除，搜索并核对该 ID 已不存在。
6. 在同一会话切 /mem0-scope session、保存第二个唯一代号；新会话 session 应看不到，project 仍能看到。显式切 global 后再测试跨项目检索。
7. 普通对话提供新的测试偏好、不调用记忆工具；等待提取完成后新建会话召回，验证自动捕获。分别关闭 autoCapture、contextInjection 并重新建会话，核对开关行为。
8. 在独立测试身份准备 session、project、其它项目与 global 控制记录，明确要求 delete_all scope=session 后核对其它三条仍在；再以 project 删除后核对其它项目/global 仍在，最后显式开启 global 删除并核对为空。不要以提交提示代替实际记录核对。

界面显示 Native integration configured 只说明能运行。用户逐项签收、真实效果和完整正式评测仍需分别记录。本轮没有评测记忆准确率或证明 SOTA；实际模型返回名称也不等于配置模型身份已经核验。

Mem0 官方 Pi 说明 · 官方删除说明

DeepSeek Harness

为 DeepSeek Harness 提供原生记忆工具、基于已提交用户历史的自动召回与完成回合捕获。空历史新会话的首轮不会自动搜索记忆；第二轮提示组装可使用上一轮已提交的用户消息搜索。

前置条件

DeepSeek Harness、已配置的宿主模型、MetaMemory 账号与组件 Key。2026-10-08 的本地验收使用官方 Harness 0.2.0-rc.2、官方 Mem0 插件 0.3.2 和基于该冻结插件构建的 @metamem/deepseek-plugin 0.1.0。安装插件时保留其 mem0ai 与 Harness peer dependencies，不能仅复制一个 dist/index.js。

安装

curl -fLO https://metamemory.8-163-122-236.nip.io/metamemory-docs/downloads/metamem-deepseek-plugin-0.1.0-20261008-r3.tar.gz
tar -xzf metamem-deepseek-plugin-0.1.0-20261008-r3.tar.gz
cd metamem-deepseek-plugin-0.1.0-20261008-r3
npm ci --ignore-scripts --no-audit --no-fund

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

export DSH_HOME="$PWD/.dsh"
npx --no-install dsh --version

配置

安装包的锁文件同时固定 Harness 及其框架依赖为 0.2.0-rc.2、SDK 为 3.3.1。无需再向另一个 profile 安装插件。在 Harness 的 Cordis 配置中注册安装目录内的模块：

- insert:
    - id: metamem
      name: "/你的安装目录/node_modules/@metamem/deepseek-plugin/dist/index.js"
      config:
        userId: alice
        host: https://metamemory.8-163-122-236.nip.io
        autoRecall: true
        autoCapture: true

将配置保存为 cordis.yml，把模块路径改为当前安装目录的绝对路径。使用同一 DSH_HOME 和 headless profile，宿主模型须已配置：

printf '%s\n' '请记住我的项目验收代号是 demo-apple；简短回答。' \
  | npx --no-install dsh --profile headless --patch ./cordis.yml --json -

工作原理

turn/end 的原因为 completed 时，插件后台提交本轮用户与助手消息。服务端提取是异步的；看到模型完成或 Add 返回并不等于记忆已经可检索。

官方 Harness 在提示组装后才提交当前用户消息。插件从 deriveMessages() 中选择 role=user 且 source.kind=user 的最后一条已提交消息；因此新会话首轮没有搜索请求，第二轮搜索的是先前用户消息。新会话先问一次目标问题，再在同一会话重复该问题，才能验收这条原生自动召回路径。召回等待保留官方 2000ms，失败或超时会继续模型回答。

召回结果通过 mem0:recall context 进入模型请求。该版本宿主可将 context 持久化为用户角色的提示上下文消息；不能仅检查 HTTP 请求的 role=system 判断是否注入。

智能体工具

记忆范围

自动捕获和召回使用配置的 userId。显式工具可以在保存和查询时传递相同 agentId、runId。自动操作不会自动附带项目或会话 app_id/run_id。平台页面接入额外把账号与项目派生为稳定 userId，并由组件 Key 做账号隔离；直接安装时须自行为每个账号／项目设置不同的稳定 userId。

2026-10-08 的真实成对测试中，默认 userId 自动捕获／召回路线已独立通过，agentId/runId 的原版工具到 SDK 参数传递也已证实。但在保持默认异步提取、原过滤不变的高级实体测试中，两侧物化记录均缺少 agent_id，随后带 agent/run 的搜索正控均返回空。因此高级实体持久化／检索保证尚未通过，不能将这些参数视为已验收的范围保证。原版 Mem0 直连与 MetaMemory 候选保留相同失败边界；没有调整 infer 或放松过滤。候选返回的 run_id 匹配，官方 GET 使用 session_id 字段，不将别名差异判为 run 丢失。

遥测

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

参数默认值

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

生命周期

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

本地验收步骤

1. 在独立测试账号／项目的新会话说“请记住我的验收代号是 <唯一代号>”，确认最终回答和宿主完成事件。
2. 在记忆管理页等到该代号实际出现，再开启另一个会话。
3. 新会话首次问“我的验收代号是什么？只用自动提供的记忆，不调用工具”，再在同一会话重复一次。分别记录首轮没有召回、第二轮检索结果、上下文与完整最终答案。
4. 切换另一账号和另一项目查询同一代号，均应不可见；随后仅删除该测试账号／项目的测试记录。

真实自动捕获／召回、显式工具、页面集成和用户验收是不同边界。上述 headless 回执不能替代页面安装、浏览器点击或当前公开分发包的验收。

<!-- NATIVE SEQUENCE BEGIN -->

调用时序 / Call sequence

只有 completed 回合才将收集的用户／助手消息后台提交，取消或异常结束不自动写入；提示组装从已提交的用户历史搜索并注入 mem0:recall 上下文。空历史首轮跳过搜索。原生工具 search_memory / add_memory 支持显式操作。

Only completed turns submit collected user/assistant messages in the background. Prompt assembly searches the latest committed human message and injects mem0:recall context; an empty first-turn history skips search. Native search_memory / add_memory tools support explicit operations.

sequenceDiagram
    participant H as DeepSeek Harness
    participant P as Native plugin
    participant G as MetaMemory gateway
    participant M as Mem0 backend
    H->>P: system-prompt/assemble before current user commit
    alt Previous committed human message exists
    P->>G: search previous human message (2000ms deadline)
    G->>M: Authorize, bind identities, route
    M->>G: Memory evidence / native records
    G->>P: Preserve backend receipt
    P->>H: Inject context before answer
    else Empty committed human history
    P->>H: Continue without recall context
    end
    H->>H: Commit current user message and run model
    H->>P: session/event turn/end completed: background Add
    P->>G: Submit Add (host policy)
    G->>M: Store / extract memories
    M->>G: Event / final write receipt
    G->>P: PENDING is not SUCCEEDED

记忆范围 / Memory scope

自动召回 filters 仅 user_id，自动捕获同样只带 userId；原生工具可选 agentId／runId。没有原生 project app_id 自动检测，平台项目隔离是额外绑定，不能说成宿主原生支持。

Automatic recall filters by user_id only; automatic capture also sends userId only. Native tools accept and forward optional agentId/runId. The default userId route passed independent live checks. In the 2026-10-08 live paired advanced-scope check, materialized records lacked agent_id and matching agent/run searches returned no results on both routes; advanced entity persistence and retrieval guarantees remain failed. The default inference policy and original filters were preserved. There is no native automatic project app_id detection; platform project isolation is an additional binding.

MetaMemory retains native plugin behavior and routes authenticated requests to the selected backend. mem0_platform and mem0 are separate Platform and OSS stores; source implementation does not imply installation or acceptance.

Mem0 官方说明 / Official guide

<!-- NATIVE SEQUENCE END -->

Hermes Agent

MetaMemory 为 Hermes 提供独立的 metamem 外部记忆 provider。本次适配使用官方独立 Mem0 插件 1.3.0 的冻结源码，保留原生召回、捕获及四个工具；通过 MetaMemory 组件 Key 连接 mem0_platform。

已核对的组合为 Hermes 0.21.5、Python 3.11+、mem0ai==2.0.10、httpx==0.28.1，MetaMemory 插件版本为 0.1.0。Hermes 内置 mem0 provider 和本插件来源不同；memory.provider 必须选择 metamem。

安装

下载并解压 固定插件安装包：

curl -fLO https://metamemory.8-163-122-236.nip.io/metamemory-docs/downloads/metamem-hermes-plugin-0.1.0-20261008.tar.gz
tar -xzf metamem-hermes-plugin-0.1.0-20261008.tar.gz

将目录复制到当前 Hermes profile 的用户插件目录。已有 metamem 时先备份并核对版本，避免覆盖正在使用的插件。

export HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
mkdir -p "$HERMES_HOME/plugins"
test ! -e "$HERMES_HOME/plugins/metamem" && cp -R metamem-hermes-plugin-0.1.0-20261008 "$HERMES_HOME/plugins/metamem"

依赖必须安装在 Hermes 实际使用的 Python 环境。以下路径换成该环境的解释器：

/path/to/hermes/.venv/bin/python -m pip install 'mem0ai==2.0.10' 'httpx==0.28.1'

Hermes 0.21.5 的 hermes plugins install 接收 Git URL／仓库标识；直接传本地解压目录会被当作仓库标识。本地包使用上述用户插件目录安装方式。hermes plugins list --user --json 可核对实际发现的插件。

配置 Mem0 Platform

为当前 profile 设置组件 Key 和 MetaMemory 入口：

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 config set memory.provider metamem

在 ${HERMES_HOME}/mem0.json 设置稳定身份：

{"mode":"platform","host":"","user_id":"alice","agent_id":"hermes","rerank":false,"sync_max_chars":450}

配置文件只放非密钥项；Key 可写入当前 profile 的 .env，权限设为 0600。插件兼容 MEM0_API_KEY，两个名字同时存在时优先使用 METAMEM_API_KEY。非空文件配置覆盖 MEM0_MODE、MEM0_USER_ID、MEM0_AGENT_ID 等环境默认值。

保持 host 为空，并清除旧 profile 中的 MEM0_HOST；该字段选择原生自托管 HTTP 服务，会绕过平台 SDK 路线。MetaMemory 网关地址放在 METAMEM_BACKEND_URL，也支持完整 /metamem/mem0_platform 路径。

交互配置使用 hermes memory setup metamem，选择 Platform，填写 MetaMemory 组件 Key。这个固定宿主不接受 memory setup --mode 一类未列出的选项。执行 hermes memory status 后新建会话；installed／available 只证明发现插件和配置就绪，还需实际保存、检索验证连接。

原生功能

回答前按当前问题召回，最多等 3 秒；慢请求可能不进入本轮上下文，仍可使用 mem0_search。回合完成后后台发送用户消息与回答，用 infer=True 提取事实；默认每条最多 450 字符。后台捕获与显式 Add 是独立路径，关闭 provider 前要等后台线程排空。

工具缺少必填参数时在本地返回错误；未知工具不会派发请求。连接失败累计五次后暂停调用 120 秒，冷却结束后新的操作可恢复。冷却并不证明旧写入失败；超时或未知写入不要自动重放，应先查事件和该身份库存。

身份与权限

搜索以 user_id 为范围；同一身份可跨会话、agent 和渠道召回。写入同时带 agent_id 和 metadata.channel，不带原生项目 app_id 或会话 run_id。不同用户设不同 user_id；hermes-user 是占位默认值，未显式配置时优先使用渠道传入的用户身份。

平台 Playground 由服务端绑定账户、项目、组件 Key 和稳定的 Hermes 用户身份，并使用独立 profile。项目隔离属于平台授权与身份映射，不能当作 Hermes 原生项目范围。客户端不能替换执行器的密钥、模型路由或宿主目录。

hermes memory off 关闭外部 provider；hermes plugins disable metamem 使用户插件不可加载。内置文件记忆与外部 provider 有各自开关。memory reset 处理内置文件记忆，不是 Mem0 云端批量删除。

逐项验收

使用新的专用用户身份与项目，保存一条容易识别的偏好；核对写入事件与库存，再在新会话召回。取实际搜索返回的 ID 更新，重新读取确认文本变化，删除后读取应返回不存在。另建用户／项目哨兵，确认修改和清理只影响本次专用数据。

安装包附 metamem-provenance.json，记录冻结官方插件版本及文件摘要；README 与本指南一致。功能证据、未通过项及清理结果见项目中的独立 Hermes 验收文档。网页加载、配置 available、工具受理和存储终态须分别核验。

官方插件还提供原生 self-hosted／OSS 配置分支；本次交付验收范围是 mem0_platform。

官方独立插件源码 · Mem0 Hermes 文档

DeerFlow：Mem0 Platform 接入

DeerFlow 2.1.0 已内置 Mem0Manager。在本平台选择 DeerFlow、mem0_platform 和 metamem 即使用这条路径；平台通过官方 Python Mem0 2.0.20 SDK 绑定服务地址、账号和项目身份，保留 DeerFlow 自己的消息过滤、捕获、检索和错误策略。

这一宿主没有独立 npm 插件，也没有 /mem0-remember、/mem0-forget 等斜杠命令。Mem0 Platform 与自建 Mem0 OSS 是两个存储，本文只验收 mem0_platform。

固定版本与安装

本次冻结 DeerFlow runtime 为 345f08be00c8a9495079b732a39b46aa9af1584e，包元数据为 deerflow-harness 2.1.0，Python 为 3.12.13。原生 Mem0 后端六个文件已与本仓库来源清单逐文件核对。

已安装本平台托管宿主的用户无需重复安装。自行部署 DeerFlow 时，先安装此固定宿主版本，再配置内置后端：

git clone https://github.com/bytedance/deer-flow.git deerflow-mem0
cd deerflow-mem0
git checkout 345f08be00c8a9495079b732a39b46aa9af1584e
cp config.example.yaml config.yaml
cd backend
uv sync --frozen
uv run deerflow --help

帮助页应包含 --print、--json、--continue 和 --resume THREAD。上面是固定源码及 lockfile 的复现路径；本次已核验现有固定环境的加载和实际执行，不把一次帮助页检查称为全部依赖的全新安装验收。

配置内置后端

在账号的组件 Key 页面取得 MetaMemory 组件 Key，通过环境变量传入，勿把真实 Key 写入 YAML。将固定源码 config.yaml 中的 memory 段替换为：

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/mem0_platform
    allow_insecure_http: false
    top_k: 8
    score_threshold: 0.1
    max_injection_chars: 12000
    timeout_seconds: 30
    startup_policy: fail_fast
    failure_policy:
      read: fail_closed
      write: raise

在同一终端设置 MEM0_API_KEY，配置原有回答模型并运行 uv run deerflow --print '请记住我的偏好：回答时先给结论。'。保留 DeerFlow 原有模型、认证和角色配置。地址必须含 /metamem/mem0_platform；服务端不会接受一个组件 Key 作为托管智能体的执行授权。

平台内部使用 metamemory_host_adapters.deerflow.sdk:UnifiedSDKMem0Manager，由服务端绑定 SDK factory 后加载。自行部署上述内置 HTTP 后端使用 manager_class: mem0 即可；不要仅修改类名却省略 factory 绑定。

实际原生能力与范围

mode: tool 提供按问题的 memory_search，且该后端仍保留 passive conversation capture。原生工具列表可能还注册另外三个事实工具，它们对这个后端仍为 unsupported；不要把工具名称存在当作能力可用。

托管配置默认 middleware，服务端可用 memory_mode: tool 选择另一模式，普通会话请求无法覆盖它。injection_enabled 是独立开关：本次配置为 true，固定版 prompt 在 tool 模式也会先自动读库存，随后模型可调用 search，回答后仍 passive capture。仅关闭注入才是不先读库存的工具模式；本次未把该另一配置标成已验收。上传块会从捕获文本去除；仅上传而没有文字的 user 及随后确认回答会跳过，多模态内容仅提取文本块。

原生身份映射为 user_id → user_id、agent_name → agent_id、thread_id → run_id，不发送 app_id。组合筛选使用 AND。平台 user 标识由账号和项目共同派生，同一个账号的不同项目有不同 user 标识；会话单独派生 run 标识。跨会话注入默认不限制当前新 thread，否则会读不到旧会话的记忆。工具的 agent 范围由原生运行上下文提供，不能通过模型文字另选其它账号或项目。

**双实体限制：**传入 user 和 agent 不代表每条提取事实都会同时保存两个字段。2026-10-08 实测中，五次原生 Add 都到达 SUCCEEDED，用户事实的 agent_id 却为 null；随后 AND(user, agent) 得到空库存。Mem0 官方说明（2026-09-28 更新）也记录了默认 infer=True 提取链可能省略 agent 字段。原版组合筛选保持不变，该组合下的自动捕获与召回不能保证通过；不要为了显示成功删除 agent 条件，或把默认提取改成原文存储。默认托管路径若未传 agent，按账号与项目派生的 user 范围验收。独立用户仍应验证自己实际使用的 agent 配置。

写入终态、错误和恢复

原生 add / aadd 只提交一次，不主动轮询事件；PENDING、一次回答结束、或 HTTP 200 都不是落库成功。平台页面可以显示“记忆写入未确认”；验收时还需查看同一事件的终态和随后库存。异步 a* 方法通过 asyncio.to_thread 执行同步 HTTP，避免阻塞宿主事件循环。

fail_closed 读取失败会终止依赖记忆的回答；fail_open 会记录故障并返回空记忆。raise 写入失败向宿主抛错；log_and_drop 记录并丢弃，没有重试队列。超时或断线后的未知写入不要自动重发，先只读查原事件和原范围库存。更换会话只改变会话 thread，不清除项目的长期记忆；同一会话恢复使用原生 checkpoint。

用户逐项验收

默认配置的本轮真实捕获、新会话召回、工具检索、checkpoint 恢复，以及 user/project 范围管理均已完成，全部测试记录清理、临时授权撤销。自动验收证据和“用户验收”分别登记在宿主适配清单；双实体限制单列保留，根进程公网复核和用户逐项验收仍待登记，不用旧 Add/Recall 代替全部能力。

原生边界可对照固定版 Mem0 后端说明。

<!-- NATIVE SEQUENCE BEGIN -->

调用时序 / Call sequence

该图对应本仓库冻结 DeerFlow MemoryManager 后端。开启 injection 时 get_context 没有当前 query，读取范围内最近记忆；tool 模式还允许智能体按问题调用 search。add 只提交已过滤 user／assistant 消息，原生不轮询事件；aadd 通过 asyncio.to_thread 包装同步提交。不要将列库宣传成按当前问题的语义搜索。

This diagram describes the repository’s frozen DeerFlow MemoryManager backend. With injection enabled, get_context lists scoped memories without a query in either mode; tool mode also lets the agent search for its question. add submits filtered messages without polling events; aadd uses asyncio.to_thread. Inventory injection is not query-aware semantic search.

sequenceDiagram
    participant H as DeerFlow
    participant P as Native Mem0Manager
    participant G as MetaMemory gateway
    participant M as Mem0 backend
    H->>P: MemoryManager.get_context when injection enabled
    P->>G: get_all, plus model-directed search in tool mode
    G->>M: Authorize, bind identities, route
    M->>G: Memory evidence / native records
    G->>P: Preserve backend receipt
    P->>H: Inject context before answer
    H->>P: MemoryManager.add / aadd: filter and submit messages
    P->>G: Submit Add (host policy)
    G->>M: Store / extract memories
    M->>G: Event / final write receipt
    G->>P: PENDING is not SUCCEEDED

记忆范围 / Memory scope

原生 user_id → user_id，agent_name → agent_id，thread_id → run_id；没有 app_id。平台 project_id／conversation_id 通过已授权绑定映射独立 user／run 标识，构成额外项目隔离。新会话跨会话检索需不把新 thread_id 限定为唯一来源。

Native user_id maps to user_id, agent_name to agent_id and thread_id to run_id; no app_id is sent. The platform maps authorized project_id/conversation_id to isolated user/run identities for additional project isolation. Cross-session recall must not restrict evidence to the new thread_id.

MetaMemory retains native plugin behavior and routes authenticated requests to the selected backend. mem0_platform and mem0 are separate Platform and OSS stores; source implementation does not imply installation or acceptance.

<!-- NATIVE SEQUENCE END -->

算法工程 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。