Skip to content

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

Rust

docs: correct the observation-stream numbers and refresh stale 2.7 docs

AkitaOnRailse1cf0b146445
diff --git a/AGENTS.md b/AGENTS.md
index 18ebd5c5..a5176dcf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -143,7 +143,9 @@ Core design:
compiles session observations into durable wiki pages (Karpathy-style
"compile, not retrieve").
- **Retrieval** is FTS5 + lexical entity-match + link-neighbor RRF, with
- optional vector RRF when an embedding provider is configured, plus bounded
+ optional vector RRF when an embedding provider is configured, an
+ observation-evidence stream over `observations_fts` that votes for session
+ pages (on by default, `[retrieval] observation_stream`), plus bounded
raw-observation fallback.
- **LLM is opt-in.** Zero-LLM mode still captures, searches (FTS5), and
writes rule-based summaries. Providers (Anthropic, Anthropic OAuth,
@@ -203,16 +205,19 @@ crates/
├── ai-memory-test-support/ shared test helpers (dev-dependency only, no test binary).
└── ai-memory-cli/ `ai-memory` binary entry point + thin HTTP subcommands.
evals/ live A/B harness; workspace member, not shipped.
-companions/ai-memory-importer/ standalone OMC + external-conversation importer; NOT a root
+companions/ai-memory-importer/ standalone OMC, external-conversation and agentmemory importer; NOT a root
workspace member — build/test it with
`--manifest-path companions/ai-memory-importer/Cargo.toml`.
companions/ai-memory-client/ capture-privacy helpers shared by relay + importer; own workspace.
companions/ai-memory-relay/ durable external-lifecycle event relay (POST /hook/batch); own workspace.
+companions/ai-memory-wikisync/ team-wiki git sync through the public MCP tools; own workspace.
companions/ai-memory-macos/ Swift menu bar wrapper; NOT a root workspace member —
`swift test --package-path companions/ai-memory-macos`
and `./companions/ai-memory-macos/build.sh`.
hooks/ per-agent lifecycle hook bundles (shell/native).
bin/ host wrapper scripts (`ai-memory`, `deploy`, `release`).
+install.sh two-command native install, step one (release asset).
+INSTALL_FOR_AGENTS.md how an AI agent installs ai-memory for its user.
docker/ Dockerfile, compose files, TLS proxy templates.
packaging/ AUR/RPM/systemd/launchd/sysusers/tmpfiles/env native packaging assets.
nix/, flake.nix Nix package + NixOS module.
@@ -286,9 +291,9 @@ covers the same tests, slower, no tiers.
`static/tailwind.css`; commit the result. CI regenerates it on Linux and
fails if the committed file is stale, so nothing else needs the download.
- Run each Cargo companion separately (`ai-memory-client`,
- `ai-memory-importer`, `ai-memory-relay`, and on `release/2.7`
- `ai-memory-wikisync`): `cargo fmt --check`, `cargo clippy --locked
- --all-targets -- -D warnings` and `cargo test --locked`, each with
+ `ai-memory-importer`, `ai-memory-relay` and `ai-memory-wikisync`):
+ `cargo fmt --check`, `cargo clippy --locked --all-targets -- -D warnings`
+ and `cargo test --locked`, each with
`--manifest-path companions/<name>/Cargo.toml`. CI also builds the relay
and runs `uv run --no-project python tests/e2e/external_relay_smoke.py`
against the real server. Root `--workspace` commands cover none of them.
@@ -330,6 +335,7 @@ covers the same tests, slower, no tiers.
`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),
+ `scripts/onboarding-acceptance.sh` (clean home to first returned memory),
`scripts/check-changelog-sections.sh` and
`scripts/check-changelog-frozen.sh origin/<base>`.
- `.github/workflows/macos-app.yml` builds and tests the Swift companion on
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 83893b95..75f1785e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -321,7 +321,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Published `docs/benchmarks/longmemeval-s-decomposition-2026-10-12.md`, which
splits the LongMemEval-S retrieval number into capture cost, ranking quality
and harness artifacts, and records what the observation stream recovered
- (zero-LLM FTS `hit@5` 0.666 → 0.868 on all 470 questions). The benchmark,
+ (zero-LLM FTS `hit@5` 0.662 → 0.855 on all 470 questions). The benchmark,
evals and comparison docs no longer blame the 2 KB excerpt cap for the gap
(pages holding exactly the captured text score 0.968 against 0.972 for whole
sessions) and no longer attribute agentmemory's 0.967 to LongMemEval-S: it is
diff --git a/README.md b/README.md
index 96d26e46..cffacd47 100644
--- a/README.md
+++ b/README.md
@@ -270,8 +270,9 @@ open "companions/ai-memory-macos/dist/AI Memory.app"
```
Drag **AI Memory.app** to `/Applications`, then **Install & Start Server**
-from the menu extra (no Dock icon). When the status item is green, wire an
-agent with the bundled binary:
+from the menu extra (no Dock icon). The app reads the bearer token `init`
+wrote into its data dir, so the status item turns green on its own. Then wire
+an agent with the bundled binary:
```bash
BIN="/Applications/AI Memory.app/Contents/Resources/runtime/ai-memory"
@@ -514,7 +515,10 @@ readable wiki pages; the next session starts with a handoff.
- 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`.
+ the wiki and a JSON API under `/api/v1`. On a server with a bearer token
+ and no user accounts (every fresh install), the browser asks for a username
+ and password: any username, and the contents of
+ `<data_dir>/auth-tokens/default` as the password.
- Back up host-side harness configuration with
`ai-memory backup-agents -o agent-assets.tar.gz`; inspect a restore with
`ai-memory restore-agents -i agent-assets.tar.gz`, then add `--apply` only
@@ -583,8 +587,9 @@ One Rust binary runs an MCP/HTTP server and owns one data directory:
Hooks POST observations to the server. The server serializes writes
through one SQLite writer, compiles session observations into markdown
pages, and serves retrieval through FTS5, entity-match and graph-neighbor RRF,
-optional vector RRF, bounded source-authority adjustment, and bounded
-raw-observation fallback for non-global searches.
+optional vector RRF, an observation-evidence stream that lifts a session's
+page when its captured turns match (on by default), bounded source-authority
+adjustment, and bounded raw-observation fallback for non-global searches.
See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the data-flow
diagram, crate breakdown, schema notes, and invariants.
@@ -631,7 +636,7 @@ 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. |
| [`docs/managed-harness-contributions.md`](docs/managed-harness-contributions.md) | Protocol and acceptance bar for adding managed resume, transcript import, and startup context delivery to another harness. |
-| [`docs/companion-crates.md`](docs/companion-crates.md) | Optional companion projects: the [importer](companions/ai-memory-importer), [external lifecycle relay](companions/ai-memory-relay), and [team-wiki export](companions/ai-memory-wikisync). |
+| [`docs/companion-crates.md`](docs/companion-crates.md) | Optional companion projects: the [importer](companions/ai-memory-importer), [external lifecycle relay](companions/ai-memory-relay), and [team-wiki sync](companions/ai-memory-wikisync). |
| [`docs/external-lifecycle.md`](docs/external-lifecycle.md) | External lifecycle producers: per-execution native capture suppression, preserved handoffs, batch ingestion and stable retry identity. |
| [`docs/auto-improvement-loop.md`](docs/auto-improvement-loop.md) | Auto-improvement design notes: scheduled review, auto-approval default, manual review opt-in, pending proposal storage, and curator work. |
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 7ca03ca5..f74b363d 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -419,8 +419,8 @@ prunable rather than only after it ages in place.
Legacy raw fallback recall searches the durable `observations` table via
FTS5; lifecycle HookEnvelope JSON is not a complete transcript archive.
* `<data_dir>/logs/`: rolling daily `tracing` output.
-* `<data_dir>/models/`: reserved for bundled embedding models
- (M9.5+, when local `ort` lands).
+* `<data_dir>/models/`: the local embedding model (`all-MiniLM-L6-v2`),
+ fetched on first use and droppable by hand for offline installs.
* `<data_dir>/client-projects.json`: private, client-local checkout links for
`ai-memory show`, keyed by credential-free server identity plus workspace and
project. It is not part of the SQLite/wiki source of truth, and no server API
@@ -565,7 +565,9 @@ crates/
├── ai-memory-hooks/ payload schemas, sanitiser, /hook ingress.
├── ai-memory-llm/ provider auth boundary + LlmProvider / Embedder traits.
├── ai-memory-consolidate/ Karpathy ingest / lint / sweep / auto-improve pipeline.
+├── ai-memory-web/ read-only /web UI and /api/v1 JSON routes.
├── ai-memory-workstream/ read-only native transcript + launch adapters.
+├── ai-memory-test-support/ shared test helpers (dev-dependency only, no test binary).
└── ai-memory-cli/ `ai-memory` binary entry point + thin HTTP subcommands.
```
@@ -592,9 +594,9 @@ does not need to ride on the public protocol change.
| Tool | Hint | Purpose |
|---|---|---|
-| `memory_query` | read-only | FTS5 + entity-match + graph RRF + optional vector RRF search, followed by bounded kind/tier/pinned/tag authority adjustment and raw fallback. Bumps access counters for page hits. Defaults to the current project; single-project calls (project implicit or named with `workspace`+`project`) also union the reserved `_global` preferences scope as `global_scope_hits`, and only an explicit multi-`scopes` set opts out (#930); `scopes` searches named sibling projects; `global=true` searches every project at once (each hit annotated with its workspace + project). With `AI_MEMORY_RERANKER=llm`, project/scopes candidate pools are fused before at most one final LLM relevance pass; query/title/snippet data is bounded and JSON-encoded, and any timeout, provider error, invalid/incomplete score set, or four-call concurrency saturation preserves the adjusted order. The distinct `global=true` FTS-only ranker and supplemental global-preference hits are not reranked. `explain=true` attaches per-hit `score_details` (per-stream ranks, matched entities, raw FTS/cosine/entity inverse-frequency scores, the matched observation ids when the observation stream voted, RRF contributions, graph provenance including the typed edge kind (`causes`/`fixes`/`contradicts`) a neighbour was reached by, the page's evidence count, authority multiplier, and optional rerank score) to project/scopes hits plus a top-level `streams_active` list and a `timings` object with each stream's wall time in milliseconds (`fts_ms`, `entity_ms`, `vector_ms` for the stored-vector scans, `graph_ms`, `observation_ms`, `rerank_ms`; a stream that did not run is left out, and `scopes` searches sum per stream). Timings are read only on an explained query; the normal path takes no clock reading for them. The global FTS-only ranker reports its active stream and `fts_ms` without per-hit details; `as_of` reports no timings. `include_expired=true` also returns TTL-expired pages. `include_superseded=true` also returns superseded (non-latest) page versions across the FTS/entity/vector/graph streams, each hit labelled `superseded: true` (the current version is never marked); default-off is byte-identical to the latest-only behaviour, and `global=true` / `as_of` are unaffected. `pin_first=true` prepends the project's bounded pinned latest pages (`ReaderPool::list_pinned_pages`, cap 10) ahead of the fused hits, deduped by page id (a pinned page that also matches appears once, marked `pinned: true`) and re-truncated to the requested limit; it applies to single-project searches (default or `workspace`+`project`), is ignored on `scopes`/`global`/`as_of`, and default-off is byte-identical. `answer=true` (opt-in, off by default) additionally synthesizes a cited natural-language answer over the top hits via the configured LLM provider (`complete_structured`, JSON-schema `{ answer, citations }`), attached as `answer: { text, citations }`; with no provider configured it returns the hits plus an `answer_unavailable` note instead of erroring, and with `answer` unset/`false` no provider is accessed and the response is byte-identical (invariant #13). It applies to the normal single-project/`scopes` path; `global`/`as_of` ignore it. Answer quality is not yet eval-validated. An optional `reasoning` tier (`minimal` (default) / `low` / `medium` / `high` / `max`) tunes the synthesis effort: `ChatRequest` carries no per-request reasoning field (the provider-level `reasoning_effort` is fixed at construction from config), so the tier maps to a per-tier max-token budget scaled off the path's base (answer base 2 000; `minimal` = 1x = byte-identical, `low` 1.5x, `medium` 2x, `high` 3x, `max` 4x). The tier is inert unless the `answer` LLM path runs (invariant #13); an unknown value is rejected by the schema (invariant #7). |
+| `memory_query` | read-only | FTS5 + entity-match + graph RRF + optional vector RRF + observation-evidence stream (on by default) search, followed by bounded kind/tier/pinned/tag authority adjustment and raw fallback. Bumps access counters for page hits. Defaults to the current project; single-project calls (project implicit or named with `workspace`+`project`) also union the reserved `_global` preferences scope as `global_scope_hits`, and only an explicit multi-`scopes` set opts out (#930); `scopes` searches named sibling projects; `global=true` searches every project at once (each hit annotated with its workspace + project). With `AI_MEMORY_RERANKER=llm`, project/scopes candidate pools are fused before at most one final LLM relevance pass; query/title/snippet data is bounded and JSON-encoded, and any timeout, provider error, invalid/incomplete score set, or four-call concurrency saturation preserves the adjusted order. The distinct `global=true` FTS-only ranker and supplemental global-preference hits are not reranked. `explain=true` attaches per-hit `score_details` (per-stream ranks, matched entities, raw FTS/cosine/entity inverse-frequency scores, the matched observation ids when the observation stream voted, RRF contributions, graph provenance including the typed edge kind (`causes`/`fixes`/`contradicts`) a neighbour was reached by, the page's evidence count, authority multiplier, and optional rerank score) to project/scopes hits plus a top-level `streams_active` list and a `timings` object with each stream's wall time in milliseconds (`fts_ms`, `entity_ms`, `vector_ms` for the stored-vector scans, `graph_ms`, `observation_ms`, `rerank_ms`; a stream that did not run is left out, and `scopes` searches sum per stream). Timings are read only on an explained query; the normal path takes no clock reading for them. The global FTS-only ranker reports its active stream and `fts_ms` without per-hit details; `as_of` reports no timings. `include_expired=true` also returns TTL-expired pages. `include_superseded=true` also returns superseded (non-latest) page versions across the FTS/entity/vector/graph streams, each hit labelled `superseded: true` (the current version is never marked); default-off is byte-identical to the latest-only behaviour, and `global=true` / `as_of` are unaffected. `pin_first=true` prepends the project's bounded pinned latest pages (`ReaderPool::list_pinned_pages`, cap 10) ahead of the fused hits, deduped by page id (a pinned page that also matches appears once, marked `pinned: true`) and re-truncated to the requested limit; it applies to single-project searches (default or `workspace`+`project`), is ignored on `scopes`/`global`/`as_of`, and default-off is byte-identical. `answer=true` (opt-in, off by default) additionally synthesizes a cited natural-language answer over the top hits via the configured LLM provider (`complete_structured`, JSON-schema `{ answer, citations }`), attached as `answer: { text, citations }`; with no provider configured it returns the hits plus an `answer_unavailable` note instead of erroring, and with `answer` unset/`false` no provider is accessed and the response is byte-identical (invariant #13). It applies to the normal single-project/`scopes` path; `global`/`as_of` ignore it. Answer quality is not yet eval-validated. An optional `reasoning` tier (`minimal` (default) / `low` / `medium` / `high` / `max`) tunes the synthesis effort: `ChatRequest` carries no per-request reasoning field (the provider-level `reasoning_effort` is fixed at construction from config), so the tier maps to a per-tier max-token budget scaled off the path's base (answer base 2 000; `minimal` = 1x = byte-identical, `low` 1.5x, `medium` 2x, `high` 3x, `max` 4x). The tier is inert unless the `answer` LLM path runs (invariant #13); an unknown value is rejected by the schema (invariant #7). |
| `memory_recent` | read-only | Most-recently-updated `is_latest=1` pages. |
-| `memory_read_page` | read-only | Fetch the FULL body of a single wiki page by `path` or by top FTS5 hit for a `query`; optional `workspace` + `project` targets a named sibling workspace/project. Use when an agent needs more than the 24-word snippets from `memory_query`. `include_related=true` also walks the link graph outward from the page (bounded BFS reusing the `page_links` primitive per node: default 1 hop, hard cap 3, global visited set for dedup/cycle-safety, total-node cap 50, cross-project aware) and returns a `related` array of reachable pages, each labelled with its `depth` (hop distance) and `direction` (`link`/`backlink`); default-off is byte-identical (no `related` field). |
+| `memory_read_page` | read-only | Fetch the FULL body of a single wiki page by `path` or by top FTS5 hit for a `query`; optional `workspace` + `project` targets a named sibling workspace/project. Use when an agent needs more than the 24-word snippets from `memory_query`. `include_related=true` also walks the link graph outward from the page (bounded BFS reusing the `page_links` primitive per node: default 1 hop, hard cap 3, global visited set for dedup/cycle-safety, total-node cap 50, cross-project aware) and returns a `related` array of reachable pages, each labelled with its `depth` (hop distance) and `direction` (`link`/`backlink`); default-off is byte-identical (no `related` field). The response carries the page's current version as `page_id`, the value compare-and-write calls pass back. |
| `memory_read_session_observations` | read-only | Page through ONE session's raw hook observations (`ObservationRecord` with full sanitized body, capped per row by `body_max_chars`), restricted to the rows that landed in the resolved scope and to sessions the caller may see; `total` and `elided_other_scope` report the in-scope count and the rows the session left in another project. `session_id` omitted reads the latest completed visible session. |
| `memory_status` | read-only | Counts, paths, version, plus the `scope` that answered: `workspace`, `project`, and `resolved_by` (`explicit`, `session`, `shared_slot`, `startup_seed`, `default`, `default_after_mismatch`). Unscoped reads resolved by `startup_seed` or `default_after_mismatch` also log a server warning. |
| `memory_briefing` | read-only | Structured counts/activity/rules/slots/recent snapshot. Project-scoped snapshots also carry a bounded `pinned` list (up to 10) of the project's pinned latest pages (`pinned = 1`, newest first) as standing SessionStart hot-context, distinct from `slots`, which is keyed by the `_slots/` path prefix; empty and omitted from JSON when the project has no pins, so the default shape is unchanged. Opt-in `settled_first: true` leads with up to 8 of the project's highest-standing `rule`/`decision` pages, ordered by evidence count then recency; off by default. `scope` names the workspace/project briefed and `resolved_by` how it was chosen. |
@@ -617,8 +619,8 @@ long-lived entry there is expected policy behavior, not a fault.
| `memory_consolidate` | destructive | LLM-driven page rewrite. `multi_page=true` for atomic fan-out; an update whose path names an existing pinned page is skipped (`_slots/` excepted). Omitting `session_id` (or sending a blank one) consolidates the latest completed session in the resolved project; the same omission on a project with none fails as `no completed session in <scope>`. Consolidation prompts append the target project's active reserved `_prompts/consolidation.md` body as sanitized, 2,000-character-capped, JSON-encoded, untrusted advisory preferences; TTL-expired pages are ignored and a per-call `instructions` argument overrides the page for one call. Both system prompts keep schema, evidence, disclosure, tool-use, and output rules authoritative. |
| `memory_feedback` | write | Record a quality signal for one page by exact `path`: `helpful`/`not_helpful` step `pages.salience` for sweep-eligible episodic pages, while `stale`/`wrong` floor salience and surface any current page as a `feedback_flagged` lint finding. Never deletes; the path resolves to the current version in the transaction, so a later rewrite clears it. Retrieved content never authorizes feedback by itself. |
| `memory_auto_improve` | write | Manually review a completed session and apply or stage validated wiki edits through the auto-improvement approval path. Without a session ID, selects the newest completed session with no persisted auto-improvement run so repeated calls advance through preflight skips; an explicit ID remains rerunnable. The server also schedules review for new sessions; `[auto_improve] require_approval = true` leaves proposals pending for manual review. |
-| `memory_write_page` | destructive | Write durable wiki knowledge when the user explicitly asks to remember/annotate it. `scope: "global"` writes into the reserved `_global` preferences scope and `scope: "profile"` into the caller's cross-project profile (path placed under `profile/`); optional `expires_at` sets an RFC3339 or date-only TTL; optional `session_id` cites a session of the same project as evidence, and on `sessions/<id>.md` stamps the session-page frontmatter and settles the queued consolidation job. |
-| `memory_delete_page` | destructive | Delete a single page by exact `path`; `scope: "profile"` deletes from the caller's cross-project profile. Fires the admission chain (op=delete); idempotent. |
+| `memory_write_page` | destructive | Write durable wiki knowledge when the user explicitly asks to remember/annotate it. `scope: "global"` writes into the reserved `_global` preferences scope and `scope: "profile"` into the caller's cross-project profile (path placed under `profile/`); optional `expires_at` sets an RFC3339 or date-only TTL; optional `session_id` cites a session of the same project as evidence, and on `sessions/<id>.md` stamps the session-page frontmatter and settles the queued consolidation job. Optional `expected_page_id` (the `page_id` a read returned) writes only if that is still the latest version, and `create_only: true` refuses to overwrite an existing page; a failed precondition writes nothing and returns `reason: "precondition_failed"` with the current version (see `docs/programmatic-memory.md`). |
+| `memory_delete_page` | destructive | Delete a single page by exact `path`; `scope: "profile"` deletes from the caller's cross-project profile. Fires the admission chain (op=delete); idempotent. Optional `expected_page_id` deletes only if that is still the latest version; otherwise nothing is deleted and the call returns `reason: "precondition_failed"`. |
| `memory_forget_sweep` | destructive | Retention pass: evict cold pages through the wiki layer, purge aged tombstone ancestry, and hard-delete TTL-expired pages. `dry_run=true` for preview. |
| `memory_lint` | destructive | Rule-based + LLM contradiction findings → `wiki/_lint/`. Also runs a **zero-LLM contradiction detector** (design-memory-aging.md A5): cold semantic/procedural pages whose already-stored embeddings sit in the `contradiction_band_min`–`contradiction_band_max` cosine-similarity band (default 0.4–0.75; "same topic, not a near-duplicate"; at/above the max is A3 dedup, below the min unrelated) get an advisory `contradiction` finding with newer-wins timestamp advice. Bounded (one embeddings load over the capped cold set, capped findings, deterministic); a clean no-op with no embedder configured; advisory-only (never deletes/edits/supersedes a page and persists no edge, invariants #13, #16, #2), so no migration. On a single-language or single-domain store, background similarity between unrelated pages already sits well above the default floor, so the band measures domain proximity more than conflict and produces noisy findings, so raise `contradiction_band_min` (`config.toml` or `AI_MEMORY_CONTRADICTION_BAND_MIN`) for such a store. |
| `memory_install_self_routing` | read-only | Return the canonical slim routing snippet plus managed Agent Skill payloads and target hints for CLAUDE.md / AGENTS.md installs. |
@@ -692,8 +694,8 @@ browser compatibility path:
| Human password | `POST /auth/login` body | Session issuance only |
| Web session | `ai_memory_session` cookie + CSRF | `/auth/me`, `/admin/*`, `/api/v1/*` by `AuthLevel`; never `/mcp` or hooks |
| Recovery | `POST /auth/recovery` body | Root password reset; no session |
-| API key | `Authorization: Bearer` (`aim_`, root `AI_MEMORY_AUTH_TOKEN`, or external `amk_`) | Machine APIs; never a web session |
-| Deprecated browser compatibility | HTTP Basic root bearer, then HttpOnly `ai_memory_auth` cookie | GET-only browser routes until any human password or completed bootstrap exists; never machine routes |
+| API key | `Authorization: Bearer` (`aim_`, the root bearer from `AI_MEMORY_AUTH_TOKEN`, `[auth].bearer_token` or `[auth].bearer_token_file`, or external `amk_`) | Machine APIs; never a web session |
+| Browser token sign-in (no human accounts yet) | HTTP Basic with the root bearer as the password, then HttpOnly `ai_memory_auth` cookie | GET-only browser routes until any human password or completed bootstrap exists; never machine routes. A fresh install has no human accounts, so this is how a browser reaches `/web` there: the 401 carries a Basic challenge, which the HTML login redirect lets through |
The deprecated Basic/cookie path stops immediately when human auth becomes
active; restart is not required. `/web` SPA HTML is public static; the builtin
@@ -1390,16 +1392,10 @@ the server URL is loopback and no `default` server profile is registered.
## Future work
-* **M9.5: local embeddings via `ort`.** Bundle `bge-small-en-v1.5`
- for an API-key-free homelab path. ~200 MB image bloat; trait is
- ready and only needs the `OrtBgeSmallEmbedder` impl + tokenizer wiring.
* **`sqlite-vec` integration.** Brute-force cosine works fine to a few
thousand pages; past that, the `sqlite-vec` extension is the next
step. See [`docs/vector-backend-policy.md`](vector-backend-policy.md)
for the criteria that should justify adding it.
-* **Scheduled consolidation queue.** Forget sweep, lint, and auto-improvement
- already run on server-side schedules; a future queue can compile session
- summaries outside hook latency.
* **Richer curator actions.** The shipped curator stages only one report page;
future work can add individual merge/supersession/link-fix proposals while
keeping deletes and semantic rewrites review-gated.
diff --git a/docs/benchmarks/README.md b/docs/benchmarks/README.md
index 3150215a..cd198eb6 100644
--- a/docs/benchmarks/README.md
+++ b/docs/benchmarks/README.md
@@ -13,20 +13,24 @@ cargo run --release -p ai-memory-eval -- retrieval --fetch
| date | dataset | mode | overall hit@5 | file |
|---|---|---|---|---|
-| **2026-10-12** | LongMemEval-S (v1) | **zero-llm FTS + observation stream (2.7, unreleased; on by default)** | **0.868** | [longmemeval-s-decomposition-2026-10-12.md](longmemeval-s-decomposition-2026-10-12.md) |
+| **2026-10-13** | LongMemEval-S (v1) | **zero-llm FTS + observation stream (2.7, unreleased; on by default)** | **0.855** | [longmemeval-s-decomposition-2026-10-12.md](longmemeval-s-decomposition-2026-10-12.md) |
| **2026-09-21** | LongMemEval-S (v1) | **local embeddings (2.4 RC, current)** | **0.815** | [retrieval-ab-r2.md](retrieval-ab-r2.md) |
| 2026-09-21 | LongMemEval-S (v1) | zero-llm, stopword-filtered FTS (2.4 RC) | 0.666 | [retrieval-ab-r2.md](retrieval-ab-r2.md) |
| 2026-09-01 | LongMemEval-S (v1) | local embeddings (2.0 default, prior) | 0.823 | [longmemeval-s-2026-09-01-local.md](longmemeval-s-2026-09-01-local.md) |
| 2026-09-01 | LongMemEval-S (v1) | zero-llm, stopword-filtered FTS (prior) | 0.668 | [longmemeval-s-2026-09-01-fts.md](longmemeval-s-2026-09-01-fts.md) |
| 2026-09-01 | LongMemEval-S (v1) | zero-llm (pre-2.0 FTS) | 0.617 | [longmemeval-s-2026-09-01.md](longmemeval-s-2026-09-01.md) |
-The 2026-10-12 row is the 2.7 observation stream measured on all 470
-questions: zero-LLM FTS `hit@5` 0.666 → 0.868 (hit@1 0.530 → 0.619, hit@10
-0.694 → 0.936). Local embeddings with the stream went 0.800 → 0.867 on a
+The 2026-10-13 row is the 2.7 observation stream measured on all 470
+questions, stream off against stream on on the same build: zero-LLM FTS
+`hit@5` 0.662 → 0.855 (hit@1 0.511 → 0.611, hit@10 0.687 → 0.934; 91 questions
+gained, none lost). Local embeddings with the stream went 0.800 → 0.867 on a
90-question stratified sample; a full-set local run with the stream has not
been done yet, so 0.815 stays the latest full-set local number. Context
-tokens for the top five hits rose 7–19% in the final A/B runs, and p95
-latency stayed within the stream's budget. Details and commands are in the
+tokens for the top five hits rose 7–18%, and p95 latency rose 13 ms on the
+full set (84 → 97 ms). These numbers come from the harness corrected on
+2026-10-13, which replays each question's sessions under their own session
+ids; the first published figures (0.666 → 0.868) came from a harness that
+reused them across questions and left a few sessions without a page. Details and commands are in the
decomposition report below.
The 2026-09-21 (2.4 RC) re-run shows no default-ranking regression: local
@@ -49,7 +53,7 @@ harness before the next change landed.
[longmemeval-s-decomposition-2026-10-12.md](longmemeval-s-decomposition-2026-10-12.md)
splits the pipeline number into capture cost, ranking quality and harness
artifacts. With each raw session indexed whole (component mode, ranking
-only), zero-LLM FTS scores 0.972 `hit@5` on all 470 questions, against 0.666
+only), zero-LLM FTS scores 0.972 `hit@5` on all 470 questions, against 0.662
through the shipped capture path. The gap was not the 2 KB excerpt cap: pages
holding exactly the text capture keeps score 0.968. It was the zero-LLM
session page, which indexed only 80-character turn titles and no assistant
diff --git a/docs/benchmarks/longmemeval-s-decomposition-2026-10-12.md b/docs/benchmarks/longmemeval-s-decomposition-2026-10-12.md
index 0ee61bc6..c8d9df69 100644
--- a/docs/benchmarks/longmemeval-s-decomposition-2026-10-12.md
+++ b/docs/benchmarks/longmemeval-s-decomposition-2026-10-12.md
@@ -38,14 +38,19 @@ Decomposition runs (M1, 2026-10-10 to 2026-10-11):
or a stratified sample: `--stratify N` takes the first N questions of each
of the six types (single-session-preference has only 30)
-Observation-stream runs (R1, 2026-10-12):
-
-- final build: `release/2.7` at `8d8c7780`, stream switched on with
- `AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=true` (it became the default in
- `5b550300`)
-- full-set A/B: run twice, on observation-stream work not yet committed on
- top of `b7ac5a70` (the reports record that commit); the final build's
- full-set run reproduces the candidate's accuracy exactly
+Pipeline re-runs (2026-10-13, corrected harness): the FTS full-set pipeline
+with reachability, both date-prefix ablations and the strat-230 local
+pipeline-vs-whole-session A/B, on `release/2.7` at `85eb1723` with
+`AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false` on every arm (see "Harness
+correction").
+
+Observation-stream runs (R1, re-run 2026-10-13 on the corrected harness):
+
+- build: `release/2.7` at `85eb1723`, where the stream is on by default; the
+ baseline side sets `AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false` and the
+ candidate side `=true`
+- harness: `85eb1723`, which replays each question's sessions under their own
+ session ids (see "Harness correction")
- dataset, hardware and model as above (original `longmemeval_s` file)
Latency and ingest throughput were measured while two or three runs shared
@@ -57,10 +62,10 @@ its own data dir.
| What is measured | FTS (zero-LLM) | Local embeddings |
|---|---|---|
| Grep over whole raw sessions, no server (`--engine grep`) | 0.887 (470; 417/470 on both dataset files) | n/a |
-| **Pipeline**, shipped 2.6 capture and ranking (`--ingest hooks`) | **0.666** (470) | 0.809 and 0.804 (strat-230, two runs); 0.800 (strat-120, three runs) |
-| Pipeline with the per-turn date prefix removed (strat-120) | 0.658 → 0.792 | 0.800 → 0.900 |
-| Pages holding only the text capture keeps (`--ingest captured-session`) | 0.968 (470) | 0.804 → 0.943 (strat-230) |
-| **Component**, whole raw sessions (`--ingest whole-session`) | **0.972** (470, both dataset files) | 0.809 → 0.957 (strat-230) |
+| **Pipeline**, shipped 2.6 capture and ranking (`--ingest hooks`) | **0.662** (470) | 0.787 (strat-230); 0.800 (strat-120) |
+| Pipeline with the per-turn date prefix removed (strat-120) | 0.658 → 0.792 | 0.800 → 0.892 |
+| Pages holding only the text capture keeps (`--ingest captured-session`) | 0.968 (470) | 0.943 (strat-230) |
+| **Component**, whole raw sessions (`--ingest whole-session`) | **0.972** (470, both dataset files) | 0.957 (strat-230) |
Strat-230 is `--stratify 40` and strat-120 is `--stratify 20`. The published
full-set local pipeline number is 0.815
@@ -71,25 +76,28 @@ Other FTS metrics on all 470 questions:
| | pipeline | captured-session pages | whole-session pages |
|---|---|---|---|
-| hit@1 | 0.530 | 0.887 | 0.885 |
-| hit@10 | 0.694 | 0.979 | 0.977 |
-| recall@5 | 0.536 | 0.918 | 0.922 |
-| context tokens, mean | 351 | 502 | 505 |
-| query p50 / p95 ms | 14 / 99 | 27 / 99 | 28 / 93 |
+| hit@1 | 0.511 | 0.887 | 0.885 |
+| hit@10 | 0.687 | 0.979 | 0.977 |
+| recall@5 | 0.533 | 0.918 | 0.922 |
+| context tokens, mean | 367 | 502 | 505 |
+| query p50 / p95 ms | 14 / 95 | 27 / 99 | 28 / 93 |
FTS `hit@5` per slice, pipeline → whole-session: knowledge-update 0.764 →
-1.000, multi-session 0.579 → 0.975, single-session-assistant 0.804 → 1.000,
+1.000, multi-session 0.562 → 0.975, single-session-assistant 0.804 → 1.000,
single-session-preference 0.533 → 0.900, single-session-user 0.688 → 1.000,
-temporal-reasoning 0.654 → 0.945. Whole-session pages gained 145 questions
-and lost 1.
+temporal-reasoning 0.654 → 0.945. Whole-session pages gained about 146
+questions and lost 1 (the pipeline row is from the corrected harness, the
+whole-session row from the original run; whole-session ingest does not use
+session ids, so it is unaffected).
Confirmation runs on strat-120 reproduce each effect: whole vs pipeline FTS
-+0.308 (+38/−1) against +0.306 on the full set; captured vs pipeline FTS
-+0.300 (+38/−2); local whole vs pipeline +0.142 against +0.148 on strat-230.
++0.308 (+38/−1) against +0.310 on the full set; captured vs pipeline FTS
++0.300 (+38/−2); local whole vs pipeline +0.142, against +0.170 (+42/−3) on
+strat-230 with the corrected harness.
FTS returned identical per-question results across repeated runs.
With the evidence in the index, the same FTS ranks an evidence session into
-the top 5 for 97.2% of questions; through capture it managed 66.6%. Most of
+the top 5 for 97.2% of questions; through capture it managed 66.2%. Most of
the gap is therefore in capture.
## Reachability: the evidence was not on the page
@@ -124,13 +132,14 @@ turns (`stop` observations) are titled just `stop`, so no assistant text
reaches the page at all. The full observation bodies were indexed in
`observations_fts` the whole time, but `memory_query` read them only when page
search found nothing. With about 50 session pages per question that almost
-never happened: 50 of 470 questions took that fallback, and those hit at
-46/50.
+never happened: 44 of 470 questions took that fallback, and those hit at
+42/44.
-The pipeline still reached 0.666 because sessions were often found through
+The pipeline still reached 0.662 because sessions were often found through
topic words at the start of a prompt rather than through the answer. Only 39
-of its 313 hits had page-reachable evidence. Of its 157 misses, 148 had none,
-and whole-session pages recover 145 of the 157.
+of its 311 hits had page-reachable evidence. Of its 159 misses, 150 had none;
+whole-session pages, which hit 0.972 of the full set, recover nearly all of
+them.
The local embedder reads the page body cut to 6,144 bytes and then to 512
tokens. On these short pipeline pages that window holds the whole page. On
@@ -149,7 +158,7 @@ session-start`) or dropping it (`none`) on strat-120:
- FTS `hit@5` 0.658 → 0.792 (+0.133; 21 gained, 5 lost). Two independent runs
gave identical per-question results, and `none` gives the same number.
-- Local `hit@5` 0.800 → 0.900 (+0.100; 14 gained, 2 lost).
+- Local `hit@5` 0.800 → 0.892 (+0.092; 14 gained, 3 lost).
- Session-page turn reachability rises from 0.080 to 0.267, and the page
ceiling from 0.142 to 0.408.
@@ -184,44 +193,74 @@ nothing new is written to the wiki. It is on by default in 2.7; setting it to
`false` restores the previous ranking exactly.
Baseline is the stream off, candidate is the stream on, same build, same
-questions:
+questions. These are the corrected-harness runs (see "Harness correction"
+below):
| run | questions | hit@5 | hit@1 | hit@10 | recall@5 | p95 ms | flips |
|---|---|---|---|---|---|---|---|
-| FTS, full set | 470 | 0.666 → **0.868** | 0.530 → 0.619 | 0.694 → 0.936 | 0.536 → 0.767 | 103 → 98 | +96/−1 |
-| FTS, final build | 180 (`--stratify 30`) | 0.656 → **0.850** | 0.494 → 0.589 | 0.689 → 0.928 | 0.558 → 0.741 | 32 → 43 | +36/−1 |
-| Local, final build | 90 (`--stratify 15`) | 0.800 → **0.867** | 0.489 → 0.533 | 0.867 → 0.933 | 0.677 → 0.773 | 77 → 84 | +7/−1 |
+| FTS, full set | 470 | 0.662 → **0.855** | 0.511 → 0.611 | 0.687 → 0.934 | 0.533 → 0.743 | 84 → 97 | +91/−0 |
+| FTS | 180 (`--stratify 30`) | 0.656 → **0.828** | 0.483 → 0.594 | 0.689 → 0.917 | 0.558 → 0.719 | 25 → 40 | +32/−1 |
+| Local | 90 (`--stratify 15`) | 0.800 → **0.867** | 0.500 → 0.533 | 0.867 → 0.933 | 0.677 → 0.764 | 68 → 75 | +7/−1 |
FTS `hit@5` per slice on the full set, off → on: knowledge-update 0.764 →
-0.944, multi-session 0.579 → 0.893, single-session-assistant 0.804 → 0.857,
-single-session-preference 0.533 → 0.667, single-session-user 0.688 → 0.891,
-temporal-reasoning 0.654 → 0.843. No slice dropped. The two full-set A/B runs
-gave identical accuracy, and the final build's single-config full-set run
-gave the same 0.868, with a p95 of 95 ms. The full-set p95 in the table is
-from the second A/B run. The first ran on a build whose observation scan was
-not yet bounded to the project, and measured a baseline p95 of 76 ms and a
-candidate p95 of 1,373 ms; the bounded scan is what shipped.
+0.944, multi-session 0.562 → 0.868, single-session-assistant 0.804 → 0.839,
+single-session-preference 0.533 → 0.667, single-session-user 0.688 → 0.875,
+temporal-reasoning 0.654 → 0.835. No slice dropped, and no question lost its
+top-5 hit. The three runs shared the host one after another, never with each
+other. An earlier build whose observation scan was not yet bounded to the
+project measured a candidate p95 of 1,373 ms; the bounded scan is what
+shipped.
Context tokens rise. The candidate returns more hits: with the stream off,
-FTS returned fewer than five hits for 242 of 470 questions (5.2 hits on
-average), and with it on, 9.8. So the raw mean rises more than the cost of the
+FTS returned fewer than five hits for 219 of 470 questions (5.6 hits on
+average), and with it on, 9.9. So the raw mean rises more than the cost of the
top five hits does:
| run | mean context tokens, all hits | top five hits only |
|---|---|---|
-| FTS, 180 questions | 411.2 → 561.7 | 264.0 → 283.6 (+7.4%) |
-| Local, 90 questions | 473.6 → 562.4 | 236.8 → 281.2 (+18.8%) |
-| FTS, 470 questions | 350.2 → 542.1 | 249.6 → 273.6 (+9.6%) |
+| FTS, 470 questions | 366.7 → 548.8 | 256.3 → 276.4 (+7.9%) |
+| FTS, 180 questions | 414.9 → 565.7 | 266.7 → 285.4 (+7.0%) |
+| Local, 90 questions | 476.6 → 563.2 | 238.3 → 281.6 (+18.2%) |
"Top five hits only" scales each question's estimate by `min(returned, 5) /
-returned`. In the 470-question row the "off" side is from the `b7ac5a70` A/B
-and the "on" side is the final build; the final build trimmed the excerpt a
-hit carries, which affects only the "on" side.
+returned`.
The stream recovered about two thirds of the FTS headroom the decomposition
-found (0.666 → 0.868, against 0.968 for captured-text pages). A full-set
+found (0.662 → 0.855, against 0.968 for captured-text pages). A full-set
local run with the stream on has not been done yet.
+## Harness correction (2026-10-13)
+
+LongMemEval reuses session ids across questions: 4,715 of the 23,566 scored
+haystack sessions, 8 of them evidence sessions, also appear in an earlier
+question's haystack. The first runs replayed every session under its raw id,
+so a reused session already existed in the earlier question's project when
+the later replay arrived. The store filed its turns under the new project but
+dropped its `session-end` as naming a foreign scope, so those sessions never
+got a session page in the later project. This was the "8 of 845 evidence
+sessions had no session page" the first version of this report could not
+explain. A real harness mints a fresh id per session, so the replay now
+namespaces each id by question (`stored_session_uuid` in
+`evals/src/retrieval/ingest.rs`, harness `85eb1723`), and all 845 evidence
+pages are present.
+
+The pipeline numbers above, and the observation-stream runs, are from the
+corrected harness. The changes were small for the pipeline and larger for the
+stream, which had partly been scoring sessions whose page was missing:
+
+| run | first published | corrected |
+|---|---|---|
+| FTS pipeline, 470 | 0.666 | 0.662 |
+| Local pipeline, strat-230 | 0.809 / 0.804 | 0.787 |
+| FTS date-prefix ablation, strat-120 | 0.658 → 0.792 | 0.658 → 0.792 |
+| Local date-prefix ablation, strat-120 | 0.800 → 0.900 | 0.800 → 0.892 |
+| FTS stream off → on, 470 | 0.666 → 0.868 | 0.662 → 0.855 |
+| Local stream off → on, 90 | 0.800 → 0.867 | 0.800 → 0.867 |
+
+Component, grep and captured-session runs write pages directly or read the
+dataset, never replaying session ids through hooks, so they are unchanged.
+Reachability is unchanged too (0.056 / 0.102 on the session page).
+
## Comparability with other published numbers
- **Harness agreement.** `--engine grep` reimplements agentmemory's grep
@@ -255,8 +294,6 @@ local run with the stream on has not been done yet.
- With full text in the index, local embeddings scored below FTS alone on the
same 230 questions (0.943 against 0.974 on captured-text pages; 10 lost,
3 gained). The page vector covers only the first 512 tokens.
-- 8 of 845 evidence sessions had no session page after hook ingest, affecting
- at most 5 questions. The cause was not investigated.
- Hook ingest slows as the store grows: in the full pipeline run, completed
questions per minute fell from about 22 to about 5 (about 23,000 sessions
across 470 projects, contended host). The cause was not profiled.
@@ -299,22 +336,16 @@ $E retrieval --stratify 20 --embeddings local --date-prefix turn --candidate-dat
$E retrieval --stratify 20 --embeddings local --candidate-server-env AI_MEMORY_RETRIEVAL__BELIEF_AUTHORITY_WEIGHT=0.3
```
-Observation stream. These ran against builds where the stream was off by
-default; on a build where it defaults on, pass
-`--server-env AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false` for the baseline
-side:
+Observation stream (corrected harness, stream on by default):
```bash
B=target/release
-FLAG=AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=true
-# full set, A/B
-$B/ai-memory-eval retrieval --server-bin $B/ai-memory --concurrency 6 --http-timeout-secs 300 \
- --candidate-server-env $FLAG
-# final build: FTS on 180, local on 90, then the full set with the stream on
-$B/ai-memory-eval retrieval --server-bin $B/ai-memory --concurrency 6 --http-timeout-secs 300 \
- --stratify 30 --candidate-server-env $FLAG
-$B/ai-memory-eval retrieval --server-bin $B/ai-memory --concurrency 6 --http-timeout-secs 600 \
- --embeddings local --stratify 15 --candidate-server-env $FLAG
-$B/ai-memory-eval retrieval --server-bin $B/ai-memory --concurrency 6 --http-timeout-secs 300 \
- --server-env $FLAG
+AB="--server-env AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false
+ --candidate-server-env AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=true"
+# full set, then FTS on 180 and local on 90
+$B/ai-memory-eval retrieval --server-bin $B/ai-memory --concurrency 6 --http-timeout-secs 900 $AB
+$B/ai-memory-eval retrieval --server-bin $B/ai-memory --concurrency 6 --http-timeout-secs 900 \
+ --stratify 30 $AB
+$B/ai-memory-eval retrieval --server-bin $B/ai-memory --concurrency 6 --http-timeout-secs 900 \
+ --embeddings local --stratify 15 $AB
```
diff --git a/docs/benchmarks/retrieval-ab-r2.md b/docs/benchmarks/retrieval-ab-r2.md
index 4f61d2b5..1e37bce4 100644
--- a/docs/benchmarks/retrieval-ab-r2.md
+++ b/docs/benchmarks/retrieval-ab-r2.md
@@ -102,8 +102,8 @@ cargo run --release -p ai-memory-eval -- retrieval --candidate
The full-set A/B for the 2.7 observation stream (stream off → on, zero-LLM
FTS, 470 scored) is published with its provenance in
[`longmemeval-s-decomposition-2026-10-12.md`](longmemeval-s-decomposition-2026-10-12.md#what-the-observation-stream-recovered):
-`hit@5` 0.666 → 0.868, hit@1 0.530 → 0.619, hit@10 0.694 → 0.936, 96 questions
-gained and 1 lost. The local-embeddings A/B ran on a 90-question stratified
+`hit@5` 0.662 → 0.855, hit@1 0.511 → 0.611, hit@10 0.687 → 0.934, 91 questions
+gained and none lost (corrected harness, 2026-10-13). The local-embeddings A/B ran on a 90-question stratified
sample (0.800 → 0.867). The stream is on by default in 2.7, so a baseline run
of the 2.4 configuration on a 2.7 build needs
`--server-env AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false`.
diff --git a/docs/companion-crates.md b/docs/companion-crates.md
index 1ae4cd8f..ee989e07 100644
--- a/docs/companion-crates.md
+++ b/docs/companion-crates.md
@@ -67,7 +67,7 @@ Read-only companions can start ai-memory with `serve --enable-api` to mount
Both modes use the normal machine Bearer or browser-session auth boundary;
writes continue through MCP or authenticated admin routes.
-### Proposed team-wiki sync (#986)
+### Team-wiki sync (#986)
A repository-backed team-wiki sync is accepted as a companion shape, not as a
repo-local storage mode in the core server. A contribution should preserve the
@@ -249,7 +249,7 @@ Re-home by kind:
## `ai-memory-wikisync`: team-wiki export and sync
-Slices 1, 3, 4 and 5 of the accepted [team-wiki sync](#proposed-team-wiki-sync-986)
+Slices 1, 3, 4 and 5 of the accepted [team-wiki sync](#team-wiki-sync-986)
shape, implemented at [`companions/ai-memory-wikisync`](../companions/ai-memory-wikisync)
as a standalone Cargo package with its own `[workspace]` (mirroring the
importer): it is not a member of the root workspace and is not covered by
@@ -572,14 +572,16 @@ and preference for a separate repository above remain unchanged.
from shipped callers, as discussed in PR #1058. This appendix neither requires
a particular SDK nor approves speculative endpoints or wire fields. A reported
capability would not replace authorization.
-- Conditional editing needs a safe core compare-and-write seam covering body
- and editable metadata, coordinated with the normal Wiki and writer paths.
- Re-reading a page and then writing unconditionally is insufficient. Without
- that seam, applying edits must remain unavailable; stale revisions require a
- fresh diff and confirmation. Conditional deletion needs its own evaluation.
+- Conditional editing needs a safe core compare-and-write seam, coordinated
+ with the normal Wiki and writer paths. 2.7 ships it: `memory_write_page` and
+ `memory_delete_page` take `expected_page_id` (and writes `create_only`), and
+ a stale version writes or deletes nothing
+ ([`programmatic-memory.md`](programmatic-memory.md)). An editor still needs
+ to show a fresh diff and ask again when its revision went stale.
- Any retained-version or evidence reads need current access checks and bounded
retention semantics; they must not recover expired or purged content from Git.
- No new history, graph, or procedure interface is approved here.
+ 2.7's read-only page history in the built-in web UI follows those rules (it
+ hides expired versions); no graph or procedure interface is approved here.
- Mutations must retain sanitization, admission, attribution, and disk/SQL
recovery. Direct admission follows the configured failure policy; it is not
the automatic loop's separate pending-write approval flow. Uncertain delivery
diff --git a/docs/comparison.md b/docs/comparison.md
index 6ccf8916..46300fe2 100644
--- a/docs/comparison.md
+++ b/docs/comparison.md
@@ -43,7 +43,8 @@ It also publishes numbers, produced by the in-repo harness with full
provenance and measured end to end through the shipped capture pipeline:
**LongMemEval-S hit@5 about 0.82** with the default local embeddings (0.823 and
0.815 in the two published full-set runs) and 0.666 zero-LLM. The observation stream in 2.7
-(unreleased, on by default) raises zero-LLM to **0.868** on all 470 questions.
+(unreleased, on by default) raises zero-LLM from 0.662 to **0.855** on all 470
+questions, measured on one build with the stream off and on.
With capture skipped and each raw session indexed whole (component mode,
ranking only), zero-LLM FTS scores 0.972; the
[decomposition report](benchmarks/longmemeval-s-decomposition-2026-10-12.md)
@@ -295,7 +296,7 @@ operator turns it on.
- **Retrieval through capture, and no local reranker.** Through the shipped
pipeline, LongMemEval-S hit@5 is about 0.82 with local embeddings and 0.666
- zero-LLM (2.6); the 2.7 observation stream raises zero-LLM to 0.868. Ranking
+ zero-LLM (2.6); the 2.7 observation stream raises zero-LLM to 0.855. Ranking
the same raw sessions whole scores 0.972 zero-LLM. The
[decomposition](benchmarks/longmemeval-s-decomposition-2026-10-12.md) traced
the gap to capture, and within capture not to the 2 KB privacy cap (pages holding exactly the captured text
diff --git a/docs/competitive-parity.md b/docs/competitive-parity.md
index 759519dd..df8f2bd1 100644
--- a/docs/competitive-parity.md
+++ b/docs/competitive-parity.md
@@ -43,7 +43,7 @@ None of the competitors below has more than one or two of these; none has all.
- **Multi-user shared-within-project** ("pages shared, batons owned", invariant
#16), self-hosted, with no paid tier.
- **Honest, reproducible benchmarks**: LongMemEval-S hit@5 about 0.82 local and
- 0.666 zero-LLM through the shipped pipeline, 0.868 zero-LLM with the 2.7
+ 0.666 zero-LLM through the shipped pipeline, 0.855 zero-LLM with the 2.7
observation stream, and a published pipeline-vs-component decomposition
([`benchmarks/`](benchmarks/README.md)).
@@ -119,7 +119,7 @@ implemented without a separate decision.** Ordered by leverage.
([`benchmarks/longmemeval-s-decomposition-2026-10-12.md`](benchmarks/longmemeval-s-decomposition-2026-10-12.md))
split the pipeline number into capture cost, ranking and harness
artifacts, which led to the 2.7 observation stream (zero-LLM FTS hit@5
- 0.666 → 0.868). What is still unrun is the dormant substrate below: the
+ 0.662 → 0.855). What is still unrun is the dormant substrate below: the
belief-strength weight cannot move a zero-LLM corpus (every page's
confidence is 0.0 without consolidation evidence, so the measured delta
was 0.000 FTS), so it needs an LLM-consolidated corpus; typed-edge rank
@@ -259,7 +259,7 @@ implemented without a separate decision.** Ordered by leverage.
page indexed only 80-character turn titles and no assistant text, while
ranking whole sessions scored 0.972. The 2.7 observation stream, on by
default after a measured R2 delta, recovered about two thirds
- of that (0.666 → 0.868 zero-LLM FTS on the full set; 0.800 → 0.867 local on
+ of that (0.662 → 0.855 zero-LLM FTS on the full set; 0.800 → 0.867 local on
a 90-question sample). Still open: no local zero-LLM reranker, a full-set
local run with the stream, belief-strength (`page_evidence`) wired but
**default-off** and unmeasurable without an LLM-consolidated corpus, and
diff --git a/docs/install.md b/docs/install.md
index 1d11b6f5..090aca37 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1,8 +1,8 @@
# Installation cookbook
The [README quick-start](../README.md#quick-start) covers the happy
-paths (Docker + Claude Code, Arch AUR, Fedora RPM, macOS menu bar app). This
-page covers everything else:
+paths (the two-command native install, Docker + Claude Code, Arch AUR, Fedora
+RPM, macOS menu bar app). This page covers everything else:
- [One-step native install](#one-step-native-install-installsh--ai-memory-setup)
(`install.sh` + `ai-memory setup`, Linux and macOS, no root)
@@ -18,7 +18,7 @@ page covers everything else:
- [macOS menu bar app](#macos-menu-bar-app)
(self-contained `.app` + LaunchAgent)
- [Configuring other agent CLIs](#configuring-other-agent-clis)
- (Codex, Command Code, Devin CLI, OpenCode, OMP, Pi, Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, Grok Build CLI, Zero, ZCode, Kimi Code, Kiro CLI, Pool, OpenClaw, VS Code Copilot, Zed)
+ (Codex, Command Code, Devin CLI, OpenCode, OpenCode 2, OMP, Pi, Cursor, Claude Desktop, Gemini CLI, Antigravity CLI, Grok Build CLI, GitHub Copilot CLI, Hermes Agent, Zero, ZCode, Kimi Code, Kiro CLI, Pool, OpenClaw, VS Code Copilot, Zed, and MCP-only recipes for Factory Droid, Warp, Cline, Kilo Code, Goose, Qwen Code and OpenHuman)
- [Installing hooks without docker](#installing-hooks-without-docker)
(curl-based installer)
- [Running ai-memory without docker](#running-ai-memory-without-docker)
@@ -130,6 +130,13 @@ is never printed or passed on a command line, and no harness config holds it:
hooks read the credential files `init` writes, and MCP clients reach the
server through `ai-memory mcp-bridge`.
+The service serves the web UI at `http://127.0.0.1:49374/web`, and `setup`
+prints that address at the end. A fresh install has a bearer token and no user
+accounts, so the browser asks for a username and password: type any username,
+and the contents of `<data_dir>/auth-tokens/default` as the password. To sign
+in with a password of your own instead, create the first root account as in
+[first-time root](#first-time-root-greenfield).
+
`uninstall --apply` removes what `setup` wired, the service included. Every
unit `setup` renders carries an identity line holding the SHA-256 of the rest of
the file, and `uninstall` removes only a unit whose line is there and still
@@ -412,7 +419,9 @@ ai-memory \
init
```
-Edit provider/auth settings if you want LLM consolidation or bearer auth:
+`init` on a fresh data dir already turned bearer auth on (the token is in
+`auth-tokens/default` under the data dir). Edit the provider settings if you
+want LLM consolidation:
```bash
$EDITOR ~/.config/ai-memory/config.toml
@@ -505,7 +514,8 @@ sudo cat /var/lib/ai-memory/auth-tokens/default \
```
For LAN exposure, set a non-loopback bind and allowed hosts in
-`/etc/ai-memory/config.toml`, and set a bearer token in `/etc/ai-memory/env`:
+`/etc/ai-memory/config.toml`. The bearer `init` wrote already protects every
+route; set `AI_MEMORY_AUTH_TOKEN` in `/etc/ai-memory/env` only to replace it:
```toml
bind = "0.0.0.0:49374"
@@ -513,6 +523,7 @@ allowed_hosts = ["homelab", "192.168.0.90", "localhost", "127.0.0.1"]
```
```bash
+# optional: replace the token init wrote
TOKEN=$(ai-memory generate-auth-token)
printf 'AI_MEMORY_AUTH_TOKEN=%s\n' "$TOKEN" | sudo tee -a /etc/ai-memory/env
```
@@ -530,7 +541,7 @@ Verify from the host:
```bash
curl -sI http://127.0.0.1:49374/handoff
-# 401 Unauthorized when AI_MEMORY_AUTH_TOKEN is set.
+# 401 Unauthorized without the bearer token.
```
### LLM provider login with native services
@@ -611,7 +622,8 @@ sudo systemctl restart ai-memory.service # system mode
### Wire agent CLIs after native install
-For a local loopback server with no bearer token:
+For a local loopback server (the CLI finds the token file `init` wrote, so no
+token goes on the command line):
```bash
ai-memory install-mcp --client claude-code --apply
@@ -2228,8 +2240,9 @@ Data dir defaults to `~/.local/share/ai-memory` on Linux,
`~/Library/Application Support/ai-memory` on macOS, and the platform
local-data directory on Windows, typically
`%LOCALAPPDATA%\ai-memory`. Override with `AI_MEMORY_DATA_DIR=/path`.
-To require bearer-token auth, set `AI_MEMORY_AUTH_TOKEN` in the
-server's environment.
+`init` on a fresh data dir already requires the bearer token it wrote to
+`auth-tokens/default`; `AI_MEMORY_AUTH_TOKEN` in the server's environment
+overrides it.
#### Optional serve flags
@@ -2263,9 +2276,12 @@ the repo's `hooks/` automatically. Extracted release archives also
auto-discover the sibling `hooks/` bundle beside the `ai-memory` binary:
```bash
-./target/release/ai-memory install-hooks --agent claude-code --auth-token "$TOKEN"
+./target/release/ai-memory install-hooks --agent claude-code --apply
```
+The hooks read the token from the data dir; pass `--auth-token` only for a
+server whose token lives elsewhere.
+
(No need for `setup-agent` in this case - the scripts already live
at the right host path.)
@@ -2736,6 +2752,8 @@ docker run --rm akitaonrails/ai-memory:latest --help # full subcommand tree
| Subcommand | Pattern | What it does |
|---|---|---|
| `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. |
| `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 |
@@ -2764,7 +2782,7 @@ docker run --rm akitaonrails/ai-memory:latest --help # full subcommand tree
| `setup-agent --agent --to --host-prefix` | `docker run --rm -v` | Extract bundled scripts + print config (one-shot) |
| `install-instructions [--target] [--print] [--no-skills]` | same host environment used for the agent prompt files | Install or update the slim CLAUDE.md / AGENTS.md routing block and, by default, the managed ai-memory Agent Skills |
| `install-skills [--scope] [--agent]` | same host environment used for the agent skill dirs | Install or update only the managed ai-memory Agent Skills |
-| `uninstall --apply` | same host environment used for install | Remove only ai-memory-owned hooks, MCP entries, instruction blocks, managed skill files, and generated plugin files after content/marker validation. Removing hooks or MCP also deletes the `ai-memory run` auto-wire sentinels under `<data_dir>/autowire-state/`, so the next managed launch wires again. Use `--mcp-url` for custom MCP endpoints and `--mcp-name` only to narrow removal. |
+| `uninstall --apply` | same host environment used for install | Remove only ai-memory-owned hooks, MCP entries, instruction blocks, managed skill files, and generated plugin files after content/marker validation, plus the user service `setup` installed when nobody edited it since. Removing hooks or MCP also deletes the `ai-memory run` auto-wire sentinels under `<data_dir>/autowire-state/`, so the next managed launch wires again. Use `--mcp-url` for custom MCP endpoints and `--mcp-name` only to narrow removal. |
| `llm-test --provider …` | `docker run --rm -e …` | Smoke-test an LLM provider |
| `completions <shell>` | `docker run --rm` or native binary | Print a bash/zsh/fish/PowerShell/elvish completion script; see [`shell-completions.md`](shell-completions.md) |
diff --git a/docs/macos.md b/docs/macos.md
index 90918eb9..a131ae4a 100644
--- a/docs/macos.md
+++ b/docs/macos.md
@@ -131,10 +131,10 @@ extracted `./ai-memory` path (or upgrade).
Notes:
-- The MCP endpoint, capture hooks, and `ai-memory status` work without a token
- in this single-user loopback setup. If you explicitly configure
- `AI_MEMORY_AUTH_TOKEN` for the server, pass the same token with `--auth-token`
- or export it for CLI commands.
+- `init` on a fresh data dir writes a root bearer token to
+ `<data_dir>/auth-tokens/default`. The hooks, the CLI and `install-mcp` read
+ it from there, so you never pass `--auth-token` locally. An install from
+ before 2.7 keeps running without a token until `ai-memory auth enable`.
- Keep the extracted `ai-memory` at a stable path; the hook commands (and the
symlink, if you made one) reference it. Re-run `install-hooks` and re-point
the symlink if you move it.
@@ -232,7 +232,10 @@ across rebuilds. The menu extra has no Dock icon.
server on first launch by itself.
2. The status item is green when `GET /admin/status` succeeds, yellow when the
server is up but the LLM/embedding role is in error or the write queue is
- non-empty, red when the server is unreachable.
+ non-empty, red when the server is unreachable. The app sends the token saved
+ in Settings, or, when none is saved, the one `init` wrote to
+ `auth-tokens/default` in its data dir, so an install the app initialized
+ needs no pasting.
3. **Open Web UI**, **Show Status…**, **Open Config**, **Open Data Directory**,
and **Open Logs** call the existing browser UI, the bundled CLI, and Finder.
@@ -316,12 +319,14 @@ tail -f ~/Library/Logs/ai-memory/stderr.log
`bootout` then `bootstrap` again; `kickstart -k` only restarts the process and
does not re-read the definition.
-### If you configure a bearer token
+### Bearer token
-`AI_MEMORY_AUTH_TOKEN` is read from the process environment only. It is not a
-`config.toml` key, and launchd has no `EnvironmentFile`. A single-user loopback
-setup needs no token at all. If you do set one, add it to your rendered plist
-and tighten the file, because `~/Library/LaunchAgents` is not private:
+`init` on a fresh data dir writes the root bearer to
+`<data_dir>/auth-tokens/default` and records `[auth] bearer_token_file` in
+`config.toml`, so the LaunchAgent needs no token in its plist. To replace that
+token with one from the environment, note that launchd has no
+`EnvironmentFile`: add `AI_MEMORY_AUTH_TOKEN` to your rendered plist and
+tighten the file, because `~/Library/LaunchAgents` is not private:
```xml
<key>EnvironmentVariables</key>
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index e9325eaa..0c177a64 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -933,9 +933,12 @@ that drain: the lock is an OS file lock released when its holder exits.
## ZCode (z.ai)
-**Status:** MCP supported. Lifecycle hooks are not installed by this command;
-they are tracked in issue #512, so until then capture is not active and
-ai-memory only sees the sessions where an agent calls its MCP tools.
+**Status:** MCP supported. Lifecycle hooks are installed separately with
+`ai-memory install-hooks --agent zcode --apply` (see the
+[support matrix](support-matrix.md)). On a token-file install (every fresh
+`init`) `install-mcp --client zcode` is refused, because ZCode keeps only a
+literal header; add the entry by hand with the header read from
+`<data_dir>/auth-tokens/default`.
**Config file:** ZCode keeps its user-scope config at
`~/.zcode/cli/config.json`, with servers under the nested `mcp.servers` map
diff --git a/docs/support-matrix.md b/docs/support-matrix.md
index 99a3cf49..e5dd12c8 100644
--- a/docs/support-matrix.md
+++ b/docs/support-matrix.md
@@ -16,7 +16,7 @@
| 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. 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). |
+| 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. |
| 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. |
@@ -35,15 +35,15 @@
| 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; an interactive session launched with `ai-memory run antigravity` 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 antigravity` (aliases `antigravity-cli`, `agy`) adds managed workstream resume via `--conversation`; its conversation store is not decoded, so the ledger takes user prompts from `agy`'s `history.jsonl` (only this conversation's lines typed in this checkout) and assistant and tool steps from hook capture. Tool outputs (`run_command`, `view_file`, `list_dir`, etc.) are resolved directly from `.system_generated/steps/<stepIdx>/output.txt` during `post-tool-use` while mutation tools preserve code from arguments (#966). |
| 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. `SessionStart` and `UserPromptSubmit` do not accept the handoff (Grok discards that stdout). The first `PostToolUse` prints `hookSpecificOutput.additionalContext` with the pending handoff and an opted-in `[briefing]`; the model sees it after that tool result. If no tool runs, recover via MCP `memory_handoff_list` then `memory_handoff_accept` with that `handoff_id`. `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_list` then `memory_handoff_accept` with that `handoff_id`. Zero runs hooks in its sandbox, which by default denies network (loopback too) and writes outside the workspace, so events stay in the hook spool: allow `sandbox.network` and add the ai-memory data dir to `sandbox.additionalWriteRoots` in the global `~/.config/zero/config.json` (network allow covers every Zero shell command; `sessionEnd` then delivers in-process within a fixed 10-second budget, since the sandbox kills detached drainers), or run `ai-memory hook-drain` from a normal shell (see [`mcp-install.md`](mcp-install.md#zero-gitlawbzero)). |
-| ZCode | Supported | `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. 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. |
+| Zero | Supported | `install-mcp --client zero` (native HTTP + bearer in `~/.config/zero/config.json` when the token is passed explicitly; a token-file install gets a stdio `ai-memory mcp-bridge --no-session-id` entry instead) + 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_list` then `memory_handoff_accept` with that `handoff_id`. Zero runs hooks in its sandbox, which by default denies network (loopback too) and writes outside the workspace, so events stay in the hook spool: allow `sandbox.network` and add the ai-memory data dir to `sandbox.additionalWriteRoots` in the global `~/.config/zero/config.json` (network allow covers every Zero shell command; `sessionEnd` then delivers in-process within a fixed 10-second budget, since the sandbox kills detached drainers), or run `ai-memory hook-drain` from a normal shell (see [`mcp-install.md`](mcp-install.md#zero-gitlawbzero)). |
+| ZCode | Supported | `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. It is refused when the bearer lives in a token file (every fresh `init`), because ZCode keeps only a literal header; add the entry by hand there. 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 managed workstream is claimed yet. |
| 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, unless it is an interactive session launched with `ai-memory run kiro`, which finalizes it automatically when it exits if the run can tie the session to itself (see [`docs/managed-workstreams.md`](managed-workstreams.md)). `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 committed project 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_list` then `memory_handoff_accept` with that `handoff_id`. 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`](managed-harness-contributions.md)). Verified against Poolside CLI v1.0.16. |
| GitHub Copilot CLI | Supported | MCP config (`install-mcp --client copilot-cli` → `$COPILOT_HOME/mcp-config.json`, root `mcpServers`, `type: "http"`) + lifecycle hooks: `install-hooks --agent copilot-cli` writes `$COPILOT_HOME/hooks/ai-memory.json` (`COPILOT_HOME` defaults to `~/.copilot`). Configured with PascalCase event names, so Copilot sends the VS Code/Claude-compatible payload (`session_id`, `cwd`, `tool_name`, `tool_input`, `tool_result`) and native commands enforce capture exclusions; 10 events, Claude Code's nine plus `PostToolUseFailure`. Entries are flat with no `matcher`, because Copilot rejects it on `SessionStart`/`Stop`/`SessionEnd` and subagent events. The `SessionStart` hook delivers the prior session's handoff through Copilot's top-level `additionalContext`. Routing: Copilot CLI loads `AGENTS.md`, and `install-skills --agent copilot-cli` (or `install-instructions --skills-agent copilot-cli`) writes the managed Agent Skills to `.github/skills` (project) or `$COPILOT_HOME/skills` (global); `memory_install_self_routing` returns the same `copilot_cli` hints. `--scope project` is intentionally unsupported: Copilot's repository hook files (`.github/hooks/*.json`) are versioned and shared with the team and the cloud agent, so they cannot carry this machine's absolute executable and data-dir paths. `ai-memory run copilot` (alias `copilot-cli`) adds managed workstream resume: a generated `--session-id` for a fresh session, `--resume=<id>` to return, and visible-history import from `$COPILOT_HOME/session-state/<uuid>/events.jsonl` (see [`docs/managed-workstreams.md`](managed-workstreams.md)). The bare `--client copilot` alias of `install-mcp` keeps meaning VS Code Copilot. |
| 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. |
-| Muse Code | MCP-only | `install-mcp --client muse` merges a native streamable-HTTP entry with bearer `headers` into the snake_case `mcp_servers` map of `~/.config/muse/settings.json`, preserving sibling servers. The writer adds the mandatory `"schema_version": 1` when absent (without it every `muse` command fails at startup) and never rewrites an existing value, and it sets `"mode": "optional"` because Muse's default `required` aborts the whole run when the server is unreachable. Skills need no extra step: Muse reads `~/.agents/skills`, which `install-skills` already writes. Lifecycle capture and managed workstreams are not claimed — Muse documents a hook surface, but the output contract of its `SessionStart` event is not specified. |
+| Muse Code | MCP-only | `install-mcp --client muse` merges a native streamable-HTTP entry with bearer `headers` (a token-file install gets a stdio `ai-memory mcp-bridge --no-session-id` entry instead) into the snake_case `mcp_servers` map of `~/.config/muse/settings.json`, preserving sibling servers. The writer adds the mandatory `"schema_version": 1` when absent (without it every `muse` command fails at startup) and never rewrites an existing value, and it sets `"mode": "optional"` because Muse's default `required` aborts the whole run when the server is unreachable. Skills need no extra step: Muse reads `~/.agents/skills`, which `install-skills` already writes. Lifecycle capture and managed workstreams are not claimed — Muse documents a hook surface, but the output contract of its `SessionStart` event is not specified. |
| DeepSeek Harness (DSH) | MCP-only | `install-mcp --client dsh` prints a Cordis patch fragment (a `- insert:` item for `@deepseek-ai/dsh-mcp-client`) to merge into `$DSH_HOME/profiles/<profile>/cordis.patch.yml`; DSH has no fixed MCP config file, so `--apply` is refused. Lifecycle capture is not claimed: DSH's `@deepseek-ai/dsh-hooks-claude-code` bridge can run a Claude Code hook config, but ai-memory's Claude Code hooks would report DSH sessions as `agent=claude-code`, and the bridge delivers only seven Claude Code events (`PreCompact` and `SessionEnd` are not), with a detached `SessionStart`. No managed workstream. |
| Prime Agent | MCP-only | `install-mcp --client prime-agent` merges an HTTP entry (`type: "http"` + `url`) into the `mcpServers` map of `$PRIME_AGENT_CODING_AGENT_DIR/settings.json` (default `~/.prime/agent/settings.json`), preserving other settings and servers; a project's `.prime/agent/settings.json` works through `--config-file`. A token is referenced as `"bearerTokenEnvVar": "AI_MEMORY_AUTH_TOKEN"`, never written: Prime Agent 0.10 counts a user HTTP server as connected and names it in the model's prompt only with that variable set or an OAuth grant. A credential-less entry is still callable through `mcp.call_tool("ai-memory", ...)` but is not listed. The model reaches MCP tools from its Python REPL (`await mcp.call_tool("ai-memory", "memory_query", {...})`), and Prime Agent sends no session id or cwd, so pass `workspace` and `project` on project-scoped calls. Lifecycle capture and managed workstreams are not claimed: Prime Agent 0.10 removed the TypeScript extensions its 0.9 releases had and has no hook surface. Verified against Prime Agent 0.10.0. |
| Hermes Agent | Supported | `install-hooks --agent hermes` (alias `hermes-agent`) prints a ready-to-paste `hooks:` block for `~/.hermes/config.yaml`. Hermes splits each configured `command` with `shlex.split` and runs it with no shell, passing the event JSON on stdin, so the entries invoke the native `ai-memory hook` command (exec form, like Zero and ZCode — no script bundle is staged); ai-memory never writes that YAML file, which is yours to edit and which Hermes itself gates behind its hook-acceptance prompt (`hooks_auto_accept`). Two tool events are wired, `pre_tool_call` → `pre-tool-use` and `post_tool_call` → `post-tool-use`; their `tool_name` / `tool_input` payload drives concrete session attribution, tool-family titles, and capture exclusions. Hermes reports its own process directory as `cwd`, so the native hook locates each event's `.ai-memory.toml` from the tool's absolute `workdir` (`terminal`) or `path` (file tools, `search_files`); a call with no absolute location stays with the process directory. Session lifecycle (recall, prompt capture, session-end, automatic handoff) is owned by the community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) memory provider, so no hook-driven `session-end` is installed and nothing is duplicated; review that plugin's compatibility matrix, install/uninstall scripts, and secret handling before enabling it. No first-party `install-mcp` client and no managed workstream are claimed yet, and because Hermes ignores session-start hook stdout a pending handoff is recovered through MCP (`memory_handoff_list` then `memory_handoff_accept`). |
diff --git a/docs/usage.md b/docs/usage.md
index fb1aba2a..bf63e071 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -139,7 +139,7 @@ at the managed ai-memory Agent Skills that carry detailed tool routing.
| You say | Agent calls | Effect |
|---|---|---|
-| "Have we discussed X?" / "search memory for Y" | `memory_query` | FTS5 + entity/graph/vector RRF over compiled wiki pages, followed by bounded source-authority ranking and raw-observation fallback on a page miss. |
+| "Have we discussed X?" / "search memory for Y" | `memory_query` | FTS5 + entity/graph/vector RRF over compiled wiki pages, plus an observation stream (on by default) that lifts a session's page when only its captured turns match, followed by bounded source-authority ranking and raw-observation fallback on a page miss. |
| Before proposing architecture | `memory_query` | Checks prior decisions and gotchas before suggesting designs. |
| "Catch me up" / "I've been away" | `memory_explore` | Prose digest whose verbosity scales with time since last activity. |
| "Where did we leave off?" | Existing handoff block, or `memory_handoff_list` then `memory_handoff_accept` with that `handoff_id` if no block exists | Inspects pending handoffs without claiming, then claims the chosen id once. |
@@ -543,13 +543,17 @@ code; external schemes inside the brackets (`http://`, `https://`,
`mailto:`, `data:`, `javascript:`, `vbscript:`, `tel:`, `file:`)
stay literal too.
-With no authority configured on loopback, the built-in wiki remains
-anonymous. For human-authenticated administration, serve the compiled admin SPA
+With no bearer token configured on loopback (an install from before 2.7 that
+never ran `ai-memory auth enable`), the built-in wiki remains anonymous. A
+fresh install has a bearer token and no human accounts, so a browser gets a
+Basic sign-in prompt: any username, and the contents of
+`<data_dir>/auth-tokens/default` as the password. That GET-only browser path
+then keeps an HttpOnly `ai_memory_auth` cookie, and it stops immediately after
+a human password or completed bootstrap exists. For human-authenticated
+administration, create the first root account ([first-time
+root](install.md#first-time-root-greenfield)) and serve the compiled admin SPA
with `--web-ui-dir`: it signs in through `/auth/login` and uses an HttpOnly web
-session plus CSRF protection. Before human auth is active, deprecated GET-only
-browser compatibility accepts the root bearer through HTTP Basic and an
-HttpOnly `ai_memory_auth` cookie; it stops immediately after a human password or
-completed bootstrap exists. Browser-stored Bearers remain unsupported.
+session plus CSRF protection. Browser-stored Bearers remain unsupported.
`AI_MEMORY_AUTH_TOKEN` and `aim_` API keys remain machine-only credentials sent
as `Authorization: Bearer <token>` by MCP, hook, handoff, and workstream clients.