Agent Memory

Overview

Memory in Compozy allows agents to maintain context across workflow steps, sessions, and even between different workflow executions. This enables stateful interactions, personalization, and complex multi-turn conversations. Memory is essential for building AI agents that can remember user preferences, maintain conversation history, and share context between different agents in your workflows.

If you're new to Compozy, start with the Quick Start guide to understand the basics before diving into memory configuration. For a complete understanding of how memory fits into the broader system, see Core Concepts.

Key Features

Memory Architecture

Understanding the memory architecture is crucial for effective implementation. The system uses a layered approach where agents reference memory configurations that resolve to actual storage instances. Learn more about the technical implementation details and storage backend options.

The architecture supports multiple persistence backends with automatic failover and circuit breaker patterns for production reliability.

Memory Configuration

Basic Memory Setup

Configure memory references in your agent:

agents:
  - id: conversational-agent
    config:
      provider: openai
      model: gpt-4-turbo-preview
    instructions: |
      You are a helpful assistant that remembers previous conversations.
      Use context from memory to provide personalized responses.
    memory:
      - id: user_memory           # Memory resource ID
        key: "user:{{.workflow.input.user_id}}"  # Dynamic key
        mode: "read-write"        # Access mode

Memory Reference Structure

Memory references in agent configurations connect agents to memory resources. Each reference specifies which memory resource to use, how to access it, and provides a template key for dynamic memory instances. This follows the same reference pattern used throughout Compozy for connecting resources.

Each memory reference requires:

For more details on memory resource configuration, see the Memory Configuration guide.

Dynamic Key Templates

Memory keys support template expressions that are evaluated at runtime to create unique memory instances. This enables context-aware memory management where different users, sessions, or workflows can have separate memory spaces. The template system is powered by Go templates with Sprig functions, giving you powerful string manipulation and logic capabilities.

Memory keys support template expressions:

memory:
  # User-specific memory
  - id: user_context
    key: "user:{{.workflow.input.user_id}}"

  # Session-based memory
  - id: session_memory
    key: "session:{{.workflow.input.session_id}}"

  # Conversation threads
  - id: conversation
    key: "thread:{{.workflow.input.thread_id}}:{{.workflow.input.user_id}}"

  # Time-based memory
  - id: daily_context
    key: "daily:{{.workflow.input.date}}:{{.workflow.input.user_id}}"

Learn more about available template variables and key design best practices.

Memory Resources

Memory resources define the storage configuration and schema for memory instances. These resources are referenced by agents through memory references and provide the actual storage backend and configuration. Memory resources follow the same resource definition pattern as other Compozy components.

Define memory resources that agents can reference:

# memory/user_memory.yaml
resource: memory
id: user_memory
description: Persistent user context and preferences

config:
  provider: redis
  ttl: 2592000  # 30 days in seconds
  namespace: "compozy:memory:users"

schema:
  type: object
  properties:
    preferences:
      type: object
    history:
      type: array
      items:
        type: object

For a complete guide on memory resource configuration including persistence options, TTL strategies, and privacy controls, see the Memory Configuration documentation. Memory resources are typically stored in the memory/ directory and can be auto-loaded like other resources.

Multiple Memory Contexts

Agents can access multiple memory instances simultaneously, allowing them to maintain different types of context (user profiles, team information, project state) within the same conversation. This pattern is essential for multi-agent systems and complex workflows that need to maintain separate contexts for different aspects of the interaction.

Agents can access multiple memory instances:

agents:
  - id: multi-context-agent
    memory:
      - id: user_profile
        key: "profile:{{.workflow.input.user_id}}"
      - id: team_context
        key: "team:{{.workflow.input.team_id}}"
      - id: project_state
        key: "project:{{.workflow.input.project_id}}"

Each memory instance operates independently with its own eviction policies and TTL settings.

Memory in Action

Conversational Memory

Build conversational agents with context. This example demonstrates how to implement a chat system that maintains conversation history across multiple interactions. For more advanced patterns, see conversational AI patterns:

# Workflow with conversational memory
tasks:
  - id: chat
    type: basic
    $use: agent(local::agents.#(id="chat-agent"))
    action: respond
    with:
      message: "{{.workflow.input.message}}"

agents:
  - id: chat-agent
    memory:
      - id: conversation
        key: "chat:{{.workflow.input.session_id}}"

    actions:
      - id: respond
        prompt: |
          Continue the conversation naturally.
          User message: {{.input.message}}

          Use previous context to maintain conversation flow.
          Reference earlier topics when relevant.

The agent automatically receives the full conversation history as context. To manage token usage in long conversations, consider implementing memory summarization or sliding window patterns.

Memory Lifecycle

Memory Size Considerations

Strategies for managing memory size:

Memory Operations via API

Manage memory through the HTTP API. The memory API provides direct access to memory operations for integration with external systems. For detailed API documentation, see the Memory API reference:

# Write to memory
curl -X POST http://localhost:5001/api/v0/memory/write \
  -H "Content-Type: application/json" \
  -d '{
    "key": "user:123",
    "message": {
      "role": "system",
      "content": "User prefers technical explanations"
    }
  }'

# Read memory
curl http://localhost:5001/api/v0/memory/read?key=user:123

# Clear memory
curl -X POST http://localhost:5001/api/v0/memory/clear \
  -H "Content-Type: application/json" \
  -d '{"key": "user:123"}'

For programmatic access from workflows, use memory tasks instead of direct API calls.

Advanced Patterns

agents:
  - id: adaptive-agent
    memory:
      - id: "{{.workflow.input.memory_type}}_memory"
        key: "{{.workflow.input.memory_type}}:{{.workflow.input.context_id}}"

For more advanced patterns including event-driven memory updates and distributed memory architectures, see the integration patterns guide.

Best Practices

Next Steps