diegosouzapw Amnesia
Memory management toolkit for AI agents. Because forgetting is not an option.
Quick Start
- Copy templates to workspace:
cp assets/templates/*.md /path/to/agent/workspace/
Fill in each template with agent-specific information
Set up automated backups:
cp scripts/backup.sh /path/to/agent/scripts/
chmod +x /path/to/agent/scripts/backup.sh
Core Files
| File | Purpose |
|---|---|
IDENTITY.md |
Who the agent is — name, birthday, capabilities |
SOUL.md |
How the agent behaves — values, style, boundaries |
MEMORY.md |
Curated long-term memories |
USER.md |
Information about the primary user |
TOOLS.md |
Environment-specific notes |
memory/*.md |
Daily episodic logs |
Setting Up Identity
IDENTITY.md
Define static facts about the agent:
# IDENTITY.md - Who Am I?
- **Name:** [Agent name]
- **Creature:** [What the agent is]
- **Vibe:** [One-line personality]
- **Emoji:** [Representative emoji]
- **Birthday:** [Creation date]
SOUL.md
Define behavioral guidelines:
# SOUL.md - Who You Are
## Core Truths
[Fundamental principles]
## Boundaries
[What the agent won't do]
## Vibe
[Communication style]
Memory Architecture
Long-term Memory (MEMORY.md)
Curated, important information:
- Key learnings with dates
- Important facts
- People and relationships
- Project status
- Preferences discovered
- Mistakes to avoid
Daily Logs (memory/YYYY-MM-DD.md)
Raw episodic memory:
- Session starts
- Events and timestamps
- Conversations
- Learnings
- Tomorrow's tasks
Maintenance cycle: Periodically review daily logs → extract insights → update MEMORY.md
Backup System
backup.sh
Backs up workspace to git:
./scripts/backup.sh [workspace_dir] [backup_repo_dir]
Run on a cron schedule (e.g., hourly):
0 * * * * /path/to/scripts/backup.sh
restore.sh
Restores from backup after a wipe:
./scripts/restore.sh [backup_repo_dir] [workspace_dir]
new-day.sh
Initializes today's memory log:
./scripts/new-day.sh [workspace_dir]
Session Startup Checklist
When an agent starts a new session:
- Read
IDENTITY.md— establish who you are - Read
SOUL.md— establish how you behave - Read
USER.md— know who you're helping - Read
MEMORY.md— recall long-term context - Read
memory/YYYY-MM-DD.md(today + yesterday) — recent context - Check
TOOLS.md— environment specifics
Best Practices
- Save immediately — Don't rely on context; write to files
- Date your entries — When was this learned?
- Curate aggressively — Not everything goes in MEMORY.md
- Back up frequently — Hourly is good, more often is better
- Version control everything — Git is your friend
Resources
- Templates:
assets/templates/ - Scripts:
scripts/ - GitHub: https://github.com/mulletmcnasty/amnesia