Skip to content

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

Rust

docs(readme): lead with the differentiators, move detail into linked docs

AkitaOnRailsb1595623c06f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8f810742..89909c5b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -333,6 +333,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Docs
+- Reworked the README around the September 2026 research pass: a humanized
+ "Why ai-memory" differentiator section and "How it works" flow up top, a
+ compact support matrix, and a shorter quick start. Detail sections moved
+ verbatim into linked docs: `docs/support-matrix.md` (full per-agent matrix),
+ `docs/use-cases.md`, `docs/llm-providers.md`, and `docs/security.md`.
+ Added `docs/research-2026-landscape.md` and follow-up pointers in the four
+ May 2026 research documents.
- `docs/windows.md` gains **Scenario E**, a persistent-server story for native
Windows. Scenarios C and D both ended at `ai-memory serve` in a foreground
terminal, while Linux got `Restart=on-failure` from the packaged systemd
diff --git a/README.md b/README.md
index 87fbe385..1b7c77eb 100644
--- a/README.md
+++ b/README.md
@@ -14,418 +14,108 @@
[![Rust](https://img.shields.io/badge/rust-1.95+-blue)](rust-toolchain.toml)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
-## Support Matrix
+## Why ai-memory
+
+Your coding agent already has a memory feature. Claude Code takes its own
+notes, Cursor remembers some things, and every platform is adding more. All
+of them share the same walls: the notes live on one machine, belong to one
+agent, and vanish from view the moment you switch tools — or teammates.
+
+ai-memory is what's on the other side of those walls.
+
+- **It follows you across agents.** Twenty-plus harnesses — Claude Code,
+ Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro, and more —
+ feed one shared memory. Quit Claude Code mid-task, open Codex in the same
+ directory, and the next agent picks up a real handoff: where you left
+ off, what failed, what's still open. Handoffs are a protocol here, not a
+ convention — typed, owned, claimed exactly once.
+
+- **It follows you across machines.** Memory lives in a server you run —
+ on the same laptop, a homelab box, or wherever — so the project you left
+ on the desktop is the project you resume on the laptop. Same knowledge,
+ same open questions.
+
+- **It works for a team.** Point everyone at one server and what one
+ person's sessions learn, everyone's agents can retrieve. Knowledge is
+ shared per project; personal handoffs stay personal. Multi-user auth,
+ per-person attribution, and an audit log are built in — not a paid tier.
+
+- **Your memory is plain markdown.** The source of truth is a git-backed
+ wiki of ordinary `.md` files: `grep` it, open it in Obsidian, edit it by
+ hand, `rsync` it. The database is a derived index that can always be
+ rebuilt from the files. No vector store to babysit, nothing held hostage
+ in a binary blob.
+
+- **It captures the work itself, silently.** Lifecycle hooks record what
+ actually happened — prompts, tool calls, session boundaries — sanitized
+ at a typed privacy boundary before anything is stored, then consolidated
+ into readable pages. No "remember this" ceremony. And the default path
+ uses **zero LLM calls**: capture, search, and handoffs all work with no
+ API key at all.
+
+- **It tells you the truth about itself.** One self-contained binary.
+ Purge commands that say exactly what "deleted" means. A measured write
+ ceiling (~700/s) instead of a guessed one. An audit log of every
+ mutation. Boring, in the way infrastructure should be.
+
+## How it works
-| Area | Status | Notes |
-|---|---|---|
-| Linux | Supported | Primary Docker/server target and CI platform. Published Docker images support `linux/amd64` and `linux/arm64`. Native Arch/AUR packages include system and user systemd units. |
-| macOS | Supported | Workspace tests run in CI; tagged releases publish native `ai-memory-macos-aarch64.tar.gz` and `ai-memory-macos-x86_64.tar.gz` binaries. The native binary is the recommended path on Apple Silicon. See [`docs/macos.md`](docs/macos.md). |
-| Windows via WSL2 | Supported | Use the Linux install path inside WSL2 when the agent runs there. |
-| Native Windows | Experimental | Tagged releases publish `ai-memory-windows-x86_64.zip` with `ai-memory.exe`; Docker Desktop wrapper and source builds are also available. Local supported profiles default to host-native hook commands; Claude Code may use its Windows exec form, while other agents use native single command strings matching their hook schema. PowerShell/Git Bash scripts are compatibility fallbacks. See [`docs/windows.md`](docs/windows.md). |
-| Claude Code | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. `install-mcp --session-aware` optionally enables per-session auto-scope isolation through a local stdio bridge. Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default). |
-| Codex | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. No automatic true session-end hook, so run `ai-memory finalize-session` when you need a final summary/handoff. |
-| Command Code | Supported | MCP config (`~/.commandcode/mcp.json`) + its four stable lifecycle-hook events (`~/.commandcode/settings.json`); native commands enforce capture exclusions and `SessionStart` injects handoffs. `Stop` is only a turn boundary, so use `ai-memory finalize-session --agent command-code` after the final turn. `ai-memory run command-code` adds exact v3 native-session resume and visible-event import; experimental unsandboxed Mods remain excluded. |
-| Devin CLI | Supported | MCP config + lifecycle hooks. Hooks use Devin's `PostCompaction` event, inject handoffs via `hookSpecificOutput.additionalContext`, and omit subagent events because Devin does not expose them. |
-| OpenCode | Supported | Remote MCP config + generated TypeScript plugin; generated plugin enforces capture exclusions. |
-| Cursor | Supported | MCP config + lifecycle hooks. |
-| Gemini CLI | Supported | MCP config + lifecycle hooks. |
-| Oh My Pi / OMP | Supported | Use `--client omp` / `--agent omp` (or `oh-my-pi`) for native `.omp` MCP config + TypeScript extension; generated extension enforces capture exclusions. |
-| Pi | Supported | Generated `~/.pi/agent/extensions/ai-memory-pi.ts` extension provides lifecycle capture and an HTTP MCP bridge; generated extension enforces capture exclusions. |
-| Crush | Managed-only | `ai-memory run crush` resumes its project-local session database and supplies portable context through a temporary supported global-context file; no lifecycle-hook installer is provided. |
-| Managed workstreams | Opt-in | `ai-memory run` provides transparent cross-harness continuity for Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, both incompatible Kiro CLI engines, OMP, Grok Build CLI, and Antigravity CLI. Direct launches remain unchanged. See [`docs/managed-workstreams.md`](docs/managed-workstreams.md). |
-| Claude Desktop | MCP-only | Uses `mcp-remote`; no lifecycle hooks. |
-| OpenClaw | Supported | MCP config + native plugin lifecycle hooks; generated plugin enforces capture exclusions. |
-| Antigravity CLI | Supported | MCP config (`serverUrl`) + lifecycle hooks (`agy` alias). Only `PreInvocation` with `invocationNum = 0` maps to SessionStart; later model calls cannot consume a next-session handoff. No automatic true session-end hook, so run `ai-memory finalize-session --agent antigravity-cli` after the final turn when you need a summary, handoff, and opt-in SessionEnd consolidation. `ai-memory run antigravity` (aliases `antigravity-cli`, `agy`) adds managed workstream resume via `--conversation`; conversation text is not decoded, so the ledger for this harness comes from hook capture. |
-| Grok Build CLI | Supported | MCP config (`install-mcp --client grok` → `$GROK_HOME/config.toml`, default `~/.grok/config.toml`) + lifecycle hooks (`install-hooks --agent grok` → `$GROK_HOME/hooks/ai-memory.json`, default `~/.grok/hooks/ai-memory.json`, Grok-specific hook bundle). Capture works; no hook handoff injection — Grok ignores `SessionStart` stdout, so recover handoffs via MCP `memory_handoff_accept`. `ai-memory run grok` adds managed workstream resume with the context packet delivered natively through `--rules`. Skills root: `.grok/skills` / `$GROK_HOME/skills` (default `~/.grok/skills`). |
-| Swival CLI | MCP-only | `install-mcp --client swival --apply` merges a native HTTP entry into the project-root `.swival/mcp.json`, preserving sibling servers. Lifecycle and managed-workstream support are not claimed because Swival's callback contract does not expose a stable session identifier. |
-| Zero | Supported | `install-mcp --client zero` (native HTTP + bearer in `~/.config/zero/config.json`) + lifecycle hooks via `install-hooks --agent zero --apply` (exec-form native commands in `~/.config/zero/hooks.json`, JSON payload on stdin, no shell). Capture works incl. specialist (subagent) events; no handoff injection — Zero discards `sessionStart` stdout, so recover handoffs via MCP `memory_handoff_accept`. |
-| ZCode | MCP-only | `install-mcp --client zcode --apply` merges a native HTTP entry (strict schema: `type`/`url`/`headers` only) into the `mcp.servers` map of `~/.zcode/cli/config.json`, preserving sibling servers. Lifecycle hooks are not yet available — see #512. |
-| Kimi Code | Supported | MCP config (`url` entry in `~/.kimi-code/mcp.json`) + lifecycle hooks (`[[hooks]]` in `~/.kimi-code/config.toml`, 10 events including subagent start/stop and `PostToolUseFailure` for tool-failure capture); both paths honor `$KIMI_CODE_HOME`. Handoffs inject via `UserPromptSubmit` stdout (Kimi Code discards `SessionStart` hook stdout); `ai-memory run kimi` adds managed workstream resume. |
-| Kiro CLI | Supported | MCP config uses `install-mcp --client kiro-cli` (alias `kiro`) and Kiro's Bedrock-compatible schema flavor. `install-hooks --agent kiro-cli` merges v2 hooks into existing agent configs; the explicit `--agent kiro-cli-v3` target writes the incompatible standalone v3 registration. Both preserve unrelated entries, honor `$KIRO_HOME`, enforce capture exclusions, and inject pending handoffs at session start. Kiro has no true SessionEnd hook; use `ai-memory finalize-session --agent kiro-cli`, with `--session-id <uuid>` for concurrent sessions. `ai-memory run kiro` manages v2; add `--v3`, `--mode`, or `--agent-engine v3` for version-safe v3 resume. |
-| Pool | Hooks-only | Poolside Agent CLI (`pool`). Lifecycle-hook capture via `install-hooks --agent pool` (alias `poolside`): Pool reads project-scoped hooks from the repo-root `.poolside/settings.yaml`, so ai-memory stages the scripts and prints a ready-to-paste `hooks:` snippet rather than writing project-local files; native commands enforce capture exclusions. Five Claude-shaped events (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`) and no true session-end — `Stop` is a turn boundary, so run `ai-memory finalize-session --agent pool` after the final turn. `SessionStart` stdout injection is not demonstrated, so capture works but handoff injection does not — recover handoffs via MCP `memory_handoff_accept`. No first-party `install-mcp` client and no managed workstream (`ai-memory run pool`) are claimed: Pool's native session-store contract is not demonstrated (see [`docs/managed-harness-contributions.md`](docs/managed-harness-contributions.md)). Verified against Poolside CLI v1.0.16. |
-| ZCode | Hooks-only | ZCode (z.ai, `zcode`, alias `zai`). Lifecycle-hook capture via `install-hooks --agent zcode --apply`: exec-form native commands (`type: "process"`, no shell) merged into the root `hooks` block of `~/.zcode/cli/config.json` around any third-party hooks; native commands enforce capture exclusions. Six documented triggers (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`); `PostToolUseFailure` fires instead of `PostToolUse` when a tool throws and lands on the same capture channel with the error preserved. `PermissionRequest` is deliberately not installed — its hook chain races the interactive permission client, so passive capture of that event is unreliable by design. No true session-end — `Stop` is a per-turn boundary, so run `ai-memory finalize-session --agent zcode` after the final turn. Unlike Pool and Zero, `SessionStart` stdout injection works (`hookSpecificOutput.additionalContext`, verified live against the embedded engine v0.16.5), so the prior session's handoff is delivered automatically. No first-party `install-mcp` client and no managed workstream are claimed yet. |
-| VS Code Copilot | MCP-only | `.vscode/mcp.json` for Copilot agent mode; no lifecycle hooks (Copilot does not expose them yet). |
-| Zed | MCP-only | Native remote MCP under `context_servers` in Zed's user `settings.json`; no lifecycle hooks or managed-workstream support. |
-| Hermes Agent | Community | Core hook ingestion recognizes `agent=hermes` and Hermes' documented shell-hook `tool_name` / `tool_input` payload for concrete session attribution, tool-family titles, and capture exclusions. A community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) is available, but no first-party installer is shipped; review its compatibility matrix, install/uninstall scripts, and secret handling before using it. Hermes ignores session-start hook stdout, so recover handoffs through MCP. |
-| LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode Zen/Go, OpenAI-compatible endpoints, and generic OIDC device auth for native hooks. |
-| Embedding providers | Supported | OpenAI, Voyage, Google Gemini, and keyless OpenAI-compatible endpoints such as Ollama, LM Studio, and vLLM. |
-
-## What it is
-
-LLM coding agents lose context when a session ends. ai-memory gives them a
-shared, persistent wiki compiled from sanitized lifecycle observations. When a
-session ends, relevant observations become a coherent summary; the next agent
-receives a bounded handoff. Optional `ai-memory run` launches add a portable
-visible-event ledger and native per-harness resume for higher-fidelity
-cross-harness continuity.
-
-The wiki is plain markdown in a git repo - `grep`-able, openable in
-Obsidian, backed up with `rsync`. No vector database to babysit, no
-`write_note` ceremony, no manual context-loading. The full design is
-in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md); the influences and
-priors are at the [bottom](#influences-and-prior-art).
-
-## Key features
-
-- **Zero-friction lifecycle capture.** Hooks fire-and-forget bounded,
- sanitized prompt, tool-lifecycle, and session-boundary observations. Direct
- launches keep this lightweight path; it is not a complete native transcript.
- User prompts and post-compaction summaries retain up to 16 KiB;
- notifications and tool excerpts retain up to 2 KB, with a 16 KiB durable
- backstop for every observation body.
-- **Opt-in managed workstreams.** `ai-memory run claude`, then `ai-memory run
- codex --yolo`, then `ai-memory run command-code`, transparently resumes one
- logical workstream with native per-harness sessions, a portable visible-event
- ledger, and full-ledger search. Delivered packets are origin-marked; Claude
- transcript import rejects a packet that Claude persisted and read back through a tool.
- `ai-memory run` with no harness continues the newest usable Claude Code,
- Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, or Kiro CLI v2/v3
- session for this checkout.
- On first
- explicit use, an interactive launcher can adopt a previous session from the
- same checkout; later switches cannot select unrelated native history. Native
- arguments pass through unchanged except the wrapper-owned `--yolo` and
- `--fresh`; direct
- commands are unaffected. `kimi-code` and `kimi-cli` are accepted aliases for
- the installed `kimi` command; `commandcode`, `cmdc`, and `cmd` select the
- cross-platform `command-code` executable (`cmdc` on native Windows); and
- `kiro-cli` selects the installed `kiro-cli` command. Kiro defaults to v2;
- `ai-memory run kiro --v3` selects v3, while a
- returning linked v3 workstream selects its engine transparently.
-- **Per-repository capture exclusions.** A nearest-marker `[capture]`
- `ignore_paths` policy drops matching recognized file-tool events before they
- reach the local spool or server. See [the capture policy reference](docs/marker-file.md#capture-exclusions).
-- **Opt-in capture scope.** `install-hooks --capture-mode allowlist` inverts
- the default so a repository without a marker emits no lifecycle event at
- all, dropped by the native hook before the spool. Forgetting a marker then
- costs recall rather than confidentiality. Enforced by native `ai-memory
- hook` commands only — see [allowlist mode](docs/marker-file.md#allowlist-mode-the-marker-as-an-opt-in).
-- **Optional per-operator memory slots.** On shared servers,
- `[slots] per_user = true` keeps engine-written `_slots/` context in a bounded
- namespace derived from the authenticated operator. Session briefs and
- consolidation prompts receive shared slots plus the caller's own; exact wiki
- reads and searches remain project-wide, so this is context-injection
- isolation rather than RBAC. See [multi-user operation](docs/users.md#per-operator-memory-slots).
-- **Cross-agent handoffs.** Quit Claude Code mid-task, start Codex
- in the same directory hours later - the next agent sees a
- "where you left off" block before its first prompt.
-- **Per-project isolation by construction.** Each project lives at
- `<wiki_root>/<workspace_id>/<project_id>/…` keyed by stable UUIDs.
- Workspace defaults to `"default"`. Project is derived from `$cwd`:
- CLI subcommands (`bootstrap`, `write-page`, `lint`, …) walk to the
- main git repo root so all worktrees of the same repo share one
- project identity; the hook router defaults to `basename($cwd)` and
- can opt into the repo-root rule. Drop a
- [`.ai-memory.toml` marker file](docs/marker-file.md) in any
- ancestor directory to override either field explicitly — perfect for
- multi-client consultancies, work/personal split, mono-repos, or
- linked git worktrees.
- Same page path can exist in two projects without collision; a
- rename is one column update; a purge is one `rm -rf`.
-- **Global preferences scope.** Standing user/team context — tech
- choices, code style, durable personal rules — lives in the reserved
- `_global` scope (`memory_write_page` with `scope: "global"`). Default
- `memory_query` reads union it into every project as
- `global_scope_hits`, so preferences travel with you into new projects
- without naming a magic project or paying the all-projects
- `global=true` fan-out. Event capture never writes there.
-- **Entity-assisted recall.** Consolidation stores up to 10 specific nouns per
- page in canonical `entities:` frontmatter. Exact, prefix, and compound-word
- matches form a project-scoped RRF stream, so a query can recover a page even
- when its body uses different wording. The stream is lexical and adds no
- query-time LLM call.
-- **Authority-aware recall.** FTS5, entity-match RRF, graph-neighbor RRF, and
- optional vector RRF generate candidates by relevance. Before truncation, a
- bounded adjustment favors maintained `_rules/`, `decisions/`, `procedures/`, and
- `gotchas/` pages over closely matching episodic session evidence. Tier,
- `pinned`, and explicit `canonical` / `active` / `source-of-truth` or
- `superseded` / `historical` / `test-fixture` / `do-not-answer-from` tags
- contribute without becoming absolute filters, so targeted history searches
- still find session pages. These signals affect retrieval provenance only;
- retrieved text remains untrusted historical evidence and never gains
- instruction authority from its namespace, tier, tags, pin, or rank.
-- **Clear routing alongside code-intelligence tools.** Run ai-memory beside a
- structural MCP server, LSP, or other live-code tool without synchronizing
- their stores. Use memory for prior decisions, rationale, failed attempts,
- procedures, and handoffs; use the current checkout and structural provider
- for symbols, callers, dependencies, and impact analysis. Verify historical
- code claims against the checkout before acting, and treat source, builds,
- tests, and observed runtime behavior as operational truth. See
- [Historical memory and live code intelligence](docs/usage.md#historical-memory-and-live-code-intelligence).
-- **Karpathy-style LLM wiki.** Pages are compiled from observations
- at session-end (or PreCompact; clients without a true session-end event can
- use `ai-memory finalize-session --agent <agent>` for a manual final close),
- not retrieved over raw logs.
- Supersession chain + git-versioned markdown means you can
- time-travel with `ai-memory checkpoints`, `restore-page`, or raw `git log`.
-- **Built-in `/web` browser.** Read-only HTML UI for the wiki -
- project list, folder tree, FTS5 search, markdown rendering, dark
- mode. Mounted on the same axum server as MCP.
-- **Server-wide MCP client activity.**
- `GET /admin/activity/by-client?since_days=7` shows which MCP clients are
- calling memory tools, split into reads and writes. Counts use bounded UTC-day
- buckets, so arbitrary client names cannot grow the database with request
- volume; shared deployments keep the endpoint root-only. See
- [MCP client activity](docs/users.md#mcp-client-activity).
-- **Multi-agent + multi-machine ready.** Supported clients: Claude
- Code, Codex, Command Code, Devin CLI, OpenCode, Cursor, Claude Desktop (via `mcp-remote`),
- Gemini CLI, Antigravity CLI, Grok Build CLI, Kimi Code, OpenClaw, Oh My Pi
- / OMP (`omp` / `oh-my-pi`), Pi via generated bridge extension, VS Code
- GitHub Copilot agent mode (MCP-only, workspace `.vscode/mcp.json`), Kiro CLI
- (MCP + v2 lifecycle hooks), Pool (hooks-only, project
- `.poolside/settings.yaml` snippet), ZCode (hooks-only, exec-form native
- commands in `~/.zcode/cli/config.json`), and Zed (MCP-only, user `settings.json`).
- Server runs local (loopback) OR on a homelab box (LAN/VPN/cloud)
- with bearer-token auth. Shared servers can opt into
- [`[auto_scope]` modes](docs/auto-scope.md) for per-user or
- session-aware current-project routing; Claude Code has a built-in opt-in
- bridge via `install-mcp --session-aware`.
-- **Thin-client CLI.** `ai-memory status`, `bootstrap`, `checkpoints`,
- `restore-page`, `purge-project`, `purge-session`, `rename-project`, `move-project`,
- `move-session`,
- `audit-contamination`, `lint`, `curator`, `auto-improve`,
- `auto-improve-report`, `pending-writes`, `embed`, `forget-sweep`, `backup`,
- `finalize-session` are
- all HTTP clients of the running server - never touch SQLite or
- wiki files directly. `status` also reports passive LLM/embedding
- provider health from the last real provider call. Server is the
- single source of truth. `finalize-session` lists matching open
- sessions through `GET /admin/open-sessions`, then posts synthetic
- `session-end` hooks back to the server. On shared deployments it defaults to
- the caller's own plus unattributed sessions; root can pass `--all-owners` for
- explicit cross-operator recovery. When concurrent sessions share an agent and
- scope, pass `--session-id <uuid>` to target one exact open session; it cannot
- be combined with `--all`.
-- **LLM is opt-in.** Zero-LLM mode still gives you FTS5, manually declared
- entity, and graph-neighbor search plus rule-based summarisation. Add a
- provider when you want consolidated pages, lint contradictions, or staged
- auto-improvement proposals.
-
-## Use cases
-
-- **"Quit Claude Code and continue the same work in Codex."** Use the optional
- managed launcher when you want native session resume plus the portable visible
- history, not only a summary handoff:
-
- ```bash
- cd /path/to/project
- ai-memory run claude
-
- # Quit Claude Code, then continue the same workstream in Codex.
- ai-memory run codex --yolo
-
- # Continue in Command Code, preserving its own exact native session.
- ai-memory run command-code
-
- # Later, omit the name to resume the newest usable managed session here.
- ai-memory run
-
- # Start a new Codex session in the same workstream, keeping portable history.
- ai-memory run --fresh codex
-
- # Kiro defaults to v2; select its incompatible v3 engine explicitly once.
- ai-memory run kiro --v3
-
- # List the workstreams that can be selected from this checkout.
- ai-memory workstreams
-
- # Fix a name you regret; the ledger and the current selection stay put.
- ai-memory rename-workstream --from typo-nmae --to refactor-db
-
- # Pick a managed workstream from any linked local checkout, then resume it.
- ai-memory resume
-
- # List open cross-agent handoffs, oldest first, with the id
- # `memory_handoff_cancel` needs to clear a stale one.
- ai-memory handoffs
- ```
-
-- **"Pick the project instead of remembering where it lives."** Start from a
- directory containing your checkouts and choose the checkout before the
- managed harness:
-
- ```bash
- ai-memory show
-
- # Machine-readable discovery without launching anything.
- ai-memory show --json
- ```
-
- Each successful `ai-memory run` saves a client-local checkout link keyed by
- the configured server plus workspace/project. `show` joins those links with
- the server's public activity and page-count metadata. A fast, bounded depth-1
- scan of the current directory also finds new checkouts carrying a project
- marker (`.git`, `Cargo.toml`, `package.json`, `go.mod`, `pyproject.toml`, and
- friends), while skipping dependency and build directories. The server never
- exposes a checkout path, so two client machines can safely use different
- local paths for the same project on a remote homeserver.
-
- The list always leads with **`+ New project`**: type a name and ai-memory
- validates a portable directory name, stages the new checkout privately, pins
- its workspace and project in `.ai-memory.toml`, and installs the routing block
- and managed Agent Skills for the chosen agent. The final directory appears
- only after every setup step succeeds, then `show` launches from it.
-
- The harness menu only offers agents actually installed on the host, using the
- same `PATH` lookup `run` enforces at launch.
-
- `--no-scan` uses only saved links; `--workspace` filters both sources;
- `--yolo`, `--fresh`, and trailing native arguments are forwarded unchanged.
- Non-terminal use must pass `--json`; JSON mode is discovery-only and never
- launches a harness.
-
- The first explicit run can offer an existing session from this exact checkout
- or start a new one. Switching harnesses starts or resumes the native session
- linked to the shared workstream, so an obsolete local session cannot replace
- newer cross-harness history. After a normal quit, the next launch waits
- briefly if the previous launcher is still finalizing; handled failures release
- the workstream immediately. If a linked native transcript was deleted,
- ai-memory detects the orphan before launch and starts fresh; `--fresh` forces
- that recovery for one harness. Managed mode currently covers Claude Code,
- Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, Kiro CLI v2/v3, OMP,
- Grok Build CLI, and Antigravity CLI; direct harness launches remain unchanged. See
- [Managed cross-harness workstreams](docs/managed-workstreams.md).
-- **"Just put me back where I was."** From any directory, with no name to
- type and no list to read:
-
- ```bash
- ai-memory continue
- ```
-
- It picks the checkout whose managed launch is most recent, revalidates the
- path and its resolved scope, then continues there exactly as bare
- `ai-memory run` would. A link whose directory moved, was replaced, now
- resolves to a different project, or has a corrupt ordering timestamp is
- reported on stderr and skipped, so a resume never quietly lands in the wrong
- project. `--workspace` narrows the search; `--yolo` and `--fresh` are
- forwarded.
-- **"Let me choose which workstream to resume."** From any directory, select
- one of the recent workstreams from your valid client-local managed checkouts:
-
- ```bash
- ai-memory resume
- ai-memory resume --workspace work
- ```
-
- The picker shows the workstream name, project scope, activity, and linked
- harnesses. Use Up/Down (or `j`/`k`) to choose a workstream and Left/Right to
- cycle its launch harness. Every row starts at `auto`, preserving normal
- session discovery; the other choices are supported harnesses currently found
- in `PATH`. Enter launches the displayed combination. The checkout is
- revalidated first, while the server continues to receive fingerprints rather
- than a local path. Use `ai-memory workstreams` when you are already in a
- checkout and only want the read-only list.
-- **"Quit at 4 PM, pick up at 9 AM in a different agent."** The
- classic. SessionStart hook in the next supported hook client prepends a
- typed handoff with open questions, next steps, and a session summary. Grok
- captures lifecycle events but ignores SessionStart stdout, so ask it to call
- `memory_handoff_accept` when resuming from a handoff. Zero has the same
- no-stdout behavior and also must call `memory_handoff_accept`.
-- **"What did we decide about X six weeks ago?"** Use `memory_query X` from
- the agent for FTS5 fused with entity matches and linked-page expansion (plus
- vector similarity when an embedder is configured). For a quick terminal-only
- FTS5 lookup, use `ai-memory search X`; that admin command does not run the
- hybrid streams. Pages are
- LLM-consolidated, so the hit is a coherent decision page, not a raw
- chat log. Pass `explain: true` to see why each hit ranked where it
- did in project or explicit-scope retrieval. Cross-project
- `global: true` search uses its separate FTS-only ranker and reports
- that active stream without per-hit RRF details.
-- **"Remember this permanently."** When something is worth keeping
- beyond auto-captured session logs - a decision, a convention, a
- gotcha - tell the agent "save a permanent note that we standardised
- on Postgres for X" or "annotate this as a project rule" and it calls
- `memory_write_page` to write a durable, git-versioned wiki page. From
- a terminal it's `ai-memory write-page --path decisions/0007-db.md
- --body $'# Standardised on Postgres\n\n...' --pinned`. `--pinned`
- exempts it from the decay sweep; the H1 on the first line of
- `--body` becomes the page title (omit `--title` — it's still
- accepted, but LLM callers trip over JSON-escaping their way through
- it, see issue #67). Unlike a handoff (single-use) or an
- auto-synthesised session page (rewritten on consolidation), a
- write-page note is yours: it shows up in `memory_query`, renders in
- `/web`, and stays until you change it.
-- **"That page you found is out of date."** The agent calls
- `memory_feedback` with the page's path and a signal: `helpful` /
- `not_helpful` tune how strongly retention keeps a sweep-eligible episodic
- page (they move its salience, which scales the decay formula's time term),
- while `stale` / `wrong` floor the salience *and* make any current page
- show up as a `feedback_flagged` finding in the next `memory_lint` report.
- Feedback never deletes anything — it lowers confidence and flags for review —
- and it attaches to the version current when feedback is recorded, so a
- later rewrite clears the flag. Retrieved page text is untrusted and never
- authorizes feedback by itself.
-- **"Remember this, but only until the sprint ends."** Pass
- `expires_at` to `memory_write_page` (RFC3339 or `YYYY-MM-DD` = end of
- that day, UTC) — or put `expires_at:` in a page's frontmatter by
- hand. Past the TTL the page disappears from search/recent/briefing
- (pass `include_expired: true` to `memory_query` to still see it) and
- the next forget sweep hard-deletes the file and its rows. A TTL beats
- a pin; `memory_lint` warns about pinned+expiring combos.
-- **"This new project has months of history before ai-memory."**
- `cd /path/to/my-project && ai-memory bootstrap` collects
- `git log`, README, `docs/`, module headers, project rules and
- one-shot-summarises them into seed wiki pages. Future sessions
- build on top.
-- **"What durable lesson did that session teach?"**
- When an LLM provider is configured, ai-memory runs a background
- auto-improvement scheduler for newly completed sessions in every project. It
- records proposed wiki edits in the pending-writes audit trail, then approves
- them immediately through the normal wiki write path by default. Scheduler ticks
- are non-overlapping: if reviewing all projects takes longer than the interval,
- the next tick is delayed until the current one finishes. Scheduling and
- approval are separate: set `[auto_improve.scheduler] enabled = false` to stop
- automatic review, or set `[auto_improve] require_approval = true` to keep both
- scheduled and manual proposals pending for human review. `ai-memory
- auto-improve --session-id <uuid>` and MCP `memory_auto_improve` remain
- available for manual catch-up or targeted reruns. When its `session_id` is
- omitted, the MCP tool selects the newest completed session without a
- persisted auto-improvement run, so repeated calls advance past short
- preflight-skipped sessions; an explicit ID reruns that session. `ai-memory
- auto-improve-report --workspace <w> --project <p>` returns a read-only
- telemetry report for recent auto-improvement outcomes without staging or
- creating proposals; add `--stage` to create one pending report page for
- audit/approval. On deployments that distinguish operators, pending learning
- proposals are isolated by qualified operator identity, so one person's
- proposal for a page does not block another's; unattributed and single-user
- deployments retain the shared pending queue. See
- [`docs/auto-improve-eval-gates.md`](docs/auto-improve-eval-gates.md) for
- example executable eval scorers.
+```
+capture ──▶ consolidate ──▶ recall ──▶ handoff
+ hooks session-end search next agent,
+ observe summaries as + brief any harness
+ silently wiki pages injection
+```
- Existing installs do not need per-project migration. The scheduler initializes
- a per-project first-run watermark so historical sessions are not reviewed
- automatically on upgrade, then records per-session claims so failed scheduled
- reviews do not retry forever; use manual auto-improve for old sessions or
- failed scheduled sessions you want to catch up. Older configs may still contain
- an `[auto_improve] mode = ...` line; current ai-memory ignores that legacy key,
- so you can remove it when convenient.
-- **"What housekeeping should I consider?"**
- `ai-memory curator` runs a no-LLM, rule-based maintenance report over cold
- episodic pages, stale slots, duplicate exact normalized titles, and dangling
- cross-project links. It is report-only unless `--stage` is passed; staging
- queues one report page for approval and still performs no maintenance actions
- itself. Shared servers can opt into `[decay] breadth_weight` to give pages
- reinforced by several identified operators a retention bonus; the default
- `0.0` leaves existing retention scores unchanged.
-- **"Run one ai-memory for the whole household."** Stand the server
- up on a homelab box at `0.0.0.0:49374` with a bearer token; every
- laptop/desktop talks to it. Per-cwd routing keeps each project's
- pages cleanly separated; the `/web` UI is reachable from a
- browser anywhere on the LAN.
-- **"Audit what landed before sharing with a teammate."** Browse
- the wiki at `http://<server>:49374/web` - sign in with username and
- password when human auth is on. Per-project tree view,
- rendered markdown, supersession chain visible per page.
-- **"Undo one bad page edit without rolling back the whole server."**
- `ai-memory checkpoints` shows recent wiki commits, then
- `ai-memory restore-page --path notes/foo.md --from <rev>` restores that one
- markdown file and reindexes it into SQLite. Full `backup` / `restore` is
- still the answer for DB-only state such as sessions, observations, handoffs,
- users, audit rows, and embeddings.
-- **"Drop an experiment, keep the rest."**
- `ai-memory purge-project --project experimental --confirm`.
- Atomic: that project's DB rows cascade away, its wiki subdir gets
- `rm -rf`'d, every sibling project is untouched by construction.
+Agents emit sanitized observations through lifecycle hooks as you work.
+At session end, observations become coherent markdown pages in the
+project's wiki (optionally LLM-written; useful even without). The next
+session — any agent, any machine — gets a bounded brief and can search
+everything: full-text, entities, links, and (optionally) vectors, fused
+into one ranking. Cross-agent handoffs carry the baton explicitly.
+
+The full design, including the invariants that keep multi-user and
+multi-session use safe, is in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+
+## Support matrix
+
+Every row below is a first-party integration — MCP registration, lifecycle
+hooks, or both — kept honest by CI. The full matrix with per-agent notes and
+caveats is in [`docs/support-matrix.md`](docs/support-matrix.md).
+
+| Area | Status |
+| --- | --- |
+| Linux | Supported |
+| macOS | Supported |
+| Windows via WSL2 | Supported |
+| Native Windows | Experimental |
+| Claude Code | Supported |
+| Codex | Supported |
+| Command Code | Supported |
+| Devin CLI | Supported |
+| OpenCode | Supported |
+| Cursor | Supported |
+| Gemini CLI | Supported |
+| Oh My Pi / OMP | Supported |
+| Pi | Supported |
+| Crush | Managed-only |
+| Managed workstreams | Opt-in |
+| Claude Desktop | MCP-only |
+| OpenClaw | Supported |
+| Antigravity CLI | Supported |
+| Grok Build CLI | Supported |
+| Swival CLI | MCP-only |
+| Zero | Supported |
+| ZCode | MCP-only |
+| Kimi Code | Supported |
+| Kiro CLI | Supported |
+| Pool | Hooks-only |
+| ZCode | Hooks-only |
+| VS Code Copilot | MCP-only |
+| Zed | MCP-only |
+| Hermes Agent | Community |
+| LLM/auth providers | Supported |
+| Embedding providers | Supported |
## Quick start
@@ -519,24 +209,6 @@ docker run -d --name ai-memory \
# for additional agents; full list in docs/install.md.
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply
-# Grok Build CLI example:
-# ai-memory install-mcp --client grok --apply
-# ai-memory install-hooks --agent grok --apply
-# Kiro CLI v2 example (requires an existing Kiro agent config):
-# ai-memory install-mcp --client kiro-cli --apply
-# ai-memory install-hooks --agent kiro-cli --apply
-# Kiro CLI v3 example (standalone hook registration):
-# ai-memory install-hooks --agent kiro-cli-v3 --apply
-# Command Code stable MCP + lifecycle example:
-# ai-memory install-mcp --client command-code --apply
-# ai-memory install-hooks --agent command-code --apply
-# Pool (Poolside Agent CLI) example — stages scripts and prints the
-# .poolside/settings.yaml snippet to paste into each repo (no MCP client yet):
-# ai-memory install-hooks --agent pool --apply
-# ZCode (z.ai) example — merges exec-form native commands into the root
-# hooks block of ~/.zcode/cli/config.json (handoff injection works; no true
-# session-end, so run `ai-memory finalize-session --agent zcode` at the end):
-# ai-memory install-hooks --agent zcode --apply
```
On Linux/macOS, that's it. Start a Claude Code session as usual - every
@@ -545,519 +217,81 @@ open in this project will see a handoff with where you left off.
On macOS, the native release binary is also supported and recommended when you
do not need Docker; see [`docs/macos.md`](docs/macos.md).
-If two Claude Code sessions use the same server concurrently, enable
-per-session routing on the server and replace only the `ai-memory` MCP entry
-with the optional bridge:
+Wiring another agent is the same two commands with a different name —
+`--client codex`, `--agent codex`, and so on for every row of the support
+matrix. The full per-agent guide, including Windows and remote servers, is
+[`docs/install.md`](docs/install.md).
-```toml
-# <ai-memory data dir>/config.toml
-[auto_scope]
-mode = "per_session"
-```
+Two agents in the same project at once, or teammates on one server? That
+works out of the box: the "current project" pointer is isolated per caller
+by default (v1.39+). See [`docs/auto-scope.md`](docs/auto-scope.md) for the
+optional session-aware Claude Code bridge and the details.
-```bash
-ai-memory install-mcp --client claude-code --session-aware --apply
-```
-
-The bridge still connects to the configured local or remote HTTP server and
-forwards its bearer token, but also attaches Claude's lifecycle session id to
-every MCP request. Existing static HTTP installs remain the default. See
-[`docs/auto-scope.md`](docs/auto-scope.md) for Claude's `/clear` and
-implicit-resume limitations.
-
-The `install-mcp` / `install-hooks` commands use
-`AI_MEMORY_SERVER_URL` / `AI_MEMORY_AUTH_TOKEN` when set; otherwise
-they default to `http://127.0.0.1:49374` (matching the server above)
-and no bearer token. If hooks are installed after an ai-memory MCP
-entry already exists, `install-hooks` reuses that endpoint so a remote
-MCP setup cannot silently regenerate loopback-only hooks. Both commands
-are idempotent - re-runs replace ai-memory's entry, preserve every
-other server / hook you have configured, and write a timestamped
-`.bak-<ts>` next to the file before each modifying write. The hook
-scripts are staged into `~/.local/share/ai-memory/hooks/<agent>/`
-automatically; re-running overwrites them so future image updates ship
-updated hooks. Drop `--apply` to print the snippet instead of mutating.
-For Claude Code, `CLAUDE_CONFIG_DIR` relocates MCP registration to
-`$CLAUDE_CONFIG_DIR/.claude.json`, hooks to
-`$CLAUDE_CONFIG_DIR/settings.json`, and global managed skills to
-`$CLAUDE_CONFIG_DIR/skills`. The Docker wrapper forwards this variable when
-the directory is under its existing `$HOME` bind mount. Use the native binary
-when the Claude config root is outside `$HOME`. Uninstall checks both the
-active relocated paths and Claude's home defaults, so enabling the variable
-does not leave an older default-path ai-memory installation behind.
-If your agent often starts inside repository subdirectories or linked
-worktrees, add `--project-strategy repo-root` to `install-hooks` so captures
-collapse to the main git repo name; see [`docs/install.md`](docs/install.md)
-and [`docs/marker-file.md`](docs/marker-file.md) for details. Later bare
-`--apply` refreshes, including `ai-memory upgrade`, preserve that choice;
-pass `--project-strategy basename` explicitly to remove it.
-
-The Docker wrapper also bridges thin-client commands such as
-`ai-memory status` and `ai-memory bootstrap` back to the host's
-loopback server. With the local Docker quick start above, no
-`AI_MEMORY_SERVER_URL` override is needed.
-
-Managed workstreams are optional. They execute the harness on the host while
-the server may remain local or remote:
+Managed workstreams are optional and add cross-harness *session* continuity
+on top of shared memory:
```bash
ai-memory run claude
-# later, continue the same workstream in another harness
-ai-memory run codex --yolo
-# omit the name to continue the newest usable local harness session
-ai-memory run
-# or resume the newest managed checkout without changing directories first
-ai-memory continue
-```
-
-To remove ai-memory later, run `ai-memory uninstall --apply` from the
-same host environment. It removes ai-memory-owned config entries, instruction
-blocks, default-root managed skill files, and generated plugin files only after
-matching their ai-memory signatures; custom skill roots installed with
-`--target-dir` are cleaned up manually. Use `--mcp-url` if you installed MCP
-with a custom endpoint, and `--mcp-name` only when you need to narrow removal to
-one matching entry.
-
-### Install Notes
-
-- **SELinux:** on enforcing Linux hosts, the wrapper automatically adds
- `--security-opt label=disable` only to short-lived helper commands that touch
- bind-mounted host files. It does not alter the long-lived server container
- or relabel `$HOME`; do not add `:z`/`:Z` to the whole home bind. Rootless
- engines also get `-u 0:0` for those commands. Docker and podman report
- rootless mode and SELinux support under different `info` keys; both are
- read. The same treatment applies whenever `AI_MEMORY_DATA_DIR` selects a
- host directory or an explicit `--config` reads a host file. See
- [`docs/install.md`](docs/install.md#selinux-enforcing-hosts).
-- **Windows:** use the Linux path inside WSL2, or the native Windows wrapper
- from PowerShell/cmd. Local supported profiles default to host-native commands:
- Claude Code may use its supported `ai-memory.exe` exec form, while other
- agents use native single command strings matching their hook schema. The
- Docker wrapper protects `.ps1` fallback commands from nested PowerShell
- expansion with `-EncodedCommand`; rerun
- `install-hooks --agent <agent> --apply` after upgrading so existing hook
- entries receive the current form.
- PowerShell/Git Bash script bundles are compatibility fallbacks and do not
- enforce capture-policy v1. 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`
- and `AI_MEMORY_AUTH_TOKEN=<token>` on the client before installing
- MCP/hooks. Explicit `--server-url` flags still work, but are no longer
- required when the env vars are set. Any non-loopback server should use
- bearer auth.
-- **Managed-launch wrapper:** `ai-memory run`, `ai-memory show`,
- `ai-memory continue`, `ai-memory resume`, and `ai-memory workstreams` must be
- intercepted by the current host wrapper so local checkouts, native harnesses,
- and session stores remain accessible. An old wrapper may pass these commands
- into Docker and fail to find a checkout or host executable. Run
- `ai-memory upgrade` on the agent machine to refresh it. The host-native runner
- inherits `AI_MEMORY_SERVER_URL`, `AI_MEMORY_AUTH_TOKEN`, and the host `PATH`.
-- **Upgrades:** for Docker-wrapper installs, run `ai-memory upgrade` on each
- agent machine. It refreshes the local wrapper, pulls the latest image, and
- re-stages hook scripts under `~/.local/share/ai-memory/hooks/<agent>/`.
- Native package/source installs should rerun
- `ai-memory install-hooks --agent <agent> --apply` after upgrading the binary.
- Remote/homelab servers must still be redeployed separately; local wrapper
- upgrade only updates the client machine. Existing project prompt files keep
- working. Refresh the managed ai-memory routing package
- (`ai-memory install-instructions`, or `--target AGENTS.md` for AGENTS-based
- projects) when you want new tool guidance. The refresh writes the slim
- markered snippet and managed Agent Skills from the same binary-owned assets.
- Managed skill payloads use LF line endings on every release platform, while
- user-authored files keep their existing line endings.
-
-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).
-
-Tab completion for the CLI is available in bash, zsh, fish, PowerShell, and
-elvish:
-
-```bash
-ai-memory completions fish > ~/.config/fish/completions/ai-memory.fish
+ai-memory run codex --yolo # later: same workstream, different harness
+ai-memory continue # resume the newest managed checkout
```
-See [`docs/shell-completions.md`](docs/shell-completions.md) for the other
-shells' install paths.
+`ai-memory uninstall --apply` removes everything ai-memory installed,
+and only what it installed. Install commands are idempotent and write
+timestamped backups next to any file they touch.
-## Security
-
-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.
-
-Unauthenticated non-loopback HTTP now fails closed. Set
-`AI_MEMORY_AUTH_TOKEN` or bind loopback; `--allow-insecure-no-auth` is an
-intentional, dangerous exception for plain HTTP only. Authentication does not
-encrypt bearer tokens: for LAN or remote access, use the ready
-[Caddy](docker/compose.tls.caddy.yml) or
-[Cloudflare Tunnel](docker/compose.tls.cloudflared.yml) templates described in
-the [HTTPS reverse-proxy guide](docs/https-via-proxy.md).
+## Everyday use
-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
-TOKEN=$(ai-memory generate-auth-token)
-
-docker run -d --name ai-memory \
- --restart unless-stopped \
- -p 0.0.0.0:49374:49374 \
- -v ai-memory-data:/data \
- -e AI_MEMORY_AUTH_TOKEN="$TOKEN" \
- -e AI_MEMORY_ALLOWED_HOSTS="<server-ip>,localhost,127.0.0.1" \
- akitaonrails/ai-memory:latest
-
-ai-memory install-mcp --client claude-code --apply \
- --server-url "http://<server-ip>:49374/mcp" --auth-token "$TOKEN"
-ai-memory install-hooks --agent claude-code --apply \
- --server-url "http://<server-ip>:49374" --auth-token "$TOKEN"
-```
-
-Bearer auth protects `/mcp`, `/hook`, `/handoff`, `/workstream/*`, and
-machine calls to `/admin/*` and `/api/v1/*`. Humans sign in at
-`POST /auth/login`; the console uses an `HttpOnly` session cookie plus CSRF,
-not a Bearer in `localStorage`. Custom SPA HTML at `/web` is public static.
-When human auth listens beyond loopback,
-`AI_MEMORY_AUTH__SECURE_COOKIE=true` is required and signals that a trusted
-HTTPS reverse proxy owns the browser-facing edge. It makes the session cookie
-HTTPS-only. Close or redirect direct HTTP access to that hostname.
-Non-loopback binds should also set `AI_MEMORY_ALLOWED_HOSTS` to guard against
-DNS rebinding.
-
-Busy shared hook servers can also set `AI_MEMORY_HOOK_RATE_PER_SEC` (tokens per
-second per actor/session source) and optionally `AI_MEMORY_HOOK_RATE_BURST` to
-bound one runaway session without blocking unrelated hook sources. Unset or `0`
-rate leaves the limiter disabled.
-
-For shared servers where each developer should authenticate their own hook
-writes, native Claude Code hooks can use a stored OIDC device token instead of
-embedding a shared static token:
-
-```bash
-ai-memory auth login oidc-device \
- --issuer "https://issuer.example.com/realms/team" \
- --client-id "ai-memory-cli"
-
-ai-memory install-hooks --agent claude-code --apply \
- --server-url "http://<server-ip>:49374"
-```
-
-OIDC hook auth requires the native `ai-memory hook ...` command path. The Docker
-wrapper keeps shell-script hooks by default; set up OIDC from a native release
-binary or source install. Thin-client HTTP commands such as `ai-memory status`
-and `ai-memory search` also use the stored OIDC access token when no static
-`AI_MEMORY_AUTH_TOKEN` / `[auth].bearer_token` is configured; the static bearer
-still wins when present. This is for OIDC-aware gateways/bridges; native
-ai-memory server auth still accepts static root bearer / DB-user tokens, and
-`/admin/*` remains root-only unless a gateway translates accepted OIDC auth into
-upstream auth that ai-memory accepts.
-
-OIDC/Keycloak session ids are login-provider sessions, not ai-memory agent
-sessions. Shared servers that rely on `[auto_scope]` session isolation still
-need explicit `workspace` + `project` / `scopes`, or a bridge that forwards the
-real lifecycle-hook session id on MCP requests.
-
-**Want HTTPS?** ai-memory deliberately does not terminate TLS itself —
-the right answer is a battle-tested reverse proxy in front of it.
-[`docs/https-via-proxy.md`](docs/https-via-proxy.md) is the deployment
-guide, with copy-paste docker compose templates in
-[`docker/compose.tls.caddy.yml`](docker/compose.tls.caddy.yml) (Caddy
-with Let's Encrypt or internal CA) and
-[`docker/compose.tls.cloudflared.yml`](docker/compose.tls.cloudflared.yml)
-(Cloudflare Tunnel — no open ports). Both are recommended once you
-turn on multi-user or bind beyond loopback. The Quick Start happy
-path of single-user on loopback doesn't need TLS — that case is
-called out explicitly in the guide so you don't add ceremony where
-it doesn't earn its keep.
-
-**Multi-user attribution (v0.8, optional) plus human login.** When more
-than one human shares a server, ai-memory attributes each write to a
-named user. Humans sign in with username/password; agents and CLIs use
-`Authorization: Bearer` (`AI_MEMORY_AUTH_TOKEN` for root automation, or
-an `aim_` key from `ai-memory api-key add`). 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. An SSO gateway can instead use a
-dedicated `[auth].actor_proxy_bearer_token` and trusted `X-Memory-Actor-*`
-headers; its credential is deliberately separate from the root bearer so a
-missing identity cannot become root. See
-[`docs/users.md`](docs/users.md) for the full walkthrough and the
-four-rung auth ladder.
-
-See [`docs/deploy.md`](docs/deploy.md) for the full homelab pattern
-with bearer auth, host allowlisting, and TLS/reverse-proxy options.
-
-## Using Memory
-
-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.
-
-Useful entry points:
+Day to day, you mostly do not think about ai-memory. Hooks capture
+prompts, tool calls, and session boundaries; session end turns them into
+readable wiki pages; the next session starts with a handoff.
- 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. `--enable-web` also mounts a
- read-only JSON frontend API at `/api/v1` (workspaces, projects, pages,
- recent, briefing, search) so custom web UIs can read the memory without
- opening SQLite or wiki files directly. Rendered pages keep external links
- clickable, but image sources must be relative or root-relative; absolute
- external images are neutralized so viewing stored Markdown cannot act as a
- remote beacon:
-
- ```text
- GET /api/v1/workspaces
- GET /api/v1/projects?workspace=...
- GET /api/v1/workspaces/{workspace}/projects/{project}/pages
- GET /api/v1/workspaces/{workspace}/projects/{project}/pages/{path}
- GET /api/v1/workspaces/{workspace}/projects/{project}/recent?limit=...
- GET /api/v1/workspaces/{workspace}/projects/{project}/briefing?limit=...
- GET /api/v1/workspaces/{workspace}/overview?limit=...
- GET /api/v1/workspaces/{workspace}/projects/{project}/overview?limit=...
- GET /api/v1/workspaces/{workspace}/projects/{project}/handoffs?state=...&limit=...
- GET /api/v1/search?q=...&workspace=...&project=...&limit=...
- POST /api/v1/search { "q": "...", "scopes": [{ "workspace": "...", "project": "..." }] }
- ```
-
- `overview` bundles the open handoff + briefing + memory-health for a workspace
- or project in one call (the data a project overview screen needs). The
- handoff history defaults to the caller's own plus shared rows; root can use
- `all_owners=true` for recovery across operators.
-
- **Full integration guide:** see [`docs/frontend-api.md`](docs/frontend-api.md)
- for auth setup, response schemas, error model, limits/pagination,
- custom-UI hosting, a worked `fetch`/`curl` example, and the canonical
- source-of-truth files. Read that first if you're building a frontend.
-
- To serve your own static frontend instead of the built-in UI, point
- `--web-ui-dir` at the frontend's build output (same-origin with
- `/api/v1`, `/mcp`, `/admin/*`, so the existing auth applies):
-
- ```bash
- ai-memory serve --transport http --bind 127.0.0.1:49374 \
- --enable-web --web-ui-dir ../ai-memory-ui/dist
- ```
+- Run `ai-memory bootstrap` once when adopting an existing project with
+ months of history.
+- Start the server with `--enable-web` for a read-only browser view of
+ the wiki and a JSON API under `/api/v1`.
- A reference implementation — a SolidJS knowledge browser with
- screenshots and e2e tests — lives at
- [djalmajr/ai-memory-ui](https://github.com/djalmajr/ai-memory-ui).
+The full tour — search modes, entities, feedback, briefings, the web
+API — is in [`docs/usage.md`](docs/usage.md) and
+[`docs/use-cases.md`](docs/use-cases.md).
- Richer products such as import/migration pipelines and write-capable
- browser chat/editors should live as optional companion crates or projects
- that call ai-memory's public HTTP/MCP surfaces. The first implemented
- companion is the standalone OMC wiki importer at
- [`companions/ai-memory-importer`](companions/ai-memory-importer), which is
- intentionally not a root workspace member and is not included in root
- `cargo test --workspace`. See
- [`docs/companion-crates.md`](docs/companion-crates.md) for the boundary.
+## Teams and multiple machines
- When a reverse proxy hosts ai-memory under a URL subpath, set
- `--base-path` (or `AI_MEMORY_BASE_PATH`) so every HTTP surface moves
- together. Example: `--base-path /wiki` serves MCP at `/wiki/mcp`, hooks at
- `/wiki/hook`, the API at `/wiki/api/v1`, and the default browser at
- `/wiki/web`. Set `--web-slug /` if you want the browser or custom SPA at
- `/wiki` itself.
+Run the server somewhere reachable — a homelab box, a LAN host — and
+point every machine and every teammate at it. Knowledge is shared per
+project; personal handoffs stay personal; every write is attributed and
+audited. Multi-user auth (passwords, API credentials) is built in.
-Install the managed routing package once so agents proactively call the
-right MCP tool for those prompts:
+Start with [`docs/users.md`](docs/users.md) for accounts and ownership,
+and [`docs/deploy.md`](docs/deploy.md) for the server itself — including
+capacity numbers measured rather than guessed, and the one rule that
+matters: one server per data directory, never two.
-```bash
-ai-memory install-instructions
-```
-
-That command writes or updates the slim `<!-- ai-memory:start -->` block and
-the managed ai-memory Agent Skills that carry the detailed routing guidance.
-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).
-
-### Entity retrieval
-
-Consolidation extracts specific technologies, components, services, files, and
-domain nouns into each page's canonical frontmatter. Hand-edited wiki pages can
-declare the same bounded index explicitly:
-
-```yaml
----
-title: Queue choice
-entities:
- - nats jetstream
- - delivery guarantees
----
-```
-
-Names are lowercased, whitespace-normalized, de-duplicated, capped at 10 per
-page and 64 characters each, and rebuilt from Markdown during a clean-store
-`ai-memory reindex`.
-Entity lookup is project-scoped, ignores expired pages by default, and reports
-`entity_rank`, its raw inverse-frequency `entity_weight`, `matched_entities`,
-and its RRF contribution under
-`memory_query(..., explain: true)`.
-
-## LLM Providers
-
-ai-memory runs without an LLM: hooks still capture sessions, search uses
-FTS5 + declared entities + graph neighbors, and summaries fall back to
-rule-based output. Add an LLM provider
-when you want LLM consolidation (on PreCompact, on demand via
-`memory_consolidate`, or opt-in at session end with
-`AI_MEMORY_CONSOLIDATE_ON_SESSION_END`), richer linting, and bootstrap.
-Substantive session ends always write a rule-based summary page + handoff either
-way. A session containing only `SessionStart` / `SessionEnd` boundaries is
-closed without a page, handoff, or provider job. When that empty session had
-accepted startup context, its session-bound handoff is returned to the open
-pool for the next receiver instead of being lost.
-When the session-end opt-in is enabled, provider work is durably queued after
-those deterministic writes and handled by one bounded server worker, so hook
-drain latency does not cancel it. Failed jobs retry with backoff and survive a
-server restart. A resumed native session is ended again only after its
-observation generation advances; the persisted generation watermark makes
-duplicate SessionEnd delivery and system clock skew converge without repeated
-provider work. The end watermark and automatic handoff commit atomically, and
-an interrupted keyed replay finishes the wiki commit, queue insert, and key
-completion without duplicating that handoff. On the next SessionStart, the
-newest cwd-eligible automatic handoff wins; accepting it expires older eligible
-automatic handoffs without consuming manual or sibling-directory work. A new
-automatic handoff also expires prior open automatic handoffs from its exact
-cwd, so repeated SessionEnds cannot accumulate there before a receiver starts.
-
-To keep consolidation style project-specific, write
-`_prompts/consolidation.md` in that project's wiki. Its body can express
-preferences such as "prefer Portuguese titles" or "omit routine CI noise".
-Automatic, single-page, and multi-page consolidation use the page; a manual
-`memory_consolidate` call can pass `instructions` to override it once. ai-memory
-sanitizes and caps the value at 2,000 characters, JSON-encodes it in the user
-message, and treats it as untrusted advisory data. It cannot supply facts,
-request tool use or disclosure, or override the consolidation schema and
-faithfulness rules. TTL-expired preference pages are ignored. With no active
-page or argument, no preference block is appended.
-
-Recommended defaults:
-
-| Provider | Default | Use when |
-|---|---|---|
-| `anthropic` | `claude-haiku-4-5` | Best default for consolidation quality and rule classification. |
-| `anthropic-oauth` | `claude-sonnet-4-6` | Use a Claude Pro/Max subscription via `claude setup-token`, no API key. |
-| `openai` | `gpt-5.4-mini` | Cheaper and faster hosted option. |
-| `openai-oauth` | `gpt-5.5` | ChatGPT Pro/Plus/Codex backend via `ai-memory auth login openai-oauth`; no Platform API key. |
-| `copilot` | `gpt-5.5` | GitHub Copilot Chat backend via `ai-memory auth login copilot` or `COPILOT_GITHUB_TOKEN`; requires a Copilot subscription. |
-| `gemini` | `gemini-3.5-flash` | Google-hosted option with a generous free tier. |
-| `openai-compat` | no default | OpenRouter, Atlas Cloud, OrcaRouter, Ollama, vLLM, LM Studio, and other compatible endpoints. |
-
-`openai-oauth` stores a refresh token in `<data_dir>/auth.json` and talks to
-the ChatGPT/Codex Responses backend, not `api.openai.com`. For Docker quick
-starts, run `ai-memory auth login openai-oauth` with the wrapper so the token
-lands in the same `ai-memory-data` volume as the server.
-
-`anthropic-oauth` hits the same `/v1/messages` endpoint as `anthropic` but
-authenticates with an OAuth bearer token instead of an API key. Run
-`claude setup-token` once, then set `AI_MEMORY_LLM_PROVIDER=anthropic-oauth` and
-`ANTHROPIC_OAUTH_TOKEN=<token>` (or `CLAUDE_CODE_OAUTH_TOKEN`, which `claude
-setup-token` writes automatically). No `ANTHROPIC_API_KEY` is needed. The Docker
-wrappers forward either token by name to short-lived helper commands such as
-`llm-test`; configure the long-lived server container separately as shown in the
-installation guide.
-
-For both Anthropic providers, ai-memory omits `temperature` for Claude
-4.7 and later models and Claude Mythos Preview because those models reject
-non-default sampling parameters. `llm-test` sends the same representative 0.2
-value as the normal pipeline before the provider applies that compatibility
-rule.
-
-**⚠️ Unofficial and against Anthropic's usage policies — use at your own risk;
-it may get your account rate-limited or banned. See
-[the warning in `docs/install.md`](docs/install.md#anthropic-via-claude-subscription-oauth).**
-
-`copilot` stores a GitHub user token in the same auth file, exchanges it for a
-short-lived Copilot API token via GitHub's `/copilot_internal/v2/token`, and
-uses the Copilot Chat endpoint with `vscode-chat` integration headers. You can
-also set `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN` on the server.
-
-> [!TIP]
-> **For the OAuth/subscription backends (`anthropic-oauth`, `openai-oauth`,
-> `copilot`), pick a small, fast model** via `AI_MEMORY_LLM_MODEL` — e.g.
-> `claude-haiku-4-5` or `gpt-5-mini`. ai-memory's LLM work (consolidation,
-> lint, explore) is summarisation, not hard reasoning, so a Haiku/mini-class
-> model is plenty and is much easier on subscription rate limits. Save the
-> high-effort thinking models for your coding agent.
-
-> [!TIP]
-> **OpenAI-compatible structured output is schema-constrained by default.**
-> ai-memory sends each operation's JSON Schema through
-> `response_format=json_schema`, which recent Ollama, vLLM, LM Studio, and
-> llama.cpp releases honour. It falls back to the tolerant parser when an
-> endpoint explicitly rejects that field or returns a malformed shape. Set
-> `AI_MEMORY_LLM_COMPAT_STRICT=false` only for an incompatible endpoint.
-
-For small-context local models, configure both consolidation limits. The input
-target accounts for the complete rendered prompt, including bounded slot and
-current-page context plus the structured-output schema; the output limit is
-sent to the provider. Their sum must fit the model context window, with extra
-headroom because provider tokenizers differ:
-
-```toml
-[consolidation]
-max_input_tokens = 6500
-max_output_tokens = 1000
-```
-
-The equivalent environment variables are
-`AI_MEMORY_CONSOLIDATION__MAX_INPUT_TOKENS` and
-`AI_MEMORY_CONSOLIDATION__MAX_OUTPUT_TOKENS`. Provider failures during an
-automatic PreCompact/PostCompaction checkpoint fall back to the deterministic
-rule-based page; admission, storage, and scope errors still fail closed. The
-validated minimums are 6,000 input and 1,000 output tokens.
+## Security
-Every chat provider bounds each completion request at 300 seconds
-(`AI_MEMORY_LLM_TIMEOUT_SECS` to override, or `llm_timeout_secs = 900` in
-config.toml; the quick openai-oauth token refresh keeps the default ceiling).
-The default tolerates a local engine cold-loading a large model; slow hosted
-gateways whose long completions exceed the ceiling fail every request with
-`http: error sending request`, so raise the value there instead of watching
-consolidation exhaust its retries.
+The quick-start default is loopback-only with no auth — nothing outside
+your machine can reach it. From there, hardening is incremental: a bearer
+token for the LAN, per-user accounts, OIDC device auth for hooks, TLS via
+a reverse proxy. Capture is sanitized at a typed privacy boundary before
+anything is stored, and per-repository `[capture]` rules can exclude
+paths or invert to allowlist mode.
-Reranking is optional and off by default. With an LLM provider configured,
-`AI_MEMORY_RERANKER=llm` makes project and explicit-scope `memory_query`
-calls over-fetch from the hybrid stage, fuse scopes, and make at most one LLM
-call to reorder the best candidates. This can promote a relevant page that
-RRF ranked below the requested cut, at the cost of LLM latency and usage. The
-request sends the query plus at most 30 bounded page titles and search snippets
-to the configured provider; all values are JSON-encoded and treated as
-untrusted data. A timeout, provider error, or incomplete/invalid score set
-preserves the normal order. `global=true` and supplemental global-preference
-hits keep their existing non-RRF ranking. Concurrent provider calls are capped
-at four; saturated queries keep their local ranking without waiting.
+The full model is in [`docs/security.md`](docs/security.md),
+[`docs/users.md`](docs/users.md), and
+[`docs/https-via-proxy.md`](docs/https-via-proxy.md).
-Embeddings are optional and separate from the LLM provider. Set
-`AI_MEMORY_EMBEDDING_PROVIDER=openai`, `voyage`, `google`/`gemini`, or
-`openai-compat` when you want vector retrieval in addition to FTS5 + entity +
-graph-neighbor retrieval. `openai-compat` targets self-hosted engines
-(Ollama, LM Studio, vLLM): it needs no API key and requires explicit
-`AI_MEMORY_EMBEDDING_BASE_URL`, `AI_MEMORY_EMBEDDING_MODEL`, and
-`AI_MEMORY_EMBEDDING_DIM`. The optional `EMBEDDING_API_KEY` credentials the
-embedder alone and is checked before `OPENAI_API_KEY` and `LLM_API_KEY`, so
-embeddings can run on a different provider than the LLM. Both the FTS-only and
-hybrid paths apply the same bounded page-authority adjustment after candidate
-generation; embeddings improve relevance recall but do not decide which source
-is canonical.
+## LLM providers
-See [`docs/install.md#llm-provider-tiers`](docs/install.md#llm-provider-tiers)
-for env vars and Ollama/OpenRouter/Atlas Cloud/OrcaRouter examples, and
-[`docs/llm-provider-comparison.md`](docs/llm-provider-comparison.md)
-for the empirical model comparison.
+Optional. Everything works with zero LLM calls; adding a provider
+upgrades session summaries and enables semantic search. Anthropic,
+OpenAI (incl. OAuth/Codex), GitHub Copilot, Gemini, OpenCode Zen, and
+any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM) are supported
+for consolidation; OpenAI, Voyage, Gemini, and keyless OpenAI-compatible
+endpoints for embeddings. Configuration lives in
+[`docs/llm-providers.md`](docs/llm-providers.md).
## Architecture
@@ -1104,6 +338,12 @@ diagram, crate breakdown, schema notes, and invariants.
| [`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, Hermes Agent, agentmemory / basic-memory / cognee deep-dives, lessons-learned from upstream issues. |
+- [`docs/support-matrix.md`](docs/support-matrix.md) - the full agent/platform matrix with notes.
+- [`docs/use-cases.md`](docs/use-cases.md) - scenario walkthroughs.
+- [`docs/llm-providers.md`](docs/llm-providers.md) - provider configuration.
+- [`docs/security.md`](docs/security.md) - the full security model.
+- [`docs/research-2026-landscape.md`](docs/research-2026-landscape.md) - how the field looks and where we sit in it.
+- [`docs/ROADMAP-2.0.md`](docs/ROADMAP-2.0.md) - the 2.0 plan.
## Influences and prior art
diff --git a/docs/llm-providers.md b/docs/llm-providers.md
new file mode 100644
index 00000000..64da381b
--- /dev/null
+++ b/docs/llm-providers.md
@@ -0,0 +1,153 @@
+# LLM Providers
+
+> Provider configuration for consolidation and embeddings. Moved verbatim from the README front page.
+
+ai-memory runs without an LLM: hooks still capture sessions, search uses
+FTS5 + declared entities + graph neighbors, and summaries fall back to
+rule-based output. Add an LLM provider
+when you want LLM consolidation (on PreCompact, on demand via
+`memory_consolidate`, or opt-in at session end with
+`AI_MEMORY_CONSOLIDATE_ON_SESSION_END`), richer linting, and bootstrap.
+Substantive session ends always write a rule-based summary page + handoff either
+way. A session containing only `SessionStart` / `SessionEnd` boundaries is
+closed without a page, handoff, or provider job. When that empty session had
+accepted startup context, its session-bound handoff is returned to the open
+pool for the next receiver instead of being lost.
+When the session-end opt-in is enabled, provider work is durably queued after
+those deterministic writes and handled by one bounded server worker, so hook
+drain latency does not cancel it. Failed jobs retry with backoff and survive a
+server restart. A resumed native session is ended again only after its
+observation generation advances; the persisted generation watermark makes
+duplicate SessionEnd delivery and system clock skew converge without repeated
+provider work. The end watermark and automatic handoff commit atomically, and
+an interrupted keyed replay finishes the wiki commit, queue insert, and key
+completion without duplicating that handoff. On the next SessionStart, the
+newest cwd-eligible automatic handoff wins; accepting it expires older eligible
+automatic handoffs without consuming manual or sibling-directory work. A new
+automatic handoff also expires prior open automatic handoffs from its exact
+cwd, so repeated SessionEnds cannot accumulate there before a receiver starts.
+
+To keep consolidation style project-specific, write
+`_prompts/consolidation.md` in that project's wiki. Its body can express
+preferences such as "prefer Portuguese titles" or "omit routine CI noise".
+Automatic, single-page, and multi-page consolidation use the page; a manual
+`memory_consolidate` call can pass `instructions` to override it once. ai-memory
+sanitizes and caps the value at 2,000 characters, JSON-encodes it in the user
+message, and treats it as untrusted advisory data. It cannot supply facts,
+request tool use or disclosure, or override the consolidation schema and
+faithfulness rules. TTL-expired preference pages are ignored. With no active
+page or argument, no preference block is appended.
+
+Recommended defaults:
+
+| Provider | Default | Use when |
+|---|---|---|
+| `anthropic` | `claude-haiku-4-5` | Best default for consolidation quality and rule classification. |
+| `anthropic-oauth` | `claude-sonnet-4-6` | Use a Claude Pro/Max subscription via `claude setup-token`, no API key. |
+| `openai` | `gpt-5.4-mini` | Cheaper and faster hosted option. |
+| `openai-oauth` | `gpt-5.5` | ChatGPT Pro/Plus/Codex backend via `ai-memory auth login openai-oauth`; no Platform API key. |
+| `copilot` | `gpt-5.5` | GitHub Copilot Chat backend via `ai-memory auth login copilot` or `COPILOT_GITHUB_TOKEN`; requires a Copilot subscription. |
+| `gemini` | `gemini-3.5-flash` | Google-hosted option with a generous free tier. |
+| `openai-compat` | no default | OpenRouter, Atlas Cloud, OrcaRouter, Ollama, vLLM, LM Studio, and other compatible endpoints. |
+
+`openai-oauth` stores a refresh token in `<data_dir>/auth.json` and talks to
+the ChatGPT/Codex Responses backend, not `api.openai.com`. For Docker quick
+starts, run `ai-memory auth login openai-oauth` with the wrapper so the token
+lands in the same `ai-memory-data` volume as the server.
+
+`anthropic-oauth` hits the same `/v1/messages` endpoint as `anthropic` but
+authenticates with an OAuth bearer token instead of an API key. Run
+`claude setup-token` once, then set `AI_MEMORY_LLM_PROVIDER=anthropic-oauth` and
+`ANTHROPIC_OAUTH_TOKEN=<token>` (or `CLAUDE_CODE_OAUTH_TOKEN`, which `claude
+setup-token` writes automatically). No `ANTHROPIC_API_KEY` is needed. The Docker
+wrappers forward either token by name to short-lived helper commands such as
+`llm-test`; configure the long-lived server container separately as shown in the
+installation guide.
+
+For both Anthropic providers, ai-memory omits `temperature` for Claude
+4.7 and later models and Claude Mythos Preview because those models reject
+non-default sampling parameters. `llm-test` sends the same representative 0.2
+value as the normal pipeline before the provider applies that compatibility
+rule.
+
+**⚠️ Unofficial and against Anthropic's usage policies — use at your own risk;
+it may get your account rate-limited or banned. See
+[the warning in `docs/install.md`](docs/install.md#anthropic-via-claude-subscription-oauth).**
+
+`copilot` stores a GitHub user token in the same auth file, exchanges it for a
+short-lived Copilot API token via GitHub's `/copilot_internal/v2/token`, and
+uses the Copilot Chat endpoint with `vscode-chat` integration headers. You can
+also set `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN` on the server.
+
+> [!TIP]
+> **For the OAuth/subscription backends (`anthropic-oauth`, `openai-oauth`,
+> `copilot`), pick a small, fast model** via `AI_MEMORY_LLM_MODEL` — e.g.
+> `claude-haiku-4-5` or `gpt-5-mini`. ai-memory's LLM work (consolidation,
+> lint, explore) is summarisation, not hard reasoning, so a Haiku/mini-class
+> model is plenty and is much easier on subscription rate limits. Save the
+> high-effort thinking models for your coding agent.
+
+> [!TIP]
+> **OpenAI-compatible structured output is schema-constrained by default.**
+> ai-memory sends each operation's JSON Schema through
+> `response_format=json_schema`, which recent Ollama, vLLM, LM Studio, and
+> llama.cpp releases honour. It falls back to the tolerant parser when an
+> endpoint explicitly rejects that field or returns a malformed shape. Set
+> `AI_MEMORY_LLM_COMPAT_STRICT=false` only for an incompatible endpoint.
+
+For small-context local models, configure both consolidation limits. The input
+target accounts for the complete rendered prompt, including bounded slot and
+current-page context plus the structured-output schema; the output limit is
+sent to the provider. Their sum must fit the model context window, with extra
+headroom because provider tokenizers differ:
+
+```toml
+[consolidation]
+max_input_tokens = 6500
+max_output_tokens = 1000
+```
+
+The equivalent environment variables are
+`AI_MEMORY_CONSOLIDATION__MAX_INPUT_TOKENS` and
+`AI_MEMORY_CONSOLIDATION__MAX_OUTPUT_TOKENS`. Provider failures during an
+automatic PreCompact/PostCompaction checkpoint fall back to the deterministic
+rule-based page; admission, storage, and scope errors still fail closed. The
+validated minimums are 6,000 input and 1,000 output tokens.
+
+Every chat provider bounds each completion request at 300 seconds
+(`AI_MEMORY_LLM_TIMEOUT_SECS` to override, or `llm_timeout_secs = 900` in
+config.toml; the quick openai-oauth token refresh keeps the default ceiling).
+The default tolerates a local engine cold-loading a large model; slow hosted
+gateways whose long completions exceed the ceiling fail every request with
+`http: error sending request`, so raise the value there instead of watching
+consolidation exhaust its retries.
+
+Reranking is optional and off by default. With an LLM provider configured,
+`AI_MEMORY_RERANKER=llm` makes project and explicit-scope `memory_query`
+calls over-fetch from the hybrid stage, fuse scopes, and make at most one LLM
+call to reorder the best candidates. This can promote a relevant page that
+RRF ranked below the requested cut, at the cost of LLM latency and usage. The
+request sends the query plus at most 30 bounded page titles and search snippets
+to the configured provider; all values are JSON-encoded and treated as
+untrusted data. A timeout, provider error, or incomplete/invalid score set
+preserves the normal order. `global=true` and supplemental global-preference
+hits keep their existing non-RRF ranking. Concurrent provider calls are capped
+at four; saturated queries keep their local ranking without waiting.
+
+Embeddings are optional and separate from the LLM provider. Set
+`AI_MEMORY_EMBEDDING_PROVIDER=openai`, `voyage`, `google`/`gemini`, or
+`openai-compat` when you want vector retrieval in addition to FTS5 + entity +
+graph-neighbor retrieval. `openai-compat` targets self-hosted engines
+(Ollama, LM Studio, vLLM): it needs no API key and requires explicit
+`AI_MEMORY_EMBEDDING_BASE_URL`, `AI_MEMORY_EMBEDDING_MODEL`, and
+`AI_MEMORY_EMBEDDING_DIM`. The optional `EMBEDDING_API_KEY` credentials the
+embedder alone and is checked before `OPENAI_API_KEY` and `LLM_API_KEY`, so
+embeddings can run on a different provider than the LLM. Both the FTS-only and
+hybrid paths apply the same bounded page-authority adjustment after candidate
+generation; embeddings improve relevance recall but do not decide which source
+is canonical.
+
+See [`docs/install.md#llm-provider-tiers`](docs/install.md#llm-provider-tiers)
+for env vars and Ollama/OpenRouter/Atlas Cloud/OrcaRouter examples, and
+[`docs/llm-provider-comparison.md`](docs/llm-provider-comparison.md)
+for the empirical model comparison.
diff --git a/docs/security.md b/docs/security.md
new file mode 100644
index 00000000..7a30c23d
--- /dev/null
+++ b/docs/security.md
@@ -0,0 +1,113 @@
+# Security
+
+> The full security model. Moved verbatim from the README front page; the README keeps a summary.
+
+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.
+
+Unauthenticated non-loopback HTTP now fails closed. Set
+`AI_MEMORY_AUTH_TOKEN` or bind loopback; `--allow-insecure-no-auth` is an
+intentional, dangerous exception for plain HTTP only. Authentication does not
+encrypt bearer tokens: for LAN or remote access, use the ready
+[Caddy](docker/compose.tls.caddy.yml) or
+[Cloudflare Tunnel](docker/compose.tls.cloudflared.yml) templates described in
+the [HTTPS reverse-proxy guide](docs/https-via-proxy.md).
+
+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
+TOKEN=$(ai-memory generate-auth-token)
+
+docker run -d --name ai-memory \
+ --restart unless-stopped \
+ -p 0.0.0.0:49374:49374 \
+ -v ai-memory-data:/data \
+ -e AI_MEMORY_AUTH_TOKEN="$TOKEN" \
+ -e AI_MEMORY_ALLOWED_HOSTS="<server-ip>,localhost,127.0.0.1" \
+ akitaonrails/ai-memory:latest
+
+ai-memory install-mcp --client claude-code --apply \
+ --server-url "http://<server-ip>:49374/mcp" --auth-token "$TOKEN"
+ai-memory install-hooks --agent claude-code --apply \
+ --server-url "http://<server-ip>:49374" --auth-token "$TOKEN"
+```
+
+Bearer auth protects `/mcp`, `/hook`, `/handoff`, `/workstream/*`, and
+machine calls to `/admin/*` and `/api/v1/*`. Humans sign in at
+`POST /auth/login`; the console uses an `HttpOnly` session cookie plus CSRF,
+not a Bearer in `localStorage`. Custom SPA HTML at `/web` is public static.
+When human auth listens beyond loopback,
+`AI_MEMORY_AUTH__SECURE_COOKIE=true` is required and signals that a trusted
+HTTPS reverse proxy owns the browser-facing edge. It makes the session cookie
+HTTPS-only. Close or redirect direct HTTP access to that hostname.
+Non-loopback binds should also set `AI_MEMORY_ALLOWED_HOSTS` to guard against
+DNS rebinding.
+
+Busy shared hook servers can also set `AI_MEMORY_HOOK_RATE_PER_SEC` (tokens per
+second per actor/session source) and optionally `AI_MEMORY_HOOK_RATE_BURST` to
+bound one runaway session without blocking unrelated hook sources. Unset or `0`
+rate leaves the limiter disabled.
+
+For shared servers where each developer should authenticate their own hook
+writes, native Claude Code hooks can use a stored OIDC device token instead of
+embedding a shared static token:
+
+```bash
+ai-memory auth login oidc-device \
+ --issuer "https://issuer.example.com/realms/team" \
+ --client-id "ai-memory-cli"
+
+ai-memory install-hooks --agent claude-code --apply \
+ --server-url "http://<server-ip>:49374"
+```
+
+OIDC hook auth requires the native `ai-memory hook ...` command path. The Docker
+wrapper keeps shell-script hooks by default; set up OIDC from a native release
+binary or source install. Thin-client HTTP commands such as `ai-memory status`
+and `ai-memory search` also use the stored OIDC access token when no static
+`AI_MEMORY_AUTH_TOKEN` / `[auth].bearer_token` is configured; the static bearer
+still wins when present. This is for OIDC-aware gateways/bridges; native
+ai-memory server auth still accepts static root bearer / DB-user tokens, and
+`/admin/*` remains root-only unless a gateway translates accepted OIDC auth into
+upstream auth that ai-memory accepts.
+
+OIDC/Keycloak session ids are login-provider sessions, not ai-memory agent
+sessions. Shared servers that rely on `[auto_scope]` session isolation still
+need explicit `workspace` + `project` / `scopes`, or a bridge that forwards the
+real lifecycle-hook session id on MCP requests.
+
+**Want HTTPS?** ai-memory deliberately does not terminate TLS itself —
+the right answer is a battle-tested reverse proxy in front of it.
+[`docs/https-via-proxy.md`](docs/https-via-proxy.md) is the deployment
+guide, with copy-paste docker compose templates in
+[`docker/compose.tls.caddy.yml`](docker/compose.tls.caddy.yml) (Caddy
+with Let's Encrypt or internal CA) and
+[`docker/compose.tls.cloudflared.yml`](docker/compose.tls.cloudflared.yml)
+(Cloudflare Tunnel — no open ports). Both are recommended once you
+turn on multi-user or bind beyond loopback. The Quick Start happy
+path of single-user on loopback doesn't need TLS — that case is
+called out explicitly in the guide so you don't add ceremony where
+it doesn't earn its keep.
+
+**Multi-user attribution (v0.8, optional) plus human login.** When more
+than one human shares a server, ai-memory attributes each write to a
+named user. Humans sign in with username/password; agents and CLIs use
+`Authorization: Bearer` (`AI_MEMORY_AUTH_TOKEN` for root automation, or
+an `aim_` key from `ai-memory api-key add`). 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. An SSO gateway can instead use a
+dedicated `[auth].actor_proxy_bearer_token` and trusted `X-Memory-Actor-*`
+headers; its credential is deliberately separate from the root bearer so a
+missing identity cannot become root. See
+[`docs/users.md`](docs/users.md) for the full walkthrough and the
+four-rung auth ladder.
+
+See [`docs/deploy.md`](docs/deploy.md) for the full homelab pattern
+with bearer auth, host allowlisting, and TLS/reverse-proxy options.
diff --git a/docs/support-matrix.md b/docs/support-matrix.md
new file mode 100644
index 00000000..cf21c7ed
--- /dev/null
+++ b/docs/support-matrix.md
@@ -0,0 +1,39 @@
+# Support Matrix
+
+> The complete platform and agent matrix, with integration notes.
+> Moved verbatim from the README front page, which keeps a compact view.
+
+
+| Area | Status | Notes |
+|---|---|---|
+| Linux | Supported | Primary Docker/server target and CI platform. Published Docker images support `linux/amd64` and `linux/arm64`. Native Arch/AUR packages include system and user systemd units. |
+| macOS | Supported | Workspace tests run in CI; tagged releases publish native `ai-memory-macos-aarch64.tar.gz` and `ai-memory-macos-x86_64.tar.gz` binaries. The native binary is the recommended path on Apple Silicon. See [`docs/macos.md`](docs/macos.md). |
+| Windows via WSL2 | Supported | Use the Linux install path inside WSL2 when the agent runs there. |
+| Native Windows | Experimental | Tagged releases publish `ai-memory-windows-x86_64.zip` with `ai-memory.exe`; Docker Desktop wrapper and source builds are also available. Local supported profiles default to host-native hook commands; Claude Code may use its Windows exec form, while other agents use native single command strings matching their hook schema. PowerShell/Git Bash scripts are compatibility fallbacks. See [`docs/windows.md`](docs/windows.md). |
+| Claude Code | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. `install-mcp --session-aware` optionally enables per-session auto-scope isolation through a local stdio bridge. Optionally captures the assistant's final turn on `Stop` when installed with `--capture-assistant` and the server enables `capture_assistant` (double opt-in, off by default). |
+| Codex | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. No automatic true session-end hook, so run `ai-memory finalize-session` when you need a final summary/handoff. |
+| Command Code | Supported | MCP config (`~/.commandcode/mcp.json`) + its four stable lifecycle-hook events (`~/.commandcode/settings.json`); native commands enforce capture exclusions and `SessionStart` injects handoffs. `Stop` is only a turn boundary, so use `ai-memory finalize-session --agent command-code` after the final turn. `ai-memory run command-code` adds exact v3 native-session resume and visible-event import; experimental unsandboxed Mods remain excluded. |
+| Devin CLI | Supported | MCP config + lifecycle hooks. Hooks use Devin's `PostCompaction` event, inject handoffs via `hookSpecificOutput.additionalContext`, and omit subagent events because Devin does not expose them. |
+| OpenCode | Supported | Remote MCP config + generated TypeScript plugin; generated plugin enforces capture exclusions. |
+| Cursor | Supported | MCP config + lifecycle hooks. |
+| Gemini CLI | Supported | MCP config + lifecycle hooks. |
+| Oh My Pi / OMP | Supported | Use `--client omp` / `--agent omp` (or `oh-my-pi`) for native `.omp` MCP config + TypeScript extension; generated extension enforces capture exclusions. |
+| Pi | Supported | Generated `~/.pi/agent/extensions/ai-memory-pi.ts` extension provides lifecycle capture and an HTTP MCP bridge; generated extension enforces capture exclusions. |
+| Crush | Managed-only | `ai-memory run crush` resumes its project-local session database and supplies portable context through a temporary supported global-context file; no lifecycle-hook installer is provided. |
+| Managed workstreams | Opt-in | `ai-memory run` provides transparent cross-harness continuity for Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, both incompatible Kiro CLI engines, OMP, Grok Build CLI, and Antigravity CLI. Direct launches remain unchanged. See [`docs/managed-workstreams.md`](docs/managed-workstreams.md). |
+| Claude Desktop | MCP-only | Uses `mcp-remote`; no lifecycle hooks. |
+| OpenClaw | Supported | MCP config + native plugin lifecycle hooks; generated plugin enforces capture exclusions. |
+| Antigravity CLI | Supported | MCP config (`serverUrl`) + lifecycle hooks (`agy` alias). Only `PreInvocation` with `invocationNum = 0` maps to SessionStart; later model calls cannot consume a next-session handoff. No automatic true session-end hook, so run `ai-memory finalize-session --agent antigravity-cli` after the final turn when you need a summary, handoff, and opt-in SessionEnd consolidation. `ai-memory run antigravity` (aliases `antigravity-cli`, `agy`) adds managed workstream resume via `--conversation`; conversation text is not decoded, so the ledger for this harness comes from hook capture. |
+| Grok Build CLI | Supported | MCP config (`install-mcp --client grok` → `$GROK_HOME/config.toml`, default `~/.grok/config.toml`) + lifecycle hooks (`install-hooks --agent grok` → `$GROK_HOME/hooks/ai-memory.json`, default `~/.grok/hooks/ai-memory.json`, Grok-specific hook bundle). Capture works; no hook handoff injection — Grok ignores `SessionStart` stdout, so recover handoffs via MCP `memory_handoff_accept`. `ai-memory run grok` adds managed workstream resume with the context packet delivered natively through `--rules`. Skills root: `.grok/skills` / `$GROK_HOME/skills` (default `~/.grok/skills`). |
+| Swival CLI | MCP-only | `install-mcp --client swival --apply` merges a native HTTP entry into the project-root `.swival/mcp.json`, preserving sibling servers. Lifecycle and managed-workstream support are not claimed because Swival's callback contract does not expose a stable session identifier. |
+| Zero | Supported | `install-mcp --client zero` (native HTTP + bearer in `~/.config/zero/config.json`) + lifecycle hooks via `install-hooks --agent zero --apply` (exec-form native commands in `~/.config/zero/hooks.json`, JSON payload on stdin, no shell). Capture works incl. specialist (subagent) events; no handoff injection — Zero discards `sessionStart` stdout, so recover handoffs via MCP `memory_handoff_accept`. |
+| ZCode | MCP-only | `install-mcp --client zcode --apply` merges a native HTTP entry (strict schema: `type`/`url`/`headers` only) into the `mcp.servers` map of `~/.zcode/cli/config.json`, preserving sibling servers. Lifecycle hooks are not yet available — see #512. |
+| Kimi Code | Supported | MCP config (`url` entry in `~/.kimi-code/mcp.json`) + lifecycle hooks (`[[hooks]]` in `~/.kimi-code/config.toml`, 10 events including subagent start/stop and `PostToolUseFailure` for tool-failure capture); both paths honor `$KIMI_CODE_HOME`. Handoffs inject via `UserPromptSubmit` stdout (Kimi Code discards `SessionStart` hook stdout); `ai-memory run kimi` adds managed workstream resume. |
+| Kiro CLI | Supported | MCP config uses `install-mcp --client kiro-cli` (alias `kiro`) and Kiro's Bedrock-compatible schema flavor. `install-hooks --agent kiro-cli` merges v2 hooks into existing agent configs; the explicit `--agent kiro-cli-v3` target writes the incompatible standalone v3 registration. Both preserve unrelated entries, honor `$KIRO_HOME`, enforce capture exclusions, and inject pending handoffs at session start. Kiro has no true SessionEnd hook; use `ai-memory finalize-session --agent kiro-cli`, with `--session-id <uuid>` for concurrent sessions. `ai-memory run kiro` manages v2; add `--v3`, `--mode`, or `--agent-engine v3` for version-safe v3 resume. |
+| Pool | Hooks-only | Poolside Agent CLI (`pool`). Lifecycle-hook capture via `install-hooks --agent pool` (alias `poolside`): Pool reads project-scoped hooks from the repo-root `.poolside/settings.yaml`, so ai-memory stages the scripts and prints a ready-to-paste `hooks:` snippet rather than writing project-local files; native commands enforce capture exclusions. Five Claude-shaped events (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`) and no true session-end — `Stop` is a turn boundary, so run `ai-memory finalize-session --agent pool` after the final turn. `SessionStart` stdout injection is not demonstrated, so capture works but handoff injection does not — recover handoffs via MCP `memory_handoff_accept`. No first-party `install-mcp` client and no managed workstream (`ai-memory run pool`) are claimed: Pool's native session-store contract is not demonstrated (see [`docs/managed-harness-contributions.md`](docs/managed-harness-contributions.md)). Verified against Poolside CLI v1.0.16. |
+| ZCode | Hooks-only | ZCode (z.ai, `zcode`, alias `zai`). Lifecycle-hook capture via `install-hooks --agent zcode --apply`: exec-form native commands (`type: "process"`, no shell) merged into the root `hooks` block of `~/.zcode/cli/config.json` around any third-party hooks; native commands enforce capture exclusions. Six documented triggers (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`); `PostToolUseFailure` fires instead of `PostToolUse` when a tool throws and lands on the same capture channel with the error preserved. `PermissionRequest` is deliberately not installed — its hook chain races the interactive permission client, so passive capture of that event is unreliable by design. No true session-end — `Stop` is a per-turn boundary, so run `ai-memory finalize-session --agent zcode` after the final turn. Unlike Pool and Zero, `SessionStart` stdout injection works (`hookSpecificOutput.additionalContext`, verified live against the embedded engine v0.16.5), so the prior session's handoff is delivered automatically. No first-party `install-mcp` client and no managed workstream are claimed yet. |
+| VS Code Copilot | MCP-only | `.vscode/mcp.json` for Copilot agent mode; no lifecycle hooks (Copilot does not expose them yet). |
+| Zed | MCP-only | Native remote MCP under `context_servers` in Zed's user `settings.json`; no lifecycle hooks or managed-workstream support. |
+| Hermes Agent | Community | Core hook ingestion recognizes `agent=hermes` and Hermes' documented shell-hook `tool_name` / `tool_input` payload for concrete session attribution, tool-family titles, and capture exclusions. A community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) is available, but no first-party installer is shipped; review its compatibility matrix, install/uninstall scripts, and secret handling before using it. Hermes ignores session-start hook stdout, so recover handoffs through MCP. |
+| LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode Zen/Go, OpenAI-compatible endpoints, and generic OIDC device auth for native hooks. |
+| Embedding providers | Supported | OpenAI, Voyage, Google Gemini, and keyless OpenAI-compatible endpoints such as Ollama, LM Studio, and vLLM. |
diff --git a/docs/use-cases.md b/docs/use-cases.md
new file mode 100644
index 00000000..98997c7b
--- /dev/null
+++ b/docs/use-cases.md
@@ -0,0 +1,227 @@
+# Use Cases
+
+> Moved verbatim from the README front page; the scenarios and walkthroughs are unchanged.
+
+- **"Quit Claude Code and continue the same work in Codex."** Use the optional
+ managed launcher when you want native session resume plus the portable visible
+ history, not only a summary handoff:
+
+ ```bash
+ cd /path/to/project
+ ai-memory run claude
+
+ # Quit Claude Code, then continue the same workstream in Codex.
+ ai-memory run codex --yolo
+
+ # Continue in Command Code, preserving its own exact native session.
+ ai-memory run command-code
+
+ # Later, omit the name to resume the newest usable managed session here.
+ ai-memory run
+
+ # Start a new Codex session in the same workstream, keeping portable history.
+ ai-memory run --fresh codex
+
+ # Kiro defaults to v2; select its incompatible v3 engine explicitly once.
+ ai-memory run kiro --v3
+
+ # List the workstreams that can be selected from this checkout.
+ ai-memory workstreams
+
+ # Fix a name you regret; the ledger and the current selection stay put.
+ ai-memory rename-workstream --from typo-nmae --to refactor-db
+
+ # Pick a managed workstream from any linked local checkout, then resume it.
+ ai-memory resume
+
+ # List open cross-agent handoffs, oldest first, with the id
+ # `memory_handoff_cancel` needs to clear a stale one.
+ ai-memory handoffs
+ ```
+
+- **"Pick the project instead of remembering where it lives."** Start from a
+ directory containing your checkouts and choose the checkout before the
+ managed harness:
+
+ ```bash
+ ai-memory show
+
+ # Machine-readable discovery without launching anything.
+ ai-memory show --json
+ ```
+
+ Each successful `ai-memory run` saves a client-local checkout link keyed by
+ the configured server plus workspace/project. `show` joins those links with
+ the server's public activity and page-count metadata. A fast, bounded depth-1
+ scan of the current directory also finds new checkouts carrying a project
+ marker (`.git`, `Cargo.toml`, `package.json`, `go.mod`, `pyproject.toml`, and
+ friends), while skipping dependency and build directories. The server never
+ exposes a checkout path, so two client machines can safely use different
+ local paths for the same project on a remote homeserver.
+
+ The list always leads with **`+ New project`**: type a name and ai-memory
+ validates a portable directory name, stages the new checkout privately, pins
+ its workspace and project in `.ai-memory.toml`, and installs the routing block
+ and managed Agent Skills for the chosen agent. The final directory appears
+ only after every setup step succeeds, then `show` launches from it.
+
+ The harness menu only offers agents actually installed on the host, using the
+ same `PATH` lookup `run` enforces at launch.
+
+ `--no-scan` uses only saved links; `--workspace` filters both sources;
+ `--yolo`, `--fresh`, and trailing native arguments are forwarded unchanged.
+ Non-terminal use must pass `--json`; JSON mode is discovery-only and never
+ launches a harness.
+
+ The first explicit run can offer an existing session from this exact checkout
+ or start a new one. Switching harnesses starts or resumes the native session
+ linked to the shared workstream, so an obsolete local session cannot replace
+ newer cross-harness history. After a normal quit, the next launch waits
+ briefly if the previous launcher is still finalizing; handled failures release
+ the workstream immediately. If a linked native transcript was deleted,
+ ai-memory detects the orphan before launch and starts fresh; `--fresh` forces
+ that recovery for one harness. Managed mode currently covers Claude Code,
+ Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, Kiro CLI v2/v3, OMP,
+ Grok Build CLI, and Antigravity CLI; direct harness launches remain unchanged. See
+ [Managed cross-harness workstreams](docs/managed-workstreams.md).
+- **"Just put me back where I was."** From any directory, with no name to
+ type and no list to read:
+
+ ```bash
+ ai-memory continue
+ ```
+
+ It picks the checkout whose managed launch is most recent, revalidates the
+ path and its resolved scope, then continues there exactly as bare
+ `ai-memory run` would. A link whose directory moved, was replaced, now
+ resolves to a different project, or has a corrupt ordering timestamp is
+ reported on stderr and skipped, so a resume never quietly lands in the wrong
+ project. `--workspace` narrows the search; `--yolo` and `--fresh` are
+ forwarded.
+- **"Let me choose which workstream to resume."** From any directory, select
+ one of the recent workstreams from your valid client-local managed checkouts:
+
+ ```bash
+ ai-memory resume
+ ai-memory resume --workspace work
+ ```
+
+ The picker shows the workstream name, project scope, activity, and linked
+ harnesses. Use Up/Down (or `j`/`k`) to choose a workstream and Left/Right to
+ cycle its launch harness. Every row starts at `auto`, preserving normal
+ session discovery; the other choices are supported harnesses currently found
+ in `PATH`. Enter launches the displayed combination. The checkout is
+ revalidated first, while the server continues to receive fingerprints rather
+ than a local path. Use `ai-memory workstreams` when you are already in a
+ checkout and only want the read-only list.
+- **"Quit at 4 PM, pick up at 9 AM in a different agent."** The
+ classic. SessionStart hook in the next supported hook client prepends a
+ typed handoff with open questions, next steps, and a session summary. Grok
+ captures lifecycle events but ignores SessionStart stdout, so ask it to call
+ `memory_handoff_accept` when resuming from a handoff. Zero has the same
+ no-stdout behavior and also must call `memory_handoff_accept`.
+- **"What did we decide about X six weeks ago?"** Use `memory_query X` from
+ the agent for FTS5 fused with entity matches and linked-page expansion (plus
+ vector similarity when an embedder is configured). For a quick terminal-only
+ FTS5 lookup, use `ai-memory search X`; that admin command does not run the
+ hybrid streams. Pages are
+ LLM-consolidated, so the hit is a coherent decision page, not a raw
+ chat log. Pass `explain: true` to see why each hit ranked where it
+ did in project or explicit-scope retrieval. Cross-project
+ `global: true` search uses its separate FTS-only ranker and reports
+ that active stream without per-hit RRF details.
+- **"Remember this permanently."** When something is worth keeping
+ beyond auto-captured session logs - a decision, a convention, a
+ gotcha - tell the agent "save a permanent note that we standardised
+ on Postgres for X" or "annotate this as a project rule" and it calls
+ `memory_write_page` to write a durable, git-versioned wiki page. From
+ a terminal it's `ai-memory write-page --path decisions/0007-db.md
+ --body $'# Standardised on Postgres\n\n...' --pinned`. `--pinned`
+ exempts it from the decay sweep; the H1 on the first line of
+ `--body` becomes the page title (omit `--title` — it's still
+ accepted, but LLM callers trip over JSON-escaping their way through
+ it, see issue #67). Unlike a handoff (single-use) or an
+ auto-synthesised session page (rewritten on consolidation), a
+ write-page note is yours: it shows up in `memory_query`, renders in
+ `/web`, and stays until you change it.
+- **"That page you found is out of date."** The agent calls
+ `memory_feedback` with the page's path and a signal: `helpful` /
+ `not_helpful` tune how strongly retention keeps a sweep-eligible episodic
+ page (they move its salience, which scales the decay formula's time term),
+ while `stale` / `wrong` floor the salience *and* make any current page
+ show up as a `feedback_flagged` finding in the next `memory_lint` report.
+ Feedback never deletes anything — it lowers confidence and flags for review —
+ and it attaches to the version current when feedback is recorded, so a
+ later rewrite clears the flag. Retrieved page text is untrusted and never
+ authorizes feedback by itself.
+- **"Remember this, but only until the sprint ends."** Pass
+ `expires_at` to `memory_write_page` (RFC3339 or `YYYY-MM-DD` = end of
+ that day, UTC) — or put `expires_at:` in a page's frontmatter by
+ hand. Past the TTL the page disappears from search/recent/briefing
+ (pass `include_expired: true` to `memory_query` to still see it) and
+ the next forget sweep hard-deletes the file and its rows. A TTL beats
+ a pin; `memory_lint` warns about pinned+expiring combos.
+- **"This new project has months of history before ai-memory."**
+ `cd /path/to/my-project && ai-memory bootstrap` collects
+ `git log`, README, `docs/`, module headers, project rules and
+ one-shot-summarises them into seed wiki pages. Future sessions
+ build on top.
+- **"What durable lesson did that session teach?"**
+ When an LLM provider is configured, ai-memory runs a background
+ auto-improvement scheduler for newly completed sessions in every project. It
+ records proposed wiki edits in the pending-writes audit trail, then approves
+ them immediately through the normal wiki write path by default. Scheduler ticks
+ are non-overlapping: if reviewing all projects takes longer than the interval,
+ the next tick is delayed until the current one finishes. Scheduling and
+ approval are separate: set `[auto_improve.scheduler] enabled = false` to stop
+ automatic review, or set `[auto_improve] require_approval = true` to keep both
+ scheduled and manual proposals pending for human review. `ai-memory
+ auto-improve --session-id <uuid>` and MCP `memory_auto_improve` remain
+ available for manual catch-up or targeted reruns. When its `session_id` is
+ omitted, the MCP tool selects the newest completed session without a
+ persisted auto-improvement run, so repeated calls advance past short
+ preflight-skipped sessions; an explicit ID reruns that session. `ai-memory
+ auto-improve-report --workspace <w> --project <p>` returns a read-only
+ telemetry report for recent auto-improvement outcomes without staging or
+ creating proposals; add `--stage` to create one pending report page for
+ audit/approval. On deployments that distinguish operators, pending learning
+ proposals are isolated by qualified operator identity, so one person's
+ proposal for a page does not block another's; unattributed and single-user
+ deployments retain the shared pending queue. See
+ [`docs/auto-improve-eval-gates.md`](docs/auto-improve-eval-gates.md) for
+ example executable eval scorers.
+
+ Existing installs do not need per-project migration. The scheduler initializes
+ a per-project first-run watermark so historical sessions are not reviewed
+ automatically on upgrade, then records per-session claims so failed scheduled
+ reviews do not retry forever; use manual auto-improve for old sessions or
+ failed scheduled sessions you want to catch up. Older configs may still contain
+ an `[auto_improve] mode = ...` line; current ai-memory ignores that legacy key,
+ so you can remove it when convenient.
+- **"What housekeeping should I consider?"**
+ `ai-memory curator` runs a no-LLM, rule-based maintenance report over cold
+ episodic pages, stale slots, duplicate exact normalized titles, and dangling
+ cross-project links. It is report-only unless `--stage` is passed; staging
+ queues one report page for approval and still performs no maintenance actions
+ itself. Shared servers can opt into `[decay] breadth_weight` to give pages
+ reinforced by several identified operators a retention bonus; the default
+ `0.0` leaves existing retention scores unchanged.
+- **"Run one ai-memory for the whole household."** Stand the server
+ up on a homelab box at `0.0.0.0:49374` with a bearer token; every
+ laptop/desktop talks to it. Per-cwd routing keeps each project's
+ pages cleanly separated; the `/web` UI is reachable from a
+ browser anywhere on the LAN.
+- **"Audit what landed before sharing with a teammate."** Browse
+ the wiki at `http://<server>:49374/web` - sign in with username and
+ password when human auth is on. Per-project tree view,
+ rendered markdown, supersession chain visible per page.
+- **"Undo one bad page edit without rolling back the whole server."**
+ `ai-memory checkpoints` shows recent wiki commits, then
+ `ai-memory restore-page --path notes/foo.md --from <rev>` restores that one
+ markdown file and reindexes it into SQLite. Full `backup` / `restore` is
+ still the answer for DB-only state such as sessions, observations, handoffs,
+ users, audit rows, and embeddings.
+- **"Drop an experiment, keep the rest."**
+ `ai-memory purge-project --project experimental --confirm`.
+ Atomic: that project's DB rows cascade away, its wiki subdir gets
+ `rm -rf`'d, every sibling project is untouched by construction.