Skip to content

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

Rust

fix(hooks): complete marker routing and docs

AkitaOnRails7cd18f20d62e
diff --git a/AGENTS.md b/AGENTS.md
index 503e1e6a..d49dc7a9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -63,3 +63,37 @@ without disturbing the rest of the file.
- When a change affects user-visible behavior, installation, supported
platforms, supported agents, providers, or deployment, update
`CHANGELOG.md` and the README/docs support references in the same commit.
+
+## Rust Engineering Rules
+
+- Prefer small, behavior-preserving changes. Do not add compatibility
+ branches, new abstractions, or new public surface unless a shipped caller,
+ persisted data, or explicit requirement needs them.
+- Optimize the real bottleneck class first: algorithm, query shape, batching,
+ allocation count, IO boundaries, and container choice. Avoid clever
+ micro-optimizations without evidence.
+- Keep SQLite writes behind the single writer actor. For hot paths, batch work
+ into one command/transaction instead of spawning many writer messages or
+ opening per-row transactions.
+- Avoid N+1 store reads. Prefer reader methods that return the data shape the
+ caller actually needs, and use cached/prepared statements for repeated
+ queries.
+- Keep hook ingestion fire-and-forget and bounded. Do not introduce unbounded
+ `tokio::spawn` fan-out, unbounded queues, or synchronous agent-facing waits.
+- Keep CLI commands thin: parse arguments, resolve config once, call typed
+ library functions, render output. Provider-specific behavior belongs in the
+ provider module, not in command handlers.
+- Treat typed boundaries as load-bearing: IDs, `PagePath`, `AgentKind`,
+ sanitization, workspace/project resolution, and provider dialects should be
+ parsed or normalized once and reused.
+- Prefer explicit fallbacks over `unwrap`, `expect`, or `unreachable!` in
+ runtime paths. Panics are acceptable in tests only.
+- Do not use `unsafe` for performance work in this project unless profiling
+ proves it is necessary and the safety argument is documented in the code.
+- Add focused regression tests for bug fixes and behavior changes. For
+ filesystem tests, use temp dirs or injected roots; never depend on the real
+ user home directory being writable.
+- Run the full local gate before claiming a Rust change is ready:
+ `cargo fmt --check`, `git diff --check`,
+ `TAILWIND_SKIP=1 cargo test --workspace`, and
+ `TAILWIND_SKIP=1 cargo clippy --workspace --all-targets -- -D warnings`.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 86764499..6375168f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -57,6 +57,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Docker images now bundle both POSIX and PowerShell hook scripts.
### Fixed
+- Marker-file routing now reaches the generated OpenCode and OMP
+ TypeScript hook integrations, not only the POSIX/PowerShell script
+ hooks. POSIX helpers also preserve the outer hook `cwd` when nested
+ tool payloads contain their own `cwd`, and encode `+` correctly in
+ marker-derived query parameters.
- `backup --to` now streams the tarball to disk instead of buffering the full
archive in CLI memory.
- Hyphenated FTS5 queries such as `ai-memory` are normalized safely instead of
diff --git a/README.md b/README.md
index 662b72ec..45acac1c 100644
--- a/README.md
+++ b/README.md
@@ -174,589 +174,144 @@ write. The hook scripts are staged into
overwrites them so future image updates ship updated hooks. Drop
`--apply` to print the snippet instead of mutating.
-### Windows Status
-
-Windows support has two separate modes. If your agent runs inside WSL2,
-use the Linux quick start inside WSL2. If your agent runs as a native
-Windows process, use the PowerShell wrapper and `.ps1` hooks. Do not mix
-the two path worlds. See [`docs/windows.md`](docs/windows.md) for the
-native Windows, WSL2, and current real-world testing notes.
-
-> **Prefer docker compose?** Clone the repo and run
-> `docker compose -f docker/docker-compose.yml up -d` instead of
-> step 2. The bundled compose file already has
-> `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
-a one-line warning to stderr when a newer image is available. To
-upgrade:
-
-```bash
-ai-memory upgrade
-```
-
-In order: (1) self-upgrades the wrapper script itself by re-fetching
-`bin/ai-memory` from GitHub (validated against the shebang; falls
-back gracefully if curl is missing or perms block the in-place
-replacement), (2) `docker pull`s the latest image, (3) re-stages
-hook scripts under `~/.local/share/ai-memory/hooks/<agent>/` for
-every agent you've configured, and (4) tells you how to restart the
-server container so the new binary is picked up. The hook refresh
-is idempotent - re-running `install-hooks --apply` replaces the
-seven keys ai-memory owns and leaves every other hook the user has
-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).
-
-After the upgraded server starts, ai-memory applies SQLite schema
-migrations automatically (`Store::open`) and runs pending wiki-structure
-migrations before the watcher starts. No manual database reset or wiki
-rewrite is required for normal upgrades; derived indexes such as FTS
-tables are rebuilt/backfilled by migrations or the watcher reconciliation
-path.
-
-> **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
-> `/var/run/docker.sock` is already passed through. Run the
-> `install-*` commands *outside* ai-jail (they need to write to
-> `~/.local/share/ai-memory/hooks/`, which the sandbox keeps
-> read-only); daily use from inside the sandbox needs no binary at
-> all (agents reach ai-memory over MCP).
-
-**For everything else** - Codex, OpenCode, OMP, Cursor, Claude Desktop,
-Gemini CLI, OpenClaw, the curl-based hook installer (no docker
-needed), running ai-memory without docker, the full subcommand
-reference, the homelab deploy pattern, security hardening - see
-[**`docs/install.md`**](docs/install.md).
+### Install Notes
+
+- **Windows:** use the Linux path inside WSL2, or the native PowerShell
+ wrapper and `.ps1` hooks for native Windows agents. Do not mix path
+ worlds. See [`docs/windows.md`](docs/windows.md).
+- **Docker compose:** `docker compose -f docker/docker-compose.yml up -d`
+ is supported; agent setup is the same as step 3 above.
+- **Remote server:** set `AI_MEMORY_SERVER_URL=http://<server-ip>:49374`
+ on the client and pass matching `--server-url` flags when installing
+ MCP/hooks. Any non-loopback server should use bearer auth.
+- **Upgrades:** run `ai-memory upgrade` to refresh the wrapper, image,
+ and staged hook scripts. Redeploy remote servers separately.
+
+For Codex, OpenCode, OMP, Cursor, Claude Desktop, Gemini CLI, OpenClaw,
+curl-based hook installs, source builds, CLI env vars, and the full
+subcommand reference, see [`docs/install.md`](docs/install.md).
## Security
-The default Quick start runs **without authentication** because the
-server is bound to loopback (`127.0.0.1:49374`) - no process outside
-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.
-
-### When you need bearer auth
-
-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.
+Loopback-only (`127.0.0.1:49374`) with no auth is the default because
+it is safe for a single-user laptop: no process outside the machine can
+reach the server.
-### Enabling bearer auth (turn-key recipe)
+Enable bearer auth when the server is exposed beyond loopback, when
+untrusted local processes share the machine, or when the data dir holds
+sensitive project history:
```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. 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 \
-v ai-memory-data:/data \
-e AI_MEMORY_AUTH_TOKEN="$TOKEN" \
- -e AI_MEMORY_LLM_PROVIDER=anthropic \
- -e ANTHROPIC_API_KEY=sk-ant-... \
+ -e AI_MEMORY_ALLOWED_HOSTS="<server-ip>,localhost,127.0.0.1" \
akitaonrails/ai-memory:latest
-# 3. Set the same token in every client environment that needs to
-# reach this server:
-export AI_MEMORY_AUTH_TOKEN="$TOKEN"
-
-# 4. Re-run install-mcp / install-hooks so the agent configs pick
-# up the new token + URL.
ai-memory install-mcp --client claude-code --apply \
- --server-url "http://192.168.0.90:49374/mcp" \
- --auth-token "$TOKEN"
+ --server-url "http://<server-ip>:49374/mcp" --auth-token "$TOKEN"
ai-memory install-hooks --agent claude-code --apply \
- --server-url "http://192.168.0.90:49374" \
- --auth-token "$TOKEN"
+ --server-url "http://<server-ip>: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. 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
-signal to either lock the bind back to `127.0.0.1` or set a token.
+Bearer auth protects `/mcp`, `/hook`, `/handoff`, `/admin/*`, and
+`/web/*`. Browser access to `/web` uses HTTP Basic auth with the token
+as the password. Non-loopback binds should also set
+`AI_MEMORY_ALLOWED_HOSTS` to guard against DNS rebinding.
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 HTTP server rejects
-external `Host` headers with 403 before they reach `/mcp`, `/hook`,
-`/handoff`, `/admin/*`, or `/web/*`:
-
-```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
-call + session boundary automatically. The agent gains awareness of
-prior work without you typing anything special. A few patterns are
-worth knowing:
-
-### Cross-agent handoff
-
-```
-$ claude
-> "Working on the auth refactor. JWT rotation story is broken; trying
- session cookies as an alternative."
-[work for an hour]
-> /exit
-
-$ codex # in the same directory, hours or days later
-[SessionStart hook fetches the handoff; the next agent sees it.]
-> "Picking up: you were investigating session cookies as an
- alternative to broken JWT rotation. Continuing?"
-```
-
-You did nothing special. Handoff created automatically on Claude
-Code's session-end, surfaced automatically on Codex's session-start.
+with bearer auth, host allowlisting, and TLS/reverse-proxy options.
-### Compaction recovery
+## Using Memory
-When Claude Code or Codex compact their working context, the
-`PreCompact` hook fires and ai-memory writes a fresh
-`sessions/<id>.md` page summarising the session so far. After
-compaction, the agent can recover the summary via `memory_recent`
-even though its raw history is gone.
+Day to day, you mostly do not think about ai-memory. Lifecycle hooks
+capture prompts, tool calls, compaction checkpoints, and session
+boundaries. SessionStart hooks fetch pending handoffs before your first
+prompt in the next agent.
-### Adopting ai-memory mid-project: bootstrap
+Useful entry points:
-If you're installing ai-memory in a project you've been working on
-for months, the wiki starts empty and the first few sessions are
-net-zero - you're populating, not retrieving. `ai-memory bootstrap`
-solves that by LLM-summarising your existing `git log`, README,
-`docs/`, and module-level doc-comments into seed wiki pages.
+- Ask "where did we leave off?" to continue from the pending handoff.
+- Ask "have we discussed X?" or "search memory for Y" to query the wiki.
+- Ask "catch me up" for a prose digest of recent project activity.
+- Run `ai-memory bootstrap` once when adopting ai-memory in an existing
+ project with months of history.
+- Start the server with `--enable-web` and visit `/web` for a read-only
+ browser view of the markdown wiki.
-```bash
-# Run from your project's repo root. The CLI collects sources locally
-# (git log, README, docs/, module headers) and POSTs them to the server
-# at AI_MEMORY_SERVER_URL, where the LLM call and wiki writes happen.
-# Requires an LLM provider configured on the server. Budget caps at
-# 50k input tokens (~$0.05 with Claude Haiku 4.5).
-export AI_MEMORY_SERVER_URL="http://localhost:49374"
-ai-memory bootstrap
-```
-
-The workspace defaults to `default` and the project defaults to the
-current directory's basename - that's almost always what you want, so
-omit `--workspace` / `--project` unless you're deliberately overriding.
-
-Bootstrap produces a per-project `bootstrap.md` manifest (under
-`<wiki>/<workspace>/<project>/`) listing every page generated + a
-one-paragraph rationale. Run with `--dry-run` first to preview which
-sources would be sent without paying for the LLM call. Re-running on
-the same project requires `--force`.
-
-See [`docs/install.md`](docs/install.md#bootstrap-mid-project) for
-the full flag reference + per-source priority order.
-
-### Spelunking your own history
+Install the routing snippet once so agents proactively call the right
+MCP tool for those prompts:
```bash
-docker exec ai-memory ls /data/wiki/sessions/
-docker exec ai-memory cat /data/wiki/sessions/<uuid>.md
-
-# Open in Obsidian / any markdown viewer:
-docker cp ai-memory:/data/wiki ./my-ai-memory-wiki
-
-# Time-travel:
-docker exec ai-memory git -C /data/wiki log --oneline
+ai-memory install-instructions
```
-### Browse the wiki in a browser
+See [`docs/usage.md`](docs/usage.md) for handoff examples, proactive
+query routing, bootstrap details, web UI screenshots, and the raw-wiki
+inspection commands. CLI URL/auth configuration lives in
+[`docs/install.md`](docs/install.md#configuring-the-cli-url-and-auth).
-For a more navigable view, start the server with `--enable-web` and
-open `http://<host>:49374/web` in any browser. Project-list homepage,
-per-project page tree with breadcrumbs, rendered markdown with syntax
-highlighting and metadata (tier, kind, pinned, supersedes chain),
-plus FTS5 search - all read-only, no editing. Light/dark theme
-follows your OS setting via `prefers-color-scheme`.
+## LLM Providers
-![Project list homepage with the LLM-optimised banner; four projects (distrobox-gaming, ai-memory, nes-to-sms, .config) shown as cards with page counts + last activity.](docs/web-projects-home.png)
+ai-memory runs without an LLM: hooks still capture sessions, search uses
+FTS5, and summaries fall back to rule-based output. Add an LLM provider
+when you want session-end consolidation, richer linting, and bootstrap.
-Drill into any project for the folder tree (`concepts/`, `decisions/`,
-`gotchas/`, `sessions/`) and the recent-activity column:
+Recommended defaults:
-![distrobox-gaming project view: left sidebar shows the folder tree grouped by kind; right column lists recent pages with kind badges and relative timestamps.](docs/web-project-view.png)
-
-```bash
-ai-memory serve --transport http --bind 127.0.0.1:49374 --enable-web
-# or, if you run via docker compose, add it to the command line in
-# docker-compose.yml: ["serve", "--transport", "http", "--bind",
-# "0.0.0.0:49374", "--enable-web"]
-```
-
-The web routes are mounted at `/web` on the same axum server as the
-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
-
-When you type something like "don't forget to never add a function
-without a unit test", that's a **durable project rule**, not a
-session-level observation. Rules need to fire on every relevant
-action - that's what your project's `CLAUDE.md` / `AGENTS.md` is for
-(it's loaded into the agent's system prompt every turn), while
-ai-memory queries only fire when the agent thinks to call them.
-
-The consolidator now classifies each compiled observation as
-`decision | fact | rule | gotcha`. Rule-tagged pages are auto-routed
-to `wiki/_rules/<slug>.md`, and the next time you run `memory_lint`
-the agent sees a suggestion:
-
-> **rule_suggestion**: Page `_rules/never-ship-code-without-test.md`
-> looks like a durable project rule. Consider copying it into your
-> project's CLAUDE.md / AGENTS.md so the agent sees it on every
-> turn, not just when it remembers to call memory_query.
-
-ai-memory never edits your `CLAUDE.md` itself - the suggestion is
-the whole UX. You copy what's useful, ignore what isn't.
-
-### When the agent reaches for memory
-
-Hooks handle *capture* (every prompt + tool call + session boundary)
-and *handoff resume* (SessionStart auto-fetches pending handoffs)
-without you typing anything. **Proactive querying** - the agent
-reaching into the wiki on its own - depends on the agent knowing
-*when* to call which tool. Concrete patterns once the routing
-snippet is installed (see "Nudge the agent" below):
-
-| You say… | Agent calls… | Effect |
+| Provider | Default | Use when |
|---|---|---|
-| "Have we discussed X?" / "search memory for Y" | `memory_query` | FTS5 + link-neighbour RRF over compiled wiki pages, optional vector RRF, and bounded raw observation fallback when pages miss. |
-| (before proposing architecture) implicit | `memory_query` | The routing snippet tells the agent to check prior decisions / gotchas before proposing anything, so you don't get contradicted-by-its-own-history suggestions. |
-| "Catch me up" / "I've been away" | `memory_explore` | Prose digest. Verbosity auto-scales to time-since-last-activity: < 1 h → one line, > 30 days → full catchup. |
-| "Where did we leave off?" | (handoff already prepended) | SessionStart hook already prepended the handoff before your first prompt; the agent just reads from that block. |
-| "Save context for the next session" | `memory_handoff_begin` | Writes a terse handoff with `open_questions` + `next_steps` for whichever agent opens this project next. |
-| "Consolidate this session" | `memory_consolidate` | Manual trigger of what session-end normally does automatically (compile observations into wiki pages). |
-| "Audit the wiki" / "any contradictions?" | `memory_lint` | Runs the stale-page / contradiction / rule-suggestion pass. |
-| "How big is the wiki?" / "stats?" | `memory_status`, `memory_briefing` | Counts + recent activity windows. |
-
-The mapping is in the [routing snippet](#nudge-the-agent-to-use-memory-proactively)
-the next section installs.
-
-### Nudge the agent to *use* memory proactively
-
-The capture side works automatically. For the *query* side, the
-agent needs a routing table in the project's rules file
-(`CLAUDE.md` for Claude Code; `AGENTS.md` for Codex / OpenCode /
-Cursor / Gemini CLI). Two ways to install it - pick whichever's
-easier in the moment:
+| `anthropic` | `claude-haiku-4-5` | Best default for consolidation quality and rule classification. |
+| `openai` | `gpt-5.4-mini` | Cheaper and faster hosted option. |
+| `gemini` | `gemini-2.5-flash` | Google-hosted option with a generous free tier. |
+| `openai-compat` | no default | OpenRouter, Ollama, vLLM, LM Studio, and other compatible endpoints. |
-**From the agent** (no terminal needed):
+Embeddings are optional and separate from the LLM provider. Set
+`AI_MEMORY_EMBEDDING_PROVIDER=openai` or `voyage` when you want vector
+reranking in addition to FTS5 + graph-neighbor retrieval.
-> "Install ai-memory routing into this project."
-
-The agent calls the `memory_install_self_routing` MCP tool, gets
-back the canonical snippet + a per-agent filename map, then uses
-its own Write/Edit tool to land the block in the right rules file
-(Claude Code → CLAUDE.md, everyone else → AGENTS.md). Idempotent:
-the block is wrapped in `<!-- ai-memory:start -->` /
-`<!-- ai-memory:end -->` markers so the agent replaces in place on
-re-runs.
-
-**From the terminal**:
-
-```bash
-ai-memory install-instructions # auto-detects CLAUDE.md vs AGENTS.md
-ai-memory install-instructions --target AGENTS.md # force a specific file
-ai-memory install-instructions --print # preview without writing
-```
-
-The CLI's auto-detect: if `$PWD/CLAUDE.md` exists, extend that;
-if `$PWD/AGENTS.md` exists, extend that; if both exist, write to
-both (multi-agent project - keep both files in sync); if neither
-exists, create `CLAUDE.md` and print a hint about `--target
-AGENTS.md` for non-Claude agents.
-
-Both paths produce the same block. Both replace existing markered
-blocks in place rather than duplicating, so you can re-run safely
-whenever the snippet evolves (e.g. when a new MCP tool ships).
-
-## LLM provider - recommended defaults
-
-You can run ai-memory entirely without an LLM (FTS5 search +
-rule-based summaries, $0). When you *do* configure one, the
-options below are ranked by fitness for ai-memory's
-consolidation workload - see
+See [`docs/install.md#llm-provider-tiers`](docs/install.md#llm-provider-tiers)
+for env vars and Ollama/OpenRouter examples, and
[`docs/llm-provider-comparison.md`](docs/llm-provider-comparison.md)
-for the empirical writeup behind this ranking.
-
-> **TL;DR.** Use **Claude Haiku 4.5** as your default. Switch
-> to **GPT-5.4-mini** if you want the same quality cheaper +
-> faster. Switch to **qwen3:32b on Ollama** if you have a
-> local LLM server and prefer $0 / fully-self-hosted. The
-> three are interchangeable; pick once and forget.
-
-### Option 1 - Claude Haiku 4.5 *(recommended default)*
-
-Best balance of speed (~7 s), restraint, and classification
-quality. The only model that consistently classifies durable
-project rules as `kind: rule` so the consolidator auto-routes
-them to `_rules/<slug>.md`. ~$0.02 per consolidation; cost
-is negligible for personal use.
-
-```bash
-AI_MEMORY_LLM_PROVIDER=anthropic
-AI_MEMORY_LLM_MODEL=claude-haiku-4-5
-ANTHROPIC_API_KEY=sk-ant-…
-```
+for the empirical model comparison.
-Or via OpenRouter (handy if you already have an OpenRouter
-account and want one bill):
+## Architecture
-```bash
-AI_MEMORY_LLM_PROVIDER=openai-compat
-AI_MEMORY_LLM_BASE_URL=https://openrouter.ai/api/v1
-AI_MEMORY_LLM_MODEL=anthropic/claude-haiku-4.5
-LLM_API_KEY=sk-or-v1-…
-```
-
-### Option 2 - OpenAI GPT-5.4-mini *(cheaper alternative)*
-
-~5× cheaper than Haiku, ~2× faster (~4 s avg). Same parse
-reliability, same faithfulness. One known weakness: mild
-over-classification on trivial sessions (will sometimes
-manufacture an extra `decisions/` page for a thin
-session). Acceptable for most users.
-
-```bash
-AI_MEMORY_LLM_PROVIDER=openai
-AI_MEMORY_LLM_MODEL=gpt-5.4-mini
-OPENAI_API_KEY=sk-…
-```
-
-Or via OpenRouter:
+One Rust binary runs an MCP/HTTP server and owns one data directory:
-```bash
-AI_MEMORY_LLM_PROVIDER=openai-compat
-AI_MEMORY_LLM_BASE_URL=https://openrouter.ai/api/v1
-AI_MEMORY_LLM_MODEL=openai/gpt-5.4-mini
-LLM_API_KEY=sk-or-v1-…
-```
-
-### Option 3 - Google Gemini 2.5 Flash *(generous free tier)*
-
-Hosted by Google, with a free tier that's enough for most
-personal consolidation loads. Structured-output is native
-(`responseSchema` over OpenAPI 3 subset); the client inlines
-`$ref`s and strips Draft-2020-12 keywords Gemini rejects, so
-schemars-derived schemas just work. Use `gemini-2.5-flash`
-for the speed/cost balance; avoid the *-thinking* variants
-(see "What we don't recommend" below).
-
-Grab a key from https://aistudio.google.com/apikey, then:
-
-```bash
-AI_MEMORY_LLM_PROVIDER=gemini
-AI_MEMORY_LLM_MODEL=gemini-2.5-flash # optional; this is the default
-GEMINI_API_KEY=AIza… # GOOGLE_API_KEY also accepted
-```
-
-### Option 4 - Local Ollama qwen3:32b *(free / self-hosted)*
-
-$0 per consolidation. Requires a machine with at least ~24 GB
-of unified or VRAM memory to keep the Q4_K_M weights warm
-(~20 GB) plus headroom. Strix Halo / Apple Silicon / a
-recent NVIDIA card all work. Latency is ~90 s but
-consolidation is a background job - users never see it.
-
-One-time setup on the Ollama host:
-
-```bash
-ollama pull qwen3:32b
-ollama pull nomic-embed-text # for embeddings; see below
-# Recommended Ollama env:
-# OLLAMA_KEEP_ALIVE=20m (keep models warm between consolidations)
-# OLLAMA_FLASH_ATTENTION=1
-# OLLAMA_KV_CACHE_TYPE=q8_0 (halves KV memory)
-```
-
-ai-memory env:
-
-```bash
-AI_MEMORY_LLM_PROVIDER=openai-compat
-AI_MEMORY_LLM_BASE_URL=http://<ollama-host>:11434/v1
-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, also set
-`AI_MEMORY_ALLOWED_HOSTS` - see [Security → DNS-rebinding guard](#dns-rebinding-guard-ai_memory_allowed_hosts).
-
-### What we don't recommend
-
-- **Claude Sonnet 4.5** - strictly dominated by Haiku for
- this task: same parse reliability, 3× cost, hallucinated
- details before the prompt was tightened. Use it only if
- you specifically need extended reasoning (e.g. cross-page
- lint sweeps).
-- **Reasoning-mode models** (Kimi-K2.6, Claude with extended
- thinking enabled, GPT-o3, Gemini "thinking" variants) -
- these models burn `max_tokens` budget on internal
- reasoning before emitting visible content; with the
- strict-JSON consolidation prompt they hang or emit empty
- responses. If you must use one, turn reasoning off.
-
-### Embedding provider
-
-The LLM provider drives consolidation + lint. Embeddings are
-a *separate* concern (hybrid retrieval over the wiki - BM25
-+ vector RRF). Defaults when `AI_MEMORY_EMBEDDING_PROVIDER`
-is set:
-
-| Provider | Default model | Dim |
-|---|---|---|
-| `openai` | `text-embedding-3-small` | 1536 |
-| `voyage` | `voyage-3` | 1024 |
-
-For the local stack, point the OpenAI embedder at Ollama:
-
-```bash
-AI_MEMORY_EMBEDDING_PROVIDER=openai
-AI_MEMORY_EMBEDDING_BASE_URL=http://<ollama-host>:11434/v1
-AI_MEMORY_EMBEDDING_MODEL=nomic-embed-text
-AI_MEMORY_EMBEDDING_DIM=768
-OPENAI_API_KEY=ollama-local
-```
-
-Skipping the embedding provider entirely is fine -
-`memory_query` still uses FTS5, link-neighbour expansion, and raw
-fallback; you just lose vector re-ranking.
-
-Per-tier feature breakdown + the openai-compat / Ollama setup
-is in [`docs/install.md`](docs/install.md#llm-provider-tiers).
-
-## Architecture in 60 seconds
-
-A single Rust binary, optionally containerised. Runs as an
-[MCP](https://modelcontextprotocol.io/) server over stdio + HTTP.
-Owns a data directory containing:
-
-```
+```text
<data_dir>/
-├── wiki/ # markdown source of truth (git-versioned)
+├── wiki/ # markdown source of truth, git-versioned
├── raw/ # immutable session log archive
-├── db/ # SQLite (FTS5 + page_embeddings) — derived index
-├── models/ # reserved for local embedding model (v0.3+)
-└── logs/ # rolling daily tracing output
+├── db/ # SQLite indexes, including FTS5 and embeddings
+├── models/ # reserved for local embedding models
+└── logs/ # rolling tracing output
```
-Agent lifecycle hooks fire-and-forget POST to the server's HTTP
-ingress. The server queues writes through a single SQLite writer
-(no `database is locked`). On session end an optional LLM-driven pass
-rewrites pages atomically with supersession (`is_latest=false` +
-`supersedes` chain) and opens a typed handoff for the next agent.
-The scheduled retention sweep decays unused episodic content while
-semantic concept pages compound forever; pinned pages and `_slots/`
-memory slots are exempt. Retrieval is FTS5 + link-neighbour RRF by
-default; when an embedder is configured, vector RRF over
-`page_embeddings` joins the ranks. If compiled wiki search misses,
-bounded raw observation FTS provides exact-detail fallback.
-
-See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the canonical
-data-flow diagram + crate breakdown + cross-cutting invariants.
+Hooks POST observations to the server. The server serializes writes
+through one SQLite writer, compiles session observations into markdown
+pages, and serves retrieval through FTS5, graph-neighbor RRF, optional
+vector RRF, and bounded raw-observation fallback.
+
+See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the data-flow
+diagram, crate breakdown, schema notes, and invariants.
## Docs
| File | What it is |
|---|---|
| [`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/usage.md`](docs/usage.md) | Handoffs, proactive memory queries, routing snippet, web UI, raw-wiki inspection, and rules-vs-facts workflow. |
+| [`docs/marker-file.md`](docs/marker-file.md) | `.ai-memory.toml` workspace/project routing for multi-client trees, mono-repos, and work/personal separation. |
| [`docs/windows.md`](docs/windows.md) | Windows install modes: full WSL2, native Windows with Docker Desktop, native source builds, and current hook/MCP harness caveats. |
| [`docs/mcp-install.md`](docs/mcp-install.md) | Per-client MCP and lifecycle notes (Cursor, Claude Desktop, Gemini CLI, OpenClaw, OMP). |
| [`docs/deploy.md`](docs/deploy.md) | Homelab deploy: bin/deploy, bearer-token auth, TLS via cloudflared. |
| [`docs/lifecycle-ops.md`](docs/lifecycle-ops.md) | **Read before running purge / rename / backup / restore / reset.** Safety matrix for the state-touching commands, per-project disk layout (how isolation actually works), and operator workflows for "fresh start", "snapshot before risky op", "drop one project". |
+| [`docs/llm-provider-comparison.md`](docs/llm-provider-comparison.md) | Empirical notes behind the recommended LLM defaults. |
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Operational summary: data flow, crate layout, cross-cutting invariants, schema. |
| [`docs/design-decisions.md`](docs/design-decisions.md) | The full v1 spec. |
| Research docs under `docs/` | Karpathy LLM Wiki notes, agentmemory / basic-memory / cognee deep-dives, lessons-learned from upstream issues. |
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index 121f9d04..4276a177 100644
--- a/crates/ai-memory-cli/src/commands/install_hooks.rs
+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs
@@ -457,6 +457,9 @@ fn build_opencode_plugin(server_url: &str, auth_token: Option<&str>) -> String {
// re-run.
import type {{ Plugin }} from "@opencode-ai/plugin";
+import {{ existsSync, readFileSync }} from "node:fs";
+import {{ dirname, join, resolve }} from "node:path";
+import {{ homedir }} from "node:os";
const SERVER = {server_literal}.replace(/\/+$/, "");
const AGENT = "open-code";
@@ -472,6 +475,42 @@ function authHeaders(): Record<string, string> {{
return TOKEN ? {{ Authorization: `Bearer ${{TOKEN}}` }} : {{}};
}}
+function findMarker(cwd: string | undefined): string | undefined {{
+ if (!cwd) return undefined;
+ let dir = resolve(cwd);
+ const home = homedir();
+ while (dir && dir !== dirname(dir)) {{
+ const marker = join(dir, ".ai-memory.toml");
+ if (existsSync(marker)) return marker;
+ if (home && dir === home) return undefined;
+ dir = dirname(dir);
+ }}
+ return undefined;
+}}
+
+function tomlKey(text: string, key: string): string | undefined {{
+ const re = new RegExp(`^\\s*${{key}}\\s*=\\s*"([^"]*)"`);
+ for (const line of text.split(/\r?\n/)) {{
+ const match = re.exec(line);
+ if (match) return match[1];
+ }}
+ return undefined;
+}}
+
+function applyMarkerParams(url: URL, cwd: string | undefined): void {{
+ const marker = findMarker(cwd);
+ if (!marker || !cwd) return;
+ url.searchParams.set("cwd", cwd);
+ try {{
+ const body = readFileSync(marker, "utf8");
+ const workspace = tomlKey(body, "workspace");
+ const project = tomlKey(body, "project");
+ if (workspace) url.searchParams.set("workspace", workspace);
+ if (project) url.searchParams.set("project", project);
+ }} catch (_e) {{
+ }}
+}}
+
function sessionID(input: unknown): string | undefined {{
const value = input as any;
return value?.sessionID ?? value?.sessionId ?? value?.session_id ?? value?.info?.id;
@@ -525,6 +564,7 @@ function postHook(event: string, payload: Record<string, unknown>): void {{
const url = new URL(`${{SERVER}}/hook`);
url.searchParams.set("event", event);
url.searchParams.set("agent", AGENT);
+ applyMarkerParams(url, typeof payload.cwd === "string" ? payload.cwd : undefined);
try {{
void fetch(url, {{
method: "POST",
@@ -541,6 +581,7 @@ async function fetchHandoff(cwd: string): Promise<string | undefined> {{
const url = new URL(`${{SERVER}}/handoff`);
url.searchParams.set("agent", AGENT);
url.searchParams.set("cwd", cwd);
+ applyMarkerParams(url, cwd);
try {{
const response = await fetch(url, {{
headers: authHeaders(),
@@ -703,6 +744,10 @@ fn build_omp_extension(server_url: &str, auth_token: Option<&str>) -> String {
// will overwrite this file (with a `.bak-<ts>` backup) on each
// re-run.
+import {{ existsSync, readFileSync }} from "node:fs";
+import {{ dirname, join, resolve }} from "node:path";
+import {{ homedir }} from "node:os";
+
const SERVER = {server_literal}.replace(/\/+$/, "");
const AGENT = "omp";
{token_line}
@@ -717,6 +762,42 @@ function authHeaders(): Record<string, string> {{
return TOKEN ? {{ Authorization: `Bearer ${{TOKEN}}` }} : {{}};
}}
+function findMarker(cwd: string | undefined): string | undefined {{
+ if (!cwd) return undefined;
+ let dir = resolve(cwd);
+ const home = homedir();
+ while (dir && dir !== dirname(dir)) {{
+ const marker = join(dir, ".ai-memory.toml");
+ if (existsSync(marker)) return marker;
+ if (home && dir === home) return undefined;
+ dir = dirname(dir);
+ }}
+ return undefined;
+}}
+
+function tomlKey(text: string, key: string): string | undefined {{
+ const re = new RegExp(`^\\s*${{key}}\\s*=\\s*"([^"]*)"`);
+ for (const line of text.split(/\r?\n/)) {{
+ const match = re.exec(line);
+ if (match) return match[1];
+ }}
+ return undefined;
+}}
+
+function applyMarkerParams(url: URL, cwd: string | undefined): void {{
+ const marker = findMarker(cwd);
+ if (!marker || !cwd) return;
+ url.searchParams.set("cwd", cwd);
+ try {{
+ const body = readFileSync(marker, "utf8");
+ const workspace = tomlKey(body, "workspace");
+ const project = tomlKey(body, "project");
+ if (workspace) url.searchParams.set("workspace", workspace);
+ if (project) url.searchParams.set("project", project);
+ }} catch (_e) {{
+ }}
+}}
+
function sessionID(ctx: any): string | undefined {{
const id = ctx?.sessionManager?.getSessionId?.();
return typeof id === "string" && id.length > 0 ? id : undefined;
@@ -785,6 +866,7 @@ function postHook(event: string, payload: Record<string, unknown>): void {{
const url = new URL(`${{SERVER}}/hook`);
url.searchParams.set("event", event);
url.searchParams.set("agent", AGENT);
+ applyMarkerParams(url, typeof payload.cwd === "string" ? payload.cwd : undefined);
try {{
void fetch(url, {{
method: "POST",
@@ -801,6 +883,7 @@ async function fetchHandoff(cwd: string): Promise<string | undefined> {{
const url = new URL(`${{SERVER}}/handoff`);
url.searchParams.set("agent", AGENT);
url.searchParams.set("cwd", cwd);
+ applyMarkerParams(url, cwd);
try {{
const response = await fetch(url, {{
headers: authHeaders(),
@@ -1360,6 +1443,13 @@ mod tests {
assert!(plugin.contains("const startedSessions = new Set<string>();"));
assert!(plugin.contains("function startSession"));
assert!(plugin.contains("fetchHandoff"));
+ assert!(plugin.contains("function applyMarkerParams"));
+ assert!(plugin.contains("readFileSync(marker, \"utf8\")"));
+ assert!(plugin.contains("text.split(/\\r?\\n/)"));
+ assert!(plugin.contains(
+ "applyMarkerParams(url, typeof payload.cwd === \"string\" ? payload.cwd : undefined);"
+ ));
+ assert!(plugin.contains("applyMarkerParams(url, cwd);"));
assert!(plugin.contains("postPreCompact"));
assert!(plugin.contains("postHook(\"session-start\""));
assert!(plugin.contains("postHook(\"user-prompt\""));
@@ -1406,6 +1496,13 @@ mod tests {
assert!(extension.contains("postHook(\"session-start\""));
assert!(extension.contains("postHook(\"user-prompt\""));
assert!(extension.contains("fetchHandoff"));
+ assert!(extension.contains("function applyMarkerParams"));
+ assert!(extension.contains("readFileSync(marker, \"utf8\")"));
+ assert!(extension.contains("text.split(/\\r?\\n/)"));
+ assert!(extension.contains(
+ "applyMarkerParams(url, typeof payload.cwd === \"string\" ? payload.cwd : undefined);"
+ ));
+ assert!(extension.contains("applyMarkerParams(url, cwd);"));
assert!(extension.contains("Bearer ${TOKEN}"));
assert!(extension.contains("tok"));
}
diff --git a/docs/install.md b/docs/install.md
index ed51869f..272fb4b4 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -5,6 +5,7 @@ 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 the CLI URL and auth](#configuring-the-cli-url-and-auth)
- [Configuring other agent CLIs](#configuring-other-agent-clis)
(Codex, OpenCode, OMP, Cursor, Claude Desktop, Gemini CLI, OpenClaw)
- [Installing hooks without docker](#installing-hooks-without-docker)
@@ -14,6 +15,7 @@ path (docker + Claude Code). This page covers everything else:
- [LLM provider tiers + self-hosted Ollama](#llm-provider-tiers)
- [Subcommand reference](#subcommand-reference)
- [Operating without auth](#operating-without-auth) (local-only)
+- [Keeping ai-memory up to date](#keeping-ai-memory-up-to-date)
> **Shorthand.** Most snippets use `$TOKEN` and `homelab:49374`. If
> you're following along verbatim:
@@ -65,6 +67,38 @@ two env vars automatically.
---
+## Configuring the CLI URL and auth
+
+The `ai-memory` binary is a thin HTTP client. It never opens the wiki
+or SQLite directly; state-touching commands go through the running
+server, which is the sole writer.
+
+Configuration is two optional environment variables:
+
+| Variable | Default | When to set it |
+|---|---|---|
+| `AI_MEMORY_SERVER_URL` | `http://127.0.0.1:49374` | When the server runs somewhere other than the same machine, such as `http://192.168.0.90:49374`. |
+| `AI_MEMORY_AUTH_TOKEN` | unset | When the server has bearer auth enabled. |
+
+For a single-laptop loopback server, set neither variable. For a
+remote or homelab server, put both in your shell rc or direnv file:
+
+```bash
+export AI_MEMORY_SERVER_URL="http://192.168.0.90:49374"
+export AI_MEMORY_AUTH_TOKEN="<token>"
+```
+
+Explicit `--server-url` and `--auth-token` flags on `install-mcp` and
+`install-hooks` override the environment. That is useful when you are
+generating config for a client that talks to a different server than
+your default CLI target.
+
+`init`, `serve`, `install-*`, `generate-auth-token`, and `setup-agent`
+do not need these env vars because they either set up local files or
+start the server itself.
+
+---
+
## Configuring other agent CLIs
> `install-mcp --server-url` takes the MCP endpoint **including** `/mcp`
@@ -494,12 +528,61 @@ ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply
```
+### Docker compose alternative
+
+If you prefer compose, clone the repo and run:
+
+```bash
+docker compose -f docker/docker-compose.yml up -d
+```
+
+The bundled compose file already has `restart: unless-stopped`, a
+healthcheck, and the named volume wired up. Agent setup is the same as
+the regular Docker path.
+
+---
+
+## Keeping ai-memory up to date
+
+The wrapper checks Docker Hub at most once every 24 hours and prints a
+one-line warning when a newer image is available. Upgrade with:
+
+```bash
+ai-memory upgrade
+```
+
+The command self-upgrades the wrapper script, pulls the latest Docker
+image, re-stages hook scripts under
+`~/.local/share/ai-memory/hooks/<agent>/` for configured agents, and
+prints how to restart the server container so the new binary is used.
+Re-running `install-hooks --apply` remains idempotent: ai-memory
+replaces only the hook entries it owns and leaves unrelated hooks alone.
+
+Set `AI_MEMORY_NO_VERSION_CHECK=1` to silence the daily check, or
+`AI_MEMORY_WRAPPER_URL=<url>` to pin wrapper self-upgrades to a fork or
+tagged release.
+
+When the upgraded server starts, it applies SQLite schema migrations and
+pending wiki-structure migrations automatically. No manual database
+reset or wiki rewrite is required for normal upgrades.
+
+If the server runs on another host, `ai-memory upgrade` refreshes only
+the local wrapper, local image, and local hook scripts. Redeploy the
+remote server separately with `bin/deploy` or `docker compose pull &&
+docker compose up -d` in that deploy directory.
+
+Inside ai-jail or another bwrap sandbox, the wrapper is usable from the
+sandbox, but run `install-*` commands outside the sandbox because they
+write to `~/.local/share/ai-memory/hooks/`.
+
---
## See also
- [`docs/deploy.md`](deploy.md) - homelab deploy walkthrough
(`bin/deploy`, cloudflared TLS, env-file management)
+- [`docs/usage.md`](usage.md) - handoffs, proactive querying, web UI,
+ routing snippet, and raw-wiki inspection
- [`docs/mcp-install.md`](mcp-install.md) - per-client MCP config
reference for Cursor, Claude Desktop, Gemini CLI, OpenClaw, OMP
- [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) - what's actually
diff --git a/docs/llm-provider-comparison.md b/docs/llm-provider-comparison.md
index 7f7e4ca1..0411141e 100644
--- a/docs/llm-provider-comparison.md
+++ b/docs/llm-provider-comparison.md
@@ -30,7 +30,7 @@
> server** (Ollama / vLLM / llama-swap with a 30B-class
> model): qwen3:32b on Ollama — $0 per consolidation,
> background latency invisible to users. See
-> [README → LLM provider configuration](../README.md#llm-provider--recommended-defaults)
+> [Installation cookbook - LLM provider tiers](install.md#llm-provider-tiers)
> for setup. Reproduce the comparison in [`evals/`](../evals/).
## Why this document exists
diff --git a/docs/marker-file.md b/docs/marker-file.md
index 544ac8fc..d4972081 100644
--- a/docs/marker-file.md
+++ b/docs/marker-file.md
@@ -30,6 +30,11 @@ a marker is found, hook scripts also forward the current `cwd` so
workspace-only markers can still resolve `project = basename(cwd)` for
handoff lookups.
+The marker path is shared by the POSIX/PowerShell hook scripts and the
+generated OpenCode / OMP TypeScript integrations. In all cases, hook
+capture and handoff lookup send the same `cwd`, `workspace`, and
+`project` query params to the server when a marker is present.
+
## Schema
```toml
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index e328235a..8432244e 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -301,7 +301,7 @@ that *starts* the next one - to play nicely with ai-memory:
| Side | What's needed | Covered by |
|---|---|---|
| **Ending side** | The agent must create a handoff, either through a true session-end hook or by calling `memory_handoff_begin`. | Built-in for Claude Code, Codex, Cursor, Gemini CLI, OpenClaw, and OMP. OpenCode has no true session-end event, so ask it to call `memory_handoff_begin` before quitting when you need a handoff. |
-| **Starting side** | Either (a) the session-start/plugin path injects the handoff via `/handoff`, OR (b) the model proactively calls `memory_handoff_accept` on first turn. | (a) is built-in for Claude Code / Codex / Cursor / Gemini CLI / OpenClaw / OpenCode / OMP. (b) works for any MCP-capable client if you nudge the model - see [the CLAUDE.md snippet](../README.md#nudging-the-agent-to-use-memory-proactively). |
+| **Starting side** | Either (a) the session-start/plugin path injects the handoff via `/handoff`, OR (b) the model proactively calls `memory_handoff_accept` on first turn. | (a) is built-in for Claude Code / Codex / Cursor / Gemini CLI / OpenClaw / OpenCode / OMP. (b) works for any MCP-capable client if you nudge the model - see [the routing snippet](usage.md#install-the-routing-snippet). |
So a typical mixed workflow looks like:
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 00000000..60a042d9
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,151 @@
+# Day-to-day usage
+
+This page covers what happens after ai-memory is installed: handoffs,
+compaction recovery, proactive memory queries, the web UI, and the
+project-rule routing snippet.
+
+## Cross-agent handoff
+
+You normally do not create handoffs by hand. With lifecycle hooks
+installed, session-end capture writes the handoff and the next
+session-start hook fetches it.
+
+```text
+$ claude
+> Working on the auth refactor. JWT rotation is broken; trying session cookies.
+[work for an hour]
+> /exit
+
+$ codex # in the same directory, later
+[SessionStart hook fetches the handoff; Codex sees it before your prompt.]
+> Picking up: you were investigating session cookies as an alternative...
+```
+
+If an agent has MCP but no lifecycle hook surface, ask it to call
+`memory_handoff_begin` before quitting. The next hooked agent can still
+consume that handoff automatically.
+
+## Compaction recovery
+
+When Claude Code or Codex compact their working context, the
+`PreCompact` hook fires and ai-memory writes a fresh
+`sessions/<id>.md` page summarising the session so far. After
+compaction, the agent can recover the summary via `memory_recent` even
+though its raw chat history was compacted away.
+
+## Proactive memory queries
+
+Hooks handle capture without prompting. Proactive querying depends on
+the agent knowing which MCP tool to call for each situation. Install the
+routing snippet into the project rules file once, then agents can use
+the wiki without you naming tools explicitly.
+
+| You say | Agent calls | Effect |
+|---|---|---|
+| "Have we discussed X?" / "search memory for Y" | `memory_query` | FTS5 + graph/vector RRF over compiled wiki pages, with bounded raw-observation fallback. |
+| Before proposing architecture | `memory_query` | Checks prior decisions and gotchas before suggesting designs. |
+| "Catch me up" / "I've been away" | `memory_explore` | Prose digest whose verbosity scales with time since last activity. |
+| "Where did we leave off?" | Existing handoff block, or `memory_handoff_accept` if no block exists | Resumes from the latest pending handoff. |
+| "Save context for the next session" | `memory_handoff_begin` | Writes a terse handoff with open questions and next steps. |
+| "Consolidate this session" | `memory_consolidate` | Manually runs what session-end normally runs automatically. |
+| "Audit the wiki" / "any contradictions?" | `memory_lint` | Runs stale-page, contradiction, and rule-suggestion checks. |
+| "How big is the wiki?" / "stats?" | `memory_status`, `memory_briefing` | Counts and recent activity windows. |
+
+## Install the routing snippet
+
+From an agent, say:
+
+```text
+Install ai-memory routing into this project.
+```
+
+The agent calls `memory_install_self_routing`, receives the canonical
+snippet, and writes it to the right rules file (`CLAUDE.md` for Claude
+Code, `AGENTS.md` for Codex / OpenCode / Cursor / Gemini CLI). The
+block is wrapped in `<!-- ai-memory:start -->` and
+`<!-- ai-memory:end -->`, so re-runs replace it in place.
+
+From a terminal:
+
+```bash
+ai-memory install-instructions
+ai-memory install-instructions --target AGENTS.md
+ai-memory install-instructions --print
+```
+
+Auto-detect extends `CLAUDE.md` when it exists, `AGENTS.md` when it
+exists, both when both exist, or creates `CLAUDE.md` when neither
+exists. Use `--target AGENTS.md` for non-Claude-only projects.
+
+## Bootstrap an existing project
+
+If you install ai-memory into a project that already has months of
+history, the wiki starts empty. `ai-memory bootstrap` seeds it from the
+existing repo history and docs.
+
+```bash
+export AI_MEMORY_SERVER_URL="http://localhost:49374"
+ai-memory bootstrap --dry-run
+ai-memory bootstrap
+```
+
+The bootstrap collector reads `git log`, the root README, `docs/`,
+project rule files, and Rust module docs, then POSTs the selected
+sources to the running server. It requires an LLM provider on the
+server. See [Installation cookbook - bootstrap mid-project](install.md#bootstrap-mid-project)
+for flags, token budgets, and source priority.
+
+## Browse the wiki in a browser
+
+Start the server with `--enable-web` and open
+`http://<host>:49374/web`.
+
+```bash
+ai-memory serve --transport http --bind 127.0.0.1:49374 --enable-web
+```
+
+Docker compose users can add the flag to the service command:
+
+```yaml
+command: ["serve", "--transport", "http", "--bind", "0.0.0.0:49374", "--enable-web"]
+```
+
+The web UI is read-only: project list, per-project page tree,
+breadcrumbs, rendered markdown, metadata, and FTS5 search. If the
+server has `AI_MEMORY_AUTH_TOKEN` set, the browser uses HTTP Basic auth:
+leave the username blank and paste the token as the password. MCP and
+hook clients continue to use `Authorization: Bearer <token>`.
+
+![Project list homepage with four projects shown as cards with page counts and last activity.](web-projects-home.png)
+
+![Project view with folder tree, kind badges, and recent activity.](web-project-view.png)
+
+## Inspect the raw wiki
+
+The wiki is plain markdown plus git history.
+
+```bash
+docker exec ai-memory ls /data/wiki/sessions/
+docker exec ai-memory cat /data/wiki/sessions/<uuid>.md
+
+# Open in Obsidian or any markdown viewer:
+docker cp ai-memory:/data/wiki ./my-ai-memory-wiki
+
+# Time-travel:
+docker exec ai-memory git -C /data/wiki log --oneline
+```
+
+## Rules vs facts
+
+Durable project rules belong in the agent's rules file, not only in the
+wiki. For Claude Code that is `CLAUDE.md`; for Codex, OpenCode,
+Cursor, and Gemini CLI it is usually `AGENTS.md`.
+
+The consolidator classifies compiled observations as `decision`,
+`fact`, `rule`, or `gotcha`. Rule-tagged pages are routed to
+`wiki/_rules/<slug>.md`, and `memory_lint` reports a suggestion when a
+rule looks durable enough to copy into `CLAUDE.md` or `AGENTS.md`.
+
+ai-memory never edits the rules file on its own. The lint suggestion is
+the whole workflow: copy the rule if it should apply every turn, ignore
+it if it was temporary context.
diff --git a/hooks/_lib.sh b/hooks/_lib.sh
index 003e6280..787f80e1 100644
--- a/hooks/_lib.sh
+++ b/hooks/_lib.sh
@@ -36,13 +36,16 @@ ai_memory_parse_toml_key() {
"$file" | head -n 1
}
-# Extract `cwd` from a JSON payload on stdin or in $1. Returns the
-# value or nothing. Tolerates leading whitespace and escaped quotes
-# inside other keys by anchoring on the `cwd` key explicitly.
+# Extract the first `cwd` from a JSON payload on stdin or in $1. Returns
+# the value or nothing. This is intentionally a tiny shell fallback, not
+# a JSON parser; taking the first match preserves the top-level cwd when
+# tool payloads contain nested `cwd` fields later in the object.
ai_memory_extract_cwd() {
payload="${1:-$(cat)}"
- printf '%s' "$payload" \
- | sed -n -E 's/.*"cwd"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p' \
+ rest=${payload#*\"cwd\"}
+ [ "$rest" = "$payload" ] && return 0
+ printf '%s' "$rest" \
+ | sed -n -E 's/^[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p' \
| head -n 1
}
@@ -51,7 +54,7 @@ ai_memory_extract_cwd() {
# plus a defensive pass for anything a hand-edited marker might contain.
ai_memory_url_encode() {
printf '%s' "$1" \
- | sed 's/%/%25/g; s/&/%26/g; s/=/%3D/g; s/?/%3F/g; s/#/%23/g; s/ /%20/g'
+ | sed 's/%/%25/g; s/+/%2B/g; s/&/%26/g; s/=/%3D/g; s/?/%3F/g; s/#/%23/g; s/ /%20/g'
}
# Build a query-string suffix from the marker file walked up from "$1".
diff --git a/tests/hooks/test_lib.sh b/tests/hooks/test_lib.sh
index a6fce42d..09da2891 100755
--- a/tests/hooks/test_lib.sh
+++ b/tests/hooks/test_lib.sh
@@ -56,6 +56,8 @@ assert_eq "no marker returns empty" "" \
PAYLOAD='{"session_id":"x","cwd":"/home/u/foo","tool":"Read"}'
assert_eq "extract cwd from payload" "/home/u/foo" "$(ai_memory_extract_cwd "$PAYLOAD")"
assert_eq "extract cwd from empty json" "" "$(ai_memory_extract_cwd '{}')"
+PAYLOAD_NESTED='{"session_id":"x","cwd":"/home/u/root","tool_input":{"cwd":"/tmp/nested"}}'
+assert_eq "extract cwd prefers first match" "/home/u/root" "$(ai_memory_extract_cwd "$PAYLOAD_NESTED")"
# --- marker_qs --------------------------------------------------------
QS=$(ai_memory_marker_qs "$TMP/a/b/c")
@@ -72,6 +74,7 @@ assert_eq "no marker -> empty qs" "" "$QS3"
assert_eq "url_encode passes safe slug" "movvia" "$(ai_memory_url_encode "movvia")"
assert_eq "url_encode escapes ampersand" "a%26b" "$(ai_memory_url_encode "a&b")"
assert_eq "url_encode escapes equals" "a%3Db" "$(ai_memory_url_encode "a=b")"
+assert_eq "url_encode escapes plus" "a%2Bb" "$(ai_memory_url_encode "a+b")"
# --- summary ----------------------------------------------------------
printf '\n%d passed, %d failed\n' "$PASS" "$FAIL"