1How does an assistant remember both what was said and what is true?
Two memories work side by side. An episodic memory keeps past exchanges and finds the ones that resemble the new message. A semantic memory keeps facts as short statements such as "Acme uses invoicing plan B". Each turn reads both, answers, then files the exchange and any new fact.
You may need it if
- Customers repeat context they gave last week, and the assistant still asks again.
- The assistant recalls a past chat but contradicts a fact the customer has since corrected.
- You need to answer both "what did we discuss?" and "what is their current setup?".
2When are two memories one too many?
Use it when
- The same customer, account or project comes back across many sessions.
- Some of what matters is how a past conversation went, and some is a stable fact.
- Facts change over time and the assistant must use the latest version.
Avoid it when
- Requests are one-off and nothing needs to carry over to the next session.
Use Tool Use instead - The knowledge is a body of documents to consult, not something learned from conversations.
Use Agentic RAG instead - Questions depend on chains of relations across many entities, such as which suppliers serve which plants.
Use Graph Memory instead - The history is long but only a small profile must stay in view, and the agent can manage paging itself.
Use Tiered Memory instead
What it costs
- Model calls
- 3 per turn: recall, answer, write-back
- Latency
- medium
- Complexity
- medium
3How does one turn read from and write to both memories?
A recaller searches past episodes by similarity and looks up facts about the entities in the message. The responder answers from that bundle. A memory writer then extracts new or changed facts and files the whole exchange as a new episode.
- Step 1 of 5
A message arrives
The message comes with the account it belongs to. Only that account's memories will be searched, never another customer's.
- Step 2 of 5
Recall from two places
The recaller pulls the three or four past exchanges most similar to the message, and every current fact about the people, products and plans it names.
- Step 3 of 5
Answer from the bundle
The responder sees the message and the recall bundle. When an old episode and a current fact disagree, the fact wins, because it was updated more recently.
- Step 4 of 5
Learn from the turn
The memory writer reads the exchange. A new or changed fact replaces the old statement, with today's date. The exchange itself is summarised and filed as an episode.
- Step 5 of 5
Release
The answer leaves only after both writes. The next turn, even in another session, starts with what this one learned.
What each part does
- Message
- The new message from a known user or account, with an identifier that selects their memories.
- Episodic memory
- Past exchanges, each a short summary with its date, searched by similarity to the new message.
- Semantic memory
- Current facts as subject, relation, object statements, each with the date it was learned.
- Recaller
- Finds the few past episodes and facts that bear on this message and bundles them.
- Responder
- Answers the message using the recalled episodes and facts, preferring facts when they disagree.
- Memory writer
- Extracts new or changed facts from the exchange and files the exchange as a new episode.
- Answer
- The reply, released once both memories are updated for this turn.
- Episodic memory → Recaller: similar past exchanges
- Semantic memory → Recaller: facts about named entities
- Recaller → Responder: recall bundle
- Responder → Memory writer: message and reply
- Memory writer → Semantic memory: new or replaced facts
- Memory writer → Episodic memory: episode summary
Where it connects
One message or request, with an identifier for the user or account whose memories apply.
When: The responder has answered and both memories have been updated for the turn.
The reply, plus the episodes and facts it relied on and the facts added or replaced this turn.
Dated summaries of past exchanges for one account, retrieved by similarity. Appended, never rewritten.
Dated subject, relation, object statements for one account. One current statement per subject and relation; a newer one replaces it.
4What do I ask my assistant to set up?
The agents to launch
Recaller
For the new message, return at most four past episodes that are most relevant, and every stored fact about the people, companies, products or plans it mentions. Quote each item with its date. Do not answer the message.
Sees: The message, the account's episode search and fact lookup. Not other accounts' memories.
Responder
Answer the message using the recall bundle. When an episode and a fact disagree, trust the fact. If something you need is not in the bundle, say so instead of guessing. Never invent a past conversation.
Sees: The message and the recall bundle only. Not the raw stores.
Memory writer
From the message and the reply, list durable facts as subject, relation, object with today's date. Mark each as new or as replacing an existing fact. Ignore moods and one-off remarks. Then write a two-sentence summary of the exchange as an episode, including any commitment made.
Sees: The message, the reply and the current facts for the entities mentioned. Not the full episode history.
A prompt you can paste
Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.
You are the orchestrator of a multi-agent workflow that follows the "Episodic + Semantic Memory" architecture. Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it. # Task [Describe your task here] # Episodic + Semantic Memory Recall past exchanges and known facts, answer, then write both back. Input: the task above. It must provide: One message or request, with an identifier for the user or account whose memories apply. If something essential is missing, ask for it before starting. Agents to launch: - Recaller: For the new message, return at most four past episodes that are most relevant, and every stored fact about the people, companies, products or plans it mentions. Quote each item with its date. Do not answer the message. Context for this agent: The message, the account's episode search and fact lookup. Not other accounts' memories. - Responder: Answer the message using the recall bundle. When an episode and a fact disagree, trust the fact. If something you need is not in the bundle, say so instead of guessing. Never invent a past conversation. Context for this agent: The message and the recall bundle only. Not the raw stores. - Memory writer: From the message and the reply, list durable facts as subject, relation, object with today's date. Mark each as new or as replacing an existing fact. Ignore moods and one-off remarks. Then write a two-sentence summary of the exchange as an episode, including any commitment made. Context for this agent: The message, the reply and the current facts for the entities mentioned. Not the full episode history. Procedure: 1. Create two stores per account. An episode store with dated summaries and similarity search, and a fact store keyed by subject and relation. 2. Launch the recaller on the incoming message and collect its bundle. 3. Launch the responder in a separate context with the message and the bundle. 4. Launch the memory writer on the message and the reply. Apply its fact changes, replacing any fact with the same subject and relation, and append its episode summary. 5. Release the reply with the list of items read and written. Stop rule: One pass per turn. Recall at most four episodes, write once to each store, then release. The stores are kept for the next turn. Exit: - `answer`, when: The responder has answered and both memories have been updated for the turn. Deliver: The reply, plus the episodes and facts it relied on and the facts added or replaced this turn. # Final deliverable The reply, then the episodes and facts recalled, the facts added or replaced, and the episode filed for this turn.
The same thing in code
from datetime import date
from typing import TypedDict, cast
from langchain.chat_models import init_chat_model
from langgraph.graph import START, StateGraph
from pydantic import BaseModel
llm = init_chat_model("anthropic:claude-sonnet-5-5")
ACCOUNT = "account-123" # selects this user's memories; stores are never shared across accounts
class Fact(BaseModel):
subject: str
relation: str
object: str
learned: str = ""
class Cues(BaseModel):
query: str # what to search past episodes for
entities: list[str] # people, companies, products or plans named in the message
class MemoryUpdate(BaseModel):
facts: list[Fact] # new or replacing; moods and one-off remarks left out
episode: str # two sentences, including any commitment made
EPISODES: dict[str, list[tuple[str, str]]] = {} # account -> (date, summary)
FACTS: dict[str, dict[tuple[str, str], Fact]] = {} # account -> (subject, relation) -> fact
def search_episodes(account: str, text: str, k: int = 4) -> list[tuple[str, str]]:
# plug in a vector index scoped to the account; this stub returns the latest k
return EPISODES.get(account, [])[-k:]
def lookup_facts(account: str, entities: list[str]) -> list[Fact]:
return [f for f in FACTS.get(account, {}).values() if f.subject in entities]
class State(TypedDict):
message: str
entities: list[str]
bundle: str
reply: str
written: list[str]
async def recaller(state: State) -> dict:
cues = cast(Cues, await llm.with_structured_output(Cues).ainvoke(
"Do not answer this message. Name what to search past episodes for, and every entity "
f"it mentions.\n{state['message']}"))
episodes = search_episodes(ACCOUNT, cues.query) # at most four episodes
facts = lookup_facts(ACCOUNT, cues.entities)
bundle = "\n".join([f"[episode {d}] {s}" for d, s in episodes]
+ [f"[fact {f.learned}] {f.subject} {f.relation} {f.object}" for f in facts])
return {"entities": cues.entities, "bundle": bundle}
async def responder(state: State) -> dict:
# sees the message and the recall bundle only, not the raw stores
reply = await llm.ainvoke(
"Answer the message using the recall bundle. When an episode and a fact disagree, trust the "
"fact. If something is missing, say so. Never invent a past conversation.\n"
f"Recall bundle:\n{state['bundle']}\n\nMessage: {state['message']}")
return {"reply": reply.text}
async def writer(state: State) -> dict:
current = lookup_facts(ACCOUNT, state["entities"])
update = cast(MemoryUpdate, await llm.with_structured_output(MemoryUpdate).ainvoke(
"List durable facts from this exchange as subject, relation, object, new or replacing a "
"current fact. Then summarise the exchange in two sentences as an episode.\n"
f"Current facts: {[f.model_dump() for f in current]}\n"
f"Message: {state['message']}\nReply: {state['reply']}"))
today = date.today().isoformat()
for fact in update.facts: # keyed by subject and relation, so a new fact replaces the old one
dated = fact.model_copy(update={"learned": today})
FACTS.setdefault(ACCOUNT, {})[(fact.subject, fact.relation)] = dated
EPISODES.setdefault(ACCOUNT, []).append((today, update.episode)) # one write per store per turn
return {"written": [f"{f.subject} {f.relation} {f.object}" for f in update.facts] + [update.episode]}
graph = StateGraph(State)
graph.add_node("recaller", recaller)
graph.add_node("responder", responder)
graph.add_node("writer", writer)
graph.add_edge(START, "recaller")
graph.add_edge("recaller", "responder")
graph.add_edge("responder", "writer")
app = graph.compile()
async def run(task: str):
# the reply is released only after both memories are updated
final = await app.ainvoke({"message": task, "entities": [], "bundle": "", "reply": "", "written": []})
return {"reply": final["reply"], "recalled": final["bundle"], "written": final["written"]}
Replace the dicts with a persistent store per account, such as a LangGraph store with an embedding index, so episode search is by real similarity.
from datetime import date
from typing import Any
from claude_agent_sdk import (AgentDefinition, ClaudeAgentOptions, ResultMessage,
create_sdk_mcp_server, query, tool)
from pydantic import BaseModel
ACCOUNT = "account-123" # selects this user's memories; stores are never shared across accounts
EPISODES: dict[str, list[tuple[str, str]]] = {} # account -> (date, summary)
FACTS: dict[str, dict[tuple[str, str], tuple[str, str]]] = {} # (subject, relation) -> (object, date)
class Fact(BaseModel):
subject: str
relation: str
object: str
class MemoryUpdate(BaseModel):
facts: list[Fact]
episode: str
def text(body: str) -> dict[str, Any]:
return {"content": [{"type": "text", "text": body or "nothing stored"}]}
@tool("search_episodes", "Past episodes of this account most similar to a text", {"text": str})
async def search_episodes(args: dict[str, Any]) -> dict[str, Any]:
# plug in a vector index scoped to the account; this stub returns the latest four
return text("\n".join(f"[{d}] {s}" for d, s in EPISODES.get(ACCOUNT, [])[-4:]))
@tool("lookup_facts", "Stored facts about one entity of this account", {"entity": str})
async def lookup_facts(args: dict[str, Any]) -> dict[str, Any]:
facts = FACTS.get(ACCOUNT, {}).items()
return text("\n".join(f"[{d}] {s} {r} {o}" for (s, r), (o, d) in facts if s == args["entity"]))
MEMORY = create_sdk_mcp_server("memory", tools=[search_episodes, lookup_facts])
AGENTS = {
"recaller": AgentDefinition(
description="Finds past episodes and facts that bear on a message.",
prompt="Return at most four relevant past episodes and every stored fact about the people, "
"companies, products or plans the message mentions, each with its date. Do not answer it.",
tools=["mcp__memory__search_episodes", "mcp__memory__lookup_facts"]),
"responder": AgentDefinition(
description="Answers a message from a recall bundle.",
prompt="Answer using the recall bundle only. When an episode and a fact disagree, trust the "
"fact. If something is missing, say so. Never invent a past conversation.",
tools=[]), # sees the bundle, not the raw stores
"memory-writer": AgentDefinition(
description="Extracts durable facts and an episode summary from an exchange.",
prompt="Look up the current facts for the entities mentioned. List durable facts as subject, "
"relation, object; ignore moods. Then summarise the exchange in two sentences as an episode.",
tools=["mcp__memory__lookup_facts"]), # current facts, not the episode history
}
async def delegate(agent: str, brief: str, schema: type[BaseModel] | None = None) -> ResultMessage:
options = ClaudeAgentOptions(
agents=AGENTS, mcp_servers={"memory": MEMORY},
allowed_tools=["Agent", "mcp__memory__search_episodes", "mcp__memory__lookup_facts"],
output_format={"type": "json_schema", "schema": schema.model_json_schema()} if schema else None)
async for message in query(prompt=f"Delegate this to the {agent} agent.\n\n{brief}", options=options):
if isinstance(message, ResultMessage):
return message
raise RuntimeError(f"{agent} returned no result")
async def run(task: str):
bundle = (await delegate("recaller", f"Message: {task}")).result or ""
reply = (await delegate("responder", f"Recall bundle:\n{bundle}\n\nMessage: {task}")).result or ""
done = await delegate("memory-writer", f"Message: {task}\nReply: {reply}", MemoryUpdate)
update = MemoryUpdate.model_validate(done.structured_output)
today = date.today().isoformat()
for f in update.facts: # keyed by subject and relation, so a new fact replaces the old one
FACTS.setdefault(ACCOUNT, {})[(f.subject, f.relation)] = (f.object, today)
EPISODES.setdefault(ACCOUNT, []).append((today, update.episode))
# the reply is released only after both memories are updated
return {"reply": reply, "recalled": bundle, "written": update.model_dump()}
Replace the dicts with persistent per-account stores and a vector index behind search_episodes; take the account from your session, not a constant.
from datetime import date
from agents import Agent, Runner, function_tool
from pydantic import BaseModel
ACCOUNT = "account-123" # selects this user's memories; stores are never shared across accounts
EPISODES: dict[str, list[tuple[str, str]]] = {} # account -> (date, summary)
FACTS: dict[str, dict[tuple[str, str], tuple[str, str]]] = {} # (subject, relation) -> (object, date)
class Fact(BaseModel):
subject: str
relation: str
object: str
class MemoryUpdate(BaseModel):
facts: list[Fact] # durable facts only, new or replacing
episode: str # two sentences, including any commitment made
@function_tool
def search_episodes(text: str) -> list[str]:
"""Past episodes of this account most similar to the text."""
# plug in a vector index scoped to the account; this stub returns the latest four
return [f"[{d}] {s}" for d, s in EPISODES.get(ACCOUNT, [])[-4:]]
@function_tool
def lookup_facts(entity: str) -> list[str]:
"""Stored facts about one person, company, product or plan of this account."""
return [f"[{d}] {s} {r} {o}" for (s, r), (o, d) in FACTS.get(ACCOUNT, {}).items() if s == entity]
recaller = Agent(
name="Recaller",
instructions="Return at most four relevant past episodes and every stored fact about the people, "
"companies, products or plans the message mentions, each with its date. Do not answer it.",
tools=[search_episodes, lookup_facts],
)
responder = Agent( # no tools: it sees the recall bundle, not the raw stores
name="Responder",
instructions="Answer the message using the recall bundle. When an episode and a fact disagree, "
"trust the fact. If something is missing, say so. Never invent a past conversation.",
)
writer = Agent(
name="Memory writer",
instructions="Look up the current facts for the entities mentioned. List durable facts from the "
"exchange as subject, relation, object; ignore moods and one-off remarks. Then summarise the "
"exchange in two sentences as an episode.",
tools=[lookup_facts], # current facts, not the episode history
output_type=MemoryUpdate,
)
async def run(task: str):
bundle = str((await Runner.run(recaller, f"Message: {task}")).final_output)
reply = str((await Runner.run(responder, f"Recall bundle:\n{bundle}\n\nMessage: {task}")).final_output)
update = (await Runner.run(writer, f"Message: {task}\nReply: {reply}")).final_output_as(MemoryUpdate)
today = date.today().isoformat()
for f in update.facts: # keyed by subject and relation, so a new fact replaces the old one
FACTS.setdefault(ACCOUNT, {})[(f.subject, f.relation)] = (f.object, today)
EPISODES.setdefault(ACCOUNT, []).append((today, update.episode))
# the reply is released only after both memories are updated
return {"reply": reply, "recalled": bundle, "written": update.model_dump()}
Replace the dicts with persistent per-account stores and a vector index behind search_episodes; pass the account through the run context.
import { anthropic } from '@ai-sdk/anthropic';
import { generateText, isStepCount, Output, tool } from 'ai';
import { z } from 'zod';
const model = anthropic('claude-sonnet-5-5');
const ACCOUNT = 'account-123'; // selects this user's memories; stores are never shared across accounts
type Fact = { subject: string; relation: string; object: string; learned: string };
const episodes = new Map<string, { date: string; summary: string }[]>();
const facts = new Map<string, Map<string, Fact>>(); // key: subject|relation
const factsAbout = (entity: string) =>
[...(facts.get(ACCOUNT)?.values() ?? [])].filter((f) => f.subject === entity);
const searchEpisodes = tool({
description: 'Past episodes of this account most similar to a text',
inputSchema: z.object({ text: z.string() }),
// plug in a vector index scoped to the account; this stub returns the latest four
execute: async () => (episodes.get(ACCOUNT) ?? []).slice(-4),
});
const lookupFacts = tool({
description: 'Stored facts about one person, company, product or plan of this account',
inputSchema: z.object({ entity: z.string() }),
execute: async ({ entity }) => factsAbout(entity),
});
const updateSchema = z.object({
facts: z.array(z.object({ subject: z.string(), relation: z.string(), object: z.string() })),
episode: z.string().describe('two sentences, including any commitment made'),
});
export async function run(task: string) {
const { text: bundle } = await generateText({
model,
instructions:
'Return at most four relevant past episodes and every stored fact about the people, companies, ' +
'products or plans the message mentions, each with its date. Do not answer the message.',
prompt: `Message: ${task}`,
tools: { searchEpisodes, lookupFacts },
stopWhen: isStepCount(5),
});
// no tools: the responder sees the recall bundle, not the raw stores
const { text: reply } = await generateText({
model,
instructions:
'Answer the message using the recall bundle. When an episode and a fact disagree, trust the ' +
'fact. If something is missing, say so. Never invent a past conversation.',
prompt: `Recall bundle:\n${bundle}\n\nMessage: ${task}`,
});
const { output: update } = await generateText({
model,
instructions:
'Look up the current facts for the entities mentioned. List durable facts from the exchange as ' +
'subject, relation, object; ignore moods. Then summarise the exchange as an episode.',
prompt: `Message: ${task}\nReply: ${reply}`,
tools: { lookupFacts }, // current facts, not the episode history
output: Output.object({ schema: updateSchema }),
stopWhen: isStepCount(5),
});
const today = new Date().toISOString().slice(0, 10);
const store = facts.get(ACCOUNT) ?? new Map<string, Fact>();
// keyed by subject and relation, so a new fact replaces the old one
for (const f of update.facts) store.set(`${f.subject}|${f.relation}`, { ...f, learned: today });
facts.set(ACCOUNT, store);
episodes.set(ACCOUNT, [...(episodes.get(ACCOUNT) ?? []), { date: today, summary: update.episode }]);
// the reply is released only after both memories are updated
return { reply, recalled: bundle, written: update };
}
Replace the maps with persistent per-account stores and a vector index behind searchEpisodes; take the account from the session, not a constant.
Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.
What goes wrong
- Adding a fact without replacing the old one leaves two truths in the store. Key facts by subject and relation.
- Filing full transcripts as episodes makes similarity search noisy and costly. File short summaries.
- A shared store across accounts leaks one customer's facts into another's conversation.
- Extracting opinions or moods as facts turns a bad day into a permanent label.
Chain it
Its result can feed
- Reflection direct
Treat the reply as an existing answer to improve. Keep it consistent with the episodes and facts it relied on, and do not alter the memory records listed with it.
- Chain of Verification conditional
Condition: Use this link when the reply makes general factual claims that can be checked independently, not when it only restates account-specific facts drawn from memory.
- Debate conditional
Condition: Use this link when the message asks for a decision, recommendation or judgement that can be argued, not when it asks for recall or a simple conversational reply.
- Constitutional Critique direct
Check the reply against every rule in the constitution and fix only the failed rules, keeping the memory-backed content intact.
- Textual Backpropagation direct
Treat the reply as an existing answer to improve against the original task, using the accompanying episodes and facts as context.