Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
chore: name the next release 3.0.0
AkitaOnRails4c5c5c74a899
diff --git a/AGENTS.md b/AGENTS.mdindex 922004c2..d7aa7181 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -690,7 +690,7 @@ Additional boundary rules:- **Branch model.** `main` is the patch line: it takes fixes and docs only(`[Unreleased]` holds only `### Fixed`), and patch tags are cut from it.Additive work targets the standing `release/X.Y` branch for the next minor- (currently `release/2.7`). Keep `main` an ancestor of it by forward-merging+ (currently `release/3.0`). Keep `main` an ancestor of it by forward-merging`main` into it after every fix lands, never the reverse; when a patchrelease ships, rebuild the branch's `[Unreleased]` as only its own entriesso released sections stay identical to `main`'s. A fix lands on `main`diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f25c9a1e..aa01d8f2 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -177,7 +177,7 @@ and [0.x](docs/changelog/0.x.md).deleted only with `--prefer repo`. Every sync write and delete now carriesthe page version it was planned against, so a page changed during the run isreported and left alone while the rest apply, and `sync --apply` refuses a- server older than 2.7. Without the flag deletes are still only reported.+ server older than 3.0. Without the flag deletes are still only reported.(#986)- `ai-memory doctor` now reports three silent capture failures: an unreachableserver (reported instead of aborting the check), a hook spool that is full and@@ -273,7 +273,7 @@ and [0.x](docs/changelog/0.x.md).under `sessions/` or another reserved family, and links to pages that werenot imported become plain text. Every write goes through `memory_write_page`with `create_only` or `expected_page_id`, and the importer refuses servers- older than 2.7. A memory's versions are written oldest first so ai-memory+ older than 3.0. A memory's versions are written oldest first so ai-memorykeeps the supersession chain, and `forgetAfter` becomes `expires_at`. Eachpage carries a stable UUIDv5 ingest key, so an interrupted import resumeswithout duplicates and a rerun writes nothing. Text is redacted beforediff --git a/companions/ai-memory-importer/README.md b/companions/ai-memory-importer/README.mdindex c686584c..f6bfc029 100644--- a/companions/ai-memory-importer/README.md+++ b/companions/ai-memory-importer/README.md@@ -54,7 +54,7 @@ and its source without adding product-specific agent kinds to core.Two routes read what agentmemory exports. Both write through the MCP`memory_write_page` tool with explicit `workspace` and `project`, every writeconditional: `create_only` for a page's first version and `expected_page_id`-for each later one. They refuse a server older than ai-memory 2.7, which would+for each later one. They refuse a server older than ai-memory 3.0, which wouldignore those arguments. Pages land under `--dest-prefix` (default`imported/agentmemory`), never under ai-memory's own `sessions/` or any otherreserved family.diff --git a/companions/ai-memory-importer/src/agentmemory/mock.rs b/companions/ai-memory-importer/src/agentmemory/mock.rsindex 31102857..eb1e31ac 100644--- a/companions/ai-memory-importer/src/agentmemory/mock.rs+++ b/companions/ai-memory-importer/src/agentmemory/mock.rs@@ -40,7 +40,7 @@ pub(crate) struct MockState {pub(crate) requests: Vec<String>,pub(crate) write_calls: usize,pub(crate) failure: Option<Failure>,- /// Advertise `create_only` in `tools/list` (a 2.7+ server).+ /// Advertise `create_only` in `tools/list` (a 3.0+ server).pub(crate) conditional: bool,pub(crate) hook_batches: Vec<Value>,next_id: usize,diff --git a/companions/ai-memory-importer/src/agentmemory/vault.rs b/companions/ai-memory-importer/src/agentmemory/vault.rsindex 1b653c1d..76a2bf8c 100644--- a/companions/ai-memory-importer/src/agentmemory/vault.rs+++ b/companions/ai-memory-importer/src/agentmemory/vault.rs@@ -638,7 +638,7 @@ pub(crate) mod tests {let error = run(args(td.path(), &server.url, &manifest)).await.unwrap_err();- assert!(error.to_string().contains(">= 2.7"), "{error:#}");+ assert!(error.to_string().contains(">= 3.0"), "{error:#}");assert_eq!(server.state().write_calls, 0);}diff --git a/companions/ai-memory-importer/src/mcp.rs b/companions/ai-memory-importer/src/mcp.rsindex 40f969f8..e8cf2aa5 100644--- a/companions/ai-memory-importer/src/mcp.rs+++ b/companions/ai-memory-importer/src/mcp.rs@@ -19,7 +19,7 @@ const ERROR_PREVIEW: usize = 300;/// JSON-RPC `invalid_request`, the code a failed precondition carries.const INVALID_REQUEST: i64 = -32600;/// The server release that added conditional page writes.-pub(crate) const MIN_SERVER: &str = "2.7";+pub(crate) const MIN_SERVER: &str = "3.0";/// What a conditional write requires of the destination page.#[derive(Debug, Clone, Copy, PartialEq, Eq)]diff --git a/companions/ai-memory-wikisync/README.md b/companions/ai-memory-wikisync/README.mdindex dde5e60f..e6d9f9e5 100644--- a/companions/ai-memory-wikisync/README.md+++ b/companions/ai-memory-wikisync/README.md@@ -13,7 +13,7 @@ team's shared memory can live as reviewable markdown in git:- `sync --check` is a read-only CI gate, and `install-hook` runs `sync`after every git merge.-`sync --apply` needs ai-memory 2.7 or later: every write and delete is+`sync --apply` needs ai-memory 3.0 or later: every write and delete isconditional on the page version the plan saw, and an older server wouldignore that condition, so `sync` refuses to write to one.@@ -158,7 +158,7 @@ Safety rules:after it was classified is refused by the server, reported as "changedduring this run", and left with its old state for the next run; the otherpages still sync, and the run exits non-zero. A server without these- preconditions (before ai-memory 2.7) is detected before anything is+ preconditions (before ai-memory 3.0) is detected before anything iswritten and refused.- **The server's version wins after an import.** If the server storessomething other than the file (the sanitizer redacting a secret), the file@@ -230,7 +230,7 @@ ai-memory-wikisync uninstall-hook --dest docs/wiki [--hooks-dir DIR]## Roadmap (#986)1. Read-only export into a project repository (`export`).-2. Conditional mutation seam (compare-and-write) in core (ai-memory 2.7).+2. Conditional mutation seam (compare-and-write) in core (ai-memory 3.0).3. Two-way sync (`sync`): repository edits flow back through the public MCPwrite tool.4. Deletes and conflict reporting (`--propagate-deletes`, conditionaldiff --git a/companions/ai-memory-wikisync/src/client.rs b/companions/ai-memory-wikisync/src/client.rsindex 1f134c81..860485a9 100644--- a/companions/ai-memory-wikisync/src/client.rs+++ b/companions/ai-memory-wikisync/src/client.rs@@ -44,7 +44,7 @@ pub struct PageSummary {#[derive(Debug, Clone, Deserialize)]pub struct ApiPage {/// Latest version id, the token a conditional MCP write or delete- /// passes back. Servers older than 2.7 do not send it.+ /// passes back. Servers older than 3.0 do not send it.#[serde(default)]pub id: Option<String>,pub path: String,diff --git a/companions/ai-memory-wikisync/src/mcp.rs b/companions/ai-memory-wikisync/src/mcp.rsindex 9b19a7e1..93250745 100644--- a/companions/ai-memory-wikisync/src/mcp.rs+++ b/companions/ai-memory-wikisync/src/mcp.rs@@ -25,7 +25,7 @@ const ERROR_PREVIEW: usize = 300;/// JSON-RPC `invalid_request`, the code a failed precondition carries.const INVALID_REQUEST: i64 = -32600;/// The server release that added conditional writes and deletes.-const MIN_SERVER: &str = "2.7";+const MIN_SERVER: &str = "3.0";/// What a conditional write requires of the server's current page.#[derive(Debug, Clone, Copy, PartialEq, Eq)]diff --git a/companions/ai-memory-wikisync/tests/api_server.rs b/companions/ai-memory-wikisync/tests/api_server.rsindex 63b5538b..36fb4a83 100644--- a/companions/ai-memory-wikisync/tests/api_server.rs+++ b/companions/ai-memory-wikisync/tests/api_server.rs@@ -76,7 +76,7 @@ struct Fixture {/// Edit this page right before an MCP call on it is handled, to simulate/// another writer landing between a sync's classification and its write.edit_before_mcp: Option<&'static str>,- /// A server older than 2.7: no `expected_page_id` in the tool schema, no+ /// A server older than 3.0: no `expected_page_id` in the tool schema, no/// `id` on pages, and preconditions silently ignored.old_server: bool,/// Arguments of every MCP tool call, in order.@@ -1125,7 +1125,7 @@ async fn sync_apply_checks_the_tool_schema_before_a_create() {).unwrap();let err = sync(addr, &dest).await.expect_err("old server refused");- assert!(format!("{err:#}").contains("ai-memory >= 2.7"), "{err:#}");+ assert!(format!("{err:#}").contains("ai-memory >= 3.0"), "{err:#}");assert!(fixture.page("decisions/new.md").is_none());assert!(fixture.mcp_calls.lock().unwrap().is_empty());}diff --git a/docs/benchmarks/README.md b/docs/benchmarks/README.mdindex 89587827..620f12af 100644--- a/docs/benchmarks/README.md+++ b/docs/benchmarks/README.md@@ -13,15 +13,15 @@ cargo run --release -p ai-memory-eval -- retrieval --fetch| date | dataset | mode | overall hit@5 | file ||---|---|---|---|---|-| **2026-10-13** | LongMemEval-S (v1) | **zero-llm FTS + observation stream (2.7, unreleased; on by default)** | **0.951** | [longmemeval-s-decomposition-2026-10-12.md](longmemeval-s-decomposition-2026-10-12.md) |-| **2026-10-13** | LongMemEval-S (v1) | **local embeddings + observation stream (2.7, unreleased; on by default)** | **0.936** | [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 (3.0, unreleased; on by default)** | **0.951** | [longmemeval-s-decomposition-2026-10-12.md](longmemeval-s-decomposition-2026-10-12.md) |+| **2026-10-13** | LongMemEval-S (v1) | **local embeddings + observation stream (3.0, unreleased; on by default)** | **0.936** | [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 release) | 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-13 rows are the 2.7 observation stream measured on all 470+The 2026-10-13 rows are the 3.0 observation stream measured on all 470questions, comparing the stream off and on with the same build. Zero-LLM FTS`hit@5` went 0.662 → 0.951 (hit@1 0.511 → 0.857, hit@10 0.687 → 0.972; 139questions gained, 3 lost) and local embeddings 0.796 → 0.936 (hit@1 0.536 →diff --git a/docs/benchmarks/longmemeval-s-decomposition-2026-10-12.md b/docs/benchmarks/longmemeval-s-decomposition-2026-10-12.mdindex 743d84d9..2eaf2e9f 100644--- a/docs/benchmarks/longmemeval-s-decomposition-2026-10-12.md+++ b/docs/benchmarks/longmemeval-s-decomposition-2026-10-12.md@@ -3,7 +3,7 @@This report splits ai-memory's LongMemEval-S `hit@5` into its parts:evidence the index never sees, ranking on evidence it does see, andartifacts of the harness itself. It then records what the observation-stream, shipped in 2.7 (unreleased), recovered.+stream, shipped in 3.0 (unreleased), recovered.It publishes two kinds of number, and they answer different questions:@@ -22,10 +22,10 @@ Every number below comes from the in-repo harness (`evals/`, seeDecomposition runs (2026-10-10 to 2026-10-11):-- server: `release/2.7` at `7dd6b2c2` (the binary reports 2.6.3), before the+- server: `release/3.0` at `7dd6b2c2` (the binary reports 2.6.3), before theobservation stream existed- harness: `420a8556` (the instruments) and `31f515dc` (adds- `--http-timeout-secs`); `release/2.7` carries the same `evals/` tree as+ `--http-timeout-secs`); `release/3.0` carries the same `evals/` tree as`7a2c603d` and `8b797e08`- dataset: `longmemeval_s` (sha256 `08d8dad4be43ee2049a22ff5674eb86725d0ce5ff434cde2627e5e8e7e117894`);where noted, `longmemeval_s_cleaned` (Hugging Face@@ -40,14 +40,14 @@ Decomposition runs (2026-10-10 to 2026-10-11):Pipeline re-runs (2026-10-13, corrected harness): the FTS full-set pipelinewith reachability, both date-prefix ablations and the strat-230 local-pipeline-vs-whole-session A/B, on `release/2.7` at `7e08baa7` with+pipeline-vs-whole-session A/B, on `release/3.0` at `7e08baa7` with`AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false` on every arm (see "Harnesscorrection").Observation-stream runs (2026-10-13, corrected harness):- build: the shipped ranking, `41793120` on top of `25594224`, for the- full-set FTS and local A/Bs; `release/2.7` at `7e08baa7` for the first+ full-set FTS and local A/Bs; `release/3.0` at `7e08baa7` for the firstversion. The stream is on by default in both, so the baseline side sets`AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false` and the candidate side`=true`@@ -195,10 +195,10 @@ for takes its lexical evidence from the stream alone: page FTS over itstitle-only body still reports a rank but adds nothing, so a session that onlyshares topic words in its titles cannot outvote the session holding theanswer. Hits are still pages, and nothing new is written to the wiki. It is on-by default in 2.7; setting it to `false` restores the previous ranking+by default in 3.0; setting it to `false` restores the previous rankingexactly.-Stream off → on, same build (`release/2.7` at `41793120` on top of+Stream off → on, same build (`release/3.0` at `41793120` on top of`25594224`, the shipped ranking), same questions, all 470, corrected harness:| run | hit@5 | hit@1 | hit@10 | recall@5 | p95 ms | flips |@@ -236,7 +236,7 @@ vector, like its FTS row, sees only the title-only body.In its first version the stream's vote was added on top of page FTS, so asession page whose title list shared topic words with the question stillcollected both. That version, stream off → on, corrected harness, on-`release/2.7` at `7e08baa7`:+`release/3.0` at `7e08baa7`:| run | questions | hit@5 | hit@1 | hit@10 | recall@5 | p95 ms | flips ||---|---|---|---|---|---|---|---|@@ -328,7 +328,7 @@ Reachability is unchanged too (0.056 / 0.102 on the session page).## Reproduce-Build once, from a `release/2.7` checkout:+Build once, from a `release/3.0` checkout:```bashcargo build --release -p ai-memory-cli -p ai-memory-evaldiff --git a/docs/benchmarks/retrieval-ab-r2.md b/docs/benchmarks/retrieval-ab-r2.mdindex caa48748..b420e911 100644--- a/docs/benchmarks/retrieval-ab-r2.md+++ b/docs/benchmarks/retrieval-ab-r2.md@@ -97,15 +97,15 @@ cargo run --release -p ai-memory-eval -- retrieval --candidate-embeddings localcargo run --release -p ai-memory-eval -- retrieval --candidate```-### Observation stream (2.7, unreleased)+### Observation stream (3.0, unreleased)-The full-set A/B for the 2.7 observation stream (stream off → on, zero-LLM+The full-set A/B for the 3.0 observation stream (stream off → on, zero-LLMFTS, 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.662 → 0.951, hit@1 0.511 → 0.857, hit@10 0.687 → 0.972, 139questions gained and 3 lost; local embeddings 0.796 → 0.936 on the full set-(corrected harness, 2026-10-13). The stream is on by default in 2.7, so a baseline run-of the 2.4 configuration on a 2.7 build needs+(corrected harness, 2026-10-13). The stream is on by default in 3.0, so a baseline run+of the 2.4 configuration on a 3.0 build needs`--server-env AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false`.### Illustrative sample-20 run (triple + QA-accuracy, NOT a baseline)diff --git a/docs/companion-crates.md b/docs/companion-crates.mdindex ee989e07..42c8da37 100644--- a/docs/companion-crates.md+++ b/docs/companion-crates.md@@ -135,7 +135,7 @@ Initial source support is intentionally narrow:`ExportData` JSON file (`agentmemory-export`, with a required projectmapping file). Both write through MCP `memory_write_page` with explicitscope, every write conditional (`create_only`, then `expected_page_id` per- later version), refuse servers older than 2.7, and land under+ later version), refuse servers older than 3.0, and land under`imported/agentmemory/`, outside every reserved family. Each page versioncarries a stable UUIDv5 ingest key, so a rerun skips what is already there.Observations are dropped unless replayed as `external-import` sessions@@ -230,7 +230,7 @@ Re-home by kind:- Treat non-overwrite checks on `/admin/write-page` as best-effort: the OMCroute re-checks before each write but cannot make that endpoint atomic withthe read. The agentmemory routes use the conditional MCP write seam that- shipped in 2.7 instead, so the server refuses a page that appeared or+ shipped in 3.0 instead, so the server refuses a page that appeared orchanged.- Keep LLM normalization optional; deterministic import should work with no LLM.- Keep provider-specific performance tweaks, such as model parameter changes, out@@ -273,7 +273,7 @@ directions are family-scoped and dry-run by default.with explicit `workspace` and `project`, so sanitization, admission andattribution apply. Every call carries the classified page version(`expected_page_id`, or `create_only` for a new page). It never opens the- wiki directory or SQLite, and refuses to write to a server older than 2.7,+ wiki directory or SQLite, and refuses to write to a server older than 3.0,which would ignore the precondition.- `sync --check` is read-only (no files, no state) and exits 0 in sync,3 on drift, 4 on conflicts or refusals; a clone without state compares@@ -364,7 +364,7 @@ never reaches the hook file.### Roadmap (#986)1. Read-only export into a project repository (shipped).-2. Conditional mutation seam in core (shipped in 2.7: `expected_page_id` /+2. Conditional mutation seam in core (shipped in 3.0: `expected_page_id` /`create_only` on `memory_write_page`, `expected_page_id` on`memory_delete_page`, and the version id on `memory_read_page` and`/api/v1` pages).@@ -573,14 +573,14 @@ and preference for a separate repository above remain unchanged.a particular SDK nor approves speculative endpoints or wire fields. A reportedcapability would not replace authorization.- 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+ with the normal Wiki and writer paths. 3.0 ships it: `memory_write_page` and`memory_delete_page` take `expected_page_id` (and writes `create_only`), anda stale version writes or deletes nothing([`programmatic-memory.md`](programmatic-memory.md)). An editor still needsto show a fresh diff and ask again when its revision went stale.- Any retained-version or evidence reads need current access checks and boundedretention semantics; they must not recover expired or purged content from Git.- 2.7's read-only page history in the built-in web UI follows those rules (it+ 3.0's read-only page history in the built-in web UI follows those rules (ithides expired versions); no graph or procedure interface is approved here.- Mutations must retain sanitization, admission, attribution, and disk/SQLrecovery. Direct admission follows the configured failure policy; it is notdiff --git a/docs/comparison.md b/docs/comparison.mdindex b95f8929..90da937e 100644--- a/docs/comparison.md+++ b/docs/comparison.md@@ -45,14 +45,14 @@ What still sets ai-memory apart:runs on a laptop, a homelab box, or a LAN server, with no paid tier.- **Capture under the harness you already use.** One server; 20+ harnesses(Claude Code, Codex, Cursor, Gemini, OpenCode, Kimi, …) feed and read the- same memory. Replication between servers is not automatic; in 2.7+ same memory. Replication between servers is not automatic; in 3.0(unreleased) the `ai-memory-wikisync` companion adds two-way,conflict-aware sync between a server's wiki and a git repository.It also publishes retrieval numbers, produced by the in-repo harness with fullprovenance and measured end to end through the shipped capture pipeline:LongMemEval-S hit@5 **0.666** zero-LLM and **0.815** with the default local-embeddings in the published 2.6 line. The observation stream in 2.7+embeddings in the published 2.6 line. The observation stream in 3.0(unreleased, on by default) raises zero-LLM to **0.951** and local embeddingsto **0.936** on all 470 questions, measured on one build with the stream offand on. With capture skipped and each raw session indexed whole (component@@ -246,19 +246,19 @@ ships something ai-memory does not, it is named.with DB tokens and OIDC, claim-once handoffs and cross-project messaging,guarded backup/restore/purge, and no runtime dependency under the ElasticLicense (iii-engine's engine is ELv2). You give up editing and forgetting- memories in a browser (the 2.7 web UI adds page history with diffs, a+ memories in a browser (the 3.0 web UI adds page history with diffs, asession timeline, a recall trace and a health panel, but stays read-only by- design), the iii console's OpenTelemetry traces (ai-memory 2.7 has+ design), the iii console's OpenTelemetry traces (ai-memory 3.0 hasper-stream timings in `explain=true` and a root-only Prometheus`/admin/metrics` instead), the coordination tools (leases, actions,routines, signals, sentinels), mesh sync (the nearest equivalent is thegit-based `ai-memory-wikisync` companion), image memory, the two-way Claude- `MEMORY.md` bridge, PaaS deploy templates, an npm package (ai-memory 2.7+ `MEMORY.md` bridge, PaaS deploy templates, an npm package (ai-memory 3.0installs natively on Linux and macOS in two commands, `install.sh` and then`ai-memory setup`, but has no `npx` route, and Windows gets no servicestep), and the opt-in local cross-encoder reranker. The benchmark numbers are notlike-for-like (component vs pipeline, see above). To move your data, the- `ai-memory-importer` companion (2.7) reads agentmemory's Obsidian vault+ `ai-memory-importer` companion (3.0) reads agentmemory's Obsidian vault(`agentmemory-vault`) or its `ExportData` JSON (`agentmemory-export`), and`ai-memory doctor` flags agentmemory MCP entries and rules-file guidelineblocks left behind; see@@ -383,10 +383,10 @@ ships something ai-memory does not, it is named.- **Distribution through plugin directories.** Cognee's Claude Code plugin islisted in Anthropic's official plugin directory, and Mem0, Supermemory andOpenViking ship native plugins per agent. ai-memory- installs with `install.sh` and `ai-memory setup` (2.7) or `install-hooks`,+ installs with `install.sh` and `ai-memory setup` (3.0) or `install-hooks`,not from a plugin marketplace.- **An installer that detects and wires every agent.** `ai-memory setup`- (2.7) wires MCP, hooks and Agent Skills for each detected agent on Linux and+ (3.0) wires MCP, hooks and Agent Skills for each detected agent on Linux andmacOS. Hindsight's coding-agent package covers 16+ agents, and memU's`memu-agent detect` finds unknown agents' transcripts. Windows has noservice step yet.@@ -404,12 +404,12 @@ ships something ai-memory does not, it is named.recall into each request. ai-memory's hooks inject the session brief atsession start (on the first prompt for harnesses without a start hook);later recall is an agent tool call.-- **No "show what was recalled" view in the agent.** The 2.7 web UI has a+- **No "show what was recalled" view in the agent.** The 3.0 web UI has arecall trace with per-stream ranks, but the agent session has no compactcard showing the user which memories were injected.- **Retrieval through capture, and no local reranker.** Through the shippedpipeline, LongMemEval-S hit@5 is 0.815 with local embeddings and 0.666- zero-LLM (2.6); the 2.7 observation stream raises them to 0.936 and 0.951. Ranking+ zero-LLM (2.6); the 3.0 observation stream raises them to 0.936 and 0.951. Rankingthe same raw sessions whole scores 0.972 zero-LLM. The[decomposition](benchmarks/longmemeval-s-decomposition-2026-10-12.md) tracedthe gap to capture, and within capture not to the 2 KB privacy cap (pages holding exactly the captured text@@ -430,7 +430,7 @@ ships something ai-memory does not, it is named.| Tool | Number | Kind | Setup ||---|---|---|---|- | ai-memory 2.7 (unreleased) | LongMemEval-S hit@5 0.951 FTS / 0.936 local (2.6: 0.666 / 0.815) | Retrieval through capture | In-repo harness, all 470 questions; component mode FTS 0.972 |+ | ai-memory 3.0 (unreleased) | LongMemEval-S hit@5 0.951 FTS / 0.936 local (2.6: 0.666 / 0.815) | Retrieval through capture | In-repo harness, all 470 questions; component mode FTS 0.972 || MemPalace | 96.6% R@5 raw, 98.4% held-out (450 q) | Retrieval only | Different harness || agentmemory | 95.2% `recall_any@5`; 2026-10-09 baseline 96.2% any-hit, 84.68% strict recall-all@5 | Retrieval, component | Whole raw sessions, reranker disabled; the authors say the baseline supports no competitive claim || Mem0 | LongMemEval 94.4, LoCoMo 92.5, BEAM 64.1 (1M) / 48.6 (10M) | End-to-end QA, LLM-judged | Managed platform, top-200 budget; harness defaults to gpt-4o reader and judge; headline models not stated |diff --git a/docs/competitive-parity.md b/docs/competitive-parity.mdindex ad557004..525ffd90 100644--- a/docs/competitive-parity.md+++ b/docs/competitive-parity.md@@ -46,7 +46,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.- **Reproducible retrieval benchmarks**: LongMemEval-S hit@5 0.815 local and- 0.666 zero-LLM through the shipped 2.6 pipeline, 0.951 zero-LLM and 0.936 local with the 2.7+ 0.666 zero-LLM through the shipped 2.6 pipeline, 0.951 zero-LLM and 0.936 local with the 3.0observation stream, and a published pipeline-vs-component decomposition([`benchmarks/`](benchmarks/README.md)). Others publish numbers too (Mem0,Zep, Hindsight, EverOS, MemPalace, agentmemory), mostly end-to-end QA with@@ -66,8 +66,8 @@ coding-agent competitors as well as in their original camps.| **MemPalace** (hook capture, team server) | **Partly**: overlapping goals, different substrate | Git-markdown truth, claim-once handoffs, typed cross-project messaging, the auth ladder | Its temporal graph and team server as shipped. Its 96.6% / 98.4% R@5 is retrieval-only like our hit@5, but on a different harness, so neither number ranks the tools || **mcp-memory-service** (fact rows + hook capture) | **Yes** if you liked hook capture + typed edges + published numbers | Files-as-truth (not opaque fact rows), handoffs, cross-project messaging, `as_of` temporal, a reproducible number, and (new on 2.4) its aging set at parity done zero-LLM/reversible/off-by-default (per-tier decay curves, extractive compression, DBSCAN cold-cluster dedup, access boosts, 0.4–0.75-band contradiction flagging) | Cloud/multi-backend replication (Cloudflare/Milvus), graph viz. (Belief-strength + clustering consolidation are no longer a give-up: ai-memory now ships both, clustering as a zero-LLM default-off pass, belief-strength off and eval-gated) || **basic-memory** (file-first markdown) | **Yes** for multi-harness coding continuity; **no** for a personal Obsidian KB with live team co-edit | Ambient capture (no `write_note` ceremony), full lifecycle, handoffs/messaging, git-versioned truth, published numbers | Local zero-cost reranking, real-time collaborative editing, Postgres backend, `build_context` graph-walk, hosted mobile/web UX |-| **agentmemory** (hook capture, KV store) | **Yes** for operability + data ownership | Self-contained binary (no `iii-engine` sidecar, no ELv2 runtime), files-as-truth, SQL indexes committed in-txn, zero-LLM summaries and handoffs, typed claim-once handoffs, a multi-user auth ladder (DB tokens, OIDC), native Windows without a manual sidecar download (ours is still "Experimental"), and a 2.7 importer for its vault and `ExportData`. Both now default to auth on for new installs (theirs since 0.9.30, ours in 2.7, unreleased) | Browser edit/forget (the 2.7 web UI adds page history/diff, a session timeline, a recall trace and a health panel, but stays read-only by design), the iii console's OTEL traces (we ship explain timings + Prometheus `/admin/metrics` in 2.7), a P2P mesh-sync primitive (`ai-memory-wikisync` is our git-based answer), the opt-in local cross-encoder reranker, an npm/`npx` install (ours is a two-command native install on Linux and macOS in 2.7, no npm package), ~31 more tools (54, all visible by default; mostly speculative). Benchmarks are not like-for-like: their 95.2% LongMemEval-S is a component measurement with the reranker disabled (their 2026-10-09 baseline adds 84.68% strict recall-all@5, which they say supports no competitive claim), ours is end-to-end |-| **Claude Code built-in memory** | **Yes** for teams / multi-machine / multi-harness; **not obviously** for a solo dev on one machine in Claude only | Cross-machine, cross-harness, team sharing, tool-lifecycle capture, real search | Zero setup: it's already on with no server to run (our one structural disadvantage for the solo case; 2.7's `install.sh` + `ai-memory setup` cut ours to two commands on Linux and macOS, but there is still a server) |+| **agentmemory** (hook capture, KV store) | **Yes** for operability + data ownership | Self-contained binary (no `iii-engine` sidecar, no ELv2 runtime), files-as-truth, SQL indexes committed in-txn, zero-LLM summaries and handoffs, typed claim-once handoffs, a multi-user auth ladder (DB tokens, OIDC), native Windows without a manual sidecar download (ours is still "Experimental"), and a 3.0 importer for its vault and `ExportData`. Both now default to auth on for new installs (theirs since 0.9.30, ours in 3.0, unreleased) | Browser edit/forget (the 3.0 web UI adds page history/diff, a session timeline, a recall trace and a health panel, but stays read-only by design), the iii console's OTEL traces (we ship explain timings + Prometheus `/admin/metrics` in 3.0), a P2P mesh-sync primitive (`ai-memory-wikisync` is our git-based answer), the opt-in local cross-encoder reranker, an npm/`npx` install (ours is a two-command native install on Linux and macOS in 3.0, no npm package), ~31 more tools (54, all visible by default; mostly speculative). Benchmarks are not like-for-like: their 95.2% LongMemEval-S is a component measurement with the reranker disabled (their 2026-10-09 baseline adds 84.68% strict recall-all@5, which they say supports no competitive claim), ours is end-to-end |+| **Claude Code built-in memory** | **Yes** for teams / multi-machine / multi-harness; **not obviously** for a solo dev on one machine in Claude only | Cross-machine, cross-harness, team sharing, tool-lifecycle capture, real search | Zero setup: it's already on with no server to run (our one structural disadvantage for the solo case; 3.0's `install.sh` + `ai-memory setup` cut ours to two commands on Linux and macOS, but there is still a server) || **Hindsight** (pages-over-facts; coding-agent package) | **Yes** for zero-LLM, files-as-truth, or claim-once handoffs; **no** if you want its end-to-end QA numbers, git-history ingestion, or 16+ agent installer | Zero-LLM default (Hindsight needs an LLM, local or by subscription), markdown files as the source of truth (its markdown is a one-way mirror of Postgres), one binary, claim-once handoffs, cross-project messaging, and (new on 2.4) a belief-strength `confidence` + an opt-in "dream" rewrite that borrow their model but never delete a source and keep the zero-LLM default | Its published end-to-end QA accuracy, git-history ingestion, hooks for 16+ coding agents with one shared bank per repo, a reranker on by default, image/file ingestion, user/team/company scopes inside a bank, and belief-strength that *actually moves ranking by default* (ours ships but is off and eval-gated) || **Mem0** (fact extractor; coding plugins) | **Yes** for coding memory without a cloud key; **no** for app end-user personalization | Zero-LLM, no cloud API key, no telemetry, editable pages, git truth, claim-once handoffs, cross-project messaging | Native plugins for seven coding agents from one runtime, failed-command-to-fix capture with categories, a subdirectory search scope, shared team plus personal memory, cloud user profiles, and its SDK/integration ecosystem || **Supermemory** (hosted memory API; coding plugins) | **Yes** for data ownership and an open-source self-host; **no** for a managed multimodal second brain | Git-markdown truth, an open-source self-hosted server (its server binary is not open source), claim-once handoffs, scoped project identity (its isolation is a tag), zero-LLM default | Recall injected on every prompt, connectors and multimodal ingestion, managed hosting, memoryrepo's stale-write signal |@@ -116,9 +116,9 @@ remaining risk is that borrowed ideas sit **dormant** until the eval harness (R2| Contradiction detection (0.4–0.75 band) | mcp-memory-service | **SHIPPED (parity), advisory-only** | 2.4 (#814) surfaces likely conflicts in `memory_lint` from existing embeddings; zero-LLM, never edits/deletes/persists an edge || Surprisal-first + idle/cancel dream scheduling | Honcho (Dreamer) / Supermemory | **SHIPPED (parity), opt-in** | 2.4 (#816) idle-scheduled, cancels on activity, orders most-novel-first; off by default, observable `DreamReport` per run || Git-as-snapshot | agentmemory | **BETTER** | The wiki files *are* the truth (diffable), not a `state.json` dump |-| Viewer: version diff, session timeline/replay, health | agentmemory | **SHIPPED (2.7), read-only by design** | Page history with server-side diffs (superseded versions included, so a concurrent write's loser stays visible), a paged session timeline, and a root-only health panel with the same fix lines as `ai-memory status`. Edit/forget in the browser is declined (#482); a `clippy.toml` forbids `Wiki` writes in the web crate |-| Recall tracing / metrics | agentmemory (via the iii console's OTEL) | **SHIPPED (2.7), different shape** | No OTEL exporter: `explain=true` reports per-stream timings, `/web/search` shows a recall trace with per-stream ranks and RRF contributions, and root-only `/admin/metrics` exposes Prometheus counters and latency histograms with no content or scope in any label |-| Auth on by default | agentmemory (0.9.30) | **SHIPPED (2.7), new installs only** | `init` on a fresh data dir creates an owner-only root token and the server requires it; existing installs keep working and opt in with `ai-memory auth enable`, which rewires hooks and MCP clients without writing the token into a harness config |+| Viewer: version diff, session timeline/replay, health | agentmemory | **SHIPPED (3.0), read-only by design** | Page history with server-side diffs (superseded versions included, so a concurrent write's loser stays visible), a paged session timeline, and a root-only health panel with the same fix lines as `ai-memory status`. Edit/forget in the browser is declined (#482); a `clippy.toml` forbids `Wiki` writes in the web crate |+| Recall tracing / metrics | agentmemory (via the iii console's OTEL) | **SHIPPED (3.0), different shape** | No OTEL exporter: `explain=true` reports per-stream timings, `/web/search` shows a recall trace with per-stream ranks and RRF contributions, and root-only `/admin/metrics` exposes Prometheus counters and latency histograms with no content or scope in any label |+| Auth on by default | agentmemory (0.9.30) | **SHIPPED (3.0), new installs only** | `init` on a fresh data dir creates an owner-only root token and the server requires it; existing installs keep working and opt in with `ai-memory auth enable`, which rewires hooks and MCP clients without writing the token into a harness config || Pages-over-facts / living pages | Hindsight | **PARITY** (native) | Same architecture, file-first vs their Postgres-first; `settled_first` briefing shipped || Cross-session experience/abstraction pass | Letta/Hindsight/surveys | **REAL, ~parity** | ≥2-session evidence guard is real, but the pass is LLM-required and **off by default** || Typed relation edges | graph camp | **PARTLY SHIPPED** | Link-neighbours are now a first-class retrieval surface: `memory_read_page include_related` walks the `page_links` graph outward (bounded BFS, #775). Retrieval **RANK weighting by edge type is still not done** (edge kind stays explain-only in `memory_query`) |@@ -139,7 +139,7 @@ implemented without a separate decision.** Ordered by leverage.2026-10-12 decomposition([`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+ artifacts, which led to the 3.0 observation stream (zero-LLM FTS hit@50.662 → 0.951, local 0.796 → 0.936). What is still unrun is the dormant substrate below: thebelief-strength weight cannot move a zero-LLM corpus (every page'sconfidence is 0.0 without consolidation evidence, so the measured delta@@ -168,19 +168,19 @@ implemented without a separate decision.** Ordered by leverage.weighting** (edge kind stays explain-only) and a `contradicts` *authority*cap; A5 (#814) surfaces contradictions in `memory_lint` but does not yetfeed rank.-4. **Sharpen the cross-machine story: partly done in 2.7.** `comparison.md`'s+4. **Sharpen the cross-machine story: partly done in 3.0.** `comparison.md`'s"cross-machine *by construction*" meant one shared server + manual git/rsync,with **no automatic replication** (agentmemory ships a P2P primitive; mcp-memory-- service has Cloudflare/Milvus). 2.7 (unreleased) adds the file-first answer:+ service has Cloudflare/Milvus). 3.0 (unreleased) adds the file-first answer:the `ai-memory-wikisync` companion syncs a server's wiki with a gitrepository both ways through the public MCP write path, with conditionalwrites (`expected_page_id`/`create_only`, #986), conflicts that need`--prefer`, opt-in delete propagation, and a `sync --check` CI gate.`comparison.md` now says replication between servers is not automatic andnames the companion.-5. **Close the setup-friction gap vs the built-in: narrowed in 2.7.** This is+5. **Close the setup-friction gap vs the built-in: narrowed in 3.0.** This isour one structural weakness for the solo user. Much was already done (`run`- auto-wire, `doctor`, `backfill`, `install-self-routing`), and 2.7+ auto-wire, `doctor`, `backfill`, `install-self-routing`), and 3.0(unreleased) adds a two-command native install for Linux and macOS:`install.sh` (a release asset with its own `.sha256`, verified beforeunpacking, no root) and then `ai-memory setup`, which runs `init`, installs@@ -265,35 +265,35 @@ implemented without a separate decision.** Ordered by leverage.Capabilities seen across the field in the 2026-10 research, each with ourdecision. The table is keyed by capability, not by tool. Verdicts:-**SHIPPED (2.7)**, **ADOPT** (planned), **MEASURE-FIRST** (build only when a+**SHIPPED (3.0)**, **ADOPT** (planned), **MEASURE-FIRST** (build only when anumber or real demand exists), **DECLINE** (conflicts with goals orinvariants), **ALREADY** (we have it and should say so).| Capability seen in the field | Verdict | Why ||---|---|---|-| Retrieval recall through capture (several tools rank whole raw sessions) | SHIPPED (2.7) | The 2026-10-12 decomposition showed our zero-LLM session page indexed only 80-character turn titles; the observation stream recovered it (FTS hit@5 0.662 → 0.951, local 0.796 → 0.936, all 470). Chasing another tool's headline number is declined: those numbers measure different things |+| Retrieval recall through capture (several tools rank whole raw sessions) | SHIPPED (3.0) | The 2026-10-12 decomposition showed our zero-LLM session page indexed only 80-character turn titles; the observation stream recovered it (FTS hit@5 0.662 → 0.951, local 0.796 → 0.936, all 470). Chasing another tool's headline number is declined: those numbers measure different things || Local zero-LLM cross-encoder reranker | MEASURE-FIRST | Fits the zero-LLM invariant (a local model, not an LLM). Bar before building: hit@5 at least +0.03 on both FTS and local paths over the shipped ranking, p95 at most +100 ms on the reference host and measured on a low-end ARM host; default-on only if the keyless path gains. Measured headroom is small after the stream (component-mode FTS 0.972 vs pipeline 0.951) || Editable browser viewer (edit / forget / bulk forget) | DECLINE | The web UI is read-only by design (`frontend-api.md` §10); wiki mutations go only through `Wiki::write_page`/`apply_batch`; agents already edit and forget via MCP (`memory_write_page` with `expected_page_id`, `memory_delete_page`) and the CLI |-| Viewer read side: version diff, session timeline/replay, recall trace, health | SHIPPED (2.7) | Page history with server-side diffs, a paged session timeline, a recall trace with per-stream ranks, a root-only health panel |-| OTEL traces / metrics | SHIPPED (2.7) as explain timings + content-free Prometheus `/admin/metrics`; OTLP export MEASURE-FIRST (demand-gated) | If built: off by default, no subscriber layer when off, OTLP over http/protobuf on the existing reqwest/rustls, exporter modules filtered out of the subscriber (invariant 15), a span-field allowlist (durations, counts, UUIDs only), ratio sampling, and `cargo deny` must pass |-| Auth on by default | SHIPPED (2.7) for new installs; requiring auth on existing loopback installs DECLINED for 2.x | Flipping existing installs would break every env-less hook and MCP config, a major change under our semver. Existing installs opt in with `ai-memory auth enable` |-| One-command installer / onboarding | SHIPPED (2.7) for Linux and macOS (`install.sh` + `ai-memory setup`); the agent-driven install doc is folded in | No npm package; no Windows service step |+| Viewer read side: version diff, session timeline/replay, recall trace, health | SHIPPED (3.0) | Page history with server-side diffs, a paged session timeline, a recall trace with per-stream ranks, a root-only health panel |+| OTEL traces / metrics | SHIPPED (3.0) as explain timings + content-free Prometheus `/admin/metrics`; OTLP export MEASURE-FIRST (demand-gated) | If built: off by default, no subscriber layer when off, OTLP over http/protobuf on the existing reqwest/rustls, exporter modules filtered out of the subscriber (invariant 15), a span-field allowlist (durations, counts, UUIDs only), ratio sampling, and `cargo deny` must pass |+| Auth on by default | SHIPPED (3.0) for new installs; requiring auth on existing loopback installs DECLINED for 2.x | Flipping existing installs would break every env-less hook and MCP config, a major change under our semver. Existing installs opt in with `ai-memory auth enable` |+| One-command installer / onboarding | SHIPPED (3.0) for Linux and macOS (`install.sh` + `ai-memory setup`); the agent-driven install doc is folded in | No npm package; no Windows service step || Many-language README | DECLINE | Translations go stale on every release, and stale docs are defects under our quality bar || Large speculative tool surfaces (leases, task graphs, routines, sentinels, sketches, crystals, facets; 50+ tools visible by default) | DECLINE | No evidence of real use; each tool adds prompt-surface cost; we keep 23 tools and have run leases where needed || Signals between agents | ALREADY | Typed cross-project messaging with exactly-once pop |-| Mesh / P2P sync | ALREADY (2.7) via `ai-memory-wikisync` | Two-way, conflict-aware git sync over the file truth using `expected_page_id` compare-and-swap |+| Mesh / P2P sync | ALREADY (3.0) via `ai-memory-wikisync` | Two-way, conflict-aware git sync over the file truth using `expected_page_id` compare-and-swap || Durable capture inbox / offline spool | ALREADY | Hook spool, `ai-memory-relay`, `ai-memory recover`, 202/429 backpressure || 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 (2.7) 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 seven more clients; 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 || Importing old transcripts | ALREADY | `backfill` replays native transcripts through `/hook`, sanitized, on by default || Commit ↔ session linking | MEASURE-FIRST (demand) | Managed runs already record git checkpoints || Project profile resource | ALREADY | `memory_briefing` plus the cross-project profile |-| Migration importers from other tools | SHIPPED (2.7) for one tool's vault/export plus a `doctor` check for its leftovers; others on demand | Importers live in the `ai-memory-importer` companion, never in core |+| Migration importers from other tools | SHIPPED (3.0) for one tool's vault/export plus a `doctor` check for its leftovers; others on demand | Importers live in the `ai-memory-importer` companion, never in core || Benchmark rigor | ADOPT | Publish pipeline and component numbers separately, keep run receipts, add strict recall-all@5 beside hit@5, report models and versions per result file; claim no cross-tool ranking without a shared harness |### Step up, borrow, ignore@@ -388,7 +388,7 @@ next to Caura's trust tiers.or calls an LLM. The R2 harness that gates the quality work now exists andmeasures the accuracy+latency+context-tokens triple plus end-to-endQA-accuracy (the QA column is still illustrative sample-20 only).-- **2.7 (unreleased) closes several viewer, operability and migration gaps** the same way:+- **3.0 (unreleased) closes several viewer, operability and migration gaps** the same way:read-only page history/diff, a session timeline, a recall trace and aroot-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`@@ -399,7 +399,7 @@ next to Caura's trust tiers.- **The real weakness was retrieval through capture**, and it was*self-inflicted, not copied*: the decomposition showed the zero-LLM sessionpage indexed only 80-character turn titles and no assistant text, while- ranking whole sessions scored 0.972. The 2.7 observation stream, on by+ ranking whole sessions scored 0.972. The 3.0 observation stream, on bydefault after a measured R2 delta, recovered nearly all ofthat (0.662 → 0.951 zero-LLM FTS and 0.796 → 0.936 local on the full set).Still open: no local zero-LLM reranker, local embeddings scoring slightlydiff --git a/docs/cookbook.md b/docs/cookbook.mdindex ab8feda5..e74f0f99 100644--- a/docs/cookbook.md+++ b/docs/cookbook.md@@ -204,7 +204,7 @@ Everything is opt-in and fail-safe: the family allowlist must be explicitwith a diff summary and refused without `--force`, no frontmatter is forged,and the tool never runs git itself. `sync` sends reviewed repository editsback through MCP (each write conditional on the version it planned against;-needs ai-memory 2.7+), and deletes travel only with `--propagate-deletes`.+needs ai-memory 3.0+), and deletes travel only with `--propagate-deletes`.### Keep it in step after merges and in CIdiff --git a/docs/design-client-sdk.md b/docs/design-client-sdk.mdindex 0467379c..113f3ff5 100644--- a/docs/design-client-sdk.md+++ b/docs/design-client-sdk.md@@ -415,13 +415,13 @@ header or a request body.Pi bridge already sends `2025-03-26` and accepts that answer. The SDK usesonly `initialize`, `tools/list` and `tools/call`, which behave the same acrossthose versions.-- The minimum server is 2.7.0, the release that adds conditional writes+- The minimum server is 3.0.0, the release that adds conditional writesand deletes (`expected_page_id`, `create_only`) and the version id on page- reads (`CHANGELOG.md`, `[Unreleased]` on `release/2.7`). `GET /identity` and+ reads (`CHANGELOG.md`, `[Unreleased]` on `release/3.0`). `GET /identity` andincremental `recent` shipped in 2.6.0. A floor below the precondition seamwould let an older server ignore `expectedPageId` as an unknown argument andturn a guarded write into an unconditional one, which is why wikisync- refuses servers older than 2.7 (`ensure_conditional_writes` in+ refuses servers older than 3.0 (`ensure_conditional_writes` in`companions/ai-memory-wikisync/src/mcp.rs`).- `capabilities()` runs `initialize` (server name, version, protocol version),`tools/list` (tool names and input-schema property names) and@@ -741,7 +741,7 @@ rule extension (§6.3); a pointer in [programmatic-memory.md](programmatic-memorand [companion-crates.md](companion-crates.md).Maintainer decisions before phase 1 starts: approve the start (this document),-and confirm the 2.7.0 floor.+and confirm the 3.0.0 floor.### Phase 2: reads and messaging (about 4 to 5 days)diff --git a/docs/design-cross-project-profile.md b/docs/design-cross-project-profile.mdindex 7e22456e..0d1a14f1 100644--- a/docs/design-cross-project-profile.md+++ b/docs/design-cross-project-profile.md@@ -333,7 +333,7 @@ As shipped, grouping compares a candidate only with groups that share one ofits tokens (an inverted index), once per distinct token set in each group,which keeps a pass near-linear without any stored state. Fully incrementalgrouping, keyed by a stored group per candidate, needs a schema change and is-left to 2.7.+left to 3.0.Lower priority, considered and not scheduled: a byte ruler with retry insteadof truncating long statements (truncation only affects the rare entry over 200diff --git a/docs/design-marketplace-plugins.md b/docs/design-marketplace-plugins.mdindex feb26ac0..9a273766 100644--- a/docs/design-marketplace-plugins.md+++ b/docs/design-marketplace-plugins.md@@ -1,6 +1,6 @@# Design proposal: ai-memory as marketplace plugins (#1166)-**Status: proposal for 2.7, research done 2026-10-13. Not implemented.**+**Status: proposal for 3.0, research done 2026-10-13. Not implemented.**Builds on RFC #1166, the feedback comments on it, and the[`docs/desktop/`](desktop/) notes (especially[`verification-2026-10.md`](desktop/verification-2026-10.md) and@@ -23,9 +23,9 @@ The marketplace lives in this repository. Catalog files sit at the repositoryroot and pin each plugin to the release tag, so `/plugin marketplace addakitaonrails/ai-memory` only ever installs released plugin content.-Recommended 2.7 scope: the Claude Code plugin (CLI and the desktop Code tab),+Recommended 3.0 scope: the Claude Code plugin (CLI and the desktop Code tab),its marketplace, CI validation, a sandboxed end-to-end test, and the-`setup`/`doctor`/`upgrade` integration. Codex follows in 2.7 if the trust+`setup`/`doctor`/`upgrade` integration. Codex follows in 3.0 if the trustquestion below resolves cleanly. Cursor, Cowork capture, Antigravity andGemini come later.@@ -394,7 +394,7 @@ it) before Cursor ships.## Manifests-These are the files the renderer would produce for 2.7.0. The Claude ones+These are the files the renderer would produce for 3.0.0. The Claude onespassed `claude plugin validate --strict` in the prototype.### Phase 1: Claude Code@@ -414,7 +414,7 @@ passed `claude plugin validate --strict` in the prototype."source": "git-subdir","url": "https://github.com/akitaonrails/ai-memory.git","path": "plugins/claude-code",- "ref": "v2.7.0"+ "ref": "v3.0.0"}}]@@ -427,7 +427,7 @@ passed `claude plugin validate --strict` in the prototype.{"name": "ai-memory","displayName": "ai-memory",- "version": "2.7.0",+ "version": "3.0.0","description": "Long-term memory across sessions and harnesses. Hands each lifecycle event to the installed ai-memory binary, which applies your capture exclusions and sends a sanitized record only to your ai-memory server (default http://127.0.0.1:49374). Adds the ai-memory MCP tools. No telemetry. Requires the ai-memory binary.","author": { "name": "AkitaOnRails", "url": "https://github.com/akitaonrails" },"homepage": "https://github.com/akitaonrails/ai-memory",@@ -483,7 +483,7 @@ plugin's own `timeout` cannot raise it ("Timeouts set on plugin-providedhooks don't raise the budget"); the native `session-end` already fits it,because it hands the drain to a detached process. `async: true` on the toolevents is worth measuring later, but it changes how Claude reports output, so-2.7 keeps parity with the settings hooks.+3.0 keeps parity with the settings hooks.`plugins/claude-code/.mcp.json`:@@ -534,7 +534,7 @@ Portable layout, which Codex 0.162.1 accepted locally (finding 10)."source": "git-subdir","url": "https://github.com/akitaonrails/ai-memory.git","path": "plugins/codex",- "ref": "v2.7.0"+ "ref": "v3.0.0"},"policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },"category": "Productivity"@@ -549,7 +549,7 @@ Portable layout, which Codex 0.162.1 accepted locally (finding 10).{"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json","name": "ai-memory",- "version": "2.7.0",+ "version": "3.0.0","description": "Long-term memory across sessions and harnesses, backed by the installed ai-memory binary and your ai-memory server. No telemetry."}```@@ -591,7 +591,7 @@ trusted after a plugin upgrade (open question 2). The catalog`preToolUse`, `postToolUse`, `postToolUseFailure`, `preCompact`, `stop`):```json-{ "name": "ai-memory", "version": "2.7.0",+{ "name": "ai-memory", "version": "3.0.0","description": "Long-term memory across sessions and harnesses, backed by the installed ai-memory binary. No telemetry.","author": { "name": "AkitaOnRails" }, "license": "MIT" }```@@ -721,7 +721,7 @@ Mapped to the boundary inventory, all at integration level:| Docker wrapper routes `hook` to the native client | Wrapper fix | `scripts/check-native-packaging.sh` || Sandboxed Claude install fires hooks into a scratch server | Real wiring, no API key | `plugins.yml` |-## Phased plan for 2.7+## Phased plan for 3.0Estimates are engineer-days for one person familiar with the codebase.@@ -731,11 +731,11 @@ Estimates are engineer-days for one person familiar with the codebase.| **1. Claude Code plugin** | Renderer and hidden `render-plugins`; launcher; `plugins/claude-code`; root catalog; `hook` origin de-duplication; empty `--server-url` handling; Docker wrapper `hook` routing; `setup`/`install-*`/`doctor`/`upgrade`/`uninstall` integration; drift, launcher, parity and de-duplication tests; `docs/install.md` and `docs/mcp-install.md` sections, `plugins/README.md`, CHANGELOG `Added`, security-boundaries row | 4-5 || **2. CI and release automation** | `plugins.yml` (validate, launcher, sandboxed e2e, Codex smoke); `bin/release` stamping; `validate-version` extension; release zip asset | 1.5-2 || **3. Codex plugin** | `plugins/codex`, `.agents/plugins/marketplace.json`, `commandWindows`, trust guidance in docs, `doctor` plugin-hook trust check | 2 |-| **4. Cursor plugin** (2.7 stretch, else 2.8) | Depends on the phase 0 answers; #721 detection of the Cursor plugin; branch strategy for the Cursor import | 2-3 |+| **4. Cursor plugin** (3.0 stretch, else 3.1) | Depends on the phase 0 answers; #721 detection of the Cursor plugin; branch strategy for the Cursor import | 2-3 || **Later** | Cowork capture if phase 0 shows hooks run in the VM; Antigravity; Gemini; Copilot CLI and Droid catalogs; a directory submission | — |Phases 1 to 3 come to roughly 9 to 10.5 days. This is additive work, so it targets-`release/2.7`, not `main`.+`release/3.0`, not `main`.## Open questions for the maintainer@@ -745,7 +745,7 @@ Phases 1 to 3 come to roughly 9 to 10.5 days. This is additive work, so it targepossibly review of the whole repository? An allowlist-capture variant(events only from repositories with an `.ai-memory.toml` marker) wouldarguably satisfy the "project-relevance gate" rule. That would be a- second plugin with a different default, so it is not proposed for 2.7.+ second plugin with a different default, so it is not proposed for 3.0.2. **Codex trust across upgrades.** If Codex hashes hook commands afterexpanding `${PLUGIN_ROOT}`, every plugin update needs a fresh `/hooks`approval, and an untrusted hook is skipped silently. Is that acceptable@@ -769,7 +769,7 @@ Phases 1 to 3 come to roughly 9 to 10.5 days. This is additive work, so it targe6. **Token option.** Add a `sensitive` `auth_token` option, kept in the OScredential store, for remote-server users who never run the CLI's authcommands? It would need the hook to accept a token from the environment,- a new input on the trust boundary. Proposed: no for 2.7.+ a new input on the trust boundary. Proposed: no for 3.0.7. **Marketplace and plugin names.** `ai-memory@ai-memory` reads a littleodd, but both names are free of the reserved prefixes, and changing aplugin name later needs a `renames` entry. Keep it?diff --git a/docs/design-verbatim-residue.md b/docs/design-verbatim-residue.mdindex 8c2c463d..8c6d665f 100644--- a/docs/design-verbatim-residue.md+++ b/docs/design-verbatim-residue.md@@ -480,7 +480,7 @@ Fifteen facts are planted once each:Where a fact sits is a choice, so this session's `projection_loss` describesthe fixture, not real sessions (§1.2 is the evidence for those); what itsupports is the off/on comparison. Zero-LLM at the default budget of-`build_batch_request` on `release/2.7` today: 225 of 300 observations+`build_batch_request` on `release/3.0` today: 225 of 300 observationsselected, one body truncated, 8 of 15 facts lost, exactly the eight plantedat risk, and `recall_prompt` 0.886. A test pins that split (the seven kept,the pasted prompt's two lost, at least six of the eight at risk lost), so a@@ -712,7 +712,7 @@ runs, not after.left); at 0.8 the first room appears near 8,000 tokens (209 characters).Not part of this series.-## 8. Pull request plan (base `release/2.7`)+## 8. Pull request plan (base `release/3.0`)| PR | Content | Size ||---|---|---|@@ -781,7 +781,7 @@ warning, so every new `pub` item carries a doc comment), `cargo tf`,`cargo deny check`; gitleaks runs on the PR range with the fail-closedconfig. If the maintainer would rather implement the mechanism from thisdocument, that is a fine outcome too; the fork stays rebased on-`release/2.7`, so it never competes with that work.+`release/3.0`, so it never competes with that work.## 9. Decisionsdiff --git a/docs/install.md b/docs/install.mdindex 53523a89..00519b74 100644--- a/docs/install.md+++ b/docs/install.md@@ -84,7 +84,7 @@ sh install.sh| Variable | Default | Effect ||---|---|---|-| `AI_MEMORY_VERSION` | latest | Install this release, e.g. `2.7.0` |+| `AI_MEMORY_VERSION` | latest | Install this release, e.g. `3.0.0` || `AI_MEMORY_BIN_DIR` | `~/.local/bin` | Where the `ai-memory` link goes || `AI_MEMORY_LIB_DIR` | `~/.local/lib/ai-memory` | Where the release is unpacked || `AI_MEMORY_RELEASE_BASE_URL` | GitHub Releases | A mirror serving `latest/download/<asset>` and `download/v<version>/<asset>`; the same variable `ai-memory upgrade` reads. The checksum comes from the same origin as the archive, so use only a mirror you control. |diff --git a/docs/macos.md b/docs/macos.mdindex a131ae4a..5ba46f81 100644--- a/docs/macos.md+++ b/docs/macos.md@@ -134,7 +134,7 @@ Notes:- `init` on a fresh data dir writes a root bearer token to`<data_dir>/auth-tokens/default`. The hooks, the CLI and `install-mcp` readit 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`.+ before 3.0 keeps running without a token until `ai-memory auth enable`.- Keep the extracted `ai-memory` at a stable path; the hook commands (and thesymlink, if you made one) reference it. Re-run `install-hooks` and re-pointthe symlink if you move it.diff --git a/docs/research-2026-landscape.md b/docs/research-2026-landscape.mdindex 2f02f0d8..43670d1e 100644--- a/docs/research-2026-landscape.md+++ b/docs/research-2026-landscape.md@@ -573,7 +573,7 @@ with another or with ours, and no ranking is claimed.| Tool | Number | Kind | Setup caveats ||---|---|---|---|-| ai-memory 2.7 (unreleased) | LongMemEval-S hit@5 0.951 zero-LLM FTS, 0.936 local embeddings (all 470) | Retrieval through the shipped capture pipeline | 2.6 published 0.666 / 0.815; component mode (raw sessions indexed whole) FTS 0.972 |+| ai-memory 3.0 (unreleased) | LongMemEval-S hit@5 0.951 zero-LLM FTS, 0.936 local embeddings (all 470) | Retrieval through the shipped capture pipeline | 2.6 published 0.666 / 0.815; component mode (raw sessions indexed whole) FTS 0.972 || MemPalace | 96.6% R@5 raw, 98.4% on 450 held-out questions | Retrieval only | Closest in kind to our hit@5; different harness || agentmemory | 95.2% `recall_any@5`; 2026-10-09 baseline 452/470 (96.2%) any-hit, 84.68% strict recall-all@5 | Retrieval, component (whole raw sessions) | Reranker disabled; the authors say the baseline supports no competitive claim || mcp-memory-service | 80.4% R@5 turn-level, 86.0% session-level | Retrieval | Not re-read on 2026-10-13 |diff --git a/docs/usage.md b/docs/usage.mdindex d00eb33c..ba970de2 100644--- a/docs/usage.md+++ b/docs/usage.md@@ -567,7 +567,7 @@ code; external schemes inside the brackets (`http://`, `https://`,`mailto:`, `data:`, `javascript:`, `vbscript:`, `tel:`, `file:`)stay literal too.-With no bearer token configured on loopback (an install from before 2.7 that+With no bearer token configured on loopback (an install from before 3.0 thatnever ran `ai-memory auth enable`), the built-in wiki remains anonymous. Afresh install has a bearer token and no human accounts, so a browser gets aBasic sign-in prompt: any username, and the contents ofdiff --git a/evals/README.md b/evals/README.mdindex 792bf331..92d1dbf9 100644--- a/evals/README.md+++ b/evals/README.md@@ -378,7 +378,7 @@ These flags split a hit@k number into evidence the index never saw andranking on evidence it did. All are opt-in; the defaults reproduce thepublished baselines. The results are in[`docs/benchmarks/longmemeval-s-decomposition-2026-10-12.md`](../docs/benchmarks/longmemeval-s-decomposition-2026-10-12.md).-On a 2.7 server the observation stream is on by default, so reproducing a+On a 3.0 server the observation stream is on by default, so reproducing a2.6-era baseline also needs`--server-env AI_MEMORY_RETRIEVAL__OBSERVATION_STREAM=false`.@@ -426,7 +426,7 @@ Honest-numbers notes:holding exactly the captured text score 0.968 FTS `hit@5` against0.972 for whole raw sessions. The larger cost was the zero-LLM sessionpage, which indexed only 80-character turn titles; the observation- stream (on by default in 2.7) puts the observation bodies back into+ stream (on by default in 3.0) puts the observation bodies back intoranking;- each session's original date is prepended to its turn text, since areplayed history must carry its own timestamps (the officialdiff --git a/install.sh b/install.shindex be30fa95..edac63e1 100755--- a/install.sh+++ b/install.sh@@ -13,7 +13,7 @@# and wire your agents.## Environment (all optional):-# AI_MEMORY_VERSION release to install, e.g. 2.7.0 (default: latest)+# AI_MEMORY_VERSION release to install, e.g. 3.0.0 (default: latest)# AI_MEMORY_BIN_DIR where the `ai-memory` link goes (default: ~/.local/bin)# AI_MEMORY_LIB_DIR where the release is unpacked# (default: ~/.local/lib/ai-memory)@@ -142,7 +142,7 @@ main() {esaccase "$version" inlatest) url_dir="$release_base/latest/download" ;;- *[!0-9A-Za-z.+-]*) die "AI_MEMORY_VERSION must look like 2.7.0" ;;+ *[!0-9A-Za-z.+-]*) die "AI_MEMORY_VERSION must look like 3.0.0" ;;v*) url_dir="$release_base/download/$version" ;;*) url_dir="$release_base/download/v$version" ;;esac