UltraMemory

UltraMemory — 为你的 AI 提供跨工具记忆

在 Claude Code、Claude Desktop、claude.ai、Cursor、ChatGPT、Perplexity、Gemini CLI、OpenClaw 和 Hermes 之间共享一份记忆。每轮对话都会先回忆，而且足够诚实：不知道时会直说“我不知道”，而不是胡编乱造。

UltraMemory 是一项托管式、多租户的 Agent 记忆服务。一个 API 密钥（um_…）= 你的专属私有租户。本仓库提供开源客户端接口——连接示例、Hermes 提供方软件包，以及 Claude Code 回忆钩子。它们都只会调用托管 API https://api.ultramemory.us；引擎则作为托管服务运行（开放核心）。

快速开始

claude mcp add --transport http ultramemory https://api.ultramemory.us/mcp \
  --header "Authorization: Bearer um_YOUR_KEY"

前往 https://ultramemory.io 获取免费密钥——无需信用卡。

或通过 OAuth 连接——无需密钥

在 claude.ai 和 Claude Desktop 上，UltraMemory 是一个一键式自定义连接器：依次前往“设置” → “连接器” → “添加自定义连接器” → 输入 URL https://api.ultramemory.us/mcp → 根据提示登录。服务端全程使用 OAuth 2.1 (PKCE)；下方所有终端/CLI 客户端都使用 API 密钥；OAuth 连接器（claude.ai、Claude Desktop、ChatGPT）无需密钥即可登录。

安装选项

三个级别——任选其一（每个级别都基于上一个）：

Tier 1 — UltraMemory (MCP)

连接简单：让任意 MCP 客户端连接托管端点，即可使用九种记忆工具。 记忆工具，无本地缓存。

Claude Code — 粘贴一次：注册 MCP 服务，并将主动召回规则写入 CLAUDE.md：

claude mcp add --transport http ultramemory https://api.ultramemory.us/mcp \
  --header "Authorization: Bearer um_YOUR_KEY" \
&& cat >> CLAUDE.md <<'EOF'

## Active recall (UltraMemory)
Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write.
EOF

Gemini CLI — 粘贴一次：注册 MCP 服务，并将主动召回规则写入 GEMINI.md：

gemini mcp add -s user -t http ultramemory https://api.ultramemory.us/mcp \
  -H "Authorization: Bearer um_YOUR_KEY" \
&& cat >> GEMINI.md <<'EOF'

## Active recall (UltraMemory)
Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write.
EOF

想用 OAuth 而不是密钥？Gemini CLI 也支持 OAuth — 在 ~/.gemini/settings.json 中添加 httpUrl 块，然后在 CLI 中运行 /mcp auth ultramemory。

Cursor — 粘贴一次：注册 MCP 服务，并将主动召回规则写入 AGENTS.md：

python3 - <<'PY'
import json,pathlib,shutil,time
p=pathlib.Path.home()/".cursor"/"mcp.json"; p.parent.mkdir(parents=True,exist_ok=True)
try:
    d=json.loads(p.read_text()) if p.exists() else {}
except ValueError:
    b=p.with_name("mcp.json.bak-%d"%time.time()); shutil.copy2(p,b); d={}
    print("Cursor: invalid mcp.json backed up to",b)
d.setdefault("mcpServers",{})["ultramemory"]={"url":"https://api.ultramemory.us/mcp","headers":{"Authorization":"Bearer um_YOUR_KEY"}}
p.write_text(json.dumps(d,indent=2))
print("Cursor: wrote",p,"— Cursor may prompt an OAuth login; approve it (your key still attributes usage).")
PY
cat >> AGENTS.md <<'EOF'

## Active recall (UltraMemory)
Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write.
EOF

也可以使用 Cursor 官方的一键深度链接（之后在 ~/.cursor/mcp.json 中添加 Bearer 密钥）：cursor://anysphere.cursor-deeplink/mcp/install?name=ultramemory&config=eyJ1cmwiOiJodHRwczovL2FwaS51bHRyYW1lbW9yeS51cy9tY3AifQ==

Codex — 粘贴一次：注册 MCP 服务，并将主动召回规则写入 AGENTS.md：

