Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(docs): align current guidance with runtime
AkitaOnRailsab5eb71815e6
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ae9587fc..312ab7c4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,7 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Changed+- Configuring the hosted `anthropic` or `openai` provider without an explicit+ model now selects the documented recommended defaults, `claude-haiku-4-5`+ and `gpt-5.4-mini`, instead of the older `claude-sonnet-4-6` and+ `gpt-4o-mini` fallbacks. Explicit `AI_MEMORY_LLM_MODEL` values are unchanged.+### Fixed+- User-facing help and current-reference documentation now match the shipped+ agent integrations, multi-user activation boundary, MCP URL normalization,+ Pi bridge, and `memory_consolidate` configuration requirements. Local+ documentation links and anchors were also audited and repaired.- Reader APIs now derive absent page kinds consistently from canonical pathfamilies. Session, concept, procedure, note, and slot pages no longer surfaceas generic facts, while an explicit frontmatter `kind` still takes precedencediff --git a/README.md b/README.mdindex 653715c6..e5799885 100644--- a/README.md+++ b/README.md@@ -10,7 +10,7 @@> re-explaining the architecture, the failed approaches, or the open> questions.-[](docs/ARCHITECTURE.md)+[](https://github.com/akitaonrails/ai-memory/releases/latest)[](rust-toolchain.toml)[](LICENSE)@@ -231,8 +231,8 @@ packaged unit. Full user-service, system-service, auth, and provider setup is in### Docker-You need: Docker + an agent CLI (Claude Code, Codex, Devin CLI, OpenCode, OMP,-Cursor, Antigravity CLI, Grok Build CLI, or anything else that speaks MCP).+You need: Docker + an agent CLI from the [Support Matrix](#support-matrix), or+anything else that speaks MCP.The published Docker image includes `linux/amd64` and `linux/arm64` variants,so Apple Silicon Macs and ARM64 Linux hosts can pull `akitaonrails/ai-memory`@@ -349,10 +349,9 @@ one matching entry.projects) when you want new tool guidance. The refresh writes the slimmarkered snippet and managed Agent Skills from the same binary-owned assets.-For Codex, Devin CLI, OpenCode, OMP, Cursor, Claude Desktop, Gemini CLI,-Antigravity CLI, Grok Build CLI, Kimi Code, OpenClaw, VS Code Copilot,-curl-based hook installs, source builds,-CLI env vars, and the full subcommand reference, see [`docs/install.md`](docs/install.md).+For every client in the [Support Matrix](#support-matrix), plus curl-based hook+installs, source builds, CLI environment variables, and the full subcommand+reference, see [`docs/install.md`](docs/install.md).## Security@@ -436,13 +435,13 @@ it doesn't earn its keep.shares a server, ai-memory can attribute each write to a named user.The bearer token continues to authenticate at the wire level; userscreated via `ai-memory user add` get their own tokens that resolve to-their identity in audit logs (and, in subsequent milestones, page-frontmatter + the web UI). Data stays single-tenant — there is no-per-page RBAC — but once `[auth].token_pepper` enables multi-user-mode, every `/admin/*` endpoint requires the root token, including-status/search/read-page and user-management routes. Existing single-user installs-are not affected unless you opt in by setting `[auth].token_pepper`-(auto-generated for new installs by `ai-memory init`). See+their identity in audit logs, page frontmatter, `/api/v1` responses, and the+page view UI. Data stays single-tenant — there is no per-page RBAC. A+`[auth].token_pepper` is required for DB-user authentication, but creating the+first user row is what immediately switches every `/admin/*` endpoint to+root-only, including status/search/read-page and user-management routes.+`ai-memory init` generates a pepper for new installs without changing+single-user behavior until a user is added. See[`docs/users.md`](docs/users.md) for the full walkthrough and thefour-rung auth ladder.diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rsindex cf83adfd..9e006b5b 100644--- a/crates/ai-memory-cli/src/cli.rs+++ b/crates/ai-memory-cli/src/cli.rs@@ -70,10 +70,9 @@ pub enum Command {/// Hidden hook spool drainer used by native session-end hooks.#[command(hide = true, name = "hook-drain")]HookDrain(HookDrainArgs),- /// Print MCP server registration snippets for any supported client- /// (Claude Code, Codex, OpenCode, Cursor, Claude Desktop, Gemini- /// CLI, OpenClaw, OMP, Pi, Grok, Zero, Devin, Antigravity CLI, VS Code- /// Copilot). See docs/mcp-install.md for the full guide.+ /// Print MCP server registration snippets for any supported client.+ /// Current values are listed under `--client`; see docs/mcp-install.md+ /// for the full guide.InstallMcp(InstallMcpArgs),/// Stage + commit the wiki tree under git.Commit(CommitArgs),@@ -801,8 +800,8 @@ pub enum AgentChoice {/// them straight to `--agent`, which used to fail on this one.#[value(alias = "opencode")]OpenCode,- /// Real Pi coding agent. Recognized separately from OMP, but hook- /// install intentionally fails closed until the Pi bridge lands.+ /// Real Pi coding agent. The generated TypeScript extension provides+ /// lifecycle capture and bridges ai-memory's HTTP MCP tools into Pi.Pi,/// Oh My Pi (`omp`) — TypeScript extension/// under `~/.omp/agent/extensions/`. `--apply` writes the extension@@ -927,7 +926,8 @@ pub enum McpClient {GeminiCli,/// OpenClaw personal AI gateway — `~/.openclaw/config.json`.Openclaw,- /// Real Pi coding agent. Pi core has no native MCP config yet.+ /// Real Pi coding agent. Uses ai-memory's generated bridge extension+ /// because Pi has no native MCP config.Pi,/// Oh My Pi (`omp`) — `~/.omp/agent/mcp.json`.#[value(alias = "oh-my-pi")]@@ -1189,7 +1189,7 @@ pub struct LlmTestArgs {/// Provider to test.#[arg(long, value_enum)]pub provider: LlmProviderChoice,- /// Model identifier (e.g. `claude-sonnet-4-6`, `gpt-4o-mini`, `llama3.1:8b`).+ /// Model identifier (e.g. `claude-haiku-4-5`, `gpt-5.4-mini`, `llama3.1:8b`).#[arg(long)]pub model: String,/// Prompt to send.@@ -1269,20 +1269,16 @@ pub struct InstallHooksArgs {pub agent: AgentChoice,/// Filesystem root that contains the vendored hook scripts (defaults/// to the repo's `hooks/` if known, else `/usr/local/share/ai-memory/hooks`).- /// Ignored for generated TypeScript integrations (OpenCode, OMP, OpenClaw).+ /// Ignored for generated TypeScript integrations (OpenCode, OMP, Pi,+ /// OpenClaw).#[arg(long)]pub hooks_dir: Option<PathBuf>,/// Server URL the hooks will POST to. Defaults to the configured/// `server_url` / AI_MEMORY_SERVER_URL when set, else loopback. If neither/// is configured, apply-mode also reuses an existing ai-memory MCP entry/// for the same agent when one is present.- ///- /// `Option` (no `default_value_t`) is deliberate: it lets- /// `effective_hook_server_url` distinguish "not passed" from "passed- /// and happens to equal the compiled default" — a plain `String` with- /// a default can't tell those apart, which let `AI_MEMORY_SERVER_URL`- /// silently override an explicit `--server-url <default>` (found- /// 2026-07-12 during Devin real-acceptance A/B testing).+ // Keep this optional so effective_hook_server_url can distinguish an+ // omitted flag from an explicit URL that equals the compiled default.#[arg(long)]pub server_url: Option<String>,/// Bearer token to embed in the hook config's `env` block. When@@ -1291,12 +1287,9 @@ pub struct InstallHooksArgs {/// is set there. Generate one with `ai-memory generate-auth-token`.#[arg(long, hide_env_values = true)]pub auth_token: Option<String>,- /// **Multi-user attribution (P1.8)**: stamp the installed hooks- /// with this username so the operator + the hook scripts both- /// know which registered user (from `ai-memory user add`) the- /// install is for. This flag is metadata — the actual token- /// stamped into the hook env block is whatever you pass via- /// `--auth-token`. Recommended workflow:+ /// Stamp the installed hooks with a registered username for operator+ /// visibility. This flag is metadata: the server resolves attribution+ /// from the token passed via `--auth-token`. Recommended workflow:////// ```bash/// # 1. create the user (prints the token once)@@ -1307,9 +1300,8 @@ pub struct InstallHooksArgs {/// --as-user alice --auth-token <alice-token>/// ```///- /// Without this flag, hooks are installed anonymously (same as- /// pre-v0.8 behaviour) — every write attributed to "anonymous"- /// or to `[auth].root_username` when the root token is reused.+ /// Without this flag, the installer omits the username label;+ /// attribution still resolves from the bearer token at request time.#[arg(long)]pub as_user: Option<String>,/// **Mutate** the selected agent's hook config in place instead of@@ -1342,12 +1334,10 @@ pub struct InstallMcpArgs {/// Server URL the client should connect to — either the base URL/// (`https://host:49374`, the same value `install-hooks --server-url`/// takes) or the full MCP endpoint (`…/mcp`); a missing `/mcp` suffix- /// is appended automatically (#185). Defaults to the configured+ /// is appended automatically. Defaults to the configured/// `server_url` / AI_MEMORY_SERVER_URL plus `/mcp` when set, else/// loopback.- ///- /// `Option` (no `default_value_t`) is deliberate: see the matching- /// comment on `InstallHooksArgs::server_url` — same bug, same fix.+ // Keep this optional for the same explicit-URL precedence as hook install.#[arg(long)]pub server_url: Option<String>,/// Friendly name the client should show for this server entry.diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rsindex 4b57ea37..8afbdef8 100644--- a/crates/ai-memory-cli/src/config.rs+++ b/crates/ai-memory-cli/src/config.rs@@ -668,9 +668,9 @@ impl Config {let model = match non_empty(self.llm_model.as_deref()) {Some(s) => s.to_string(),None => match provider {- ProviderChoice::Anthropic => "claude-sonnet-4-6".to_string(),+ ProviderChoice::Anthropic => "claude-haiku-4-5".to_string(),ProviderChoice::AnthropicOAuth => "claude-sonnet-4-6".to_string(),- ProviderChoice::OpenAi => "gpt-4o-mini".to_string(),+ ProviderChoice::OpenAi => "gpt-5.4-mini".to_string(),ProviderChoice::Gemini => "gemini-2.5-flash".to_string(),ProviderChoice::OpenAiOAuth => "gpt-5.5".to_string(),ProviderChoice::Copilot => "gpt-5.5".to_string(),@@ -1198,7 +1198,7 @@ mod tests {let provider = cfg.llm_provider_config().unwrap().unwrap();assert_eq!(provider.provider, ProviderChoice::OpenAi);- assert_eq!(provider.model, "gpt-4o-mini");+ assert_eq!(provider.model, "gpt-5.4-mini");assert_eq!(provider.auth.requirement(),AuthRequirement::RequiredApiKey {@@ -1218,6 +1218,22 @@ mod tests {assert!(!provider.compat_strict);}+ #[test]+ fn anthropic_provider_uses_documented_default_model() {+ let cfg = Config {+ llm_provider: Some("anthropic".into()),+ runtime_env: RuntimeEnv {+ anthropic_api_key: Some(SecretString::from("sk-ant-test-key")),+ ..RuntimeEnv::default()+ },+ ..Config::default()+ };++ let provider = cfg.llm_provider_config().unwrap().unwrap();+ assert_eq!(provider.provider, ProviderChoice::Anthropic);+ assert_eq!(provider.model, "claude-haiku-4-5");+ }+#[test]fn llm_test_api_key_override_wins_over_env_auth() {let cfg = Config {diff --git a/crates/ai-memory-mcp/src/server.rs b/crates/ai-memory-mcp/src/server.rsindex 71505262..1a580125 100644--- a/crates/ai-memory-mcp/src/server.rs+++ b/crates/ai-memory-mcp/src/server.rs@@ -1454,8 +1454,9 @@ impl AiMemoryServer {(single-page) rewrites sessions/<id>.md from the observation \log. multi_page=true fans out into a batch of concept/decision/\gotcha pages plus the session page, all written in one atomic \- SQL transaction. Off by default; requires \- AI_MEMORY_LLM_PROVIDER + AI_MEMORY_LLM_MODEL set on the server. \+ SQL transaction. Off by default; requires AI_MEMORY_LLM_PROVIDER \+ plus that provider's credentials. AI_MEMORY_LLM_MODEL is optional \+ for providers with a built-in default. \The consolidation target is resolved from where the session's \observations actually landed, so a session that adopted its scope \marker mid-run still consolidates into the right project. Admission \@@ -1471,7 +1472,7 @@ impl AiMemoryServer {) -> Result<CallToolResult, McpError> {let Some(consolidator) = self.consolidator.as_ref() else {return Err(McpError::internal_error(- "memory_consolidate not configured (set AI_MEMORY_LLM_PROVIDER + AI_MEMORY_LLM_MODEL)",+ "memory_consolidate not configured (set AI_MEMORY_LLM_PROVIDER and the provider's required credentials; providers without a built-in model also require AI_MEMORY_LLM_MODEL)",None,));};@@ -6381,6 +6382,14 @@ mod tests {msg.contains("not configured"),"error should mention configuration: {msg}",);+ assert!(+ msg.contains("provider's required credentials"),+ "error should direct users to provider credentials: {msg}",+ );+ assert!(+ msg.contains("without a built-in model"),+ "error should not imply every provider needs an explicit model: {msg}",+ );}#[tokio::test]diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 92c48723..af6aedd8 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -6,9 +6,9 @@## Purpose-ai-memory is a single Rust binary that gives AI coding agents (Claude-Code, OpenAI Codex, Cursor, Gemini CLI, Antigravity CLI, Grok Build CLI,-OpenClaw, OpenCode, OMP, and MCP-capable clients) long-term memory shared across CLIs.+ai-memory is a single Rust binary that gives the coding agents in the+[README Support Matrix](../README.md#support-matrix), plus other MCP-capable+clients, long-term memory shared across CLIs.Quit one mid-task; open another in the same directory; continue. Nomanual `write_note` ceremony, no copy-pasting summaries betweensessions.@@ -63,8 +63,9 @@ from hook paths.3. On true `SessionEnd` events, the server synthesises a`sessions/<id>.md` summary page (rule-based, no LLM) and opens a`Handoff` row for the next agent. Auto-commits the wiki. Clients- without a true session-end hook (currently Antigravity CLI) should call- `memory_handoff_begin` before quitting when a handoff is needed.+ without a reliable true session-end hook need an explicit ending action:+ Codex provides `ai-memory finalize-session`, while Antigravity CLI should+ call `memory_handoff_begin` before quitting when a handoff is needed.4. When `AI_MEMORY_LLM_PROVIDER` is set, `memory_consolidate` rewritesthat summary into a richer durable page or fans out into amulti-page batch under `concepts/`, `decisions/`, `gotchas/`.@@ -182,9 +183,9 @@ contradict specific existing content.## Cross-project links-Pages normally link within their own project (`[[decisions/0001.md]]`,-`[label](../gotchas/x.md)`). A wikilink can also name another project so-that dependencies between projects become explicit edges in the graph:+Pages normally link within their own project (`[[decisions/0001.md]]`, or a+`label` pointing to `../gotchas/x.md`). A wikilink can also name another project+so that dependencies between projects become explicit edges in the graph:* `[[project:path.md]]` — a sibling project in the same workspace.* `[[workspace/project:path.md]]` — a project in another workspace.@@ -386,7 +387,7 @@ min_session_age_secs = 600**LLM provider env** (opt-in):```AI_MEMORY_LLM_PROVIDER anthropic | openai | openai-oauth | copilot | gemini | openai-compat-AI_MEMORY_LLM_MODEL e.g. claude-sonnet-4-6, gpt-5.5, gemini-2.5-flash+AI_MEMORY_LLM_MODEL optional when the provider has a default; e.g. claude-haiku-4-5, gpt-5.4-miniANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / LLM_API_KEYAI_MEMORY_LLM_BASE_URL for openai-compat (Ollama, vLLM)COPILOT_GITHUB_TOKEN optional GitHub token for copilotdiff --git a/docs/deploy.md b/docs/deploy.mdindex 8641dddb..d569ce14 100644--- a/docs/deploy.md+++ b/docs/deploy.md@@ -43,7 +43,7 @@ cp docker/docker-compose.prod.yml.example docker/docker-compose.prod.yml$EDITOR docker/docker-compose.prod.yml # set the image tag + adjust ports if neededcp docker/.env.production.example docker/.env.production-$EDITOR docker/.env.production # fill API keys; pick LLM provider + model+$EDITOR docker/.env.production # fill credentials; pick an LLM provider (model override optional)# 2. Create the deploy dir on the homelab. Source bin/deploy.env so# SERVER/DEPLOY_DIR are exported in this shell.@@ -99,9 +99,9 @@ curl -sI http://homelab:49374/handoff \**Then update every MCP client** to send the same token. `ai-memoryinstall-mcp --client <name> --auth-token <token>` prints the exact-snippet per client (Claude Code, Codex, OpenCode, Cursor, Claude-Desktop, Gemini CLI, OpenClaw, OMP / Oh My Pi, Antigravity CLI). The agent CLI sends an-`Authorization: Bearer <token>` header on every call; ai-memory's+snippet for every client in the [README Support Matrix](../README.md#support-matrix);+run `ai-memory install-mcp --help` for the current accepted values. The agent+CLI sends an `Authorization: Bearer <token>` header on every call; ai-memory'smiddleware validates with a constant-time comparison.**Encrypted transport.** Plain HTTP on the LAN means anyone with adiff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex 1c90790e..7e06fa93 100644--- a/docs/design-decisions.md+++ b/docs/design-decisions.md@@ -1,8 +1,10 @@# ai-memory - Design Decisions (Synthesis)-> Distills the four research reports (`research-*.md`) and three issue-tracker-> reports (`issues-*.md`) into the concrete decisions this project will make.-> Read this first; the research files are the receipts.+> Historical rationale distilled from the original research and issue-tracker+> reports. For the current operational map, read+> [`ARCHITECTURE.md`](ARCHITECTURE.md); for current client support, use the+> [README Support Matrix](../README.md#support-matrix). The research files are+> the historical receipts.## 1. Product shapediff --git a/docs/https-via-proxy.md b/docs/https-via-proxy.mdindex aab7a4e1..7f87f823 100644--- a/docs/https-via-proxy.md+++ b/docs/https-via-proxy.md@@ -24,7 +24,10 @@ this case. Most ai-memory installs never need a proxy.Add a TLS-terminating proxy in front of ai-memory when any of theseapply:-- **Multi-user mode is on** (`[auth].token_pepper` set, users created via `ai-memory user add`). Per-user tokens travel between clients and the server — sniffable over plain HTTP on the LAN. See [`docs/users.md`](users.md).+- **Multi-user mode is on** (at least one user row exists; `[auth].token_pepper`+ is the credential prerequisite). Per-user tokens travel between clients and+ the server — sniffable over plain HTTP on the LAN. See+ [`docs/users.md`](users.md).- **The server is bound beyond loopback** (`AI_MEMORY_BIND=0.0.0.0:49374` or a LAN-routable IP). Anyone on the network segment sees plaintext token traffic and `/web` cookies.- **You access `/web` from a different machine** than the one running ai-memory. The browser session cookie set after Basic auth lives in the clear over HTTP.- **You're exposing ai-memory beyond the LAN.** Cloudflare Tunnel or a public-domain Caddy with Let's Encrypt are the two patterns most homelab operators land on.diff --git a/docs/install.md b/docs/install.mdindex 5e15ef31..3e891161 100644--- a/docs/install.md+++ b/docs/install.md@@ -484,9 +484,9 @@ AI_MEMORY_NATIVE_TEST_IMAGE=quay.io/toolbx/arch-toolbox:latest scripts/test-nati## Configuring other agent CLIs-> `install-mcp --server-url` takes the MCP endpoint **including** `/mcp`-> (e.g. `http://homelab:49374/mcp`) — the rendered client config expects the-> full MCP URL. `install-hooks --server-url` takes the bare server **origin**+> `install-mcp --server-url` accepts either the bare server origin or the full+> MCP endpoint and appends a missing `/mcp` exactly once.+> `install-hooks --server-url` takes the bare server **origin**> (e.g. `http://homelab:49374`) — hook scripts append `/hook`, `/handoff`,> etc. themselves.@@ -498,9 +498,9 @@ Each agent CLI needs two things:Without this, the agent can still query memory but capturebecomes manual.-Claude Desktop is MCP-only today. Claude Code, Codex, Devin CLI, OpenCode,-OMP, Cursor, Gemini CLI, Antigravity CLI, Grok Build CLI, Kimi Code, and OpenClaw have lifecycle capture paths through-`install-hooks`.+Claude Desktop and VS Code Copilot are MCP-only today. The hook-capable clients+in the [README Support Matrix](../README.md#support-matrix), including Pi and+Zero, have lifecycle capture paths through `install-hooks`.> **Hook install pattern.** Local supported profiles default to host-native> commands. Claude Code may use its supported Windows exec form (`command` =@@ -510,7 +510,7 @@ OMP, Cursor, Gemini CLI, Antigravity CLI, Grok Build CLI, Kimi Code, and OpenCla> enforce capture-policy v1. Remote-only/Docker script installs still use the> two-step path: (1) `docker cp` bundled scripts to your home dir, (2)> `docker run --rm install-hooks` renders the config snippet.-> OpenClaw, OpenCode, and OMP are different: they use generated+> OpenClaw, OpenCode, OMP, and Pi are different: they use generated> TypeScript plugin/extension files, so no shell-script extraction is> needed for those clients.@@ -1201,7 +1201,7 @@ remains opt-in and keeps its interval-only behavior (no startup catch-up).----## Bootstrap mid-project {#bootstrap-mid-project}+## Bootstrap mid-projectWhen you adopt ai-memory in a project that's already been around fora while, the wiki starts empty. `ai-memory bootstrap` ingests the@@ -1388,7 +1388,7 @@ write to `~/.local/share/ai-memory/hooks/`.(`bin/deploy`, cloudflared TLS, env-file management)- [`docs/usage.md`](usage.md) - handoffs, proactive querying, web UI, slimrouting snippet + managed Agent Skills, migration from other memory tools, and raw-wiki inspection-- [`docs/mcp-install.md`](mcp-install.md) - per-client MCP config- reference for Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, OpenClaw, OMP, VS Code Copilot+- [`docs/mcp-install.md`](mcp-install.md) - per-client MCP config reference for+ every client in the [README Support Matrix](../README.md#support-matrix)- [`docs/ARCHITECTURE.md`](ARCHITECTURE.md) - what's actuallyrunning inside ai-memorydiff --git a/docs/marker-file.md b/docs/marker-file.mdindex d5856056..d618d940 100644--- a/docs/marker-file.md+++ b/docs/marker-file.md@@ -31,7 +31,7 @@ workspace-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 / OpenClaw TypeScript integrations. In all cases,+generated OpenCode / OMP / Pi / OpenClaw TypeScript integrations. In all cases,hook capture and handoff lookup send the same `cwd`, `workspace`, `project`,`project_strategy`, `drop_subagent`, `default_global`, `briefing`, and`briefing_budget` query params to the server when a marker declares them;@@ -308,7 +308,7 @@ repo root — so an agent that runs `mkdir sub && cd sub` and stays there nolonger forks the rest of the session into a phantom project named `sub`.This is **install-time config**, written into the agent's hook command (and-the generated OpenCode / OMP / OpenClaw plugins) — the same status as the+the generated OpenCode / OMP / Pi / OpenClaw plugins) — the same status as the`AI_MEMORY_AUTH_TOKEN` / `AI_MEMORY_HOOK_URL` it sits beside, *not* a user-setruntime override (which was deliberately rejected in #16). The flag accepts`basename` (the default — bakes nothing, behavior unchanged) or `repo-root`.diff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex 40c07cf1..50879739 100644--- a/docs/mcp-install.md+++ b/docs/mcp-install.md@@ -19,10 +19,10 @@This page documents how to register ai-memory as an MCP server withagent CLIs beyond the README quick start.-Claude Code, OpenAI Codex, Devin CLI, Cursor, Gemini CLI, Antigravity CLI, Grok Build CLI, Zero, Kimi Code, OpenClaw, OpenCode, and-OMP have automatic capture integrations (host-native commands for supported-local profiles, plus generated TypeScript plugin/extension files for OpenClaw /-OpenCode / OMP) and are covered in the [main README](../README.md#quick-start).+The hook-capable clients in the [README Support Matrix](../README.md#support-matrix)+have automatic capture integrations (host-native commands for supported local+profiles, plus generated TypeScript plugin/extension files for OpenClaw,+OpenCode, OMP, and Pi).Claude Code may use its supported Windows exec form; other agents use nativesingle command strings according to their hook schema. PowerShell/Git Bashscript bundles are compatibility fallbacks and do not enforce capture-policydiff --git a/docs/users.md b/docs/users.mdindex 667b188f..8798c286 100644--- a/docs/users.md+++ b/docs/users.md@@ -1,9 +1,7 @@# Multi-user attribution-> **Status:** v0.8 (rolling out across Phase 1 milestones P1.1–P1.8).-> This page documents what's already merged today; per-page-> attribution + frontmatter `last_modified_by` (P1.6) and `/api/v1`-> author surfacing (P1.7) ship in subsequent milestones.+> **Status:** Introduced in v0.8; this page documents the current shipped+> contract.ai-memory is **single-tenant data** with **optional multi-userattribution**. Every authenticated request sees the same wiki pages —@@ -149,7 +147,7 @@ The list never surfaces tokens — only their hashes are in the DB.`ai-memory user expire <username>` stamps `token_expired_at = now()`on the row. The user's bearer stops authenticating immediately, butthe row stays put so historical `author_id` references in-`audit_log` (and, after P1.6, in `pages`) keep resolving to their+`audit_log` and `pages` keep resolving to theirreal names.```console@@ -194,9 +192,10 @@ If you're upgrading from a pre-v0.8 ai-memory:`multi-user not enabled` message. Existing installs never tripthis because they never call `user add`.- `/admin/*` endpoints are open to the configured bearer token in- single-user mode, matching historical behavior. After you configure- `[auth].token_pepper`, every admin endpoint requires the root token;- DB-user tokens receive **403** and anonymous requests receive **401**.+ single-user mode, matching historical behavior. Creating the first user row+ immediately makes every admin endpoint root-only; DB-user tokens receive+ **403** and anonymous requests receive **401**. Merely configuring+ `[auth].token_pepper` does not activate that boundary.### Migrating an existing single-user install@@ -255,8 +254,8 @@ See `crates/ai-memory-store/src/users.rs` for the full rationale.| `/api/v1` page responses include `author: { username, name?, email? }` | ✓ P1.7 || ETag invalidation on author change (so caches refresh attribution) | ✓ P1.7 || `install-hooks --as-user <name>` metadata + flag validation | ✓ P1.8 |-| Web UI shows author on page view + list views | ⏳ follow-up commit (data is already on `/api/v1`) |-| `audit_log.author_id` populated on every write | ⏳ deferred (touches many ops; planned for next round) |+| Web UI shows author on the page view | ✓ shipped |+| Attributed mutation audit rows carry `audit_log.author_id` | ✓ shipped |Commit ids for each milestone are recorded in `CHANGELOG.md`.diff --git a/docs/windows.md b/docs/windows.mdindex 8cf8d8b0..0c646ebf 100644--- a/docs/windows.md+++ b/docs/windows.md@@ -311,8 +311,8 @@ Windows agent builds.Claude Code invokes hooks as a direct binary call (no shell) by default;`AI_MEMORY_HOOK_PLATFORM=windows-bash` restores the Git Bash `bash -c`path. WSL2 Claude Code uses normal WSL `.sh` paths.-- Codex, Devin CLI, OpenCode, Cursor, Gemini CLI, Grok Build CLI, Kimi Code,- and OpenClaw may each choose different+- Codex, Devin CLI, OpenCode, Cursor, Gemini CLI, Grok Build CLI, Zero,+ Kimi Code, and OpenClaw may each choose differentWindows config locations or shell execution behavior. ai-memory usesthe current best-known defaults, but they need validation on realinstallations.