Introduction
# Agent Memory Rules
## What to Remember - Decisions and their reasoning — "we chose X because Y" helps avoid re-debating - User preferences explicitly stated — don't infer, record what they actually said - Project context that survives sessions — locations, credentials references, architecture decisions - Lessons learned from mistakes — what went wrong and how to avoid it next time - Recurring patterns in user requests — anticipate needs without being asked
## What NOT to Remember - Temporary context that expires — "current task" status belongs in session, not long-term memory - Sensitive data (passwords, tokens, keys) — memory files are less protected than secret storage - Obvious facts the model already knows — don't store "Python is a programming language" - Duplicate information — one source of truth, not scattered copies - Raw conversation logs — distill insights, don't copy transcripts
## Memory Structure - One master file (MEMORY.md) for critical, frequently-accessed context — keep it scannable - Topic-specific files in memory/ directory for detailed reference — index them in master file - Date-based files (YYYY-MM-DD.md) for daily logs — archive, not primary reference - Keep master file under 500 lines — if larger, split into topic files and summarize in master - Use headers and bullet points — walls of text are unsearchable
## Writing Style - Concise, factual statements — "User prefers dark mode" not "The user mentioned they like dark mode" - Include dates for time-sensitive information — preferences evolve, decisions get revisited - Add source context — "Per 2024-01-15 discussion" helps verify later - Imperative for rules — "Always ask before deleting files" not "The user wants us to ask" - Group related information — scattered facts are harder to retrieve
## Retrieval Patterns - Search before asking — user already told you, check memory first - Query with keywords, not full sentences — semantic search works better with key terms - Check recent daily logs for current project context — they have freshest information - Cross-reference master file with topic files — master has summary, topic files have details - Admit uncertainty — "I checked memory but didn't find this" is better than guessing
## Maintenance - Review and prune periodically — outdated information pollutes retrieval - Consolidate daily logs into master file weekly — distill lessons, archive raw logs - Update, don't append contradictions — "User now prefers X" should replace old preference, not sit alongside it - Remove completed todos — memory is state, not history - Version decisions — "v1: chose X, v2: switched to Y because Z" tracks evolution
## Anti-Patterns - Hoarding everything — more memory ≠ better, noise drowns signal - Forgetting to check — asking questions already answered wastes user time - Stale preferences — user said "I like X" a year ago, might have changed - Memory as todo list — use dedicated task systems, memory is for context - Duplicate sources of truth — pick one location for each type of information
## Context Window Management - Memory competes with conversation for context — keep files lean - Load only relevant memory per task — don't dump entire memory every turn - Summarize long files before loading — key points, not full content - Archive old information — accessible if needed, not always loaded - Track what's loaded — avoid redundant memory reads in same session