> ## 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의 메모리 서버로 연결하고, 연결된 에이전트가 언제 어떻게 기억을 사용해야 하는지 안내합니다. 클라이언트별 설정 파일을 직접 편집할 필요가 없습니다.

## 번들 구성

| 파일                            | 용도                                                 |
| ----------------------------- | -------------------------------------------------- |
| `plugin.json`                 | 번들 매니페스트(이름, 버전, 설명).                              |
| `mcp.json`                    | Myrm `/mcp` 엔드포인트를 가리키는 Streamable HTTP MCP 서버 설정. |
| `skills/myrm-memory/SKILL.md` | 연결된 에이전트용 운영 가이드: 언제 기억을 회상·저장·감사·수정할지.            |

## 번들 생성

1. **설정 → 메모리 → 연결**(연결 마법사)을 엽니다.
2. 외부에 노출할 Myrm 에이전트를 선택합니다.
3. **Agent Plugins** 카드에서 번들에 토큰을 포함할지, `MYRM_MCP_TOKEN` 환경 변수에서 읽을지 선택합니다.
4. **Agent Plugins 번들 생성**을 클릭한 뒤 \*\*전체 다운로드 (.zip)\*\*로 번들 전체를 한 번에 다운로드하거나, 각 파일을 개별 복사합니다. 압축 파일을 풀면 — 올바른 구조가 이미 포함되어 있습니다 — 클라이언트의 플러그인 디렉터리에 넣고 활성화합니다.

위에 나열된 번들 구조를 유지하세요: `plugin.json`과 `mcp.json`은 플러그인 루트에, `SKILL.md`는 `skills/myrm-memory/` 하위 디렉터리에 넣어야 합니다. zip은 이 구조를 자동으로 유지합니다. 파일을 하나씩 복사했다면 직접 다시 만들어야 합니다. 클라이언트는 `skills/<name>/` 하위 디렉터리의 스킬 파일만 로드하므로, 루트에 평평하게 둔 `SKILL.md`는 조용히 무시됩니다.

토큰 포함 모드는 바로 사용할 수 있지만 `mcp.json`에 자격 증명이 기록되므로 해당 번들은 버전 관리에 커밋하지 마세요. 기본 환경 변수 모드는 번들을 자격 증명 없이 유지하고 안전하게 커밋할 수 있게 합니다. 대부분의 클라이언트는 `${MYRM_MCP_TOKEN}`을 대체하며, 일부(VS Code, Cursor)는 `${env:MYRM_MCP_TOKEN}`을 사용합니다. 대체를 지원하지 않는 클라이언트는 마법사에서 토큰 포함 모드를 켜면 됩니다 — 토큰은 언제든 취소할 수 있습니다.

## 접근 관리

* 생성된 토큰은 선택한 Myrm 에이전트에 바인딩되며, 번들로 접근할 수 있는 기억은 해당 에이전트의 기억뿐입니다.
* 마법사에서 번들을 **재생성**하면 새 토큰이 발급되고 — 이전 토큰은 즉시 무효화되므로, 기존 번들을 사용하는 클라이언트는 다시 구성해야 합니다.
* 마법사에서 연결을 **해지**하면 토큰이 즉시 무효화됩니다.
* 사용 전에 마법사의 **상태 점검**으로 연결을 확인하세요.

## Doctor 검사 실행

마법사의 **Doctor** 버튼은 온라인 토큰 테스트보다 한 단계 더 나아갑니다. 사용자 머신의 MCP 클라이언트 **실제 설정 파일**을 직접 읽어 클라이언트 쪽에서도 번들이 올바르게 연결되었는지 검증합니다.

| 진단 코드                 | 의미                                             | 심각도 |
| --------------------- | ---------------------------------------------- | --- |
| `verified`            | 설정 파일 발견, `myrm-memory` 항목 존재, Bearer 토큰 해시 일치 | 정상  |
| `token_valid`         | 토큰이 존재하고 저장된 해시와 일치(검증할 파일 없음)                 | 정상  |
| `token_env`           | 항목이 `${MYRM_MCP_TOKEN}` 사용 — 로컬에서 최종 값 확인 불가   | 주의  |
| `config_file_missing` | 설정 경로가 존재하지 않음(`~/.claude.json` 등 확인)          | 실패  |
| `entry_missing`       | 파일은 있지만 예상 키 아래 `myrm-memory` 항목 없음            | 실패  |
| `token_missing`       | 항목은 있지만 `Authorization: Bearer <token>` 헤더 없음  | 실패  |
| `token_mismatch`      | 파일의 토큰이 저장된 해시와 불일치 — 설정 조각 다시 복사              | 실패  |
| `file_unreadable`     | 파일은 있지만 유효한 JSON/TOML 아님                       | 실패  |

* JSON(`json_mcp`)과 TOML(`toml_mcp`) 두 클라이언트 형식을 모두 지원하며, 경로의 `~`는 자동 확장됩니다.
* 토큰은 SHA-256 해시로만 저장됩니다 — 평문으로 저장하지 않습니다.
* 진단 메시지는 6개 언어(EN / 中文 / 繁體 / 日本語 / 한국어 / DE)를 지원하며, 모든 진단 코드에 실행 가능한 수정 가이드가 제공됩니다.
* Doctor는 읽기 전용입니다 — 클라이언트 설정 파일을 절대 수정하지 않습니다.

## 자체 호스팅

번들은 전송 계층만 담당하므로 자체 호스팅 인스턴스 — 로컬 Web UI, 데스크톱 앱, 클라우드 샌드박스 — 에서도 동일하게 동작합니다. `mcp.json`의 `url`을 인스턴스의 `/mcp` 엔드포인트로 바꾸고, 해당 인스턴스의 연결 마법사에서 토큰을 생성하면 됩니다.