Memory Management

Memory Management

Tiered memory system that makes an AI agent a continuous collaborator across sessions.

Architecture

The memory system has two tiers, configurable per project:

HOT CACHE (always loaded at boot)
├── <primer_file>             ← Role, identity, constraints
├── <boot_digest_file>        ← Tactical status, active tasks
├── <boot_contract_file>      ← Immutable constraints
└── <snapshot_file>           ← Cognitive Hologram (1-line per file)

SEMANTIC CACHE (fast lookup, loaded on demand)
├── <summary_cache_file>      ← RLM summaries for project specific key content, documentation , etc. 
└── <tool_cache_file>         ← RLM summaries for plugins/skills/scripts/tools

VECTOR STORE (semantic search, loaded on demand)
└── <vector_db_backend>       ← e.g. ChromaDB via vector-db plugin

DEEP STORAGE (loaded on demand)
├── <domain_data_dir>/        ← E.g. Research, topics
│   └── {topic}/analysis.md   ← Deep dives
├── <design_docs_dir>/        ← E.g. ADRs, RFCs
├── <governance_dir>/         ← E.g. Protocols, playbooks
├── <vault_dir>/              ← Linked knowledge graph (e.g. Obsidian)
└── <traces_file>             ← Persistent external logging (e.g. HuggingFace)

Projects define their own file paths for each slot. The pattern is universal and projects may omit or add tiers depending on their complexity.

Lookup Flow

Query arrives → 
1. Check hot cache (boot files)         → Covers ~90% of context needs
2. Check topics directory               → Deep knowledge by subject
3. Check decisions directory            → Architecture decisions  
4. Query semantic cache (if available)  → Tool/script discovery
5. Ask user                             → Unknown? Learn it.

Promotion / Demotion Rules

Promote to Hot Cache when:

• Knowledge is referenced in 3+ consecutive sessions
• It's critical for active work (current spec, active protocol)
• It's a constraint or identity anchor

Demote to Deep Storage when:

• Spec/feature is completed and merged
• Governing document is superseded by newer version
• Topic research is concluded
• Technical decision is ratified (move from draft to archive)

What Goes Where

Session Memory Workflow

At Session Start (Boot)

1. Load hot cache files in order
2. Integrity check validates snapshot
3. If snapshot stale → flag for refresh at session end

During Session

• New learning → Write to <domain_data_dir>/{topic}/
• New decision → Create design document draft
• New tool → Register in tool inventory
• Correction → Update relevant file + note in disputes log if contradicting

At Session End (Seal)

1. Update snapshot file with new content
2. Seal validates no drift since last audit
3. Persist traces to external storage (if configured)

Conventions

• Hot cache target: ~200 lines total across boot files
• Snapshot: 1 sentence per file, machine-readable
• Topic folders: lowercase-hyphens/
• Document numbering: 3-digit, sequential
• Always capture corrections and contradictions in a disputes log

Configuration

Projects configure the memory system by setting file paths in their project-specific plugin. Example env vars: