Memory & Context

Understanding how agents remember and use information is crucial for building effective AI workers. MeetLoyd implements a sophisticated memory system with enterprise-grade data sovereignty.

Memory Pointer Architecture

MeetLoyd uses a control plane / data plane separation for memory management:

┌──────────────────────────────────────────────────────────────┐
│               MEETLOYD CONTROL PLANE                          │
│                                                               │
│   What we store:                                              │
│   - Memory pointers (paths, not content)                      │
│   - Content hashes (for integrity verification)               │
│   - Sync status and metadata                                  │
│   - Access audit logs                                         │
└──────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────┐
│               YOUR DATA PLANE                                 │
│                                                               │
│   What you store (in your S3/GCS/Azure):                     │
│   - Actual conversation messages                              │
│   - Agent memory content                                      │
│   - Team context and knowledge                                │
│   - User preferences and facts                                │
└──────────────────────────────────────────────────────────────┘

This architecture ensures your data never leaves your infrastructure. See Storage Adapters for configuration details.

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 from your storage)             │    │
│  │ 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, MeetLoyd prioritizes:

System Prompt - Always included
Current Message - Always included
Recent Memory - Most relevant facts (via semantic search)
Recent Conversation - Latest messages
Older Context - Summarized or truncated

Memory Types

MeetLoyd supports different types of memory, each stored with pointers:

Conversation Memory

Automatic history within a conversation. Messages are stored in your external storage.

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

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

Storage flow:

Message sent to MeetLoyd
MeetLoyd writes content to your storage (S3/GCS/Azure)
MeetLoyd creates pointer with path and hash
On retrieval, MeetLoyd reads from your storage using pointer

User Memory

Persistent memory tied to a specific user, stored in your infrastructure.

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

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

// Conversation 2 (days later):
// Agent: [Retrieves preference from your storage]

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 client.memory.set({
  teamId: 'team-123',
  key: 'current_outage',
  value: {
    service: 'Email',
    status: 'Investigating',
    startedAt: '2026-01-15T10:00:00Z'
  }
});

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

Storage:

Pointer created in MeetLoyd
Actual JSON stored in your bucket at memories/team/T123/current_outage.json

Knowledge Memory

Structured information with semantic search.

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

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

Storage:

Document content stored in your storage
Embeddings stored alongside (or in vector DB)
MeetLoyd stores pointer with embedding metadata

Memory Scopes

Scope	Description	Stored At	Access
`tenant`	Organization-wide	`memories/tenant/{tenantId}/`	All agents
`app`	App-level	`memories/app/{appId}/`	App agents
`team`	Team shared	`memories/team/{teamId}/`	Team agents
`agent`	Agent-specific	`memories/agent/{agentId}/`	Single agent
`user`	User personal	`memories/user/{userId}/`	User's conversations
`conversation`	Single conversation	`memories/conv/{convId}/`	That conversation

Memory Pointer Structure

Every memory in MeetLoyd is represented by a pointer:

interface MemoryPointer {
  id: string
  tenantId: string

  // Scope hierarchy
  scopeType: 'tenant' | 'app' | 'team' | 'agent' | 'user' | 'conversation'
  teamId?: string
  agentId?: string
  userId?: string

  // Classification
  memoryType: 'conversation_history' | 'agent_memory' | 'team_context' | 'fact' | ...

  // Storage reference (NOT the content)
  storagePath: string           // "memories/team/T123/context.json"
  contentHash: string           // SHA-256 for integrity
  contentSizeBytes: number

  // Embedding metadata
  hasEmbeddings: boolean
  embeddingModel?: string       // "text-embedding-3-small"
  embeddingStoragePath?: string // Where vectors are stored

  // Sync state
  syncStatus: 'synced' | 'pending_write' | 'pending_read'
}

Memory Operations

Storing Memory

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

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

Retrieving Memory

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

// Semantic search (embeddings in your storage)
const results = await client.memory.search({
  scope: 'user',
  userId: 'user-123',
  query: 'VPN issues',
  limit: 5
});

Deleting Memory

// Delete specific memory
await client.memory.delete({
  scope: 'user',
  userId: 'user-123',
  key: 'temporary_note'
});
// Pointer deleted from MeetLoyd
// Data deleted from your storage

// Clear all user memory
await client.memory.clear({
  scope: 'user',
  userId: 'user-123'
});
// All pointers deleted
// All data in memories/user/user-123/* deleted

