Skip to content

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.md
index 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 path
families. Session, concept, procedure, note, and slot pages no longer surface
as generic facts, while an explicit frontmatter `kind` still takes precedence
diff --git a/README.md b/README.md
index 653715c6..e5799885 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@
> re-explaining the architecture, the failed approaches, or the open
> questions.
-[![status: v0.8 multi-user](https://img.shields.io/badge/status-v0.8--multiuser-green)](docs/ARCHITECTURE.md)
+[![Release](https://img.shields.io/github/v/release/akitaonrails/ai-memory)](https://github.com/akitaonrails/ai-memory/releases/latest)
[![Rust](https://img.shields.io/badge/rust-1.95+-blue)](rust-toolchain.toml)
[![License](https://img.shields.io/badge/license-MIT-blue)](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 slim
markered 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; users
created 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 the
four-rung auth ladder.
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 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.rs
index 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.rs
index 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.md
index 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. No
manual `write_note` ceremony, no copy-pasting summaries between
sessions.
@@ -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` rewrites
that summary into a richer durable page or fans out into a
multi-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-mini
ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / LLM_API_KEY
AI_MEMORY_LLM_BASE_URL for openai-compat (Ollama, vLLM)
COPILOT_GITHUB_TOKEN optional GitHub token for copilot
diff --git a/docs/deploy.md b/docs/deploy.md
index 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 needed
cp 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-memory
install-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's
middleware validates with a constant-time comparison.
**Encrypted transport.** Plain HTTP on the LAN means anyone with a
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 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 shape
diff --git a/docs/https-via-proxy.md b/docs/https-via-proxy.md
index 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 these
apply:
-- **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.md
index 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 capture
becomes 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-project
When you adopt ai-memory in a project that's already been around for
a 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, slim
routing 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 actually
running inside ai-memory
diff --git a/docs/marker-file.md b/docs/marker-file.md
index 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)` for
handoff 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 no
longer 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-set
runtime 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.md
index 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 with
agent 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 native
single command strings according to their hook schema. PowerShell/Git Bash
script bundles are compatibility fallbacks and do not enforce capture-policy
diff --git a/docs/users.md b/docs/users.md
index 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-user
attribution**. 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, but
the 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 their
real 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 trip
this 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.md
index 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 different
Windows config locations or shell execution behavior. ai-memory uses
the current best-known defaults, but they need validation on real
installations.