Memory

Memory enables agents to remember information across conversations, creating more personalized and context-aware experiences.

Why Memory Matters

Without memory:

Conversation 1:
User: "My laptop is a MacBook Pro M3"
Agent: "Got it!"

Conversation 2 (next day):
User: "My laptop is running slow"
Agent: "What kind of laptop do you have?"  ← Forgot!

With memory:

Conversation 1:
User: "My laptop is a MacBook Pro M3"
Agent: "Got it, I'll remember that!"

Conversation 2 (next day):
User: "My laptop is running slow"
Agent: "I see you're using a MacBook Pro M3. Let me help..."  ← Remembers!

Memory Types

Conversation Memory

Automatic within a single conversation.

• Scope: Single conversation
• Lifetime: Until conversation ends
• Setup: Automatic, no configuration

// Same conversation - automatic memory
const r1 = await client.agents.chat({
  agentId: 'agent-123',
  message: 'My name is Sarah'
});

const r2 = await client.agents.chat({
  agentId: 'agent-123',
  conversationId: r1.conversationId,
  message: 'What is my name?'
});
// Agent knows: "Sarah"

User Memory

Persists across conversations for a specific user.

• Scope: Per user, per agent
• Lifetime: Configurable (default 90 days)
• Setup: Enable in agent config

// Enable user memory
await client.agents.update({
  agentId: 'agent-123',
  memory: {
    userMemory: {
      enabled: true,
      retention: '90d'
    }
  }
});

// Conversation 1
await client.agents.chat({
  agentId: 'agent-123',
  userId: 'user-456',
  message: 'I prefer bullet point responses'
});

// Conversation 2 (different session)
await client.agents.chat({
  agentId: 'agent-123',
  userId: 'user-456',  // Same user
  message: 'Explain how VPN works'
});
// Agent uses bullet points because it remembers preference

Team Memory

Shared across all agents in a team.

• Scope: All agents in team
• Lifetime: Until deleted
• Setup: Enable at team level

// Store team-wide knowledge
await client.memory.set({
  scope: 'team',
  teamId: 'team-123',
  key: 'current_outage',
  value: {
    service: 'Email',
    status: 'investigating',
    eta: '2 hours'
  }
});

// Any agent in the team sees this
// "Note: We're currently investigating an Email outage..."

Knowledge Memory

Structured information the agent can search and reference.

• Scope: Per agent
• Lifetime: Until deleted
• Setup: Upload documents or add entries

// Add knowledge
await client.memory.addKnowledge({
  agentId: 'agent-123',
  documents: [
    {
      title: 'VPN Setup Guide',
      content: 'To set up VPN, first install...',
      metadata: { category: 'networking', version: '2.0' }
    }
  ]
});

// Agent can now answer VPN questions from this knowledge

Using the Memory Tool

Agents can explicitly use memory through the Memory tool:

Storing Information

User: "My employee ID is E12345"

Agent thinks: "I should remember this for future reference"
[Tool Call: memory.set]
  key: "employee_id"
  value: "E12345"

Agent: "Got it! I've saved your employee ID E12345."

Retrieving Information

User: "What's my employee ID?"

Agent thinks: "I should check if I have this stored"
[Tool Call: memory.get]
  key: "employee_id"
[Result: "E12345"]

Agent: "Your employee ID is E12345."

Searching Memories

User: "What do you know about me?"

Agent thinks: "Let me search all memories for this user"
[Tool Call: memory.search]
  query: "user preferences and information"
[Results: { employee_id: "E12345", laptop: "MacBook Pro M3", department: "Engineering" }]

Agent: "Here's what I know about you:
- Employee ID: E12345
- Laptop: MacBook Pro M3
- Department: Engineering"

Memory API

Set Memory

await client.memory.set({
  scope: 'user',
  userId: 'user-456',
  agentId: 'agent-123',
  key: 'preferences',
  value: {
    responseStyle: 'bullet_points',
    timezone: 'America/New_York'
  }
});

Get Memory

const value = await client.memory.get({
  scope: 'user',
  userId: 'user-456',
  agentId: 'agent-123',
  key: 'preferences'
});

Search Memories

const results = await client.memory.search({
  scope: 'user',
  userId: 'user-456',
  agentId: 'agent-123',
  query: 'laptop preferences',
  limit: 5
});

List All Memories

const memories = await client.memory.list({
  scope: 'user',
  userId: 'user-456',
  agentId: 'agent-123'
});

Delete Memory

