Skip to content

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.md
index 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.0
refuses `--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 rewrites
diff --git a/docs/install.md b/docs/install.md
index 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, except
for 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 docker
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index 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 auth
diff --git a/docs/support-matrix.md b/docs/support-matrix.md
index 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. |