docs/user-guide/memory-system.md
SuperClaude Framework includes a built-in memory system called ReflexionMemory that helps the PM Agent learn from past mistakes and avoid repeating errors.
ReflexionMemory is an automatic error learning system that:
Key Point: ReflexionMemory is built-in and requires no installation or setup. It works automatically.
When the PM Agent encounters an error during implementation:
Error Occurs:
→ PM Agent detects failure
→ Analyzes root cause
→ Documents the learning
→ Saves to ReflexionMemory
Each error is stored as a "reflexion entry" containing:
| Field | Description | Example |
|---|---|---|
task | What you were trying to do | "implement JWT authentication" |
mistake | What went wrong | "JWT validation failed" |
evidence | Proof of the error | "TypeError: Cannot read property 'verify'" |
rule | Lesson learned | "Always check environment variables before implementation" |
fix | How it was solved | "Added SUPABASE_JWT_SECRET to .env" |
tests | Verification steps | ["Check .env.example", "Verify all env vars set"] |
status | Current state | "adopted" (active rule) |
Next time a similar error occurs:
New Error:
1. ReflexionMemory searches past errors
2. Finds similar mistakes (keyword matching)
3. Returns known solutions
4. PM Agent applies fix immediately
Result:
✅ Instant resolution
✅ Zero additional tokens
✅ <10% error recurrence rate
ReflexionMemory data is stored locally in your project:
<project-root>/
└── docs/
└── memory/
└── reflexion.jsonl # Error learning database
Format: JSON Lines - one JSON object per line
Persistence: Persists across sessions, commits, and branches
ReflexionMemory uses keyword-based similarity matching:
overlap = (matching_keywords) / (total_keywords)Example:
Current error: "JWT token validation failed missing secret"
Past error: "JWT validation failed secret not found"
Overlap: 7/8 keywords match = 87.5% similarity ✅
ReflexionMemory works transparently:
You can view the memory file directly:
# View all learnings
cat docs/memory/reflexion.jsonl | jq
# Search for specific topic
cat docs/memory/reflexion.jsonl | jq 'select(.task | contains("auth"))'
# Count total learnings
wc -l docs/memory/reflexion.jsonl
Clear all memory (use with caution):
rm docs/memory/reflexion.jsonl
Remove specific entry: Edit the file manually and delete the line
Mark as obsolete: Change "status": "adopted" to "status": "deprecated"
ReflexionMemory activates during:
Scenario: User asks to implement OAuth login
Step 1 - Pre-Check:
PM Agent: "Checking past OAuth implementations..."
ReflexionMemory: Found 2 similar tasks
PM Agent: "⚠️ Warning: Past mistake - forgot to set OAUTH_SECRET"
Step 2 - Implementation:
PM Agent: Implements OAuth + remembers to check env vars
Result: Success on first try ✅
Step 3 - If Error Occurs:
PM Agent: "Error: OAUTH_REDIRECT_URL not configured"
ReflexionMemory: No similar error found
PM Agent: Investigates, fixes, documents learning
ReflexionMemory: Saves new entry for future reference
See docs/memory/reflexion.jsonl.example for sample entries.
Each line is a complete JSON object:
{"ts": "2025-10-30T14:23:45+09:00", "task": "implement auth", "mistake": "JWT validation failed", "evidence": "TypeError: secret undefined", "rule": "Check env vars before auth implementation", "fix": "Added JWT_SECRET to .env", "tests": ["Verify .env vars", "Test JWT signing"], "status": "adopted"}
Current: Keyword-based search (50% overlap threshold)
Planned: Semantic search upgrade
| Feature | ReflexionMemory | Mindbase (Planned) | Mem0/Letta |
|---|---|---|---|
| Setup | Built-in | Never implemented | External install |
| Storage | Local JSONL | N/A | PostgreSQL/Vector DB |
| Search | Keyword (50%) | N/A | Semantic |
| Scope | Errors only | N/A | Full memory |
| Cost | Free | N/A | Infrastructure |
Why ReflexionMemory: Focused, efficient, and requires zero setup.
If docs/memory/reflexion.jsonl doesn't exist:
Check:
status: "adopted"? (Deprecated entries are ignored)ReflexionMemory files rarely exceed 1MB. If needed:
mv reflexion.jsonl reflexion-archive-2025.jsonltail -100 reflexion-archive-2025.jsonl > reflexion.jsonlIf you manually edit and break the JSON format:
# Validate each line
cat docs/memory/reflexion.jsonl | while read line; do echo "$line" | jq . || echo "Invalid: $line"; done
# Remove invalid lines
cat docs/memory/reflexion.jsonl | while read line; do echo "$line" | jq . >/dev/null 2>&1 && echo "$line"; done > fixed.jsonl
mv fixed.jsonl docs/memory/reflexion.jsonl
superclaude/core/pm_init/reflexion_memory.pydocs/research/reflexion-integration-2025.mdsuperclaude/agents/pm-agent.mddocs/reference/pm-agent-autonomous-reflection.md# View all learnings
cat docs/memory/reflexion.jsonl | jq
# Search for auth-related errors
grep -i "auth" docs/memory/reflexion.jsonl | jq
# Count learnings
wc -l docs/memory/reflexion.jsonl
# Latest 5 errors
tail -5 docs/memory/reflexion.jsonl | jq
# Check for duplicates (same mistake)
cat docs/memory/reflexion.jsonl | jq -r '.mistake' | sort | uniq -c | sort -rn
Questions? See the FAQ or open an issue on GitHub.