Memory System

Understanding Atlas’s hierarchical memory system for context and learning

Memory System

Atlas provides a sophisticated hierarchical memory system that allows agents and sessions to learn from past experiences and maintain context across interactions.

Memory Hierarchy

Atlas memory operates at three levels, each serving different purposes:

1. Agent Memory

Individual agent experiences during execution:

• Short-term working memory
• Task-specific context
• Tool usage patterns
• Recent interactions

2. Session Memory

Workflow-level context shared across agents:

• Session goals and objectives
• Inter-agent communication
• Accumulated insights
• Decision history

3. Workspace Memory

Long-term organizational knowledge:

• Learned patterns and best practices
• Historical data and trends
• Shared knowledge base
• Cross-session insights

Memory Types

Atlas supports five types of memory, each optimized for different kinds of information:

Episodic Memory

What: Specific events and experiences Used for: Recalling past interactions, learning from history Example: “Last Tuesday, customer X reported issue Y”

memory:
  workspace:
    memory_types:
      episodic:
        enabled: true
        max_age_days: 90
        max_entries: 1000

Semantic Memory

What: Facts, concepts, and general knowledge Used for: Building domain understanding Example: “Product SKU-123 is our best seller”

memory:
  workspace:
    memory_types:
      semantic:
        enabled: true
        max_age_days: 365
        max_entries: 2000

Procedural Memory

What: How to perform tasks Used for: Remembering successful approaches Example: “To process refunds, first verify the order…”

memory:
  workspace:
    memory_types:
      procedural:
        enabled: true
        max_age_days: 180
        max_entries: 500

Working Memory

What: Current task context Used for: Active problem-solving Example: Current conversation state, immediate goals

memory:
  agent:
    memory_types:
      working:
        enabled: true
        max_age_hours: 2
        max_entries: 50

Contextual Memory

What: Situational awareness Used for: Understanding current environment Example: User preferences, session parameters

memory:
  session:
    memory_types:
      contextual:
        enabled: true
        max_age_hours: 24
        max_entries: 100

Configuration

Basic Memory Setup

Enable memory for your workspace:

version: "1.0"

workspace:
  name: "memory-enabled-workspace"
  
atlas:
  memory:
    enabled: true
    storage: "local"  # or "cloud"
    
agents:
  assistant:
    type: "llm"
    config:
      memory_enabled: true
      memory_scope: "session"
      context_window: 10  # Recent memories to include

Advanced Configuration

Fine-tune memory behavior:

atlas:
  memory:
    # Global settings
    default:
      enabled: true
      storage: "local"
      retention:
        max_age_days: 30
        max_entries: 1000
        cleanup_interval_hours: 24
    
    # Streaming for performance
    streaming:
      enabled: true
      batch_size: 10
      flush_interval: "1s"
      background_processing: true
    
    # Scope-specific settings
    agent:
      enabled: true
      context_limits:
        relevant_memories: 5
        past_successes: 2
        past_failures: 1
    
    session:
      enabled: true
      context_limits:
        relevant_memories: 10
        past_successes: 5
        past_failures: 3
    
    workspace:
      enabled: true
      include_in_context: false  # Too broad for agent context
      context_limits:
        relevant_memories: 20

Memory in Action

Example: Customer Support

agents:
  support-agent:
    type: "llm"
    config:
      memory_enabled: true
      memory_scope: "workspace"  # Access all customer history
    
    prompts:
      system: |
        You have access to customer interaction history.
        Use past experiences to provide better support.
        Remember customer preferences and issues.

jobs:
  handle-support:
    config:
      memory:
        enabled: true
        create_memories: true
        memory_tags: ["support", "customer-{customer_id}"]
        
        # What to remember
        memory_extraction:
          - customer_preferences
          - issue_resolutions
          - successful_approaches

Example: Learning System

agents:
  learning-assistant:
    type: "llm"
    config:
      memory_enabled: true
      memory_types: ["episodic", "procedural", "semantic"]
    
    prompts:
      system: |
        Learn from each interaction:
        - Remember what works and what doesn't
        - Build knowledge about user preferences
        - Improve responses based on feedback

jobs:
  adaptive-assistance:
    execution:
      agents:
        - id: "learning-assistant"
          post_execution:
            extract_learnings: true
            learning_categories:
              - "user_preferences"
              - "effective_solutions"
              - "common_issues"

Memory Patterns

1. Context Preservation

Maintain context across a session:

agents:
  context-aware:
    config:
      memory_enabled: true
      memory_scope: "session"
      context_preservation:
        include_all_turns: true
        summarize_after: 10  # Summarize after 10 exchanges

2. Learning from Feedback

Improve based on outcomes:

jobs:
  learning-job:
    config:
      memory:
        track_outcomes: true
        outcome_indicators:
          - "user_satisfaction"
          - "task_completion"
          - "time_to_resolution"
        
        learn_from:
          successes: true
          failures: true
          threshold: 0.8  # Only remember high-confidence learnings

3. Cross-Session Intelligence

Share insights across sessions:

workspace:
  memory:
    cross_session_sharing:
      enabled: true
      share_types: ["procedural", "semantic"]
      privacy_filter: true  # Remove PII
      
      aggregation:
        min_occurrences: 3  # Pattern must occur 3+ times
        confidence_threshold: 0.7

Best Practices

1. Memory Scoping

Choose the right scope:

• Agent: Task-specific, short-term
• Session: Workflow coordination
• Workspace: Long-term organizational knowledge

2. Memory Hygiene

Keep memory clean and relevant:

memory:
  retention:
    max_age_days: 90
    relevance_decay: true  # Older memories become less relevant
    
  cleanup:
    remove_duplicates: true
    consolidate_similar: true
    prune_low_relevance: true

3. Privacy Considerations

Protect sensitive information:

memory:
  privacy:
    anonymize_pii: true
    exclude_patterns:
      - "ssn:*"
      - "credit_card:*"
      - "password:*"
    
    encryption:
      at_rest: true
      algorithm: "AES-256"

4. Performance Optimization

Balance memory with performance:

memory:
  performance:
    lazy_loading: true  # Load memories only when needed
    cache_recent: 100   # Keep recent memories in cache
    index_fields: ["tags", "timestamp", "relevance"]
    
    context_limits:
      max_tokens: 2000  # Don't overwhelm the model
      max_memories: 20

Troubleshooting

Memory Not Persisting

Check configuration:

atlas workspace info --show-memory-config

Verify memory is enabled at all levels:

• Workspace configuration
• Agent configuration
• Job configuration

Context Overload

If agents are confused by too much context:

1. Reduce context_window
2. Increase relevance_threshold
3. Use more specific memory_tags

Performance Issues

For better performance:

1. Enable streaming memory
2. Use appropriate retention policies
3. Index frequently accessed fields
4. Limit context window size

Memory Analytics

Monitor memory usage:

memory:
  analytics:
    enabled: true
    track:
      - memory_size
      - retrieval_time
      - relevance_scores
      - usage_patterns
    
    export_to: "prometheus"  # or "datadog", "custom"

View memory stats:

atlas memory stats --workspace my-workspace
atlas memory search --query "customer issues" --limit 10

Next Steps

• Configure Supervisor Patterns with memory
• Build Custom Agents with specialized memory
• Explore Platform Memory Configuration
• Learn Memory Best Practices