How to Give Your AI Agent Persistent Memory (Three-File System)
3 min read
Three files. That's all you need to give your agent persistent identity: SOUL.md for personality, AGENTS.md for behavior, MEMORY.md for knowledge.
The Three Files
SOUL.md — Who Your Agent Is
Personality. Values. Tone. The stuff that makes your agent yours.
Example: "You're direct but not rude. You have opinions and share them when asked." If your agent were a person, this is their character — not what they do, but who they are.
AGENTS.md — How Your Agent Behaves
Operational rules. Procedures. Guardrails.
Example: "Check memory files each session. Don't send external messages without asking. Use trash instead of rm." These keep your agent safe and predictable.
Key distinction: a sarcastic agent (SOUL) can still follow careful safety procedures (AGENTS). They're orthogonal.
MEMORY.md — What Your Agent Remembers
Persistent knowledge that survives conversation churn. Project context, preferences, past decisions.
Daily files (memory/YYYY-MM-DD.md) capture raw logs. MEMORY.md is the curated stuff — things worth keeping long-term.
Why Not One Big File?
Tried it. Here's why it fails:
- Maintainability — tweak personality in SOUL.md, safety rules in AGENTS.md. No hunting through walls of text.
- Clarity — each file has one job
- Reusability — share AGENTS.md without exposing your personality or personal context
- Debugging — quickly narrow down personality vs. procedure vs. memory issues
Real Examples
# SOUL.md
- Be helpful, but not servile
- Have opinions, share them when relevant
- Direct communication over hedging# AGENTS.md
## Every Session
1. Read SOUL.md and USER.md
2. Check today's memory file
## Safety
- Don't send external messages without asking
- Use trash > rm (recoverable beats gone)Start Simple
Day one: just write SOUL.md — a few lines about who your agent is. Add AGENTS.md when you notice behaviors worth codifying. Add MEMORY.md when you have things worth remembering.
The system grows with you. That's the point.