memory-management

Memory Management Skill

Purpose

Guide Claude Code to intentionally capture, store, and use context, decisions, and preferences across sessions, enabling true "memory" that survives context resets and improves over time.

When to Use This Skill

Automatically activates when you mention:

• Remembering user preferences or choices
• Tracking decisions made during development
• Capturing important context
• Learning from user corrections
• Persisting project-specific knowledge
• Memory that survives session resets

The Problem: Context Loss

Without intentional memory:

• ❌ Same mistakes repeated across sessions
• ❌ User has to re-explain preferences every time
• ❌ Important decisions forgotten after context reset
• ❌ No learning from corrections
• ❌ Starting from scratch each session

With intentional memory:

• ✅ Preferences remembered and auto-applied
• ✅ Decisions documented and retrievable
• ✅ Context persists across sessions
• ✅ Learn and adapt from corrections
• ✅ Continuous improvement over time

Core Principles

1. Be Selective

Track signal, not noise:

• ✅ User explicitly states preference ("always use X")
• ✅ User corrects same pattern 2+ times
• ✅ Important architectural decisions
• ✅ Project-specific conventions
• ❌ One-time experiments
• ❌ Formatting preferences (use linter config)
• ❌ Temporary changes
• ❌ Information already in codebase

2. Be Transparent

User should always know what's stored:

• Store in visible location (.claude/memory/)
• Use human-readable format (JSON with comments)
• Provide commands to view memory (/show-memory)
• Log when memory is created/updated
• Allow user to clear memory anytime

3. Be Intentional

Only capture what adds value:

• Preferences that save time
• Decisions that provide context
• Patterns that prevent mistakes
• Knowledge that's hard to rediscover

4. Be Respectful

Never store sensitive data:

• ❌ API keys, tokens, credentials
• ❌ Personal information (unless necessary)
• ❌ Private repository URLs with tokens
• ❌ Business-sensitive logic
• ✅ Preferences, patterns, conventions
• ✅ Architecture decisions, rationale

What to Remember

User Preferences

Examples:

• Naming conventions (camelCase vs. snake_case)
• Import style (named vs. default)
• Error handling approach (try/catch vs. error boundaries)
• State management choice (Context vs. Zustand vs. TanStack Query)
• Component structure preferences

Storage location: .claude/memory/{skill-name}/preferences.json

Example:

{
  "naming": {
    "convention": "camelCase",
    "learned_from": "user_correction",
    "correction_count": 2,
    "examples": [
      "userId (not user_id)",
      "createdAt (not created_at)"
    ],
    "confidence": "high",
    "last_updated": "2025-01-15T10:30:00Z"
  }
}

Architectural Decisions

Examples:

• Why a specific pattern was chosen
• Alternatives considered and rejected
• Trade-offs and constraints
• Future considerations

Storage location: .claude/memory/project/decisions.json

Example:

{
  "decisions": [
    {
      "id": "auth-jwt-2025-01-15",
      "date": "2025-01-15",
      "decision": "Use JWT authentication instead of sessions",
      "rationale": "Need stateless auth for mobile apps",
      "alternatives_considered": [
        "Session-based auth (rejected: not stateless)",
        "OAuth only (rejected: need custom auth flow)"
      ],
      "impact": "Requires database migration for refresh tokens",
      "files_affected": [
        "lib/supabase/auth.ts",
        "app/api/auth/**/*.ts"
      ]
    }
  ]
}

Correction Patterns

Examples:

• User repeatedly corrects same mistake
• User provides specific guidance
• User rejects suggested approach

Storage location: .claude/memory/{skill-name}/corrections.json

Example:

{
  "corrections": [
    {
      "pattern": "Import style",
      "count": 3,
      "first_seen": "2025-01-10T09:00:00Z",
      "last_seen": "2025-01-15T14:30:00Z",
      "examples": [
        "import { Component } from 'lib' ✓",
        "import Component from 'lib' ✗"
      ],
      "action": "Always use named imports",
      "confidence": "high"
    }
  ]
}

Project Knowledge

Examples:

• Tech stack and versions
• Project structure and organization
• Integration points (APIs, databases)
• Deployment patterns

Storage location: .claude/memory/project/knowledge.json

Example:

{
  "tech_stack": {
    "frontend": "Next.js 14, React 19, shadcn/ui, Tailwind",
    "backend": "Supabase Edge Functions, PostgreSQL",
    "deployment": "Vercel (frontend), Supabase (backend)",
    "last_verified": "2025-01-15"
  },
  "structure": {
    "components": "app/components/",
    "pages": "app/(routes)/",
    "api": "app/api/",
    "supabase_functions": "supabase/functions/"
  }
}

When to Persist

Immediate Persistence

Capture immediately when:

• ✅ User explicitly says "always" or "never"
• ✅ User provides architectural decision with rationale
• ✅ User corrects same pattern for the 2nd time
• ✅ User defines project-specific convention

Deferred Persistence

Capture after confirmation when:

• User provides preference once (wait for second instance)
• Pattern seems emerging but not confirmed
• Decision has significant impact (confirm first)

Never Persist

Don't capture:

• ❌ Experimental or temporary changes
• ❌ Information already in code/config
• ❌ Generic best practices (not project-specific)
• ❌ Sensitive data of any kind

Storage Patterns

Directory Structure

.claude/memory/
├── project/
│   ├── knowledge.json          # Tech stack, structure
│   ├── decisions.json          # Architectural decisions
│   └── context.json            # Current feature context
├── {skill-name}/
│   ├── preferences.json        # User preferences for this skill
│   ├── corrections.json        # User corrections tracked
│   └── learned_patterns.json  # Patterns learned over time
└── .gitignore                  # Don't commit sensitive memory

File Format

Use JSON with clear structure:

{
  "version": "1.0",
  "created": "2025-01-15T10:00:00Z",
  "last_updated": "2025-01-15T14:30:00Z",
  "data": {
    // Actual content
  }
}

Schema Example

interface MemoryEntry {
  version: string;
  created: string;           // ISO timestamp
  last_updated: string;      // ISO timestamp
  expires?: string;          // Optional expiry
  confidence: 'low' | 'medium' | 'high';
  source: 'user_stated' | 'user_correction' | 'inferred';
  data: Record<string, any>;
}

Decision Tracking

What Makes a Good Decision Log

Include:

1. What: What was decided
2. Why: Rationale and reasoning
3. When: Date/time
4. Alternatives: What else was considered
5. Impact: Files affected, breaking changes
6. Context: Current constraints/requirements

Example Template:

## Decision: [Short Title]

**Date**: 2025-01-15
**Context**: [What problem were we solving?]

**Decision**: [What we decided to do]

**Rationale**:
- [Key reason 1]
- [Key reason 2]

**Alternatives Considered**:
- **Option A**: [Why rejected]
- **Option B**: [Why rejected]

**Impact**:
- Files: [List of affected files]
- Breaking: [Yes/No - details]
- Migration: [What needs to change]

**Trade-offs**:
- ✅ Pro: [Benefit]
- ❌ Con: [Drawback]

When to Log Decisions

Always log:

• ✅ Architecture changes (auth, state management, routing)
• ✅ Technology choices (new library, framework change)
• ✅ Breaking changes to APIs or database
• ✅ Deviation from established patterns

Optional logging:

• Component structure choices
• File organization changes
• Refactoring approaches

Don't log:

• Bug fixes (unless revealing design issue)
• Minor implementation details
• Routine tasks

Correction Tracking

Detecting Corrections

User corrections happen when:

1. User exp