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

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

```markdown
# 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

```bash
# 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)
```bash
# 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`