memory-protocol

What this skill does

# Memory Protocol

**Version:** 2.0.0
**Portability:** High

---

## Memory Directory

Memory is stored in `~/.claude/projects/<project-path>/memory/` and persists across sessions. Claude Code's auto memory feature manages this directory automatically.

## Objective

Defines patterns for systematic knowledge accumulation and retrieval in agent workflows, enabling agents to learn from past experiences and avoid repeating work.

**Purpose:** Build institutional knowledge over time, recall solutions to previously-solved problems, and avoid context loss between sessions.

**Scope:**
- **Included:** Recall-before-act pattern, storage patterns, search strategies, knowledge organization
- **Excluded:** Specific memory system implementations, storage backends, MCP server details

---

## Core Principles

### Principle 1: Recall Before Act (Search First)

**The Principle:** Before starting any task or debugging any problem, search accumulated knowledge for relevant past experiences.

**Why this matters:** The most wasteful work is work you've already done. Searching memory first prevents repeating solutions, rediscovering conventions, and re-debugging known issues.

**How to apply:**
1. Before starting a task, search for similar past work
2. Before debugging an error, search for that error message
3. Before making architectural decisions, search for past decisions
4. Use search results to inform current work

**Example:**
```
# Bad workflow
User: "Fix the login bug"
Agent: Immediately starts debugging from scratch
        (Wastes 30 minutes rediscovering root cause)

# Good workflow
User: "Fix the login bug"
Agent: Search memory: "login bug authentication error"
       Found: "Login fails when session expires - solution: refresh token"
       Apply known solution
       (Fixes in 2 minutes)
```

**Search triggers:**
- Starting any new task
- Encountering an error
- Making design decisions
- Unsure about conventions
- Before asking user questions (maybe already answered)

### Principle 2: Remember After Discovery (Capture Insights)

**The Principle:** After solving non-obvious problems, learning conventions, or making decisions, immediately store that knowledge.

**Why this matters:** Knowledge not captured is knowledge lost. Future you (or other agents) will encounter the same problems and waste time if solutions aren't stored.

**What to remember:**
- **Solutions:** How you fixed non-obvious problems
- **Conventions:** Project-specific patterns discovered
- **Decisions:** Why you chose approach A over B
- **User preferences:** Workflows, tools, style choices the user prefers
- **Tool quirks:** Unexpected behaviors of libraries, APIs, CLIs
- **Root causes:** Deep understanding from debugging sessions

**What NOT to remember:**
- Obvious information (standard library usage)
- One-time facts (file paths, temporary values)
- Information already well-documented elsewhere
- Noise (every small step taken)

**How to apply:**
```
# After solving a problem
Agent: Discovered that API requires OAuth2 token in X-Custom-Auth header (not standard Authorization header)
Action: Store memory: "API authentication quirk: Use X-Custom-Auth header for OAuth2 tokens"

# After learning convention
Agent: Noticed all test files use suffix _test.py (not test_*.py)
Action: Store memory: "Project convention: Test files named <module>_test.py"

# After architectural decision
Agent: Chose event sourcing over CRUD for audit requirements
Action: Store memory: "Architecture: Using event sourcing. Rationale: Audit log requirement needs full history"
```

### Principle 3: Knowledge Graph Structure (Connect Related Information)

**The Principle:** Memories should be connected to related memories, forming a knowledge graph rather than isolated facts.

**Why this matters:** Connected knowledge is more discoverable and provides richer context. Finding one memory can lead to discovering related knowledge.

**How to apply:**
- Link solutions to the problems they solve
- Connect architectural decisions to the requirements that drove them
- Relate conventions to the codebase areas where they apply
- Associate user preferences with the features they affect

**Example (Conceptual):**
```
Memory 1: "Authentication uses JWT tokens"
  └─ Related to: Memory 2 "JWT secret stored in environment variable JWT_SECRET"
      └─ Related to: Memory 3 "Environment variables loaded from .env file"

Query: "How does authentication work?"
Result: Finds all 3 related memories (complete picture)
```

### Principle 4: Prime Directive (Knowledge Accumulation is Critical)

**The Principle:** Treat knowledge accumulation and retrieval as a primary responsibility, not an optional nice-to-have.

**Why this matters:** Agents without memory repeat mistakes, waste time, and don't improve. Memory is what enables learning and compound productivity gains.

**How to apply:**
- Make recall and remember part of every workflow
- Set reminders at natural checkpoints (task start, error encountered, task complete)
- Proactively store discoveries before context truncation
- Review and refine stored knowledge periodically

**Workflow integration:**
```
Task start → Recall relevant knowledge
  ↓
Work on task
  ↓
Encounter problem → Recall solutions
  ↓
Solve problem → Remember solution
  ↓
Task complete → Remember insights
```

---

## Constraints and Boundaries

### DO:
- Search memory BEFORE starting any non-trivial task
- Search for error messages before debugging
- Store solutions to non-obvious problems
- Store project conventions as discovered
- Store architectural decisions with rationale
- Connect related memories
- Be concise (don't store essays)
- Use clear, searchable language

### DON'T:
- Skip search because "this seems simple" (simple problems have simple solutions you may have seen)
- Store obvious information (language basics, standard library)
- Store one-time facts (temporary values, session-specific data)
- Store without context ("fixed bug" - which bug? how?)
- Wait until "later" to store memories (you'll forget)
- Store duplicate information (search first to check)

**Rationale:** Systematic knowledge management compounds over time. Initial overhead is small compared to long-term productivity gains.

---

## Usage Patterns

### Pattern 1: Task Start Recall

**Scenario:** Starting work on a new feature.

**Approach:**

**Step 1: Query for related work**
```
Task: "Add email notification when order ships"

Search: "email notification" OR "order shipping" OR "email sending"

Results:
- Memory 1: "Email service uses SendGrid, API key in SENDGRID_API_KEY"
- Memory 2: "Email templates in templates/email/"
- Memory 3: "Order model has shipment_date field"
```

**Step 2: Use knowledge to inform work**
- Use SendGrid (don't research email providers)
- Follow existing template structure
- Hook into shipment_date field

**Benefits:**
- Start with context (not from zero)
- Follow established patterns
- Avoid rediscovering tools/conventions

### Pattern 2: Error Resolution Recall

**Scenario:** Encountering an error during development.

**Approach:**

**Step 1: Search for error**
```
Error: "ssl.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED]"

Search: "CERTIFICATE_VERIFY_FAILED"

Result:
- Memory: "macOS SSL error: Install certificates.command after Python install"
```

**Step 2: Apply known solution**
```bash
/Applications/Python 3.x/Install Certificates.command
```

**Step 3: If NOT found, debug and remember**
```
(After solving novel error)

Store: "SSL error on macOS: Python doesn't use system certificates by default. Run Install Certificates.command in Python installation directory to fix."
```

**Benefits:**
- Instant solution to known problems
- Build catalog of fixes over time
- Future errors resolve faster

### Pattern 3: Convention Discovery and Storage

**Scenario:** Working in an unfamiliar codebase.

**Approach:**

**While working, notice patterns:**
```
Observation 1: All API routes start with /api/v1/
Observation 2: Test