Product
How memory ages
Unused session pages lose retention weight and can be removed. Cold-page compaction, deduplication and the dream pass are off by default. With an LLM configured, a separate auto-improvement scheduler can edit the wiki automatically.
What ages and what stays
Only one of the four memory tiers decays. Pinned pages are exempt in all of them.
Working
Notes for the session in progress. They end with it.
Episodic
One page per session. This is the tier that ages: a page nobody reads goes cold within months.
Semantic
Decisions, concepts and gotchas. They do not decay.
Procedural
Rules, procedures and runbooks. They do not decay.
The path with no LLM
A scheduled sweep scores every unpinned episodic page. The score falls with age and rises each time the page is read.
Page read
reinforces
Retention score
Forget-sweep
Cold?
Cold?
Evict
Compact
One survivor
git history
restore-page
Evict
Compact
One survivor
The retention score
- With the defaults, a page loses half its score about every 35 days. Below 0.20 it counts as cold.
- Every read adds to the score, and the effect of old reads fades too.
StaleorWrongfeedback drops a page to the lowest salience.- The score decides what the sweep does. It never changes search ranking.
# All three are optional. Without them, cold pages are evicted on one shared curve.
[decay]
compact_cold_episodic = true
dedup_cold_clusters = true
[decay.half_life_days]
working = 7
episodic = 365
Always on
Reading keeps a page alive
Search hits, opening a page, reaching it through a link and
memory_exploreall count as reads. Reads only ever raise the score.Off by default
A half-life per tier
[decay.half_life_days]sets how fast each tier fades, such as a short life for scratch notes and a long one for session history. Leave it out and scores stay exactly as they were.Off by default
Compact a cold page
With
compact_cold_episodic, a cold page keeps its abstract, its first-paragraph summary and the tokens worth keeping (file paths, URLs, code spans, error codes and identifiers) and drops the prose. Without it, the page is evicted.Off by default
Merge near-duplicates
With
dedup_cold_clusters, cold pages that say almost the same thing are clustered by their embeddings. The one with the highest score survives and absorbs the others’ keep-tokens. The others are superseded and point to it.Off by default
Skip empty sessions
An entropy filter keeps near-empty or highly repetitive session pages out of the experience pass, before any LLM prompt is built.
Runs with memory_lint
Flag likely contradictions
memory_lintreports pairs of knowledge pages that cover the same topic without being duplicates, and says which one is newer. The report is advisory and edits no page.Always on
A confidence score per page
Each page gets a confidence between 0 and 0.95, from how many separate sessions support it, how recent the last one is, and how many pages contradict it. You see it in
explainoutput. It affects ranking only if you raisebelief_authority_weightabove 0.
The dream pass
Dedup keeps the facts of a cluster. The dream pass hands the same cluster to your LLM, which rewrites it as one coherent page. It runs while you are away and stops when you come back.
Opt-in
Idle 5 min
Cold clusters
Most novel first
LLM rewrite
LLM rewrite
One merged page
Sources superseded
Activity cancels
git history
It needs three things
[dream] enabled = true, an LLM provider and an embedder. Without a provider, the zero-LLM dedup keeps working as before.It waits for you to leave
A run starts after 300 seconds with no client activity. When you return, it cancels at the next cluster.
The most novel cluster goes first
Clusters farthest from anything the wiki already says are handled first. The ordering and the idle trigger follow Honcho’s Dreamer.
Sources are superseded
The highest-scoring page is rewritten. Each merged page becomes a stub that points to it, and the original text stays in the version chain and in git.
Every merge names its sources
Evidence rows record which pages fed each merge, so an invented detail can be traced. Output is schema-checked JSON, and each run leaves a report.
# Also needs an LLM provider and an embedder.
[dream]
enabled = true
idle_window_secs = 300
max_clusters_per_run = 8
What can be undone, and what cannot
Compaction, dedup and the dream pass rewrite through the wiki, so each change is a new version and a git commit.
Rewrites are reversible
ai-memory restore-pageandmemory_restore_pagerecover a page from a retained git checkpoint while its project exists. MCP checkpoint listing and restoration both require admin authority. Neither restores sessions, observations or handoffs stored only in the database.Review defaults before upgrading
Compaction, deduplication and the dream pass remain opt-in. Existing retention and expiry rules still apply. Take a full backup before an upgrade; automatic wiki migration archives do not replace your database backup.
Pin what must stay
Pinning protects a page from decay-based removal. Semantic and procedural pages do not decay. An explicit expiry date still allows deletion, even for a pinned page.
Optional ledger cleanup: [decay] ledger_retention_months = N deletes rotated hook logs after N whole UTC months following the end of their month. The default is 0 (off). It always keeps log.md, the current month and the previous month. Preview with a dry run; old git history and backups can retain copies.
More ways to query
Each one is an optional argument on an existing tool.
Answers with citations
memory_querywithanswer: truereturns a short answer and the page paths it came from. It needs an LLM provider and follows Honcho’s dialectic endpoint. Its quality has not been evaluated yet, so open the cited pages.Reasoning levels
A
reasoningargument, fromminimaltomax, sets the token budget for answers and formemory_explore.Pinned pages first
pin_firstputs up to ten pinned pages ahead of the search results, and the session briefing now lists them.Related pages
memory_read_pagewithinclude_relatedwalks links and backlinks up to three steps out.Older versions on request
include_supersededadds replaced versions to a search, each one labelled.Which project answered
memory_statusreports the workspace and project it resolved, and how it got there.
Questions and answers
Does ai-memory delete old memories?
Unpinned episodic session pages age. A cold page is evicted by default; its database tombstone can be removed after 180 days. Optional compaction or merging keeps shorter content. A page can still be recovered if a retained git checkpoint contains it and its project exists. Pinned, semantic and procedural pages do not decay, but an explicit expiry can still delete them.
Does memory aging need an LLM?
No. Scoring, per-tier half-lives, compaction, dedup, contradiction flags and the confidence score use no LLM. Dedup and contradiction flags read embeddings, which the default local embedder produces. Only the dream pass calls an LLM, and it is off by default.
What is the dream pass?
An opt-in background job. After five idle minutes it takes clusters of cold, near-duplicate pages and has your LLM rewrite each cluster into one page. The sources are superseded, and the run stops when you come back.
Will an upgrade change my existing memory?
Compaction, deduplication and the dream pass remain opt-in. Existing retention and expiry rules still apply. Take a full backup before an upgrade; automatic wiki migration archives do not replace your database backup.
Do these features improve retrieval scores?
Nobody has measured that yet. The project treats them as shipped, opt-in and unproven until its evaluation harness shows a gain.
Give your agents a memory today.
Free and open source under the MIT license. The default memory features need no model API key; your coding agent may require its own account.