Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs(2.4): reflect shipped memory-aging feature set + re-assess competitive standing
AkitaOnRailsdd6e8e884830
diff --git a/README.md b/README.mdindex 59e769ef..7e145185 100644--- a/README.md+++ b/README.md@@ -53,6 +53,26 @@ ai-memory is what's on the other side of those walls.uses **zero LLM calls**: capture, search, and handoffs all work with noAPI key at all.+- **It ages gracefully, without an LLM.** Memory decays on a schedule you+ can tune per tier, and the memory you actually use decays *slower* — open a+ page, search it, or reach it through a link and it earns its keep. When+ episodic notes go cold they can be compacted down to their durable facts+ (file paths, error codes, decisions) instead of dropped, near-duplicates+ collapse into one, and likely contradictions get flagged — all with **zero+ API calls**. Nothing is hard-deleted: the original stays in git and the+ version chain (`restore-page` brings it back). Access-weighted retention is+ always on because it can only ever keep memory *longer*; the parts that+ rewrite or drop content (compaction, dedup, per-tier curves) stay off by+ default until you turn them on.++- **And it can dream, if you let it.** Point it at an LLM and an opt-in+ background pass will, while you're idle, rewrite whole clusters of cold+ notes into single coherent pages — cancelling the moment you come back to+ work. It never deletes a source (the pre-merge versions stay reachable),+ it's off by default, and it's gated on a recall eval before it could ever+ become default behavior. The zero-LLM path above is what runs unless you+ ask for more.+- **It tells you the truth about itself.** One self-contained binary.Purge commands that say exactly what "deleted" means. A measured writeceiling (~700/s) instead of a guessed one. An audit log of every@@ -132,16 +152,19 @@ each, and what you gain:|---|---|---|| **Mem0 / fact extractors** (LangMem) | Automatic per-turn capture | Memory compiles into readable **pages** you own and edit, not opaque fact rows; retrieval fuses FTS + entity + graph (+ optional vectors), not vector-only || **Zep / Graphiti** (temporal KG) | Temporal reasoning, typed relations | Bi-temporal-lite (`as_of`, version-filtered search) and typed edges without standing up a graph database — on one binary |-| **mcp-memory-service** (closest sibling) | SQLite + local embeddings, hook capture, typed edges, honest numbers | Human-editable markdown **pages** instead of fact-rows, plus cross-agent handoffs as a first-class, claim-once protocol |+| **mcp-memory-service** (closest sibling) | SQLite + local embeddings, hook capture, typed edges, honest numbers — and, on 2.4, per-tier decay curves, extractive compression, DBSCAN cold-cluster dedup, access reinforcement, and contradiction flagging | Human-editable markdown **pages** instead of fact-rows, cross-agent claim-once handoffs, and the same aging machinery done **zero-LLM by default, reversibly** (supersede-not-delete + `restore-page`), and **off by default** || **basic-memory** (file-first sibling) | Markdown-on-disk as the source of truth | Automatic lifecycle capture and a derived FTS/entity/graph index on top, cross-agent handoffs, and multi-user sharing built in || **Claude Code built-in memory** | "Remember my project" convenience, zero setup | Synced across machines and agents, searchable, team-capable, and captures tool lifecycle — not a per-laptop `MEMORY.md` |-| **Hindsight / OpenViking** (hosted, LLM-required) | Living pages / document memory with a background consolidation loop | A self-contained binary that runs zero-LLM by default and keeps memory in files you own; per-project team sharing instead of strict per-bank isolation |+| **Hindsight / OpenViking** (hosted, LLM-required) | Living pages / document memory with a background consolidation loop — and, on 2.4, belief-strength confidence plus an opt-in LLM "dream" rewrite of cold clusters | A self-contained binary that runs zero-LLM by default and keeps memory in files you own; per-project team sharing instead of strict per-bank isolation; the dream/belief features are **opt-in, off by default, and never delete a source** (vs a mandatory LLM loop) || **Supermemory / LiquidLM** (hosted memory API) | A managed second brain with automatic ingestion | Git-versioned markdown you own, no required API spend, offline operation, and per-project team sharing — ai-memory remembers *this repo*, not a general vault |The consistent theme: **files you own** (git-backed markdown), a **zero-LLMdefault**, **one self-contained binary**, **cross-agent + cross-machine + team**sharing, **automatic lifecycle capture**, and **typed, claim-once handoffs**.-Opt-in features (LLM consolidation, vector search) stay opt-in.+Opt-in features (LLM consolidation, vector search, the "dream" consolidation+pass, belief-strength in ranking) stay opt-in — and the zero-LLM aging path+(per-tier decay, extractive compaction, dedup, contradiction flagging,+access-weighted retention) works with no API key at all.**Built on the shoulders of:** the[Karpathy LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)diff --git a/docs/comparison.md b/docs/comparison.mdindex 0a03d99a..43f50de9 100644--- a/docs/comparison.md+++ b/docs/comparison.md@@ -55,7 +55,7 @@ not). See [where we're behind](#where-were-behind-or-different-by-choice).| Temporal knowledge graph | Zep/Graphiti, Cognee | Bi-temporal "what was true vs believed when" | Needs a graph DB; heavier to self-host. ai-memory ships **bi-temporal-lite** on SQLite ([`temporal.md`](temporal.md)) + typed edges ([`typed-edges.md`](typed-edges.md)) for the useful part || Memory OS / self-editing | Letta, MemOS, MIRIX | Agent curates its own tiered memory | Token-expensive self-editing; Letta itself now concedes file-first ("Is a Filesystem All You Need?") || Hosted context database | **OpenViking** (ByteDance) | Progressive L0/L1/L2 loading; directory-scoped retrieval; broad integrations | LLM-**required** (VLM + embeddings); opaque swappable storage; AGPLv3 core + SaaS/enterprise weight |-| Paper-backed pages | **Hindsight** (Vectorize) | "Mental models" = living markdown pages an agent boots from; belief-strength consolidation; a preprint | Postgres/pgvector-primary, LLM-required; strict per-bank isolation (no team-sharing within a project) |+| Paper-backed pages | **Hindsight** (Vectorize) | "Mental models" = living markdown pages an agent boots from; belief-strength consolidation; a preprint | Postgres/pgvector-primary, LLM-required; strict per-bank isolation (no team-sharing within a project). ai-memory now ships belief-strength `confidence` + an opt-in LLM "dream" rewrite, both zero-LLM-default-preserving, off by default, and R2-gated before default-on || Closest sibling (fact-row twin) | doobidoo/mcp-memory-service | SQLite(+vec), local ONNX, hook capture, typed edges, honest numbers | What ai-memory would be if it chose fact-rows over wiki **pages** || Platform-native | Claude Code auto-memory | Zero setup, on by default | Machine-local, **no sync**, single-agent, repo-scoped, no tool-lifecycle capture, no team || **File-first wiki (ai-memory)** | ai-memory, basic-memory, OKF | Human-editable markdown truth + derived index; cross-agent; zero-LLM default; multi-user | Below the reranking leaders on raw R@5; LLM-optional means no VLM fact-extraction sophistication |@@ -117,12 +117,50 @@ ai-memory also **shipped the borrowable ideas** from that research rather thanjust cataloguing them: typed relation edges, ingestion-time temporal validitywith `as_of` queries, local (no-key) embeddings as the default, and thecross-session abstraction pass are all in the product today. The 2.4 line added-five more, each **opt-in with defaults byte-identical**: a bounded related-pages-graph walk (`memory_read_page include_related`, basic-memory/LiquidLM), an opt-in-dialectic **answer** over hits and a **reasoning** tier (Honcho, both-LLM-required and off by default), a **pin-before-search** contract (`memory_query-pin_first` + a pinned standing-context briefing, LiquidLM), and a-**show-superseded** retrieval knob over the supersession chains.+five retrieval conveniences, each **opt-in with defaults byte-identical**: a+bounded related-pages graph walk (`memory_read_page include_related`,+basic-memory/LiquidLM), an opt-in dialectic **answer** over hits and a+**reasoning** tier (Honcho, both LLM-required and off by default), a+**pin-before-search** contract (`memory_query pin_first` + a pinned+standing-context briefing, LiquidLM), and a **show-superseded** retrieval knob+over the supersession chains.++The 2.4 line also closed most of the **memory-aging** gap — the decay,+compression, and consolidation machinery the field converged on — on+ai-memory's own zero-LLM, file-first terms (design of record:+[`design-memory-aging.md`](design-memory-aging.md)):++- **Per-tier decay curves** (mcp-memory-service's 365/180/90/30 shape): the+ single global half-life is now a tunable per-tier `[decay.half_life_days]`+ table. Identity default — an upgrade changes no score.+- **Extractive tier-down of cold episodic pages** (agentmemory and+ mcp-memory-service ship extractive, zero-LLM compression as a default):+ instead of evicting a cold page, ai-memory can compact it to its abstract,+ a summary, and a regex-mined keep-token set (paths, URLs, code spans, error+ codes) and drop the prose — reversible through git + the supersession chain.+- **Cold-cluster dedup** (mcp-memory-service's DBSCAN): near-duplicate cold+ episodic pages cluster (adaptive-eps DBSCAN over already-stored embeddings)+ and collapse to one survivor — superseded, never deleted.+- **Zero-LLM contradiction flagging** (mcp-memory-service's 0.4–0.75+ cosine band): `memory_lint` now surfaces likely-conflicting pages, advisory+ only, from existing embeddings.+- **Access-weighted retention** (mcp-memory-service's access boost): a page a+ human opens, searches, or reaches through the link graph resists decay like+ a search hit — now on *every* read path.+- **Belief-strength confidence** (Hindsight, mcp-memory-service): a read-time,+ zero-LLM `confidence` per page (distinct-session breadth, recency, live+ `contradicts` count), surfaced in `memory_query explain` and `memory_status`.+- **An opt-in LLM "dream" pass** (Hindsight's Dreamer, Honcho's Dreamer,+ Supermemory's "dreaming"): idle-scheduled, cancel-on-activity,+ surprisal-first cross-session rewrite/merge of cold clusters.++Two of these change behavior only where a provider is configured and the+operator opts in — belief-strength folded into ranking, and the dream pass —+and both are **off by default and gated on a recall eval (R2) before they may+default on**. No such eval has been run yet, so ai-memory claims *parity of+mechanism, not a measured quality win*: the substrate ships, honestly, off.+Everything else here is zero-LLM, reversible, and off by default until an+operator turns it on.## Coming from another tool?@@ -137,7 +175,12 @@ pin_first` + a pinned standing-context briefing, LiquidLM), and a- **From mcp-memory-service:** a very close sibling; the switch is fact-rows →wiki pages (human-editable markdown truth) and cross-agent handoffs as afirst-class protocol. Cross-project [agent messaging](agent-messaging.md) is- new ground neither had as a typed queue.+ new ground neither had as a typed queue. On aging you keep what you relied on+ — the 2.4 line matches its per-tier decay curves, extractive compression,+ DBSCAN cold-cluster dedup, access boosts, and 0.4–0.75-band contradiction+ detection — but done **zero-LLM by default, reversibly** (every collapse+ supersedes rather than deletes; `restore-page` recovers the original), and+ **off by default** so an upgrade evicts nothing.- **From Supermemory / LiquidLM (a hosted memory API):** you trade a cloudvault and a managed multimodal RAG service for a self-contained binary whosememory lives in git-versioned markdown you own, works zero-LLM by default, and@@ -151,10 +194,17 @@ pin_first` + a pinned standing-context briefing, LiquidLM), and a"second brain," ai-memory remembers *this repo*.- **From Hindsight / OpenViking:** you trade a hosted, LLM-required service fora self-contained binary that runs zero-LLM by default and keeps memory in- files you own. You give up (for now) their VLM-driven extraction depth and- their published headline accuracy numbers; you gain no vendor lock-in, no- required API spend, and per-project team sharing rather than strict per-bank- isolation.+ files you own. The consolidation shape you came for is here on 2.4 — a+ belief-strength `confidence` over evidence and an idle-scheduled,+ cancel-on-activity, surprisal-first LLM "dream" rewrite of cold clusters —+ but as **opt-in layers that never delete a source** (the pre-merge versions+ stay reachable) and are **off by default and gated on a recall eval before+ default-on**, over a zero-LLM core, rather than a mandatory loop. OpenViking's+ L0/L1/L2 progressive tiers map onto ai-memory's extractive tier-down+ (abstract + summary + keep-tokens). You give up (for now) their VLM-driven+ extraction depth and their published headline accuracy numbers; you gain no+ vendor lock-in, no required API spend, and per-project team sharing rather+ than strict per-bank isolation.## Where we're behind, or different by choice@@ -170,6 +220,14 @@ Fair means saying this plainly:default, and its end-to-end QA-accuracy is early and small-sample (see[`benchmarks/retrieval-ab-r2.md`](benchmarks/retrieval-ab-r2.md)), not aheadline claim.+- **Belief-strength and the dream pass ship, but off — no proven win yet.**+ The 2.4 memory-aging set includes the two pieces that could move retrieval+ *quality* — folding belief-strength `confidence` into ranking authority, and+ the LLM "dream" rewrite of cold clusters — but both are **off by default and+ gated on a recall eval (R2) that has not been run**. We claim parity of+ *mechanism* with Hindsight/mcp-memory-service here, not a measured recall or+ QA improvement; until R2 shows a positive delta the honest statement is+ "shipped, opt-in, unproven," and the default path is unchanged.- **Headline benchmark comparability.** Hindsight quotes 91.4% *accuracy* andOpenViking quotes LoCoMo lifts — different datasets/metrics than our hit@5,and both are self-reported/preprint. We publish a reproducible harness and adiff --git a/docs/competitive-parity.md b/docs/competitive-parity.mdindex f9a85b93..1f1c559a 100644--- a/docs/competitive-parity.md+++ b/docs/competitive-parity.md@@ -48,11 +48,11 @@ None of the competitors below has more than one or two of these; none has all.| From | Migrate to ai-memory? | You gain | You give up ||---|---|---|---|-| **mcp-memory-service** (fact-row twin) | **Yes** if you liked hook capture + typed edges + honest numbers | Files-as-truth (not opaque fact rows), handoffs, cross-project messaging, `as_of` temporal, a marginally better + reproducible number | Belief-strength + clustering consolidation, cloud/multi-backend replication (Cloudflare/Milvus), graph viz |+| **mcp-memory-service** (fact-row twin) | **Yes** if you liked hook capture + typed edges + honest numbers | Files-as-truth (not opaque fact rows), handoffs, cross-project messaging, `as_of` temporal, a marginally better + reproducible number, and — new on 2.4 — its aging set at parity done zero-LLM/reversible/off-by-default (per-tier decay curves, extractive compression, DBSCAN cold-cluster dedup, access boosts, 0.4–0.75-band contradiction flagging) | Cloud/multi-backend replication (Cloudflare/Milvus), graph viz. (Belief-strength + clustering consolidation are no longer a give-up — ai-memory now ships both, clustering as a zero-LLM default-off pass, belief-strength off/R2-gated) || **basic-memory** (file-first sibling) | **Yes** for multi-harness coding continuity; **no** for a personal Obsidian KB with live team co-edit | Ambient capture (no `write_note` ceremony), full lifecycle, handoffs/messaging, git-versioned truth, published numbers | Local zero-cost reranking, real-time collaborative editing, Postgres backend, `build_context` graph-walk, hosted mobile/web UX || **agentmemory** (ideological sibling) | **Yes** for operability + data ownership | Self-contained binary (no `iii-engine` sidecar), files-as-truth, SQL indexes committed in-txn, typed handoffs, Windows parity, fuller auth | ~13 pts raw R@5 (they rerank), a P2P mesh-sync primitive, ~31 tools of (mostly speculative) surface || **Claude Code built-in memory** | **Yes** for teams / multi-machine / multi-harness; **not obviously** for a solo dev on one machine in Claude only | Cross-machine, cross-harness, team sharing, tool-lifecycle capture, real search | Zero setup — it's already on with no server to run (our one honest structural disadvantage for the solo case) |-| **Hindsight** (pages-over-facts) | **Yes** for self-hosted/offline/team; **no** if you need their published accuracy + are fine with an LLM-required cloud | Zero-LLM, files you own, one binary, in-project team sharing (vs strict per-bank isolation) | Their published headline accuracy, VLM/LLM extraction depth, belief-strength that actually moves ranking |+| **Hindsight** (pages-over-facts) | **Yes** for self-hosted/offline/team; **no** if you need their published accuracy + are fine with an LLM-required cloud | Zero-LLM, files you own, one binary, in-project team sharing (vs strict per-bank isolation), and — new on 2.4 — a belief-strength `confidence` + an opt-in "dream" rewrite that borrow their model but never delete a source and keep the zero-LLM default | Their published headline accuracy, VLM/LLM extraction depth, and belief-strength that *actually moves ranking by default* (ours ships but is off/R2-gated until an eval proves it) || **Zep/Graphiti** (temporal KG) | **Yes** for self-hosting coders avoiding Neo4j+LLM (Community Edition is discontinued); **no** for enterprise graph-query/world-time | One binary on SQLite, zero-LLM, files, coding-harness native, a supported self-host | True bi-temporal (world vs observed time), Cypher/BFS graph queries, custom entity/edge types, `minRating` || **Mem0** | **Mostly no — different buyer** (app end-user personalization). Yes only if you (mis)used it as coding-session memory | Zero-LLM, per-repo, cross-harness, editable pages, no API spend | Mem0's SDK/integration ecosystem + managed cloud personalization || **Letta / MemOS** | **No** if you're building your agent *on* Letta; **yes** if you only wanted your existing coding agent to remember | Additive memory under your existing harness, zero-LLM, no runtime adoption | The ADE + agent-framework machinery (which you don't need unless building on Letta) |@@ -81,12 +81,19 @@ until the eval harness (R2) that would justify activating them gets built.| Local embeddings (all-MiniLM-L6-v2) | mcp-memory-service | **BETTER** | Pure-Rust candle (no ONNX/C++ per target), checksum-pinned, default-on with background backfill || Hook capture | mcp-memory-service | **BETTER** | 20+ harnesses + typed sanitizer boundary + backpressure vs Claude-Code-centric || Versioned supersession | agentmemory | **BETTER** | A concurrent divergent write supersedes but the loser stays reachable (invariant #16); theirs flips `isLatest` |-| Retention-as-formula (decay) | agentmemory | **BETTER** | Real SQL decay math vs in-memory O(N²) Jaccard capped at 1000 rows |+| Retention-as-formula (decay) | agentmemory | **BETTER** | Real SQL decay math vs in-memory O(N²) Jaccard capped at 1000 rows; 2.4 adds opt-in per-tier half-life curves (identity default) |+| Per-tier retention curves (365/180/90/30) | mcp-memory-service | **SHIPPED (parity), better default** | `[decay.half_life_days]` per tier (2.4, #807); their shape, but the omitted-key default is byte-identical to the old single-λ — no upgrade mass-evicts |+| Extractive, zero-LLM compression | agentmemory / mcp-memory-service | **BETTER** | 2.4 tier-down (#808) keeps abstract+summary+regex keep-tokens and drops prose, but is **reversible** (git + supersession chain, `restore-page`) and off by default, not a lossy in-place rewrite |+| Cold-cluster dedup (DBSCAN, adaptive-eps) | mcp-memory-service | **SHIPPED (parity), better safety** | 2.4 (#812) over the bounded cold set (no O(N²)); collapses by **supersede-not-delete** (invariant #16), conservative eps ceiling, zero-LLM, off by default |+| Access-weighted retention (access boost) | mcp-memory-service | **SHIPPED (parity+), closed a real gap** | 2.4 (#798) wired reinforcement into `read_page`, the related-walk, and `explore` — every read path, not just search; throttled/async/FTS-exempt |+| Contradiction detection (0.4–0.75 band) | mcp-memory-service | **SHIPPED (parity), advisory-only** | 2.4 (#814) surfaces likely conflicts in `memory_lint` from existing embeddings; zero-LLM, never edits/deletes/persists an edge |+| Surprisal-first + idle/cancel dream scheduling | Honcho (Dreamer) / Supermemory | **SHIPPED (parity), opt-in** | 2.4 (#816) idle-scheduled, cancels on activity, orders most-novel-first; off by default, observable `DreamReport` per run || Git-as-snapshot | agentmemory | **BETTER** | The wiki files *are* the truth (diffable), not a `state.json` dump || Pages-over-facts / living pages | Hindsight | **PARITY** (native) | Same architecture, file-first vs their Postgres-first; `settled_first` briefing shipped || Cross-session experience/abstraction pass | Letta/Hindsight/surveys | **REAL, ~parity** | ≥2-session evidence guard is the genuine article — but LLM-required and **off by default** || Typed relation edges | graph camp | **PARTLY SHIPPED** | Link-neighbours are now a first-class retrieval surface — `memory_read_page include_related` walks the `page_links` graph outward (bounded BFS, #775) — but retrieval **RANK weighting by edge type is still not done** (edge kind stays explain-only in `memory_query`) |-| Belief-strength consolidation | Hindsight / mcp-memory-service | **BEHIND** | `page_evidence` substrate shipped but **ranking-inert**; we still correct via binary supersession, not evidence-weighted belief |+| Belief-strength consolidation | Hindsight / mcp-memory-service | **SHIPPED, off by default (parity of mechanism, unproven)** | 2.4 (#815) computes a read-time, zero-LLM `confidence` over `page_evidence` (distinct-session breadth, recency, live `contradicts`, capped `[0,0.95]`), exposed inertly in `explain`/`status`; foldable into ranking authority behind a **default-0.0, R2-gated** weight. Our improvement over Hindsight's documented **entrenchment** failure: breadth-not-raw-count weighting, recency shading, a confidence cap, and **supersession always wins** regardless of evidence. Not yet default-on — no R2 delta run |+| LLM merge/rewrite "dream" pass | Hindsight (Dreamer) / Supermemory ("dreaming") | **SHIPPED, opt-in/off (parity of mechanism, unproven)** | 2.4 (#816) rewrites cold clusters into one page via the gated `apply_batch` path, `dry_run` first, JSON-schema output; **never deletes a source** (superseded with a merge-note stub, `restore-page` recovers), off by default, provider-less stores keep the zero-LLM A3 path. Off until an R2 quality delta is shown || bi-temporal-lite | Zep/Graphiti | **BEHIND by design** | Ingestion-time only; world-time validity deferred (honestly, because dating facts needs an LLM and breaks the zero-LLM path) |## Honest gaps (consolidated) and recommended adjustments@@ -108,12 +115,18 @@ implemented without a separate decision.** Ordered by leverage.our headline — has *no* reranking, while basic-memory ships a local one andagentmemory/Hindsight's score lead is largely reranking (0.823 vs 0.952 samedataset). Closes a gap on our own keyless turf. Gate on R2.-3. **Activate the dormant substrate (once R2 exists):** wire `page_evidence`- confidence into `PageAuthority` (clamped) — belief-strength; and add typed-edge- rank weighting + a `contradicts` authority cap — turning typed edges from- explain-only into a retriever. Both are designed in- [`design-hindsight-borrowings.md`](design-hindsight-borrowings.md); both are- inert today.+3. **Activate the dormant substrate — belief-strength now wired, off by+ default (2.4, #815).** `page_evidence` confidence is now computed at read+ time (zero-LLM) and can be folded into `PageAuthority` behind a clamped,+ **default-0.0** `[retrieval] belief_authority_weight` — the design in+ [`design-hindsight-borrowings.md`](design-hindsight-borrowings.md) §3, with+ the anti-entrenchment guards baked in. It is exposed inertly in+ `memory_query explain` and `memory_status` today; **it does not move ranking+ until an operator sets the weight, and turning it on is gated on a positive+ R2 delta that has not been run.** Still genuinely behind: **typed-edge rank+ weighting** (edge kind stays explain-only) and a `contradicts` *authority*+ cap — A5 (#814) surfaces contradictions in `memory_lint` but does not yet+ feed rank.4. **Sharpen the cross-machine story.** `comparison.md`'s "cross-machine *byconstruction*" is overstated — it's one shared server + manual git/rsync, with**no automatic replication** (agentmemory ships a P2P primitive; mcp-memory-@@ -142,10 +155,17 @@ implemented without a separate decision.** Ordered by leverage.retrieval knob** shipped as `memory_query include_superseded=true` (#773) overour supersession chains. All five are strictly opt-in LLM/retrieval layers*over* the zero-LLM FTS/RRF core, never a requirement (invariant #13).+ The **memory-aging** set (A1–A5, B1–B4, C1) landed on 2.4 as well —+ per-tier decay curves, extractive tier-down, DBSCAN cold-cluster dedup,+ the contradiction band, access reinforcement on all read paths,+ belief-strength confidence, and the LLM dream pass — audited row-by-row in+ the borrowed-ideas table above; the design of record is+ [`design-memory-aging.md`](design-memory-aging.md).**Still unshipped:** MCP tool behavior hints- (readOnly/destructive/idempotent) on the 23-tool surface; a clustering/dedup- consolidation pass (mcp-memory-service's DBSCAN); a read-only graph- visualization in `/web`; a first-class TS SDK story for ecosystem parity.+ (readOnly/destructive/idempotent) on the 23-tool surface; typed-edge **rank**+ weighting and a `contradicts` authority cap (A5 flags, it doesn't yet rank);+ a read-only graph visualization in `/web`; a first-class TS SDK story for+ ecosystem parity.Deliberately out of scope: Honcho's theory-of-mind user-modeling engine andLiquidLM's opaque-cloud / LLM-mandatory / multimodal-second-brain substrate(all off-mission for file-first, zero-LLM coding memory; the global-scope@@ -163,17 +183,27 @@ implemented without a separate decision.** Ordered by leverage.cross-harness capture, claim-once handoffs + messaging, and multi-usershared-within-project. On operability, data ownership, and cross-agent/teamcontinuity, ai-memory is genuinely ahead of every overlapping competitor.-- **The borrowed conveniences now ship (opt-in).** The 2.4 line landed the five- competitor-specific closes above — related-walk, dialectic answer, reasoning- tier, pin-before-search, and the show-superseded knob — each opt-in with- defaults byte-identical, and the R2 harness that gates the quality work now- exists and measures the accuracy+latency+context-tokens triple plus end-to-end+- **The borrowed conveniences now ship (opt-in), and so does the aging set.**+ The 2.4 line landed the five competitor-specific closes above — related-walk,+ dialectic answer, reasoning tier, pin-before-search, and the show-superseded+ knob — plus the memory-aging program (per-tier decay curves, extractive+ tier-down, DBSCAN cold-cluster dedup, contradiction flagging,+ access-weighted retention, belief-strength confidence, and the LLM "dream"+ pass), each opt-in with defaults byte-identical. Our consistent improvements+ over the sources borrowed from (mcp-memory-service, agentmemory, Honcho,+ Hindsight, LiquidLM): **zero-LLM by default**, **reversible** (supersede-not-+ delete + `restore-page`, never a lossy in-place rewrite or a deleted source),+ **file-first**, and **R2/opt-in discipline** on anything that touches ranking+ or calls an LLM. The R2 harness that gates the quality work now exists and+ measures the accuracy+latency+context-tokens triple plus end-to-endQA-accuracy (illustrative sample-20 only so far).- **The honest weakness is still retrieval quality**, and it remains*self-inflicted by discipline, not by copying*: no local zero-LLM reranker- exists, belief-strength (`page_evidence`) and typed-edge **RANK** weighting are- built but still switched off, and the published *full-dataset* triple is still- pending (only illustrative sample-20 numbers so far). The gate (R2) is now+ exists, belief-strength (`page_evidence`) is now wired but **default-off**,+ typed-edge **RANK** weighting is still not built, and the published+ *full-dataset* triple is still pending (only illustrative sample-20 numbers so+ far). No R2 delta has been run, so nothing quality-affecting defaults on. The+ gate (R2) is nowopen — **activate what's already there against a full-500 run.**- **Migration answer:** for the self-hosted, multi-harness, team, zero-LLM,own-your-data coding-memory user, yes — we do the basics and add what theydiff --git a/docs/cookbook.md b/docs/cookbook.mdindex c32f086e..cedfb41e 100644--- a/docs/cookbook.md+++ b/docs/cookbook.md@@ -77,6 +77,40 @@ Once the material is saved as pages in the right scope, any project can searchit (`memory_query`) and read a specific document in full (`memory_read_page`)before implementing against it.+## Recipe: control what gets kept, aged, or consolidated++By default nothing you have to think about: memory decays on a single gentle+curve, and an upgrade to 2.4 changes no scores and evicts nothing. When you *do*+want to tune aging, it is all opt-in and reversible — the original of anything+compacted or merged stays in git and the supersession chain, recoverable with+`ai-memory restore-page`.++- **Keep something forever:** pin it. A pinned page is exempt from the+ forget-sweep regardless of tier or age. Semantic and procedural pages never+ decay either — only working/episodic memory ages.+- **Make a note expire on a deadline:** ask your agent to remember it "until+ <date>" (an `expires_at`); the forget-sweep deletes it when the time passes,+ no matter how often it was read. A TTL outranks pinning.+- **Tune how long each tier lasts:** set per-tier half-lives in the project's+ `.ai-memory.toml` `[decay.half_life_days]` (e.g. keep episodic history longer,+ working-tier scratch shorter). Omit it for the default single curve.+- **Compact instead of evict, and de-duplicate:** `[decay] compact_cold_episodic`+ keeps a cold page's durable facts (paths, error codes, decisions) and drops the+ prose; `[decay] dedup_cold_clusters` collapses near-duplicate cold pages into+ one survivor. Both are zero-LLM, off by default, and supersede rather than+ delete.+- **Keep used memory longer:** nothing to configure — a page you open, search,+ or reach through a related-pages walk is reinforced automatically and resists+ decay.+- **Surface likely contradictions:** run `memory_lint` (through your agent or the+ CLI); with embeddings configured it flags pairs of same-topic pages that look+ like they conflict, advisory only.+- **Let an LLM consolidate on idle ("dream"):** with a provider *and* an embedder+ configured, `[dream] enabled` turns on a background pass that rewrites clusters+ of cold notes into single coherent pages while you're idle and cancels the+ moment you return. It is off by default, never deletes a source, and is gated on+ an internal recall eval before it could ever become default behavior.+## Recipe: two agents / two repos working together- **Continuity across agents in the same project** (quit Claude Code, open Codexdiff --git a/docs/research-2026-landscape.md b/docs/research-2026-landscape.mdindex ec48e573..88f90f8b 100644--- a/docs/research-2026-landscape.md+++ b/docs/research-2026-landscape.md@@ -96,7 +96,18 @@ tracker repeats patterns from our own history - v11.10.0 fixedconsolidation time horizons that *silently ignored their configuredwindow*, the same class of quiet-lifecycle bug our `#526`/`#528` workaddressed with observable outcomes. Published honest numbers: 80.4% R@5-on LongMemEval turn-level, 86.0% session-level.+on LongMemEval turn-level, 86.0% session-level. **Where we now stand+(2.4):** its consolidation set — type-dependent TTL (365/180/90/30),+extractive compression, DBSCAN adaptive-eps clustering, access/connection+boosts, and 0.4–0.75-band contradiction detection — is the direct+grounding for the 2.4 memory-aging program+([`design-memory-aging.md`](design-memory-aging.md)), which now ships each+at parity but **zero-LLM by default, reversible** (supersede-not-delete ++`restore-page`), and **off by default** (per-tier `[decay.half_life_days]`,+extractive tier-down, cold-cluster dedup, access reinforcement on all read+paths, and a `memory_lint` contradiction finding). The difference is+posture, not mechanism: theirs runs autonomously; ours preserves the+zero-LLM default path and evicts nothing on upgrade.**Platform development: Claude Code native "auto memory"** shippeddefault-on (v2.1.59): the agent keeps its own `MEMORY.md` plus topic@@ -137,8 +148,23 @@ are Virginia Tech Sanghani faculty; the Post is a named collaborator), itis a preprint, and it reports accuracy rather than the R@5 others quote -still the most credible benchmark claim here (a paper with per-categorysub-scores, gains concentrated where structured temporal memory should-help), and a reminder the serious players now publish numbers. Full-analysis in [`research-hindsight.md`](research-hindsight.md).+help), and a reminder the serious players now publish numbers. **Where we+now stand (2.4):** the two ideas flagged to carry forward — belief-strength+over binary supersession, and the background rewrite loop — now ship, as+opt-in layers over the zero-LLM core, per+[`design-hindsight-borrowings.md`](design-hindsight-borrowings.md) §3 and+[`design-memory-aging.md`](design-memory-aging.md) B1–B4. Belief-strength is+a read-time, zero-LLM `confidence` (distinct-session breadth + recency ++live `contradicts`, capped) exposed inertly in `explain`/`status` and+foldable into ranking behind a **default-0.0, R2-gated** weight; the+"dream" pass is an idle-scheduled, cancel-on-activity, surprisal-first LLM+rewrite of cold clusters that is **off by default and never deletes a+source**. We designed *against* Hindsight's own documented failure —+belief *entrenchment* (raw proof-count pins a wrong page) — with+breadth-not-count weighting, a confidence cap, and supersession always+winning over evidence. Honest caveat: no R2 delta has been run, so this is+parity of *mechanism*, not a measured accuracy win. Full analysis in+[`research-hindsight.md`](research-hindsight.md).**Biggest-backed new entrant: `volcengine/OpenViking`** (~37.5K stars,ByteDance/Volcano-Engine, AGPLv3 core + Apache-2.0 CLI/examples, three@@ -157,7 +183,11 @@ at **L0 (one-sentence abstract, for relevance checks)**, **L1 (overview, forplanning)**, or **L2 (full original, read only when needed)** — the reported34-91% input-token reduction (LoCoMo) is almost entirely this deferral, andit maps directly onto work we already have (V61 abstract embeddings, the-session brief) rather than a new architecture. Second, **directory-scoped+session brief) rather than a new architecture — and 2.4's **extractive+tier-down** (A2, [`design-memory-aging.md`](design-memory-aging.md)) now+persists exactly this shape for cold episodic pages: an L0 abstract, an L1+summary, and an L2 keep-token set, with the full prose one supersession-+restore away. Second, **directory-scopedretrieval** (a "TrieHI" prefix-tree vector index that narrows a query to apath subtree before ranking) — a cheaper cousin of our per-project scoping,one level down at the `_rules/` / `norms/` path prefix. Read the numbers@@ -274,7 +304,13 @@ carrying forward as *optional LLM layers over* our zero-LLM core, neverrequirements: the **dialectic/oracle query** (ask-a-question → synthesizedanswer, which maps onto our retrieval as an opt-in LLM step) and the**reasoning-tier ladder** (minimal→max reasoning per query as a clean-cost/quality knob). Deliberately **reject** the rest as off-mission: LLM-mandatory+cost/quality knob). **Both now ship on 2.4** as opt-in, off-by-default LLM+layers (`memory_query answer=true` #782; `reasoning: {minimal..max}` #783),+and the Dreamer's *scheduling shape* — surprisal-first ordering, idle+trigger, cancel-on-activity — is the grounding for 2.4's opt-in "dream"+consolidation pass (#816, [`design-memory-aging.md`](design-memory-aging.md)+B3/B4), which stays off by default and never deletes a source. Deliberately+**reject** the rest as off-mission: LLM-mandatoryingestion, opaque-Postgres-as-truth, the Postgres+Redis+worker operationalweight, and the heavy theory-of-mind engine itself — a coding agent needs projectfacts, decisions, and conventions, not a psychological model of the developer@@ -401,7 +437,12 @@ ships a *paper* with per-category LongMemEval sub-scores (91.4%), so thebar is no longer "publish a number" but "publish a harness and a metricsomeone else can re-run" - fix the split and the metric (theirs isaccuracy, agentmemory/mcp-memory-service quote R@5; pick one and state-it) so our result is comparable, not just present.+it) so our result is comparable, not just present. **Now load-bearing on+2.4:** the two aging features that can move quality — belief-strength folded+into ranking (#815) and the LLM "dream" pass (#816) — ship **off by default+and gated on this harness before they may default on**; no R2 delta has been+run yet, so both remain opt-in and unproven (see+[`design-memory-aging.md`](design-memory-aging.md) R2 acceptance).**R3 - Typed relation edges (small-medium).** `causes` / `fixes` /`contradicts` on our existing `links`/`entities` model, from the@@ -449,7 +490,12 @@ storage: reuse the abstract already embedded at V61. Worth a design docthat decides where the L1 overview comes from (frontmatter summary,first-paragraph extraction, or the existing abstract) before any code;it composes with R5 (the cross-session abstraction pass produces good-L1 summaries) rather than competing with it. Directory-scoped retrieval+L1 summaries) rather than competing with it. **Partly realized on 2.4:**+extractive tier-down (A2, #808) already persists the L0 abstract + L1+summary + L2 keep-token shape for cold episodic pages+([`design-memory-aging.md`](design-memory-aging.md)); the remaining R7 work+is the *tiered on-start brief* that leads with abstracts, still a design+doc before code. Directory-scoped retrieval(OpenViking's TrieHI) is the lower-priority half — a path-prefix filteron `memory_query` within a project — worth noting but not schedulinguntil R7's tiering lands.@@ -561,3 +607,11 @@ benchmark number before R2 exists; chasing agentmemory's tool-count- Landscape comparisons: cognee.ai, vectorize.io, atlan.com,particula.tech, mnemoverse.com 2026 roundups (read as marketing;cross-checked against the projects' own repos where load-bearing).+- In-repo design of record for the 2.4 memory-aging borrowings (per-tier+ decay, extractive tier-down, cold-cluster dedup, contradiction band,+ belief-strength, the dream pass, access-weighting):+ [`design-memory-aging.md`](design-memory-aging.md) (with a sourced+ competitor-grounding table) and+ [`design-hindsight-borrowings.md`](design-hindsight-borrowings.md) §3+ (belief-strength). Migration verdicts:+ [`competitive-parity.md`](competitive-parity.md).