Skip to content

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

Rust

docs(roadmap): 2.0 release plan from the 2026 landscape research

AkitaOnRails625996ffc650
diff --git a/README.md b/README.md
index 1b7c77eb..249219df 100644
--- a/README.md
+++ b/README.md
@@ -343,6 +343,7 @@ diagram, crate breakdown, schema notes, and invariants.
- [`docs/llm-providers.md`](docs/llm-providers.md) - provider configuration.
- [`docs/security.md`](docs/security.md) - the full security model.
- [`docs/research-2026-landscape.md`](docs/research-2026-landscape.md) - how the field looks and where we sit in it.
+- [`docs/ROADMAP-2.0.md`](docs/ROADMAP-2.0.md) - the plan for the 2.0 release, one item at a time.
- [`docs/ROADMAP-2.0.md`](docs/ROADMAP-2.0.md) - the 2.0 plan.
## Influences and prior art
diff --git a/docs/ROADMAP-2.0.md b/docs/ROADMAP-2.0.md
new file mode 100644
index 00000000..d882869d
--- /dev/null
+++ b/docs/ROADMAP-2.0.md
@@ -0,0 +1,176 @@
+# 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 0.967 R@5, mcp-memory-service 0.804/0.860) are against
+ **v1** chat histories. 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:
+ - 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).
+- `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) -
+ additive migration, 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 honestly.
+- Retrieval: `as_of` parameter on entity queries (additive, default
+ now).
+- Migration: additive columns; backfill `valid_from` from the page
+ version's `created_at` - a one-shot data migration inside refinery.
+
+## Item 5 - Local embeddings (ONNX, all-MiniLM class)
+
+*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) - 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.
+
+## 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,
+ not 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 the honest note, or not at all.
+
+## Sequencing and the cut
+
+```
+1 harness → 2 OKF (+migration) → 3 typed edges → 4 temporal → 5 local-embed → 6 abstraction
+```
+
+Each lands on main individually gated (fmt, clippy -D warnings, full
+tests, changelog guards, harness numbers where retrieval is touched).
+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;
+- README/ARCHITECTURE reflect 2.0 reality;
+- the eval numbers are re-run and published for the final tree.
+
+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.