Skip to content

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.md
index 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 no
API 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 write
ceiling (~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-LLM
default**, **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.md
index 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 than
just cataloguing them: typed relation edges, ingestion-time temporal validity
with `as_of` queries, local (no-key) embeddings as the default, and the
cross-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 a
first-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 cloud
vault and a managed multimodal RAG service for a self-contained binary whose
memory 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 for
a 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 a
headline 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* and
OpenViking quotes LoCoMo lifts — different datasets/metrics than our hit@5,
and both are self-reported/preprint. We publish a reproducible harness and a
diff --git a/docs/competitive-parity.md b/docs/competitive-parity.md
index 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 and
agentmemory/Hindsight's score lead is largely reranking (0.823 vs 0.952 same
dataset). 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 *by
construction*" 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) over
our 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 and
LiquidLM'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-user
shared-within-project. On operability, data ownership, and cross-agent/team
continuity, 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-end
QA-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 now
open — **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 they
diff --git a/docs/cookbook.md b/docs/cookbook.md
index 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 search
it (`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 Codex
diff --git a/docs/research-2026-landscape.md b/docs/research-2026-landscape.md
index 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 fixed
consolidation time horizons that *silently ignored their configured
window*, the same class of quiet-lifecycle bug our `#526`/`#528` work
addressed 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"** shipped
default-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), it
is a preprint, and it reports accuracy rather than the R@5 others quote -
still the most credible benchmark claim here (a paper with per-category
sub-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, for
planning)**, or **L2 (full original, read only when needed)** — the reported
34-91% input-token reduction (LoCoMo) is almost entirely this deferral, and
it 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-scoped
retrieval** (a "TrieHI" prefix-tree vector index that narrows a query to a
path 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, never
requirements: the **dialectic/oracle query** (ask-a-question → synthesized
answer, 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-mandatory
ingestion, opaque-Postgres-as-truth, the Postgres+Redis+worker operational
weight, and the heavy theory-of-mind engine itself — a coding agent needs project
facts, 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 the
bar is no longer "publish a number" but "publish a harness and a metric
someone else can re-run" - fix the split and the metric (theirs is
accuracy, 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 doc
that 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 filter
on `memory_query` within a project — worth noting but not scheduling
until 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).