Skip to content

CONCEPT.md

Latest commit

 

History

History
249 lines (205 loc) · 6.05 KB

CONCEPT.md

File metadata and controls

249 lines (205 loc) · 6.05 KB
Raw

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.