快速开始

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 的标准方法。组件特有复盘、巩固等操作仅在明确声明的扩展能力中提供；未完成的能力不能作为通用接口承诺。

宿主记忆插件

将 MetaMemory 接入你正在使用的智能体，让它在新会话中读取项目背景和个人偏好。选择宿主，按指南完成安装、连接和第一条记忆的保存。

开始使用

1. 在 MetaMemory 账号中取得 Mem0 Platform 组件 Key。
2. 打开对应宿主指南，下载安装包并配置连接。
3. 保存一条事实，搜索确认后，新建会话再次提问。

选择宿主

托管控制台已配置宿主时，无需重复本机安装。不同宿主的配置变量和工具名称不同，请使用对应指南。

记忆如何生效

插件按宿主的规则捕获对话或接收主动保存请求，之后在新会话中读取记忆。后台保存可能需要等待；先确认事实可读取，再判断跨会话记忆是否生效。

只需要远程工具时，可以使用远程 MCP。完整插件的自动捕获和本地技能需按宿主安装。

Codex

为 Codex 提供跨会话的项目背景和个人偏好记忆。插件包含搜索、保存指导、暂停和清理等技能；会话内容由宿主钩子捕获并在后台保存。

准备

需要 Codex 0.160.0、Python 3.10+、Git，以及 MetaMemory 的 Mem0 Platform 组件 Key。插件版本为 0.1.0。

1. 安装插件

下载 Codex 插件，解压后将下面的路径改成 marketplace 根目录的实际绝对路径：

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 钩子管理界面审阅并启用插件钩子，然后新建会话。

2. 配置连接

read -rsp 'MetaMemory 组件 Key: ' METAMEM_API_KEY
echo
export METAMEM_API_KEY
export METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io/metamem/mem0_platform"
export METAMEM_MEMORY_COMPONENT="mem0_platform"

从配置了这些变量的终端启动 Codex。需要自定义身份时，使用稳定的 MEM0_USER_ID 和 MEM0_PROJECT_ID；同一项目的新会话应保持身份一致。随后执行 $metamem:status 检查状态。

3. 保存和读取

$metamem:remember 本项目数据库迁移必须支持回滚
$metamem:search 数据库迁移约定 --scope repo

remember 会把事实交给会话捕获流程；保存通常在后台提交、会话结束或压缩时完成。先等搜索能查到该事实，再新建会话问“数据库迁移有什么要求？”。

调用时序

常用技能

repo 查本仓库个人与共享记忆，mine 只查本人的仓库记忆，dir 缩小共享项目的目录范围。记忆搜索工具为 search_memories；此插件没有独立的库存、单条更新或按 ID 删除工具。

清理记忆

先暂停捕获并等待在途保存完成，再使用 $metamem:forget，确认个人／共享范围。云端删除与仅清本地数据是不同操作，按技能提示选择；共享项目记忆需要单独授权。恢复捕获后，新对话仍可生成记忆。

控制台中的流式对话

在“记忆组件宿主智能体集成体验”中使用原版 Mem0 或 MetaMemory 接入时，页面会随着宿主返回新的回答内容逐步显示正文。它使用本轮宿主实际生成的文字，不会把完成后的回答切成小段播放，也不会为流式显示重新调用模型或记忆服务。首段出现前，仍可能需要等待宿主启动、自动召回和模型生成。

工作详情在浏览器独立后台线程中整理，回答显示不等待详情处理。记忆召回、保存和会话延续仍遵循本指南中的宿主规则；文字开始出现不表示记忆已经保存成功，保存状态以已有事件或记录为准。

原版 Mem0 与 MetaMemory 两条路线的流式显示已完成本轮真实对话验收。这一结果只说明控制台的流式回答及完整终态通过；记忆是否保存成功，仍以本轮记忆事件或读写记录为准。

常见问题

卸载

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

卸载不会删除云端记忆。只需要远程搜索工具时，也可使用远程 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 插件后，可以主动保存和搜索记忆，也可以让插件在会话过程中自动捕获有用信息。

