Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: release-ledger pass for 3.0 (changelog dedupe, stale docs, audit fixes)
AkitaOnRailsfcc61ad20548
diff --git a/AGENTS.md b/AGENTS.mdindex 3c2aae6f..ad569b3a 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -351,6 +351,7 @@ covers the same tests, slower, no tiers."$HOME\.rustup"`.- Shell-level checks: `tests/hooks/test_lib.sh`,+ `tests/hooks/test_plugin_launcher.sh`, `tests/install_sh.sh`,`tests/e2e/handoff_smoke.sh`, `tests/wrapper_upgrade.sh`,`tests/e2e/external_relay_smoke.py`, `scripts/check-native-packaging.sh`,`scripts/check-nix-packaging.sh` (Nix flake output),diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3276b64f..b40eda8d 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -37,8 +37,19 @@ and [0.x](docs/changelog/0.x.md).hidden `ai-memory render-plugins`, with a test that fails when thecommitted files drift from it. When Claude settings-file hooks and theplugin are both installed, the settings hooks win and the plugin skips the- events they deliver; sessions with no project folder are not captured- through the plugin. `setup` and `ai-memory run` no longer write settings+ events they deliver, but only a settings hook with a catch-all matcher+ (empty, `*` or absent) counts; sessions with no project folder are not+ captured through the plugin. Droid running the Claude Code plugin gets the+ same treatment: the plugin skips folderless sessions and the events+ `install-hooks --agent droid` already delivers. The Claude Code hooks start+ the launcher with `sh`, a relative `ai_memory_bin` option is ignored, and+ the plugin trees and every `*.sh` are pinned to LF line endings. With no+ server URL set, the launcher omits `--server-url`; a binary older than 3.0+ rejects that, so the launcher retries it once against+ `http://127.0.0.1:49374` and prints an upgrade hint. The plugins need+ ai-memory 3.0 or later. On Windows, Codex calls `ai-memory hook` directly+ without the launcher, so folderless sessions are captured there and a+ missing binary goes unreported; `docs/install.md` records this. `setup` and `ai-memory run` no longer write settingshooks, MCP entries or skills for an agent whose plugin is enabled;`doctor` reports each plugin, version skew, double wiring and Codex pluginhooks Codex skips; `upgrade` also updates the Claude Code plugin;@@ -58,11 +69,9 @@ and [0.x](docs/changelog/0.x.md).raw score and RRF contribution in every stream, the fused score, theauthority multiplier, and the intent boost and rerank score when present;the page also lists the streams that ran, the embedder and reranker in use,- and each stream's time in milliseconds. A scoped `/api/v1/search` (one- project or `scopes`) uses the same ranker, so it returns the same order as- `memory_query`, and its `rank` is now the fused rank. A search without a- scope is still the cross-project FTS5 search, as `memory_query(global=true)`- is. Project search follows the per-project read rule: a viewer without a+ and each stream's time in milliseconds. A web search without a scope is+ still the cross-project FTS5 search, as `memory_query(global=true)` is.+ Project search follows the per-project read rule: a viewer without agrant on a restricted project gets a 403 and no trace, and an unknown projectis a 404.- Added a root-only server health page at `/web/health`, linked from the web UI@@ -85,7 +94,10 @@ and [0.x](docs/changelog/0.x.md).`install.sh.sha256`. It downloads the release tarball for the machine, checksit against the published `.sha256` file and refuses to install when that fileis missing, names another asset or does not match, or when the archive holds- an absolute or `..` path. It unpacks under `~/.local/lib/ai-memory`, links+ an absolute or `..` path or a symlink or hard-link member. Its `wget`+ fallback for the default GitHub URL runs only with `--https-only` and+ refuses a `wget` that lacks the flag. It unpacks under+ `~/.local/lib/ai-memory` without restoring file ownership, links`~/.local/bin/ai-memory`, needs no root, leaves an existing non-link`ai-memory` (such as the Docker wrapper) alone, and runs nothing when thedownload is cut short. The new `ai-memory setup [--yes] [--agent <name>]...@@ -94,11 +106,16 @@ and [0.x](docs/changelog/0.x.md).user unit or launchd LaunchAgent with this install's binary, data dir andconfig, wires MCP, hooks and global Agent Skills for each named or detectedagent, and ends with a read-only check of `/healthz`, `memory_status` and- `doctor`. It shows the plan and asks first; without a terminal it changes- nothing unless given `--yes`. A second run changes nothing. Windows has no- service step. `ai-memory uninstall --apply` stops and removes that service,- but only a unit `setup` wrote and nobody edited since; any other unit at that- path is left alone and reported. `INSTALL_FOR_AGENTS.md` tells an AI agent how to install+ `doctor`. The unit names a stable path to the binary (the invoked path, an+ `ai-memory` on `PATH`, or Homebrew's `opt/bin` link) when the resolved+ binary sits in a versioned Homebrew Cellar or `/nix/store` path, so the+ service survives an upgrade or garbage collection. It shows the plan and+ asks first; without a terminal it changes nothing unless given `--yes`. A+ second run changes nothing. Windows has no service step. `ai-memory+ uninstall --apply` stops and removes that service, but only a unit `setup`+ wrote and nobody edited since; any other unit at that path is left alone+ and reported. With `--purge-data`, uninstall refuses a live ai-memory+ process before it stops the service. `INSTALL_FOR_AGENTS.md` tells an AI agent how to installai-memory for its user, and `scripts/onboarding-acceptance.sh` measures thepath from a clean home to the first returned memory.- Added page history and session replay to the read-only web UI. Each page@@ -122,9 +139,13 @@ and [0.x](docs/changelog/0.x.md).`ai-memory-web` crate now has a `clippy.toml` that forbids the `Wiki` writeand destructive methods, so a write path in the web UI or `/api/v1` fails`cargo clippy -D warnings`.-- Added an observation stream to `memory_query` ranking:- `[retrieval] observation_stream` (env- `AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM`, on by default). A zero-LLM+- Added an observation stream to `memory_query` ranking, on by default+ because it raised hit@5 on the retrieval eval for both zero-LLM and+ local-embedding search while staying inside its latency and context-token+ budgets. To keep the previous ranking, set `[retrieval]+ observation_stream = false` (or+ `AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false`); ranking is then identical+ to before. A zero-LLMsession page keeps only a short excerpt of each turn, so the detail aquestion asks about often lives only in the session's observations. With theflag on, project and `scopes` searches also run full-text search over@@ -136,8 +157,12 @@ and [0.x](docs/changelog/0.x.md).only shares topic words in its titles cannot outvote the session holdingthe answer. When page search did notmatch the page itself, the matching excerpt becomes the hit's snippet, and- `explain=true` reports an `observation` stream with the matched observation- ids. Hits are still pages and nothing is written; sessions without a page+ `explain=true` lists `observation` in `streams_active` whenever the stream+ runs and reports the matched observation ids. The excerpt and the ids are+ shown only when the caller may read that session's timeline; another+ operator's observations still vote for the shared session page. The stream+ finds the project's observation range with an index seek. Hits are still+ pages and nothing is written; sessions without a pagekeep the `raw_hits` fallback, and `global=true` search is unchanged.- Added a root-only `GET /admin/metrics` endpoint in Prometheus text format.It exposes the hook admission and delivery counters, MCP tool calls split@@ -170,7 +195,7 @@ and [0.x](docs/changelog/0.x.md).quit from anything else, and the zero-LLM session page closes its summarywith `ended (<reason>)`. Payloads without a reason are stored as before.(#1225)-- The web UI shows pending cross-project mail. Project cards carry an amber+- Added pending cross-project mail to the web UI. Project cards carry an amber`N inbox` badge when messages are waiting for an agent in that project, thehome page summarises the total and links the projects holding mail, and theproject page gains a read-only Mailbox section listing up to five of them@@ -178,8 +203,8 @@ and [0.x](docs/changelog/0.x.md).empty state when there are none. A sender the viewer may not read is shown as"a project you cannot read", and the page never pops or cancels a message.(#1202)-- `install-mcp --client prime-agent` registers ai-memory with Prime Agent- (PrimeIntellect-ai/prime-agent), merging an HTTP entry into the `mcpServers`+- Added `install-mcp --client prime-agent`, which registers ai-memory with+ Prime Agent (PrimeIntellect-ai/prime-agent), merging an HTTP entry into the `mcpServers`map of `$PRIME_AGENT_CODING_AGENT_DIR/settings.json` (default`~/.prime/agent/settings.json`) and preserving other settings and servers.With a token the entry names `"bearerTokenEnvVar": "AI_MEMORY_AUTH_TOKEN"`@@ -188,9 +213,9 @@ and [0.x](docs/changelog/0.x.md).OAuth grant), so export it where you launch `prime-agent`. Without a tokenthe server is still callable through `mcp.call_tool("ai-memory", ...)` but isnot listed. MCP-only: Prime Agent 0.10 has no lifecycle hooks. (#1163)-- `memory_write_page` accepts `expected_page_id` (write only if that is still- the page's latest version) or `create_only` (write only if the page does not- exist), and `memory_delete_page` accepts `expected_page_id`. A precondition+- Added `expected_page_id` (write only if that is still the page's latest+ version) and `create_only` (write only if the page does not exist) to+ `memory_write_page`, and `expected_page_id` to `memory_delete_page`. A preconditionthat no longer holds fails with `reason: "precondition_failed"` and thecurrent version, and changes nothing. `memory_read_page` returns the versionas `page_id` and `/api/v1` pages as `id`. This is the compare-and-write the@@ -203,7 +228,7 @@ and [0.x](docs/changelog/0.x.md).after each merge: a dry-run report unless `--on-merge apply`, never with`--prefer`, and never with a stored token. The cookbook has a GitHubActions recipe. (#986)-- The `ai-memory-wikisync` companion now propagates deletes with+- Added delete propagation to the `ai-memory-wikisync` companion with`sync --propagate-deletes` (#986, slice 4): a file deleted in the repositorydeletes its server page through `memory_delete_page`, and a page deleted onthe server deletes its file, when the other side is unchanged since the last@@ -214,8 +239,8 @@ and [0.x](docs/changelog/0.x.md).reported and left alone while the rest apply, and `sync --apply` refuses aserver older than 3.0. Without the flag deletes are still only reported.(#986)-- `ai-memory doctor` now reports three silent capture failures: an unreachable- server (reported instead of aborting the check), a hook spool that is full and+- Changed `ai-memory doctor` to report three silent capture failures: an+ unreachable server (reported instead of aborting the check), a hook spool that is full andevicting undelivered events, and installed ai-memory Codex hooks that Codexskips because they are untrusted or changed since they were trusted (askedof Codex itself through `codex app-server`). `ai-memory status` no longer says@@ -227,9 +252,11 @@ and [0.x](docs/changelog/0.x.md).`--prefer repo` or `--prefer server`; deletes are reported, not synced.It is a dry-run without `--apply`, refuses files without frontmatter,refuses to overwrite server pages whose metadata a write would clear, and- re-reads each page right before writing it. (#1164)-- `finalize-session --agent antigravity-cli` now replays the session's typed- prompts from `agy`'s `history.jsonl` before its synthetic session-end, so+ re-reads each page right before writing it. An export, or an import's+ rewrite of the repository file, is skipped and reported when that file+ changed during the run, and the run exits non-zero. (#1164)+- Changed `finalize-session --agent antigravity-cli` to replay the session's+ typed prompts from `agy`'s `history.jsonl` before its synthetic session-end, solive Antigravity sessions, whose hooks carry no prompt event, get a summarypage titled by the first prompt, a handoff with "Started/Last", and promptsthat `memory_query` and `memory_recent` can find. Only lines whose@@ -238,8 +265,8 @@ and [0.x](docs/changelog/0.x.md).prompt typed after the first finalize arrives with the next one. A checkoutthe capture allowlist does not admit and `--all-owners` runs replay nothing,and a missing `history.jsonl` only warns. (#1160)-- `ai-memory run` accepts `copilot` (alias `copilot-cli`) and manages GitHub- Copilot CLI as a workstream harness: a fresh session gets a generated+- Added `copilot` (alias `copilot-cli`) to `ai-memory run`, which manages+ GitHub Copilot CLI as a workstream harness: a fresh session gets a generated`--session-id`, a returning one is resumed with `--resume=<id>`, userselectors (`--resume`, `--continue`, `--session-id`, `--connect`) win,utility subcommands pass through, and `--yolo` maps to Copilot's native@@ -249,7 +276,7 @@ and [0.x](docs/changelog/0.x.md).and the existing SessionStart hook delivers the workstream context. Thefirst managed launch auto-wires Copilot's hooks and MCP, and `doctor` nowcounts its local sessions. Verified against Copilot CLI 1.0.92. (#1040)-- GitHub Copilot CLI is now a first-class routing target:+- Made GitHub Copilot CLI a first-class routing target:`install-skills --agent copilot-cli` (and `install-instructions--skills-agent copilot-cli`) writes the managed Agent Skills to therepository's `.github/skills` or, globally, to `$COPILOT_HOME/skills`@@ -269,7 +296,10 @@ and [0.x](docs/changelog/0.x.md).and recovery replay now use reserved `recovery_*` idempotency keys, sore-running `backfill --force` over sessions imported by ai-memory ≤2.6.0 (orplain-backfilling a recovery-replayed session) can duplicate those older- observations. (#1125)+ observations. Every spool drain path deletes an event the server answered+ `dropped_*` or `resumed` instead of re-sending it each pass, and a hook+ that finds the spool's capacity lock busy waits up to 50 ms and then spools+ the event anyway. (#1125)- Added `AI_MEMORY_LLM_COMPAT_DISABLE_THINKING` for the `openai-compat`provider (opt-in, off by default, ignored by every other provider): whenset, every chat request carries@@ -280,7 +310,9 @@ and [0.x](docs/changelog/0.x.md).Agent CLI (`agent --print --mode ask`) so a Cursor subscription can drivesummaries without an API key. The default model is `cursor-grok-4.6-high`("Grok 4.6"). `AI_MEMORY_CURSOR_AGENT` overrides the binary. The provider never passes- `--yolo` or `--force`, because the prompt is captured session text. (#1127)+ `--yolo` or `--force`, because the prompt is captured session text, and+ runs `agent` with an allowlisted environment, so it never inherits+ `AI_MEMORY_AUTH_TOKEN` or provider keys. (#1127)- Added `applies_to` and `enforced_by` arguments to `memory_write_page`, and`--applies-to` / `--enforced-by` to `ai-memory write-page`, for profileentries. Both fields were documented as profile-entry frontmatter, but no@@ -299,8 +331,8 @@ and [0.x](docs/changelog/0.x.md).a Cordis profile patch rather than a fixed config file, so the command prints aready-to-merge `- insert:` fragment for `@deepseek-ai/dsh-mcp-client` andrefuses `--apply`. (#1193)-- The `ai-memory-importer` companion imports agentmemory data. `agentmemory-vault`- reads its Obsidian vault export; `agentmemory-export` reads its `ExportData`+- Added agentmemory import to the `ai-memory-importer` companion.+ `agentmemory-vault` reads its Obsidian vault export; `agentmemory-export` reads its `ExportData`JSON file, from disk only, and needs a mapping file from agentmemory'sproject names (or exact session working directories) to ai-memoryworkspaces and projects. `--apply` refuses to run while any record is@@ -316,8 +348,8 @@ and [0.x](docs/changelog/0.x.md).`--replay-observations` replays them as `external-import` sessions through`/hook/batch`, and records with no ai-memory counterpart are counted in themanifest. The cookbook has a "Coming from agentmemory" section.-- `ai-memory doctor` reports agentmemory configuration left behind after a- migration: an MCP server entry in any harness config `install-mcp` knows (or+- Added an agentmemory residue check to `ai-memory doctor`. It reports+ agentmemory configuration left behind after a migration: an MCP server entry in any harness config `install-mcp` knows (orin a project's `.mcp.json`, `.cursor/mcp.json`, `.gemini/settings.json` or`.vscode/mcp.json`), and agentmemory guideline blocks in rules files such as`AGENTS.md`, `GEMINI.md`, `.cursor/rules/` and `.kiro/steering/`. It names@@ -360,7 +392,7 @@ and [0.x](docs/changelog/0.x.md).patch too). Only ZCode, whose config keeps HTTP entries only, is refused withthe manual option. `uninstall` recognises these entries.`install-hooks --apply` stores the token in the hook credential files only.-- `ai-memory status` and `ai-memory doctor` now show the server's auth+- Changed `ai-memory status` and `ai-memory doctor` to show the server's authposture, and for an unauthenticated loopback server print`auth: none (loopback)` with the fix, `ai-memory auth enable`.- Added a server-side drop list for tool events: `[ingest]@@ -440,9 +472,8 @@ and [0.x](docs/changelog/0.x.md).`scopes`) to rank with the same hybrid ranker as `memory_query` instead ofFTS5 alone, so it returns the same order as `memory_query`, and `rank` isnow the fused rank. Cross-project search without a scope is unchanged.-- Documented hand-written MCP recipes for Factory Droid, Warp, Cline, Kilo- Code, Goose, Qwen Code and OpenHuman in `docs/install.md`, and listed them- in `docs/support-matrix.md` as `MCP-only (documented)`: each recipe follows+- Documented hand-written MCP recipes for Warp, Cline, Kilo Code, Goose,+ Qwen Code and OpenHuman in `docs/install.md`, and listed them in `docs/support-matrix.md` as `MCP-only (documented)`: each recipe followsthe client's own documentation at a named version and has not yet been runend to end. Aider is not listed because it has no MCP support.- Published `docs/benchmarks/longmemeval-s-decomposition-2026-10-12.md`, which@@ -457,14 +488,6 @@ and [0.x](docs/changelog/0.x.md).figure is 95.2% from a component harness with the reranker disabled, notlike-for-like with ai-memory's pipeline numbers. `docs/comparison.md` gains a"From agentmemory" migration note.-- Changed `memory_query` ranking to include the observation stream by- default, after it raised hit@5 on the retrieval eval for both zero-LLM and- local-embedding search while staying inside its latency and context-token- budgets. `explain=true` lists `observation` in- `streams_active` whenever it runs. To keep the previous ranking, set- `[retrieval] observation_stream = false` (or- `AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false`); ranking is then identical- to before.- Changed `ai-memory init` on a fresh data dir (no config file and nodatabase yet) to create a root bearer token at`<data_dir>/auth-tokens/default` and record `[auth] bearer_token_file`, so@@ -478,7 +501,8 @@ and [0.x](docs/changelog/0.x.md).server's credential. The Docker wrapper hands a host command (`install-hooks`,`mcp-bridge`, `run`) the token of a server initialized on its volume as anowner-only file that `install-hooks` copies from the volume, never on a- command line. With no human accounts the built-in web UI answers a browser+ command line. The wrapper deletes that host copy when `install-hooks` finds+ no token in the volume and after a successful `uninstall --apply`. With no human accounts the built-in web UI answers a browserwith a Basic sign-in prompt instead of redirecting to a login form thatcould not succeed: any username, and the token file's contents as thepassword. `ai-memory setup` prints that URL and the file to read, never the@@ -543,6 +567,17 @@ and [0.x](docs/changelog/0.x.md).`ai-memory install-hooks` once, skips the event and exits 0, so the agentis never blocked.+### Security+- Fixed HTTP Basic sign-in to the web UI minting a 30-day `ai_memory_auth`+ cookie that held the root bearer token. Basic sign-in sets no cookie now;+ a cookie set by an older build keeps working until human auth is enabled.+- Fixed `memory_query`, `/web/search` and `/api/v1/search` showing another+ operator's captured observations on a multi-user server. Observation+ excerpts, the observation ids in `explain`, and raw-observation fallback+ hits now come only from sessions the caller may read under the+ session-timeline owner rule. Another operator's observations still rank+ shared session pages.+## [2.6.6] - 2026-10-13### Fixeddiff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.mdindex 9fec09e4..aacf374a 100644--- a/INSTALL_FOR_AGENTS.md+++ b/INSTALL_FOR_AGENTS.md@@ -22,7 +22,7 @@ Linux or macOS it takes two commands, and neither needs root.`<self>` is one of `claude-code`, `codex`, `opencode`, `opencode2`,`gemini-cli`, `cursor`, `kimi-code`, `kiro-cli`, `grok`, `copilot-cli`,- `antigravity-cli`, `command-code`, `devin`, `omp`, `pi`, `openclaw`+ `antigravity-cli`, `command-code`, `devin`, `droid`, `omp`, `pi`, `openclaw`(`ai-memory setup --help` lists every value). Repeat `--agent` to wireseveral harnesses. Without `--agent`, `setup` wires every harness it findsunder the home directory.diff --git a/README.md b/README.mdindex b594c580..e926592c 100644--- a/README.md+++ b/README.md@@ -582,7 +582,7 @@ identity/SSO, and offline-install questions specifically, seeOptional. Everything works with zero LLM calls; adding a providerupgrades session summaries and enables semantic search. Anthropic,OpenAI (including OAuth), Codex CLI credential reuse, GitHub Copilot, Gemini,-OpenCode (Go and Zen), and+OpenCode (Go and Zen), the Cursor Agent CLI (`cursor`), andany OpenAI-compatible endpoint (Ollama, LM Studio, vLLM) are supportedfor consolidation; OpenAI, Voyage, Gemini, and keyless OpenAI-compatibleendpoints for embeddings. Configuration lives indiff --git a/companions/ai-memory-wikisync/README.md b/companions/ai-memory-wikisync/README.mdindex a7268ba1..242182b0 100644--- a/companions/ai-memory-wikisync/README.md+++ b/companions/ai-memory-wikisync/README.md@@ -240,5 +240,5 @@ ai-memory-wikisync uninstall-hook --dest docs/wiki [--hooks-dir DIR]write tool.4. Deletes and conflict reporting (`--propagate-deletes`, conditionalwrites).-5. This release: post-merge hook and CI integration (`install-hook`,- `sync --check`).+5. Post-merge hook and CI integration (`install-hook`, `sync --check`)+ (ai-memory 3.0).diff --git a/docs/companion-crates.md b/docs/companion-crates.mdindex e18a4367..584d79e1 100644--- a/docs/companion-crates.md+++ b/docs/companion-crates.md@@ -78,11 +78,12 @@ the public MCP write/delete tools. It must never open the wiki directory orSQLite directly. The core read seam is `/api/v1` in API-only mode; the supportedMCP page arguments are documented in [programmatic memory](programmatic-memory.md).-Slice 1 (read-only export), slice 3 (two-way sync through the MCP write-tool), slice 4 (conditional writes and opt-in deletes) and slice 5 (the CI-check and post-merge hook) ship as+All five slices of #986 have shipped. Slice 1 (read-only export) came first,+in 2.x. Slice 2 (the compare-and-write seam in core), slice 3 (two-way sync+through the MCP write tool), slice 4 (conditional writes and opt-in deletes)+and slice 5 (the CI check and post-merge hook) ship in 3.0. The companion is[`ai-memory-wikisync`](#ai-memory-wikisync-team-wiki-export-and-sync)-below; the remaining slices are tracked in #986.+below.## `ai-memory-client`: shared private capture privacydiff --git a/docs/competitive-parity.md b/docs/competitive-parity.mdindex 525ffd90..f01e1b77 100644--- a/docs/competitive-parity.md+++ b/docs/competitive-parity.md@@ -286,7 +286,7 @@ invariants), **ALREADY** (we have it and should say so).| Larger capture caps | Keep ours (2 KB / 16 KiB) | Privacy boundary (invariant 6); the decomposition showed the caps were not the cause (pages holding exactly the captured text scored 0.968) || PaaS deploy templates (Fly, Railway, Render, Coolify) | DECLINE for now (a demand-gated docs recipe at most) | Non-loopback already refuses to run without auth; a hosted path is not our product || Redis or other external store backends | DECLINE | Invariants 2 and 3 (single-writer SQLite; indexes in the same transaction) and markdown as truth |-| Harness long tail (Droid, Warp, Cline, Kilo, Goose, Qwen Code, Aider, …) | SHIPPED (3.0) as MCP recipes for seven more clients; hooks only where the harness has a lifecycle API (Droid accepted, #1240) | Any MCP client reaches us over HTTP |+| Harness long tail (Droid, Warp, Cline, Kilo, Goose, Qwen Code, Aider, …) | SHIPPED (3.0) as MCP recipes for six more clients (Warp, Cline, Kilo Code, Goose, Qwen Code, OpenHuman), plus first-class Droid; hooks only where the harness has a lifecycle API (Droid accepted, #1240) | Any MCP client reaches us over HTTP || Image / vision memory | DECLINE | Off-mission; the sanitizer boundary is text-only || Bidirectional bridge with a harness's own `MEMORY.md` | DECLINE (bidirectional); one-way import ADOPT | Two sources of truth contradict our routing rule against harness-local stores || Obsidian vault export | ALREADY | The wiki is already markdown in git; open `<data_dir>/wiki/<ws>/<project>` as a vault |@@ -393,7 +393,8 @@ next to Caura's trust tiers.root-only health panel in the web UI; explain timings and a content-free`/admin/metrics`; auth on by default for new installs with `auth enable`for existing ones; a two-command native install for Linux and macOS- (`install.sh` + `ai-memory setup`); MCP recipes for seven more clients; an importer for+ (`install.sh` + `ai-memory setup`); MCP recipes for six more clients (Warp, Cline,+ Kilo Code, Goose, Qwen Code, OpenHuman), plus first-class Droid; an importer foragentmemory's vault and export plus a `doctor` check for its leftovers; andgit-based wiki sync (`ai-memory-wikisync`).- **The real weakness was retrieval through capture**, and it wasdiff --git a/docs/install.md b/docs/install.mdindex cb959481..2e028088 100644--- a/docs/install.md+++ b/docs/install.md@@ -2919,7 +2919,9 @@ docker run --rm akitaonrails/ai-memory:latest --help # full subcommand tree|---|---|---|| `serve` | `docker compose up -d` (already done) | Run the HTTP MCP server || `setup [--yes] [--agent <name>]... [--no-service]` | native binary (after `install.sh`) | `init` a fresh data dir (with its root bearer token), install and start a per-user service, wire MCP, hooks and Agent Skills for each named or detected agent, then run a read-only self-check. Shows the plan and asks first; a second run changes nothing. |-| `auth enable` | native binary or host wrapper | Give an existing install without auth a root bearer token in `auth-tokens/default` and re-render its hook and MCP wiring to read it. Idempotent. |+| `auth enable [--no-mcp]` | native binary or host wrapper | Give an existing install without auth a root bearer token in `auth-tokens/default` and re-render its hook and MCP wiring to read it; `--no-mcp` leaves the MCP registrations alone. Idempotent. |+| `project init` | native binary, in the checkout | Ask for `workspace` and `project` and write them to a new `.ai-memory.toml` marker at the worktree root; the defaults keep the scope the checkout already resolves to, and an existing marker is never overwritten. Needs a terminal. |+| `recover [--json]` | host wrapper or native binary | After a server outage, drain the local hook spool, replay degraded-run transcripts through the backfill path, and finish managed runs whose transcript import failed. Safe to re-run; `--json` prints the report as JSON. || `run [harness] [args...]` | host wrapper or native binary | Opt into one managed cross-harness workstream; omit the harness to resume the newest usable local session, or name Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, Kiro CLI v2/v3, OMP, Grok Build CLI, Antigravity CLI, or GitHub Copilot CLI explicitly; exact `--yolo` and `--fresh` flags are wrapper-owned and other native arguments pass through || `show [--json]` | host wrapper or native binary | Choose a client-local checkout and installed managed harness, or return structured discovery data without launching; remote servers never provide checkout paths || `continue [--workspace NAME]` | host wrapper or native binary | From any directory, revalidate and resume the newest client-local managed checkout; accepts `--yolo` and `--fresh` but no harness-native arguments |diff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex e90ea2a0..306cc8a2 100644--- a/docs/support-matrix.md+++ b/docs/support-matrix.md@@ -16,8 +16,8 @@| 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, which include a per-user launchd agent. The native binary is the recommended path on Apple Silicon. A source-built menu bar app (`companions/ai-memory-macos`) bundles that binary, starts the LaunchAgent, and opens `/web` and `ai-memory status` — README quick-start and [`docs/macos.md`](macos.md) Scenario D. || 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. Native `ai-memory upgrade` is supported for writable x86_64 zip installs (checksum-verified zip + rename-aside self-replace + sibling `hooks/` refresh). 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`](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; on a token-file install (every fresh `init`) the session-aware bridge entry is automatic. 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. `SessionEnd` is wired since Codex CLI 0.145.0 (openai/codex#33895), so finished sessions get an automatic end-of-session summary/handoff; on older Codex the event is inert and `ai-memory finalize-session --agent codex` is the fallback. Managed runs (`ai-memory run codex`) recover when Codex's shared daemon reports a stale run id, provided exactly one live run matches the authorized project, checkout, and operator; ambiguous matches fail closed. `--no-daemon` remains available as an isolation and diagnostic option (see [`docs/managed-workstreams.md`](managed-workstreams.md)). 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's `Stop` payload carries `last_assistant_message`, same as Claude Code. |+| Claude Code | Supported | MCP config + lifecycle hooks; native commands enforce capture exclusions. The same hooks, MCP tools and skills also ship as a marketplace plugin (ai-memory 3.0 or later; see [`install.md`](install.md#marketplace-plugins)). `install-mcp --session-aware` optionally enables per-session auto-scope isolation through a local stdio bridge; on a token-file install (every fresh `init`) the session-aware bridge entry is automatic. 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. The same hooks, MCP tools and skills also ship as a marketplace plugin (ai-memory 3.0 or later; see [`install.md`](install.md#marketplace-plugins)). `SessionEnd` is wired since Codex CLI 0.145.0 (openai/codex#33895), so finished sessions get an automatic end-of-session summary/handoff; on older Codex the event is inert and `ai-memory finalize-session --agent codex` is the fallback. Managed runs (`ai-memory run codex`) recover when Codex's shared daemon reports a stale run id, provided exactly one live run matches the authorized project, checkout, and operator; ambiguous matches fail closed. `--no-daemon` remains available as an isolation and diagnostic option (see [`docs/managed-workstreams.md`](managed-workstreams.md)). 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's `Stop` payload carries `last_assistant_message`, same as Claude Code. || 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; an interactive session launched with `ai-memory run command-code` is finalized automatically when it exits if the run can tie the session to itself (see [`docs/managed-workstreams.md`](managed-workstreams.md)). `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 (V1/V2 auto-detected) | Supported | Host-side generic `opencode` commands probe the exact executable and select the V1 direct MCP/function-plugin/transcript contracts or V2 nested `mcp.servers`/`{ id, setup }` plugin/`session_v2` contracts. The result is reused through managed discovery, launch, auto-wire, and transcript import; an automatic run skips OpenCode when probing fails but continues other harness discovery. Container-oriented `setup-agent` requires `--opencode-dialect v1|v2`. Generated sibling plugins and alternate MCP entries are migrated only when ai-memory ownership is proven. |@@ -55,5 +55,5 @@| Goose | MCP-only (documented) | `type: streamable_http` extension (URL key `uri`) in `~/.config/goose/config.yaml`, added with `goose configure`; no documented env-var expansion in headers. No `install-mcp` client and no lifecycle hooks installed. Documented against Goose 1.54.0, not yet verified end to end. See [`install.md`](install.md#goose). || Qwen Code | MCP-only (documented) | `httpUrl` entry under `mcpServers` in `~/.qwen/settings.json`; the bearer header reads `${AI_MEMORY_AUTH_TOKEN}`, which Qwen Code expands. No `install-mcp` client and no lifecycle hooks installed. Documented against Qwen Code 0.25.1, not yet verified end to end. See [`install.md`](install.md#qwen-code). || OpenHuman | MCP-only (documented) | `url` + `headers` entry added in the app's **mcp.json** tab (a view over OpenHuman's server store, not a file on disk); header values are stored write-only. No `install-mcp` client and no lifecycle hooks installed. Documented against OpenHuman 0.64.15, not yet verified end to end. See [`install.md`](install.md#openhuman). |-| LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode (Go and Zen), OpenAI-compatible endpoints, and generic OIDC device auth for native hooks. |+| LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode (Go and Zen), Cursor Agent CLI (`cursor`), 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/upgrading-to-3.0.md b/docs/upgrading-to-3.0.mdindex a898e4d3..2f4cd2c0 100644--- a/docs/upgrading-to-3.0.md+++ b/docs/upgrading-to-3.0.md@@ -29,7 +29,11 @@ For the full list of changes, see the 3.0.0 section ofreinstall it.4. If you use the `ai-memory-wikisync` or `ai-memory-importer` companions,upgrade the server first. Their 3.0 versions refuse to write to a server- older than 3.0.+ older than 3.0. The first `ai-memory-wikisync` run after the upgrade+ rewrites unedited files from an earlier export so they carry the new+ frontmatter.+5. The Claude Code and Codex marketplace plugins need ai-memory 3.0 or later.+ Upgrade the binary before you install them.## Upgrade steps@@ -104,6 +108,10 @@ file, gives it to the installed hooks, and re-registers the MCP clients thatpoint at this server. `ai-memory status` and `ai-memory doctor` now print theserver's auth posture.+A browser that signs in to the web UI with HTTP Basic no longer gets an+`ai_memory_auth` cookie. A cookie a 2.x server set keeps working until human+auth is enabled.+### `memory_query` searches observations by defaultThe observation stream is now on by default: project and `scopes` searchesdiff --git a/docs/usage.md b/docs/usage.mdindex 0d29f006..edab69a1 100644--- a/docs/usage.md+++ b/docs/usage.md@@ -300,8 +300,12 @@ Omitted fields do not inherit the previous version; empty entity lists andrelation objects clear those fields. Empty `kind` or `abstract` strings omitthose keys. Existing requests without the new fields remain valid, includingthe admin's existing top-level `kind`. Arbitrary frontmatter, scope and author-fields are never copied from metadata. This is an unconditional replacement;-it provides no patch or compare-and-write precondition.+fields are never copied from metadata. Without `expected_page_id` or+`create_only` the write is an unconditional replacement. Only+`memory_write_page` accepts those preconditions; `POST /admin/write-page` has+neither. See+[Change a page only if nobody else has](programmatic-memory.md#change-a-page-only-if-nobody-else-has)+for conditional writes.## Install the routing snippet and Agent Skills