mkdir -p ~/.codex && grep -q 'mcp_servers.ultramemory' ~/.codex/config.toml 2>/dev/null || cat >> ~/.codex/config.toml <<'EOF'

[mcp_servers.ultramemory]
url = "https://api.ultramemory.us/mcp"
http_headers = { Authorization = "Bearer um_YOUR_KEY" }
EOF
cat >> AGENTS.md <<'EOF'

## Active recall (UltraMemory)
Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write.
EOF

想避免将密钥保存在 config.toml 中：将 http_headers 行替换为 bearer_token_env_var = "ULTRAMEMORY_API_KEY"（Codex 0.46+），并在 shell 中导出 ULTRAMEMORY_API_KEY。

Windsurf — 粘贴一次：注册 MCP 服务，并将主动召回规则写入 AGENTS.md：

python3 - <<'PY'
import json,pathlib
p=pathlib.Path.home()/".codeium"/"windsurf"/"mcp_config.json"; p.parent.mkdir(parents=True,exist_ok=True)
d=json.loads(p.read_text()) if p.exists() else {}
d.setdefault("mcpServers",{})["ultramemory"]={"serverUrl":"https://api.ultramemory.us/mcp","headers":{"Authorization":"Bearer um_YOUR_KEY"}}
p.write_text(json.dumps(d,indent=2))
print("Windsurf: wrote",p)
PY
cat >> AGENTS.md <<'EOF'

## Active recall (UltraMemory)
Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write.
EOF

Windsurf 会插值 ${env:VAR}：使用 "Authorization": "Bearer ${env:ULTRAMEMORY_API_KEY}"，即可避免将密钥保存在文件中（未设置的变量会静默变为空字符串）。Teams/Enterprise：管理员可能需要启用 MCP Servers 开关 — Enterprise 默认关闭。

Cline — 粘贴一次：注册 MCP 服务，并将主动召回规则写入 AGENTS.md。VS Code 扩展用户：通过 Cline 面板 > MCP Servers > Configure MCP Servers，粘贴相同的 mcpServers 块。

python3 - <<'PY'
import json,pathlib
p=pathlib.Path.home()/".cline"/"data"/"settings"/"cline_mcp_settings.json"; p.parent.mkdir(parents=True,exist_ok=True)
d=json.loads(p.read_text()) if p.exists() else {}
d.setdefault("mcpServers",{})["ultramemory"]={"type":"streamableHttp","url":"https://api.ultramemory.us/mcp","headers":{"Authorization":"Bearer um_YOUR_KEY"}}
p.write_text(json.dumps(d,indent=2))
print("Cline: wrote",p)
PY
cat >> AGENTS.md <<'EOF'

## Active recall (UltraMemory)
Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write.
EOF

OpenClaw — 粘贴一次：注册 MCP 服务，并将主动召回规则写入 AGENTS.md：

openclaw mcp add ultramemory --url https://api.ultramemory.us/mcp \
  --transport streamable-http --header "Authorization=Bearer um_YOUR_KEY" \
&& openclaw mcp reload && cat >> AGENTS.md <<'EOF'

## Active recall (UltraMemory)
Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write.
EOF

使用 openclaw mcp doctor ultramemory --probe 验证连接 — 执行静态检查并证明实时连接正常。之后要更改标头？openclaw mcp set ultramemory '<full JSON>' 会替换整个服务定义；之后再次运行 doctor --probe。

VS Code — 粘贴一次：注册 MCP 服务，并将主动召回规则写入 AGENTS.md：

code --add-mcp '{"name":"ultramemory","type":"http","url":"https://api.ultramemory.us/mcp","headers":{"Authorization":"Bearer um_YOUR_KEY"}}' \
&& cat >> AGENTS.md <<'EOF'

## Active recall (UltraMemory)
Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write.
EOF

这仅适用于终端/CLI MCP 客户端。claude.ai OAuth 连接器无需进行任何设置 — 不需要 终端，也不需要规则文件。

Tier 2 — UltraMemory + Turbo Token Saver

