L2 - Memory

The Memory layer (L2) manages agent state, context, and persistence across different time scales and scopes.

---

Overview

The Memory layer provides structured storage and retrieval mechanisms for agent context, enabling agents to maintain state across interactions and make informed decisions based on past experiences.

---

Memory Types

Working Memory

Scope: Current request
Persistence: None
Temporary context for ongoing tasks

Short-term Memory

Scope: Session
Persistence: Session duration
Conversation and interaction history

Long-term Memory

Scope: Agent lifetime
Persistence: Persistent
Learned patterns and preferences

Episodic Memory

Scope: Specific events
Persistence: Selective
Important experiences and outcomes

---

Key Requirements

Storage & Retrieval

Requirement	Description
Working Memory	Implement in-memory context for current operations
TTL Expiration	Support time-based automatic cleanup
Vector Search	Enable semantic similarity search for retrieval
Atomic Operations	Provide read-modify-write guarantees

Security & Privacy

Requirement	Description
No Plaintext Secrets	Never store credentials without encryption
Audit Logging	Log all write operations for compliance
Size Limits	Implement eviction policies for memory bounds
Concurrent Access	Handle multi-threaded access safely

---

Memory Schema

Memory Entry

{
  "id": "memory-uuid",
  "type": "short_term|long_term|episodic",
  "created_at": "ISO8601",
  "expires_at": "ISO8601",
  "content": {
    "text": "User prefers concise responses",
    "embedding": [0.1, 0.2, ...]
  },
  "metadata": {
    "source": "conversation",
    "confidence": 0.95,
    "tags": ["preference", "style"]
  },
  "access_count": 42,
  "last_accessed": "ISO8601"
}

---

Eviction Policies

LRU (Least Recently Used)

{
  "eviction_policy": {
    "type": "lru",
    "max_size_mb": 100,
    "max_entries": 1000
  }
}

TTL (Time-To-Live)

{
  "eviction_policy": {
    "type": "ttl",
    "default_ttl_seconds": 3600,
    "max_ttl_seconds": 86400
  }
}

---

Vector Search

Semantic Retrieval

{
  "query": {
    "text": "What are the user's preferences?",
    "embedding": [0.1, 0.2, ...],
    "top_k": 5,
    "similarity_threshold": 0.8,
    "filters": {
      "type": "long_term",
      "tags": ["preference"]
    }
  }
}

Response

{
  "results": [
    {
      "memory_id": "uuid",
      "similarity": 0.95,
      "content": {...}
    }
  ],
  "total_results": 5
}

---

Partitioning

Context-based Partitioning

{
  "partitions": {
    "user_context": {
      "max_size_mb": 50,
      "ttl_seconds": 86400
    },
    "system_context": {
      "max_size_mb": 20,
      "ttl_seconds": 3600
    },
    "temporary": {
      "max_size_mb": 10,
      "ttl_seconds": 300
    }
  }
}

---

Best Practices

1. Use Appropriate Memory Types: Match memory type to data lifespan
2. Implement Vector Search: Enable semantic retrieval for better context
3. Set Realistic TTLs: Balance memory usage with context needs
4. Monitor Memory Usage: Track growth and eviction rates
5. Secure Sensitive Data: Encrypt PII and use proper access controls
6. Implement Snapshots: Enable debugging and rollback capabilities

---

Related Layers

• L1 - Runtime: Manages memory resource quotas
• L3 - Capabilities: May access memory for context
• L4 - Reasoning: Queries memory for decision-making
• Specification: Full requirements for L2 Memory

---

© 2026 IbIFACE — CC BY 4.0