Context Management

Automatic Summarization

Long conversations are automatically summarized to fit context windows:

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.]

Storage: Summary pointer created, actual summary stored in your bucket.

Context Window Management

interface ConversationPointer {
  // ... other fields

  // Context tracking
  contextWindowTokens: number      // Current usage
  contextWindowLimit: number       // Model limit (e.g., 128K)
  needsSummarization: boolean      // Auto-set when approaching limit

  // Summary pointer
  summaryPointerId?: string        // Points to summary storage
}

Data Flow Diagram

┌────────────────────────────────────────────────────────────────────────┐
│                        Memory Write Flow                                │
├────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  1. Agent generates memory content                                      │
│     │                                                                   │
│     ▼                                                                   │
│  2. Memory Service computes hash (SHA-256)                              │
│     │                                                                   │
│     ▼                                                                   │
│  3. Write to your storage ─────────────────> Your S3/GCS/Azure          │
│     │                                       (encrypted at rest)         │
│     ▼                                                                   │
│  4. Create/update pointer in MeetLoyd DB                                │
│     - Path: "memories/user/U123/preference.json"                        │
│     - Hash: "7f83b166..."                                               │
│     - Size: 245 bytes                                                   │
│     │                                                                   │
│     ▼                                                                   │
│  5. Log access in audit trail                                           │
│                                                                         │
└────────────────────────────────────────────────────────────────────────┘

Privacy & Compliance

Data Residency

Your data stays in your chosen region:

// Configure regional storage
await client.storage.configure({
  storageType: 'gcs',
  connectionConfig: {
    project: 'my-project',
    bucket: 'meetloyd-eu',  // EU bucket
    region: 'europe-west1'
  }
});

// Export user data
const export = await client.memory.export({
  userId: 'user-123',
  format: 'json'
});

// Delete all user data
await client.memory.eraseUser('user-123');
// - All pointers deleted from MeetLoyd
// - All data deleted from your storage
// - Audit log records the erasure

Audit Trail

All memory operations are logged:

interface MemoryAccessLog {
  id: string
  pointerId: string
  accessorType: 'agent' | 'user' | 'system' | 'api'
  accessorId: string
  operation: 'read' | 'write' | 'delete' | 'search' | 'export'
  success: boolean
  accessedAt: Date
}

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 (SSN, credit cards)
Temporary information
Confidential business data without consent

Memory Hygiene

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

// Set retention policies
await client.memory.setRetentionPolicy({
  scope: 'user',
  memoryType: 'conversation_history',
  retentionDays: 90,
  archiveAfterDays: 30,
  autoDelete: true
});

Performance Tips

Use semantic search - Don't load all memories; search for relevant ones
Set appropriate limits - Fetch only what you need
Enable summarization - Keep context windows efficient
Use type filters - Narrow search when you know what you want

Troubleshooting

Agent Doesn't Remember

Check:

Memory enabled on agent?
Same userId across conversations?
Memory retention not expired?
Storage health check passing?

// Debug: Check storage health
const health = await client.storage.healthCheck();

// Debug: List pointers
const pointers = await client.memory.listPointers({
  scope: 'user',
  userId: 'user-123'
});

"Hash mismatch" Error

Data integrity verification failed:

Data may have been modified outside MeetLoyd
Encryption key may have changed
Check for storage corruption

Context Too Long

Solutions:

Enable automatic summarization
Clear old conversation history
Reduce system prompt length
Use knowledge search instead of loading all docs

Next: Learn about Storage Adapters for detailed configuration of your data plane.

Memory Pointer Architecture​

The Context Window​

What's in the Context Window​

Context Assembly Priority​

Memory Types​

Conversation Memory​

User Memory​

Team Memory​

Knowledge Memory​

Memory Scopes​

Memory Pointer Structure​

Memory Operations​

Storing Memory​

Retrieving Memory​

Deleting Memory​

Context Management​

Automatic Summarization​

Context Window Management​

Data Flow Diagram​

Privacy & Compliance​

Data Residency​

Right to Erasure (GDPR)​

Audit Trail​

Best Practices​

What to Remember​

Memory Hygiene​

Performance Tips​

Troubleshooting​

Agent Doesn't Remember​

"Hash mismatch" Error​

Context Too Long​