State Management with Long-Term Memory Notes using OpenAI Agents SDK
https://github.com/openai/openai-cookbook/blob/main/examples/agents_sdk/context_personalization.ipynb
1. State-based > Retrieval-based memory — Rejects the common
RAG/vector-search approach to memory. Instead maintains a structured
state object with explicit precedence rules. The argument: semantic
search is fragile, can't handle belief updates or conflict resolution,
and fails silently when phrasing varies.
2. Two-phase memory processing — Distill during the session (via tool
call), consolidate after (via separate LLM call). This is more reliable
than trying to do it all at once, and lets you use a cheaper model
(gpt-5-mini) for the consolidation pass.
3. Session vs Global memory scoping — "I want a window seat this time"
should NOT overwrite "usually prefers aisle." Most memory systems get
this wrong by treating all preferences as permanent. The explicit
scoping + ephemeral phrase detection ("this time", "this trip") during
consolidation prevents this.
4. Precedence hierarchy — Latest user message > session memory > global
memory > profile defaults. This single rule prevents the #1 failure mode
of memory systems: stale memories overriding current intent.
5. Context trimming triggers memory re-injection — When the conversation
gets long and old messages are trimmed, session memories would be lost.
The one-shot flag mechanism (inject_session_memories_next_turn)
automatically re-injects them into the system prompt. Subtle but
critical for long-running sessions.
6. Memory as a tool, not a side-effect — The agent explicitly calls
save_memory_note() rather than having an external system silently
extract memories. This gives the model agency over what gets remembered
and keeps the capture intentional + auditable.
7. Three-layer guardrails — Memory is an injection surface. Checks at
capture (reject PII/instructions), consolidation (no hallucinated
facts), and injection (delimiters + precedence enforcement). Most
memory implementations ignore this entirely.
8. "Forgetting" as a feature — Consolidation actively prunes stale,
low-signal, and ephemeral notes. Memory systems that only accumulate
eventually poison their own context.