> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myrmagent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Plugins 记忆插件

> 让任何支持 Agent Plugins 标准的客户端（VS Code、Copilot、Kiro、Cursor 等）获得由 Myrm 支撑的长期记忆。

# Agent Plugins 记忆插件

Myrm 提供一份符合 [Agent Plugins](https://agent-plugins.org) 标准的便携插件，可将长期记忆接入任何支持该标准的客户端 —— VS Code、GitHub Copilot、Kiro、Cursor、ChatGPT、Codex 等。插件仅负责传输层：它将 MCP 客户端指向 Myrm 的记忆服务，并教会接入的 agent 何时、如何使用记忆，无需逐客户端手工编辑配置文件。

## 插件包含

| 文件                            | 作用                                           |
| ----------------------------- | -------------------------------------------- |
| `plugin.json`                 | 插件清单（名称、版本、描述）。                              |
| `mcp.json`                    | 指向 Myrm `/mcp` 端点的 Streamable HTTP MCP 服务配置。 |
| `skills/myrm-memory/SKILL.md` | 给接入 agent 的操作指引：何时回忆、存储、审计与修正记忆。             |

## 生成插件

1. 打开 **设置 → 记忆 → 连接**（连接向导）。
2. 选择要对外暴露记忆的 Myrm 智能体。
3. 在 **Agent Plugins** 卡片中，选择将 token 写入插件文件，或从 `MYRM_MCP_TOKEN` 环境变量读取。
4. 点击 **生成 Agent Plugins 插件**，然后点击 **下载全部 (.zip)** 一次性下载整个插件，或逐个复制各文件。解压压缩包 —— 其中已包含正确的目录结构 —— 放入客户端的插件目录并启用即可。

请保持上方列出的插件目录结构：`plugin.json` 与 `mcp.json` 放在插件根目录，`SKILL.md` 放在 `skills/myrm-memory/` 子目录下 —— zip 会自动保持该结构；若逐个复制文件，请手动重建。客户端只会从 `skills/<name>/` 子目录加载技能文件，平放在根目录的 `SKILL.md` 会被静默忽略。

将 token 写入插件文件模式开箱即用，但会把凭据写进 `mcp.json`，请勿将此类插件提交到版本库。默认的环境变量模式保持插件无凭据、可安全提交：多数客户端替换 `${MYRM_MCP_TOKEN}`，部分客户端（VS Code、Cursor）使用 `${env:MYRM_MCP_TOKEN}`。若客户端不支持插值，可在向导中开启 token 写入模式——token 随时可撤销。

## 管理访问

* 生成的 token 与所选 Myrm 智能体绑定，通过插件只能访问该智能体的记忆。
* 在向导中**重新生成**插件即可签发新 token —— 旧 token 立即失效，使用旧插件的客户端需重新配置。
* 在向导中**撤销**连接可立即吊销 token。
* 依赖前可先通过向导的**健康检查**验证连接。

## 运行 Doctor 检查

向导的 **Doctor** 按钮比在线 token 测试更进一步：它会读取你机器上 MCP 客户端的**真实配置文件**，从客户端侧确认插件是否正确接入。

| 诊断码                   | 含义                                          | 严重度 |
| --------------------- | ------------------------------------------- | --- |
| `verified`            | 找到配置文件、`myrm-memory` 条目存在、Bearer Token 哈希匹配 | 健康  |
| `token_valid`         | Token 存在且与存储哈希匹配（无文件可校验）                    | 健康  |
| `token_env`           | 条目使用 `${MYRM_MCP_TOKEN}` —— 本机无法校验最终值       | 需注意 |
| `config_file_missing` | 配置路径不存在（请检查 `~/.claude.json` 等）             | 失败  |
| `entry_missing`       | 文件存在但预期键下没有 `myrm-memory` 条目                | 失败  |
| `token_missing`       | 条目存在但缺少 `Authorization: Bearer <token>` 头   | 失败  |
| `token_mismatch`      | 文件中的 Token 与存储哈希不匹配 —— 请重新复制配置片段            | 失败  |
| `file_unreadable`     | 文件存在但不是合法 JSON/TOML                         | 失败  |

* 同时支持 JSON（`json_mcp`）与 TOML（`toml_mcp`）两种客户端格式，路径中的 `~` 自动展开。
* Token 仅以 SHA-256 哈希存储 —— 绝不落明文。
* 诊断消息支持 6 种语言（EN / 中文 / 繁體 / 日本語 / 한국어 / DE），每个诊断码都附可执行的修复指引。
* Doctor 只读不写 —— 绝不修改你客户端的配置文件。

## 自托管

插件仅负责传输层，因此同样适用于自托管实例 —— 本地 Web UI、桌面端或云沙箱。将 `mcp.json` 中的 `url` 指向你实例的 `/mcp` 端点，并到对应实例的连接向导生成 token 即可。