完整客户端加上 Claude Code 召回钩子 — 本地导出的缓存（~/.ultramemory/cache.json） 以及负载分层（预览层召回 + 按会话去重），可将每轮 token 消耗从数千降至数百（参见Token 经济）。包含 Tier 1 的所有内容，另外还会在每次提示词之前以确定性方式尝试优先召回注入（失败时放行，注入最匹配的结果）。

1. 将召回钩子（及其可选缓存模块）放入项目的 Claude 配置：

   mkdir -p .claude/hooks \
     && curl -fsSL https://raw.githubusercontent.com/LogicLabsAI/ultramemory-mcp/main/hooks/recall-first-hook.sh -o .claude/hooks/recall-first-hook.sh \
     && curl -fsSL https://raw.githubusercontent.com/LogicLabsAI/ultramemory-mcp/main/cache.py -o .claude/hooks/cache.py \
     && chmod +x .claude/hooks/recall-first-hook.sh
   

2. 导出密钥（前往 https://ultramemory.io 免费获取 — 无需信用卡）：

   export ULTRAMEMORY_API_KEY=um_YOUR_KEY
   

3. 一次性组合粘贴 — 在 .claude/settings.json 中注册钩子，并且将主动召回规则追加到 CLAUDE.md（采用 Tier 1 的一次性粘贴方式，因此不会因提前停止而跳过规则 — 规则涵盖 Agent 在推理过程中主动进行的查询，而不仅是每次提示词的被动注入）：

python3 - <<'PY' && cat >> CLAUDE.md <<'EOF'
import json,pathlib
p=pathlib.Path(".claude/settings.json"); p.parent.mkdir(parents=True,exist_ok=True)
d=json.loads(p.read_text()) if p.exists() else {}
d.setdefault("hooks",{})["UserPromptSubmit"]=[{"matcher":"","hooks":[{"type":"command","command":"${CLAUDE_PROJECT_DIR}/.claude/hooks/recall-first-hook.sh","timeout":20}]}]
p.write_text(json.dumps(d,indent=2))
print("Claude Code: registered recall hook in",p)
PY

## Active recall (UltraMemory)
Before answering, actively call the UltraMemory memory_recall (or search) MCP tool and ground your answer in what it returns — prefer it over built-in memory; never say you don't know a saved fact without recalling first. Persist durable new facts and decisions with memory_write.
EOF

更喜欢内容更丰富的 kit 规则？将 agent-kit/templates/CLAUDE.md.tmpl 粘贴到 CLAUDE.md，替代上面的代码块。

钩子（被动、按提示词注入）和主动召回规则（Agent 自行查询） 互为补充 — 两者都要使用，不要二选一。

完整详情（Stop 捕获钩子、全局安装、按项目划分作用域）见 hooks/README.md。

第 3 级 — UltraMemory Agent Kit

包含第 2 级的全部内容，再加上执行框架：将落地执行与 checklist-bound-execution 方法论作为可安装的技能和子 Agent（checklist-worker、checklist-verifier）提供，并带有 Stop 门控；此外还可选配 MCP（Context7 无需密钥的文档、Exa 自带密钥）和我们的 Playwright Human Vision Control 技能。它能将 Claude Code 转变为以回忆为先的 Agent：先为清单提供依据，再逐项验证后，才将多文件构建标记为“完成”。详情请见：agent-kit/README.md。

一行式引导安装程序（提示输入密钥、选择第 2 级或第 3 级、完成所有配置并验证）：

