AI Agent Memory System Blueprint

Three Layers

• Fact: Stable profile — name, language, preferred tools; YAML for structured lookup
• Episodic: One record per line — decisions, pitfalls, lessons; filter by tags, never load all
• Scratchpad: Current progress and to-dos; hands off across sessions, cleared when done

How They Work Together

Core principle: load on demand. CLAUDE.md is only the routing entry — it stores no memory itself.

startup   → load fact.yml (who you are)
in-task   → read/write scratchpad.md (what you're doing now)
            ↓ when history is needed
            query episodic.jsonl (what happened before)
done      → promote key decisions to episodic.jsonl, clear scratchpad
            update fact.yml if a preference changed

Memory Strength Formula

Once the episodic layer holds hundreds of records, strength decides what surfaces and what fades (below threshold → flagged archivable, never deleted).

strength = base(importance / 10)
         + retrieval(count * 0.08)
         + association(edges * 0.05)
         - decay(weeks * 0.03)

Bootstrap in 3 Steps (10 min)

# 1. Create the memory dir and fact layer
mkdir -p memory
cat > memory/fact.yml << 'EOF'
user:
  name: "Your name"
  language: "English"
  timezone: "Asia/Taipei"
  preferences:
    tech_stack: ["your usual stack"]
EOF

# 2. Create the scratchpad layer
cat > memory/scratchpad.md << 'EOF'
# Scratchpad - current task
EOF

# 3. Add memory routing to CLAUDE.md
## Memory routing
# - preferences/config: memory/fact.yml
# - task scratchpad: memory/scratchpad.md

Full design: the three-layer AI agent memory architecture →