Home
Back to Overview

Persistent Memory & State Management

Transform agents from stateless responders into systems with context

Learn how to give agents long-term memory across sessions

The Memory Problem

Without Memory

Session 1:
"I'm Alex"
"I love pizza"
Session 2:
"What's my name?"
"I don't know" ❌

With Memory

Session 1:
"I'm Alex" → Saved
"I love pizza" → Saved
Session 2:
"What's my name?"
"Alex!" ✓

Architecture

Agent Session

Top Layer
System Prompt
Loaded Memories (injected into prompt)
saveMemory Tool (for storing new facts)
↓

Memory Manager

Middleware
Load from storage (on startup)
Save to storage (when saveMemory called)
Format memories for prompt injection
↓

Persistent Storage

Data Layer
Storage File:
agent-memory.json
Contains all saved facts and preferences across sessions

Data Flow

Read Flow (Startup):
Storage → Memory Manager → Agent Session
Memories loaded and injected into system prompt
Write Flow (During Use):
Agent Session → Memory Manager → Storage
New facts saved via saveMemory tool

How It Works

1. Startup

1. Load agent-memory.json
2. Extract facts and preferences
3. Add to system prompt
4. Agent "remembers" past information

2. During Conversation

Step 1

User Shares Information

User: "My name is Alex and I love pizza"
↓
Step 2

Agent Recognizes Important Fact

LLM Analysis:
"This contains personal information that should be remembered"
↓
Step 3

Agent Calls saveMemory()

Function Call:
saveMemory("user_name", "Alex", "fact")
saveMemory("favorite_food", "pizza", "preference")
↓
Step 4

Saved to JSON File

agent-memory.json:
[
{"type": "fact", "key": "user_name", "value": "Alex", ...},
{"type": "preference", "key": "favorite_food", "value": "pizza", ...}
]
↓
Step 5

Available in Future Sessions

Next Session:
Agent loads memories → System prompt includes:
"You remember: user_name is Alex, favorite_food is pizza"

Memory Types

Facts: General Information

{
"type": "fact",
"key": "user_name",
"value": "Alex",
"timestamp": "2025-10-29T11:22:57.372Z"
}

Preferences

{
"type": "preference",
"key": "favorite_food",
"value": "pizza",
"timestamp": "2025-10-29T11:22:58.022Z"
}

Memory Integration Pattern

System Prompt Enhancement

Base Prompt:
"You are a helpful assistant."
Enhanced with Memory:
"You are a helpful assistant with long-term memory.
=== LONG-TERM MEMORY ===
Known Facts:
- User's name is Alex
- User loves pizza"

Tool-Assisted Saving

Step 1

User Shares Information

User: "My favorite color is blue"
↓
Step 2

Agent Recognizes Value

LLM Reasoning:
"This is a personal preference that should be remembered for future conversations"
↓
Step 3

Agent Calls saveMemory()

Function Call:
saveMemory({
type: "preference",
key: "favorite_color",
value: "blue"
})
↓
Step 4

Persisted to Storage

Memory saved to agent-memory.json
{
"type": "preference",
"key": "favorite_color",
"value": "blue",
"timestamp": "2025-10-29T11:22:57.372Z"
}
Key Benefits:
Autonomous decision-making
No manual memory management
Context-aware saving
Structured data format

Real-World Applications

📅 Personal Assistant

  • • Remember appointments
  • • Preferences, contacts
  • • Personalized responses

💬 Customer Service

  • • Past interactions
  • • Customer preferences
  • • Issue context

📚 Learning Tutor

  • • Student progress
  • • Weak areas
  • • Adapted teaching

🏥 Healthcare Assistant

  • • Medical history
  • • Medication reminders
  • • Health tracking

Memory Strategies

Episodic Memory

Store specific events and conversations

"On 2025-01-15, user asked about Python"

Semantic Memory

Store facts and knowledge

"User is a software engineer"

Procedural Memory

Store how-to information

"User's workflow: design → code → test"

💾 Memory Management Best Practices

Memory Size Limits

  • • Context window: 4096 tokens
  • • System prompt: ~200 tokens
  • • Available for memory: ~3800 tokens
  • • Each memory: ~50-100 tokens
  • • Max memories: ~40-75 items

Cleanup Strategies

  • • Remove old memories (by date)
  • • Summarize related memories
  • • Keep only important facts
  • • Archive instead of delete
  • • Use importance scoring

Challenges & Solutions

Challenge 1: Memory Bloat

Problem: Too many memories slow down agent

Solution: Importance scoring, periodic cleanup, summary compression

Challenge 2: Conflicting Information

Problem: "User likes pizza" vs "User is vegan"

Solution: Timestamps for recency, explicit updates, conflict resolution

Challenge 3: Privacy

Problem: Sensitive information in memory

Solution: Encryption at rest, access controls, expiration policies

Key Concepts

1. Persistence

Memory survives application restarts, system reboots, time gaps

2. Context Augmentation

Memories enhance system prompt: Prompt = Base + Memories + User Input

3. Agent-Driven Storage

Agent decides what to remember: Important? → Save | Trivial? → Ignore

Comparison

Feature Simple Agent Memory Agent
Remembers names ✗ ✓
Recalls preferences ✗ ✓
Personalization ✗ ✓
Context continuity ✗ ✓
Cross-session state ✗ ✓

Key Takeaway

Memory transforms agents from tools into assistants.

🤝

Build relationships

🎯

Personalized experiences

💾

Maintain context over time

This is essential for production AI agent systems.

Next: ReAct Pattern