准备

需要 Claude Code、Python 3.10+、Git，以及 MetaMemory 账号的 Mem0 Platform 组件 Key。本指南适用于 Claude Code 2.1.289、MetaMemory 插件 0.1.0。请在 Git 项目目录中使用插件。

1. 下载并安装

下载 Claude Code 插件，解压后进入解压目录的上一级，执行：

claude --version
claude plugin marketplace add "$PWD/metamem-claude-20261008-merged-v1"
claude plugin install metamem@metamem-claude-20261008-merged-v1 --scope user

如果已安装另一份 Mem0 或 MetaMemory 记忆插件，先停用或卸载旧插件，避免重复捕获。

2. 配置连接

在启动 Claude Code 的终端中设置组件 Key 和服务地址：

read -rsp 'MetaMemory 组件 Key: ' METAMEM_API_KEY
echo
export METAMEM_API_KEY
export METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io/metamem/mem0_platform"
export METAMEM_MEMORY_COMPONENT="mem0_platform"
python3 -c 'import json,os; print(json.dumps({"api_key":os.environ["METAMEM_API_KEY"]}))' |
  claude plugin configure metamem@metamem-claude-20261008-merged-v1 --values-stdin
claude plugin list

重新启动 Claude Code，或在会话中执行 /reload-plugins。然后用 /metamem:status 检查连接及暂停状态。组件 Key 应保存在私有配置中，不提交到 Git。

3. 保存并读取第一条记忆

在项目会话中执行：

/metamem:remember 本项目数据库迁移必须支持回滚

插件会记录这段对话，并在会话结束、压缩或后台提交时提取记忆。命令的回复不代表记忆已立即保存；等待后台处理后，用下面的命令查找：

/metamem:search 数据库迁移约定 --scope repo --top-k 5

查到事实后，新建会话，再问“本项目数据库迁移有什么要求？”，检查是否读取到了之前的记忆。

调用时序

首次自动召回只检查新会话的第一条用户提示，默认要求至少 20 个字符。需要确保查到记忆时，直接使用 /metamem:search。

常用命令

搜索范围：repo 包含本仓库共享记忆和个人记忆；mine 只查本人的仓库记忆；dir 缩小共享项目记忆到当前目录。新会话要读取旧记忆，请保持同一账号和项目。

删除记忆

先执行 /metamem:pause，等待正在提交的内容处理完，再执行 /metamem:forget。阅读它给出的范围并确认后删除。个人仓库记忆与团队共享记忆分别授权；这个命令不支持按关键词只删某一条。

删除后可用搜索检查结果，再按需 /metamem:resume。恢复后新的对话可以继续产生记忆。

控制台中的流式对话

在“记忆组件宿主智能体集成体验”中使用原版 Mem0 或 MetaMemory 接入时，页面会随着宿主返回新的回答内容逐步显示正文。它使用本轮宿主实际生成的文字，不会把完成后的回答切成小段播放，也不会为流式显示重新调用模型或记忆服务。首段出现前，仍可能需要等待宿主启动、自动召回和模型生成。

工作详情在浏览器独立后台线程中整理，回答显示不等待详情处理。记忆召回、保存和会话延续仍遵循本指南中的宿主规则；文字开始出现不表示记忆已经保存成功，保存状态以已有事件或记录为准。

原版 Mem0 与 MetaMemory 两条路线的流式显示已完成本轮真实对话验收。这一结果只说明控制台的流式回答及完整终态通过；记忆是否保存成功，仍以本轮记忆事件或读写记录为准。

常见问题

Sidekick 可在独立 Git worktree 中执行子任务并继承已召回的上下文。它不自动复制原工作区未提交的修改；使用前确认任务需要的文件已经提交。

卸载

claude plugin uninstall metamem@metamem-claude-20261008-merged-v1

卸载本机插件不会自动删除云端记忆。

OpenCode

在 OpenCode 中保存、搜索和管理跨会话记忆，并自动召回项目背景。本指南适用于 OpenCode 1.18.34 和 MetaMemory 插件 0.1.0。

