Product
How memory ages
A project collects session pages for months, and most of them stop being useful. ai-memory scores each one, keeps what you still read, and can shrink or merge the rest. The default path calls no LLM, and every feature that rewrites a page is off until you turn it on.
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.
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.
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-pagebrings back the full page from the wiki’s git history.An upgrade changes nothing
Compaction, dedup and the dream pass are off by default. An upgrade changes no score and evicts nothing, and the server archives the data directory before it migrates.
Pin what must stay
A pinned page is never swept. Semantic and procedural pages do not decay.
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?
Only episodic session pages age. By default a cold one is evicted and removed for good after 180 days. You can have cold pages compacted or merged instead, and both can be restored. Pinned, semantic and procedural pages are kept.
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?
No. Compaction, dedup and the dream pass are off by default, so an upgrade changes no score and evicts nothing. The server archives the data directory before it migrates.
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. You need no account and no API key.