Expand description
Memory an agent keeps between runs, and the rules that keep it survivable.
§Writable memory is delayed code
A vector store bolted onto an agent looks like a cache and behaves like a program. Whatever is written today is read back tomorrow into a context window, where a model treats it as established fact — so a single poisoned write becomes a standing instruction that fires on every later session. The literature calls this the attack that waits, and its distinguishing property is that nothing at read time looks wrong.
Three rules follow, and none of them is about the storage engine.
§Trust comes from provenance, never from content
A recalled item is labelled by where it came from, not by what it says. Content-inferred trust is adversarially gameable by construction: text that asserts its own reliability is the cheapest thing an attacker can write.
So MemoryItem carries its sources, and StepCtx::recall hands back a
Tainted value whose label is the join of them. An item written from a
model’s output is untrusted forever, however many times it is re-read, and
reaching a mutating sink with it takes the same journaled release as any
other untrusted value.
§Retrieval is an effect, not a lookup
Memory is mutable state outside the journal, so reading it from inside the deterministic zone would make replay depend on what the store happens to hold now. A run replayed after a later write would retrieve different items, reach different conclusions, and produce a history that disagrees with itself — the exact failure the effect protocol exists to prevent.
So a recall is journaled: the query, the filters, and the selection — item ids with their exact versions and content digests. Replay reads that record and re-materialises those versions rather than re-running the search, so the ranking is not re-computed and cannot drift with the corpus.
§Content is versioned and supersedable, never edited in place
A memory that can be rewritten in place cannot be audited, and cannot be repaired: there is no way to ask what the agent believed last Tuesday, and no way to undo one bad write without guessing what it replaced. Writes append a new version and mark the old version’s lifecycle metadata superseded. Its content and security metadata remain unchanged, forgetting is selective, and lineage survives correction so a later erasure can still traverse it.
Structs§
- Compaction
- Where a summary should land.
- Formation
- Governed model-assisted formation of durable memories.
- InMemory
Semantic Retriever - Deterministic exact cosine retriever for tests and small corpora.
- Memory
Item - One remembered thing.
- Memory
Write - Where a runtime memory write lands.
- Recall
- What to recall.
- Selected
- One selected memory, as the journal records it.
- Semantic
Hit - One ranked semantic selection as journaled.
- Semantic
Query - A semantic query whose exact vector and index identity are journalable.
- Semantic
Vector - One immutable vector record for
InMemorySemanticRetriever.
Enums§
- Memory
Error - Why a memory operation could not be completed.
Traits§
- Embedder
- Turns text into a vector.
- Memory
Store - Where memories live.
- Semantic
Retriever - Derived semantic index, never durable memory truth.