How a record is organised
A memory's shape decides its behaviour: is it keyed for exact lookup, does a new value supersede the old, is it vector-indexed for semantic recall or kept lean as full-text only? A Task is ephemeral and stays out of the vector index; a Fact is keyed and supersedes. The schema is the contract between what a memory is and how it gets stored and retrieved.
| Schema | Organises | Keyed | Supersedes | Index | Persistence | src | |
|---|---|---|---|---|---|---|---|
| Fact | Atomic, stable knowledge ("uses GraphQL", "prefers dark mode") | yes | yes | Vector + FTS | Stable | ↗ | |
| Event | What happened at a specific time, a deployment, a decision | yes | yes | Vector + FTS | Time-anchored | ↗ | |
| Instruction / Procedure | How to do something, procedures, workflows, runbooks | yes | yes | Vector + FTS | Stable | ↗ | |
| Task | What is being worked on right now, ephemeral by design | no | no | FTS only (kept out of vector index) | Ephemeral | ↗ | |
| Entity / Profile | A synthesized per-user/entity document, patched over time | yes | yes | Vector | Patched | ↗ | |
| Relationship (triple) | A subject–predicate–object edge with a validity window | yes | yes | Graph | Bi-temporal | ↗ | |
| Summary | A rolling compaction of older history into a running digest | no | yes | Vector | Rolling | ↗ | |
| Message / Raw turn | Verbatim conversation turns, the unclassified safety net | no | no | FTS only | Append-only | ↗ |
Keyed, supersedes, indexed, persisted: the shape decides the behaviour
Schema decides what an agent can retrieve and how far it can trust it. Each row records what the shape organises, how it is keyed, whether it is anchored to a moment in time, and whether a newer record supersedes an older one. Those four properties do most of the work.
Show more
Time causes the most trouble. A point-in-time decision and a durable preference look alike going in and behave very differently coming out: one was true on a date, the other is true until changed. Confuse them and the agent either treats a one-off as a standing instruction or keeps asking for something it has already been told. Supersession is the other half of the same problem, since new information has to be able to displace what it contradicts rather than sit alongside it.
What is a memory schema?
The shape of a single stored memory: what fields it holds, how it is looked up, and how long it lives. A fact, an event, a task and a raw chat message all need different shapes. Choosing the wrong one is why some memories turn out to be impossible to retrieve later.
What fields does a memory record need?
At minimum the content itself, who or what it is about, when it was written, and where it came from. Most systems add a type, so the record goes to the right index, and a version or timestamp, so a newer value can replace an older one.
Should agent memory be one profile or a list of facts?
A profile is a single document per user that you keep patching. A list is separate facts appended over time. Profiles read cleanly and get harder to edit correctly as they grow; lists are trivial to add to and need a step that resolves contradictions. Most production systems use lists.
What does it mean for a memory to supersede another?
A newer value retires the older one instead of both sitting in the store. Without it, an agent that retrieves "prefers Postgres" and "prefers MySQL" has no way to tell which is current. Short-lived records like tasks and raw messages usually do not supersede; they are simply appended.
Which memories should be vector-indexed?
Only the ones you will look up by meaning: facts, events, instructions, summaries. Short-lived working state and raw message logs are normally kept out of the vector index so it stays small and precise. Relationships go in a graph instead, because the value there is in the links rather than the wording.