Overview

What is Memory in Compozy?

Compozy's memory system provides persistent context storage for AI agents and workflows, enabling stateful conversations, data caching, and intelligent decision-making. The system supports multiple memory types and automatic lifecycle management to optimize both performance and cost.

Memory integrates seamlessly with agents to maintain conversation history, stores context between workflow executions, and supports dynamic memory allocation through YAML templates.

Core Features

Multiple Memory Types

Token-based, message-count, and buffer memory strategies optimized for different use cases and cost models

Dynamic Key Templates

Use template expressions to create user-specific, session-based, or context-aware memory instances

Automatic Lifecycle Management

TTL-based cleanup, eviction policies, and resource optimization without manual intervention

Privacy & Security

Built-in PII redaction, configurable privacy controls, and secure data handling practices

Memory System Architecture

Loading diagram...

Memory System Components

Memory Manager

The central orchestrator that creates and retrieves memory instances based on resource configurations. Evaluates template expressions and manages the complete lifecycle of memory instances.

Template Engine

Enables dynamic memory keys through Go template syntax, supporting variables like {{.workflow.input.user_id}} for user-specific and context-aware memory allocation.

Memory Instances

Individual memory containers that store conversation messages and context data. Each instance implements specific memory types with automatic cleanup and thread-safe operations.

Redis Storage

High-performance persistent storage layer providing fast key-value operations, atomic updates, TTL-based cleanup, and scalable multi-instance support.

Memory Types

Choose the right memory strategy based on your application needs and cost optimization requirements:

Optimized for LLM integration and cost management

resource: memory
id: conversation_memory
type: token_based
max_tokens: 4000
max_context_ratio: 0.8

1
Smart Token Tracking
Automatically counts tokens in stored messages using the same tokenization as your LLM provider
2
Context Window Optimization
Removes oldest messages when approaching model context limits, ensuring optimal performance
3
Cost Management
Helps control API costs by maintaining token budgets and preventing expensive large context calls
4
Configurable Strategies
Supports different flush strategies for memory management based on usage patterns

Ideal for: Chat applications, LLM integration, conversation history management, token budget optimization

Dynamic Key Templates

Create flexible memory organization using template expressions that adapt to workflow context and user data.

Template keys enable memory isolation and multi-tenancy by creating unique memory instances per user, session, or context. Learn more about template variables.

# User-specific memory for multi-tenant applications
key: "user:{{.workflow.input.user_id}}"

# Session-based memory for temporary contexts
key: "session:{{.session_id}}:conversation"

# Multi-level hierarchy for complex applications
key: "project:{{.project_id}}:agent:{{.agent_id}}"

# Context-aware memory with multiple dimensions
key: "tenant:{{.tenant_id}}:user:{{.user_id}}:chat:{{.chat_id}}"

1
User Isolation
Separate memory instances per user for multi-tenant applications and data privacy
2
Session Management
Temporary memory contexts that expire with user sessions
3
Hierarchical Organization
Multi-level memory organization for complex application structures
4
Context Awareness
Memory keys that adapt based on workflow context and runtime data

privacy:
  enabled: true
  redaction_patterns:
    - name: "email"
      pattern: "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b"
      replacement: "[REDACTED:EMAIL]"
    - name: "phone"
      pattern: "\\b\\d{3}-\\d{3}-\\d{4}\\b"
      replacement: "[REDACTED:PHONE]"

1
Regex-based Redaction
Configurable patterns that automatically identify and redact sensitive information
2
Custom Redaction Rules
Define application-specific patterns for industry-specific data protection needs
3
Automatic PII Removal
Built-in patterns for common personally identifiable information types
4
Secure Storage
Redacted data is stored securely with no way to reverse the redaction process

Security Best Practices

Essential security considerations for production deployments:

1
Key Security
Avoid including sensitive information in memory keys - they may appear in logs and monitoring systems
2
Appropriate TTL Settings
Set TTL values based on data sensitivity and compliance requirements for your industry
3
Privacy Controls
Always enable privacy controls in production environments to prevent accidental PII exposure
4
Access Controls
Implement proper access controls and authentication for memory instance access
5
Monitoring & Auditing
Monitor memory access patterns and maintain audit logs for compliance requirements

Review the complete security guide for comprehensive protection strategies.

Agent Integration

Memory seamlessly integrates with agents to provide persistent context and conversation history.

agents:
  - id: customer_support
    memory:
      - id: conversation_history
        key: "support:{{.workflow.input.conversation_id}}"
      - id: customer_profile
        key: "customer:{{.workflow.input.customer_id}}"

1
Context Persistence
Agents automatically access memory for conversation history and context continuity
2
Multi-Memory Support
Agents can use multiple memory instances for different data types and contexts
3
Dynamic Keys
Memory keys adapt to workflow context, enabling user-specific and session-based isolation
4
Seamless Operations
Memory operations (read, append, clear, flush) are handled automatically by agents

Learn more about agent memory integration in the agent memory documentation.

Common Use Cases

Best Practices

1
Hierarchical Naming
Use consistent patterns like domain:entity:context for clear organization and easy debugging
2
Unique Identifiers
Include necessary identifiers to ensure uniqueness across users, sessions, and contexts
3
Avoid Sensitive Data
Never include sensitive information in keys - they may appear in logs and monitoring systems
4
Keep Keys Short
Use reasonably short keys for better performance and reduced storage overhead