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.mdindex 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 artdiff --git a/docs/ROADMAP-2.0.md b/docs/ROADMAP-2.0.mdnew file mode 100644index 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.