Agentic Architectures

Catalogue / Memory

Episodic + Semantic Memory

Recall past exchanges and known facts, answer, then write both back

Shape
memory-loop
Model calls
3 per turn: recall, answer, write-back
Latency
medium
Complexity
medium

Also known as Dual memory, Episodes and facts

1

How 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?".
2

When 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
3

How 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.

Message: The new message from a known user or account, with an identifier that selects their memories.MessageEpisodic memory: Past exchanges, each a short summary with its date, searched by similarity to the new message.EpisodicmemorySemantic memory: Current facts as subject, relation, object statements, each with the date it was learned.SemanticmemoryRecaller: Finds the few past episodes and facts that bear on this message and bundles them.RecallerResponder: Answers the message using the recalled episodes and facts, preferring facts when they disagree.ResponderMemory writer: Extracts new or changed facts from the exchange and files the exchange as a new episode.Memory writerAnswer: The reply, released once both memories are updated for this turn.Answer
  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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

Entry
message
TaskQuestion

One message or request, with an identifier for the user or account whose memories apply.

Exit
answer
Answer

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.

Memory kept between runs
episodes
Knowledge

Dated summaries of past exchanges for one account, retrieved by similarity. Appended, never rewritten.

Memory kept between runs
facts
Knowledge

Dated subject, relation, object statements for one account. One current statement per subject and relation; a newer one replaces it.

4

What 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.

Framework-agnostic prompt
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

LangGraph, python, package langgraph
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.

Claude Agent SDK, python, package claude-agent-sdk
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.

OpenAI Agents SDK, python, package openai-agents
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.

Vercel AI SDK, typescript, package ai
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