Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(plugins): install guide, design decisions, security boundary row (#1166)
AkitaOnRailsdc85e7857200
diff --git a/AGENTS.md b/AGENTS.mdindex 621f4116..3c2aae6f 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -217,6 +217,10 @@ companions/ai-memory-macos/ Swift menu bar wrapper; NOT a root workspace memcompanions/ai-memory-ts/ optional TypeScript client SDK (npm, Node 22+); NOT a workspacemember and never shipped with the server.hooks/ per-agent lifecycle hook bundles (shell/native).+plugins/ generated Claude Code + Codex marketplace plugins (catalogs in+ `.claude-plugin/`, `.agents/plugins/`); edit the templates in+ `crates/ai-memory-cli/templates/plugin/` and re-run+ `ai-memory render-plugins --out .` — a test fails on drift.bin/ host wrapper scripts (`ai-memory`, `deploy`, `release`).install.sh two-command native install, step one (release asset).INSTALL_FOR_AGENTS.md how an AI agent installs ai-memory for its user.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 82fbe76f..dcb39e41 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,6 +12,33 @@ and [0.x](docs/changelog/0.x.md).## [Unreleased]### Added+- Added ai-memory as a marketplace plugin for Claude Code and Codex. The+ repository is now a plugin marketplace: `claude plugin marketplace add+ akitaonrails/ai-memory` then `claude plugin install ai-memory@ai-memory`,+ or `codex plugin marketplace add akitaonrails/ai-memory` then `codex plugin+ add ai-memory@ai-memory` (Codex runs the hooks only after you trust them in+ `/hooks`; trust survives plugin upgrades). Each plugin carries the+ lifecycle hooks, the MCP tools through `ai-memory mcp-bridge`, the routing+ skills and a `status` skill that runs `ai-memory doctor`. The hooks call+ one short POSIX launcher that hands every event to the installed binary's+ native `ai-memory hook`, so `ignore_paths`, allowlist mode, marker scope+ and server profiles apply exactly as for `install-hooks`; without the+ binary the plugin captures nothing, says so once at session start and+ never blocks the agent. The binary is still installed separately. Catalogs+ pin each plugin to the release tag, and `plugins/` is generated by the+ hidden `ai-memory render-plugins`, with a test that fails when the+ committed files drift from it. When Claude settings-file hooks and the+ plugin are both installed, the settings hooks win and the plugin skips the+ events they deliver; sessions with no project folder are not captured+ through the plugin. `setup` and `ai-memory run` no longer write settings+ hooks, MCP entries or skills for an agent whose plugin is enabled;+ `doctor` reports each plugin, version skew, double wiring and Codex plugin+ hooks Codex skips; `upgrade` also updates the Claude Code plugin;+ `uninstall` removes the plugins. `ai-memory hook --server-url` and+ `ai-memory mcp-bridge --server-url` now treat an empty value as unset and+ use the configured server, and `hook --server-url` may be omitted. Each+ release attaches `ai-memory-claude-plugin.zip` for the Claude desktop app's+ plugin upload. See `docs/install.md#marketplace-plugins`. (#1166)- Added a recall trace to web search. A project page has its own search box,and a search with `workspace` and `project`(`/web/search?q=…&workspace=…&project=…`) now ranks with the same hybriddiff --git a/README.md b/README.mdindex 27ae13f2..59d6f191 100644--- a/README.md+++ b/README.md@@ -215,6 +215,17 @@ variables and how to verify the script before running it are inAn AI agent installing ai-memory for you can follow[`INSTALL_FOR_AGENTS.md`](INSTALL_FOR_AGENTS.md).+Claude Code and Codex users can wire their agent as a marketplace plugin+instead (the binary is still installed as above):++```bash+claude plugin marketplace add akitaonrails/ai-memory && claude plugin install ai-memory@ai-memory+codex plugin marketplace add akitaonrails/ai-memory && codex plugin add ai-memory@ai-memory+```++Codex then asks you to trust the hooks in `/hooks`. See+[Marketplace plugins](docs/install.md#marketplace-plugins).+### Arch Linux (AUR)For native Arch installs, use the AUR packages. They installdiff --git a/crates/ai-memory-cli/src/commands/render_plugins.rs b/crates/ai-memory-cli/src/commands/render_plugins.rsindex 458c41ae..306bbc32 100644--- a/crates/ai-memory-cli/src/commands/render_plugins.rs+++ b/crates/ai-memory-cli/src/commands/render_plugins.rs@@ -43,7 +43,8 @@ const LAUNCHER_PATH: &str = "scripts/ai-memory-hook";const CLAUDE_DESCRIPTION: &str = "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.";+ the ai-memory MCP tools. No telemetry. Requires the ai-memory binary. In Cowork, capture runs \+ on your computer and needs ai-memory installed there; the memory tools still work.";const CODEX_DESCRIPTION: &str = "Long-term memory across sessions and harnesses, backed by the \installed ai-memory binary and your ai-memory server. No telemetry. Codex runs the hooks only \after you trust them in /hooks.";diff --git a/crates/ai-memory-cli/templates/plugin/claude-code-README.md b/crates/ai-memory-cli/templates/plugin/claude-code-README.mdindex 0ba62b03..d7fc3952 100644--- a/crates/ai-memory-cli/templates/plugin/claude-code-README.md+++ b/crates/ai-memory-cli/templates/plugin/claude-code-README.md@@ -31,20 +31,22 @@ claude plugin marketplace add akitaonrails/ai-memoryclaude plugin install ai-memory@ai-memory```-`ai-memory upgrade` also updates the plugin, because Claude Code does not-auto-update third-party marketplaces unless you turn that on.+Claude Code does not auto-update third-party marketplaces unless you turn+that on. `ai-memory upgrade` updates the plugin along with a release-tarball+binary; after a Homebrew, AUR or RPM upgrade, run `claude plugin marketplace+update ai-memory` and `claude plugin update ai-memory@ai-memory`.## What it runs and what it sends-- **Hooks.** Every lifecycle event (session start and end, prompts, tool+- Hooks: every lifecycle event (session start and end, prompts, toolcalls, compaction, stop, subagents) runs `scripts/ai-memory-hook`, a shortPOSIX shell script you can read in full. It finds the installed `ai-memory`binary and hands it the event with `ai-memory hook`. The binary appliesyour capture exclusions (`ignore_paths`, allowlist mode, server profiles)before anything is written or sent, spools the event locally, and deliversit only to your ai-memory server, which sanitizes it before storage.-- **MCP.** The ai-memory memory tools, through `ai-memory mcp-bridge`.-- **Skills.** The ai-memory routing skills, plus `/ai-memory:status`, which+- MCP: the ai-memory memory tools, through `ai-memory mcp-bridge`.+- Skills: the ai-memory routing skills, plus `/ai-memory:status`, whichruns `ai-memory doctor` and summarizes it.No telemetry. Nothing goes anywhere except the ai-memory server you@@ -77,11 +79,11 @@ setup` leaves Claude's settings alone while the plugin is enabled.## Platform notes-- **Windows.** Claude Code runs plugin hooks through Git Bash, which it+- On Windows, Claude Code runs plugin hooks through Git Bash, which italready requires; the launcher needs nothing else.-- **Docker wrapper.** Plugin hooks need a wrapper that routes `ai-memory+- With the Docker wrapper, plugin hooks need a wrapper that routes `ai-memoryhook` to its native client; run `ai-memory upgrade` to get it.-- **Cowork.** Capture runs on your computer and needs ai-memory installed+- In Cowork, capture runs on your computer and needs ai-memory installedthere; the memory tools still work.## Uninstalldiff --git a/crates/ai-memory-cli/templates/plugin/codex-README.md b/crates/ai-memory-cli/templates/plugin/codex-README.mdindex 2e3b42a0..5cf2300b 100644--- a/crates/ai-memory-cli/templates/plugin/codex-README.md+++ b/crates/ai-memory-cli/templates/plugin/codex-README.md@@ -31,14 +31,14 @@ command says so in its changelog, and you trust the new command once.## What it runs and what it sends-- **Hooks.** Each lifecycle event runs `scripts/ai-memory-hook`, a short POSIX+- Hooks: each lifecycle event runs `scripts/ai-memory-hook`, a short POSIXshell script, which hands the event to the installed binary(`ai-memory hook`). The binary applies your capture exclusions, spools theevent, and delivers it only to your ai-memory server. On Windows the hookscall `ai-memory hook` directly, so `ai-memory` must be on `PATH`.-- **MCP.** The ai-memory memory tools, through `ai-memory mcp-bridge+- MCP: the ai-memory memory tools, through `ai-memory mcp-bridge--no-session-id`.-- **Skills.** The ai-memory routing skills and a `status` skill.+- Skills: the ai-memory routing skills and a `status` skill.No telemetry. The plugin has no settings; the server URL and credentialscome from your ai-memory config.diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 5ec0ae35..d92ebad5 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -802,6 +802,22 @@ file; `uninstall` stops and removes only a unit whose digest still matches.`install.sh`, a release asset with its own `.sha256`, installs the releasetarball under `~/.local` after checking it against the published checksum.+The hidden `render-plugins --out <dir>` generates the Claude Code and Codex+marketplace plugins under `plugins/` and their catalogs+(`.claude-plugin/marketplace.json`, `.agents/plugins/marketplace.json`) from+the same event lists and managed skills `install-hooks` and `install-skills`+use, pinned to the binary's version and the `v<version>` tag (#1166). A CLI+suite test fails when the committed tree differs from its output, and+`bin/release` re-runs it after the version bump. Each plugin's hooks call one+POSIX launcher that finds the installed binary and `exec`s the native `hook`+with `AI_MEMORY_HOOK_ORIGIN=<agent>-plugin`; the launcher has no capture+logic, so the plugin is a fourth front door that adds nothing to the trust+surface. The origin lets `hook` drop a plugin copy that a Claude settings-file+hook already delivers and skip folderless sessions+(`commands/plugin_origin.rs`). `setup` and the `run` auto-wire leave an agent+with an enabled plugin unwired; `doctor`, `upgrade` and `uninstall` read the+user-level plugin install (`commands/agent_plugins.rs`).+`auth enable` turns on the root bearer for an install created beforenew installs got one; see [`[auth]` root bearer](#auth-root-bearer).diff --git a/docs/design-marketplace-plugins.md b/docs/design-marketplace-plugins.mdindex 9a273766..761dcafd 100644--- a/docs/design-marketplace-plugins.md+++ b/docs/design-marketplace-plugins.md@@ -1,6 +1,13 @@# Design proposal: ai-memory as marketplace plugins (#1166)-**Status: proposal for 3.0, research done 2026-10-13. Not implemented.**+**Status: implemented for 3.0 (Claude Code and Codex plugins), 2026-10-13.+Cursor, Cowork capture, Antigravity and Gemini remain later work.** The+sections below keep the research and the reasoning; where the shipped code+differs from the original proposal, the text says so and+[Implementation notes](#implementation-notes-30) lists every change. The+generated files under `plugins/` and the renderer+(`crates/ai-memory-cli/src/commands/render_plugins.rs`) are authoritative over+the manifest listings here.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@@ -89,7 +96,47 @@ What the local runs showed:`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`.+ `CODEX_HOME`. **Corrected in Phase 0:** install succeeding was not the+ same as loading. With an Agent Plugins root `plugin.json` (`$schema`+ set), `plugin/read` over `codex app-server` reported the skills and the+ MCP server but **no hooks**, whether hooks were discovered by default or+ named with `hooks` or `extensions."com.openai".hooks`. With Codex's own+ `.codex-plugin/plugin.json` all seven hooks, the seven skills and (once+ the manifest says `"mcpServers": "./mcp.json"`) the MCP server load. The+ shipped Codex plugin uses that layout.++Phase 0 runs (2026-10-13, Claude Code 2.1.296 and Codex 0.162.1, scratch+`HOME`/`CLAUDE_CONFIG_DIR`/`CODEX_HOME`, the operator's configuration+untouched):++11. **Claude option storage.** `claude plugin install` records the plugin in+ `<config dir>/plugins/installed_plugins.json` (`version: 2`,+ `plugins."ai-memory@ai-memory"[]` with `scope`, `installPath`,+ `version`) and enables it in the user `settings.json` `enabledPlugins`.+ `claude plugin configure --values-stdin` stores option values under+ `pluginConfigs."ai-memory@ai-memory".options` in the same file, and an+ empty string clears an option.+12. **An option whose default is `""` is substituted as an empty argument**+ in the MCP `args` (`mcp-bridge --server-url ""`), while the hook+ environment still has no `CLAUDE_PLUGIN_OPTION_SERVER_URL`. Hooks get+ `CLAUDE_PROJECT_DIR`.+13. **Codex trust survives an upgrade.** Codex keys plugin hook trust as+ `ai-memory@ai-memory:hooks/hooks.json:<event>:<group>:<handler>` and+ hashes the command *before* `${PLUGIN_ROOT}` expansion: the same plugin+ installed into two `CODEX_HOME`s at different paths reported identical+ `currentHash` values, and a trusted hook stayed `trusted` after a+ version bump and reinstall, both from a local marketplace and through a+ `git-subdir` source with a moved `ref`. The Codex smoke test also+ reinstalls into a new `cache/ai-memory/ai-memory/<version>` directory,+ and every hook stays trusted. Editing `scripts/ai-memory-hook` itself+ does not change the hash.+14. **Codex plugin hooks fire without credentials.** Once trusted, a+ `thread/start` plus `turn/start` over `codex app-server` ran the plugin's+ `SessionStart` and `UserPromptSubmit` hooks through the launcher into the+ real binary, which spooled both as agent `codex` in the fixture marker's+ scope. With the model provider pointed at a closed loopback port, no+ request left the machine. `commandWindows` in the hooks file is accepted+ (no `hooks/list` error); it was not run.## Per-app capability table@@ -158,13 +205,17 @@ One POSIX `sh` script, `scripts/ai-memory-hook`, shared by every plugin andcalled 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);+ on Claude) when set, else an empty value, which the binary reads as "use+ the `server_url` of my config" (section 3). It cannot rely on+ `userConfig` defaults, which hooks do not receive (local finding 5).+ *Shipped differently from the proposal,* which fell back to+ `AI_MEMORY_HOOK_URL` and then to loopback: that would have sent a user+ whose config names a remote server to `127.0.0.1` unless they also set+ the plugin option;2. finds the binary: the `ai_memory_bin` option if set, else `command -vai-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`);+ `PATH` (`$HOME/.local/bin`, `$HOME/.cargo/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 thissession is not captured. Install it and run ai-memory setup: <url>"}` on@@ -209,6 +260,18 @@ See open question 4.flags the plugin does not (`--capture-assistant`, a baked`--project-strategy`). An env variable rather than a flag keeps an olderbinary working with a newer plugin; it just skips the de-duplication.+ *Shipped* as `AI_MEMORY_HOOK_ORIGIN=<agent>-plugin` (`claude-code-plugin`,+ `codex-plugin`), checked per event: the plugin copy is dropped only when a+ settings file carries an ai-memory hook for *that* event, so an older+ install wiring fewer events still gets the rest from the plugin. The+ checkout is `CLAUDE_PROJECT_DIR` when Claude sets it, else the payload+ `cwd`. Codex plugin events are never de-duplicated: Codex skips an+ untrusted settings hook without a trace, and nothing at hook time can tell+ a trusted one from a skipped one, so dropping the plugin copy could lose+ the event. `setup` and `doctor` handle a double Codex install instead.+ The same origin check skips a **folderless session** (decision 8): no+ `cwd`, or a cwd inside a Claude desktop `…/Claude/scratch-workspaces/…`+ directory, matched lexically.- **`hook` and `mcp-bridge`: an empty `--server-url` means unset.** This lets`.mcp.json` pass `${user_config.server_url}` while a user who has aconfigured `server_url` keeps it.@@ -219,19 +282,36 @@ See open question 4.- **`setup`, `install-hooks`, `install-skills`:** detect an enabledai-memory Claude plugin (`installed_plugins.json` plus `enabledPlugins` inthe 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.+ skills and MCP entry, printing what was skipped. *Shipped:* `setup` and the+ `ai-memory run` auto-wire skip an agent (Claude Code or Codex) whose plugin+ is enabled. The explicit `install-hooks`, `install-mcp` and+ `install-skills` still write when asked; they are the override, so no+ `--force` flag was added (`install-skills --force` already means something+ else). `setup` has no `--server-url`, and none is needed: the plugin's+ `server_url` option defaults to empty, so hooks and MCP both follow the+ server in the ai-memory config, and nothing has to be copied into Claude's+ plugin options.- **`doctor`:** report the plugin (version, enabled, options), version skewagainst the binary, duplicate wiring (plugin plus settings hooks, pluginskills plus installed skills), and a Docker wrapper on `PATH` without therouting fix. For Codex, extend `codex_hook_trust.rs` to plugin hooks.+ *Shipped:* plugin, version, enabled state, skew, settings hooks, installed+ skills, a second MCP entry, `disableAllHooks`/`allowManagedHooksOnly`, and+ Codex plugin hooks Codex skips (matched by `pluginId`). Plugin options are+ not reported, and neither is the Docker wrapper: the wrapper fix that+ routes `hook` to the native client lands separately on `main`, and a+ wrapper-run `doctor` executes inside the container, where it cannot see+ the host `PATH`.- **`upgrade`:** when the plugin is installed, run `claude pluginmarketplace update ai-memory` and `claude plugin updateai-memory@ai-memory` after replacing the binary, because backgroundauto-update is off for third-party marketplaces. This keeps binary and- plugin in step without asking users to opt into auto-update.+ plugin in step without asking users to opt into auto-update. *Shipped,*+ also when the binary is already current. For Codex, `upgrade` prints+ `codex plugin marketplace upgrade ai-memory` and `codex plugin add+ ai-memory@ai-memory` instead of running them. A package-managed binary+ (Homebrew, AUR, RPM) never reaches this path, so those users run the+ plugin update themselves (documented in `docs/install.md`).- **`uninstall`:** offer `claude plugin uninstall ai-memory@ai-memory`.None of this touches the MCP tool surface, so the tool count stays at 23.@@ -243,7 +323,7 @@ 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}` |+| Server URL | `userConfig.server_url` (string) | empty (shipped; proposed `http://127.0.0.1:49374`) | Read by the launcher from `CLAUDE_PLUGIN_OPTION_SERVER_URL`; MCP gets `${user_config.server_url}`. Empty means the `server_url` of the ai-memory config, for hooks and MCP alike || 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 |@@ -312,7 +392,12 @@ our repository would install the Claude plugin and send events tagged- the launcher recognizes the other harnesses' markers (`DROID_PLUGIN_ROOT`,Codex's `PLUGIN_ROOT`, Cursor's `CURSOR_VERSION`). It hands the event tothe matching ai-memory agent when one exists, and otherwise prints `{}` and- exits;+ exits. *Shipped:* `DROID_PLUGIN_ROOT` → `droid`; `PLUGIN_ROOT` without+ `CLAUDE_PLUGIN_ROOT` → `codex`; neither `CLAUDE_PLUGIN_ROOT` nor+ `PLUGIN_ROOT` → `{}`. Cursor is not remapped: when Cursor runs Claude+ hooks the event already reaches the existing #721 path as `claude-code`+ with `cursor_version`, and whether Cursor runs *plugin* hooks at all is+ one of the Cursor unknowns;- we ship a native catalog for each harness we support, so the fallback isnever used.@@ -344,6 +429,11 @@ plugins/.cursor-plugin/plugin.json mcp.json hooks/hooks.json scripts/ skills/```+*Shipped layout:* as above without `cursor/`, and Codex's manifest is+`plugins/codex/.codex-plugin/plugin.json` (Phase 0 finding 10). The plugin+templates (launcher, READMEs, `status` skill) live in+`crates/ai-memory-cli/templates/plugin/`.+Each harness gets its own directory: event names, the `--agent` value andthe MCP flags (`--no-session-id` for everyone except Claude) all differ, andClaude strips manifest keys it does not know while still loading@@ -543,14 +633,19 @@ Portable layout, which Codex 0.162.1 accepted locally (finding 10).}```-`plugins/codex/plugin.json`:+`plugins/codex/.codex-plugin/plugin.json` (shipped; the proposal's Agent+Plugins root `plugin.json` installs but loads no hooks, finding 10):```json{- "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json","name": "ai-memory","version": "3.0.0",- "description": "Long-term memory across sessions and harnesses, backed by the installed ai-memory binary and your ai-memory server. No telemetry."+ "description": "Long-term memory across sessions and harnesses, backed by the installed ai-memory binary and your ai-memory server. No telemetry. Codex runs the hooks only after you trust them in /hooks.",+ "author": { "name": "AkitaOnRails", "url": "https://github.com/akitaonrails" },+ "homepage": "https://github.com/akitaonrails/ai-memory",+ "repository": "https://github.com/akitaonrails/ai-memory",+ "license": "MIT",+ "mcpServers": "./mcp.json"}```@@ -572,7 +667,7 @@ Portable layout, which Codex 0.162.1 accepted locally (finding 10)."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" }] }]+ "commandWindows": "ai-memory hook --event session-start --agent codex" }] }]}}```@@ -582,7 +677,12 @@ The remaining events follow the same shape. `SessionEnd` stays within Codex'spolicy value suits a plugin with no auth of its own, whether omitting`matcher` is valid for every event, and whether a hook trusted once staystrusted after a plugin upgrade (open question 2). The catalog-`ref` is stamped by `bin/release` exactly like Claude's.+`ref` is stamped by `bin/release` exactly like Claude's. *Resolved in Phase+0:* omitting `matcher` loads all seven events, `ON_INSTALL` installs without+prompting for anything, and trust survives an upgrade (finding 13). The+`commandWindows` value omits `--server-url`, which the binary now treats as+"use the config"; it passes no empty argument because Windows PowerShell 5.1+drops empty arguments to native commands.### Phase 3: Cursor@@ -634,6 +734,15 @@ The #721 de-duplication has to learn about the Cursor plugin. Today### On pull requests (`.github/workflows/plugins.yml`, path-filtered)+*Shipped:* jobs `validate` (items 2), `launcher` (item 3) and `e2e` (items+4 and 6, plus a cheap `render-plugins` drift check for pushes to `main`).+Item 1 runs in `ci.yml`'s existing `cargo nextest` job, item 5 in the CLI+suite. Claude Code 2.1.296 and Codex 0.162.1 are pinned as npm installs in+the workflow `env`. The Codex smoke points the model provider at a closed+loopback port, so it needs no secret and no outbound request. Item 7+(Windows) stays open: the launcher tests are POSIX-only, and nothing has+run on Windows yet (see the unverified list).+Paths: `plugins/**`, the three catalog files, `render_shared.rs`,`ai-memory-core/src/routing_skills/**`, `bin/ai-memory`, the workflow itself.@@ -711,15 +820,18 @@ Paths: `plugins/**`, the three catalog files, `render_shared.rs`,Mapped to the boundary inventory, all at integration level:-| Test | Proves | Where |+| Test | Proves | Where (shipped) || --- | --- | --- |-| 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` |+| Committed `plugins/` equals renderer output; versions and refs match the workspace; no credential in any plugin file | No drift between CLI and plugin installs | CLI `tests/suite/plugins.rs` `committed_plugins_match_the_renderer`, `plugin_versions_and_catalog_refs_match_the_workspace`, `plugin_tree_carries_no_credentials`; `render_plugins.rs` unit tests |+| Launcher, missing binary | Fail-open, guidance once, nothing sent | `tests/hooks/test_plugin_launcher.sh`; `plugins.rs` `without_a_binary_nothing_is_sent_and_the_agent_is_not_blocked` |+| `ignore_paths` and allowlist through the launcher | Capture policy parity (front door 1, 2) | `plugins.rs` `ignore_paths_hold_through_the_plugin`, `allowlist_mode_holds_through_the_plugin` (real binary, recorded payloads) |+| Marker and server-profile routing through the launcher | Scope parity (front door 3) | `plugins.rs` `marker_scope_routes_plugin_events`, `server_profiles_route_plugin_events` |+| Plugin copy plus settings copy gives one observation; control: plugin alone delivers | De-duplication (front door 4), adversarial with a control | `plugins.rs` `a_settings_hook_for_the_same_event_drops_the_plugin_copy`; `hook.rs` `plugin_copy_is_dropped_only_with_the_plugin_origin`; `plugin_origin.rs` unit tests; `claude_plugin_smoke.py` scenario 2 (real `claude -p`) |+| Folderless sessions and foreign hosts | Decision 8; section 6 guard | `plugins.rs` `folderless_sessions_are_not_captured_through_the_plugin`, `foreign_hosts_are_attributed_or_ignored`; `test_plugin_launcher.sh` |+| Docker wrapper routes `hook` to the native client | Wrapper fix | Lands on `main` separately (not in this change) |+| Sandboxed Claude install fires hooks into a scratch server | Real wiring, no API key | `tests/e2e/claude_plugin_smoke.py` in `plugins.yml` |+| Codex install, untrusted by default, trusted hooks fire, trust survives a bump | Real wiring, no API key | `tests/e2e/codex_plugin_smoke.py` in `plugins.yml` |+| `setup`/`run` skip, `doctor`, `upgrade`, `uninstall` | Integration | `setup.rs` `an_enabled_plugin_takes_over_the_agents_wiring`, `run_autowire.rs` `an_enabled_plugin_leaves_the_harness_unwired`, `doctor.rs` `plugin_report_names_double_wiring_and_skew`, `upgrade.rs` `upgrade_updates_an_installed_claude_code_plugin_only`, `uninstall.rs` `uninstall_removes_each_plugin_through_its_harness`, `codex_hook_trust.rs` `summarizes_the_ai_memory_plugin_hooks_by_plugin_id` |## Phased plan for 3.0@@ -737,45 +849,114 @@ Estimates are engineer-days for one person familiar with the codebase.Phases 1 to 3 come to roughly 9 to 10.5 days. This is additive work, so it targets`release/3.0`, not `main`.+*Delivered for 3.0:* phase 0 (the locally runnable spikes, findings 10-14),+phase 1 except the Docker wrapper routing (landing separately on `main`),+phase 2, and phase 3. Phase 4 (Cursor) waits for 3.1: its four unknowns+need a Cursor install with plugin support, and the #721 detection would have+to learn the plugin format first.+## 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 3.0.-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 3.0.-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).+All eight were decided on 2026-10-13. The original question follows each+decision in brief.++1. **Directory listing. Decided: no submission** to the claude.ai or+ Anthropic directory for the capture plugin; capture hooks are ungated by+ design and do not qualify. The plugin ships through our own marketplace+ in this repository. An MCP-only listing may come later, not now.+ (Asked: also list in the directory portal, possibly as an+ allowlist-capture variant?)+2. **Codex trust across upgrades. Decided: accept and document it** as+ Codex's security model. Phase 0 found that trust survives an upgrade+ anyway, because Codex hashes the unexpanded command (finding 13); a+ release that changes a hook command needs one re-trust, which the+ changelog will say. `doctor` and the `status` skill flag skipped hooks.+3. **Cowork. Decided:** the plugin says in one line that capture runs on the+ user's computer and needs ai-memory installed there, and that the memory+ tools still work (manifest description and README). No extra+ session-start message is added.+4. **Windows. Decided: Git Bash** is fine for Claude plugin hooks, since+ Claude Code requires it already. A PowerShell launcher only if Codex+ needs one; it does not, because Codex's `commandWindows` calls+ `ai-memory hook` directly.+5. **Which wiring wins. Decided:** settings hooks win at runtime; the+ plugin's launcher path skips the events the settings hooks already+ deliver, and `doctor` reports the double install and suggests keeping+ one. `setup` stops writing settings wiring while the plugin is enabled.+6. **Token option. Decided: no** stored-token option in the plugin; it reuses+ the credential files the binary already reads.+7. **Names. Decided: keep `ai-memory@ai-memory`.**+8. **Folderless sessions. Decided: skip capture** for a session with no+ project folder (through the plugin; settings-file hooks keep today's+ `default/scratch` routing).++Target release: 3.0.0 (the branch formerly called `release/2.7`).++## Implementation notes (3.0)++Where the shipped code differs from the proposal above:++- **Server URL.** The `server_url` option defaults to empty and the launcher+ passes it through unchanged; `hook` and `mcp-bridge` read an empty+ `--server-url` as "use the config". `hook --server-url` may now be+ omitted (the Codex `commandWindows` commands rely on it). No+ `AI_MEMORY_HOOK_URL` fallback and no `setup --server-url` → `claude plugin+ configure` step: one source of truth, `config.toml`.+- **Codex manifest.** `.codex-plugin/plugin.json` with `"mcpServers":+ "./mcp.json"`, not the Agent Plugins root manifest (finding 10).+- **No runtime de-duplication for Codex** (section 3).+- **No `--force`.** `setup` and `run` skip plugin-covered agents; the+ explicit `install-*` commands are the override.+- **`upgrade` for Codex prints** the update commands rather than running+ them.+- **`doctor`** does not report plugin options or the Docker wrapper (section+ 3).+- **Catalog entry `version`.** The Claude catalog entry also carries the+ plugin version; `claude plugin validate --strict` accepts it.+- **Version.** The renderer stamps the binary's own version, so until+ `bin/release 3.0.0` runs, the committed manifests say the current+ workspace version (2.6.6) and the catalogs point at `v2.6.6`, a tag+ without `plugins/`. A marketplace add of this branch therefore cannot+ install the plugin yet; `--plugin-dir` and local marketplaces can.++## Still unverified, and how to check++Each needs hardware or software this work did not have. Run every check with+a scratch config dir, never the operator's own.++- **Claude Code on Windows (Git Bash present / absent).** In a Windows VM+ with Claude Code: `claude plugin marketplace add <checkout>` and `claude+ --plugin-dir <checkout>\plugins\claude-code -p hi` with+ `CLAUDE_CONFIG_DIR` set to a temp dir and options pointing at a scratch+ server (as in `tests/e2e/claude_plugin_smoke.py`); confirm the+ observations land. Repeat with Git Bash removed from `PATH` and record what+ Claude does with the shell-form hook.+- **Claude desktop Code tab (macOS) hook `PATH`.** Install the plugin, start+ a Code-tab session in a repository, and check that events arrive with+ only `/opt/homebrew/bin/ai-memory` or `~/.local/bin/ai-memory` installed+ (the launcher's fallbacks). `ai-memory doctor` coverage, or a temporary+ `env > /tmp/x` line in a copy of the launcher, shows the `PATH`.+- **Cowork.** Upload `ai-memory-claude-plugin.zip`, start a Cowork session,+ and check whether the hooks run on the host or in the VM (new files under+ the host's `<data_dir>/hook-spool/`, or the missing-binary+ `systemMessage`), and whether the host loopback answers.+- **Codex on Windows.** In Codex for Windows, trust the plugin hooks and+ check that `commandWindows` (`ai-memory hook --event … --agent codex`)+ spools events; `codex app-server` `hooks/list` shows the command Codex+ will run.+- **Codex from the GitHub marketplace.** After the 3.0.0 tag exists: `codex+ plugin marketplace add akitaonrails/ai-memory`, `codex plugin add+ ai-memory@ai-memory`, trust, then after 3.0.1 `codex plugin marketplace+ upgrade ai-memory` + `codex plugin add ai-memory@ai-memory` and confirm+ `hooks/list` still reports `trusted` (finding 13 was proven with local+ and `file://` `git-subdir` sources).+- **Claude install from GitHub at the tag.** After the tag: `claude plugin+ marketplace add akitaonrails/ai-memory`, `claude plugin install+ ai-memory@ai-memory`, then `claude plugin details ai-memory@ai-memory`.+- **Tool events from a live model turn** (PreToolUse, PostToolUse, Stop,+ subagents) need a logged-in model; the CLI suite covers them one level+ down with recorded payloads.+- **Cursor:** the four unknowns in the Cursor section.## What we borrowed and what we avoideddiff --git a/docs/install.md b/docs/install.mdindex 03ca4ece..c72701d8 100644--- a/docs/install.md+++ b/docs/install.md@@ -6,6 +6,8 @@ RPM, macOS menu bar app). This page covers everything else:- [One-step native install](#one-step-native-install-installsh--ai-memory-setup)(`install.sh` + `ai-memory setup`, Linux and macOS, no root)+- [Marketplace plugins](#marketplace-plugins)+ (Claude Code and Codex: hooks, MCP and skills as one plugin)- [Server on a different machine](#server-on-a-different-machine)(homelab, LAN box, remote server)- [Configuring the CLI URL and auth](#configuring-the-cli-url-and-auth)@@ -166,6 +168,104 @@ the first command to a `memory_query` that returns a captured hook event (adebug build on a Linux workstation, local embeddings off so no model downloadis counted). The target is 60 seconds.+## Marketplace plugins++From 3.0 this repository is also a plugin marketplace. A plugin wires one+agent in a single step: lifecycle hooks, the ai-memory MCP tools, the routing+skills, and a `status` skill that runs `ai-memory doctor` and summarizes it.+It is the alternative to `install-hooks` + `install-mcp` + `install-skills`+for that agent; `ai-memory setup` does the rest (data dir, service, other+agents) either way.++The plugin does not contain ai-memory. Install the binary first (above, or+Homebrew, AUR, RPM, the Docker wrapper, the macOS app), then add the plugin.+Every hook runs `scripts/ai-memory-hook`, a short POSIX script that finds+the binary and hands it the event with `ai-memory hook`, the same native+command `install-hooks` wires. Capture policy (`ignore_paths`, allowlist+mode), marker scope and server profiles therefore apply exactly as they do+for settings-file hooks. Without the binary the plugin captures nothing,+prints one line at session start, and never blocks the agent. The plugins+have no telemetry and hold no credentials: hooks and the MCP bridge use the+credentials the CLI already stores (`ai-memory setup`, `auth login`).++The catalogs pin each plugin to the release tag, so a marketplace add only+installs released plugin content. Generated files live under `plugins/`+(see [`plugins/README.md`](../plugins/README.md)).++### Claude Code++```sh+claude plugin marketplace add akitaonrails/ai-memory+claude plugin install ai-memory@ai-memory+```++(or `/plugin marketplace add akitaonrails/ai-memory` and `/plugin install+ai-memory@ai-memory` inside Claude Code). The plugin works in the CLI and in+the desktop app's Code tab. Options, all optional, are set with `/plugin+configure ai-memory@ai-memory`:++| Option | Default | Use |+| --- | --- | --- |+| `server_url` | empty | Empty uses the `server_url` from your ai-memory config, so the plugin and the CLI never disagree. Set it only to point this plugin elsewhere. |+| `ai_memory_bin` | `ai-memory` | Path to the binary when it is not on the `PATH` the app sees. The launcher also tries `~/.local/bin`, `~/.cargo/bin`, `/opt/homebrew/bin`, `/usr/local/bin` and `/usr/bin`. |+| `data_dir` | empty | Only for an install with a non-default data directory. |++- Claude Code does not auto-update a third-party marketplace+ unless you turn that on. `ai-memory upgrade` runs `claude plugin+ marketplace update ai-memory` and `claude plugin update ai-memory@ai-memory`+ after replacing the binary; with a package-managed binary (Homebrew, AUR,+ RPM) run those two commands yourself after the package upgrade.+- If `install-hooks` already put ai-memory hooks in+ `~/.claude/settings.json` or a checkout's `.claude/settings.local.json`,+ those win: the plugin skips every event they deliver, so nothing is+ captured twice. `ai-memory doctor` reports the double install and which+ copy to remove. While the plugin is enabled, `ai-memory setup` and+ `ai-memory run` stop writing Claude's settings hooks, MCP entry and+ skills; run `ai-memory install-hooks --agent claude-code --apply` (or+ `install-mcp`, `install-skills`) to add them anyway.+- Folderless sessions (a desktop scratch workspace with no project folder)+ are not captured through the plugin.+- On Windows, Claude Code runs plugin hooks through Git Bash, which it+ already requires, so the launcher needs nothing else.+- With the Docker wrapper, plugin hooks need a `bin/ai-memory` wrapper that runs+ `ai-memory hook` through its native host client, not in a container+ (otherwise each event pays a `docker run` and `127.0.0.1` points inside+ the container). Run `ai-memory upgrade` to get the wrapper with that+ routing.+- Each release attaches+ `ai-memory-claude-plugin.zip` for **Customize > Plugins > Upload plugin**.+ In Cowork, capture runs on your computer and needs ai-memory installed+ there; the memory tools still work.+- Remove it with `claude plugin uninstall ai-memory@ai-memory`;+ `ai-memory uninstall` does it too.++### Codex++```sh+codex plugin marketplace add akitaonrails/ai-memory+codex plugin add ai-memory@ai-memory+```++Then open Codex, run `/hooks`, and trust the ai-memory hooks. Codex runs a+plugin's hooks only after you trust them, and skips an untrusted one without+a message. Trust is keyed on the hook command before `${PLUGIN_ROOT}` is+expanded, and the commands stay identical across releases, so a plugin+upgrade keeps it; a release that has to change a command says so in the+changelog. `ai-memory doctor` and the `status` skill report hooks Codex+skips. The Codex plugin has no options: the server URL and credentials come+from your ai-memory config, and the MCP entry runs `ai-memory mcp-bridge+--no-session-id` from `PATH`. On Windows the hooks call `ai-memory hook`+directly (`commandWindows`), so `ai-memory` must be on `PATH`.++Codex runs plugin hooks and `~/.codex/hooks.json` hooks side by side, and an+untrusted settings hook is skipped silently, so the plugin cannot safely drop+its copy the way the Claude Code plugin does. Keep one: `ai-memory setup`+does not add Codex settings hooks while the plugin is enabled, and `doctor`+flags a double install. To update, run `codex plugin marketplace upgrade+ai-memory` and `codex plugin add ai-memory@ai-memory` (`ai-memory upgrade`+prints them). Remove with `codex plugin remove ai-memory@ai-memory` or+`ai-memory uninstall`.+## Server on a different machineWhen the ai-memory server runs on a LAN box (homelab, headless server)diff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex 3b2d3c93..20ab1914 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -225,6 +225,18 @@ or switch identities behind Claude Code.`--session-aware` is Claude-Code-only. Other clients keep their documentednative HTTP or generated bridge paths.+**Marketplace plugin.** The ai-memory Claude Code plugin+(`claude plugin install ai-memory@ai-memory`, see+[install.md](install.md#marketplace-plugins)) registers this same+session-aware bridge for you, as server `plugin:ai-memory:ai-memory`, so its+tools appear as `mcp__plugin_ai-memory_ai-memory__<tool>`. The plugin passes+its `server_url` option to `mcp-bridge --server-url`; left empty (the+default), the bridge uses the server in your ai-memory config. While the+plugin is enabled, `ai-memory setup` does not also write an `ai-memory`+entry to `~/.claude.json`, and `ai-memory doctor` flags one that is already+there. The Codex plugin likewise registers `ai-memory mcp-bridge+--no-session-id`.+---## Cursordiff --git a/docs/security-boundaries.md b/docs/security-boundaries.mdindex 2d867b95..9850616a 100644--- a/docs/security-boundaries.md+++ b/docs/security-boundaries.md@@ -82,6 +82,7 @@ means the boundary is not built yet.| 11j | Offline recovery journal and transcript replay | `ai-memory-cli/src/commands/recovery.rs` keeps bounded locators, ordered semantic transcript digests, pre-launch cursors and persistent correlated-delivery/loss evidence in an atomic journal, refuses a symlinked data dir and any symlinked component inside it (ancestors above the data dir are trusted, so macOS `/var` → `/private/var` works), sanitizes/caps failure reasons, and bounds each replay plus the whole pass; `hook_spool` coordinates enqueue and quarantine with short filesystem locks, canonically resolves partial scope from the recorded cwd, bounds per-file reads and current global occupancy across the main spool and recovery directories, sweeps completed tombstones, and holds correlated events outside drain until replay succeeds or restores them on failure; degraded resumes use `ai-memory-workstream`'s adapter-validated delta export, whose blocking parse and baseline scans are capped by record, event-count, source-byte and serialized-byte totals; `backfill::import_exact_session` chunks by item and byte limits and requires per-item durable acknowledgements; `run.rs` journals every session launch, including explicit spool-only evidence for unsupported exporters, and journals a resumed export only after capturing its exact pre-launch cursor; `workstream.rs` `/recover/finish` retains owner/project authorization, rejects superseded runs, and validates a finished retry by durable transcript/native/cursor/exit identity without regenerating its checkpoint; validated recovery ingest keys bind session, agent, event kind and sanitized event identity until session purge | `transcript.rs` `persisted_baseline_exports_only_offline_append_and_rejects_rewrite`, parser/baseline cap and ordered-semantic digest tests; CLI `run_offline.rs` real degraded spool-only and overlap/idempotency tests; `recovery.rs` `spool_only_without_correlated_evidence_never_auto_clears`, `a_dropped_spool_event_stays_lost_on_the_next_empty_pass`, loss/time-budget tests, `symlinked_journal_and_ancestor_are_refused`, `a_symlinked_ancestor_of_the_data_dir_is_trusted`, `a_symlink_inside_a_data_dir_under_a_symlinked_ancestor_is_refused`; `hook_spool.rs` partial-scope late enqueue, completion-race, occupancy churn/active-cap, bounded-read and tombstone-sweep tests, plus interval isolation (`completed_tombstone_keeps_a_later_resume_of_the_same_session` proves a post-interval resume hook is delivered, `completing_one_recovery_interval_leaves_the_other_intervals_entries_intact` proves one interval's completion never consumes another's evidence and ambiguous entries fail closed into the main spool); `backfill.rs` `two_sequential_recovery_intervals_on_one_resumed_session_replay_exactly_once` proves the second interval's content and session-end are stored with end-of-session effects while reruns stay pure replays; `transcript.rs` `an_oversized_first_record_is_skipped_by_session_listing_caps` proves the first-record byte caps bite before allocation; store `insert_observation_ingest_dedups_on_key` rejects cross-session and changed-event preclaims; hooks `expired_run_recovery_is_owner_only_and_refuses_superseded_runs` proves changed transcript refusal and changed-checkpoint no-op | STRONG on Unix integration coverage; Unix lock opens use no-follow and atomic replacement rechecks the destination. Windows owner-only ACL/reparse and lock semantics require the PR `windows` lane || 11i | OpenCode executable probing and generated-config cleanup (#1097) | `ai-memory-cli/src/config.rs` captures the full process environment once in typed `RuntimeEnv`; `run.rs` overlays explicit `run --env` values with platform key semantics and uses that same effective environment for executable resolution, probing, and launch without rereading process environment; `opencode_dialect.rs` invokes only direct argv `--version`, caps output and time, and rejects malformed/future majors. Automatic launch skips only OpenCode on probe failure; explicit OpenCode fails. `install_hooks.rs` quarantines the incompatible sibling before reading its exact ownership markers, restores unowned content with an atomic no-replace link, and never deletes or overwrites a concurrent replacement; `install_mcp.rs` owns the shared dual-schema endpoint/token inference used by both installers, rejects conflicting generated V1/V2 entries before mutation, and migrates an alternate-major entry only when endpoint, generated shape, and absent-or-Authorization-only headers match, preserving custom headers and ambiguous entries; auto-wire migrates MCP before hooks infer from that exact config path and skips hook mutation when transition preflight fails | `run.rs` `automatic_opencode_probe_failure_keeps_another_harness_available`, `opencode_executable_probe_selects_v2_for_launch_and_autowire`, effective-child-environment PATH casing controls, fake V1/V2/env-derived-major/malformed/future/timeout executable tests, `setup-agent` V1/V2 no-probe integration controls; `install_hooks.rs` `opencode_plugin_cleanup_removes_only_exact_owned_incompatible_sibling`, `opencode_plugin_cleanup_preserves_a_concurrent_user_replacement`, `opencode_plugin_restore_moves_quarantine_when_destination_is_free`, `opencode_plugin_restore_preserves_an_existing_replacement`, `opencode_plugin_restore_does_not_replace_a_file_created_at_restore_window`, `opencode_plugin_cleanup_does_not_escape_custom_target_directory`; `install_mcp.rs` `opencode_install_reuses_owned_endpoint_and_token_across_major_transitions`, `opencode_install_refuses_conflicting_owned_transition_entries`, `opencode_install_does_not_infer_from_a_user_owned_transition_entry`, `opencode_mcp_migration_moves_only_owned_alternate_shape`, `opencode_mcp_migration_preserves_ambiguous_user_entry`, `opencode_mcp_migration_preserves_custom_headers`, `opencode_mcp_migration_accepts_only_historical_generated_headers` | STRONG for Unix process probes and platform-neutral ownership gates; exact Windows executable resolution remains covered by `run.rs` resolver tests and requires the PR `windows` label || 11k | Server-side tool drop list (#1241) | `ai-memory-hooks/src/drop_list.rs` `IngestDropList::matches`, checked in `router.rs` `admit_hook` and the `handle_hook_batch` loop right after the client capture protocol and before the rate limiter, the ingest semaphore, the sanitizer and storage; lists from `[ingest] drop_tool_use_id_prefixes` / `drop_tool_names`, validated once in `Config::load` (at most 64 entries of 128 printable characters each). Only tool events match: a tool-call id by prefix, a tool name exactly, both read through the per-agent mapping `capture_policy::tool_payload_fields` that tool metadata uses (generic Claude-style fields for an agent without one; Factory Droid sends no tool-call id, so only its tool name can match). A drop answers 202 and counts as `dropped_by_policy`; the matched value is never logged | `router.rs` `the_ingest_drop_list_drops_before_any_capacity_is_spent` (with the semaphore exhausted a listed event still answers 202; control: an unlisted one gets 429) and `the_ingest_drop_list_applies_to_hook_batches` (listed items acknowledged as policy drops, the unlisted item ingested); `drop_list.rs` unit tests (prefix only at the start, names only exact, non-tool events never match, bounds refused; `each_agent_is_matched_on_its_own_tool_fields` matches OpenCode `callID`, Hermes `extra.tool_call_id` and Antigravity `toolCall.name`, with same-agent controls kept, and fails when only the generic fields are read). Both router tests fail with `matches` forced to `false` | STRONG. The list applies to every project on the server; it narrows what is stored and never widens access |+| 11l | Marketplace plugin front door: a plugin-launched event gets exactly the native hook's capture policy, scope and server routing, is captured once beside settings-file hooks, and sends nothing without the binary (#1166) | `plugins/*/scripts/ai-memory-hook` (rendered from `crates/ai-memory-cli/templates/plugin/ai-memory-hook.sh` by `render_plugins.rs`) has no capture logic: it only finds the binary and `exec`s `ai-memory hook` with `AI_MEMORY_HOOK_ORIGIN=<agent>-plugin`, `hook` first so the Docker wrapper routes it, and without a binary drains stdin, prints `{}` (guidance on `session-start` only) and exits 0; `hook.rs` `is_dropped_plugin_copy` + `plugin_origin.rs` `drops_plugin_event` drop a plugin copy when the user `settings.json` (honouring `CLAUDE_CONFIG_DIR`) or the checkout's `.claude/settings.local.json` carries an ai-memory hook for the same event (`install_hooks::settings_file_carries_ai_memory_hook_for_event`), and drop a folderless session (no `cwd`, or a Claude desktop `scratch-workspaces` cwd); Codex plugin events are never de-duplicated (an untrusted settings hook is skipped silently, so dropping could lose the event); the drift test keeps every plugin hook on the native path (no `hooks/<agent>/*.sh`, no credential in any plugin file) | CLI `tests/suite/plugins.rs` through the committed launcher and the real binary: `ignore_paths_hold_through_the_plugin` (ignored path never spooled; public-file control kept), `allowlist_mode_holds_through_the_plugin` (unmarked checkout emits nothing, prompts included; marked control captured), `marker_scope_routes_plugin_events`, `server_profiles_route_plugin_events` (profile URL and token, never the plugin's URL), `a_settings_hook_for_the_same_event_drops_the_plugin_copy` (user and project settings; unwired-event and no-settings controls), `folderless_sessions_are_not_captured_through_the_plugin`, `without_a_binary_nothing_is_sent_and_the_agent_is_not_blocked`, `foreign_hosts_are_attributed_or_ignored`, `committed_plugins_match_the_renderer`, `plugin_tree_carries_no_credentials`; `plugin_origin.rs` unit tests (`codex_plugin_events_are_never_deduplicated_against_settings`); `hook.rs` `plugin_copy_is_dropped_only_with_the_plugin_origin`; `tests/hooks/test_plugin_launcher.sh`; `tests/e2e/claude_plugin_smoke.py` (real `claude -p`: settings hook plus plugin give one `user-prompt`) | STRONG. Verified 2026-10-13: removing the `is_dropped_plugin_copy` guard fails the de-duplication and folderless tests (and the smoke reports `user-prompt x2`); disabling the native `Drop` disposition or the allowlist gate fails the `ignore_paths` and allowlist tests through the launcher. Not covered: tool events from a live model turn (no credential in CI), Windows Git Bash, Cowork and the desktop Code tab (see `docs/design-marketplace-plugins.md`) || 12 | Network/auth posture, including auth on by default for new installs (an existing install keeps loopback no-auth until `ai-memory auth enable`) | `config.rs` loopback `DEFAULT_BIND`; `serve.rs` `validate_http_exposure`, `require_allowed_host`; `auth.rs` `require_bearer`; `serve.rs` mounts `/identity` inside the host and machine-auth gates even with web disabled; `nix/nixos-module.nix` treats only literal `127.0.0.1`/`::1` as loopback, requires exactly one secret environment source for other binds, keeps secret auth and `llm_headers` values out of the Nix store, and brackets IPv6 in `ExecStart`; new-install default: `commands/init.rs` `root_bearer_for_new_config` mints a root bearer only on a fresh data dir (no config file and no database) and only when no bearer is supplied otherwise, via `local_auth.rs` `provision_root_token` (`auth-tokens/` `0700`, file `0600`, atomic, reused when present) and records the relative `[auth].bearer_token_file`; `config.rs` `apply_bearer_token_file` reads it once (`AI_MEMORY_AUTH_TOKEN` wins, inline + file together refused, a missing or blank file leaves no bearer) and `discover_root_token` lets a packaged install's client commands use `<data_dir>/auth-tokens/default` only with no config file at the probed path, a loopback server URL and no registered `default` profile; `serve.rs` `refuse_a_missing_token_file` stops a server whose configured file holds no token; `AuthSettings::renderable_bearer_token` keeps a file-sourced token out of every renderer: `install_mcp.rs` `route_file_token` (Claude Code gets the session-aware `ai-memory mcp-bridge` entry, Codex and Prime Agent name `AI_MEMORY_AUTH_TOKEN`, every other client a `stdio_bridge_entry` that runs `mcp-bridge --no-session-id` in its documented stdio shape, Pi keeps its extension, ZCode (HTTP-only) is refused) and `mcp_bridge.rs`, which authenticates with the config-resolved bearer and connects upstream before serving stdio, so a refused token ends it with `401 Unauthorized` instead of hanging; `uninstall.rs` `mcp_entry_is_ours` / `toml_mcp_entry_targets` recognise bridge entries by `install_mcp::bridge_entry_url`; `auth_enable.rs` `rewire_clients` re-registers every client whose entry targets this server, `install_hooks.rs` (persisted to the hook credential files, never inlined, not even on the F5 persist-failure fallback), `setup_agent.rs`, `run_autowire.rs`, `setup.rs` (runs `init`, adopts the minted token in memory through `adopt_token_file`, and calls the installers with no explicit token; the rendered user unit carries none; `user_service.rs` `is_rendered_by_setup` lets `uninstall` stop and delete only a unit carrying `setup`'s identity line whose SHA-256 still matches, never a hand-written or edited one); `local_auth.rs` `seed_hook_credential` gives hooks the token through `auth-token`/`auth-header` and keeps a different stored credential; `uninstall.rs` keeps the root bearer (`server_profiles::clear_tokens` `keep`); `commands/auth_enable.rs` is the idempotent opt-in | `serve.rs` host-guard (missing→400 / forged→403), non-loopback-requires-token; `auth.rs` wrong-token 401; `serve.rs` `machine_identity_remains_authenticated_with_web_disabled_and_expired_keys` (wrong and expired keys refused, valid machine key accepted, web remains disabled); `flake.nix` `nixos-module-eval` refuses `localhost` and `0.0.0.0` without a secret source, refuses two secret sources, `settings.auth` secrets, and `settings.llm_headers`, with literal IPv4/IPv6 loopback and one-source controls; `cli/tests/suite/auth_default_e2e.rs` against the shipped binary: `a_fresh_install_requires_the_token_and_its_own_clients_still_work` (after `init`, unauthenticated `/mcp`, `/hook`, `/api/v1/projects`, `/admin/status` → 401 and `/healthz` → 200; the same requests with the token succeed; the native hook delivers with no token in its environment, `status` authenticates through config, `mcp-bridge` lists tools; the token is in neither process's `/proc/<pid>/cmdline`; after `install-hooks`, `install-mcp --apply` for every client it writes (21, by default config path under the test home), a refused ZCode install and `auth enable` twice, a scan of the whole home finds the token nowhere and a scan of the data dir finds it only in the token file and the two hook credential files), `an_existing_install_is_unchanged_until_auth_enable` (control: a pre-default install serves every route open and `status` names the fix; `auth enable` twice is idempotent, rewires Claude Code to the bridge, and after a restart the routes refuse and the hook still delivers), `a_packaged_install_with_an_external_config_wires_its_clients`, `uninstall_keeps_the_root_bearer_and_a_missing_one_stops_the_server`, `a_host_client_given_the_token_file_by_env_authenticates`; `init.rs` `a_fresh_init_mints_a_root_bearer_the_loader_reads`, `init_on_an_existing_install_does_not_turn_auth_on`, `init_with_a_supplied_bearer_mints_nothing`, `re_running_init_keeps_the_same_root_bearer`; `config.rs` `a_relative_bearer_token_file_resolves_against_the_data_dir`, `a_missing_or_blank_bearer_token_file_is_reported_not_guessed`, `the_env_token_wins_over_the_bearer_token_file`, `an_inline_bearer_and_a_bearer_token_file_together_are_refused`, `a_client_without_a_config_file_discovers_the_root_bearer`, `root_bearer_discovery_is_refused_outside_its_narrow_case` (existing config, remote URL, `default` profile, env token); `auth_default_e2e.rs` `a_session_less_bridge_serves_any_client_without_holding_the_token` (`tools/list` and a scoped `memory_query` through `mcp-bridge --no-session-id` against a fresh auth-on server, the token in neither the bridge's `/proc/<pid>/cmdline` nor its `/proc/<pid>/environ`; control: the session-aware mode still refuses to start without `CLAUDE_CODE_SESSION_ID`) and `a_bridge_without_the_token_is_refused_cleanly_not_hung` (exits promptly naming `401 Unauthorized`); `mcp_bridge.rs` `only_the_session_aware_mode_forwards_and_requires_a_session_id`, `a_session_less_upstream_config_carries_no_session_header`, `stdio_bridge_forwards_tools_and_session_header_in_both_http_modes` (control); `install_mcp.rs` `a_file_sourced_token_wires_every_client_without_entering_its_config` (every written client: no token, no header, an entry that reaches the server; ZCode refused and unwritten), `stdio_bridge_entries_follow_each_clients_documented_shape`, `inline_and_explicit_tokens_still_embed_as_before` (control); `uninstall.rs` `bridge_entries_are_recognised_by_their_upstream_url` (JSON, OpenCode array and TOML shapes; a bridge to another server and a foreign command are kept); `install_hooks.rs` `a_file_sourced_token_is_persisted_but_never_embedded`; `auth_enable.rs` `enable_twice_is_idempotent_and_leaks_the_token_into_no_harness_config` (every client pre-wired over HTTP is re-registered, ZCode reported as manual, the second run byte-identical), `enable_leaves_an_entry_for_another_server_alone`, `enable_refuses_while_a_default_profile_would_share_the_token`; `local_auth.rs` `the_root_bearer_is_owner_only`, `seeding_never_replaces_a_different_hook_credential`; `setup_e2e.rs` `setup_installs_wires_is_idempotent_and_uninstall_removes_its_unit` (one `setup --yes` in a fresh temp home: the token is in no file under the home but the token file and the two hook credential files, not in the user unit and not in `setup`'s output; the self-check's `memory_status` and a hook event authenticate through the file; `uninstall` then disables and deletes the unit once and a second `uninstall` calls nothing), `uninstall_leaves_a_unit_it_did_not_write` (adversarial: the packaged unit copied by hand is kept, no `systemctl` call); `user_service.rs` `a_foreign_or_edited_unit_is_left_alone`, `rendered_units_carry_an_identity_that_survives_only_unedited` | STRONG. Bite checks for the new-install default: with fresh-install minting disabled the fresh e2e routes answer without a token and the `init` tests fail; with `renderable_bearer_token` returning the file token, `install-mcp`, `install-hooks`, `auth enable` and the e2e scans find it in harness configs; without the `serve` refusal a server whose token file was deleted keeps running (the e2e times out on it); without the hook seeding the fresh e2e hook is refused; without `clear_tokens` `keep` uninstall deletes the root bearer; with `route_file_token` no longer choosing the stdio bridge the every-client and `auth enable` tests fail; with `auth enable` skipping the re-registration its test fails; with the session-less mode forwarding an inherited id the bridge unit test fails; without the 401 naming the refusal e2e fails; without bridge-entry recognition the uninstall test fails; with `setup` handing the token to `install-mcp` its scan finds it in `.claude.json`; with `is_rendered_by_setup` accepting any unit, the foreign-unit tests fail; with discovery removed the packaged e2e gets 401, and with each discovery guard removed the matching case of `root_bearer_discovery_is_refused_outside_its_narrow_case` fails. Residual: a hand-edited `servers.toml` that adds a `default` profile after the root bearer exists would read the root bearer as that profile's token (`server add` refuses it, `auth enable` refuses while it exists); ZCode takes only HTTP entries and is refused, so it needs a manual entry; the stdio entries for Zero, Muse Code and DeepSeek Harness follow their documented or source-level format but were not run against those clients || 12b | Managed-workstream provenance privacy, stable replay identity and server event namespace | `ai-memory-core/src/workstream.rs` `scrub_workstream_provenance`; `ai-memory-hooks/src/workstream.rs` `finish_run` reserved client-id check and `sanitize_events` before immutable segments, with `sanitize_events` and `append_boundary_events` scrubbing event/checkpoint/losses content *before* the 64 KiB cap so a cap-straddling secret is never cut into an unmatchable prefix (#1113); `ai-memory-store/src/workstream.rs` `finish_run` stable identity check and `stored_event`, scrubbing content with the explicitly supplied configured sanitizer before its 16 KiB store-boundary bound; no changes to the typed observation boundary | `store/tests/suite/workstream_provenance.rs` `workstream_provenance_is_bounded_scrubbed_and_idempotent_before_storage` (hostile and oversized source ids, unknown metadata, legitimate correlation, retry and distinct event ids), `workstream_provenance_legacy_reads_strip_secrets_and_unknown_metadata` (search and tail, malformed/oversized legacy JSON), `workstream_provenance_reused_event_id_retains_data_and_refuses_identity_change` (first indexed version retained, identity refusal and batch rollback), `workstream_provenance_replay_survives_sanitizer_changes` (new extra patterns and removal of a built-in-pattern allowlist exemption, with identity-refusal control), `workstream_provenance_replay_preserves_legacy_rows_above_bounds`, `workstream_provenance_finished_run_ignores_late_events`, `workstream_provenance_retry_with_marker_matching_pattern_is_idempotent`, `workstream_content_is_scrubbed_before_the_store_cap` (a credential straddling the 16 KiB store cap is redacted, not persisted as an unmatchable prefix; benign control verbatim; #1113); `hooks` `workstream_provenance_finish_scrubs_before_raw_segment_and_search` (custom sanitizer, immutable segment, SQL recovery and finished-run no-op), `workstream_provenance_client_cannot_use_server_event_ids` (reserved ids refused before raw writes, normal client event and server-generated checkpoint/loss controls), `finish_run_scrubs_event_content_before_the_byte_cap` and `finish_run_scrubs_boundary_events_before_the_byte_cap` (a credential straddling the 64 KiB event cap is redacted in the raw segment and never reaches the index; checkpoint/losses and benign controls; #1113); `cli/tests/suite/workstream_provenance.rs` (text/JSON and old server DTOs) | STRONG: privacy, stable-identity and reserved-namespace regressions fail with their guards bypassed; an isolated allowlist bypass fails on the unknown key, and bypassing the raw-id search authorization returns 200 where its test requires 403. No provenance is emitted in startup packets, and old raw segments are not rewritten || 12c | Browser cross-origin writes refused on an unauthenticated server (a foreign page in the operator's browser, DNS rebinding, and a LAN host where browsers send no fetch metadata) | `serve.rs` `refuse_cross_origin_browser_requests` / `is_cross_origin_browser_request`, layered on the machine (`/mcp`, `/hook*`, `/handoff`, `/workstream/*`, `/identity`) and admin (`/admin/*`) routes when auth is off: `Sec-Fetch-Site` other than `same-origin`/`none` → 403, or, without fetch metadata, an `Origin` whose authority is not the `Host` → 403; and `is_non_script_browser_request`: any `Sec-Fetch-Dest` other than `empty` (case-insensitive; non-UTF-8 refused) → 403 whatever `Sec-Fetch-Site` says, so links, images, navigations, iframes and form posts are refused even as `same-origin` or `none`. Browsers send fetch metadata over plain HTTP only to a potentially trustworthy host, so on any other `Host` (a LAN address or name in the allowlist, `0.0.0.0`, `host.docker.internal`; `is_loopback_host` admits only `localhost`, `*.localhost`, `127.0.0.0/8` and `[::1]`) `handoff_fetch_lacks_client_marker` also refuses `GET`/`HEAD /handoff` without a non-empty `X-AI-Memory-Client` header (`ai_memory_hooks::CLIENT_MARKER_HEADER`) → 403 whose body names both remedies (re-stage hooks, or set a bearer token). A page cannot add that header without a preflight these routes never answer. `/handoff` is the one state-changing `GET` on these routes; the other `GET`s are reads a foreign page cannot see the answer to, and every cross-origin `POST` carries `Origin`. Every first-party client sends the marker: the native hook (`hook_capture.rs` `post_hook`/`post_batch`/`get_handoff`), CLI subcommands (`http_client.rs` `ServerEndpoint::authenticate`), every curl in `hooks/_lib.sh`, both header tables in `hooks/lib/ai-memory-hook.ps1`, and the generated TypeScript integrations (`render_shared.rs` `ts_auth_headers_fn` plus the spool drain). Loopback hosts keep accepting a fetch without it, so hooks staged before the header existed still work on a default install, except that a request carrying any proxy forwarding header (`Forwarded`, `X-Forwarded-For`/`-Host`/`-Proto`/`-Server`/`-Port`, `X-Original-Forwarded-For`, `X-Real-IP`, `X-Client-IP`, `CF-Connecting-IP`, `True-Client-IP`, `Via`; `PROXY_HEADERS`) counts as non-loopback, since a plain-HTTP proxy can rewrite `Host` to loopback while the browser behind it sent no fetch metadata. No first-party client sends those headers. Hooks, the CLI and MCP clients send none of these headers; the web UI's same-origin `/admin/pending-writes` calls are `fetch()` (`Sec-Fetch-Dest: empty`) and pass. Behind it, axum `Json` and rmcp's `Content-Type: application/json` check refuse the preflight-free content types (`text/plain`, form-urlencoded, multipart) with 415; `require_allowed_host` (and rmcp `allowed_hosts` on `/mcp`) refuses a rebinding `Host`; machine/admin routes carry no CORS layer, so a preflight never comes back permissive. A stored wiki page viewed in the built-in web UI could otherwise turn the guard's same-origin allowance into a claim: `ai-memory-web/src/markdown.rs` `safe_image_url` / `is_safe_image_target` render as `#` any image target that is root-relative, a network path, carries a `..` segment (also percent-encoded), or, for a UI mounted at the base-path root, starts with a server route segment Every `/web` surface (built-in pages including `/web/pending`, the login page, a custom SPA and `/api/v1`) answers `X-Frame-Options: DENY` and `Content-Security-Policy: frame-ancestors 'none'` (`ai-memory-web/src/mount.rs` `deny_framing`), because a framed page's own Approve/Reject `fetch()` is same-origin and the guard rightly lets it through | `cli/tests/suite/cross_origin_e2e.rs` `browser_cross_origin_requests_cannot_write_to_an_unauthenticated_loopback_server`, against the shipped `serve`: every write route (`/hook`, `/hook/batch`, MCP `memory_write_page`/`memory_delete_page`/`memory_message_send`/`memory_handoff_accept`, `/admin/write-page`/`delete-page`/`purge-project`/`messages/send`, `/workstream/runs`) × each simple content type × modern, Origin-only and fetch-metadata-only browser shapes → 4xx; body-less `GET /handoff` (which claims the single-use baton), `POST /admin/profile/rebuild` and `POST /admin/backup` → 403; a rebinding `Host` → 403; preflights answer no `Access-Control-Allow-*`; `GET /handoff` as a same-origin `document` or `image` and as a `Sec-Fetch-Site: none` `document` → 403 with the baton still open. Then a canary scan of the whole data dir, page/project/handoff survival, and legitimate controls (JSON MCP calls, a JSON hook → 202, the web UI's same-origin `/admin/pending-writes` list and approve reach their handlers, the anonymous active-project pointer is unmoved after the refused `/handoff` fetches while the closing hook-style fetch claims the baton and moves it). `serve.rs` `cross_origin_browser_request_detection` and `non_script_browser_request_detection` (header tables) and `cross_origin_browser_guard_applies_only_without_auth` (same-origin `image` and `none` `document` refused, same-origin `empty` passes, both pass with auth on); `ai-memory-web` `markdown.rs` `neutralises_images_that_reach_server_routes` (`/handoff?…`, `/admin/backup`, `//host/…`, `../` and `%2e%2e/` traversal, root-mounted route names refused) with `preserves_relative_images` as the legitimate control. `cross_origin_e2e.rs` `handoff_fetch_on_a_lan_host_requires_the_client_marker`, against a `serve` that allowlists a LAN name and address: `GET` and `HEAD /handoff` through either without the marker, and with an empty one → 403 carrying the remedy text, with the baton still open and the active-project pointer unmoved; controls: a marked fetch through the LAN name claims the baton, and a marker-less fetch through `127.0.0.1` (a hook staged before the marker) claims the next one; then a `127.0.0.1` fetch carrying each proxy forwarding header and no marker → 403 with the baton still open, and the same fetch with the marker claims it. `serve.rs` `loopback_host_detection`, `handoff_fetch_client_marker_decision` (incl. a loopback `Host` with each proxy header, refused without the marker and admitted with it, and a named row per header so none can drop out of the list) and `handoff_client_marker_guard_on_lan_hosts_and_under_a_base_path` (also under a `--base-path` nest; inactive with auth on). Front-door parity: `hook_capture.rs` `every_native_hook_request_carries_the_client_marker` (handoff GET, hook POST, batch POST), `http_client.rs` `authenticate_no_token_sets_only_the_client_marker`, the client-marker block of `tests/hooks/test_lib.sh` (every curl branch of the GET, the POST and the drain, plus a static check that every PowerShell header table carries it and every `Invoke-WebRequest` passes one), `render_shared.rs` `assert_every_ts_request_carries_client_marker` run for OpenCode, OpenCode 2, OMP, Pi and OpenClaw, `external_capture_ts.rs` (the rendered OpenCode plugin under Node sends no unmarked request) and `external_capture_powershell.rs` `every_request_carries_the_client_marker` (Windows leg); `ai-memory-web/src/mount.rs` `web_surfaces_refuse_to_be_framed` (`/web`, `/web/pending`, `/web/login`, `/api/v1/projects` all carry both headers; bites with `deny_framing` neutralized) | STRONG with listed residuals. Bite checks: with the marker check disabled, the LAN e2e marker-less `GET /handoff` returns 200 and the unit layer test fails; with the proxy-header rule disabled, the proxied loopback e2e fetch claims the baton and the unit decision test fails; dropping the marker from the native handoff GET, the shell token-drain curl, a PowerShell header table or the TypeScript spool drain fails the matching front-door test. With the guard removed, the cross-origin `GET /handoff` returns 200, consumes the baton and moves the active-project pointer (the pre-fix behaviour); with the guard treating `same-origin` as foreign, the web UI control gets 403; with the `Sec-Fetch-Dest` check removed, the same-origin `document` `GET /handoff` returns 200 and the unit guard test lets a same-origin image through; with the host layer removed, a rebound `/hook` returns 202; a permissive `CorsLayer` fails the preflight assertion; reverting `is_safe_image_target` to the pre-fix rule fails the markdown test on `/handoff?…`, dropping the percent-decoding fails it on `%2e%2e/`, and emptying the route list fails it on a root-mounted `handoff`. To reproduce the bite on the 415 layer, remove the guard and make `/hook` read a raw body instead of `Json`: a `text/plain` hook then returns 202 and the test fails. Residual, closed by setting a bearer token: a browser that sends no fetch metadata even to a loopback host (Safari before 16.4) sends no `Sec-Fetch-*` header and no `Origin` on an image `GET` or a link click, so such a request to a loopback host still reaches `/handoff` (loopback keeps accepting marker-less legacy hooks) and the other, read-only `GET` routes. On a non-loopback host the marker requirement closes `/handoff` for every browser. A plain-HTTP proxy that rewrites `Host` to its loopback upstream and adds no forwarding header (nginx's default `proxy_pass`) looks exactly like a local client, so in front of an unauthenticated server it must add `X-Forwarded-For` or keep `proxy_set_header Host $host`, or the server must sit behind TLS or use a bearer token (`security.md`, `https-via-proxy.md`). Browsers that send fetch metadata no longer have the earlier link residuals: a link opened from another app (`Sec-Fetch-Site: none`) and a link clicked in a stored page (`same-origin` navigation) both carry a non-`empty` destination and are refused. With auth on, the bearer token and the session CSRF token are the gate and this layer is a no-op |diff --git a/plugins/claude-code/.claude-plugin/plugin.json b/plugins/claude-code/.claude-plugin/plugin.jsonindex 747f151f..e439fb19 100644--- a/plugins/claude-code/.claude-plugin/plugin.json+++ b/plugins/claude-code/.claude-plugin/plugin.json@@ -2,7 +2,7 @@"name": "ai-memory","displayName": "ai-memory","version": "2.6.6",- "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.",+ "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. In Cowork, capture runs on your computer and needs ai-memory installed there; the memory tools still work.","author": {"name": "AkitaOnRails","url": "https://github.com/akitaonrails"diff --git a/plugins/claude-code/README.md b/plugins/claude-code/README.mdindex 0ba62b03..d7fc3952 100644--- a/plugins/claude-code/README.md+++ b/plugins/claude-code/README.md@@ -31,20 +31,22 @@ claude plugin marketplace add akitaonrails/ai-memoryclaude plugin install ai-memory@ai-memory```-`ai-memory upgrade` also updates the plugin, because Claude Code does not-auto-update third-party marketplaces unless you turn that on.+Claude Code does not auto-update third-party marketplaces unless you turn+that on. `ai-memory upgrade` updates the plugin along with a release-tarball+binary; after a Homebrew, AUR or RPM upgrade, run `claude plugin marketplace+update ai-memory` and `claude plugin update ai-memory@ai-memory`.## What it runs and what it sends-- **Hooks.** Every lifecycle event (session start and end, prompts, tool+- Hooks: every lifecycle event (session start and end, prompts, toolcalls, compaction, stop, subagents) runs `scripts/ai-memory-hook`, a shortPOSIX shell script you can read in full. It finds the installed `ai-memory`binary and hands it the event with `ai-memory hook`. The binary appliesyour capture exclusions (`ignore_paths`, allowlist mode, server profiles)before anything is written or sent, spools the event locally, and deliversit only to your ai-memory server, which sanitizes it before storage.-- **MCP.** The ai-memory memory tools, through `ai-memory mcp-bridge`.-- **Skills.** The ai-memory routing skills, plus `/ai-memory:status`, which+- MCP: the ai-memory memory tools, through `ai-memory mcp-bridge`.+- Skills: the ai-memory routing skills, plus `/ai-memory:status`, whichruns `ai-memory doctor` and summarizes it.No telemetry. Nothing goes anywhere except the ai-memory server you@@ -77,11 +79,11 @@ setup` leaves Claude's settings alone while the plugin is enabled.## Platform notes-- **Windows.** Claude Code runs plugin hooks through Git Bash, which it+- On Windows, Claude Code runs plugin hooks through Git Bash, which italready requires; the launcher needs nothing else.-- **Docker wrapper.** Plugin hooks need a wrapper that routes `ai-memory+- With the Docker wrapper, plugin hooks need a wrapper that routes `ai-memoryhook` to its native client; run `ai-memory upgrade` to get it.-- **Cowork.** Capture runs on your computer and needs ai-memory installed+- In Cowork, capture runs on your computer and needs ai-memory installedthere; the memory tools still work.## Uninstalldiff --git a/plugins/codex/README.md b/plugins/codex/README.mdindex 2e3b42a0..5cf2300b 100644--- a/plugins/codex/README.md+++ b/plugins/codex/README.md@@ -31,14 +31,14 @@ command says so in its changelog, and you trust the new command once.## What it runs and what it sends-- **Hooks.** Each lifecycle event runs `scripts/ai-memory-hook`, a short POSIX+- Hooks: each lifecycle event runs `scripts/ai-memory-hook`, a short POSIXshell script, which hands the event to the installed binary(`ai-memory hook`). The binary applies your capture exclusions, spools theevent, and delivers it only to your ai-memory server. On Windows the hookscall `ai-memory hook` directly, so `ai-memory` must be on `PATH`.-- **MCP.** The ai-memory memory tools, through `ai-memory mcp-bridge+- MCP: the ai-memory memory tools, through `ai-memory mcp-bridge--no-session-id`.-- **Skills.** The ai-memory routing skills and a `status` skill.+- Skills: the ai-memory routing skills and a `status` skill.No telemetry. The plugin has no settings; the server URL and credentialscome from your ai-memory config.