architecture
Pattern: Memory & State Management
Architectural patterns for agent memory and state management. Covers conversation, entity, episodic, and semantic memory types with implementation guidance.
Overview
Memory enables agents to maintain context across interactions. The right memory architecture depends on what needs to be remembered and for how long.
Memory Types
See ENT-AGENT-MEMORY for conceptual overview.
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MEMORY TYPES β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β CONVERSATION ENTITY EPISODIC SEMANTIC β
β "What was said" "Who/what" "What happened" "What we know" β
β β
β Session scope Entity scope Event scope Domain scope β
β Auto-managed Semi-auto Curated Curated β
β Buffer/summary Key-value Time-series Vector store β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
1. Conversation Memory
Purpose
Maintain context within a single session/conversation.
Strategies
Buffer Window
from langchain.memory import ConversationBufferWindowMemory
# Keep last N exchanges
memory = ConversationBufferWindowMemory(k=10)
Pros: Simple, bounded size Cons: Loses older context abruptly
Summary Buffer
from langchain.memory import ConversationSummaryBufferMemory
# Summarize when buffer exceeds limit
memory = ConversationSummaryBufferMemory(
llm=summarizer_llm,
max_token_limit=2000
)
Pros: Retains key info, bounded Cons: Lossy, requires LLM calls
Token Buffer
from langchain.memory import ConversationTokenBufferMemory
# Keep messages until token limit
memory = ConversationTokenBufferMemory(
llm=llm,
max_token_limit=4000
)
Pros: Predictable context size Cons: May cut mid-conversation
Selection Guide
| Scenario | Strategy |
|---|---|
| Short conversations (<10 turns) | Buffer Window |
| Long conversations, key points matter | Summary Buffer |
| Need exact history | Token Buffer + external log |
| Cost-sensitive | Buffer Window |
2. Entity Memory
Purpose
Track facts about specific entities (people, companies, concepts) across sessions.
Implementation
from langchain.memory import ConversationEntityMemory
class EnhancedEntityMemory:
def __init__(self, llm, storage):
self.base_memory = ConversationEntityMemory(llm=llm)
self.storage = storage # Database for persistence
def load_entity(self, entity_name: str) -> dict:
"""Load entity from persistent storage."""
return self.storage.get(entity_name, {})
def save_entity(self, entity_name: str, data: dict):
"""Persist entity to storage."""
existing = self.load_entity(entity_name)
merged = {**existing, **data, "updated_at": datetime.now()}
self.storage.set(entity_name, merged)
def get_context(self, entities: list) -> str:
"""Build context from relevant entities."""
context_parts = []
for entity in entities:
data = self.load_entity(entity)
if data:
context_parts.append(f"## {entity}\n{format_entity(data)}")
return "\n\n".join(context_parts)
Schema Example
# Prospect entity schema
{
"name": "Sarah Chen",
"type": "person",
"attributes": {
"role": "VP Engineering",
"company": "TechCorp",
"email": "sarah@techcorp.com"
},
"facts": [
{"fact": "Concerned about integration timeline", "source": "call_2026-01-02"},
{"fact": "Has budget authority up to $50K", "source": "email_2026-01-03"}
],
"relationships": [
{"entity": "TechCorp", "type": "works_at"},
{"entity": "Mike Johnson", "type": "reports_to"}
],
"metadata": {
"created_at": "2026-01-01",
"updated_at": "2026-01-03",
"source": "crm_import"
}
}
Catalog Applications
| Agent | Entity Types |
|---|---|
| Sales | Prospects, Companies, Deals |
| CS | Accounts, Contacts, Tickets |
| HR | Candidates, Employees, Roles |
| Ops | Vendors, Contracts |
3. Episodic Memory
Purpose
Remember specific events, interactions, and their outcomes over time.
Implementation
class EpisodicMemory:
def __init__(self, vectorstore):
self.store = vectorstore
def add_episode(self, event: dict):
"""Store a discrete event."""
doc = Document(
page_content=self._format_episode(event),
metadata={
"timestamp": event["timestamp"],
"event_type": event["type"],
"entities": event.get("entities", []),
"outcome": event.get("outcome"),
"sentiment": event.get("sentiment")
}
)
self.store.add_documents([doc])
def recall_similar(self, query: str, k: int = 5,
time_range: tuple = None,
event_type: str = None) -> list:
"""Retrieve similar past events."""
filters = {}
if time_range:
filters["timestamp"] = {
"$gte": time_range[0],
"$lte": time_range[1]
}
if event_type:
filters["event_type"] = event_type
return self.store.similarity_search(
query,
k=k,
filter=filters if filters else None
)
def recall_by_entity(self, entity: str, k: int = 10) -> list:
"""Get all episodes involving an entity."""
return self.store.similarity_search(
f"interactions with {entity}",
k=k,
filter={"entities": {"$contains": entity}}
)
def _format_episode(self, event: dict) -> str:
"""Format event for embedding."""
return f"""
Event: {event['type']}
Date: {event['timestamp']}
Participants: {', '.join(event.get('entities', []))}
Summary: {event['description']}
Outcome: {event.get('outcome', 'N/A')}
"""
Event Schema
# Episode schema
{
"id": "evt_20260103_001",
"type": "meeting",
"timestamp": "2026-01-03T14:00:00Z",
"entities": ["Sarah Chen", "TechCorp", "Deal_12345"],
"description": "Demo call discussing API integration capabilities",
"details": {
"duration_minutes": 45,
"attendees": ["Sarah Chen", "Mike Johnson"],
"topics": ["API integration", "pricing", "timeline"]
},
"outcome": "positive",
"next_steps": ["Send proposal", "Schedule technical deep-dive"],
"sentiment": 0.7
}
Catalog Applications
| Agent | Episode Types |
|---|---|
| Sales | Calls, Emails, Meetings |
| CS | Support tickets, QBRs |
| Engineering | Incidents, Deployments |
| HR | Interviews, Reviews |
4. Semantic Memory
Purpose
Store and retrieve domain knowledge (policies, docs, procedures).
Implementation
See ENT-RAG and Pattern: Knowledge Architecture (RAG vs Semantic vs Fine-Tuning).
Key Differences from Episodic
| Factor | Episodic | Semantic |
|---|---|---|
| Content | Events that happened | Facts and knowledge |
| Time | Time-stamped | Timeless (mostly) |
| Updates | Append-only | Replace/update |
| Retrieval | "What happened when..." | "What is..." |
Memory Architecture by Agent
| Agent | Conversation | Entity | Episodic | Semantic |
|---|---|---|---|---|
| Prospect Research | - | Prospect | Outreach history | - |
| Email Draft | Thread | Prospect | - | Templates |
| Meeting Prep | - | Account | Meeting history | - |
| Account Health | - | Account | Interactions | - |
| Incident Analysis | - | Services | Past incidents | Runbooks |
| Policy Q&A | Session | - | - | Policies |
| Resume Screener | - | Candidate | - | Job reqs |
Persistence Strategies
In-Memory (Session Only)
# LangChain default - lost on restart
memory = ConversationBufferMemory()
Database (Cross-Session)
# Redis for fast access
from langchain.memory import RedisChatMessageHistory
history = RedisChatMessageHistory(
session_id="user_123",
url="redis://localhost:6379"
)
memory = ConversationBufferMemory(chat_memory=history)
Vector Store (Semantic/Episodic)
# Pinecone, Weaviate, Chroma, etc.
from langchain.vectorstores import Pinecone
vectorstore = Pinecone.from_existing_index(
index_name="episodes",
embedding=embeddings
)
Anti-Patterns
| Anti-Pattern | Problem | Solution |
|---|---|---|
| Unbounded memory | Token/cost explosion | Window or summarize |
| No persistence | Context lost on restart | Database storage |
| Over-retrieval | Irrelevant context | Better filtering |
| Wrong memory type | Poor recall | Match type to need |
| No memory at all | Repetitive, no learning | Add appropriate type |
Related Documents
- ENT-AGENT-MEMORY - Core concept definition
- ENT-RAG - Semantic memory implementation
- Pattern: Knowledge Architecture (RAG vs Semantic vs Fine-Tuning) - Knowledge architecture
- Pattern: Agent Chaining & Orchestration - Shared memory in chains