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

# Code Explanation: simple-agent-with-memory.js

This example extends the simple agent with **persistent memory**, enabling it to remember information across sessions while intelligently avoiding duplicate saves.

## Key Components

### 1. MemoryManager Import
```javascript
import {MemoryManager} from "./memory-manager.js";
```
Custom class for persisting agent memories to JSON files with unified memory storage.

### 2. Initialize Memory Manager
```javascript
const memoryManager = new MemoryManager('./agent-memory.json');
const memorySummary = await memoryManager.getMemorySummary();
```
- Loads existing memories from file
- Generates formatted summary for system prompt
- Handles migration from old memory schemas

### 3. Memory-Aware System Prompt with Reasoning
```javascript
const systemPrompt = `
You are a helpful assistant with long-term memory.

Before calling any function, always follow this reasoning process:

1. **Compare** new user statements against existing memories below.
2. **If the same key and value already exist**, do NOT call saveMemory again.
   - Instead, simply acknowledge the known information.
   - Example: if the user says "My name is Malua" and memory already says "user_name: Malua", reply "Yes, I remember your name is Malua."
3. **If the user provides an updated value** (e.g., "I actually prefer sushi now"), 
   then call saveMemory once to update the value.
4. **Only call saveMemory for genuinely new information.**

When saving new data, call saveMemory with structured fields:
- type: "fact" or "preference"
- key: short descriptive identifier (e.g., "user_name", "favorite_food")
- value: the specific information (e.g., "Malua", "chinua")

Examples:
saveMemory({ type: "fact", key: "user_name", value: "Malua" })
saveMemory({ type: "preference", key: "favorite_food", value: "chinua" })

${memorySummary}
`;
```

**What this does:**
- Includes existing memories in the prompt
- Provides explicit reasoning guidelines to prevent duplicate saves
- Teaches the agent to compare before saving
- Instructs when to update vs. acknowledge existing data

### 4. saveMemory Function
```javascript
const saveMemory = defineChatSessionFunction({
    description: "Save important information to long-term memory (user preferences, facts, personal details)",
    params: {
        type: "object",
        properties: {
            type: {
                type: "string",
                enum: ["fact", "preference"]
            },
            key: { type: "string" },
            value: { type: "string" }
        },
        required: ["type", "key", "value"]
    },
    async handler({ type, key, value }) {
        await memoryManager.addMemory({ type, key, value });
        return `Memory saved: ${key} = ${value}`;
    }
});
```

**What it does:**
- Uses structured key-value format for all memories
- Saves both facts and preferences with the same method
- Automatically handles duplicates (updates if value changes)
- Persists to JSON file
- Returns confirmation message

**Parameter Structure:**
- `type`: Either "fact" or "preference"
- `key`: Short identifier (e.g., "user_name", "favorite_food")
- `value`: The actual information (e.g., "Alex", "pizza")

### 5. Example Conversation
```javascript
const prompt1 = "Hi! My name is Alex and I love pizza.";
const response1 = await session.prompt(prompt1, {functions});
// Agent calls saveMemory twice:
// - saveMemory({ type: "fact", key: "user_name", value: "Alex" })
// - saveMemory({ type: "preference", key: "favorite_food", value: "pizza" })

const prompt2 = "What's my favorite food?";
const response2 = await session.prompt(prompt2, {functions});
// Agent recalls from memory: "Pizza"
```

## How Memory Works

### Flow Diagram
```
Session 1:
User: "My name is Alex and I love pizza"
  ↓
Agent calls: saveMemory({ type: "fact", key: "user_name", value: "Alex" })
Agent calls: saveMemory({ type: "preference", key: "favorite_food", value: "pizza" })
  ↓
Saved to: agent-memory.json

Session 2 (after restart):
1. Load memories from agent-memory.json
2. Add to system prompt
3. Agent sees: "user_name: Alex" and "favorite_food: pizza"
4. Can use this information in responses

Session 3:
User: "My name is Alex"
  ↓
Agent compares: user_name already = "Alex"
  ↓
No function call! Just acknowledges: "Yes, I remember your name is Alex."
```

## The MemoryManager Class

Located in `memory-manager.js`:
```javascript
class MemoryManager {
  async loadMemories()           // Load from JSON (handles schema migration)
  async saveMemories()           // Write to JSON
  async addMemory()              // Unified method for all memory types
  async getMemorySummary()       // Format memories for system prompt
  extractKey()                   // Helper for migration
  extractValue()                 // Helper for migration
}
```

**Benefits:**
- Single unified method for all memory types
- Automatic duplicate detection and prevention
- Automatic value updates when information changes

## Key Concepts

### 1. Structured Memory Format
All memories now use a consistent structure:
```javascript
{
  type: "fact" | "preference",
  key: "user_name",           // Identifier
  value: "Alex",              // The actual data
  source: "user",             // Where it came from
  timestamp: "2025-10-29..."  // When it was saved/updated
}
```

### 2. Intelligent Duplicate Prevention
The agent is trained to:
- **Compare** before saving
- **Skip** if data is identical
- **Update** if value changed
- **Acknowledge** existing memories instead of re-saving

### 3. Persistent State
- Memories survive script restarts
- Stored in JSON file with metadata
- Loaded at startup and injected into prompt

### 4. Memory Integration in System Prompt
Memories are automatically formatted and injected:
```
=== LONG-TERM MEMORY ===

Known Facts:
- user_name: Alex
- location: Paris

User Preferences:
- favorite_food: pizza
- preferred_language: French
```

## Why This Matters

**Without memory:** Agent starts fresh every time, asks same questions repeatedly

**With basic memory:** Agent remembers, but may save duplicates wastefully

**With smart memory:** Agent remembers AND avoids redundant saves by reasoning first

This enables:
- **Personalized responses** based on user history
- **Efficient memory usage** (no duplicate entries)
- **Natural conversations** that feel continuous
- **Stateful agents** that maintain context
- **Automatic updates** when information changes

## Expected Output

**First run:**
```
User: "Hi! My name is Alex and I love pizza."
AI: "Nice to meet you, Alex! I've noted that you love pizza."
[Calls saveMemory twice - new information saved]
```

**Second run (after restart):**
```
User: "What's my favorite food?"
AI: "Your favorite food is pizza! You mentioned that you love it."
[No function calls - recalls from loaded memory]
```

**Third run (duplicate statement):**
```
User: "My name is Alex."
AI: "Yes, I remember your name is Alex!"
[No function call - recognizes duplicate, just acknowledges]
```

**Fourth run (updated information):**
```
User: "I actually prefer sushi now."
AI: "Got it! I've updated your favorite food to sushi."
[Calls saveMemory once - updates existing value]
```

## Reasoning Process

The system prompt explicitly guides the agent through this decision tree:
```
New user statement
    ↓
Compare to existing memories
    ↓
    ├─→ Exact match? → Acknowledge only (no save)
    ├─→ Updated value? → Save to update
    └─→ New information? → Save as new
```

This reasoning-first approach makes the agent more intelligent and efficient with memory operations!