An agent that remembers a user’s preference can use it in a later conversation instead of asking again. Agent memory makes that possible by retaining information from past conversations, actions, and experiences, then bringing relevant pieces into the agent’s current context. Knowledge serves a related but different role: it supplies external information, such as documents. Both can use the same storage and retrieval methods. section 6.0 section 6.6
Table 6.1 Sources, storage formats, and retrieval mechanisms of knowledge and memory used in agent applications
| Source |
Storage format |
Retrieval mechanism |
| Memory (short-term)—previous conversation thread |
Agent/user conversation thread stored as text |
Provided automatically as message history |
| Memory (long-term)—previous user conversations |
Summarized memories stored as text or in a vector database (semantic) |
Semantic/vector search |
| Knowledge (unstructured), documents (PDFs) |
Vector database (semantic) and text document index |
Semantic/vector search and keyword search |
| Knowledge (structured), database tables, structured logs |
Same format as source |
Relational database queries, log parsing |
Compare what is stored and how it is retrieved: recent conversation turns can arrive as message history, while older conversations can be searched as long-term memory. section 6.1
The practical boundary is the context window: only a limited amount of information fits into any one model call. Short-term conversational memory keeps recent turns in that window. Long-term memory persists outside it and is retrieved selectively. A memory store may grow independently of the window, but its contents cannot all be used at once. Older turns, lengthy tool results, and retrieved memories may need to be filtered, summarized, or left out. section 1.3.4 section 6.1
Think of memory as four cooperating pieces:
- Current context holds the conversation and other information available for the next model call. section 6.4.1
- External storage preserves information across sessions in files, databases, or vector stores. section 6.4.1
- Task state records working notes or plan progress that an agent reads and writes while working. section 6.4.1
- Retrieval finds useful stored items and adds them to the current prompt. A semantic search can find related wording; keyword, relational, or graph queries can cover cases it misses. section 6.1 section 6.6
From one session to the next
During a conversation, keep recent user and agent turns as message history. If the user states a durable preference, save it outside the session. On a later request, retrieve that preference only if it is relevant and add it to the prompt. The same approach can recall a prior agent attempt or decision. This is retrieval applied to the agent’s past, not a change to the model’s training. section 1.3.4 section 6.0
Listing 11.4 04_knowledge_memory_tips.py
from agents import Agent, Runner, SQLiteSession, function_tool
kb = load_vector_kb( #1
embedding_model="text-embedding-3-small", #2
index="HNSW",
shards=["product", "policy", "engineering"], )
@function_tool
def retrieve(query: str, product: str|None=None, version: str|None=None,
date: str|None=None, role: str|None=None, tenant: str|None=None) -> str:
"""Return grounded snippets using metadata filters."""
return kb.query(query=query, k=5,
filters={"product": product, "version": version, "date": date,
"role": role, "tenant": tenant}) #3
@function_tool
def remember(user_id: str, fact: str) -> str:
"""Persist long-term user fact in vector memory; prune aggressively."""
kb.upsert(text=fact, metadata={"user_id": user_id, "kind": "preference"},
ttl_days=90); return "ok" #3
agent = Agent(
name="Support",
instructions=("Use ONLY retrieved context; cite chunk ids; if absent #4
say 'I don't know'."), #4
tools=[retrieve, remember],
)
session = SQLiteSession("u42-chat") #5
kb.ingest("docs/*.md", chunking="semantic",
partition_by=["role", "tenant", "product", "version"]) #3
print(Runner.run_sync(
agent,
"Can I use the beta API on v3.2? (tenant=acme)",
session=session))
A single-agent example pairs a session with retrieval and remember tools. Its retrieval call uses metadata filters, and its remember call stores a user preference with a retention period. section 11.1.4
Start with session history; add persistent memory when information needs to survive a session. Retrieve selectively instead of stuffing the store into a prompt. Prune stale or redundant items, keep sensitive information separated by role or tenant, and require answers to stay grounded in retrieved context. Terms such as “working” and “long-term” memory are useful shorthand, but the engineering questions are where information lives, how it is found, and whether it fits in the next call. section 11.1.4 section 6.4.1
