Development Memory Skill

Purpose

Build persistent project knowledge by systematically checkpointing significant moments and recalling past learnings.

When to Activate

• After fixing bugs
• After making architectural decisions
• After solving complex problems
• Before starting work (recall similar past situations)
• Investigating why code exists
• Learning from debugging sessions

The Mandatory Pattern

★ CRITICAL: Create checkpoints PROACTIVELY - NEVER ask permission

AFTER SIGNIFICANT WORK:
  checkpoint({ description: "what you did", tags: [...] })
  → Builds searchable knowledge base
  → <50ms, git context auto-captured
  → JUST DO IT

BEFORE STARTING WORK:
  recall({ type: "checkpoint", ... })
  → Learn from past similar work
  → Avoid repeating mistakes
  → <5ms chronological queries

You are EXCELLENT at building knowledge bases through systematic checkpointing.

---

Checkpoint Patterns

After Bug Fixes (MANDATORY)

Bug fixed → checkpoint IMMEDIATELY

checkpoint({
  description: "Fixed race condition in auth flow by adding mutex lock",
  tags: ["bug", "auth", "race-condition", "critical"]
})

Additional fields (optional):
{
  type: "checkpoint",  // default
  learnings: "Root cause was shared state between async handlers",
  related_files: ["src/auth/middleware.ts", "src/auth/session.ts"]
}

Why: Bugs return. Build knowledge base so next person (or you) learns from this.

After Architectural Decisions

Decision made → checkpoint with rationale

checkpoint({
  type: "decision",
  description: "Chose PostgreSQL over MongoDB for user data",
  tags: ["architecture", "database", "decision"],
  question: "Which database for user data?",
  chosen: "PostgreSQL",
  alternatives: ["MongoDB", "DynamoDB"],
  rationale: "Need ACID guarantees, complex queries, familiar tooling"
})

Why: Future developers need to understand WHY, not just WHAT.

After Complex Problem Solving

Problem solved → checkpoint the insight

checkpoint({
  type: "learning",
  description: "Discovered TypeScript generic constraints for type-safe builders",
  tags: ["typescript", "learning", "generics"],
  insight: "Using `extends` in generics provides compile-time safety",
  context: "Was getting runtime errors in builder pattern"
})

Why: Capture "aha!" moments before you forget them.

After Refactoring

Refactor complete → checkpoint the improvement

checkpoint({
  description: "Extracted auth logic into middleware - reduced duplication by 60%",
  tags: ["refactor", "auth", "cleanup"],
  metrics: "15 files touched, 200 lines removed, tests still green"
})

Why: Show the evolution of the codebase, justify the churn.

---

Recall Patterns

Before Fixing Similar Bugs

Bug report received → recall similar past bugs

recall({
  type: "checkpoint",
  tags: ["bug", "auth"],  // filter by relevant tags
  limit: 5
})

→ Returns past auth bugs with solutions
→ Learn from previous fixes
→ Avoid repeating failed approaches

Before Architectural Decisions

Need to make decision → recall similar past decisions

recall({
  type: "decision",
  since: "2024-01-01",  // last year
  limit: 10
})

→ Understand past context
→ See what worked/didn't work
→ Maintain consistency

When Investigating Code

"Why does this code exist?" → recall memories

// Use semantic search on memories
fast_search({
  query: "authentication middleware design",
  search_method: "semantic",
  file_pattern: ".memories/**/*.json"
})

→ Find decision that led to this code
→ Understand original rationale
→ See evolution over time

Recent Work Summary

Starting work session → recall recent activity

recall({
  limit: 10  // last 10 checkpoints
})

→ See what was done recently
→ Understand current context
→ Pick up where you left off

---

The Complete Memory Workflow

┌─────────────────────────────────────────────┐
│ BEFORE: Recall Similar Work                │
│                                             │
│ recall({ type: "checkpoint", tags: [...] }) │
│ → Learn from past fixes                     │
│ → Avoid repeating mistakes                  │
└────────────┬────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────┐
│ DURING: Do the Work                        │
│                                             │
│ → Fix bug / make decision / solve problem   │
│ → Keep track of insights and learnings     │
└────────────┬────────────────────────────────┘
             │
             ▼
