AI memory becomes confusing when every previous message, embedding, summary, and database record is placed in one retrieval bucket. The system appears to remember more, but operators cannot tell what is authoritative, why a fact was selected, or when it should expire. Durable memory requires a data model before it requires a vector database. The goal is to preserve useful state while keeping source, scope, and retention visible.

A Brain API can make memory a deliberate service rather than a side effect of conversation history. It can distinguish temporary working state from durable user facts, separate exact records from semantic search, and return provenance with every retrieved item. That design improves quality and privacy at the same time. It also makes it possible to delete, correct, migrate, and evaluate memory without reverse-engineering opaque prompt transcripts.

Define memory classes before storage

Working memory exists only for the current run. It includes the active plan, unresolved questions, intermediate tool results, and temporary calculations. Session memory supports a bounded interaction such as a support case or research task. Durable memory survives across sessions and should contain only confirmed preferences, stable facts, or application-owned records. Episodic memory captures past events, while semantic memory stores generalized concepts or summaries derived from them.

These classes should map to different tables, indexes, or retention policies. A working scratchpad may expire within hours. A case record may remain for the business retention period. A user preference may persist until corrected. A model-generated summary should carry the source events and the prompt version that produced it. The storage system can be simple, but the distinctions must be visible in the schema.

Use an event log as the factual backbone

An append-only event log gives the system a reliable history of what happened. Each event can include an identifier, tenant, actor, event type, timestamp, payload reference, sensitivity label, and correlation ID. Events such as request_received, tool_completed, user_confirmed, memory_written, and memory_deleted are easier to reason about than a mutable blob called conversation. Derived views can summarize the current state without erasing the underlying sequence.

The event log does not need to store every model token. Store decisions, inputs that matter, structured outputs, and references to larger artifacts. Sensitive values can be redacted or placed in restricted storage. Event schemas should be versioned so replay remains possible after the application changes. A compact, typed history also supports analytics: teams can measure correction rates, stale memories, repeated retrieval failures, and the effect of a new summarization policy.

Model a memory record explicitly

A durable memory record should contain more than text and an embedding. Include a type, subject, canonical value, source, confidence class, owner, creation time, last-confirmed time, expiration, sensitivity, and allowed purposes. A record can point back to one or more events. This makes it possible to answer important questions: Was the fact stated by the user, inferred by a model, imported from a system of record, or copied from an untrusted document?

Avoid treating numerical confidence scores as truth. A source class and verification status are usually more actionable. For example, user_confirmed, system_verified, model_inferred, and imported_unverified communicate how the application should use a record. The API can then filter out inferred memories for high-impact decisions while still allowing them to personalize low-risk suggestions.

Combine exact retrieval with semantic retrieval

Not every memory query is a similarity search. Tenant, subject, type, status, and time filters should run before semantic ranking. Exact keys are appropriate for account settings, workflow state, and known entities. Full-text search can handle names and phrases. Vector retrieval is useful when the request expresses a concept in different words. A hybrid pipeline can blend these methods while preserving hard boundaries.

Retrieve a small candidate set and return provenance beside each item. The model should see the source type, date, and trust class along with the content. Re-ranking can favor recency, confirmed status, or task relevance. Do not let a high embedding similarity override access control or retention. The database query is part of the policy surface, not merely a relevance function.

Summaries are cached interpretations

Summaries reduce context cost, but they are not equivalent to original events. A summary should identify its source range, creation model, prompt version, and checksum or version of the underlying records. When source data changes, mark the summary stale. For important decisions, allow the workflow to inspect the original records rather than trusting a compressed interpretation.

Layer summaries by purpose. A session summary can capture goals, decisions, and open items. A user profile can contain only confirmed preferences. A project digest can summarize recent events with links to the underlying artifacts. This is more reliable than repeatedly summarizing a previous summary, which can amplify omissions and gradually detach the memory from its source.

Choose databases by access pattern

A relational database is often the best system of record because it supports transactions, constraints, deletion, and transparent queries. Object storage can hold large documents, images, audio, and video. A vector index can accelerate semantic retrieval, but it should store references to canonical records rather than become the only copy. A cache can hold short-lived context packages and model results. These components can begin in one managed platform and separate later.

The OpenAI Agents SDK sessions documentation demonstrates a useful boundary between run execution and session-managed conversation history. The broader lesson is to decide which component owns continuity. A Brain API should not combine a client transcript, provider continuation token, server session, and durable memory without a clear precedence rule, because duplicate or contradictory context becomes difficult to diagnose.

Make correction and deletion normal operations

Users and operators need a way to inspect, correct, and remove durable memory. A correction should not silently overwrite history; record the new value, invalidate the old view, and retain only the audit data permitted by policy. Deletion must propagate to indexes, caches, summaries, and backups according to the system's retention design. A tombstone can prevent deleted content from being re-imported during replay.

Expose memory administration through narrow APIs rather than database access. Useful operations include list memory by subject, explain why an item was retrieved, confirm a proposed memory, correct a value, and request deletion. Each operation should enforce tenant and purpose boundaries. The interface can also report that a summary will be regenerated or that an index update is pending, making eventual consistency visible instead of surprising.

Test memory as a stateful subsystem

Memory evaluations need sequences, not isolated prompts. Test that a confirmed fact is recalled in the correct context, an expired fact is excluded, a correction wins over an older value, and one tenant never receives another tenant's record. Add adversarial cases where an untrusted document tries to write a preference or where a model proposes a sensitive memory without justification. Measure retrieval precision, stale-item rate, correction success, and deletion completion.

Replay tests should pin the memory snapshot and retrieval policy so model changes do not hide data regressions. Log which candidate records were considered, which filters removed them, and why the final set was selected. That evidence turns vague complaints about the system forgetting or hallucinating into concrete failures that engineering teams can reproduce.

Implementation checklist

Before the first production release

  • Separate working, session, episodic, semantic, and durable memory.
  • Use typed events as the factual history of a workflow.
  • Store provenance, trust class, sensitivity, and expiration with every record.
  • Apply tenant and purpose filters before semantic ranking.
  • Treat summaries as versioned, invalidatable derived data.
  • Keep a canonical record outside the vector index.
  • Provide explicit correction, explanation, and deletion operations.
  • Evaluate memory with multi-step sequences and isolation tests.

Conclusion

Durable AI memory is a data-governance system with retrieval features. Its quality depends on boundaries: what can be remembered, who owns it, where it came from, how long it lasts, and which tasks may use it. Once those rules are explicit, embeddings and summaries become useful tools rather than sources of hidden state.

Start with an event log and a small set of typed memory records. Add semantic retrieval only where exact lookup is insufficient. Preserve provenance, make corrections ordinary, and test the system across time. That architecture gives agents continuity without turning the database into an unreviewable accumulation of model-generated notes.