Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(install): add MCP recipes for seven more clients
AkitaOnRails1cc23eb16980
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8054010a..30e0fc53 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -159,6 +159,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0refuses `--apply`. (#1193)### Changed+- Documented hand-written MCP recipes for Factory Droid, Warp, Cline, Kilo+ Code, Goose, Qwen Code and OpenHuman in `docs/install.md`, and listed them+ in `docs/support-matrix.md` as `MCP-only (documented)`: each recipe follows+ the client's own documentation at a named version and has not yet been run+ end to end. Aider is not listed because it has no MCP support.- Changed `ai-memory-wikisync` files to carry a small frontmatter (`title`,plus `tags`, `pinned` and a non-default `tier` when set) above the body,so metadata survives a round trip. The first run after upgrading rewritesdiff --git a/docs/install.md b/docs/install.mdindex e15ce35c..93af46dd 100644--- a/docs/install.md+++ b/docs/install.md@@ -1747,6 +1747,228 @@ handoff injection at session start or the client's closest equivalent, exceptfor Zero's no-stdout SessionStart behavior. Grok delivers on the first`PostToolUse` instead (Antigravity CLI uses `PreInvocation`).+#### Clients without an `install-mcp` writer++The clients below can reach ai-memory over streamable HTTP, but `install-mcp`+has no `--client` value for them, so you add the entry by hand. Each recipe+follows the client's own documentation at the version named. None of them has+been run end to end against ai-memory yet; the+[support matrix](support-matrix.md) marks them `MCP-only (documented)`.+If one does not connect as described, please open an issue with the client+version.++All of them are MCP-only here: ai-memory installs no lifecycle hooks for them,+so there is no automatic capture and no handoff injection. Ask the agent to+call `memory_handoff_begin` before you leave and `memory_handoff_accept` when+you resume. None of them sends ai-memory a session id, so they are static+clients: project-scoped calls need `workspace` and `project`, which the+routing snippet from `ai-memory install-instructions --target AGENTS.md`+tells the model.++The examples use the local server, `http://127.0.0.1:49374/mcp`. For a remote+server, change the URL and add the bearer header shown. Where the client+expands environment variables in its config, the example reads the token+from `AI_MEMORY_AUTH_TOKEN`; export it in the shell that starts the client.+Where the client documents no expansion, the example shows `<token>`, and the+token has to be written into that file, so keep the file private. All of+these clients speak HTTP MCP natively; `ai-memory mcp-bridge` is a Claude+Code-only adapter and is not needed.++##### Factory Droid++Droid (`droid`) reads MCP servers from `~/.factory/mcp.json` (user),+`.factory/mcp.json` in the project root, or a `.factory/mcp.json` in an+ancestor folder. It reloads when the file changes. Droid expands `${NAME}` in+`headers` values (not in `url`), and its docs say to keep auth headers in the+user file rather than the committed project file:++```json+{+ "mcpServers": {+ "ai-memory": {+ "type": "http",+ "url": "http://127.0.0.1:49374/mcp",+ "headers": { "Authorization": "Bearer ${AI_MEMORY_AUTH_TOKEN}" }+ }+ }+}+```++Leave out `headers` when the server has no bearer token. An unset variable+makes Droid fail that connection with an error naming it. Without a token,+`droid mcp add ai-memory http://127.0.0.1:49374/mcp --type http` writes the+same entry to the user file. Documented for Droid CLI 0.237.0.+Sources: <https://docs.factory.com/cli/configuration/mcp>,+<https://docs.factory.com/changelog/cli-updates>.++##### Warp++Warp reads `~/.warp/.mcp.json` and, after you approve it, a project's+`.warp/.mcp.json`. You can also add the server under **Settings > Agents >+MCP servers > + Add**. A URL server takes `url` and an optional `headers`+map, with no `type` key:++```json+{+ "mcpServers": {+ "ai-memory": {+ "url": "http://127.0.0.1:49374/mcp",+ "headers": { "Authorization": "Bearer <token>" }+ }+ }+}+```++Warp does not document environment-variable expansion in `headers`. Leave+out `headers` when the server has no bearer token. The separate Warp Agent+CLI keeps its own file with the same `mcpServers` format (`~/.warp_cli/.mcp.json`+on macOS; the docs give no Linux path). Documented for Warp+v0.2026.10.07.08.29.+Sources: <https://docs.warp.dev/agents/capabilities/mcp>,+<https://docs.warp.dev/agents/cli/configuration/>.++##### Cline++The Cline CLI reads `~/.cline/data/settings/cline_mcp_settings.json`+(override the path with `CLINE_MCP_SETTINGS_PATH`). In the VS Code extension,+open the **MCP Servers** icon, then **Configure > Configure MCP Servers**, and+edit the same `mcpServers` map. Set `type` to `streamableHttp`: without it,+Cline falls back to the legacy SSE transport.++```json+{+ "mcpServers": {+ "ai-memory": {+ "type": "streamableHttp",+ "url": "http://127.0.0.1:49374/mcp",+ "headers": { "Authorization": "Bearer <token>" },+ "disabled": false+ }+ }+}+```++Cline does not document environment-variable expansion in `headers`. Leave+out `headers` when the server has no bearer token; in that case the CLI can+write the entry with+`cline mcp add ai-memory http://127.0.0.1:49374/mcp --transport http`.+Documented for the Cline extension 4.1.23 and CLI 3.0.70.+Source: <https://docs.cline.bot/mcp/mcp-overview>.++##### Kilo Code++The Kilo Code VS Code extension and the Kilo CLI share one config:+`~/.config/kilo/kilo.jsonc` (or `kilo.json`) globally, or `kilo.jsonc` /+`.kilo/kilo.jsonc` in the project. Servers live under the `mcp` key, and a+remote server has `type: "remote"`; Kilo tries streamable HTTP first and+falls back to SSE. Kilo expands `{env:NAME}` in config values:++```json+{+ "mcp": {+ "ai-memory": {+ "type": "remote",+ "url": "http://127.0.0.1:49374/mcp",+ "enabled": true,+ "oauth": false,+ "headers": { "Authorization": "Bearer {env:AI_MEMORY_AUTH_TOKEN}" }+ }+ }+}+```++ai-memory uses a bearer token, not OAuth, so `"oauth": false` stops Kilo from+starting an OAuth flow. Leave out `headers` when the server has no bearer+token. The older `mcp_settings.json` and `.kilocode/mcp.json` files are not+in the current docs. Documented for Kilo Code 7.8.8.+Sources: <https://kilo.ai/docs/automate/mcp/using-in-kilo-code>,+<https://kilo.ai/docs/automate/mcp/using-in-cli>.++##### Goose++Goose keeps extensions in `~/.config/goose/config.yaml`+(`%APPDATA%\Block\goose\config\config.yaml` on Windows). Run `goose+configure`, choose **Add Extension > Remote Extension (Streamable HTTP)**,+enter the URL, and, for a server with a bearer token, add the custom request+header `Authorization: Bearer <token>`. The resulting entry has this shape;+note that the URL key is `uri`:++```yaml+extensions:+ ai-memory:+ type: streamable_http+ name: ai-memory+ enabled: true+ uri: "http://127.0.0.1:49374/mcp"+ headers:+ Authorization: "Bearer <token>"+ timeout: 300+```++Goose does not document environment-variable expansion in `headers`. Leave+`headers` empty (`{}`) when the server has no bearer token. For one session,+`goose session --with-streamable-http-extension "http://127.0.0.1:49374/mcp"`+loads the server without saving it (that flag takes no header). Documented+for Goose 1.54.0.+Sources: <https://goose-docs.ai/docs/guides/config-files>,+<https://goose-docs.ai/docs/getting-started/using-extensions>,+<https://goose-docs.ai/docs/guides/goose-cli-commands>.++##### Qwen Code++Qwen Code reads `mcpServers` from `~/.qwen/settings.json` (user) or+`.qwen/settings.json` (project). A streamable-HTTP server uses `httpUrl`; the+plain `url` key means the legacy SSE transport. Qwen Code expands `$NAME` and+`${NAME}` in every string of `settings.json`:++```json+{+ "mcpServers": {+ "ai-memory": {+ "httpUrl": "http://127.0.0.1:49374/mcp",+ "headers": { "Authorization": "Bearer ${AI_MEMORY_AUTH_TOKEN}" }+ }+ }+}+```++Leave out `headers` when the server has no bearer token; in that case+`qwen mcp add --scope user --transport http ai-memory http://127.0.0.1:49374/mcp`+writes the entry. Documented for Qwen Code 0.25.1.+Sources: <https://qwenlm.github.io/qwen-code-docs/en/users/features/mcp/>,+<https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/>.++##### OpenHuman++OpenHuman (tinyhumansai/openhuman) adds servers through the **mcp.json** tab+of its MCP Servers screen. That document is a view over OpenHuman's own+server store, not a file you edit on disk. A server with `url` is dialled+over streamable HTTP, and `headers` holds its credentials:++```json+{+ "mcpServers": {+ "ai-memory": {+ "url": "http://127.0.0.1:49374/mcp",+ "headers": { "Authorization": "Bearer <token>" }+ }+ }+}+```++OpenHuman does not document environment-variable expansion in that+document. It stores header values write-only and never shows them again.+Leave out `headers` when the server has no bearer token. Documented for+OpenHuman 0.64.15.+Sources: <https://tinyhumans.gitbook.io/openhuman/features/integrations/mcp-and-skills>,+<https://tinyhumans.gitbook.io/openhuman/developing/architecture/mcp-registry>.++##### Aider++Aider has no MCP support in any release (checked against 0.86.2 and its+release history), so there is no recipe. Its feature request is+[Aider-AI/aider#3314](https://github.com/Aider-AI/aider/issues/3314).+---## Installing hooks without dockerdiff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex f9bce6c6..13269f0b 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -3,6 +3,10 @@For a custom tool, start with the [programmatic memory guide](programmatic-memory.md).It shows direct MCP writes, queries and handoffs without a native hook adapter.+Factory Droid, Warp, Cline, Kilo Code, Goose, Qwen Code and OpenHuman have no+`install-mcp` client; their hand-written recipes are in+[`install.md`](install.md#clients-without-an-install-mcp-writer).+> All snippets below default to `http://127.0.0.1:49374` (local server). For a> remote server (homelab, LAN box) substitute the appropriate URL AND add an> `Authorization: Bearer <token>` header to the `headers` block when bearer authdiff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex 41e44800..99a3cf49 100644--- a/docs/support-matrix.md+++ b/docs/support-matrix.md@@ -2,6 +2,11 @@> The complete platform and agent matrix, with integration notes.> Moved verbatim from the README front page, which keeps a compact view.+>+> `MCP-only (documented)` means the row has a hand-written MCP recipe that+> follows the client's own documentation at the version named, and that+> nobody has yet run the client end to end against ai-memory. These rows are+> not in the README's compact view, which lists first-party integrations only.| Area | Status | Notes |@@ -43,5 +48,12 @@| Prime Agent | MCP-only | `install-mcp --client prime-agent` merges an HTTP entry (`type: "http"` + `url`) into the `mcpServers` map of `$PRIME_AGENT_CODING_AGENT_DIR/settings.json` (default `~/.prime/agent/settings.json`), preserving other settings and servers; a project's `.prime/agent/settings.json` works through `--config-file`. A token is referenced as `"bearerTokenEnvVar": "AI_MEMORY_AUTH_TOKEN"`, never written: Prime Agent 0.10 counts a user HTTP server as connected and names it in the model's prompt only with that variable set or an OAuth grant. A credential-less entry is still callable through `mcp.call_tool("ai-memory", ...)` but is not listed. The model reaches MCP tools from its Python REPL (`await mcp.call_tool("ai-memory", "memory_query", {...})`), and Prime Agent sends no session id or cwd, so pass `workspace` and `project` on project-scoped calls. Lifecycle capture and managed workstreams are not claimed: Prime Agent 0.10 removed the TypeScript extensions its 0.9 releases had and has no hook surface. Verified against Prime Agent 0.10.0. || Hermes Agent | Supported | `install-hooks --agent hermes` (alias `hermes-agent`) prints a ready-to-paste `hooks:` block for `~/.hermes/config.yaml`. Hermes splits each configured `command` with `shlex.split` and runs it with no shell, passing the event JSON on stdin, so the entries invoke the native `ai-memory hook` command (exec form, like Zero and ZCode — no script bundle is staged); ai-memory never writes that YAML file, which is yours to edit and which Hermes itself gates behind its hook-acceptance prompt (`hooks_auto_accept`). Two tool events are wired, `pre_tool_call` → `pre-tool-use` and `post_tool_call` → `post-tool-use`; their `tool_name` / `tool_input` payload drives concrete session attribution, tool-family titles, and capture exclusions. Hermes reports its own process directory as `cwd`, so the native hook locates each event's `.ai-memory.toml` from the tool's absolute `workdir` (`terminal`) or `path` (file tools, `search_files`); a call with no absolute location stays with the process directory. Session lifecycle (recall, prompt capture, session-end, automatic handoff) is owned by the community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) memory provider, so no hook-driven `session-end` is installed and nothing is duplicated; review that plugin's compatibility matrix, install/uninstall scripts, and secret handling before enabling it. No first-party `install-mcp` client and no managed workstream are claimed yet, and because Hermes ignores session-start hook stdout a pending handoff is recovered through MCP (`memory_handoff_list` then `memory_handoff_accept`). || GrizzyBot | Supported | [GrizzyBot](https://github.com/Foscoe63/GrizzyBot), a native macOS agent app, ships its own ai-memory bridge: it posts lifecycle events to `/hook` with `agent=grizzybot` (alias `grizzy-bot`) and talks to `/mcp` directly, so there is nothing for `install-hooks` or `install-mcp` to write. Sessions are attributed to `grizzybot`, and its Claude Code-shaped tool payloads (`tool_name`/`tool_input`/`tool_use_id`) are stored as closed-schema tool families, never tool names or arguments. The bridge is maintained in the GrizzyBot repository; review it before pointing it at a shared server. No managed workstream. |+| Factory Droid | MCP-only (documented) | Native HTTP entry in `~/.factory/mcp.json` (`type: "http"`, `url`, `headers`); the bearer header reads `${AI_MEMORY_AUTH_TOKEN}`, which Droid expands. No `install-mcp` client and no lifecycle hooks installed. Documented against Droid CLI 0.237.0, not yet verified end to end. See [`install.md`](install.md#factory-droid). |+| Warp | MCP-only (documented) | `url` + `headers` entry in `~/.warp/.mcp.json` or **Settings > Agents > MCP servers**; no documented env-var expansion in headers. No `install-mcp` client and no lifecycle hooks. Documented against Warp v0.2026.10.07.08.29, not yet verified end to end. See [`install.md`](install.md#warp). |+| Cline | MCP-only (documented) | `type: "streamableHttp"` entry under `mcpServers` (CLI: `~/.cline/data/settings/cline_mcp_settings.json`; extension: **MCP Servers > Configure**); without `type` Cline uses legacy SSE. No `install-mcp` client and no lifecycle hooks installed. Documented against Cline extension 4.1.23 / CLI 3.0.70, not yet verified end to end. See [`install.md`](install.md#cline). |+| Kilo Code | MCP-only (documented) | `type: "remote"` entry under `mcp` in `~/.config/kilo/kilo.jsonc` (shared by the VS Code extension and the CLI), with `"oauth": false` and the bearer header from `{env:AI_MEMORY_AUTH_TOKEN}`. No `install-mcp` client and no lifecycle hooks installed. Documented against Kilo Code 7.8.8, not yet verified end to end. See [`install.md`](install.md#kilo-code). |+| Goose | MCP-only (documented) | `type: streamable_http` extension (URL key `uri`) in `~/.config/goose/config.yaml`, added with `goose configure`; no documented env-var expansion in headers. No `install-mcp` client and no lifecycle hooks installed. Documented against Goose 1.54.0, not yet verified end to end. See [`install.md`](install.md#goose). |+| Qwen Code | MCP-only (documented) | `httpUrl` entry under `mcpServers` in `~/.qwen/settings.json`; the bearer header reads `${AI_MEMORY_AUTH_TOKEN}`, which Qwen Code expands. No `install-mcp` client and no lifecycle hooks installed. Documented against Qwen Code 0.25.1, not yet verified end to end. See [`install.md`](install.md#qwen-code). |+| OpenHuman | MCP-only (documented) | `url` + `headers` entry added in the app's **mcp.json** tab (a view over OpenHuman's server store, not a file on disk); header values are stored write-only. No `install-mcp` client and no lifecycle hooks installed. Documented against OpenHuman 0.64.15, not yet verified end to end. See [`install.md`](install.md#openhuman). || LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode (Go and Zen), OpenAI-compatible endpoints, and generic OIDC device auth for native hooks. || Embedding providers | Supported | OpenAI, Voyage, Google Gemini, and keyless OpenAI-compatible endpoints such as Ollama, LM Studio, and vLLM. |