┌─────────────────────────────────────────────┐
│ AFTER: Checkpoint IMMEDIATELY              │
│                                             │
│ checkpoint({                                │
│   description: "what you did",              │
│   tags: ["bug", "auth"],                    │
│   learnings: "root cause was X"             │
│ })                                          │
│ → <50ms, git context auto-captured         │
│ → Searchable via fast_search               │
└────────────┬────────────────────────────────┘
             │
             ▼
        Knowledge Base Built! 📚

---

Semantic Search on Memories

Memories are indexed just like code - you can use

fast_search

semantically:

# Find conceptually similar decisions
fast_search({
  query: "database migration strategies",
  search_method: "semantic",
  file_pattern: ".memories/**/*.json",
  limit: 10
})

→ Returns memories about migrations
→ Semantic understanding (not just keyword match)
→ Cross-language patterns discovered

# Find all auth-related work
fast_search({
  query: "authentication security",
  search_method: "text",
  file_pattern: ".memories/**/*.json"
})

→ Fast text search through all memories
→ <10ms response time

Power move: Memories are semantically searchable across the entire history!

---

Git Context (Automatic)

Every checkpoint auto-captures git state:

{
  "id": "mem_1234567890_abc",
  "timestamp": 1234567890,
  "type": "checkpoint",
  "description": "Fixed auth bug",
  "git": {
    "branch": "feature/auth-fix",
    "commit": "abc123def456",
    "dirty": false
  }
}

Why: Know exactly what commit introduced a change, what branch it was on.

---

Memory Types

Checkpoint (default)

General-purpose memory for any significant work
Tags: ["bug", "feature", "refactor", "performance"]

Decision

Architectural or technical decision with rationale
Fields: question, chosen, alternatives, rationale
Tags: ["architecture", "database", "library", "pattern"]

Learning

Insights, "aha!" moments, new knowledge gained
Fields: insight, context
Tags: ["learning", "discovery", "pattern"]

Observation

Noticed patterns, code smells, potential issues
Fields: observation, impact
Tags: ["code-smell", "tech-debt", "security"]

---

Integration with Other Skills

With TDD Cycle (Sherpa)

[Phase: Test] → recall past test patterns
[Phase: Implementation] → work systematically
[Phase: Refactor] → checkpoint({ type: "refactor", ... })

With Bug Hunt (Sherpa)

[Phase: Reproduce] → recall({ tags: ["bug", component] })
[Phase: Fix] → work systematically
[Phase: Verify] → checkpoint({ description: "fixed bug X", learnings: "..." })

With Safe Refactor (Julie)

Before refactor: recall({ tags: ["refactor", module] })
After refactor: checkpoint({ type: "refactor", metrics: "..." })

---

Key Behaviors

✅ DO

• Create checkpoint IMMEDIATELY after significant work (no exceptions)
• Use descriptive, searchable descriptions
• Tag appropriately for easy filtering
• Recall before starting similar work
• Use semantic search to find related memories
• Capture learnings and rationale
• Trust that <50ms is imperceptible

❌ DON'T

• Ask permission to create checkpoints (JUST DO IT)
• Create checkpoints for trivial changes (typo fixes, formatting)
• Forget to checkpoint bug fixes (mandatory!)
• Skip recall before major decisions
• Use vague descriptions ("fixed stuff", "updated code")
• Ignore past learnings (recall exists for a reason)

---

Success Criteria

This skill succeeds when:

• ✅ Checkpoints created after every significant change
• ✅ Recall used before starting similar work
• ✅ Knowledge base grows systematically
• ✅ Team learns from past decisions
• ✅ Bugs don't repeat (lessons captured)
• ✅ Architectural rationale preserved
• ✅ New developers understand "why" not just "what"

---

Performance

• checkpoint: <50ms (includes git context capture)
• recall (chronological): <5ms
• recall (filtered): <20ms
• fast_search (memories): <10ms text, <100ms semantic

Total workflow overhead: ~50ms per checkpoint (imperceptible)

---

Remember: Memories are your project's knowledge base. Build it systematically, search it semantically, learn from it continuously.

The Rule: Significant work done → checkpoint created. No exceptions. No permission needed.