// Delete specific memory
await client.memory.delete({
  scope: 'user',
  userId: 'user-456',
  agentId: 'agent-123',
  key: 'temporary_note'
});

// Clear all memories for user
await client.memory.clear({
  scope: 'user',
  userId: 'user-456',
  agentId: 'agent-123'
});

Memory in System Prompts

Guide how agents use memory:

## Memory Guidelines

You have the ability to remember information across conversations.

**What to remember:**
- User's name, role, and department
- Device information (laptop, phone models)
- Communication preferences
- Past issues and their resolutions
- Any explicitly requested preferences

**What NOT to remember:**
- Passwords or credentials
- Temporary information
- Sensitive personal data
- Information user asks to forget

**Using memory:**
- Check memory at the start of conversations for context
- Save important information proactively
- Reference past interactions naturally
- Update outdated information when you learn it's changed

**Example behaviors:**
- "I see you mentioned last time you're using a MacBook Pro..."
- "Based on your preference for brief responses..."
- "I remember you had a similar issue with VPN last month..."

Memory Scopes Comparison

Scope	Persists Across Sessions	Shared With	Use Case
Conversation	No	Same conversation	Short-term context
User	Yes	Same user + agent	Personalization
Team	Yes	All team agents	Shared knowledge
Knowledge	Yes	Same agent	Reference docs

Knowledge Base

Adding Documents

// Add a document
await client.memory.addKnowledge({
  agentId: 'agent-123',
  documents: [{
    title: 'Employee Handbook',
    content: '... full text ...',
    metadata: {
      category: 'HR',
      version: '2024.1',
      lastUpdated: '2024-01-15'
    }
  }]
});

Adding from URL

// Import from URL
await client.memory.addKnowledgeFromUrl({
  agentId: 'agent-123',
  url: 'https://docs.acme.com/handbook.pdf',
  metadata: { category: 'HR' }
});

Querying Knowledge

// Search knowledge base
const results = await client.memory.searchKnowledge({
  agentId: 'agent-123',
  query: 'vacation policy',
  limit: 3
});

Managing Knowledge

// List knowledge entries
const entries = await client.memory.listKnowledge({
  agentId: 'agent-123',
  category: 'HR'
});

// Delete knowledge entry
await client.memory.deleteKnowledge({
  agentId: 'agent-123',
  knowledgeId: 'knowledge-123'
});

Privacy & Compliance

User Control

Allow users to manage their data:

// User requests: "Forget everything about me"
await client.memory.clear({
  scope: 'user',
  userId: 'user-456'
});

Data Retention

Configure automatic cleanup:

await client.agents.update({
  agentId: 'agent-123',
  memory: {
    userMemory: {
      enabled: true,
      retention: '90d',  // Auto-delete after 90 days
      autoCleanup: true
    }
  }
});

Audit Trail

Track memory operations:

const logs = await client.memory.getAuditLog({
  scope: 'user',
  userId: 'user-456',
  agentId: 'agent-123',
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

Best Practices

What to Remember

// ✅ Good things to remember
- User preferences (communication style, timezone)
- Technical context (devices, software versions)
- Role and department
- Past issues and resolutions
- Explicit requests ("Remember that...")

// ❌ Don't remember
- Passwords or credentials
- Credit card numbers
- Highly sensitive personal data
- Temporary/one-time information

Memory Hygiene

// Periodic cleanup
await client.memory.cleanup({
  agentId: 'agent-123',
  olderThan: '180d',
  excludeKeys: ['preferences', 'department']
});

Handling Conflicts

// When user provides new info that conflicts
User: "Actually, I got a new laptop. It's a ThinkPad X1"

Agent: [Updates memory]
[Tool: memory.set, key: "laptop", value: "ThinkPad X1"]

Agent: "Got it! I've updated your laptop info to ThinkPad X1."

Troubleshooting

Memory Not Working

1. Is memory enabled?

   const agent = await client.agents.get('agent-123');
   console.log(agent.memory); // Check if enabled

2. Is userId provided?

   // Must include userId for user memory
   await client.agents.chat({
     agentId: 'agent-123',
     userId: 'user-456', // Required!
     message: '...'
   });

3. Check retention settings

   // Memory might have expired
   const memory = await client.memory.get({...});
   console.log(memory.createdAt, memory.expiresAt);

Memory Not Retrieved

// Debug: List all memories
const memories = await client.memory.list({
  scope: 'user',
  userId: 'user-456',
  agentId: 'agent-123'
});
console.log(memories);

---

Next: Learn about Templates to save and reuse agent configurations.