快速开始

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

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

前置条件

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

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

安装

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

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

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

方式 B：直接 MCP

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

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

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

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

管理插件

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

包含的功能

直接 MCP 工具

生命周期钩子

技能

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

使用流程

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

子智能体

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

Codex Cloud

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

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

调用时序

实线表示调用顺序；后台提交不保证写入已完成。下图按当前冻结源码描述，源码实现不等于已部署或已验收。

冻结插件先落本地证据，再由 flush worker 提交。Stop 可能按周期或 idle 调度，PreCompact 和 SessionEnd 刷新未提交内容；后台 worker 完成 HTTP 提交不代表服务器提取完成。显式 search 技能可再次召回。

原生范围与平台范围

项目知识使用 agent_id（项目身份）及 app_id（仓库）；个人记忆使用 user_id 及 app_id。检索按 repo/mine/dir 策略组合。run_id 是来源会话标识，不能把项目知识简单解释为仅 user_id。

MetaMemory 适配保留官方插件的工具、钩子和记忆策略，修改产品身份与传输路由。请求先携带平台组件 Key 和 X-Metamem-Memory-Component，由网关鉴权并绑定后端范围，再调用指定 Mem0；不是绕过平台直连原生 Mem0，也不把 Mem0 的记忆算法改成自研算法。

Mem0 官方宿主说明

MetaMemory MCP

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

前置条件

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

快速安装

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

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

登录

方式 1：浏览器登录

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

方式 2：API Key

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

可用工具

客户端配置

Claude Desktop

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

Claude Code

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

Codex

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

OpenCode

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

选择记忆组件

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

Claude Code

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

前置条件

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

快速开始

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

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

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

管理插件

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

使用方式

自动记忆

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

命令

搜索工具

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

Sidekick 智能体

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

工作原理

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

记忆范围

搜索范围

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

配置

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

存储与发送的数据

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

自动捕获与召回

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

搜索与删除示例

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

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

Sidekick 工作流程

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

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

遥测

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

调用时序

实线表示调用顺序；后台提交不保证写入已完成。下图按当前冻结源码描述，源码实现不等于已部署或已验收。

Claude 插件和 Codex 共用冻结 memory core，但宿主钩子适配与子智能体行为分别由宿主执行。Sidekick 仅属于 Claude 插件，不扩展为其他宿主的能力。原生本地证据与后台 flush 队列保留。

原生范围与平台范围

项目知识为 agent_id + app_id，个人记忆为 user_id + app_id；目录过滤由 metadata.dirs 提供。主／子会话生命周期仍遵循官方插件，而不是平台生成同名工具。

MetaMemory 适配保留官方插件的工具、钩子和记忆策略，修改产品身份与传输路由。请求先携带平台组件 Key 和 X-Metamem-Memory-Component，由网关鉴权并绑定后端范围，再调用指定 Mem0；不是绕过平台直连原生 Mem0，也不把 Mem0 的记忆算法改成自研算法。

Mem0 官方宿主说明

OpenCode

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

前置条件

MetaMemory 账号、组件 Key 和 OpenCode。

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

安装

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

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

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

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

方式 B：独立 MCP

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

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

包含的功能

可用记忆工具

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

记忆范围

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

命令

生命周期钩子

范围参数

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

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

自动捕获规则

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

调用时序

实线表示调用顺序；后台提交不保证写入已完成。下图按当前冻结源码描述，源码实现不等于已部署或已验收。

自动捕获在 chat.message 内按提示计数触发，不是每轮 agent_end，也不是所有完整会话都写入。shell 工具报错后可检索经验；会话压缩钩子保存／恢复状态。显式原生工具与 MCP 安装方式的生命周期能力不同。

原生范围与平台范围

默认 project 为 user_id + app_id；自动捕获只把会话来源写进 metadata.session_id，不写顶层 run_id。显式 session 操作使用 run_id；global 必须通过 /mem0-scope 明确开启。

MetaMemory 适配保留官方插件的工具、钩子和记忆策略，修改产品身份与传输路由。请求先携带平台组件 Key 和 X-Metamem-Memory-Component，由网关鉴权并绑定后端范围，再调用指定 Mem0；不是绕过平台直连原生 Mem0，也不把 Mem0 的记忆算法改成自研算法。

Mem0 官方宿主说明

OpenClaw

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

概览

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

前置条件

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

安装

在任意 OpenClaw 聊天入口发送：

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

配置

userId

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

平台模式

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

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

方式 2：手动配置

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

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

在 openclaw.json 中配置：

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

开源模式

方式 1：交互配置

openclaw mem0 init --mode open-source

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

方式 2：非交互配置

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

方式 3：手动配置

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

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

平台后端选择使用 METAMEM_MEMORY_COMPONENT。

短期与长期记忆

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

智能体工具

插件管理

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

隐私与安全

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

配置选项

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

CLI 命令

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

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

开源初始化参数

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

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

调用时序

实线表示调用顺序；后台提交不保证写入已完成。下图按当前冻结源码描述，源码实现不等于已部署或已验收。

冻结插件有两条路线：legacy 在 agent_end 成功后自动捕获；skills 模式的 agent_end 明确不自动捕获，由智能体调用 memory_add。skills 的 manual 策略也不自动召回；smart／always 按配置检索。因此不能承诺所有模式都会“回答后自动 Add”。

原生范围与平台范围

