Memory

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: 1. What categories do they need? 2. Should we sync anything from built-in memory? 3. 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:

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:

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: 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:

~/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)

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)

~/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)

Monthly (15 min)

When Memory is Slow

Common Traps

Security & Privacy

Data location:

This skill does NOT:

Related Skills

Feedback

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.

On first use, read setup.md to configure the memory system with the user. Key decisions: 1. What categories do they need? 2. Should we sync anything from built-in memory? 3. How do they want to find things?