Skip to content

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.md
index 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.md
index 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 the
committed files drift from it. When Claude settings-file hooks and the
plugin 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 settings
hooks, MCP entries or skills for an agent whose plugin is enabled;
`doctor` reports each plugin, version skew, double wiring and Codex plugin
hooks 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, the
authority 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 a
grant on a restricted project gets a 403 and no trace, and an unknown project
is 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, checks
it against the published `.sha256` file and refuses to install when that file
is 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 the
download 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 and
config, wires MCP, hooks and global Agent Skills for each named or detected
agent, 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 install
ai-memory for its user, and `scripts/onboarding-acceptance.sh` measures the
path 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` write
and 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-LLM
session page keeps only a short excerpt of each turn, so the detail a
question asks about often lives only in the session's observations. With the
flag 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 holding
the answer. When page search did not
match 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 page
keep 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 summary
with `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, the
home page summarises the total and links the projects holding mail, and the
project 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 token
the server is still callable through `mcp.call_tool("ai-memory", ...)` but is
not 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 precondition
that no longer holds fails with `reason: "precondition_failed"` and the
current version, and changes nothing. `memory_read_page` returns the version
as `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 GitHub
Actions 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 repository
deletes its server page through `memory_delete_page`, and a page deleted on
the 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 a
server 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 and
evicting undelivered events, and installed ai-memory Codex hooks that Codex
skips because they are untrusted or changed since they were trusted (asked
of 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, so
live Antigravity sessions, whose hooks carry no prompt event, get a summary
page titled by the first prompt, a handoff with "Started/Last", and prompts
that `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 checkout
the 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>`, user
selectors (`--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. The
first managed launch auto-wires Copilot's hooks and MCP, and `doctor` now
counts 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 the
repository'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, so
re-running `backfill --force` over sessions imported by ai-memory ≤2.6.0 (or
plain-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): when
set, 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 drive
summaries 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 profile
entries. 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 a
ready-to-merge `- insert:` fragment for `@deepseek-ai/dsh-mcp-client` and
refuses `--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's
project names (or exact session working directories) to ai-memory
workspaces 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 the
manifest. 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 (or
in 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 with
the 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 auth
posture, 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 of
FTS5 alone, so it returns the same order as `memory_query`, and `rank` is
now 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 follows
the client's own documentation at a named version and has not yet been run
end 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, not
like-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 no
database 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 an
owner-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 browser
with a Basic sign-in prompt instead of redirecting to a login form that
could not succeed: any username, and the token file's contents as the
password. `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 agent
is 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
### Fixed
diff --git a/INSTALL_FOR_AGENTS.md b/INSTALL_FOR_AGENTS.md
index 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 wire
several harnesses. Without `--agent`, `setup` wires every harness it finds
under the home directory.
diff --git a/README.md b/README.md
index b594c580..e926592c 100644
--- a/README.md
+++ b/README.md
@@ -582,7 +582,7 @@ identity/SSO, and offline-install questions specifically, see
Optional. Everything works with zero LLM calls; adding a provider
upgrades 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`), 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
diff --git a/companions/ai-memory-wikisync/README.md b/companions/ai-memory-wikisync/README.md
index 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`, conditional
writes).
-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.md
index 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 or
SQLite directly. The core read seam is `/api/v1` in API-only mode; the supported
MCP 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 privacy
diff --git a/docs/competitive-parity.md b/docs/competitive-parity.md
index 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 for
agentmemory's vault and export plus a `doctor` check for its leftovers; and
git-based wiki sync (`ai-memory-wikisync`).
- **The real weakness was retrieval through capture**, and it was
diff --git a/docs/install.md b/docs/install.md
index 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.md
index 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.md
index 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 of
reinstall 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 that
point at this server. `ai-memory status` and `ai-memory doctor` now print the
server'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 default
The observation stream is now on by default: project and `scopes` searches
diff --git a/docs/usage.md b/docs/usage.md
index 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 and
relation objects clear those fields. Empty `kind` or `abstract` strings omit
those keys. Existing requests without the new fields remain valid, including
the 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