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.mdindex 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, supportedplatforms, 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.mdindex 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 fullarchive in CLI memory.- Hyphenated FTS5 queries such as `ai-memory` are normalized safely instead ofdiff --git a/README.md b/README.mdindex 662b72ec..45acac1c 100644--- a/README.md+++ b/README.md@@ -174,589 +174,144 @@ write. The hook scripts are staged intooverwrites 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-+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:---```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.rsindex 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.mdindex 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 --applyai-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 configreference for Cursor, Claude Desktop, Gemini CLI, OpenClaw, OMP- [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) - what's actuallydiff --git a/docs/llm-provider-comparison.md b/docs/llm-provider-comparison.mdindex 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 existsdiff --git a/docs/marker-file.md b/docs/marker-file.mdindex 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` soworkspace-only markers can still resolve `project = basename(cwd)` forhandoff 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```tomldiff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex 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.mdnew file mode 100644index 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>`.++++++## 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.shindex 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.shindex 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"