Memory & Context

Understanding how agents remember and use information is crucial for building effective AI workers.

The Context Window

Every message to an agent includes context—information the agent needs to respond appropriately.

What's in the Context Window

┌─────────────────────────────────────────────────────────┐
│                    CONTEXT WINDOW                       │
│                    (e.g., 128K tokens)                  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │ SYSTEM PROMPT                                    │   │
│  │ "You are an IT Helpdesk assistant..."            │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │ MEMORY (Retrieved)                               │   │
│  │ User's laptop: ThinkPad X1 Carbon               │   │
│  │ Previous ticket: VPN issue (resolved)           │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │ CONVERSATION HISTORY                             │   │
│  │ User: My email isn't working                    │   │
│  │ Agent: Let me help you with that...             │   │
│  │ User: It shows a connection error               │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ┌─────────────────────────────────────────────────┐   │
│  │ CURRENT MESSAGE                                  │   │
│  │ User: Is Google having issues today?            │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘

Context Assembly Priority

When context exceeds limits, Deeployd prioritizes:

1. System Prompt - Always included
2. Current Message - Always included
3. Recent Memory - Most relevant facts
4. Recent Conversation - Latest messages
5. Older Context - Summarized or truncated

Memory Types

Deeployd supports different types of memory:

Conversation Memory

Automatic history within a conversation.

// First message
await deeployd.agents.chat({
  agentId: 'agent-123',
  message: 'My name is Sarah'
});

// Same conversation - agent remembers
await deeployd.agents.chat({
  agentId: 'agent-123',
  conversationId: 'conv-456',
  message: 'What is my name?'
});
// Agent responds: "Your name is Sarah"

Behavior:

• Automatic - no configuration needed
• Scoped to conversation
• Cleared when conversation ends

User Memory

Persistent memory tied to a specific user.

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

// Agent can now remember across conversations
// Conversation 1:
// User: "I prefer responses in bullet points"
// Agent: [Saves preference to user memory]

// Conversation 2 (days later):
// Agent: [Retrieves preference, uses bullet points]

Use cases:

• User preferences
• Past issues and resolutions
• Personal context (role, department)

Team Memory

Shared memory across agents in a team.

// Store team knowledge
await deeployd.memory.set({
  teamId: 'team-123',
  key: 'current_outage',
  value: {
    service: 'Email',
    status: 'Investigating',
    startedAt: '2024-01-15T10:00:00Z'
  }
});

// Any agent in the team can access
// Agent receives context: "Note: Email outage in progress"

Use cases:

• Active incidents
• Shared knowledge base
• Team-wide announcements

Knowledge Memory

Structured information the agent can query.

// Add knowledge
await deeployd.memory.addKnowledge({
  agentId: 'agent-123',
  documents: [
    {
      title: 'VPN Setup Guide',
      content: 'To set up VPN...',
      metadata: { category: 'networking' }
    },
    {
      title: 'Password Policy',
      content: 'Passwords must be...',
      metadata: { category: 'security' }
    }
  ]
});

// Agent automatically retrieves relevant knowledge
// User: "How do I set up VPN?"
// Agent: [Retrieves VPN Setup Guide] "To set up VPN..."

Use cases:

• FAQs and documentation
• Product information
• Policies and procedures

Memory Operations

Storing Memory

// Set a specific memory
await deeployd.memory.set({
  scope: 'user',
  userId: 'user-123',
  agentId: 'agent-456',
  key: 'preferred_language',
  value: 'Spanish'
});

// Add to a list
await deeployd.memory.append({
  scope: 'user',
  userId: 'user-123',
  agentId: 'agent-456',
  key: 'past_issues',
  value: { date: '2024-01-15', issue: 'VPN', resolved: true }
});

Retrieving Memory

// Get specific memory
const language = await deeployd.memory.get({
  scope: 'user',
  userId: 'user-123',
  agentId: 'agent-456',
  key: 'preferred_language'
});

// Search memories
const results = await deeployd.memory.search({
  scope: 'user',
  userId: 'user-123',
  query: 'VPN issues',
  limit: 5
});

Deleting Memory

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

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

Memory in System Prompts

Guide how agents use memory:

You are a support agent with memory capabilities.

When users share personal information:
- Remember their name, role, and department
- Remember their device preferences
- Remember past issues and solutions

When retrieving information:
- Check if you know the user before asking basic questions
- Reference past conversations when relevant
- Use their preferences without asking repeatedly

Privacy guidelines:
- Don't share one user's information with another
- Don't remember sensitive data (passwords, tokens)
- Forget information if user requests

Memory Tool

Agents can explicitly manage memory using the Memory tool:

// Agent's internal process
Agent: "User mentioned they work in Marketing"
[Tool Call: memory.set({ key: 'department', value: 'Marketing' })]

Agent: "Let me check what I know about you"
[Tool Call: memory.get({ key: 'department' })]
[Result: 'Marketing']
Agent: "I see you work in Marketing..."

Memory Tool Actions

Action	Description
get	Retrieve a specific memory
set	Store a memory
search	Find relevant memories
list	List all memories for user
delete	Remove a memory

Context Management

Automatic Summarization

Long conversations are automatically summarized:

Original (50 messages):
User: Hi, I need help with...
Agent: Sure, let me...
[... 48 more messages ...]

Summarized:
[Summary: User reported email sync issues on Outlook.
Agent diagnosed the problem as corrupt cache.
Solution: Cleared cache, recreated profile.
User confirmed issue resolved.]

Manual Context Control

// Start fresh conversation (no history)
await deeployd.agents.chat({
  agentId: 'agent-123',
  message: 'New topic',
  conversationId: null // New conversation
});

// Continue with specific context
await deeployd.agents.chat({
  agentId: 'agent-123',
  message: 'Continue',
  context: {
    summary: 'Previous discussion about X',
    relevantFacts: ['Fact 1', 'Fact 2']
  }
});

Best Practices

What to Remember

✅ Do remember:

• User preferences (communication style, format)
• Technical details (devices, systems they use)
• Past issues and resolutions
• Role and department
• Ongoing projects or concerns

❌ Don't remember:

• Passwords or credentials
• Sensitive personal data
• Temporary information
• Confidential business data

Memory Hygiene

// Periodic cleanup
await deeployd.memory.cleanup({
  agentId: 'agent-123',
  olderThan: '180d', // Remove memories older than 180 days
  excludeKeys: ['preferences'] // Keep certain memories
});

// User-initiated forget
// User: "Forget everything you know about me"
await deeployd.memory.clear({
  scope: 'user',
  userId: 'user-123'
});

Privacy Considerations

1. Inform users - Let them know what's remembered
2. Provide control - Let users delete their data
3. Limit scope - Only remember what's needed
4. Secure storage - Memory is encrypted at rest
5. Audit access - Log memory operations

Troubleshooting

Agent Doesn't Remember

Check:

1. Memory enabled on agent?
2. Same userId across conversations?
3. Memory retention not expired?
4. Memory actually stored (not just conversation)?

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

Context Too Long

Symptoms: Error about context length or truncated responses

Solutions:

1. Enable automatic summarization
2. Clear old conversation history
3. Reduce system prompt length
4. Use knowledge search instead of loading all docs

---

Next: Explore The Basics to learn more about building agents.