What an agent memory database must do
An agent memory database is not simply a table of messages or a vector index of chunks. It must preserve what happened, derive useful entities and claims, track how those claims change, retrieve a bounded context set, and explain the evidence used to assemble it.
For a production system, memory spans six responsibilities: source capture, extraction, entity resolution, temporal interpretation, retrieval, and context assembly. A database can expose lower-level primitives for teams that want to own extraction while still keeping source, time, and relationships authoritative.
Model episodes, facts, entities, and sources separately
An episode is an observation: a message, tool result, document, transaction, or application event. A fact is a claim derived from one or more episodes. An entity represents an identity that can accumulate aliases and relationships. A source explains where the episode or claim originated.
Keeping these concepts separate prevents a later correction from rewriting the original record. The current interpretation can point to a superseding fact while the system retains the earlier claim and its evidence for historical and audit queries.
- Episode: immutable source event and recorded time.
- Fact: claim, confidence, valid interval, and extraction version.
- Entity: canonical identity, aliases, identifiers, and merge history.
- Relationship: typed connection, potentially higher-order or temporal.
- Provenance: source episode, actor, request, model, and policy context.
Use both recorded time and valid time
Recorded time answers when the database learned something. Valid time answers when the claim applies in the world. They are not interchangeable. A customer can tell an agent in June that a role changed in April; the recorded time is June while the valid start is April.
A useful context API should support current truth, valid-at queries, and recorded-as-of queries. It should also expose whether an item is active, superseded, retracted, contradicted, or unresolved.
“What was believed on March 1?” and “What was actually true on March 1?” are different questions.
Fuse retrieval signals and expose freshness
Semantic similarity works well for paraphrases but can miss exact identifiers, dates, and structured relationships. Lexical search helps exact text. Graph traversal recovers related evidence. Temporal filtering decides whether the result applies. Authorization limits the candidate set.
A hybrid pipeline generates candidates from each signal, applies tenant and temporal filters, fuses and reranks candidates, deduplicates evidence, then selects a context set under a token budget. Each result should identify the contributing signals and its source.
Derived search indexes are often asynchronous. To preserve immediate post-write behavior, query the authoritative recent-write window alongside lexical and vector indexes until their watermarks pass the write bookmark.
Evaluate the complete memory loop
Retrieval accuracy alone can hide token bloat, stale indexes, entity fragmentation, or incorrect temporal answers. A credible evaluation measures recall, precision, ranking, current truth, as-of truth, entity resolution, write-to-query latency, context tokens, end-to-end answer quality, cost, and attribution.
Publish model versions, prompts, top-k values, source data, indexing freshness, and code revision. Benchmark the same workload against simple baselines—including files, SQL, and vector-only retrieval—so the graph and temporal complexity must earn its place.