Memory Architecture

3-tier memory architecture aligned with arxiv:2602.20478 "Codified Context: Infrastructure for AI Agents in a Complex Codebase"

Paper Overview

The paper "Codified Context: Infrastructure for AI Agents in a Complex Codebase" introduces a framework for managing context in large software projects. CCO implements this architecture with a 3-tier memory system that balances accessibility, specialization, and persistence.

Key Paper Insights

  • Context should be codified, not embedded in prompts
  • Memory tiers enable selective context loading based on task scope
  • Agent interoperability requires standardized context interfaces
  • Long-term memory supports project continuity across sessions

CCO's architecture directly maps to the paper's reference implementation, providing:

  • Constitution-level hot memory (AGENTS.md, CLAUDE.md)
  • Role-based specialized skills via trigger patterns
  • AOMA SQLite store for persistent cross-project memory
  • MCP tools for external agent context access

3-Tier Memory Architecture

Tier 1: Hot Memory (Always Loaded)

Constitution-level knowledge - loaded for every task automatically

yaml 
hot_memory:
  - AGENTS.md      # Agent definitions and capabilities
  - CLAUDE.md      # Project-specific instructions
  - .claude/       # Claude-specific configuration

These files define the project's identity and constraints. They are always present in context, establishing the "constitution" that all agent actions must respect.

Tier 2: Specialized Skills

Domain-expert agents with trigger-based selection

Code Roles

  • implementer
  • planner
  • reviewer
  • architect
  • debugger

Domain Experts

  • security-reviewer
  • test-engineer
  • performance-analyst
  • database-expert
  • devops-engineer

Specialists

  • debugger
  • security-researcher
  • observability-expert
  • codebase-analyst
  • api-designer
yaml 
trigger_patterns:
  - pattern: "fix.*bug|debug|error"
    agent: debugger
  - pattern: "security|vulnerability|auth"
    agent: security-reviewer
  - pattern: "test|coverage|pytest"
    agent: test-engineer
  # ... 19 total agents with unique triggers

The choose_role() function matches task characteristics against trigger patterns to select the optimal agent.

Tier 3: Cold Memory (On-Demand)

Persistent knowledge loaded via MCP tools when needed

yaml 
cold_memory:
  .context/:
    - architecture.md    # System design and components
    - decisions.md        # Architectural decision log
    - known-issues.md     # Recurring bugs and mitigations
    - deployment.md       # Install and operation notes

  AOMA_store:
    backend: sqlite
    path: ~/.codified-orchestrator/memory.db
    tools:
      - memory_ingest
      - memory_query
      - memory_search
      - memory_consolidate

Cold memory is loaded only when relevant to the current task, minimizing token overhead while preserving project knowledge.

Why This Architecture?

Benefit Implementation
Reduces Token Overhead Only hot memory is always loaded. Cold memory loads on-demand via MCP tools.
Enables Agent Interoperability Standardized trigger patterns and context interfaces allow agents to work together.
Supports Long-term Project Memory AOMA SQLite store persists across sessions, preserving decisions and learnings.
Matches Paper Reference Implementation CCO's architecture directly maps to the paper's 3-tier model with AOMA as the persistence layer.

Context Retrieval Flow

When a task arrives, CCO follows this flow to build the context bundle:

ascii 
┌─────────────────────────────────────────────────────────────────┐
│                         TASK INPUT                               │
│  "Fix the authentication bug in user login flow"                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    STEP 1: choose_role()                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Match task against trigger patterns:                     │   │
│  │   "fix.*bug|debug" → debugger agent                     │   │
│  │   "auth.*login" → security-reviewer agent               │   │
│  │ Selected: debugger (primary), security-reviewer (review)  │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│              STEP 2: build_context_bundle()                      │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ HOT (always):                                           │   │
│  │   + AGENTS.md - agent definitions                       │   │
│  │   + CLAUDE.md - project instructions                    │   │
│  │                                                        │   │
│  │ SPECIALIZED (role-based):                              │   │
│  │   + resources/debugger.md - debugger prompts           │   │
│  │   + resources/security-reviewer.md - security patterns  │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│              STEP 3: MCP tools for deep access                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ find_relevant_context(query="auth implementation")     │   │
│  │   → returns architecture.md, known-issues.md           │   │
│  │                                                        │   │
│  │ memory_query(query="previous auth fixes")              │   │
│  │   → returns AOMA distilled insights                    │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    CONTEXT BUNDLE                               │
│  Hot + Specialized + Cold memories combined                    │
│  Token-efficient, task-relevant context ready                   │
└─────────────────────────────────────────────────────────────────┘
ℹ️

The context retrieval is progressive - hot memory loads instantly, specialized skills activate based on role, and cold memory fetches only when MCP tools are invoked. This minimizes token usage while ensuring all relevant context is available.

AOMA: Adaptive Organizational Memory Architecture

AOMA is CCO's long-term memory store, aligned with the paper's research on agent memory systems (arxiv:2602.20478).

AOMA Features

  • SQLite-backed persistence - Durable storage across sessions
  • Memory consolidation - Raw observations convert to distilled insights
  • Multi-project support - Separate memory spaces per project
  • MCP integration - Access via standardized tools
  • Status filtering - active, raw, archived, failed_consolidation

Memory Status States

Status Description
raw Freshly ingested observations, unprocessed
active Consolidated insights, ready for retrieval
archived Older memories no longer actively referenced
failed_consolidation Memories that failed to consolidate properly
↑↓ Navigate Enter Select Esc Close