Durable memory
A fact told on Monday is still true on Friday.
An assistant that forgets everything the moment a conversation ends is a search box with better manners. This is where what it learns goes, so it can be corrected when it stops being true and shown to the person it is about.
kind episode | fact | procedure | summary
scope account | profile | session
trust stated | observed | inferred | untrusted
# "Actually, I moved in March"
a new memory is written; the old one is closed with
valid_to and superseded_by_id, never deleted
untrusted is never retrieved until somebody confirms itHow it works
Memory is not a list.
It authenticates against keyring, and every query carries a mandatory account predicate taken from the verified token.
A remembered claim
Who asserted it, where it came from, how confident the writer was, when it was true, and whether it has since been corrected.
Topics, and an index
Memories cluster into named topics. What an assistant carries every turn is the topic index, and it expands one topic only when it needs it: forty lines instead of four hundred.
Retrieval that ages honestly
Ranking combines relevance, recency and importance, normalised before they are combined. Recency decays from last access, not creation, so a stable fact does not look old.
The API
The operations, by what they are for.
The reference, with every field and filter, is docs/api.md.
Write
One memory, with its kind, scope, trust, source and validity. POST /v1/memory/batch reconciles several.
The topic index
Titles, one-line summaries, counts and last-touched times. GET /v1/memory/topics/{topic_id} expands one.
Corrections
A correction supersedes; it never deletes and re-adds, which would throw away that the old claim used to be true.
Trust
A person vouches for an untrusted memory, and only then may retrieval use it.
Forgetting
Hidden at once, erased after a grace period by a sweeper, and restorable until then.
Pinned blocks
The small blocks that travel with every turn.
- Install.
make install - Run the gate.
make check - Serve it on :8009; the interactive docs are at
/docs.make run
Every setting is in docs/operations.md.
The lines it does not cross
The lines this service does not cross.
Can a memory tell the assistant what to do?
No. Anything an assistant read on a page can end up in a memory, and a memory is permanent. Every memory is returned with its provenance, to be rendered as a reported claim. The API cannot enforce that; it makes the honest shape the easy one.
Is anything retrieved before a person has vouched for it?
Not if it is untrusted. A memory store is a prompt-injection persistence layer, so anything distilled from tool output or a page stays out of retrieval until it is confirmed. A topic made only of unconfirmed memories does not appear in the index either.
What if someone asks it to remember an API key?
The write is refused, with a message naming keyring, and the failure never echoes what was submitted.
Can an operator read somebody's memories?
There is no admin API and no endpoint that reads memories on somebody's behalf. Isolation comes from storage, not from prompting.
Docs
Written for the person who has to run it.
The HTTP contract
Every operation, field and filter.
Architecture
Topics, clustering, and the two views of the same rows.
Operations
Every setting, the sweeper and the grace period.
Assistant tools
How a memory is rendered to a model.
Testing
What is tested against real storage, and why.
Changelog
What changed, and why it was wrong before.