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