Progressive Memory

Token-efficient memory system for AI agents. Scan an index first, fetch details on demand. Based on progressive disclosure principles from claude-mem.

The Problem

Traditional memory dumps everything into context:

Load 3500 tokens of history
94% is irrelevant to current task
Wastes attention budget, causes context rot

The Solution

Progressive disclosure: Show what exists first, let the agent decide what to fetch.

Before: 3500 tokens loaded → 200 relevant (6%)
After:  100 token index → fetch 200 needed (100%)

Memory Format

Daily Files (`memory/YYYY-MM-DD.md`)

# 2026-02-01 (AgentName)
 
## Index (~70 tokens to scan)
| # | Type | Summary | ~Tok |
|---|------|---------|------|
| 1 | 🔴 | Auth bug - use browser not CLI | 80 |
| 2 | 🟢 | Deployed SEO fixes to 5 pages | 120 |
| 3 | 🟤 | Decided to split content by account | 60 |
 
---
 
### #1 | 🔴 Auth Bug | ~80 tokens
**Context:** Publishing via CLI
**Issue:** "Unauthorized" even with fresh tokens
**Workaround:** Use browser import instead
**Status:** Unresolved

Long-Term Memory (`MEMORY.md`)

## 📋 Index (~100 tokens)
| ID | Type | Category | Summary | ~Tok |
|----|------|----------|---------|------|
| R1 | 🚨 | Rules | Twitter posting protocol | 150 |
| G1 | 🔴 | Gotcha | CLI auth broken | 60 |
| D1 | 🟤 | Decision | Content split by account | 60 |
 
---
 
### R1 | Twitter Posting Protocol | ~150 tokens
- POST ALL tweets in ONE session
- NEVER post hook without full thread
- VERIFY everything before reporting done

Observation Types

Icon	Type	When to Use
🚨	rule	Critical rule, must follow
🔴	gotcha	Pitfall, don't repeat this
🟡	fix	Bug fix, workaround
🔵	how	Technical explanation
🟢	change	What changed, deployed
🟣	discovery	Learning, insight
🟠	why	Design rationale
🟤	decision	Architecture decision
⚖️	tradeoff	Deliberate compromise

Token Estimation

Content Type	Tokens
Simple fact	~30-50
Short explanation	~80-150
Detailed context	~200-400
Full summary	~500-1000

How It Works

Session starts → Agent scans index tables (~100-200 tokens)
Agent sees types → Prioritizes 🔴 gotchas over 🟢 changes
Agent sees costs → Decides if 400-token entry is worth it
Fetch on demand → Only load what's relevant to current task

Benefits

Token savings: ~65,000 tokens/day with 20 memory checks
Faster scanning: Icons enable visual pattern recognition
Precise references: IDs like #1, G3, D5 for exact lookup
Cost awareness: Token counts for ROI decisions

Integration

Works with any markdown-based memory system. No database required.

For Clawdbot users:

Update AGENTS.md with format instructions
Restructure MEMORY.md with index
Use format in daily memory/YYYY-MM-DD.md files

Built by LXGIC Studios

🔗 GitHub · Twitter

Progressive Memory Token-Efficient AI Agent Memory System