examples/08_simple-agent-with-memory/CONCEPT.md

Concept: Persistent Memory & State Management

Overview

Adding persistent memory transforms agents from stateless responders into systems that can maintain context and relationships across sessions.

The Memory Problem

Without Memory              With Memory
──────────────             ─────────────
Session 1:                  Session 1:
"I'm Alex"                 "I'm Alex" → Saved
"I love pizza"             "I love pizza" → Saved

Session 2:                  Session 2:
"What's my name?"          "What's my name?"
"I don't know"             "Alex!" ✓

Architecture

┌─────────────────────────────────┐
│         Agent Session           │
├─────────────────────────────────┤
│  System Prompt                  │
│  + Loaded Memories              │
│  + saveMemory Tool              │
└────────┬────────────────────────┘
         │
         ↓
┌─────────────────────────────────┐
│      Memory Manager             │
├─────────────────────────────────┤
│  • Load from storage            │
│  • Save to storage              │
│  • Format for prompt            │
└────────┬────────────────────────┘
         │
         ↓
┌─────────────────────────────────┐
│   Persistent Storage            │
│   (agent-memory.json)           │
└─────────────────────────────────┘

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

User shares information
       ↓
Agent recognizes important fact
       ↓
Agent calls saveMemory()
       ↓
Saved to JSON file
       ↓
Available in future sessions

3. Memory Types

Facts: General information

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

Preferences:

{
  "memories": [
    {
      "type": "preference",
      "key": "favorite_food",
      "value": "pizza",
      "source": "user",
      "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

Agent decides when to save:
User: "My favorite color is blue"
      ↓
Agent: "I should remember this"
      ↓
Calls: saveMemory(type="preference", key="color", content="blue")

Real-World Applications

Personal Assistant

• Remember appointments, preferences, contacts
• Personalized responses based on history

Customer Service

• Past interactions and issues
• Customer preferences and context

Learning Tutor

• Student progress and weak areas
• Adapted teaching based on history

Healthcare Assistant

• Medical history
• Medication reminders
• Health tracking

Memory Strategies

1. Episodic Memory

Store specific events and conversations:

- "On 2025-01-15, user asked about Python"
- "User struggled with async concepts"

2. Semantic Memory

Store facts and knowledge:

- "User is a software engineer"
- "User prefers TypeScript over JavaScript"

3. Procedural Memory

Store how-to information:

- "User's workflow: design → code → test"
- "User's preferred tools: VS Code, Git"

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 logic

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

Evolution Path

1. Stateless → Each interaction independent
2. Session memory → Remember during conversation
3. Persistent memory → Remember across sessions
4. Distributed memory → Share across instances
5. Semantic search → Find relevant memories

Best Practices

1. Structure memory: Use types (facts, preferences, events)
2. Add timestamps: Know when information was saved
3. Enable updates: Allow overwriting old information
4. Implement search: Find relevant memories efficiently
5. Monitor size: Prevent unbounded growth

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. They can build relationships, provide personalized experiences, and maintain context over time.

This is essential for production AI agent systems.