长期记忆绑定有效 user_id；会话记忆再带 run_id。memory_add 的 longTerm 控制写入层级，agent_id 按插件身份配置。跨会话长期检索不要限定新 run_id；原生 sessionKey 与平台会话标识不能直接混用。

MetaMemory 适配保留官方插件的工具、钩子和记忆策略，修改产品身份与传输路由。请求先携带平台组件 Key 和 X-Metamem-Memory-Component，由网关鉴权并绑定后端范围，再调用指定 Mem0；不是绕过平台直连原生 Mem0，也不把 Mem0 的记忆算法改成自研算法。

Mem0 官方宿主说明

Pi Agent

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

概览

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

前置条件

Pi Agent、MetaMemory 账号与组件 Key。

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

安装

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

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

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

可选配置

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

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

包含的功能

命令

记忆范围

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

自动召回与捕获

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

配置默认值

工具参数

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

命令参数

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

调用时序

实线表示调用顺序；后台提交不保证写入已完成。下图按当前冻结源码描述，源码实现不等于已部署或已验收。

before_agent_start 把记忆策略和召回结果加入 systemPrompt；agent_end 钩子 await Add 请求，但不轮询服务器 event_id。autoCapture 控制捕获，contextInjection 控制自动召回。

原生范围与平台范围

自动召回和捕获固定为 project：user_id + app_id，自动写入不带 run_id。显式 session 工具使用 user_id + app_id + run_id；global 仅 user_id，必须由用户明确开启。

MetaMemory 适配保留官方插件的工具、钩子和记忆策略，修改产品身份与传输路由。请求先携带平台组件 Key 和 X-Metamem-Memory-Component，由网关鉴权并绑定后端范围，再调用指定 Mem0；不是绕过平台直连原生 Mem0，也不把 Mem0 的记忆算法改成自研算法。

Mem0 官方宿主说明

DeepSeek Harness

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

前置条件

DeepSeek Harness、MetaMemory 账号与组件 Key。

安装

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

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

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

配置

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

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

使用同一 profile 加载该配置：

dsh web --patch ./cordis.yml

工作原理

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

智能体工具

记忆范围

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

遥测

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

参数默认值

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

生命周期

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

调用时序

实线表示调用顺序；后台提交不保证写入已完成。下图按当前冻结源码描述，源码实现不等于已部署或已验收。

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

原生范围与平台范围

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

MetaMemory 适配保留官方插件的工具、钩子和记忆策略，修改产品身份与传输路由。请求先携带平台组件 Key 和 X-Metamem-Memory-Component，由网关鉴权并绑定后端范围，再调用指定 Mem0；不是绕过平台直连原生 Mem0，也不把 Mem0 的记忆算法改成自研算法。

Mem0 官方宿主说明

Hermes Agent

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

工作原理

当前回合召回

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

后台事实提取

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

智能体工具

安装

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

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

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

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

平台配置

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

hermes memory setup metamem

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

方式 2：手动配置

hermes config set memory.provider metamem

在当前 profile 的 .env 中设置：

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

当前 profile 的 mem0.json：

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

自托管服务配置

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

开源模式配置

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

切换模式

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

配置

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

迁移已有用户

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

可靠性

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

配置字段

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

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

原生开源配置示例

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

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

工具参数与回合处理

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

调用时序

实线表示调用顺序；后台提交不保证写入已完成。下图按当前冻结源码描述，源码实现不等于已部署或已验收。

此图对应独立官方插件快照，不是 Hermes 历史内置 provider。召回慢于 3 秒可跳过本轮注入，保留 mem0_search 工具兜底；sync_turn 后台线程写入，默认每条截至 450 字符。显式 mem0_add 使用 infer=False；自动捕获使用 infer=True。

原生范围与平台范围

自动召回按 user_id 跨渠道共享；自动写入带 user_id + agent_id 和 metadata.channel，不带 app_id／run_id。平台空间／项目隔离是额外授权映射，不能归为 Hermes 原生范围。

MetaMemory 适配保留官方插件的工具、钩子和记忆策略，修改产品身份与传输路由。请求先携带平台组件 Key 和 X-Metamem-Memory-Component，由网关鉴权并绑定后端范围，再调用指定 Mem0；不是绕过平台直连原生 Mem0，也不把 Mem0 的记忆算法改成自研算法。

Mem0 官方宿主说明

DeerFlow：Mem0 与 metamem 接入对照

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

Mem0 与 metamem 配置对照

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

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

安装插件

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

1. 启用记忆

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

2. 提供 Key

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

export MEM0_API_KEY="你的metamem组件Key"

3. 启动 DeerFlow

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

配置客户端

Mem0：config.yaml

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

metamem：config.yaml

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

4. 接入后怎么用

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

5. 怎样确认记忆生效

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

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

返回 Mem0／metamem 接入总览

调用时序

实线表示调用顺序；后台提交不保证写入已完成。下图按当前冻结源码描述，源码实现不等于已部署或已验收。

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

原生范围与平台范围

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

MetaMemory 适配保留官方插件的工具、钩子和记忆策略，修改产品身份与传输路由。请求先携带平台组件 Key 和 X-Metamem-Memory-Component，由网关鉴权并绑定后端范围，再调用指定 Mem0；不是绕过平台直连原生 Mem0，也不把 Mem0 的记忆算法改成自研算法。

DeerFlow 的证据来自本仓库冻结 MemoryManager 源码；不标为 Mem0 官方独立发布插件。

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