1. 安装插件

下载 OpenCode 插件，解压并安装依赖：

tar -xzf metamem-opencode-plugin-0.1.0.tgz
cd package
npm install --omit=dev --ignore-scripts --legacy-peer-deps

将以下条目合并到项目 opencode.json 或 ~/.config/opencode/opencode.json，使用解压目录内 dist/index.js 的绝对路径：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["file:///你的安装目录/package/dist/index.js"]
}

保留原有配置。不要同时启用另一份 Mem0 记忆插件。

2. 配置连接

read -rsp 'MetaMemory 组件 Key: ' METAMEM_API_KEY
echo
export METAMEM_API_KEY
export METAMEM_BACKEND_URL="https://metamemory.8-163-122-236.nip.io"
export METAMEM_MEMORY_COMPONENT="mem0_platform"
opencode

从要使用记忆的项目目录启动。执行 /mem0-status 查看连接及当前身份，用 /mem0-scope project 选择项目范围。

3. 保存和读取

请用 add_memory 保存“本项目数据库迁移必须支持回滚”，设置 infer:false。
/mem0-search 数据库迁移约定

等待记录可读取后，新建会话再次提问。插件还提供 /mem0-remember、/mem0-tour、/mem0-forget 和 /mem0-context-loader。

调用时序

记忆管理

project 是当前项目；session 是当前会话；global 跨本人项目，需要显式开启。/mem0-scope 会保存默认范围，批量清理前再次确认当前范围。

自动记忆与限制

插件会在对话中召回背景，每第三条满足长度要求的用户提示触发自动捕获；它不保存完整助手对话。自动捕获的记录不纳入当前版本的 session 检索，跨会话读取请使用 project 范围。

保存和压缩捕获可能在后台处理；PENDING 表示尚未完成，可通过事件状态或实际记录确认。单条更新和删除使用搜索返回的 ID，批量删除只对自己确认的范围执行。

控制台中的流式对话

在“记忆组件宿主智能体集成体验”中使用原版 Mem0 或 MetaMemory 接入时，页面会随着宿主返回新的回答内容逐步显示正文。它使用本轮宿主实际生成的文字，不会把完成后的回答切成小段播放，也不会为流式显示重新调用模型或记忆服务。首段出现前，仍可能需要等待宿主启动、自动召回和模型生成。

工作详情在浏览器独立后台线程中整理，回答显示不等待详情处理。记忆召回、保存和会话延续仍遵循本指南中的宿主规则；文字开始出现不表示记忆已经保存成功，保存状态以已有事件或记录为准。

原版 Mem0 与 MetaMemory 两条路线的流式显示已完成本轮真实对话验收。这一结果只说明控制台的流式回答及完整终态通过；记忆是否保存成功，仍以本轮记忆事件或读写记录为准。

常见问题

OpenClaw

为 OpenClaw 提供跨会话记忆，以及保存、搜索、更新和删除工具。本指南适用于 OpenClaw 2026.9.8 和 MetaMemory 插件 0.1.0。

1. 安装插件

下载 OpenClaw 插件，执行：

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

安装参数会接受包声明的能力并确认本地来源，请使用上面的下载包。只启用一个占用 memory slot 的插件。

2. 配置连接和会话权限

在启动 OpenClaw 的终端中设置组件 Key：

read -rsp 'MetaMemory 组件 Key: ' METAMEM_API_KEY
echo
export METAMEM_API_KEY

将下面的配置合并到自己的 openclaw.json：

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

userId 换成自己的稳定项目身份，同一项目的新会话保持一致。allowConversationAccess 允许插件在回答前召回、在对话后捕获；未授权时记忆工具可加载，但自动记忆不会生效。配置后重启 OpenClaw。

3. 保存和读取

openclaw mem0 status --json
openclaw mem0 add "本项目数据库迁移必须支持回滚"
openclaw mem0 search "数据库迁移约定" --scope long-term --json

