Agent Memory Architecture: Types, Schemas, and Data Flow
Design agent memory around explicit data contracts, retrieval, corrections, and application state. Use memory types to clarify decisions, not multiply services.
Agent memory architecture is the set of storage, retrieval, and update decisions that lets an application use earlier information in later work. It connects durable records to the agent's current context while preserving identity, provenance, and the distinction between a past observation and current truth.
The useful starting point is a data flow: what enters memory, how it becomes available, what qualifies it for retrieval, and what happens when it is corrected or removed. Use memory types to organize those decisions within the storage and services your workload needs.
Use memory types to describe the workload
| Type | Example | Design question |
|---|---|---|
| Working context | The open task and last tool result | What must the next model call see? |
| Episodic records | A customer asked to postpone a rollout | Can we recover the event, date, and source? |
| Semantic facts | The customer prefers email updates | What supports this fact, and is it still applicable? |
| Procedural knowledge | A repository's release checklist | Who can change the procedure, and how is it validated? |
These are useful descriptions, not a compulsory product checklist. A document assistant might need only source retrieval and a small task record. A support agent may need preferences, prior events, and live account data. A release agent needs versioned procedures whose authority is stronger than an incidental conversation suggestion.
Design the write path before the search index
For every candidate memory, establish its scope, source, intended lifetime, and how much confidence the application can place in it. An explicit preference is different from an inference based on one interaction. A request inside a quoted example is different from the user's instruction.
Consider “Use Python for this migration, but TypeScript remains our default.” Extracting only “prefers Python” changes the meaning. A useful representation keeps the project exception and the general default separately, each tied to the original message.
For example, your application can represent a scoped preference with this record:
{
"id": "decision-104",
"tenantId": "acme",
"subjectId": "migration-project",
"kind": "decision",
"statement": "Use Python for the migration worker",
"scope": "migration-project",
"sourceId": "meeting-37#turn-18",
"observedAt": "2026-09-10T15:00:00Z",
"status": "active",
"supersedes": null
}Your database can enforce required fields and permitted status values. The extraction model cannot grant permission to read a tenant or silently promote a project decision to a company policy. Those are application rules.
Separate the record from its representations
One source may produce searchable chunks, embeddings, a summary, and extracted facts. Give those derived records a path back to the source version. Otherwise, a deleted document can survive as an orphaned summary, or a corrected fact can remain in a cached profile.
Keep stable source identity separate from content identity. The same document can have multiple revisions; two documents can have identical text but different permissions. A content hash helps detect repeated content but is not a substitute for a source ID or an access policy.
This distinction also makes reprocessing safer. When an extraction prompt changes, you can identify the affected version, build new derived records, inspect them, and switch retrieval to the accepted representation.
Make retrieval a constrained selection step
A practical read path is:
- Authenticate the request and derive allowed scopes.
- Determine the question's entity, time frame, and task.
- Retrieve permitted candidates from the relevant sources.
- Resolve or expose version conflicts.
- Select a bounded evidence set and preserve its citations.
- Generate the answer with uncertainty visible where evidence is incomplete.
Similarity is one input to selection. It cannot by itself establish authorization, freshness, or whether a remembered preference overrides a current explicit request. Apply those requirements deliberately.
For a user's shipping address, a past conversation might explain an earlier issue, while the order system controls the current shipment. Returning both without labeling their roles can create a convincing but incorrect answer.
Define operations that can be tested independently
| Operation | Contract to establish |
|---|---|
| Write | Repeating an event does not create unintended duplicates |
| Read | Only authorized, applicable evidence reaches the answer |
| Correct | Current questions use the correction; supported historical questions retain history |
| Expire | Expired context stops participating in the intended retrieval path |
| Delete | Source, derived records, and application caches follow the agreed deletion behavior |
| Export | Records retain identity, provenance, and version information |
Map these operations to your chosen service and implement any remaining lifecycle behavior in the application. For Supermemory's documented relationships between memories, see the graph-memory documentation. The application contract still needs to cover its own records and caches.
Keep procedures under stronger control
An agent may observe that a workaround helped once. That does not make the workaround an approved procedure. Store the observation with its context, then promote it to a shared instruction only through your chosen review and testing process.
For example, “skip this failing test” during a local investigation should not become a permanent release rule. A memory system that faithfully repeats the wrong instruction can cause more damage than one that forgets it.
Choose the smallest architecture that passes the workload
Begin with a relational record or a versioned file when the facts are few and exact lookup is enough. Add vector or hybrid retrieval when the questions require semantic matching. Add graph paths when explicit relationships solve a demonstrated gap.
Use the three implementation approaches to choose what to build or buy. Then test one complete lifecycle: capture a decision, retrieve it in another session, correct it, verify isolation, and remove it. That sequence reveals more about the architecture than a diagram containing every possible memory type.
For framework-specific implementations, see the guides for LangGraph, Microsoft Agent Framework and CrewAI.
If a managed memory layer fits your design, build a small pilot with Supermemory. Bring one decision and two fictional users, then walk through the lifecycle above to see how it fits your application.