Memory 🧠
Superpowered memory that never forgets.
Your agent has basic built-in memory. This skill adds infinite, perfectly organized memory for everything else — parallel and complementary, never conflicting.
How It Works
Built-in Agent Memory This Skill (~/memory/)
┌─────────────────────┐ ┌─────────────────────────────┐
│ MEMORY.md │ │ Infinite categorized storage │
│ memory/ (daily logs)│ + │ Any structure you want │
│ Basic recall │ │ Perfect organization │
└─────────────────────┘ └─────────────────────────────┘
↓ ↓
Agent basics Everything else
(works automatically) (scales infinitely)
Not a replacement. Your agent's built-in memory keeps working. This adds a parallel system for unlimited, organized storage.
Setup
On first use, read
setup.md
to configure the memory system with the user. Key decisions:
- What categories do they need?
- Should we sync anything from built-in memory?
- How do they want to find things?
When to Use
User needs organized long-term storage beyond basic agent memory: detailed project histories, extensive contact networks, decision logs, domain knowledge, collections, or any structured data that grows over time.
Architecture
Memory lives in
~/memory/
— a dedicated folder separate from built-in agent memory.
~/memory/
├── config.md # System configuration
├── INDEX.md # What's stored, where to find it
│
├── [user-defined]/ # Categories the user needs
│ ├── INDEX.md # Category overview
│ └── {items}.md # Individual entries
│
└── sync/ # Optional: synced from built-in memory
└── ...
The user defines the categories. Common examples:
projects/
— detailed project contextpeople/
— contact network with full contextdecisions/
— reasoning behind choicesknowledge/
— domain expertise, reference materialcollections/
— books, recipes, anything they collect
See
memory-template.md
for all templates.
Quick Reference
| Topic | File |
|---|
| First-time setup | setup.md
|
| All templates | memory-template.md
|
| Organization patterns | patterns.md
|
| Problems & fixes | troubleshooting.md
|
Core Rules
1. Separate from Built-In Memory
This system lives in
~/memory/
. Never modify:
- Agent's MEMORY.md (workspace root)
- Agent's
memory/
folder (if it exists in workspace)
Parallel, not replacement. Both systems work together.
2. User Defines Structure
During setup, ask what they want to store. Create categories based on their needs:
| They say... | Create |
|---|
| "I have many projects" | ~/memory/projects/
|
| "I meet lots of people" | ~/memory/people/
|
| "I want to track decisions" | ~/memory/decisions/
|
| "I'm learning [topic]" | ~/memory/knowledge/[topic]/
|
| "I collect [things]" | ~/memory/collections/[things]/
|
No preset structure. Build what they need.
3. Every Category Has an Index
Each folder gets an INDEX.md that lists contents:
# Projects Index
| Name | Status | Updated | File |
|---|
| Alpha | Active | 2026-02 | alpha.md |
| Beta | Paused | 2026-01 | beta.md |
Total: 2 active, 5 archived
Indices stay small (<100 entries). When full, split into subcategories.
4. Write Immediately
When user shares important information:
- Write to appropriate file in ~/memory/
- Update the category INDEX.md
- Then respond
Don't wait. Don't batch. Write immediately.
5. Search Then Navigate
To find information:
- Ask first: "Is this in ~/memory/ or built-in memory?"
- Search: grep or semantic search in ~/memory/
- Navigate: INDEX.md → category → specific file
# Quick search
grep -r "keyword" ~/memory/
Navigate
cat ~/memory/INDEX.md # What categories exist?
cat ~/memory/projects/INDEX.md # What projects?
cat ~/memory/projects/alpha.md # Specific project
6. Sync from Built-In (Optional)
If user wants certain info copied from built-in memory:
~/memory/sync/
├── preferences.md # Synced from built-in
└── decisions.md # Synced from built-in
Sync is one-way: Built-in → this system. Never modify built-in.
7. Scale by Splitting
When a category grows large:
- INDEX.md > 100 entries → split into subcategories
- Create sub-INDEX.md for each subcategory
- Root INDEX.md points to subcategories
~/memory/projects/
├── INDEX.md # "See active/, archived/"
├── active/
│ ├── INDEX.md # 30 active projects
│ └── ...
└── archived/
├── INDEX.md # 200 archived projects
└── ...
What to Store Here (vs Built-In)
| Store HERE (~/memory/) | Keep in BUILT-IN |
|---|
| Detailed project histories | Current project status |
| Full contact profiles | Key contacts quick-ref |
| All decision reasoning | Recent decisions |
| Domain knowledge bases | Quick facts |
| Collections, inventories | — |
| Anything that grows large | Summaries |
Rule: Built-in for quick context. Here for depth and scale.
Finding Things
For Small Memory (<50 files)
# Grep is fast enough
grep -r "keyword" ~/memory/
For Large Memory (50+ files)
Navigate via indices:
1. ~/memory/INDEX.md → find category
2. ~/memory/{category}/INDEX.md → find item
3. ~/memory/{category}/{item}.md → read details
For Huge Memory (500+ files)
Use semantic search if available, or hierarchical indices:
~/memory/projects/INDEX.md → "web projects in web/"
~/memory/projects/web/INDEX.md → "alpha project"
~/memory/projects/web/alpha.md → details
Maintenance
Weekly (5 min)
- Update INDEX.md files if entries added
- Archive completed/inactive items
Monthly (15 min)
- Review category sizes
- Split large categories
- Remove outdated entries
When Memory is Slow
- Check INDEX.md sizes (keep <100 lines)
- Split big categories into subcategories
- Archive old content
Common Traps
-
Modifying built-in memory → Never touch agent's MEMORY.md or workspace memory/. This system is parallel.
-
No indices → Without INDEX.md, finding things requires searching all files. Always maintain indices.
-
One giant category → 500 items in one folder is slow. Split into subcategories.
-
Syncing everything → Don't copy all built-in memory. Only sync what needs organization here.
-
Waiting to write → Write immediately when user shares info. Don't batch.
Security & Privacy
Data location:
- All data in
~/memory/
on user's machine
- No external services required
- No network requests
This skill does NOT:
- Access built-in agent memory (only reads if syncing)
- Send data anywhere
- Store credentials (never store secrets in memory)
Related Skills
Install with
clawhub install <slug>
if user confirms:
decide
- Decision tracking patternsescalate
- When to involve humanslearn
- Adaptive learning
Feedback
- If useful:
clawhub star memory
- Stay updated:
clawhub sync
