Memory

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 context
• people/ — contact network with full context
• decisions/ — reasoning behind choices
• knowledge/ — domain expertise, reference material
• collections/ — books, recipes, anything they collect

See memory-template.md for all templates.

Quick Reference

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:

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:

1. Write to appropriate file in ~/memory/
2. Update the category INDEX.md
3. Then respond

Don't wait. Don't batch. Write immediately.

5. Search Then Navigate

To find information:

1. Ask first: "Is this in ~/memory/ or built-in memory?"
2. Search: grep or semantic search in ~/memory/
3. 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)

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 patterns
• escalate - When to involve humans
• learn - Adaptive learning

Feedback

• If useful: clawhub star memory
• Stay updated: clawhub sync