Skip to content

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

Rust

docs: remove stale roadmap and reconcile design records

AkitaOnRailseecef4516e28
diff --git a/README.md b/README.md
index d56a9232..2218cd2f 100644
--- a/README.md
+++ b/README.md
@@ -741,6 +741,13 @@ diagram, crate breakdown, schema notes, and invariants.
| [`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. |
+Dated `design-*`, `research-*`, `issues-*`, `desktop/`, and `benchmarks/`
+files are evidence and design records, not current operating instructions.
+Their status or snapshot banner says whether work shipped, remains proposed,
+or has been superseded. Use the user guides and `ARCHITECTURE.md` for current
+behavior; the older records remain only when current design rationale links to
+them.
+
### Community articles
Written by users; not maintained here, so check them against the version you run.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index dede73d4..d1f8927b 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -280,7 +280,9 @@ Four or more unpinned excerpts of one family share a heading. Pages that do not
fit are listed by path for `memory_read_page`, and the count of them is
reserved before any page is deepened. The security notice, the
untrusted-history fence (with fence markers inside page text escaped) and the
-closing footer are never traded for content.
+closing footer are never traded for content. The accepted algorithm and its
+budget invariants are recorded in
+[`design-tiered-session-brief.md`](design-tiered-session-brief.md).
**Cross-project profile:** after the project brief, SessionStart appends a
fenced, byte-budgeted, byte-stable digest of the user's usual choices from other
@@ -333,6 +335,8 @@ the complete startup response has been assembled. With server-wide
`[handoff].claim_on_session_start = false`, SessionStart instead emits a
metadata-only notice naming the exact handoff id and leaves the row open for
an explicit `memory_handoff_accept`; the managed event range is still claimed.
+The non-destructive offer-mode rationale is recorded in
+[`design-handoff-offer-not-claim.md`](design-handoff-offer-not-claim.md).
With server-wide `[handoff].create_on_session_end = false`, session end writes
the summary page and enqueues consolidation but skips creating an automatic
baton, and an OpenCode or Antigravity turn checkpoint refreshes the page
@@ -1187,6 +1191,7 @@ llm = true # use the configured provider when there is on
verbatim_residue = false # opt in to bounded literal diagnostics from
# omitted/truncated observations; this widens
# the captured text sent to the LLM provider
+ # design: docs/design-verbatim-residue.md
max_input_tokens = 100000 # approximate whole-input target; min 8350 at the default margin (scales with it)
# a flat chars-per-token heuristic, so it
# UNDER-budgets denser corpora: pt-BR prose
@@ -1375,6 +1380,10 @@ drop_events = [] # whole hook event kinds to drop (e.g. ["pre-t
# AI_MEMORY_INGEST__DROP_EVENTS=pre-tool-use
```
+The privacy and fidelity tradeoff behind `[consolidation].verbatim_residue`,
+including its measured opt-in result, is recorded in
+[`design-verbatim-residue.md`](design-verbatim-residue.md).
+
The zero-LLM `query_intent` router also recognizes explicit Brazilian Portuguese
history phrases: "o que fizemos na última sessão", "onde paramos ontem", and
"lembre a decisão anterior", plus "sessão anterior".
diff --git a/docs/ROADMAP-2.0.md b/docs/ROADMAP-2.0.md
deleted file mode 100644
index 104a67b3..00000000
--- a/docs/ROADMAP-2.0.md
+++ /dev/null
@@ -1,247 +0,0 @@
-# ai-memory 2.0 - Plan
-
-> Source: the September 2026 landscape research
-> (`research-2026-landscape.md`) and its ranked recommendations, promoted
-> to a release plan on 2026-09-01. Method: **one item at a time**, each
-> designed → tested → implemented → full gate → committed before the next
-> begins. 2.0 is cut only when every item and its documentation is done.
-> Nothing here is released early.
-
-## Ground rules (apply to every item)
-
-- **Baseline before change.** Item 1 establishes retrieval-quality
- numbers; every later item re-runs them. A 2.0 feature that costs
- retrieval quality is a regression, not a feature.
-- **Migrations are the product.** Existing users upgrade a living store:
- wiki pages, SQLite schema, embeddings, and config all have state.
- Every item states its migration and rollback story *in its design*,
- before code. DB changes ride refinery as always; **wiki-format changes
- get their own versioned mechanism** (see item 2) because refinery
- cannot version markdown on disk.
-- **Clean-code bar.** Each item ends with a pass for duplication, dead
- code, and unnecessary surface: refactors that make the item's tests
- easier belong to the item, not to "later". No speculative
- abstractions; delete what an item obsoletes in the same commit.
-- **Tests with controls.** Every guarantee gets a test that fails
- against a deliberately broken implementation (logic broken, never a
- destination redirected). Multi-session invariant 16 applies to any
- item touching scope, pages, or retrieval.
-- **Docs in the same commit** as the behaviour they describe. CHANGELOG
- under `[Unreleased]` per item, with migration notes accumulated into
- `docs/MIGRATION-2.0.md` as they arise, not reconstructed at the end.
-
-## Item 1 - Retrieval evaluation harness (LongMemEval-V2)
-
-*Why first:* it is the regression guard for items 2-6, and the field now
-audits published numbers (mempalace). We publish none until this exists.
-
-- In-repo harness, on-demand like `writer_throughput` (`#[ignore]`d or a
- `cargo run -p ai-memory-eval` target; the `evals/` crate already
- exists as a home). Fetches/loads the LongMemEval-V2 dataset, ingests
- through the *real* store (hooks-shaped ingestion, not direct SQL),
- queries through the real retrieval stack, reports R@k / P@k per task
- category, zero-LLM and LLM-assisted modes separately.
-- Deterministic where possible; provider-dependent parts clearly marked.
-- **Dataset decision (verified 2026-09-01):** V2 is Apache-2.0 on
- HuggingFace (`xiaowu0162/longmemeval-v2`) with an official harness,
- but its trajectories are WebArena/ServiceNow-style *web-agent*
- histories, not coding sessions. The numbers competitors publish
- (agentmemory 95.2% R@5, mcp-memory-service 0.804/0.860) are against
- **v1** chat histories. (Corrected 2026-10-12: this line used to say
- agentmemory 0.967, which is the grep baseline on its in-house
- coding-agent-life-v1 corpus, not a LongMemEval number.) Therefore: target **v1 (S variant) for
- cross-project comparability**, and adopt **V2's five-ability taxonomy**
- (static state recall, dynamic state tracking, workflow knowledge,
- environment gotchas, premise awareness) as the rubric for a
- coding-agent-native companion eval built from replayed real sessions
- (the agentmemory "coding-agent-life" precedent, with our own corpus).
-- Deliverables: harness, baseline numbers committed to
- `docs/benchmarks/` with date + commit + hardware, docs on how to run.
-- Migration: none.
-
-## Item 2 - OKF v0.1 conformance (the 2.0 headline)
-
-*Why:* our wiki is nearly an OKF bundle; conformance makes ai-memory the
-server-grade implementation of the standard Google published, and the
-knowledge portable to any OKF-aware consumer.
-
-- **Design doc first** (`docs/okf.md`): field-by-field mapping of our
- frontmatter to OKF (`type` required; our `tier`, `kind`, `tags`,
- `entities`, TTL fields as extensions; OKF explicitly allows unknown
- fields). Decide native conformance vs export-only. Bias: native (wiki
- pages *are* OKF files), because "export" forks the truth.
-- **The migration is the hard part, and it must not churn versions.**
- Renaming/adding frontmatter across every page via normal writes would
- supersede every page in every store (version explosion, embedding
- invalidation, `updated_at` stampede). Instead:
- - **proactive backup before anything is touched**: the migration's
- first step compresses the entire data dir (wiki files, SQLite DB,
- manifest) into a timestamped archive *outside* the data dir, in the
- user's home (e.g. `~/ai-memory-backup-pre-2.0-<date>.tar.gz`),
- verifies the archive is readable (entry listing + size sanity)
- before proceeding, and **aborts the migration if the backup cannot
- be written or verified**: no backup, no migration. The archive
- path is recorded in the wiki meta manifest.
- - **the HTML wiki homepage surfaces the backup**: after migration,
- `serve`'s homepage shows a notice with the archive's path, size,
- and date, plus the two exits: "everything looks right → delete the
- archive" and "something is missing → restore steps" (linking the
- restore section of `docs/MIGRATION-2.0.md`). The notice is
- dismissible and disappears once the archive is deleted.
- - a dedicated one-shot migration: rewrite frontmatter **in place**,
- same page id, same version row, body untouched; single git commit
- ("okf-migration") with a pre-migration checkpoint; reindex after.
- - a `wiki_format` marker (in the wiki meta manifest) records the
- format generation; `serve` refuses to open a newer-generation wiki
- with an older binary (mirror of the DB's schema-ahead guard).
- - rollback: the pre-migration git checkpoint plus `reindex`.
- - idempotent: re-running migrates zero pages.
-- Round-trip tests: our page → OKF file → parsed back identical; foreign
- OKF bundle imports into a project; migration control test proves the
- no-churn property (same ids before/after); backup control test (break
- the archive step and the migration must refuse to run); homepage notice
- renders the recorded archive path and clears when the file is gone.
-- `ai-memory export --okf <dir>` / `import --okf` for the non-native
- direction regardless, for interop with bundles outside the store.
-
-## Item 3 - Typed relation edges
-
-*Why:* `causes` / `fixes` / `contradicts` on the existing `links` model;
-`contradicts` feeds the lint pass that already exists.
-
-- Schema: `links.relation` (nullable TEXT, default NULL = plain link),
- an additive migration with zero rewrite of existing rows.
-- Producers: wikilink syntax extension (`[[page|fixes]]` or frontmatter
- `relations:`) decided in a short design note; consolidation prompt
- gains the vocabulary (JSON-schema constrained, per invariant 7).
-- Consumers: lint (contradiction findings from `contradicts` edges),
- retrieval graph stream (relation-aware weighting only if item 1 shows
- it helps; otherwise store, don't weight).
-- Migration: none needed (additive). Docs: usage + graph docs.
-
-## Item 4 - Temporal validity on entity links (bi-temporal-lite)
-
-*Why:* "what was true in June", the one mainstream graph-camp mechanism
-worth having. Builds on item 3's schema work.
-
-- **Design doc before schema.** Reference: Zep/Graphiti paper. Scope
- deliberately small: `valid_from` / `superseded_at` on
- `entity_page_links` (and possibly typed edges), populated by
- supersession events we already emit: when a page version supersedes,
- its entity links inherit the timeline. No world-time vs
- ingestion-time split in v1 of this; ingestion-time only, documented as such.
-- Retrieval: `as_of` parameter on entity queries (additive, default
- now).
-- Migration: additive columns; backfill `valid_from` from the page
- version's `created_at` as a one-shot data migration inside refinery.
-
-## Item 5 - Local embeddings (all-MiniLM class; shipped via candle, not ONNX)
-
-*Why:* zero-config hybrid retrieval with no provider; `models/` has been
-reserved for this since M9.5. Competitors ship it by default.
-
-- `ort` crate; model NOT bundled in the binary (size); it is fetched on
- `ai-memory embed --provider local` first use into `models/`, with
- checksum pinning and an offline path (drop the file in manually).
-- Coexistence is already designed: `(provider, model, dim)` is
- denormalized on `page_embeddings`, so local vectors sit beside
- provider vectors and hybrid search already ignores mismatched triples.
- Migration: none forced; `embed --force` re-embeds opt-in.
-- Item 1 measures retrieval delta local-vs-provider before making local
- the default for fresh installs; existing installs keep their
- configured provider either way.
-- Watch: `ort`/onnxruntime licensing + build weight on all release
- targets (incl. Windows); a `local-embeddings` cargo feature if the
- dependency is heavy. **As built: this watch item decided the implementation: candle (pure Rust) instead of ort, no native
- runtime, feature `local-embeddings` (default on). Same model, same
- use case; see `docs/local-embeddings.md`.**
-
-## Item 6 - Cross-session abstraction ("Experience" stage)
-
-*Why:* the frontier the survey names; the narrative layer TriMem argues
-for. Most speculative, therefore last, and shaped by whatever items
-1-5 taught us.
-
-- A periodic pass (auto-improve is the host; scheduled like existing
- maintenance) that reads the last N sessions per project and stages
- rewrites of pattern/preference/architecture pages, cross-trajectory rather than per-session. Staged through `pending-writes` exactly like other
- auto-improve output: reviewable, never silent.
-- Zero-LLM default preserved: pass is opt-in like consolidation.
-- Success metric from item 1 plus a curated before/after page-quality
- review; if it cannot demonstrate value, it ships disabled-by-default
- with a note saying so, or not at all.
-
-## Item 7 - `status` truthfulness audit (pre-cut, low priority)
-
-*Why:* `status` is what a user trusts when deciding whether the system
-is healthy. Six items of new state make it easy for the display to drift
-from reality. Scheduled deliberately **after** items 1-6 so it audits
-the final surface, not a moving one.
-
-- Assessment first, fixes second: for every line `status` prints, trace
- it to the source of truth and answer "has this been true so far?": counts vs actual rows, FTS coverage vs actual index, embedding
- backlog vs reality, spool depth, server/bind/data-dir provenance.
-- Then the inverse: what health signal exists that `status` *doesn't*
- show? 2.0 candidates from items 1-6: `wiki_format` generation and
- OKF migration state, the pre-migration backup archive (present/size),
- typed-edge and temporal-column counts, local-ONNX embedder health,
- last eval-baseline date. Also pre-existing gaps (e.g. does anything
- surface a wedged writer queue or a failed auto-improve scope?).
-- Same lens over the sibling surfaces that claim health: `serve`
- startup lines, the admin console overview, and the wiki homepage.
-- Tests: each status line gets a test that breaks the underlying state
- and proves the line changes (logic broken, never a destination).
-
-## Item 8 - Documentation why/when pass (pre-cut)
-
-*Why:* feature docs written alongside code default to "what it does";
-readers deciding whether to ADOPT a feature need "why it exists",
-"when to reach for it" (and when not to), and a real-world example
-showing the possibility, the way `docs/local-embeddings.md` leads
-with the egress/paraphrase-recall story before the mechanics.
-
-- Sweep every user-facing doc (README sections, docs/*.md, the
- config template comments) and grade each feature's coverage: what /
- why / when / example. Fix the gaps: a short scenario ("two
- teammates on one server", "resuming on the laptop what the desktop
- left off", "asking what we knew about X before the rewrite") beats a
- flag list.
-- Real examples over abstractions: pick from this project's own
- history where possible (the eval harness catching the FTS5 bug is a
- better typed-edges/`contradicts` story than an invented one).
-- When-not-to guidance is part of honesty: every feature doc names the
- case where the simpler default is the right call.
-- Runs after items 1-6 so it covers the final surface, alongside the
- item 7 status audit.
-
-## Sequencing and the cut
-
-```
-1 harness → 2 OKF (+migration) → 3 typed edges → 4 temporal → 5 local-embed → 6 abstraction → 7 status audit → 8 docs why/when pass
-```
-
-Each lands on main individually gated (fmt, clippy -D warnings, full
-tests, changelog guards, harness numbers where retrieval is touched), with
-**fast Linux CI only per item**; the slow macOS/Windows matrix runs
-once, mandatorily, on the release-candidate SHA before the cut (see
-AGENTS.md "CI pacing"). 2.0 is cut when:
-
-- all six items (or an explicitly-decided subset; item 6 may justifiably drop) are merged with docs;
-- `docs/MIGRATION-2.0.md` reads as a complete upgrade guide and has been
- exercised against a copy of a real 1.x data dir, **including a full
- restore drill from the pre-migration backup archive**;
-- README/ARCHITECTURE reflect 2.0 reality;
-- the eval numbers are re-run and published for the final tree;
-- a **pr-post-audit over the whole 2.0 range** (v1.39.0 → the
- release candidate) has run clean: every item PR re-verified against
- the final combined tree, cross-PR interactions swept, documentation
- ledger checked, with findings fixed and re-audited before anything else
- proceeds;
-- the full macOS/Windows CI matrix is green on the release-candidate
- SHA (dispatched, not assumed), and **the user has reviewed the summary
- of everything done and explicitly approved the release**. 2.0 is never cut automatically.
-
-Deploy/live-test follows the same v1.39 pipeline: exact-main gates,
-hosted CI, `compose pull` (never `bin/deploy`), health + status + a
-migration dry-run against a copied production data dir *before* the
-production upgrade.
diff --git a/docs/agent-messaging.md b/docs/agent-messaging.md
index 4cbbd43e..a06ef8c8 100644
--- a/docs/agent-messaging.md
+++ b/docs/agent-messaging.md
@@ -144,7 +144,10 @@ design, confirm a merge) uses this same mailbox. The server already stores an
optional one-line `subject` and a `body` on every message. This section is the
convention both sides share so a companion and every orchestrator encode a
decision the same way. The tools stay `memory_message_send` and
-`memory_message_list`. [#1281](https://github.com/akitaonrails/ai-memory/issues/1281)
+`memory_message_list`. The still-open structured-protocol proposal is
+[`design-message-decisions.md`](design-message-decisions.md) / issue
+[#1281](https://github.com/akitaonrails/ai-memory/issues/1281); none of that
+proposal's fields or authorization rules exists yet.
The server stores that text as opaque message content. Correlation, options,
and who may answer live in the text plus the provenance the list already
diff --git a/docs/benchmarks/README.md b/docs/benchmarks/README.md
index 609874f7..b9bb919d 100644
--- a/docs/benchmarks/README.md
+++ b/docs/benchmarks/README.md
@@ -19,7 +19,7 @@ cargo run --release -p ai-memory-eval -- retrieval --fetch
| **2026-10-15** | LongMemEval-S (v1) | **local embeddings + observation stream (3.0.1 release)** | **0.943** | [longmemeval-s-3.0.1-release.md](longmemeval-s-3.0.1-release.md) |
| **2026-10-13** | LongMemEval-S (v1) | **zero-llm FTS + observation stream (3.0.0 release; on by default)** | **0.951** | [longmemeval-s-3.0.0-release.md](longmemeval-s-3.0.0-release.md) |
| **2026-10-13** | LongMemEval-S (v1) | **local embeddings + observation stream (3.0.0 release; on by default)** | **0.945** | [longmemeval-s-3.0.0-release.md](longmemeval-s-3.0.0-release.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) | local embeddings (historical 2.4 RC) | 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) |
diff --git a/docs/design-backup-agent-assets.md b/docs/design-backup-agent-assets.md
index ccce50f5..fa10966e 100644
--- a/docs/design-backup-agent-assets.md
+++ b/docs/design-backup-agent-assets.md
@@ -1,5 +1,9 @@
# Backup and Restore of AI Agent Assets (Skills, MCP, Plugins)
+**Status: implemented.** The shipped commands are `ai-memory backup-agents`
+and `ai-memory restore-agents`; the README is the current operator guide. This
+document retains the design and threat-model rationale.
+
## 1. Context and Motivation
`ai-memory` coordinates memory and context across AI coding agents (Claude Code, OpenAI Codex, Antigravity CLI, Gemini CLI, Cursor, OpenCode, Devin, Grok, Kiro, etc.).
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 71c47a69..dabcd089 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -205,7 +205,9 @@ agentmemory has this informally (`/handoff` skill); we make it explicit from day
## 10. MCP tool surface - narrow on purpose
-basic-memory has ~25 tools, agentmemory has 53. Both have user confusion as a result. The current v1 surface is still deliberately narrow:
+basic-memory has ~25 tools, agentmemory has 53. Both have user confusion as a
+result. The original v1 surface was deliberately narrow; the current additive
+surface is listed in [`ARCHITECTURE.md`](ARCHITECTURE.md#mcp-tool-surface-24-tools):
| Tool | Purpose | Annotation |
|---|---|---|
diff --git a/docs/design-hindsight-borrowings.md b/docs/design-hindsight-borrowings.md
index f9259b72..97ac1750 100644
--- a/docs/design-hindsight-borrowings.md
+++ b/docs/design-hindsight-borrowings.md
@@ -6,10 +6,12 @@ default-behavior-unchanged. Shipped: **P1** typed redaction labels
`evidence_count` explain field, ranking-inert; **P3** the typed edge kind in
`graph_via.edge` explain, ranking unchanged; **P4** an opt-in `settled_first`
briefing (default off); **P5** the no-API-key subscription docs. The
-**eval-gated activations remain deferred behind the R2 harness** (which does not
-yet exist): P2's confidence→authority factor and P3's typed-edge rank weighting /
-`contradicts` cap are NOT wired into ranking: the data and explanations land, and
-the default-rank flips wait for a number. Targets the `release/2.2` line
+R2 harness now exists and has been run. P2's confidence-to-authority factor
+was wired behind the default-off `belief_authority_weight` in 2.4; its
+zero-LLM R2 delta was `0.000` because that corpus has no consolidation
+evidence, so it remains off pending a consolidated-corpus result. P3's
+typed-edge rank weighting and `contradicts` cap remain unbuilt. The original
+implementation plan targeted the `release/2.2` line
(2.2.x; every item here is additive). Derived from
[`research-hindsight.md`](research-hindsight.md) §11 ("Strengths worth
borrowing") and the landscape recommendations R3/R5 in
@@ -51,7 +53,8 @@ Restated from `AGENTS.md` because they bound each design below:
- **Migrations are backup-gated (#9 / #633 ordering).** Any new column/table is
a `V63__*.sql` refinery step behind the pre-migration archive, plus the pin
bump at `api_credentials.rs:414` (currently `62`).
-- **MCP tool count is frozen at 23** (enforced by `MCP_TOOL_NAMES` and the
+- **MCP tool count was frozen at 23 for this plan** (enforced by
+ `MCP_TOOL_NAMES` and the
registered-router test in `server.rs`). None of these phases needs a *new* tool; they extend
existing surfaces (`memory_query` explain, `memory_status`, `memory_lint`,
the scheduler). If P2 ever warranted a dedicated tool, that is a separate
diff --git a/docs/design-marketplace-plugins.md b/docs/design-marketplace-plugins.md
index b94527f9..a10d06f3 100644
--- a/docs/design-marketplace-plugins.md
+++ b/docs/design-marketplace-plugins.md
@@ -314,7 +314,8 @@ See open question 4.
plugin update themselves (documented in `docs/install.md`).
- **`uninstall`:** offer `claude plugin uninstall ai-memory@ai-memory`.
-None of this touches the MCP tool surface, so the tool count stays at 23.
+None of this touched the MCP tool surface, so that implementation kept the
+then-current count at 23.
### 4. Configuration surface
diff --git a/docs/design-memory-aging.md b/docs/design-memory-aging.md
index 15c57686..364da19d 100644
--- a/docs/design-memory-aging.md
+++ b/docs/design-memory-aging.md
@@ -1,5 +1,11 @@
# Design: memory aging — decay curves, tier-down, dream pass, access-weighting (2.4)
+**Status: implemented in 2.4.** The zero-LLM aging set and the opt-in LLM
+dream pass shipped; ranking-affecting and lossy behavior remains default-off
+as designed. Sections labelled "Current state" and the phased PR plan preserve
+the pre-implementation baseline. Current feature status and R2 results are in
+[`competitive-parity.md`](competitive-parity.md#prior-gaps-and-current-status).
+
Design-of-record for a 2.4 feature set that improves how ai-memory handles
**old** memory: decay/compression/consolidation and access-weighted retention.
It is honest about what already ships, what is dormant, and what is proposed;
diff --git a/docs/design-message-decisions.md b/docs/design-message-decisions.md
index 0285a427..27df323a 100644
--- a/docs/design-message-decisions.md
+++ b/docs/design-message-decisions.md
@@ -1,6 +1,9 @@
# Design proposal: decision requests and replies on cross-project messages (#1281)
-**Status: design proposal, not implemented. 3.2 candidate.**
+**Status: open design proposal, not implemented, with no assigned release.**
+Issue [#1281](https://github.com/akitaonrails/ai-memory/issues/1281) remains
+open. Any implementation must rebase the migration numbers, tool count, and
+branch assumptions below against the then-current tree.
The maintainer set the scope in
[#1281](https://github.com/akitaonrails/ai-memory/issues/1281#issuecomment-6185835811):
@@ -188,8 +191,8 @@ Proposal (Q1, option c):
| `memory_message_pop` | New `work_id`. A plain pop skips bound replies. It adds `decision_notice`. |
| `memory_message_cancel` | Skips replies. |
-The tool count stays at 23, the admin routes get the same fields, and `/api/v1`
-and `/web` do not change. The handler and the validator refuse the
+The proposal adds no MCP tool; the admin routes get the same fields, and
+`/api/v1` and `/web` do not change. The handler and the validator refuse the
`invalid_params` reasons before the store. The store returns a typed
`StoreError` for each other reason, never `internal_error`.
@@ -352,7 +355,7 @@ control, and fails with its guard removed.
| PR | Base | Content |
|---|---|---|
| 0 | `main` | This note (docs only, as #1008). |
-| 1 | The branch for 3.2 work | One piece: V81; types and validator; the capability; store, writer, MCP and HTTP changes; `MEMORY_INSTRUCTIONS` and the messaging skill; `docs/agent-messaging.md`, `docs/usage.md`, `docs/ARCHITECTURE.md`; inventory rows; the TypeScript SDK (its drift test needs it), with error codes for the new reasons; `CHANGELOG.md`; tests 1 to 11. |
+| 1 | The feature branch selected after approval | One piece: the next free migration; types and validator; the capability; store, writer, MCP and HTTP changes; `MEMORY_INSTRUCTIONS` and the messaging skill; `docs/agent-messaging.md`, `docs/usage.md`, `docs/ARCHITECTURE.md`; inventory rows; the TypeScript SDK (its drift test needs it), with error codes for the new reasons; `CHANGELOG.md`; tests 1 to 11. |
| 2 | Same | CLI flags (`--reply-to`, `--choice`, `--decision-file`, `--work-id`) and an e2e test. |
## 9. Alternatives
diff --git a/docs/design-page-ingestion-windows.md b/docs/design-page-ingestion-windows.md
index 8d0521bf..c9807856 100644
--- a/docs/design-page-ingestion-windows.md
+++ b/docs/design-page-ingestion-windows.md
@@ -227,7 +227,7 @@ its precision for entity-phrased questions.
- Full local gate per AGENTS.md; fast Linux CI per merge, full matrix on
the release-candidate SHA before any tag, per the CI pacing rule.
-## 9. Open questions (for maintainer input before coding)
+## 9. Questions resolved during implementation
1. The v2.1.0 cut landed after your "targeting 2.1" note: does the
implementation PR still ride the `release/2.1` line (2.1.x additive)
diff --git a/docs/design-rules-promotion.md b/docs/design-rules-promotion.md
index e08110c3..3ed435d8 100644
--- a/docs/design-rules-promotion.md
+++ b/docs/design-rules-promotion.md
@@ -13,9 +13,9 @@ Insight borrowed from ECC (`docs/research-ecc.md`): **"Memory is unreviewed
context, not executable policy. Promote accepted knowledge into governed
project documentation."** ai-memory already points in this direction: the lint
emits a `rule_suggestion` finding ("this page looks like a durable rule;
-consider copying it into CLAUDE.md/AGENTS.md"). The 2.1 feature closes that
-loop by turning a durable memory into a governed, always-loaded rule the agent
-obeys every turn.
+consider copying it into CLAUDE.md/AGENTS.md"). A future feature would close
+that loop by turning a durable memory into a governed, always-loaded rule the
+agent obeys every turn.
The maintainer named the trap, and it kills this feature if we get it wrong:
AGENTS.md is a scarce, shared budget. If promotion dumps every learned rule
diff --git a/docs/design-tiered-session-brief.md b/docs/design-tiered-session-brief.md
index 13c89714..26687838 100644
--- a/docs/design-tiered-session-brief.md
+++ b/docs/design-tiered-session-brief.md
@@ -1,12 +1,14 @@
# Design: tiered L0/L1/L2 SessionStart brief
-**Status:** Draft (2026-10-13). Open questions resolved. Eventual path:
-[`docs/design-tiered-session-brief.md`](design-tiered-session-brief.md).
+**Status:** Implemented in 3.1 by PR
+[#1264](https://github.com/akitaonrails/ai-memory/pull/1264); this is the
+design of record. The baseline, rollout, and PR-plan sections below describe
+the proposal as reviewed, not unfinished work. Current behavior is summarized
+in [`ARCHITECTURE.md`](ARCHITECTURE.md#data-flow).
-This is the remaining landscape R7 work: consume extractive L0/L1/L2
-tiers on the opted-in SessionStart project brief. Additive rendering on
-the next minor after 3.0.0. Verified against `main` at `dbe928e3`
-(`release: v3.0.0`).
+This completed the remaining landscape R7 work: consume extractive L0/L1/L2
+tiers on the opted-in SessionStart project brief. The proposal baseline was
+verified against `main` at `dbe928e3` (`release: v3.0.0`).
Ideas only from OpenViking's progressive-disclosure tiers and Letta-code
MemFS directory deferral. Do not vendor either tree (OpenViking is AGPLv3).
@@ -232,7 +234,7 @@ Restated from `AGENTS.md` because they bound the packing:
5. **Pages shared, batons owned (#16).** The brief does not filter pages
by `author_id`. Slot visibility stays the existing
`SlotVisibility::for_viewer` SQL predicate.
-6. **MCP tool count frozen at 23.** No `memory_brief_expand`. Footer
+6. **MCP tool count was frozen at 23 for this proposal.** No `memory_brief_expand`. Footer
already points at follow-up tools.
7. **Wiki mutations stay on `Wiki::write_page` / `apply_batch`.** This
design does not write wiki files. It only reads latest rows.
@@ -893,7 +895,8 @@ must not call it.
### D. New MCP tool `memory_brief_expand`
-Breaks the 23-tool freeze. Duplicates `memory_read_page` (by path) and
+Would have broken the then-current 23-tool freeze. Duplicates
+`memory_read_page` (by path) and
`memory_query` (by search). The footer already names follow-up. Rejected.
### E. Persist compiled L0/L1 sidecar files (OpenViking `.abstract.md` / `.overview.md`)
diff --git a/docs/desktop/antigravity.md b/docs/desktop/antigravity.md
index 94882dd4..be945735 100644
--- a/docs/desktop/antigravity.md
+++ b/docs/desktop/antigravity.md
@@ -71,7 +71,9 @@ handle: no `SessionEnd` event (a finished `Stop` is a turn checkpoint
instead), no prompt in any payload (read from the transcript), older builds
without `SessionStart` (the first turn's `PreInvocation` stands in), and `cwd`
comes as `workspacePaths[]` rather than a single `cwd`. Needs a live
-verification pass on the IDE. Implemented in 3.2 (#TBD); see
+verification pass on the IDE. Implemented in 3.2
+([#1415](https://github.com/akitaonrails/ai-memory/issues/1415),
+[#1416](https://github.com/akitaonrails/ai-memory/pull/1416)); see
[`plan.md`](plan.md#phase-1--antigravity-ide-capture-parity-smallest-new-code-step).
**Verified with the CLI (`agy` 1.3.0, 2026-10-08; see
diff --git a/docs/desktop/plan.md b/docs/desktop/plan.md
index d537dcd7..81faf3e7 100644
--- a/docs/desktop/plan.md
+++ b/docs/desktop/plan.md
@@ -1,8 +1,9 @@
# Desktop support — phased plan (research output, reconciled with RFC #878)
-> This file reconciles RFC #878 (github.com/akitaonrails/ai-memory#878) with
-> the findings in this directory (2026-10-07). Nothing here is scheduled
-> work; each phase lists what would need to change and where the risk sits.
+> This dated rollout record reconciles RFC #878
+> (github.com/akitaonrails/ai-memory#878) with the findings in this directory
+> (2026-10-07). Nothing remaining here is scheduled work; each phase records
+> what shipped or what would still need to change and where the risk sits.
## What the research changed vs the RFC
@@ -64,7 +65,9 @@ The research's best new target, ahead of the RFC's `.mcpb`:
- Tests: payload-mapping unit tests against the documented schema
(camelCase fields; `<app_data_dir>` variants per surface).
-Status (3.2, #TBD): the premise above that Antigravity has no SessionStart is
+Status (3.2, [#1415](https://github.com/akitaonrails/ai-memory/issues/1415),
+implemented by [#1416](https://github.com/akitaonrails/ai-memory/pull/1416)):
+the premise above that Antigravity has no SessionStart is
out of date. The hook reference bundled with `agy` 1.4.0 and App 2.24.0 (and
<https://antigravity.google/docs/hooks/>) documents `SessionStart`, fired once
per new conversation before the first model call; `agy` 1.3.0, verified here
@@ -106,7 +109,7 @@ payload. What shipped, under the existing `antigravity-cli` agent kind:
## Phase 3 — explicit capture for hookless surfaces (RFC Phase 1, adjusted)
-- Tool-surface change (23-tool count, MEMORY_INSTRUCTIONS/SNIPPET_BODY,
+- Tool-surface change (current 24-tool count, MEMORY_INSTRUCTIONS/SNIPPET_BODY,
prompt-surface regression tests, adversarial boundary test) for an
explicit capture tool the model calls on apps without hooks (Claude Chat
tab, Grok Bot, hosted ChatGPT chat). Scoping per RFC: fixed
diff --git a/docs/issues-basic-memory.md b/docs/issues-basic-memory.md
index d1319935..852507a6 100644
--- a/docs/issues-basic-memory.md
+++ b/docs/issues-basic-memory.md
@@ -1,5 +1,11 @@
# basic-memory - Issue & PR Pain-Point Synthesis
+> **Historical snapshot (2026-05-21).** This file is retained because the
+> architecture cites these concrete failure modes; issue states and version
+> claims below are not current product guidance. See
+> [`research-2026-landscape.md`](research-2026-landscape.md) for the latest
+> reviewed competitor state.
+>
> Source: GitHub `basicmachines-co/basic-memory`. Captured 2026-05-21.
> Tracker is unusually high-signal: small team, deep technical replies.
> Dominant themes: sync correctness, multi-project routing, embedding install hell.
diff --git a/docs/issues-cognee.md b/docs/issues-cognee.md
index ad055296..d6c84ad1 100644
--- a/docs/issues-cognee.md
+++ b/docs/issues-cognee.md
@@ -1,5 +1,11 @@
# cognee - Issue & PR Pain-Point Synthesis
+> **Historical snapshot (2026-05-21).** This file is retained because the
+> architecture cites these concrete failure modes; issue states and version
+> claims below are not current product guidance. See
+> [`research-2026-landscape.md`](research-2026-landscape.md) for the latest
+> reviewed competitor state.
+>
> Source: GitHub `topoteretes/cognee`. Captured 2026-05-21.
> Tracker character: ~40% feature requests (high comment counts), ~40% bugs
> closed fast by next release, ~20% truly hard still-open bugs at architectural seams.
diff --git a/docs/issues-mempalace.md b/docs/issues-mempalace.md
index 8e0bf3e4..f5207370 100644
--- a/docs/issues-mempalace.md
+++ b/docs/issues-mempalace.md
@@ -1,5 +1,11 @@
# MemPalace - Issue & Architecture Synthesis
+> **Historical snapshot (2026-05-24).** This file is retained because the
+> architecture cites these concrete failure modes; issue states and version
+> claims below are not current product guidance. See
+> [`research-2026-landscape.md`](research-2026-landscape.md) for the latest
+> reviewed competitor state.
+>
> Source: GitHub `MemPalace/mempalace`.
> Captured 2026-05-24. Repo: 52.7k stars, MIT, Python, created 2026-04-05,
> v3.3.5, 241 open issues, ~1600 PRs in ~7 weeks. The maintainers publish
diff --git a/docs/prior-art-implementation-findings.md b/docs/prior-art-implementation-findings.md
index 318e56a8..fb44c239 100644
--- a/docs/prior-art-implementation-findings.md
+++ b/docs/prior-art-implementation-findings.md
@@ -312,7 +312,7 @@ These items previously drifted from the code. Their current status is:
| Area | Current status |
|---|---|
-| MCP tool count/list | Fixed: architecture and design docs list the current 17-tool surface. |
+| MCP tool count/list | Fixed: `ARCHITECTURE.md` lists the current 24-tool surface; the v1 design table remains an explicitly historical baseline. |
| Lint scope | Fixed: lint covers stale episodic pages, duplicate titles, rule suggestions, broken cross-project links, and optional LLM contradictions. |
| sqlite-vec status | Fixed: the vector policy documents packed vectors in SQLite with brute-force cosine as the current backend. |
| raw archive status | Fixed: docs distinguish reserved `raw/` files from implemented observation-FTS fallback. |