Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs: surface Security, document scenario C, fix stale /web claim

AkitaOnRails13f0eb52012a
diff --git a/README.md b/README.md
index 7bdd4128..159a5924 100644
--- a/README.md
+++ b/README.md
@@ -96,6 +96,12 @@ overwrites them so future image updates ship updated hooks. Drop
> `restart: unless-stopped`, a healthcheck, and the named volume
> wired up; step 3 is identical.
+> **Server on a different machine?** Replace `-p 127.0.0.1:49374:49374` with
+> `-p 0.0.0.0:49374:49374` on the server's docker run; on the client, set
+> `export AI_MEMORY_SERVER_URL=http://<server-ip>:49374` and add
+> `--server-url <same>` to the install-mcp / install-hooks commands.
+> See [Security](#security) — anything non-loopback should also have a bearer token.
+
### Keeping ai-memory up to date
The wrapper checks Docker Hub at most once every 24 hours and prints
@@ -119,6 +125,12 @@ wired up alone. Set `AI_MEMORY_NO_VERSION_CHECK=1` to silence the
daily check, or `AI_MEMORY_WRAPPER_URL=<url>` to pin the self-upgrade
source (e.g. a fork or a tagged release).
+> **If your server runs on a different host** (scenarios C/D), `ai-memory upgrade`
+> only refreshes the local wrapper, your local image, and your hook scripts. You
+> still need to redeploy the server separately — run `bin/deploy` on the homelab
+> box (or `docker compose pull && docker compose up -d` in your deploy dir) so
+> the server picks up the new binary too.
+
> **Inside ai-jail (or any bwrap sandbox)?** The wrapper at
> `~/.local/bin/ai-memory` works fine — the sandbox bind-mounts
> `~/.local` read-only, so the script is visible from inside, and
@@ -134,34 +146,6 @@ needed), running ai-memory without docker, the full subcommand
reference, the homelab deploy pattern, security hardening — see
[**`docs/install.md`**](docs/install.md).
-## Configuring the CLI
-
-The `ai-memory` binary is a thin HTTP client. It never opens the
-wiki or SQLite directly — every state-touching command goes through
-the running server, which is the sole writer.
-
-Configuration is two environment variables, both **optional**:
-
-| Variable | Default | When to set it |
-|---|---|---|
-| `AI_MEMORY_SERVER_URL` | `http://127.0.0.1:49374` | When the server runs somewhere other than this machine (e.g. a homelab at `http://192.168.0.90:49374`). |
-| `AI_MEMORY_AUTH_TOKEN` | unset (no auth) | When the server has bearer auth enabled — see [Security](#security). |
-
-For the **single-laptop local case** you don't need either: the CLI
-talks to the loopback server with no credentials and just works.
-
-For a **remote / homelab** server, set both in your shell rc (or a
-`.envrc` if you use direnv):
-
-```bash
-export AI_MEMORY_SERVER_URL="http://192.168.0.90:49374"
-export AI_MEMORY_AUTH_TOKEN="b9a5075d…"
-```
-
-The `init`, `serve`, `install-*`, `generate-auth-token`, and
-`setup-agent` subcommands don't need these env vars — they either
-set up local files or start the server itself.
-
## Security
The default Quick start runs **without authentication** because the
@@ -170,23 +154,24 @@ this machine can reach it. That's the safest default for a personal
laptop and matches the "single-user, single-machine" use case the
project is optimised for.
-You need to enable bearer authentication if **any of these are
-true:**
+### When you need bearer auth
-- The server is exposed beyond loopback (LAN, VPN, reverse proxy,
- cloud).
+Enable bearer auth if **any** of these are true:
+
+- The server is exposed beyond loopback (LAN, VPN, reverse proxy, cloud).
- More than one untrusted process runs on the same machine.
- The data dir contains observations from sensitive projects you
wouldn't want any local user to read.
-To enable it:
+### Enabling bearer auth (turn-key recipe)
```bash
# 1. Generate a token (one-time; save the output somewhere).
TOKEN=$(ai-memory generate-auth-token)
echo "$TOKEN" # 64 hex chars
-# 2. Pass it to the server on startup.
+# 2. Pass it to the server on startup. Note the bind is now 0.0.0.0
+# so remote clients can reach it; only do this with a token set.
docker run -d --name ai-memory \
--restart unless-stopped \
-p 0.0.0.0:49374:49374 \
@@ -201,22 +186,21 @@ docker run -d --name ai-memory \
export AI_MEMORY_AUTH_TOKEN="$TOKEN"
# 4. Re-run install-mcp / install-hooks so the agent configs pick
-# up the new token + URL. The wrapper reads AI_MEMORY_AUTH_TOKEN
-# from your env and embeds it in the generated config.
+# up the new token + URL.
ai-memory install-mcp --client claude-code --apply \
- --server-url "http://192.168.0.90:49374/mcp"
+ --server-url "http://192.168.0.90:49374/mcp" \
+ --auth-token "$TOKEN"
ai-memory install-hooks --agent claude-code --apply \
- --server-url "http://192.168.0.90:49374"
+ --server-url "http://192.168.0.90:49374" \
+ --auth-token "$TOKEN"
```
When the server has `AI_MEMORY_AUTH_TOKEN` set, every request to
`/mcp`, `/hook`, `/handoff`, `/admin/*`, and `/web/*` must present
-the token. For HTTP clients (MCP, hooks, CLI) that means the
-`Authorization: Bearer <token>` header. For the `/web/*` browser
-flow it's HTTP Basic auth (the browser shows a native dialog;
-username is ignored, paste the token as the password). Constant-time
-token comparison via `subtle::ConstantTimeEq` rules out timing-based
-recovery.
+the token. HTTP clients (MCP, hooks, CLI) send an
+`Authorization: Bearer <token>` header; the `/web/*` browser flow
+uses HTTP Basic auth (see below). Token comparison uses
+`subtle::ConstantTimeEq` to rule out timing-based recovery.
When the server has **no** `AI_MEMORY_AUTH_TOKEN` set AND binds to a
non-loopback address, it logs a loud `warn` on startup. That's the
@@ -225,6 +209,70 @@ signal to either lock the bind back to `127.0.0.1` or set a token.
See [`docs/deploy.md`](docs/deploy.md) for the full homelab pattern
(bearer + TLS via cloudflared + reverse proxy).
+### DNS-rebinding guard (`AI_MEMORY_ALLOWED_HOSTS`)
+
+Any non-loopback bind also needs `AI_MEMORY_ALLOWED_HOSTS` set to the
+host/IP the clients will use, otherwise the rmcp server rejects
+external `Host` headers with 403:
+
+```bash
+-e AI_MEMORY_ALLOWED_HOSTS="<server-ip>,localhost,127.0.0.1"
+```
+
+Clients hitting the server by IP or hostname will be accepted;
+requests with an unrecognised `Host` are refused. This guards against
+DNS-rebinding attacks where a malicious page tricks the browser into
+sending requests to the server using a different hostname.
+
+### Browser access to `/web`
+
+When the server has **no** bearer token set, visit
+`http://<host>:49374/web` in any browser — no prompt.
+
+When `AI_MEMORY_AUTH_TOKEN` is set, the browser shows a native HTTP
+Basic dialog on first visit. Leave the username blank (or any value)
+and paste the token as the password. The server sets a cookie that
+persists for 30 days so subsequent navigation doesn't re-prompt.
+
+Browsers cannot pass a Bearer header in normal navigation, which is
+why the `/web` routes use HTTP Basic rather than Bearer. MCP and hook
+clients continue to use `Authorization: Bearer <token>`.
+
+## Configuring the CLI
+
+The `ai-memory` binary is a thin HTTP client. It never opens the
+wiki or SQLite directly — every state-touching command goes through
+the running server, which is the sole writer.
+
+Configuration is two environment variables, both **optional**:
+
+| Variable | Default | When to set it |
+|---|---|---|
+| `AI_MEMORY_SERVER_URL` | `http://127.0.0.1:49374` | When the server runs somewhere other than this machine (e.g. a homelab at `http://192.168.0.90:49374`). |
+| `AI_MEMORY_AUTH_TOKEN` | unset (no auth) | When the server has bearer auth enabled — see [Security](#security). |
+
+For the **single-laptop local case** (scenarios A/B) you don't need
+either env var: the CLI talks to the loopback server and just works.
+Scenario B (loopback + token) only requires `AI_MEMORY_AUTH_TOKEN` in
+the env.
+
+For a **remote / homelab** server (scenarios C/D), set both in your
+shell rc (or a `.envrc` if you use direnv):
+
+```bash
+export AI_MEMORY_SERVER_URL="http://192.168.0.90:49374"
+export AI_MEMORY_AUTH_TOKEN="b9a5075d…" # only when server has auth enabled
+```
+
+Explicit flags (`--auth-token`, `--server-url`) on `install-mcp` /
+`install-hooks` override env vars when both are set — useful when
+you're generating configs for a client that talks to a different
+server than the CLI default.
+
+The `init`, `serve`, `install-*`, `generate-auth-token`, and
+`setup-agent` subcommands don't need these env vars — they either
+set up local files or start the server itself.
+
## How it works in practice
You mostly don't think about it. Hooks capture every prompt + tool
@@ -314,10 +362,12 @@ ai-memory serve --transport http --bind 127.0.0.1:49374 --enable-web
```
The web routes are mounted at `/web` on the same axum server as the
-MCP endpoint, so the bearer-auth posture is identical (set
-`AI_MEMORY_AUTH_TOKEN` and pass `Authorization: Bearer …` from the
-browser, or front the server with a reverse proxy that handles its
-own auth, or keep the bind loopback-only).
+MCP endpoint. When the server has bearer auth enabled, the browser
+shows a native HTTP Basic dialog on first visit — leave the username
+blank (or any value) and paste the token as the password; the cookie
+persists for 30 days so subsequent navigation doesn't re-prompt.
+Loopback-bound servers with no token need no credentials at all. See
+[Security → Browser access to /web](#browser-access-to-web) above.
### Rules vs facts — ai-memory tells you when something belongs in CLAUDE.md
@@ -449,17 +499,8 @@ AI_MEMORY_LLM_MODEL=qwen3:32b
LLM_API_KEY=ollama-local # any non-empty value; Ollama doesn't validate
```
-If you bind ai-memory to a non-loopback address so Claude
-Code on a different machine can reach it, also set:
-
-```bash
-AI_MEMORY_ALLOWED_HOSTS=<your-host-or-ip>,localhost,127.0.0.1
-```
-
-(Without this rmcp's DNS-rebinding guard rejects external
-`Host` headers with 403. See
-[`docs/llm-provider-comparison.md`](docs/llm-provider-comparison.md)
-for the discovery story.)
+If you bind ai-memory to a non-loopback address, also set
+`AI_MEMORY_ALLOWED_HOSTS` — see [Security → DNS-rebinding guard](#dns-rebinding-guard-ai_memory_allowed_hosts).
### What we don't recommend
@@ -536,7 +577,7 @@ data-flow diagram + crate breakdown + cross-cutting invariants.
| File | What it is |
|---|---|
-| [`docs/install.md`](docs/install.md) | **Installation cookbook.** Every agent CLI, every alternative (curl, source build, no-docker, no-auth). Read after the Quick start if your setup doesn't match the happy path. |
+| [`docs/install.md`](docs/install.md) | **Installation cookbook.** Every agent CLI, every alternative (curl, source build, no-docker, no-auth), and the server-on-a-different-machine (homelab/LAN) walkthrough. Read after the Quick start if your setup doesn't match the happy path. |
| [`docs/mcp-install.md`](docs/mcp-install.md) | Per-client MCP config snippets (Cursor, Claude Desktop, Gemini CLI, OpenClaw, pi). |
| [`docs/deploy.md`](docs/deploy.md) | Homelab deploy: bin/deploy, bearer-token auth, TLS via cloudflared. |
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Operational summary: data flow, crate layout, cross-cutting invariants, schema. |
diff --git a/docs/deploy.md b/docs/deploy.md
index c13e85ef..5f3420b6 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -139,10 +139,16 @@ alternatives:
| Provider | Model | Approx. cost / consolidation | Notes |
|---|---|---|---|
+| anthropic | `claude-haiku-4-5` | ~$0.02 | **Recommended default.** Best balance of speed, restraint, and classification quality. Not a reasoning model. |
| openai-compat (OpenRouter) | `moonshotai/kimi-k2.6` | ~$0.013 | Reasoning model; latency ~2-3 min per consolidation. Fine because consolidation is fire-and-forget. |
-| anthropic | `claude-sonnet-4-6` | ~$0.02 | Faster (~15s), not a reasoning model. Smarter on average but more expensive. |
-| openai | `gpt-4o-mini` | ~$0.002 | Cheapest mainstream option. Decent quality. |
-| openai-compat (Ollama) | `qwen2.5-coder:14b` | $0 | Self-hosted. Set `AI_MEMORY_LLM_BASE_URL=http://host.docker.internal:11434/v1`. Quality depends on the model. |
+| openai | `gpt-5.4-mini` | ~$0.002 | Cheaper, faster alternative. Decent quality. |
+| openai-compat (Ollama) | `qwen3:32b` | $0 | Self-hosted. Set `AI_MEMORY_LLM_BASE_URL=http://host.docker.internal:11434/v1`. Quality depends on the model. |
+
+> **What we don't recommend:** reasoning-mode models (Kimi-K2.6 in reasoning mode,
+> Claude with extended thinking, GPT-o3, Gemini "thinking" variants) — they burn
+> token budget on internal reasoning before emitting output and hang or emit empty
+> responses with the strict-JSON consolidation prompt. If you must use one, turn
+> reasoning off.
ai-memory's consolidator uses OpenAI's `json_schema` strict mode for
structured output. Most modern models honour this, but if you switch
diff --git a/docs/install.md b/docs/install.md
index 0d1011f7..50e6c4fc 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -3,6 +3,8 @@
The [README quick-start](../README.md#quick-start) covers the happy
path (docker + Claude Code). This page covers everything else:
+- [Server on a different machine](#server-on-a-different-machine)
+ (homelab, LAN box, remote server)
- [Configuring other agent CLIs](#configuring-other-agent-clis)
(Codex, OpenCode, Cursor, Claude Desktop, Gemini CLI, OpenClaw, pi)
- [Installing hooks without docker](#installing-hooks-without-docker)
@@ -23,8 +25,54 @@ path (docker + Claude Code). This page covers everything else:
---
+## Server on a different machine
+
+When the ai-memory server runs on a LAN box (homelab, headless server)
+and you use Claude Code / Codex / etc. on a laptop:
+
+### Server side (the homelab host)
+
+```bash
+docker run -d --name ai-memory \
+ --restart unless-stopped \
+ -p 0.0.0.0:49374:49374 \
+ -v ai-memory-data:/data \
+ -e AI_MEMORY_AUTH_TOKEN="$TOKEN" \
+ -e AI_MEMORY_ALLOWED_HOSTS="<server-ip>,localhost,127.0.0.1" \
+ -e AI_MEMORY_LLM_PROVIDER=anthropic \
+ -e ANTHROPIC_API_KEY=sk-ant-... \
+ akitaonrails/ai-memory:latest
+```
+
+See [Security](../README.md#security) in the README for why
+`AI_MEMORY_AUTH_TOKEN` and `AI_MEMORY_ALLOWED_HOSTS` are both
+required for any non-loopback bind.
+
+### Client side (the laptop)
+
+```bash
+export AI_MEMORY_SERVER_URL="http://<server-ip>:49374"
+export AI_MEMORY_AUTH_TOKEN="$TOKEN"
+
+ai-memory install-mcp --client claude-code --apply \
+ --server-url "http://<server-ip>:49374/mcp"
+ai-memory install-hooks --agent claude-code --apply \
+ --server-url "http://<server-ip>:49374"
+```
+
+The CLI commands (`bootstrap`, `status`, `search`, `lint`, etc.) inherit the
+two env vars automatically.
+
+---
+
## Configuring other agent CLIs
+> `install-mcp --server-url` takes the MCP endpoint **including** `/mcp`
+> (e.g. `http://homelab:49374/mcp`) — the rendered client config expects the
+> full MCP URL. `install-hooks --server-url` takes the bare server **origin**
+> (e.g. `http://homelab:49374`) — hook scripts append `/hook`, `/handoff`,
+> etc. themselves.
+
Each agent CLI needs two things:
1. **MCP registration** — so the agent can call `memory_query`,
@@ -169,6 +217,10 @@ This path is friction-free when:
## Running ai-memory without docker
+Most users should stick to the docker wrapper from the Quick start. Build from
+source only when hacking on ai-memory itself or running on a platform docker
+doesn't support.
+
```bash
git clone https://github.com/akitaonrails/ai-memory ~/.ai-memory
cd ~/.ai-memory
@@ -211,11 +263,16 @@ If you set only the provider, ai-memory picks a sensible default:
| Setting | Default | Why |
|---|---|---|
-| `AI_MEMORY_LLM_PROVIDER=anthropic` | `claude-sonnet-4-6` | Smart enough to summarise; cheap enough to run on every session-end. Not a reasoning model. |
-| `AI_MEMORY_LLM_PROVIDER=openai` | `gpt-4o-mini` | OpenAI equivalent to the Sonnet tier in price/quality. |
+| `AI_MEMORY_LLM_PROVIDER=anthropic` | `claude-haiku-4-5` | **Recommended default.** Best balance of speed, restraint, and classification quality. Not a reasoning model. Consistently classifies durable project rules as `kind: rule`. |
+| `AI_MEMORY_LLM_PROVIDER=openai` | `gpt-5.4-mini` | Cheaper + faster alternative. Same parse reliability; mild over-classification on thin sessions. |
| `AI_MEMORY_EMBEDDING_PROVIDER=openai` | `text-embedding-3-small` (1536-dim) | 5× cheaper than `-3-large` with marginal recall loss. |
| `AI_MEMORY_EMBEDDING_PROVIDER=voyage` | `voyage-3` (1024-dim) | Voyage's current general-purpose recommendation. |
+> **What we don't recommend:** reasoning-mode models (Claude with extended
+> thinking, GPT-o3, Gemini "thinking" variants) — they burn token budget on
+> internal reasoning and hang or emit empty responses with the strict-JSON
+> consolidation prompt. Turn reasoning off if you must use one.
+
### Self-hosted LLMs (Ollama / vLLM / LM Studio / OpenRouter)
```bash
@@ -374,21 +431,12 @@ critical pairing — **no bearer token AND loopback only** is the only
safe combination. The startup log will warn loudly if you bind to a
LAN address without setting `AI_MEMORY_AUTH_TOKEN`.
-Then register the agent CLI without the `Authorization` header:
+Then wire up the agent CLI. Both commands default to no auth and
+`http://127.0.0.1:49374` — no extra flags needed for the local case:
```bash
-claude mcp add --transport http ai-memory http://localhost:49374/mcp
-```
-
-And register hooks without `--auth-token`:
-
-```bash
-docker run --rm -v "$HOME/.ai-memory:/host" \
- akitaonrails/ai-memory:latest \
- setup-agent --agent claude-code \
- --to /host/hooks \
- --host-prefix "$HOME/.ai-memory/hooks" \
- --server-url "http://localhost:49374"
+ai-memory install-mcp --client claude-code --apply
+ai-memory install-hooks --agent claude-code --apply
```
---
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index 9e1e33e5..c9e61460 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -1,5 +1,10 @@
# MCP install guide — additional clients
+> 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
+> is enabled. The MCP wire protocol expects the `/mcp` path suffix on the URL.
+
This page documents how to register ai-memory as an MCP server with
the agent CLIs **that are not covered inline in the README**.