保存可能返回异步事件。等待搜索或读取能确认事实后，再新建会话提问。

调用时序

选择保存方式

skills 模式通过 skills.recall.enabled、strategy 控制召回；manual 关闭自动召回。自动捕获模式要求有效用户内容不少于 50 字符，跳过定时任务等非交互触发。

常用操作

也可使用 openclaw mem0 get、list、update、delete、event list 和 event status。session 范围只用于当前会话；跨会话读取使用稳定的用户身份。

全量删除需要明确确认。CLI 示例：openclaw mem0 delete --all --user-id my-project-user --confirm --json。执行前核对用户范围；单条删除应使用读取到的实际 ID。

控制台中的流式对话

在“记忆组件宿主智能体集成体验”中使用原版 Mem0 或 MetaMemory 接入时，页面会随着宿主返回新的回答内容逐步显示正文。它使用本轮宿主实际生成的文字，不会把完成后的回答切成小段播放，也不会为流式显示重新调用模型或记忆服务。首段出现前，仍可能需要等待宿主启动、自动召回和模型生成。

工作详情在浏览器独立后台线程中整理，回答显示不等待详情处理。记忆召回、保存和会话延续仍遵循本指南中的宿主规则；文字开始出现不表示记忆已经保存成功，保存状态以已有事件或记录为准。

原版 Mem0 与 MetaMemory 两条路线的流式显示已完成本轮真实对话验收。这一结果只说明控制台的流式回答及完整终态通过；记忆是否保存成功，仍以本轮记忆事件或读写记录为准。

常见问题

当前推荐用组件 Key 完成配置。邮箱登录需要服务管理员启用邮件发送；具体可用性取决于所连接服务的配置。

Pi Agent

为 Pi 提供跨会话记忆、自动捕获和记忆管理。适用于 Pi 1.0.3、MetaMemory 插件 0.1.0。

1. 安装

下载 Pi 插件，执行：

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

保留安装目录。不要同时加载另一份 Mem0 插件。

2. 配置

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

本插件读取 MEM0_API_KEY，请填入 MetaMemory 组件 Key；地址需要包含 /metamem/mem0_platform。将用户身份换成自己的稳定值，启动 Pi 后执行 /mem0-status。

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

{
  "userId": "my-project-user",
  "autoCapture": true,
  "contextInjection": true,
  "defaultScope": "project",
  "searchThreshold": 0.3
}

3. 保存和读取

/mem0-remember 本项目数据库迁移必须支持回滚
/mem0-search 数据库迁移约定

查到事实后，新建会话再提问。保存处理中请等事件或记录可读取后再判断结果。

调用时序

常用命令和范围

mem0_memory 工具还支持按 ID 更新、删除及范围清理。project 对应项目，session 对应当前会话，global 跨本人项目；自动捕获和自动召回始终使用 project 范围。

删除和项目隔离

/mem0-forget 只有一个匹配时弹确认，多匹配时选择即删除。工具的更新、删除和批量清理没有额外弹窗，使用前核对范围及 ID。

项目身份取 Git 仓库根目录名称；同名仓库可能共享项目身份。需要隔离同名项目时，设置不同的 MEM0_USER_ID。同一仓库的子目录共享项目记忆。

控制台中的流式对话

在“记忆组件宿主智能体集成体验”中使用原版 Mem0 或 MetaMemory 接入时，页面会随着宿主返回新的回答内容逐步显示正文。它使用本轮宿主实际生成的文字，不会把完成后的回答切成小段播放，也不会为流式显示重新调用模型或记忆服务。首段出现前，仍可能需要等待宿主启动、自动召回和模型生成。

工作详情在浏览器独立后台线程中整理，回答显示不等待详情处理。记忆召回、保存和会话延续仍遵循本指南中的宿主规则；文字开始出现不表示记忆已经保存成功，保存状态以已有事件或记录为准。

原版 Mem0 与 MetaMemory 两条路线的流式显示已完成本轮真实对话验收。这一结果只说明控制台的流式回答及完整终态通过；记忆是否保存成功，仍以本轮记忆事件或读写记录为准。

