Tiered Memory Architecture for Autonomous Agents

Overview

A deterministic, layered memory engineering framework that replaces naive full-context injection. It organizes agent memory into 4 distinct tiers (Core Injected, Topic Notes, Searchable Session History, and Ephemeral Working Memory), ensuring high signal-to-noise ratio and zero context bloating.

When to Use & When NOT to Use

When to Use

• Agent system design where memory exceeds 5,000 characters and causes context degradation.
• Multi-session persistence: preserving stable user preferences and environmental facts across restarts.
• Preventing memory drift and hallucinatory rule overrides.

When NOT to Use

• Short, one-shot CLI tasks with no cross-session continuity requirements.
• Raw logging or storing multi-megabyte datasets (store in database / file assets instead).

The 4-Tier Memory Hierarchy

Common Pitfalls

1. Saving transient task progress to L1 Core Memory: Never record PR numbers, bug fixes, or step counts to MEMORY.md; they become stale in 7 days. Use session search instead.
2. Imperative phrasing in memory: Write memories as declarative facts ("User prefers concise tables" ✓), not directives ("Always output tables" ✗), to avoid overriding runtime instructions.
3. Memory Sprawl: When L1 exceeds 70% capacity, trigger automatic consolidation: merge duplicates, prune obsolete entries, and offload detailed guides to L2 notes.

Verification Checklist

• L1 Core Memory is ≤ 70% of configured char budget.
• No temporary TODO state or session logs exist in MEMORY.md.
• Topic notes in notes/ contain structured YAML frontmatter.
• Database FTS5 index is synchronized with message store.