True Learning Architecture - How Agents Actually Get Smarter
The real architecture for AI agent learning, not just data storage
🧠 True Learning Architecture
The Problem We're Solving
Storing 10,000 decisions is useless if agents can't access them efficiently. The goal isn't to KEEP decisions - it's to LEARN from them.
Human Memory Analogy
You don't remember every meal you ate.
But you learned "I'm allergic to shellfish" once and NEVER forgot.
That single rule replaced thousands of:
- "I ate shrimp, felt sick"
- "I ate lobster, felt sick"
- "I ate crab, felt sick"
→ DISTILLED TO: "Avoid shellfish"
The Pyramid of Intelligence
┌─────────────────┐
│ CORE RULES │ ~20 items
│ (Always loaded) │ ~500 tokens
│ "Never use │
│ rootDir..." │
└────────┬────────┘
│
┌────────▼────────┐
│ PATTERN LIBRARY │ ~100 items
│ (Loaded on task) │ ~2000 tokens
│ "For forms, use │
│ reactive..." │
└────────┬────────┘
│
┌────────▼────────┐
│ SIMILAR DECISIONS│ 3-5 items
│ (Semantic search) │ ~500 tokens
│ "Last time we │
│ did X..." │
└────────┬────────┘
│
┌──────────────▼──────────────┐
│ RAW DECISIONS │ 10,000+ items
│ (Archive/Training) │ NOT loaded
│ Only for: │
│ - Auditing │
│ - Pattern mining │
│ - Future fine-tuning │
└─────────────────────────────┘
What Gets Loaded Per Task (~3000 tokens max)
┌─────────────────────────────────────────────────────────────┐
│ CONTEXT INJECTION FOR: "Fix the build error in auth module" │
├─────────────────────────────────────────────────────────────┤
│ │
│ 🔴 CORE RULES (always loaded, ~500 tokens) │
│ ├─ Never use rootDir in tsconfig.lib.json │
│ ├─ Always export through src/index.ts │
│ ├─ Use nx reset when cache issues │
│ └─ Check path mappings in tsconfig.base.json │
│ │
│ 🟡 RELEVANT PATTERNS (task-matched, ~1000 tokens) │
│ ├─ Build errors: 80% are path/export issues │
│ ├─ Auth module: Uses @libs-core/auth-core │
│ └─ Pattern: Check imports before code │
│ │
│ 🟢 SIMILAR DECISIONS (semantic search, ~500 tokens) │
│ ├─ "Fixed auth build by adding to index.ts" (conf: 0.98) │
│ ├─ "Module not found → path mapping issue" (conf: 0.95) │
│ └─ "Auth integration required shared types" (conf: 0.92) │
│ │
│ 📊 CURRENT SESSION (what we're doing now, ~500 tokens) │
│ └─ Working on: AI infrastructure rebuild │
│ │
└─────────────────────────────────────────────────────────────┘
│
▼
TOTAL: ~2500 tokens
(Fits easily in context)
The Learning Pipeline
┌─────────────────────────────────────────────────────────────────┐
│ LEARNING PIPELINE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. CAPTURE │
│ └─ Raw decision logged via MCP │
│ │
│ 2. VALIDATE (24-48 hours) │
│ └─ Did it work? Track outcome │
│ └─ If failed: Mark as anti-pattern │
│ └─ If succeeded: Increase confidence │
│ │
│ 3. REFERENCE TRACKING │
│ └─ How many times was this decision referenced? │
│ └─ High reference = important pattern │
│ │
│ 4. DISTILLATION (weekly LLM job) │
│ └─ Group similar decisions │
│ └─ Extract common pattern │
│ └─ Create rule: "When X, do Y because Z" │
│ │
│ 5. PROMOTION │
│ └─ Pattern used 10+ times → Core Rule │
│ └─ Decision referenced 5+ times → Pattern │
│ └─ Decision never referenced → Archive candidate │
│ │
│ 6. ARCHIVE (smart, not time-based) │
│ └─ Archive when: Pattern extracted AND outcome known │
│ └─ Keep when: High confidence OR frequently referenced │
│ └─ Never archive: Anti-patterns (learn from failures) │
│ │
└─────────────────────────────────────────────────────────────────┘
Archive Criteria (Revised)
❌ DON'T Archive Based On:
- Age alone (90 days is arbitrary)
- Session number
- File count
✅ DO Archive When:
- Pattern has been extracted from the decision
- Outcome is known (success/failure recorded)
- Not referenced in 30+ days AND confidence < 0.9
- Similar decisions exist (keep highest confidence)
🔒 NEVER Archive:
- Anti-patterns (failures we must remember)
- Architectural decisions (rare but critical)
- Decisions with confidence > 0.95
- Decisions referenced 5+ times
Data Flow
┌─────────────────┐
│ MCP log_decision│
└────────┬────────┘
│
▼
┌─────────────────┐
│ Raw Decisions │ ai-mcp-dev.decisions
│ (Hot Storage) │
└────────┬────────┘
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ Outcome │ │ Reference │ │ Embedding │
│ Tracking │ │ Counter │ │ Generation│
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │
└────────────────┼────────────────┘
│
▼
┌─────────────────┐
│ Pattern Mining │ Weekly LLM job
│ (Distillation) │
└────────┬────────┘
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ Core Rules│ │ Patterns │ │ Archive │
│ (~20) │ │ (~100) │ │ (10K+) │
└───────────┘ └───────────┘ └───────────┘
ai-agents. ai-agents. ai-agents.
core_rules patterns archived_decisions
Implementation Priority
Phase 1: Smart Context Loading (NOW)
- Implement relevance scoring for decisions
- Build semantic search with embeddings
- Create core rules extraction from high-confidence decisions
- Limit preflight to ~3000 tokens
Phase 2: Learning Pipeline (NEXT)
- Outcome tracking (did it work?)
- Reference counting (how often used?)
- Weekly pattern mining job
Phase 3: Intelligent Archive (LATER)
- Archive based on learning status, not age
- Keep anti-patterns forever
- Compress archived data
Key Metrics to Track
| Metric | Target | Why It Matters |
|---|---|---|
| Preflight tokens | <3000 | Context efficiency |
| Pattern coverage | >80% | Are common scenarios covered? |
| Outcome rate | >70% | Are we tracking if decisions worked? |
| Reference rate | >30% | Are patterns being used? |
| Archive with learning | 100% | Never archive without extracting wisdom |
The Goal
TODAY: FUTURE:
═══════ ═══════
10,000 raw decisions 20 core rules
Never accessed Always loaded
Agents don't learn Agents get smarter
Archive by age Archive after learning
The measure of success isn't how much we store, but how much we learn.