常见问题

DeepSeek Harness

为 DeepSeek Harness 提供保存、搜索和跨会话记忆。适用于 Harness 0.2.0-rc.2、MetaMemory 插件 0.1.0。

1. 安装

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

安装包同时包含所需 Harness 依赖。使用前配置自己的宿主回答模型。

2. 配置连接

read -rsp 'MetaMemory 组件 Key: ' METAMEM_API_KEY
echo
export METAMEM_API_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"

在安装目录保存 cordis.yml，将模块路径换成实际绝对路径，将 userId 换成自己的稳定项目身份：

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

npx --no-install dsh --profile headless --patch ./cordis.yml --json -

不同本地项目使用不同 userId；同一项目跨会话保持一致。

3. 保存和读取

在会话中提供一条要记住的项目事实，或让智能体调用 add_memory 主动保存。用 search_memory 搜索确认保存完成。

自动召回使用上一轮已提交的用户消息。新会话的第一轮不会自动搜索；先问一次目标问题，再在同一会话重复该问题。需要立即搜索时，直接要求使用 search_memory。

调用时序

工具与开关

范围限制

默认读写按 userId 区分，不会自动识别 Git 项目或附加项目范围。当前版本的 agentId/runId 组合检索存在上游实体字段缺失问题，不能作为可靠隔离依据；项目隔离使用不同且稳定的 userId。

此插件只提供保存和搜索工具，更新或清理请使用 MetaMemory 的记忆管理功能。

控制台中的流式对话

在“记忆组件宿主智能体集成体验”中使用原版 Mem0 或 MetaMemory 接入时，页面会随着宿主返回新的回答内容逐步显示正文。它使用本轮宿主实际生成的文字，不会把完成后的回答切成小段播放，也不会为流式显示重新调用模型或记忆服务。首段出现前，仍可能需要等待宿主启动、自动召回和模型生成。

工作详情在浏览器独立后台线程中整理，回答显示不等待详情处理。记忆召回、保存和会话延续仍遵循本指南中的宿主规则；文字开始出现不表示记忆已经保存成功，保存状态以已有事件或记录为准。

原版 Mem0 与 MetaMemory 两条路线的流式显示已完成本轮真实对话验收。这一结果只说明控制台的流式回答及完整终态通过；记忆是否保存成功，仍以本轮记忆事件或读写记录为准。

常见问题

Hermes Agent

为 Hermes 添加自动捕获、回答前召回和四个记忆管理工具。适用于 Hermes 0.21.5、Python 3.11+、MetaMemory 插件 0.1.0。

1. 安装

下载 Hermes 插件，解压并放入当前 profile 的插件目录：

tar -xzf metamem-hermes-plugin-0.1.0-20261008.tar.gz
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 plugins list --user --json

将示例中的 Python 路径换成自己的环境路径。

2. 配置连接

read -rsp 'MetaMemory 组件 Key: ' METAMEM_API_KEY
echo
export METAMEM_API_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":"my-project-user","agent_id":"hermes","rerank":false,"sync_max_chars":450}

保持 host 为空，并清除旧 MEM0_HOST 配置；服务地址通过 METAMEM_BACKEND_URL 提供。用稳定 user_id 区分本人或项目，再执行 hermes memory status，新建会话。

3. 保存和读取

让 Hermes 用 mem0_add 保存“本项目数据库迁移必须支持回滚”，再用 mem0_search 查找。确认记忆可读取后，新建会话提问，插件会尝试在回答前召回背景。

调用时序

常用操作

自动捕获在回合完成后后台提取用户与助手文本，默认每条最多 450 字符；需要完整保留较长事实时使用显式保存。读取按 user_id 范围进行，同一身份可跨会话和渠道读取；不同本地项目需要不同用户身份。

控制台中的流式对话

