Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: design for ai-memory marketplace plugins (#1166)
AkitaOnRails7871615ce0cb
diff --git a/docs/design-marketplace-plugins.md b/docs/design-marketplace-plugins.mdnew file mode 100644index 00000000..feb26ac0--- /dev/null+++ b/docs/design-marketplace-plugins.md@@ -0,0 +1,894 @@+# Design proposal: ai-memory as marketplace plugins (#1166)++**Status: proposal for 2.7, research done 2026-10-13. Not implemented.**+Builds on RFC #1166, the feedback comments on it, and the+[`docs/desktop/`](desktop/) notes (especially+[`verification-2026-10.md`](desktop/verification-2026-10.md) and+[`extensions.md`](desktop/extensions.md)).++## Summary++Ship ai-memory as a plugin in each coding app's plugin system, starting with+Claude Code. The plugin stays thin. It holds manifests, the routing skills,+an MCP entry that runs `ai-memory mcp-bridge`, and one small POSIX launcher+that hands every lifecycle event to the installed binary's native+`ai-memory hook` command. The server and the binary are still installed+separately. The plugin never captures through the curl script bundle, so+capture policy (`ignore_paths`, allowlist mode, server profiles) stays+enforced client-side exactly as it is for `install-hooks` today. When the+binary is missing, the plugin captures nothing, prints one line of guidance at+session start, and exits 0.++The marketplace lives in this repository. Catalog files sit at the repository+root and pin each plugin to the release tag, so `/plugin marketplace add+akitaonrails/ai-memory` only ever installs released plugin content.++Recommended 2.7 scope: the Claude Code plugin (CLI and the desktop Code tab),+its marketplace, CI validation, a sandboxed end-to-end test, and the+`setup`/`doctor`/`upgrade` integration. Codex follows in 2.7 if the trust+question below resolves cleanly. Cursor, Cowork capture, Antigravity and+Gemini come later.++## How this was checked++Two kinds of evidence, and the doc says which one backs each claim:++- **Docs.** Official documentation fetched on 2026-10-13. URLs are listed in+ [Sources](#sources).+- **Local runs.** Experiments on 2026-10-13 with Claude Code 2.1.296, Codex+ CLI 0.162.1, Gemini CLI 0.63.0 and `cursor-agent` 2026.10.01, each in a+ scratch config directory (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`). The+ operator's own agent configuration was not touched. A prototype Claude+ plugin with the manifests from this doc was validated, installed into the+ sandbox, and driven with `claude -p`.++What the local runs showed:++1. `claude plugin validate --strict <dir>` checks more than JSON syntax. It+ failed on an unknown hook event (`hooks.PostToolUze: unknown hook event;+ entry ignored at runtime`), on an unknown manifest key, and on a+ marketplace without `description`. Exit codes are usable in CI.+2. A sandboxed install works offline: `claude plugin marketplace add <path>`,+ `claude plugin install ai-memory@ai-memory`, `claude plugin details`.+3. **Plugin hooks fire in `claude -p` without any login.** With no+ credentials, `claude -p "say ok"` printed `Not logged in` but still ran+ the plugin's `SessionStart`, `UserPromptSubmit` and `SessionEnd` hooks.+ Through the prototype launcher and the 2.6.6 native binary, all three+ events landed in a scratch spool (`SessionStart` 38-63 ms including a+ failed handoff fetch, `UserPromptSubmit` 8-12 ms). The final run used the+ exact Claude manifests in this doc, loaded with `--plugin-dir`. CI can+ therefore test real hook wiring without an API key. Tool events need a+ model turn and cannot be driven this way.+4. **Shell-form hooks reject `${user_config.*}`.** Claude Code refused the+ hook with "references ${user_config.*} in a shell-form command. … Use exec+ form instead … or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's+ environment."+5. **Option defaults are not applied in hooks.** With an option left unset,+ an exec-form hook referencing it failed ("Plugin option "server_url" isn't+ set"), and `CLAUDE_PLUGIN_OPTION_SERVER_URL` was absent from the hook+ environment. The same unset option *was* substituted with its default in+ the MCP server's `args`. Hooks must therefore never depend on an option+ being set; the launcher supplies its own defaults.+6. `CLAUDE_PLUGIN_OPTION_<KEY>` is exported to hook processes (shell and exec+ form) once the user sets the option. It is not exported to MCP servers.+7. The plugin's stdio MCP server receives `CLAUDE_CODE_SESSION_ID`, so the+ session-aware `ai-memory mcp-bridge` works unchanged. The server is named+ `plugin:ai-memory:ai-memory` and its tools are+ `mcp__plugin_ai-memory_ai-memory__<tool>`. Nothing in the codebase matches+ on the `mcp__ai-memory__` prefix, so the rename is harmless.+8. An exec-form hook whose binary is missing fails with a non-blocking+ "Executable not found in $PATH" error on every event.+9. **The Docker host wrapper runs `ai-memory hook` in a container.**+ `bin/ai-memory` sends `mcp-bridge`, `install-hooks` and a few other+ commands to the native host client, but not `hook`. A launcher that found+ the wrapper on `PATH` paid about 280 ms per event (a `docker run`), and+ inside the container `127.0.0.1` is the container. The native client+ took about 5 ms per event. The wrapper has to route `hook` to the native+ client before a plugin can rely on `PATH` (Phase 1, item 2).+10. Codex 0.162.1 accepted a plugin in the portable layout (root+ `plugin.json`, `mcp.json`, `hooks/hooks.json`) from a local+ `.agents/plugins/marketplace.json`: `codex plugin marketplace add` and+ `codex plugin add ai-memory@ai-memory` both succeeded in a scratch+ `CODEX_HOME`.++## Per-app capability table++Docs fetched 2026-10-13 unless marked otherwise. "Local" means confirmed in+the runs above.++| App | Hooks in a plugin | MCP in a plugin | Skills | Config and secrets | Updates | Distribution | Review / submission |+| --- | --- | --- | --- | --- | --- | --- | --- |+| **Claude Code** (CLI, desktop Code tab) | Yes, `hooks/hooks.json`; merged with user/project hooks; no per-hook approval prompt (install warning and workspace-trust rules only) | Yes, `.mcp.json` or `mcpServers`; stdio/http/sse/ws | Yes, `skills/` (namespaced `/ai-memory:<skill>`) | `userConfig`; `sensitive: true` goes to the OS credential store; `${user_config.KEY}` in MCP config and exec-form hook args; `CLAUDE_PLUGIN_OPTION_<KEY>` in hook env (local: only when set) | `version` pins users; third-party marketplaces have background auto-update **off** by default; `claude plugin update` | Own marketplace (`/plugin marketplace add owner/repo`), directory portal (`<name>@synced`), community marketplace | Directory portal needs a paid plan, README, license, no credentials in files; `claude-plugins-official` takes no portal submissions |+| **Claude Cowork** | Yes (loads) | Local stdio only "when the Cowork session runs on your computer"; remote listed as a connector | Yes | `${user_config.*}` in MCP "Ignored when a referenced option has no default; Cowork doesn't prompt" | Account-synced | Customize > Plugins, zip upload | Same as above; top-level `bin/` makes the plugin uninstallable |+| **Claude Chat tab** | Ignored | Remote only | Yes | Remote URL with `${user_config.*}` ignored | Account-synced | Customize > Plugins | Same |+| **Codex** (CLI + desktop) | Yes, `hooks/hooks.json` or `extensions."com.openai".hooks`; per-hook hash trust: "Installing or enabling a plugin doesn't automatically trust its hooks" | Yes, portable `mcp.json` (`type` required) or legacy `.mcp.json` | Yes | MCP auth types only; no documented per-plugin user settings | `codex plugin marketplace upgrade`; no documented auto-update | `.agents/plugins/marketplace.json` in a repo or `~/.agents/plugins/`; legacy `.claude-plugin/marketplace.json` | Public directory: "Plugins containing lifecycle hooks aren't eligible"; MCP must be public HTTPS |+| **Cursor** | Only in the Cursor Plugin format (`.cursor-plugin/plugin.json` + `hooks/hooks.json`); an Agent Plugin (root `plugin.json`) carries skills and MCP only | Yes, `mcp.json`; expands `${CURSOR_PLUGIN_ROOT}` and `${CLAUDE_PLUGIN_ROOT}` (not `${PLUGIN_ROOT}`) in MCP fields | Yes | `variables` schema, values entered in the dashboard, used as `${VAR}` in `mcp.json` | GitHub import auto-refresh (≤10 min) or manual Refresh | cursor.com/marketplace, team marketplaces, `.cursor-plugin/marketplace.json` at a repo root | "Every plugin is manually reviewed before it's listed"; no documented approval step for plugin hooks |+| **Gemini CLI** | Yes, `hooks/hooks.json` in the extension (timeouts in ms) | Yes, `gemini-extension.json` `mcpServers` | Yes | `settings[]` with `envVar`; `sensitive: true` uses the system keychain | Git HEAD or release tag; `gemini extensions update` | `gemini extensions install <git url>`; gallery crawls repos with topic `gemini-cli-extension` and a root manifest | Automated validation. Note: "Gemini CLI was replaced by Antigravity CLI on June 18th, 2026" for unpaid and Google One users |+| **Antigravity** | Yes, root `hooks.json`, documented for the CLI only; no SessionEnd or prompt event | Yes, `mcp_config.json` (`serverUrl`, not `url`) | Yes | Not documented | "automatically updated" (2.0) | `agy plugin install <name>@antigravity-plugins-official`, GitHub URL, local dir | Not documented; no plugin-root variable documented |+| **Copilot CLI** | Yes | Yes | Yes | Not documented | `copilot plugin update` | marketplace repos; also reads `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` as fallbacks | Not documented |+| **Factory Droid** | Yes, Claude-style `hooks/hooks.json`, `${DROID_PLUGIN_ROOT}` or `${CLAUDE_PLUGIN_ROOT}` | Yes, `mcp.json` (no secrets) | Yes | Not documented | `droid plugin marketplace update` | Reads `.factory-plugin/marketplace.json`, falls back to `.claude-plugin/marketplace.json` | Not documented |+| **OpenCode** | Code-level plugins (JS/TS events), not a hooks file | From config, not the plugin | — | Config | npm via Bun at startup | npm or local | None. ai-memory already generates this plugin (`install-hooks --agent opencode`) |+| **Kimi Code** | No (plugins are tool bundles) | No | — | `config_file`/`inject` | Reinstall | Local, zip, git | None |+| **Zed** | No | MCP extensions, "We plan to deprecate MCP server extensions in favor of the official MCP registry" | — | — | Registry | Extension registry | Registry PR |++Corrections to the table in RFC #1166:++- **Codex.** Plugins with hooks cannot go in the public directory, so a+ capturing Codex plugin ships through our own marketplace file. Installing+ it still leaves every hook untrusted until the user approves it in `/hooks`.+- **Cursor.** Hooks require the `.cursor-plugin/` format. An Agent Plugin, or a+ `cursor://` MCP deeplink, adds no hooks and so does not trigger the #721+ de-duplication.+- **Antigravity** can bundle MCP (`mcp_config.json`).+- **Gemini CLI** has been replaced by Antigravity CLI for most free users, so+ it ranks low.+- **Claude.** The anthropic-official listing is out of reach in practice.+ Besides having no submission route, its review prompt+ (`anthropics/claude-plugins-official/.github/policy/prompt.md`, read+ 2026-10-13) fails any plugin whose `UserPromptSubmit`, `PreToolUse` or+ `PostToolUse` hook "runs without a project-relevance gate". Capture hooks+ are ungated by design. The self-hosted marketplace is the channel; the+ directory portal is optional (see open questions).++## Design++### 1. What the plugin is, and what it is not++- **Manifests, skills, one launcher script.** No Node or Python, no+ compiled binary, no first-run download. This keeps the Rust-only core rule,+ passes the Claude directory checklist's "binary that isn't an image or+ font" hold, and avoids the patterns that made other memory plugins fragile+ (claude-mem's Bun bootstrap, cognee's 120 s blocking venv install,+ hindsight's unpinned `uvx …@latest`).+- **No top-level `bin/`.** Claude refuses to install such a plugin in Chat and+ Cowork. The launcher lives in `scripts/`.+- **The binary is installed once, separately** (install.sh, Homebrew, AUR,+ RPM, Docker wrapper, the macOS app). The plugin assumes it and says so+ plainly when it is missing.+- **The native hook is the only capture path.** The plugin never ships or+ calls `hooks/<agent>/*.sh`. Those scripts POST with curl and sit outside+ capture-policy v1 (row 11h in `security-boundaries.md`). If the plugin+ fell back to them when the binary is missing, `ignore_paths` and allowlist+ mode would be offered and silently not enforced. Without the binary the+ plugin captures nothing.++### 2. The launcher++One POSIX `sh` script, `scripts/ai-memory-hook`, shared by every plugin and+called as `ai-memory-hook <agent> <event>`. It:++1. picks the server URL: the plugin option (`CLAUDE_PLUGIN_OPTION_SERVER_URL`+ on Claude), else `AI_MEMORY_HOOK_URL`, else `http://127.0.0.1:49374`. It+ cannot rely on `userConfig` defaults, which hooks do not receive (local+ finding 5);+2. finds the binary: the `ai_memory_bin` option if set, else `command -v+ ai-memory`, else the install locations a GUI-launched app may not have on+ `PATH` (`$HOME/.local/bin`, `/opt/homebrew/bin`, `/usr/local/bin`,+ `/usr/bin`);+3. if nothing is found: reads and discards stdin, prints+ `{"systemMessage": "ai-memory: the ai-memory binary was not found, so this+ session is not captured. Install it and run ai-memory setup: <url>"}` on+ `session-start` and `{}` on every other event, and exits 0. This is the+ pattern Anthropic's own `claude-security` plugin uses for a missing+ Python;+4. otherwise runs `exec "$bin" hook --event <event> --agent <agent>+ --server-url <url> [--data-dir <dir>]` with `AI_MEMORY_HOOK_ORIGIN=<agent>-plugin`+ in the environment. The subcommand comes first so the Docker wrapper can+ intercept it.++The prototype took about 2 ms per call on the missing-binary path. The script+is short enough to read in full, which matters because plugin hooks run with+the user's full permissions.++Why a script and not exec form straight to `ai-memory`:++- exec form gives a raw "Executable not found" error on every tool call when+ the binary is missing (local finding 8);+- it cannot reach binaries that are off a GUI app's `PATH`;+- exec form with `${user_config.server_url}` fails outright when the option+ is unset (finding 5).++The script's cost is Windows. Claude Code runs shell-form hooks through Git+Bash on Windows, so the launcher works there when Git Bash is installed, and+fails without it (Claude then falls back to PowerShell). Codex has a+per-hook `commandWindows` override that can call `ai-memory.exe` directly.+See open question 4.++### 3. Changes to the binary (small, all in existing modules)++- **`hook`: origin-aware de-duplication.** Claude runs a plugin's hook and an+ identical settings-file hook separately ("A plugin's or skill's copy of the+ same handler stays separate"). A user with `install-hooks` already applied+ who adds the plugin would be captured twice. When+ `AI_MEMORY_HOOK_ORIGIN=claude-plugin` (read through the injectable lookup,+ invariant 1) and the Claude settings files already carry ai-memory hooks+ (`settings_file_carries_ai_memory_hooks` on the user file, honouring+ `CLAUDE_CONFIG_DIR`, and the repository's `.claude/settings.local.json`),+ the plugin copy is dropped and prints `{}`. This mirrors+ `is_redundant_cursor_copy` (#721). Settings hooks win because they carry+ flags the plugin does not (`--capture-assistant`, a baked+ `--project-strategy`). An env variable rather than a flag keeps an older+ binary working with a newer plugin; it just skips the de-duplication.+- **`hook` and `mcp-bridge`: an empty `--server-url` means unset.** This lets+ `.mcp.json` pass `${user_config.server_url}` while a user who has a+ configured `server_url` keeps it.+- **Docker wrapper: route `hook` to the native host client**, as it already+ does for `mcp-bridge` (local finding 9). Without this, a Docker-wrapper+ user's plugin hooks run in a container, over budget and pointed at the+ wrong loopback.+- **`setup`, `install-hooks`, `install-skills`:** detect an enabled+ ai-memory Claude plugin (`installed_plugins.json` plus `enabledPlugins` in+ the user settings) and stop writing the parallel Claude settings hooks,+ skills and MCP entry, printing what was skipped. `--force` keeps today's+ behaviour. `setup --server-url` writes the plugin's options through+ `claude plugin configure ai-memory@ai-memory --values-stdin` instead of+ editing Claude's files.+- **`doctor`:** report the plugin (version, enabled, options), version skew+ against the binary, duplicate wiring (plugin plus settings hooks, plugin+ skills plus installed skills), and a Docker wrapper on `PATH` without the+ routing fix. For Codex, extend `codex_hook_trust.rs` to plugin hooks.+- **`upgrade`:** when the plugin is installed, run `claude plugin+ marketplace update ai-memory` and `claude plugin update+ ai-memory@ai-memory` after replacing the binary, because background+ auto-update is off for third-party marketplaces. This keeps binary and+ plugin in step without asking users to opt into auto-update.+- **`uninstall`:** offer `claude plugin uninstall ai-memory@ai-memory`.++None of this touches the MCP tool surface, so the tool count stays at 23.++### 4. Configuration surface++Zero required settings. The defaults reproduce a local `ai-memory setup`+install.++| Knob | Claude plugin | Default | Notes |+| --- | --- | --- | --- |+| Server URL | `userConfig.server_url` (string) | `http://127.0.0.1:49374` | Read by the launcher from `CLAUDE_PLUGIN_OPTION_SERVER_URL`; MCP gets `${user_config.server_url}` |+| Binary path | `userConfig.ai_memory_bin` (string) | `ai-memory` | For installs off `PATH` |+| Data dir | `userConfig.data_dir` (string) | empty | Only for a non-default data dir |+| Token | **none in the plugin** | — | Hooks read `<data_dir>/auth-token`, the OIDC `auth.json` or a server profile; `mcp-bridge` reads the bearer `Config::load` resolves. Same files `setup`, `install-hooks --auth-token` and `auth login` already write |+| Project override, capture mode, `ignore_paths`, briefing, server routing | `.ai-memory.toml` marker, persisted capture mode, `servers.toml` profiles | as today | The native hook already enforces all of these. Nothing is duplicated into plugin settings |++Keeping the token out of the plugin keeps one credential store for hooks, MCP+and the CLI. It also avoids a pattern Anthropic's directory scan flags: an+Arroway source comment records an earlier build being flagged for reading a+token from the environment. A `sensitive` token option is open question 6.++Cowork: an unset option in an MCP entry loads there only if the option has a+default, and Cowork never prompts. Every option above has a default.++### 5. Trust and security++- **Claude.** No per-hook approval for plugin hooks; installing the plugin is+ the trust decision, plus workspace trust in interactive sessions. Plugin+ hooks run outside Claude's sandbox with full user permissions. The README+ and the marketplace description must say exactly what runs and what is+ sent: lifecycle payloads, sanitized by the server, to the configured+ ai-memory server only; no telemetry. `disableAllHooks` disables plugin+ hooks too, and `allowManagedHooksOnly` blocks them unless the plugin is+ force-enabled in managed settings. `doctor` reports both.+- **Codex.** Every plugin hook stays untrusted until approved in `/hooks`,+ and a changed handler is skipped silently. Install docs must say this, and+ `doctor` must detect untrusted or modified plugin hooks. Hook commands are+ kept byte-identical across releases (they reference `${PLUGIN_ROOT}`, never+ a versioned path), so trust can survive upgrades. Whether Codex hashes the+ handler before or after variable expansion is not verified (open question+ 2).+- **No secrets in plugin files.** CI greps the plugin tree for bearer-shaped+ strings, and `claude plugin validate` already warns on credential-looking+ header values and on non-loopback `http://` URLs.+- **Capture policy parity.** Every event goes through the native hook, which+ runs capture policy before spool and network (rows 11b, 11g, 11k). The+ launcher has no capture logic of its own.++**Third front door.** Shell hooks, the native client and the generated+TypeScript integrations are the existing three places marker, scope and+capture logic lives, and fixes have had to cover all three (#661, #668). A+plugin is a fourth entry point. It stays safe only if it adds no logic of its+own and the following stays true, each item backed by a test (see+[Tests](#tests)):++1. a plugin-launched event with an `ignore_paths` match never reaches the+ spool;+2. under allowlist capture mode, a repository without a marker emits nothing;+3. marker `workspace`/`project` and `servers.toml` routing apply to+ plugin-launched events exactly as to settings-launched ones;+4. a plugin copy and a settings copy of the same event produce one+ observation, and the plugin copy is the one dropped;+5. with no binary, nothing is sent anywhere and the agent is not blocked.++Implementation adds a row to `docs/security-boundaries.md` for the plugin+front door, citing these tests, in the same change.++### 6. Other harnesses reading our Claude files++Copilot CLI reads `.claude-plugin/plugin.json` and+`.claude-plugin/marketplace.json` as fallbacks, and Droid falls back to+`.claude-plugin/marketplace.json`. Codex also falls back to it when no+`.agents/plugins/marketplace.json` exists. A user who points one of those at+our repository would install the Claude plugin and send events tagged+`claude-code` in a payload dialect the server does not expect. Two guards:++- the launcher recognizes the other harnesses' markers (`DROID_PLUGIN_ROOT`,+ Codex's `PLUGIN_ROOT`, Cursor's `CURSOR_VERSION`). It hands the event to+ the matching ai-memory agent when one exists, and otherwise prints `{}` and+ exits;+- we ship a native catalog for each harness we support, so the fallback is+ never used.++The server's `agent_from_payload` relabelling remains the last line of+defence.++## Repository layout++Recommendation: keep the plugins and the marketplace catalogs **in this+repository**, with catalog entries pinned to the release tag.++```+.claude-plugin/marketplace.json Claude catalog (also read by Droid)+.agents/plugins/marketplace.json Codex catalog+.cursor-plugin/marketplace.json Cursor catalog (phase 3)+plugins/+ README.md what each plugin runs and sends+ claude-code/+ .claude-plugin/plugin.json+ hooks/hooks.json+ .mcp.json+ scripts/ai-memory-hook generated copy of the shared launcher+ skills/<six routing skills>/SKILL.md+ skills/status/SKILL.md+ README.md LICENSE+ codex/+ plugin.json mcp.json hooks/hooks.json scripts/ skills/+ cursor/+ .cursor-plugin/plugin.json mcp.json hooks/hooks.json scripts/ skills/+```++Each harness gets its own directory: event names, the `--agent` value and+the MCP flags (`--no-session-id` for everyone except Claude) all differ, and+Claude strips manifest keys it does not know while still loading+`hooks/hooks.json`. That rules out a shared hooks file in one directory+(Arroway and claude-mem keep separately named hooks files for the same+reason). Skills are copies generated from the same source, not symlinks;+symlinks break zip uploads and Windows checkouts.++Every file under `plugins/` is **generated** by Rust code from the sources+that already feed `install-hooks` and `install-skills`: `CLAUDE_CODE_EVENTS`,+`CODEX_EVENTS` and `CURSOR_EVENTS` in `render_shared.rs`, and the+`MANAGED_SKILLS` in `ai-memory-core::routing_skills`. A CLI suite test fails+when the committed tree differs from the renderer's output. That is how+plugin installs and CLI installs avoid drifting, the RFC's stated goal. The+renderer is a hidden `ai-memory render-plugins --out <dir>` subcommand with+two callers, the drift test and `bin/release`. A golden-file test with an+environment toggle would also work; the subcommand is easier to run by hand.++**Why in this repository:**++- Plugin files change in the same PR as the Rust code and tests they depend+ on, under the same CI and review.+- Claude (`git-subdir` with `ref`) and Codex (`git-subdir` with `ref` or+ `sha`) can pin each catalog entry to `vX.Y.Z`. Unreleased edits on `main`+ never reach users, and the catalog on `main` always points at the newest+ release. Cognee's Codex catalog already points back into its own repo this+ way.+- `bin/release` stamps every version and `ref` in the release commit, so the+ tag carries a catalog that points at itself. Nothing is pushed after the+ release and no cross-repository token is needed.+- The repository is small enough to serve as a marketplace: 1,011 tracked+ files and a 31 MiB pack, against the directory checklist's limits of+ 10,000 files and 50 MiB. Both CLIs offer `--sparse` for marketplace adds.++**Why not a separate `ai-memory-plugins` repository (yet):** it adds a+release step that needs a write token for another repository, a second place+to review, and a drift risk. It becomes worth it for formats that need a+manifest at the repository root: the Gemini gallery (`gemini-extension.json`+at the root), `agy plugin install <github url>`, and possibly a directory+submission whose reviewer clones the whole repository. If that happens,+the release workflow can publish `plugins/<harness>/` into it as generated+output, the same way Arroway's public repo mirrors a private source.++The Cursor catalog cannot pin a ref as far as the docs say. Cursor imports a+repository and refreshes it. Phase 3 has to verify whether a branch can be+chosen (a `plugins-release` branch moved by the release workflow would solve+it) before Cursor ships.++## Manifests++These are the files the renderer would produce for 2.7.0. The Claude ones+passed `claude plugin validate --strict` in the prototype.++### Phase 1: Claude Code++`.claude-plugin/marketplace.json` (repository root):++```json+{+ "name": "ai-memory",+ "owner": { "name": "AkitaOnRails", "url": "https://github.com/akitaonrails" },+ "description": "ai-memory plugins: lifecycle capture and memory tools for coding agents, backed by your own ai-memory server.",+ "plugins": [+ {+ "name": "ai-memory",+ "description": "Long-term memory across sessions and harnesses.",+ "source": {+ "source": "git-subdir",+ "url": "https://github.com/akitaonrails/ai-memory.git",+ "path": "plugins/claude-code",+ "ref": "v2.7.0"+ }+ }+ ]+}+```++`plugins/claude-code/.claude-plugin/plugin.json`:++```json+{+ "name": "ai-memory",+ "displayName": "ai-memory",+ "version": "2.7.0",+ "description": "Long-term memory across sessions and harnesses. Hands each lifecycle event to the installed ai-memory binary, which applies your capture exclusions and sends a sanitized record only to your ai-memory server (default http://127.0.0.1:49374). Adds the ai-memory MCP tools. No telemetry. Requires the ai-memory binary.",+ "author": { "name": "AkitaOnRails", "url": "https://github.com/akitaonrails" },+ "homepage": "https://github.com/akitaonrails/ai-memory",+ "repository": "https://github.com/akitaonrails/ai-memory",+ "license": "MIT",+ "keywords": ["memory", "mcp", "hooks", "handoff", "context"],+ "userConfig": {+ "server_url": {+ "type": "string",+ "title": "ai-memory server URL",+ "description": "Base URL of the ai-memory server. Keep the default for a local install.",+ "default": "http://127.0.0.1:49374"+ },+ "ai_memory_bin": {+ "type": "string",+ "title": "ai-memory executable",+ "description": "Path to the ai-memory binary, only needed when it is not on PATH.",+ "default": "ai-memory"+ },+ "data_dir": {+ "type": "string",+ "title": "ai-memory data directory",+ "description": "Only for an install that uses a non-default data directory.",+ "default": ""+ }+ }+}+```++`plugins/claude-code/hooks/hooks.json`, the same nine events and empty+matchers `install-hooks` writes today:++```json+{+ "description": "ai-memory lifecycle capture through the installed ai-memory binary",+ "hooks": {+ "SessionStart": [{ "matcher": "", "hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/ai-memory-hook claude-code session-start" }] }],+ "UserPromptSubmit": [{ "matcher": "", "hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/ai-memory-hook claude-code user-prompt-submit" }] }],+ "PreToolUse": [{ "matcher": "", "hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/ai-memory-hook claude-code pre-tool-use" }] }],+ "PostToolUse": [{ "matcher": "", "hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/ai-memory-hook claude-code post-tool-use" }] }],+ "PreCompact": [{ "matcher": "", "hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/ai-memory-hook claude-code pre-compact" }] }],+ "Stop": [{ "matcher": "", "hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/ai-memory-hook claude-code stop" }] }],+ "SessionEnd": [{ "matcher": "", "hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/ai-memory-hook claude-code session-end" }] }],+ "SubagentStart": [{ "matcher": "", "hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/ai-memory-hook claude-code subagent-start" }] }],+ "SubagentStop": [{ "matcher": "", "hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/ai-memory-hook claude-code subagent-stop" }] }]+ }+}+```++No `timeout` is set, matching `install-hooks`. The native hook returns after+a local spool write. `SessionEnd` has a 1.5 s budget in Claude, and a+plugin's own `timeout` cannot raise it ("Timeouts set on plugin-provided+hooks don't raise the budget"); the native `session-end` already fits it,+because it hands the drain to a detached process. `async: true` on the tool+events is worth measuring later, but it changes how Claude reports output, so+2.7 keeps parity with the settings hooks.++`plugins/claude-code/.mcp.json`:++```json+{+ "mcpServers": {+ "ai-memory": {+ "command": "${user_config.ai_memory_bin}",+ "args": ["mcp-bridge", "--server-url", "${user_config.server_url}"]+ }+ }+}+```++The session-aware bridge (no `--no-session-id`), the same one `install-mcp+--client claude-code` registers; the plugin MCP process receives+`CLAUDE_CODE_SESSION_ID` (local finding 7). No token: the bridge+authenticates with the bearer `Config::load` resolves. `.mcp.json` takes the+binary from an option rather than the launcher because a stdio MCP `command`+must be a real executable on Windows.++`plugins/claude-code/skills/` holds the six managed routing skills plus a+`status` skill with `disable-model-invocation: true`, invoked as+`/ai-memory:status`. It runs `ai-memory doctor` for the plugin's agent and+summarizes the result: binary found, server reachable, duplicate wiring, spool+backlog, and for Codex untrusted hooks. The skill only reports. Fixes+stay with the user.++The six routing skills duplicate what `install-skills` puts in+`~/.claude/skills`, and two copies of each description would sit in context.+`setup` and `install-skills` skip the Claude target when the plugin is+enabled (section 3).++### Phase 2: Codex++Portable layout, which Codex 0.162.1 accepted locally (finding 10).++`.agents/plugins/marketplace.json`:++```json+{+ "name": "ai-memory",+ "interface": { "displayName": "ai-memory" },+ "plugins": [+ {+ "name": "ai-memory",+ "source": {+ "source": "git-subdir",+ "url": "https://github.com/akitaonrails/ai-memory.git",+ "path": "plugins/codex",+ "ref": "v2.7.0"+ },+ "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },+ "category": "Productivity"+ }+ ]+}+```++`plugins/codex/plugin.json`:++```json+{+ "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",+ "name": "ai-memory",+ "version": "2.7.0",+ "description": "Long-term memory across sessions and harnesses, backed by the installed ai-memory binary and your ai-memory server. No telemetry."+}+```++`plugins/codex/mcp.json`:++```json+{+ "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",+ "mcpServers": {+ "ai-memory": { "type": "stdio", "command": "ai-memory", "args": ["mcp-bridge", "--no-session-id"] }+ }+}+```++`plugins/codex/hooks/hooks.json` (default discovery; seven `CODEX_EVENTS`):++```json+{+ "hooks": {+ "SessionStart": [{ "hooks": [{ "type": "command",+ "command": "sh \"${PLUGIN_ROOT}/scripts/ai-memory-hook\" codex session-start",+ "commandWindows": "ai-memory hook --event session-start --agent codex --server-url http://127.0.0.1:49374" }] }]+ }+}+```++The remaining events follow the same shape. `SessionEnd` stays within Codex's+1 s default (3 s maximum). Open questions for Codex: which `authentication`+policy value suits a plugin with no auth of its own, whether omitting+`matcher` is valid for every event, and whether a hook trusted once stays+trusted after a plugin upgrade (open question 2). The catalog+`ref` is stamped by `bin/release` exactly like Claude's.++### Phase 3: Cursor++`.cursor-plugin/plugin.json` plus Cursor's camelCase events from+`CURSOR_EVENTS` (`sessionStart`, `sessionEnd`, `beforeSubmitPrompt`,+`preToolUse`, `postToolUse`, `postToolUseFailure`, `preCompact`, `stop`):++```json+{ "name": "ai-memory", "version": "2.7.0",+ "description": "Long-term memory across sessions and harnesses, backed by the installed ai-memory binary. No telemetry.",+ "author": { "name": "AkitaOnRails" }, "license": "MIT" }+```++```json+{ "hooks": { "sessionStart": [ { "command": "sh \"${CURSOR_PLUGIN_ROOT}/scripts/ai-memory-hook\" cursor session-start" } ] } }+```++```json+{ "mcpServers": { "ai-memory": { "command": "ai-memory", "args": ["mcp-bridge", "--no-session-id"] } } }+```++Not verified, and must be settled before Cursor ships:++- whether `${CURSOR_PLUGIN_ROOT}` expands in hook commands (the docs only+ promise it for MCP fields);+- what a relative `./scripts/…` resolves against;+- whether the plugin `hooks.json` needs `"version": 1`;+- whether Cursor's third-party import also runs hooks from Claude *plugins*,+ or only from Claude settings files.++The #721 de-duplication has to learn about the Cursor plugin. Today+`cursor_native_hooks_installed` looks only at `~/.cursor/hooks.json`.++### Later: Antigravity, Gemini CLI, Copilot CLI, Droid++- **Antigravity.** It documents no plugin-root variable, so a hook cannot+ find a bundled launcher. Its hook would have to call `ai-memory` from+ `PATH`, which brings back the GUI `PATH` problem. Install by GitHub URL+ probably needs a root manifest. The per-turn `invocationNum` issue+ (verification notes) should be fixed first.+- **Gemini CLI.** Needs a root `gemini-extension.json` for the gallery and for+ install-by-URL. Low priority given the move to Antigravity.+- **Copilot CLI and Droid.** Both read Claude-style layouts and have Claude-style+ hooks. Each needs its own directory and catalog (`.github/plugin/`,+ `.factory-plugin/`) with its own `--agent`. The launcher guard in section 6+ covers the meantime.++## Automation++### On pull requests (`.github/workflows/plugins.yml`, path-filtered)++Paths: `plugins/**`, the three catalog files, `render_shared.rs`,+`ai-memory-core/src/routing_skills/**`, `bin/ai-memory`, the workflow itself.++1. **Drift and versions.** `cargo nextest run -p ai-memory-cli -E+ 'test(/plugin/)'`: the committed `plugins/` tree equals the renderer+ output, every manifest version equals `workspace.package.version`, every+ catalog `ref` is `v<that version>`, and the plugin tree has no+ bearer-shaped strings.+2. **Claude validation.** Install a pinned Claude Code CLI (as a CI tool,+ not a build dependency), then `claude plugin validate --strict .` (marketplace)+ and `claude plugin validate --strict plugins/claude-code`.+3. **Launcher tests.** `shellcheck -s sh` plus `tests/hooks/test_plugin_launcher.sh`:+ missing binary (exit 0, `systemMessage` only on session-start, stdin+ drained), option precedence, the Docker wrapper on `PATH`, the+ foreign-harness guard, and a timing bound.+4. **Sandboxed Claude end-to-end.** Build the binary, start `ai-memory serve`+ on a scratch data dir and a free port, then:++ ```bash+ export CLAUDE_CONFIG_DIR="$RUNNER_TEMP/claude"+ mkdir -p "$CLAUDE_CONFIG_DIR"+ # Options for a --plugin-dir plugin live under the id "ai-memory@inline".+ jq -n --arg url "$URL" --arg bin "$PWD/target/debug/ai-memory" --arg dd "$RUNNER_TEMP/data" \+ '{pluginConfigs: {"ai-memory@inline": {options: {server_url: $url, ai_memory_bin: $bin, data_dir: $dd}}}}' \+ > "$CLAUDE_CONFIG_DIR/settings.json"+ cd "$FIXTURE_REPO"+ env -u ANTHROPIC_API_KEY claude -p "hi" --plugin-dir "$GITHUB_WORKSPACE/plugins/claude-code" || true+ ```++ Then assert through `/api/v1` or `ai-memory search` that the server holds+ `session-start`, `user-prompt-submit` and `session-end` observations for+ agent `claude-code` in the project the fixture's marker names. This works+ without credentials (local finding 3). `--plugin-dir` loads the PR's files+ directly; the catalog itself pins a tag that does not exist yet, so a+ second step only runs `claude plugin marketplace add "$GITHUB_WORKSPACE"`+ and checks that the catalog loads. Scrub `AI_MEMORY_*` and managed-run+ variables first: in the prototype run they leaked a `managed_run`+ parameter into the spooled URL.+5. **Front-door parity.** Tool events cannot be driven without a model, so+ policy parity is tested one level down. Pipe recorded Claude payloads+ through the launcher into the real binary and assert that an+ `ignore_paths` match never reaches the spool, that allowlist mode without+ a marker emits nothing, that marker and `servers.toml` routing apply, and+ that a plugin copy is dropped when settings hooks exist. These are the+ adversarial tests the security-boundary row cites.+6. **Codex smoke.** In a scratch `CODEX_HOME`: `codex plugin marketplace add`+ on the checkout, then `codex plugin add ai-memory@ai-memory`, and assert+ the cached plugin root contains the expected files. Optionally, drive `codex+ app-server` with `hooks/list` (the method used in the verification notes)+ to assert the hooks are discovered and reported `untrusted`.+7. **Windows.** Add `plugins/**` to `windows.yml`'s path filter once the+ Windows story is decided.++### On release++- `bin/release <version>` stamps `version` in every plugin manifest and+ catalog entry and sets every catalog `ref` to `v<version>`, in the same+ commit that bumps `Cargo.toml`.+- `release.yml`'s `validate-version` job also checks those values against+ the tag.+- The `github-release` job attaches `ai-memory-claude-plugin.zip` (the+ `plugins/claude-code` tree) and its `.sha256`, for **Customize > Plugins >+ Upload plugin** in the desktop app and Cowork.+- Nothing else is published. The catalogs on `main` point at the new tag as+ soon as the release commit lands. Existing users get the update through+ `ai-memory upgrade` (section 3), `claude plugin update`, or auto-update if+ they turned it on.+- Add "plugin catalogs point at the new tag; `claude plugin validate` passes+ on the tag" to the release checklist next to the Homebrew tap step.++`claude plugin tag` creates `{name}--v{version}` tags. We already tag+`vX.Y.Z`, and our catalogs point at that tag, so it is not needed.++## Tests++Mapped to the boundary inventory, all at integration level:++| Test | Proves | Where |+| --- | --- | --- |+| Committed `plugins/` equals renderer output; versions and refs match the workspace | No drift between CLI and plugin installs | CLI `tests/suite/plugins.rs` |+| Launcher, missing binary | Fail-open, guidance once, nothing sent | `tests/hooks/test_plugin_launcher.sh` |+| `ignore_paths` and allowlist through the launcher | Capture policy parity (front door 1, 2) | CLI suite, real binary, recorded payloads |+| Marker and server-profile routing through the launcher | Scope parity (front door 3) | CLI suite, beside `marker_scope.rs` and `server_profiles.rs` |+| Plugin copy plus settings copy gives one observation; control: plugin alone delivers | De-duplication (front door 4), adversarial with a control | `hook.rs` unit test plus CLI suite |+| Docker wrapper routes `hook` to the native client | Wrapper fix | `scripts/check-native-packaging.sh` |+| Sandboxed Claude install fires hooks into a scratch server | Real wiring, no API key | `plugins.yml` |++## Phased plan for 2.7++Estimates are engineer-days for one person familiar with the codebase.++| Phase | Work | Estimate |+| --- | --- | --- |+| **0. Verification spikes** | Codex: does trust survive a plugin version bump? (two installs, `hooks/list` on each). Claude Desktop Code tab on macOS: what `PATH` do plugin hooks get? Cowork on macOS/Windows: do plugin hooks run on the host and reach `127.0.0.1:49374`? Claude Code on Windows with and without Git Bash. Cursor: the four unknowns above | 1-1.5 |+| **1. Claude Code plugin** | Renderer and hidden `render-plugins`; launcher; `plugins/claude-code`; root catalog; `hook` origin de-duplication; empty `--server-url` handling; Docker wrapper `hook` routing; `setup`/`install-*`/`doctor`/`upgrade`/`uninstall` integration; drift, launcher, parity and de-duplication tests; `docs/install.md` and `docs/mcp-install.md` sections, `plugins/README.md`, CHANGELOG `Added`, security-boundaries row | 4-5 |+| **2. CI and release automation** | `plugins.yml` (validate, launcher, sandboxed e2e, Codex smoke); `bin/release` stamping; `validate-version` extension; release zip asset | 1.5-2 |+| **3. Codex plugin** | `plugins/codex`, `.agents/plugins/marketplace.json`, `commandWindows`, trust guidance in docs, `doctor` plugin-hook trust check | 2 |+| **4. Cursor plugin** (2.7 stretch, else 2.8) | Depends on the phase 0 answers; #721 detection of the Cursor plugin; branch strategy for the Cursor import | 2-3 |+| **Later** | Cowork capture if phase 0 shows hooks run in the VM; Antigravity; Gemini; Copilot CLI and Droid catalogs; a directory submission | — |++Phases 1 to 3 come to roughly 9 to 10.5 days. This is additive work, so it targets+`release/2.7`, not `main`.++## Open questions for the maintainer++1. **Directory listing.** The self-hosted marketplace covers Claude Code and+ (by zip upload) Cowork. Do we also want the claude.ai directory portal,+ which needs a paid plan, a README describing every network call, and+ possibly review of the whole repository? An allowlist-capture variant+ (events only from repositories with an `.ai-memory.toml` marker) would+ arguably satisfy the "project-relevance gate" rule. That would be a+ second plugin with a different default, so it is not proposed for 2.7.+2. **Codex trust across upgrades.** If Codex hashes hook commands after+ expanding `${PLUGIN_ROOT}`, every plugin update needs a fresh `/hooks`+ approval, and an untrusted hook is skipped silently. Is that acceptable+ with `doctor` and `/ai-memory:status` flagging it, or should Codex stay on+ `install-hooks` (one trust per command change) until Codex changes?+3. **Cowork.** If phase 0 shows Cowork hooks run inside the VM, where the+ binary is absent and the host loopback may be unreachable, should the+ plugin say "Cowork is not captured" at session start, or stay silent+ there? The `systemMessage` would otherwise appear on every Cowork session.+ The #878 report that "each message ends and reopens the session" also+ means one session-start (and handoff check) per message.+4. **Windows.** Accept "Git Bash required" for Claude plugin hooks on Windows+ (Claude Code already prefers Git Bash for hooks), or add a PowerShell twin+ of the launcher? A hook entry cannot switch by OS in Claude, though Codex's+ `commandWindows` can.+5. **Which wiring wins.** Proposed: settings hooks win at runtime, and+ `setup` stops writing them once the plugin is enabled. The alternative is+ to make the plugin the default Claude Code install path in `setup` and+ migrate existing settings hooks. That is cleaner long-term but changes+ behaviour for every current user.+6. **Token option.** Add a `sensitive` `auth_token` option, kept in the OS+ credential store, for remote-server users who never run the CLI's auth+ commands? It would need the hook to accept a token from the environment,+ a new input on the trust boundary. Proposed: no for 2.7.+7. **Marketplace and plugin names.** `ai-memory@ai-memory` reads a little+ odd, but both names are free of the reserved prefixes, and changing a+ plugin name later needs a `renames` entry. Keep it?+8. **Folderless sessions** (Code tab scratch workspaces, Cursor's empty+ window) still land in `default/scratch`. The plugin does not change that.+ It stays a separate decision (`desktop/plan.md` phase 2).++## What we borrowed and what we avoided++From the memory tools surveyed (claude-mem, supermemory, mem0, cognee,+hindsight, Arroway, engram) and Anthropic's own plugins:++- **Borrowed:**+ - one dependency-free hook entry point per host;+ - fail open with `{"systemMessage": …}` once when a runtime is missing+ (Anthropic's `claude-security`, `security-guidance`);+ - generated per-host directories with a drift check in CI (mem0's+ `build.py --check`);+ - a clean-profile `marketplace add` + `install --json` smoke test (cognee);+ - a version-consistency check across manifests (cognee, engram);+ - a description that states what is sent and that there is no telemetry.+- **Avoided:**+ - first-run installs inside hooks (claude-mem's Bun bootstrap, cognee's+ 120 s blocking venv install, hindsight's unpinned `uvx …@latest`);+ - hooks that scan the plugin cache for the newest version (claude-mem);+ - tokens in plugin-directory or repository-local config files (claude-mem+ Cowork, supermemory);+ - blocking hooks with long timeouts (hindsight's 45 s recall, Arroway's+ 700 s `Stop`);+ - default-on identified telemetry (mem0);+ - a top-level `bin/`.++## Appendix: the prototype launcher++The script used in the local runs. The shipped version adds the+foreign-harness guard from section 6, per-harness option variables, and the+`shellcheck` and shell tests listed under Automation.++```sh+#!/bin/sh+# ai-memory plugin hook launcher. Usage: ai-memory-hook <agent> <event>+# Resolves the installed ai-memory binary and hands the event to the native+# `ai-memory hook` command, which owns capture policy, spooling and routing.+# Never blocks the agent: a missing binary drains stdin and exits 0.+agent="$1"+event="$2"+url="${CLAUDE_PLUGIN_OPTION_SERVER_URL:-${AI_MEMORY_HOOK_URL:-http://127.0.0.1:49374}}"+bin="${CLAUDE_PLUGIN_OPTION_AI_MEMORY_BIN:-}"+if [ -z "$bin" ] || [ "$bin" = "ai-memory" ]; then+ bin=""+ if command -v ai-memory >/dev/null 2>&1; then+ bin=$(command -v ai-memory)+ else+ for candidate in "$HOME/.local/bin/ai-memory" /opt/homebrew/bin/ai-memory \+ /usr/local/bin/ai-memory /usr/bin/ai-memory; do+ if [ -x "$candidate" ]; then bin="$candidate"; break; fi+ done+ fi+fi+if [ -z "$bin" ] || [ ! -x "$bin" ]; then+ cat >/dev/null+ if [ "$event" = "session-start" ]; then+ printf '%s\n' '{"systemMessage":"ai-memory: the ai-memory binary was not found, so this session is not captured. Install it and run `ai-memory setup`: https://github.com/akitaonrails/ai-memory#install"}'+ else+ printf '{}\n'+ fi+ exit 0+fi+set -- --event "$event" --agent "$agent" --server-url "$url"+if [ -n "${CLAUDE_PLUGIN_OPTION_DATA_DIR:-}" ]; then+ set -- --data-dir "$CLAUDE_PLUGIN_OPTION_DATA_DIR" "$@"+fi+AI_MEMORY_HOOK_ORIGIN="$agent-plugin" exec "$bin" hook "$@"+```++## Sources++All fetched 2026-10-13.++Claude:+- Plugin manifest reference: <https://code.claude.com/docs/en/plugins/manifest-reference>+- Plugin components (hooks, MCP, `bin/`, data dir): <https://code.claude.com/docs/en/plugins/components>+- Hooks reference (shell vs exec form, Windows shells, SessionEnd budget, workspace trust, deduplication): <https://code.claude.com/docs/en/hooks>+- MCP (plugin servers, variable expansion, `headersHelper`): <https://code.claude.com/docs/en/mcp>+- Marketplace reference (sources, `strict`, versions): <https://code.claude.com/docs/en/plugins/marketplace-reference>+- Host a marketplace (auto-update off by default): <https://code.claude.com/docs/en/plugins/host-marketplace>+- CLI reference (`validate`, `configure`, `tag`, `details`): <https://code.claude.com/docs/en/plugins/cli-reference>+- Loading and local testing: <https://code.claude.com/docs/en/plugins/loading>+- Publish and Anthropic marketplaces: <https://code.claude.com/docs/en/plugins/publish>, <https://code.claude.com/docs/en/plugins/anthropic-marketplaces>+- Plugin security: <https://code.claude.com/docs/en/plugins/security>+- Plugin evals: <https://code.claude.com/docs/en/plugin-evals>+- Settings (`disableAllHooks`, `allowManagedHooksOnly`): <https://code.claude.com/docs/en/settings-reference>+- Platform support (Chat, Cowork, Code): <https://claude.com/docs/plugins/platform-support>+- Pre-submission checklist and submission: <https://claude.com/docs/plugins/pre-submission-checklist>, <https://claude.com/docs/plugins/submit>+- Desktop extensions and Cowork VM note: <https://claude.com/docs/third-party/claude-desktop/extensions>+- Official marketplace review prompt: `anthropics/claude-plugins-official`, `.github/policy/prompt.md`++Codex:+- Build plugins: <https://developers.openai.com/plugins/build/plugins> (same content at <https://developers.openai.com/codex/plugins/build>)+- Hooks and plugin hook trust: <https://learn.chatgpt.com/docs/hooks> (redirect target of <https://developers.openai.com/codex/hooks>)++Cursor:+- Plugins: <https://cursor.com/docs/plugins>+- Plugin reference: <https://cursor.com/docs/reference/plugins>+- Hooks: <https://cursor.com/docs/hooks>+- Third-party hooks: <https://cursor.com/docs/reference/third-party-hooks>++Others:+- Gemini CLI extensions: <https://geminicli.com/docs/extensions/>, <https://geminicli.com/docs/extensions/reference/>, <https://geminicli.com/docs/extensions/releasing/>, <https://geminicli.com/docs/hooks/>+- Antigravity: <https://antigravity.google/docs/plugins.md>, <https://antigravity.google/docs/hooks.md>, <https://antigravity.google/docs/mcp.md>+- Copilot CLI plugin reference: <https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference>+- Factory Droid plugins: <https://docs.factory.com/cli/configuration/plugins.md>+- OpenCode plugins: <https://opencode.ai/docs/plugins/>+- Kimi Code plugins and hooks: <https://moonshotai.github.io/kimi-cli/en/customization/plugins.md>, <https://moonshotai.github.io/kimi-cli/en/customization/hooks.md>+- Agent Plugins 1.0.0: <https://agent-plugins.org/specification>+- Zed MCP extensions: <https://zed.dev/docs/extensions/mcp-extensions>++Example repositories read: `thedotmack/claude-mem`,+`supermemoryai/claude-supermemory`, `mem0ai/mem0` (`integrations/`),+`topoteretes/cognee-integrations`, `vectorize-io/hindsight`,+`oaleviola/arroway-plugin`, `anthropics/claude-plugins-official`,+`anthropics/claude-code` (`plugins/`), `Gentleman-Programming/engram`.diff --git a/docs/desktop/extensions.md b/docs/desktop/extensions.mdindex 2e12126f..3c95ad77 100644--- a/docs/desktop/extensions.md+++ b/docs/desktop/extensions.md@@ -2,7 +2,9 @@> Can an ai-memory extension in each app's marketplace do what an installer> cannot? Sourced from current official docs and, for Codex, its source.-> The resulting design proposal is RFC #1166.+> The resulting design proposal is RFC #1166; the implementation design,+> re-verified on 2026-10-13, is+> [`design-marketplace-plugins.md`](../design-marketplace-plugins.md).## Claude (one plugin format, three surfaces)