Integration Patterns

Start with the Basics

Memory integration enables stateful AI interactions across your workflows. If you're new to Compozy memory, start with memory overview to understand core concepts, or jump to memory tasks for direct task-based integration.

Overview

Memory integration in Compozy provides three primary patterns for building stateful applications: agent memory integration (the easiest and most common approach), memory tasks (direct workflow integration), and API integration (for external systems). These patterns enable persistent conversations, context management, and intelligent caching using Compozy's declarative YAML configuration - no complex TypeScript implementations required.

Agent Memory Integration

Declarative YAML configuration with automatic context loading - the simplest and most powerful approach

Direct Memory Tasks

Built-in memory task types for explicit memory operations within workflows

API Integration

HTTP API endpoints for external system integration and custom applications

Agent Memory Integration

This is the easiest and most common way to integrate memory - using declarative YAML configuration with automatic context loading and injection. Perfect for conversational AI and most memory-enabled applications.

The fundamental pattern uses a single memory resource with dynamic key templates:

# Define your agent with memory
agents:
  - id: chat_agent
    config:
      $ref: global::models.#(provider=="openai")
      temperature: 0.7

    # Memory configuration - automatic loading and saving
    memory:
      - id: conversation_memory
        key: "user:{{.workflow.input.user_id}}"
        mode: read-write

    instructions: |
      You are a helpful assistant with access to conversation history.
      Use context from previous messages to provide relevant responses.

    actions:
      - id: chat
        prompt: |
          User message: {{.workflow.input.message}}

          Respond naturally using our conversation history for context.

# Use the agent in workflows
tasks:
  - id: handle_chat
    type: basic
    $use: agent(local::agents.#(id="chat_agent"))
    action: chat
    with:
      message: "{{.workflow.input.message}}"

Why This Works

Compozy automatically loads memory context before agent execution and automatically saves new interactions afterward. No manual memory operations needed!

Direct Memory Tasks

For explicit memory control in workflows, use the built-in memory task types. This approach gives you fine-grained control over memory operations and is perfect for complex memory management scenarios.

Memory tasks provide direct access to all memory operations:

tasks:
  # Read existing memory
  - id: load_conversation
    type: memory
    operation: read
    memory_ref: conversation_memory
    key_template: "user:{{.workflow.input.user_id}}"
    outputs:
      history: "{{.output.messages}}"
      message_count: "{{.output.message_count}}"

  # Process with the loaded context
  - id: generate_response
    type: basic
    $use: agent(local::agents.#(id="chat_agent"))
    with:
      message: "{{.workflow.input.message}}"
      context: "{{.tasks.load_conversation.output.history}}"
    outputs:
      response: "{{.output.response}}"

  # Save the new interaction
  - id: save_interaction
    type: memory
    operation: append
    memory_ref: conversation_memory
    key_template: "user:{{.workflow.input.user_id}}"
    payload:
      role: "assistant"
      content: "{{.tasks.generate_response.output.response}}"
      timestamp: "{{now}}"

When to Use Memory Tasks

Use memory tasks when you need explicit control over memory operations, custom memory management logic, or integration with non-agent tasks.

API Integration

For external systems and custom applications, use Compozy's HTTP API endpoints to integrate memory functionality. This pattern is perfect for mobile apps, web frontends, and third-party integrations.

Compozy provides REST API endpoints for all memory operations:

// Read memory
const response = await fetch('/api/v1/memory/read', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    memory_ref: 'conversation_memory',
    key: 'user:12345',
    limit: 50
  })
});
const { messages, message_count } = await response.json();

// Append to memory
await fetch('/api/v1/memory/append', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    memory_ref: 'conversation_memory',
    key: 'user:12345',
    payload: {
      role: 'user',
      content: 'Hello, how are you?',
      timestamp: new Date().toISOString()
    }
  })
});

// Check memory health
const healthResponse = await fetch('/api/v1/memory/health', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    memory_ref: 'conversation_memory',
    key: 'user:12345'
  })
});
const { token_count, status } = await healthResponse.json();

API Authentication

Configure API authentication and rate limiting in your Compozy deployment settings.

Memory Key Design Patterns

Effective memory key patterns are crucial for organizing data and ensuring proper isolation in multi-tenant applications.

User-based patterns provide isolated memory spaces:

# Basic user memory
key: "user:{{.workflow.input.user_id}}"
# Example: user:12345

# User conversation history
key: "user:{{.workflow.input.user_id}}:conversations"
# Example: user:12345:conversations

# User preferences and settings
key: "user:{{.workflow.input.user_id}}:profile"
# Example: user:12345:profile

# Time-based user sessions
key: "user:{{.workflow.input.user_id}}:session:{{.workflow.input.date}}"
# Example: user:12345:session:2024-01-15

Perfect for: Personal assistants, user dashboards, individual account management

Architecture Benefits:

Multiple Integration Paths: Choose the approach that best fits your application needs
Consistent API: All patterns use the same underlying memory system and operations
Security Isolation: Template engine and access controls ensure proper data isolation