在“记忆组件宿主智能体集成体验”中使用原版 Mem0 或 MetaMemory 接入时，页面会随着宿主返回新的回答内容逐步显示正文。它使用本轮宿主实际生成的文字，不会把完成后的回答切成小段播放，也不会为流式显示重新调用模型或记忆服务。首段出现前，仍可能需要等待宿主启动、自动召回和模型生成。

工作详情在浏览器独立后台线程中整理，回答显示不等待详情处理。记忆召回、保存和会话延续仍遵循本指南中的宿主规则；文字开始出现不表示记忆已经保存成功，保存状态以已有事件或记录为准。

原版 Mem0 与 MetaMemory 两条路线的流式显示已完成本轮真实对话验收。这一结果只说明控制台的流式回答及完整终态通过；记忆是否保存成功，仍以本轮记忆事件或读写记录为准。

常见问题

关闭 provider 前等待后台提交完成。关闭或卸载不会自动删除云端记忆。

DeerFlow

DeerFlow 内置 Mem0 记忆后端，可以在对话后保存事实，并在新会话中使用历史记忆。本指南适用于 DeerFlow 2.1.0 和 Mem0 Platform。

在 MetaMemory 控制台使用

选择 DeerFlow 宿主及 mem0_platform 组件，在同一项目中开始对话。提供一条项目事实，等它在记忆管理中出现后，新建会话提问即可。托管宿主无需在本机再次安装插件。

自行部署

准备 Python、uv 和 MetaMemory 的 Mem0 Platform 组件 Key，安装对应宿主版本：

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

保留自己的回答模型配置，在 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/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

read -rsp 'MetaMemory 组件 Key: ' MEM0_API_KEY
echo
export MEM0_API_KEY
uv run deerflow --print '请记住：本项目数据库迁移必须支持回滚。'

DeerFlow 使用内置后端，不需要安装 npm 记忆插件，也没有 /mem0-remember 等斜杠命令。

调用时序

读取方式

自动捕获保留用户和助手文本。保存可能在后台提取，回答结束不代表事实已经可读取；先在记忆管理中确认，再测试跨会话召回。

范围与管理限制

MetaMemory 托管项目有账号和项目身份绑定；新会话继续使用同一项目。自行部署时保持用户身份稳定，不同项目应配置不同的用户身份。

当前 Mem0 后端不支持 DeerFlow 的事实创建／更新／删除工具、import 或 Settings 编辑；这些入口可能返回“不支持”。查询使用 memory_search，浏览和清理使用已支持的记忆管理入口。

使用 user 与 agent 组合范围时，上游自动提取可能不保存 agent 字段，导致组合查询为空；当前不能把该组合当作可靠隔离保证。请按实际使用的身份范围检查记忆。

控制台中的流式对话

在“记忆组件宿主智能体集成体验”中使用原版 Mem0 或 MetaMemory 接入时，页面会随着宿主返回新的回答内容逐步显示正文。它使用本轮宿主实际生成的文字，不会把完成后的回答切成小段播放，也不会为流式显示重新调用模型或记忆服务。首段出现前，仍可能需要等待宿主启动、自动召回和模型生成。

工作详情在浏览器独立后台线程中整理，回答显示不等待详情处理。记忆召回、保存和会话延续仍遵循本指南中的宿主规则；文字开始出现不表示记忆已经保存成功，保存状态以已有事件或记录为准。

原版 Mem0 与 MetaMemory 两条路线的流式显示已完成本轮真实对话验收。这一结果只说明控制台的流式回答及完整终态通过；记忆是否保存成功，仍以本轮记忆事件或读写记录为准。

常见问题

停止本轮对话

任务取得编号后，可以点击“停止”终止本轮宿主工作进程。已完成的任务直接读取已有结果，不会重新发送。停止执行不会撤销已经提交到云端的记忆写入；写入结果未确认时，项目保留待核对状态，避免重复保存。

对话直接显示宿主回答；不会为工作详情额外查询一遍回答后的记忆库存。需要查看当前库存时，点击“获取记忆”。自动召回和保存仍使用原生记忆管理器。

停止时保留已经生成的文字，并标记“已停止”。

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