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.mdindex 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 articlesWritten by users; not maintained here, so check them against the version you run.diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex 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 notfit are listed by path for `memory_read_page`, and the count of them isreserved before any page is deepened. The security notice, theuntrusted-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 afenced, 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 ametadata-only notice naming the exact handoff id and leaves the row open foran 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 writesthe summary page and enqueues consolidation but skips creating an automaticbaton, and an OpenCode or Antigravity turn checkpoint refreshes the page@@ -1187,6 +1191,7 @@ llm = true # use the configured provider when there is onverbatim_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.mdmax_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 Portuguesehistory 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.mddeleted file mode 100644index 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.mdindex 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 anoptional one-line `subject` and a `body` on every message. This section is theconvention both sides share so a companion and every orchestrator encode adecision 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 alreadydiff --git a/docs/benchmarks/README.md b/docs/benchmarks/README.mdindex 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.mdindex 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.mdindex 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.mdindex 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 worthborrowing") 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 isa `V63__*.sql` refinery step behind the pre-migration archive, plus the pinbump 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 theregistered-router test in `server.rs`). None of these phases needs a *new* tool; they extendexisting surfaces (`memory_query` explain, `memory_status`, `memory_lint`,the scheduler). If P2 ever warranted a dedicated tool, that is a separatediff --git a/docs/design-marketplace-plugins.md b/docs/design-marketplace-plugins.mdindex 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 surfacediff --git a/docs/design-memory-aging.md b/docs/design-memory-aging.mdindex 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.mdindex 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. Alternativesdiff --git a/docs/design-page-ingestion-windows.md b/docs/design-page-ingestion-windows.mdindex 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 onthe release-candidate SHA before any tag, per the CI pacing rule.-## 9. Open questions (for maintainer input before coding)+## 9. Questions resolved during implementation1. The v2.1.0 cut landed after your "targeting 2.1" note: does theimplementation 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.mdindex 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 unreviewedcontext, not executable policy. Promote accepted knowledge into governedproject documentation."** ai-memory already points in this direction: the lintemits 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 rulediff --git a/docs/design-tiered-session-brief.md b/docs/design-tiered-session-brief.mdindex 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-codeMemFS 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 pagesby `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`. Footeralready points at follow-up tools.7. **Wiki mutations stay on `Wiki::write_page` / `apply_batch`.** Thisdesign 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.mdindex 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 checkpointinstead), no prompt in any payload (read from the transcript), older buildswithout `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; seediff --git a/docs/desktop/plan.md b/docs/desktop/plan.mdindex 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 isout 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 onceper 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 anexplicit capture tool the model calls on apps without hooks (Claude Chattab, Grok Bot, hosted ChatGPT chat). Scoping per RFC: fixeddiff --git a/docs/issues-basic-memory.md b/docs/issues-basic-memory.mdindex 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.mdindex 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.mdindex 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 publishdiff --git a/docs/prior-art-implementation-findings.md b/docs/prior-art-implementation-findings.mdindex 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. |