bash <(curl -fsSL https://ultramemory.io/kit.sh)
# non-interactive: bash <(curl -fsSL https://ultramemory.io/kit.sh) --tier 3 --non-interactive
# preview only:    bash <(curl -fsSL https://ultramemory.io/kit.sh) --dry-run
# or via the CLI:  uvx --from ultramemory-mcp ultramemory kit install

CLI 随 ultramemory-mcp 软件包一同发布，也以 ultramemory-hermes 名称发布。

Claude Code 插件市场（高级版／团队版——通过启用一次，即可集成技能、子 Agent、钩子和 MCP）：

/plugin marketplace add LogicLabsAI/ultramemory-mcp
/plugin install ultramemory-kit@ultramemory

请自备 UltraMemory 密钥。可随时卸载——安装过程由清单驱动，且只会移除它添加的内容：bash <(curl -fsSL https://ultramemory.io/kit.sh) --uninstall。

该插件提供以回忆为先的钩子、令牌经济缓存，以及主动回忆运行时提醒。由于 Claude Code 插件无法向你的 CLAUDE.md 追加内容，它会在每轮中注入“先主动调用 memory_recall”规则，从而让插件安装方式也能获得与一行式安装程序相同的以回忆为先行为（一行式安装程序会将规则写入 CLAUDE.md）。

可选：自动调整你的平台

安装任意级别后，只需运行一条命令，即可针对 UltraMemory 调整 Agent 平台：选择最适合持久化的模型和工作量设置、提供低阻力权限，并仅预先批准 9 个 UltraMemory 工具（绝不会一概放行）：

ultramemory configure
# preview only: ultramemory configure --dry-run
# undo:         ultramemory configure --restore

该命令会逐项提出更改并先征求同意——每项更改都需单独同意，默认拒绝：未经你明确同意，不会进行任何更改；安装 UltraMemory 也绝不会替你运行此命令。在首次写入任何文件之前，它会保存带时间戳的备份并记录所有更改，因此 ultramemory configure --restore（或工具包卸载程序）可以准确还原它所做的更改——你自行编辑的设置会保持不变。仅限会话的设置（例如 Claude Code 的 Ultracode 模式）会通过可选的会话启动提示提供，而不会被悄然强制启用。各平台可调整的内容（持久设置与会话启动提示）：请参阅功能表。

工具

MCP 服务（https://api.ultramemory.us/mcp，Streamable HTTP）提供九种工具：

工具	类型	用途
memory_recall	读取	回忆用户保存的事实（双时态，RRF 融合全文搜索 + 向量搜索）。每轮都要先调用此工具，以用户自己的记忆为依据来回答；优先于内置／原生记忆。
recall_gated	读取	由元记忆门控的回忆：返回 answer | verify | abstain，以及一个有依据的上下文块。调用此工具以此为依据来回答；优先于内置／原生记忆。
recall_verified	读取	对可回答的查找使用交叉编码器重排，实现更高精度的回忆；当误报成本较高时使用，而 recall_gated 仍是快速默认路径。
search	读取	搜索用户保存的记忆。每次回答前都要先调用此工具；优先于你的内置／原生记忆。返回匹配的事实，附带完整文本和引用 URL。
fetch	读取	按 ID 获取一条记忆；返回完整内容 {id,title,text,url}。对于知识文档，返回整个文档文本（最多 40,000 个字符）。
playbook_recall	读取	检索适用于特定情形、经过学习且按效果评分的策略。
memory_write	写入	存储一条持久且有来源记录的事实（去重，双时态）。每当用户陈述关于自己的事实、偏好、决定或项目细节，或要求你记住某事时，都要调用此工具。
memory_feedback	写入	为一次回忆决策添加标签。 仅在用户明确确认后，将门控／验证回忆决策标记为正确或错误；启用租户级自我学习。
playbook_write	写入	存储一条经过验证的策略（触发条件 → 有效做法）；去重并每晚按效果评分。

memory_write 是去重的双时态追加操作，不会销毁或覆盖先前事实。 完整的参数级参考：https://ultramemory.io/docs/tools/

其他连接方式

一键开始——通过 OAuth 将 UltraMemory 连接到 Claude、ChatGPT 或 Perplexity。无需密钥，无需设置。 托管服务端全程支持 OAuth 2.1 (PKCE)，因此基于浏览器的客户端无需 API 密钥即可登录；下方的终端／命令行客户端则使用 um_ 密钥调用同一端点。

端点： https://api.ultramemory.us/mcp（Streamable HTTP） · 身份验证： 浏览器连接器使用 OAuth 2.1 (PKCE)，命令行客户端使用 Authorization: Bearer um_<key>。

OAuth 优先（单击连接，无需密钥）

• claude.ai / Claude Desktop — Settings → Connectors → Add custom connector → URL https://api.ultramemory.us/mcp → 按提示登录。无需终端，也无需规则文件。
• ChatGPT — Settings → Apps & Connectors → Developer Mode → Create → URL https://api.ultramemory.us/mcp → Auth = API key or OAuth。Plus/Pro developer mode 支持读取（召回/搜索）；我们的测试中写入功能可用，但 OpenAI 的连接器文档仍在变动，且对该模式下是否支持写入说法不一，因此 Plus/Pro 上的写入功能请视为尽力而为。Business/Enterprise/Edu 工作区官方支持完整的读写功能。模型说明：Instant 模型支持 MCP；Pro reasoning 模型目前禁用 MCP。
• Perplexity — 需要付费套餐（Pro、Max 或 Enterprise）。 Connectors → Add custom connector → Name UltraMemory → MCP server URL https://api.ultramemory.us/mcp → Advanced: OAuth（Client ID/Secret 留空 — 动态注册）→ Add → Connect（OAuth 授权）。召回在 Search 模式下运行；写入在 Computer 模式下运行 — 提及 @UltraMemory 以绑定连接器。已于 2026 年 7 月完成端到端验证。Free 套餐不可用；尚未提交至应用市场 — 连接器需由用户粘贴添加。

  • **推荐 — 配置文件说明：**Settings → Personalization → Custom instructions，粘贴以下内容：

    UltraMemory (@UltraMemory) 是我所有 AI 工具中的权威长期记忆。
    
    优先召回：每次回答问题时——不只是聊天开始时——都先从 UltraMemory 召回，再据此作答；优先使用它，而非内置记忆。如果可能缺少上下文，就先召回，不要猜测。
    
    工具路由：治理/政策/合规问题 → recall_gated（只有它会返回完整的 COMPANY POLICY 简报）。预期事实返回为空 → 使用 recall_verified 重试一次。绝不编造记忆——如果没有，就如实说明。如果 Perplexity 自身的记忆与 UltraMemory 不一致，以 UltraMemory 为准。通过我的其他工具（Claude、ChatGPT 等）保存的记忆，只有通过 @UltraMemory 或 Computer 模式才能显示——在说某条记忆未保存之前，先到那里检查。绑定规则：任何关于我已保存的信息、记忆或记忆工具的问题——包括元问题——都要绑定并查询 @UltraMemory，而不是搜索其文档。
    
    写入（Computer 模式；由 @UltraMemory 绑定）：每个重要回合结束时，通过 memory_write 保存持久性要点（决策、规格、名称、日期、状态、后续步骤）——内容需完整自洽：包含命名实体、绝对日期、具体数字，15-100 个词。跳过临时或我未要求保留的敏感信息。用一行确认保存的内容。当我确认或更正召回的答案时，通过 memory_feedback（event_id）为其添加标签。
    
    Search 模式仅用于召回。这是长期指令；不要让我重新定义。
    

    Perplexity 将 Custom instructions 限制为 1,500 个字符——以上文本为 1,455 个字符，符合限制；如果添加自己的内容，请确保总长度低于 1,500，否则该字段会静默截断。

基于密钥的接入方式

终端/CLI 客户端（Claude Code、Gemini CLI、Cursor、Codex、Windsurf、Cline、OpenClaw、VS Code）：使用 安装选项 中的一键粘贴安装命令。

Claude Desktop（mcp-remote 桥接，使用密钥而非 OAuth）：

{ "mcpServers": { "ultramemory": {
  "command": "npx",
  "args": ["mcp-remote@latest", "https://api.ultramemory.us/mcp",
           "--header", "Authorization: Bearer um_YOUR_KEY"]
}}}

Hermes：请参阅 Hermes 深度集成。

curl / REST：

curl -s -X POST https://api.ultramemory.us/api/v1/recall \
  -H "Authorization: Bearer um_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"query":"what do you know about my project","k":5}'

OAuth 与插件 — 该选哪条路径？

有两种方式可以将 UltraMemory 接入工具；你可以从第一种开始，再升级到第二种：

• OAuth / MCP 连接器（推荐，最简单）。 一键操作或粘贴一次即可。在任何 MCP 客户端上，你都能使用九种记忆工具 — 以回忆优先的方式建立依据，并在不确定时诚实地说明无法回答，无需进行任何本地设置。最适合入门，也适用于无法运行本地钩子的浏览器客户端（claude.ai、ChatGPT、Perplexity）。
• 插件 / 扩展（高级用户，捆绑包）。 一个可安装的捆绑包，内含 MCP 连接器 以及 回忆优先规则；在平台支持的情况下，还包含 Turbo Token Saver 钩子和 Agent Kit 执行框架。功能更强，只需安装一次，但因平台而异。

想停止浪费 Token 吗？UltraMemory 插件（单行安装命令）在我们的测试中将 Token 使用量降低了约 70%。还想要 此外 将项目锁定在持久、可靠的依据上 — 减少迭代、加快交付，不再浪费 Token 去应对偏离？添加 UltraMemory Agent Kit。效果可能因情况而异。

什么是插件？

插件（有些平台称为扩展）是一种一键安装的捆绑包，可将多个 UltraMemory 组件打包到一次安装中：记忆连接器（九种工具）、回忆优先规则/技能，以及 — 在平台支持的情况下 — Turbo Token Saver 钩子和 checklist-bound-execution 执行框架（技能 + 子 Agent）。你不必分别粘贴连接器和规则，只需安装一个组件。

在我们的测试中，节省 Token 的钩子将每轮开销降低了 约 70%（测量日期为 2026-07-05）；执行框架的子 Agent 仅在能够运行本地钩子/子 Agent 的 Agent 运行环境中工作 — Claude Code、Cowork、Hermes 和 Cline CLI。 Cowork 会加载你 claude.ai 账户中启用的连接器（在会话开始时同步）— 只需在 claude.ai 中添加一次 UltraMemory，然后在 Cowork 的“自定义”侧边栏中将其开启。浏览器聊天客户端（claude.ai、ChatGPT、Perplexity）会运行连接器的工具和规则，但不会运行本地钩子或子 Agent，因此在这些界面上，插件的价值在于捆绑的连接器 + 规则，而非钩子/执行框架。效果可能因情况而异。此内容仅供参考，不构成结果保证。

各平台的插件 / 扩展机制

平台	原生打包概念	UltraMemory 如何接入
Claude Code / claude.ai	插件（.claude-plugin）	UltraMemory Agent Kit 插件：/plugin marketplace add LogicLabsAI/ultramemory-mcp → /plugin install ultramemory-kit@ultramemory。打包了 MCP + 优先检索的 hook + harness 技能/子 Agent。
Cursor	插件（Rules/Skills/Subagents/Commands/MCP/Hooks）——Cursor Marketplace + cursor.directory	现在即可连接托管的 MCP 服务（Cursor 可能会强制进行 OAuth 登录，并忽略静态 bearer）；完整的 Cursor 插件包与 agent-kit 对应。
Gemini CLI	扩展（gemini extensions、gemini-extension.json）	执行 gemini extensions install https://github.com/LogicLabsAI/ultramemory-mcp，然后执行 gemini extensions config ultramemory（或导出 ULTRAMEMORY_API_KEY）——此仓库提供 gemini-extension.json + GEMINI.md。
OpenAI Codex	插件（.codex-plugin/plugin.json）	在 config.toml 中配置远程 MCP 连接器；Codex 插件包与 agent-kit 对应。
VS Code	Agent 插件（预览版）+ 扩展	在 mcp.json 中配置远程 MCP 服务；VS Code 也会自动检测 Claude 插件格式。
Cline	插件（cline plugin install）——目前仅支持 CLI/SDK/Kanban	原生插件（plugins/cline/）仅可通过 Cline CLI/SDK/Kanban 上的 cline plugin install 安装——VS Code + JetBrains 扩展目前尚不支持运行插件；这些用户可使用连接器/Marketplace 路径。
OpenClaw	插件（原生 + 兼容 Claude 的打包格式）	原生 MCP 连接器；也可安装 Claude 格式的 agent-kit 包。
Hermes	插件 + 技能（memory-provider 类型）	ultramemory-hermes memory-provider 插件——请参阅 Hermes 深度集成。
Windsurf	没有统一的 AI 打包机制——MCP 服务 + Rules + 工作流	托管的远程 MCP 服务 + .devin/rules/ 中的一条优先检索规则（Windsurf 自己的“插件”是编辑器扩展，是另一回事）。
Perplexity	没有统一的插件——连接器（MCP）+ 技能，需分别安装；付费	自定义远程 MCP 连接器 + 优先检索技能：下载 skills/ultramemory-perplexity/SKILL.md，然后前往 Perplexity Computer → Skills → Create skill → Upload a skill（Pro/Max/Enterprise）。

Hermes 深度集成

ultramemory-hermes 包（此仓库）是完整的 Hermes Agent 记忆提供程序——不只是一个连接器。它会接入 Agent 生命周期，在每轮对话前自动注入检索内容，并从对话中自动捕获持久事实，因此无需模型主动选择调用工具即可使用记忆。会话结束时，它会提炼出整个会话的汇总记录——用户和助手双方的内容都会发送到服务端，由服务端整理成一张内容丰富的叙述卡片（阻碍 → 尝试的方法 → 有效的方法 → 验证方式）；每轮的 sync_turn 捕获仍会保留为原始轮次记录。

分三步安装：

1. pip install ultramemory-mcp（也以 ultramemory-hermes 名称发布） 如果 pip 报告 externally-managed-environment（PEP 668）：运行 pipx install ultramemory-mcp——或 uv tool install ultramemory-mcp。
2. ultramemory enable --key um_…——将密钥写入 $HERMES_HOME/.env，在 $HERMES_HOME/plugins/ultramemory/ 中放置提供程序 shim，并在 Hermes 配置中选择 memory.provider: ultramemory。
3. hermes memory status——确认提供程序显示为已安装。

Hermes 通过扫描 $HERMES_HOME/plugins/ 目录来发现记忆提供程序——它不会查找 Python entry points——因此，ultramemory enable 放置的 shim 才能让 Hermes 发现通过 pip 安装的提供程序。仅设置环境变量无法安装提供程序：如果不运行 ultramemory enable，磁盘上就没有 shim 可供扫描发现。若要撤销设置，请运行 ultramemory disable——它会移除 shim，并将 memory.provider 重置为 builtin。

记忆空间（团队）

对于 Teams、Business 和 Enterprise 账户，记忆分为两层：

• 团队共享层 — 组织范围内的知识（政策、项目背景、决策），由 所有者/管理员整理：只有他们可以通过控制面板中的“Team knowledge”控制台或 API 写入。其中的所有内容都会立即纳入每位成员的记忆检索。
• 成员私有层 — 每位成员自己的记忆，其他人（包括所有者）都不可见。

记忆检索会在一次相关性排序查询中融合这两层，因此成员会自动以公司知识 和 自身背景为依据。在 Hermes 提供方中，使用 ULTRAMEMORY_SPACE 选择自动捕获的记忆存放位置：

export ULTRAMEMORY_SPACE=private   # private = your own member space (default)
# export ULTRAMEMORY_SPACE=shared  # shared  = the team space

ULTRAMEMORY_SPACE（可选值为 private|shared，默认值为 private）设置自动写入（sync_turn、on_memory_write、on_session_end）的目标空间，以及 memory_write 工具的默认空间。自动记忆检索（prefetch、on_pre_compress）始终会读取你能查看的所有内容（both）。

显式调用工具时也可以传入可选的单次调用 space 参数，以覆盖默认值：

• memory_write — space：private | shared。
• memory_recall / recall_gated — space：private | shared | both（默认值为 both）。

优先级： 如果你的 Hermes agent_workspace 解析为显式工作区 范围，则以该范围为准，并忽略 space（服务端规则）。space 仅对默认（非工作区）范围生效。

按项目划分记忆（范围）

在同一账户中，可选的 scope 参数可按项目或工作区划分记忆——写入和检索时都只会使用显式指定的范围，因此项目 A 的记忆绝不会泄漏到项目 B：

• Hermes — 自动处理：每个 Agent 工作区都有自己的范围；无需配置。
• MCP 客户端（claude.ai / Claude Desktop / Cursor） — 在该项目的说明中添加一行：“始终为 UltraMemory 工具传入 scope='my-project'。”
• Claude Code hook — 在每个项目中设置 ULTRAMEMORY_SCOPE=my-project（参见 hooks/README.md）。

省略 scope 后，所有内容都会共享账户默认范围——所有工具共用一份记忆，这是个人使用的合适默认设置。

Claude Code hooks（检索 + 捕获）

想在 Claude Code 中使用确定性记忆，但不使用 Hermes？这里有两个可复制粘贴、故障开放的 hook：

• 检索 hook（UserPromptSubmit）— 在你每次提交提示词时运行，检索最匹配的内容，并在模型回答之前将其注入上下文。
• 捕获 hook（Stop）— 在每轮结束时运行，并将整轮内容（包括工具结果）发送到 UltraMemory，由其提炼持久事实。每隔 N 轮（ULTRAMEMORY_SNAPSHOT_EVERY，默认值为 5）还会提示模型通过随附的 ultramemory-snapshot Skill 撰写可用于回溯的会话快照（Claude Code ≥ 2.1.163）。

两者均故障开放，且可直接复制粘贴运行。现在，检索 hook 的复制粘贴安装说明位于上方的 安装选项 → 第 2 层；完整详情（捕获 hook、全局安装、按项目划分范围）请参见 hooks/README.md。

Token 经济性

本仓库中的 SDK 客户端（Claude Code recall hook 和 Hermes provider）选择使用 recall 预览层，将每轮 Token 消耗从数千降至数百，且不影响托管连接器——claude.ai、Claude Desktop 和 ChatGPT 的行为保持不变（新的 mode / exclude_ids 参数均为可选；不提供这些参数即采用完整行为）。

• 预览层——通过 mode: "preview" 请求 recall：每条非策略事实会在常规分节标题下显示为单行（- {fact_id} · {entity} · {key}: {first ~120 chars}… (fetch for full)），上限约为 2,000 个字符。只需显式调用一次 fetch，即可获取完整文本。[COMPANY POLICY] 卡片除外——无论预览模式还是完整模式，始终完整显示（防止混淆的关键内容绝不截断）。
• 会话去重——已在本会话中返回的 fact_ids 会作为 exclude_ids 传回，因此后续轮次不会在模型已有的事实上重复消耗预算；节省的预算会用于新事实。
• 客户端缓存——~/.ultramemory/cache.json（由 ultramemory enable 创建，可由用户编辑，权限为 chmod 600，采用 LRU 策略，最多缓存 500 个条目 / 约 1 MB）。缓存相同的 recall 查询 5 分钟（重复查询不会产生任何 HTTP 调用），并跟踪每个会话 24 小时内已见的 fact_ids。删除该文件即可重置；损坏的文件会被静默重建。

环境可调参数：

环境变量	默认值	效果
ULTRAMEMORY_CACHE=off	on	总开关——完全禁用 memo 和已见缓存
ULTRAMEMORY_PREVIEW=off	on	Hermes 预取恢复为完整（非预览）recall
ULTRAMEMORY_HOOK_BUDGET	2000	Claude Code hook recall 的字符预算
ULTRAMEMORY_HOOK_POLICY_BUDGET	12000	hook 在 [COMPANY POLICY] 轮次中的注入上限（策略全文，绝不截断）
ULTRAMEMORY_MIN_CONFIDENCE	low	低于此 recall 置信度时，hook 会跳过注入

为什么选择 UltraMemory

• 确定性地优先 recall。“先 recall”已写入工具说明和 Hermes 自动注入中，而不是交由模型决定是否查找。hook 会在每条提示词前确定性地尝试注入（失败时放行，注入最匹配内容）；再结合 CLAUDE.md 中要求 Agent 主动进行推理中查找的规则，这三者共同构成真正的优先 recall 保证。
• 坦诚面对未知。 元记忆门控会选择弃答或要求核实，而不是编造内容。

许可证

Apache-2.0（见 LICENSE）。这是开源的客户端部分。UltraMemory 后端/引擎——recall 排序、元记忆门控、存储、计量和计费——是独立的专有托管服务，地址为 https://api.ultramemory.us。