Active memory management and maintenance for Claude Code framework. Keep project context fresh, organized, and relevant. The Memory plugin provides tools to manage Claude Code's persistent memory system. It helps you review memory state, update memory files interactively, and clean up stale entries. This ensures Claude maintains accurate, relevant context across sessions while avoiding outdated in
Add this skill
npx mdskills install applied-artificial-intelligence/memoryComprehensive memory management with garbage collection, interactive updates, and performance tracking
1# Memory Plugin23Active memory management and maintenance for Claude Code framework. Keep project context fresh, organized, and relevant.45## Overview67The Memory plugin provides tools to manage Claude Code's persistent memory system. It helps you review memory state, update memory files interactively, and clean up stale entries. This ensures Claude maintains accurate, relevant context across sessions while avoiding outdated information.89## Memory System1011Claude Code uses a file-based memory system located in `.claude/memory/`:1213```14.claude/memory/15├── project_state.md # Current project status and structure16├── decisions.md # Architectural and design decisions17├── lessons_learned.md # Insights and patterns discovered18├── conventions.md # Code style and naming conventions19├── dependencies.md # External libraries and tools20└── [domain-specific].md # Custom memory files21```2223**How it works**:24- Memory files are **loaded into every Claude Code session**25- Files use **@import syntax** for modular organization26- Content should be **concise, current, and actionable**27- Stale information **degrades Claude's effectiveness**2829## Features3031- **Memory Review**: Inspect current memory state with metadata32- **Interactive Updates**: Add, update, remove, or relocate memory entries33- **Garbage Collection**: Identify and clean stale entries automatically34- **Auto-Reflection**: Suggest memory updates at task completion35- **Context Optimization**: Keep memory lean and relevant3637## Commands3839### `/memory-review`40Display current memory state with timestamps, sizes, and staleness indicators.4142**What it does**:43- Lists all memory files in `.claude/memory/`44- Shows file sizes and line counts45- Displays last modified timestamps46- Identifies stale entries (>30 days old)47- Calculates total memory usage48- Highlights optimization opportunities4950**Usage**:51```bash52/memory-review # Review all memory files53```5455**Output Example**:56```57Memory Files Review58===================5960project_state.md61 Size: 3.2 KB (82 lines)62 Modified: 2 days ago63 Status: ✅ Current6465decisions.md66 Size: 5.4 KB (148 lines)67 Modified: 1 week ago68 Status: ✅ Current6970lessons_learned.md71 Size: 8.1 KB (210 lines)72 Modified: 45 days ago73 Status: ⚠️ Stale (consider reviewing)7475conventions.md76 Size: 1.8 KB (52 lines)77 Modified: 3 days ago78 Status: ✅ Current7980---81Total Memory: 18.5 KB (492 lines)82Stale Files: 183Recommendation: Review lessons_learned.md84```8586**When to use**:87- ✅ Before starting new work (check current context)88- ✅ After long breaks (verify memory is current)89- ✅ When context feels off (audit memory state)90- ✅ Before /memory-gc (see what will be cleaned)91- ✅ Regular maintenance (monthly review)9293### `/memory-update`94Interactive memory maintenance with add, update, remove, and relocate operations.9596**What it does**:97- Guides you through memory update workflow98- Suggests updates based on recent work99- Adds new knowledge to appropriate files100- Updates existing entries101- Removes outdated information102- Reorganizes memory structure103104**Usage**:105```bash106/memory-update # Interactive memory update workflow107```108109**Workflow**:1101. **Review Recent Work**: Analyzes recent commits, completions, decisions1112. **Suggest Updates**: Proposes memory additions/updates1123. **Interactive Editing**:113 - Add new entries114 - Update existing entries115 - Remove outdated entries116 - Relocate entries to better files1174. **Apply Changes**: Updates memory files1185. **Verify**: Shows what changed119120**Operations**:121122**Add New Entry**:123```bash124/memory-update125> Operation: add126> File: decisions.md127> Entry: "Use PostgreSQL for data persistence (MongoDB too complex for our use case)"128```129130**Update Existing Entry**:131```bash132/memory-update133> Operation: update134> File: dependencies.md135> Find: "React 17.0.2"136> Replace: "React 18.2.0 (upgraded for concurrent features)"137```138139**Remove Outdated Entry**:140```bash141/memory-update142> Operation: remove143> File: lessons_learned.md144> Entry: "Initial SQLite approach was too slow (replaced with PostgreSQL)"145```146147**Relocate Entry**:148```bash149/memory-update150> Operation: relocate151> From: lessons_learned.md152> To: decisions.md153> Entry: "GraphQL adoption decision"154> Reason: "More appropriate in decisions.md"155```156157**When to use**:158- ✅ After completing major feature (/ship auto-suggests)159- ✅ After making architectural decision160- ✅ After discovering important lesson161- ✅ After changing dependencies/conventions162- ✅ When /memory-review shows missing context163164### `/memory-gc`165Garbage collection for stale memory entries - identify and clean up obsolete content.166167**What it does**:168- Scans all memory files for stale entries169- Identifies information >30 days old with no recent references170- Detects superseded decisions171- Finds completed temporary tasks172- Proposes removals with rationale173- Optionally auto-cleans with confirmation174175**Usage**:176```bash177/memory-gc # Analyze and suggest cleanup178/memory-gc --auto # Auto-clean with confirmation179/memory-gc --dry-run # Show what would be cleaned (no changes)180```181182**Staleness Criteria**:183- **>30 days**: No modification in last month184- **Superseded**: Newer decision contradicts old one185- **Completed**: Task/work unit finished186- **Irrelevant**: Context no longer applicable187- **Redundant**: Duplicate information188189**Output Example**:190```191Memory Garbage Collection192=========================193194Stale Entries Found: 8195196decisions.md197 ⚠️ "Use MongoDB for persistence" (45 days old)198 Superseded by: "Use PostgreSQL" (2 days ago)199 Recommendation: Remove200201lessons_learned.md202 ⚠️ "TypeScript strict mode causes too many issues" (60 days old)203 Status: No longer relevant (now using strict mode successfully)204 Recommendation: Remove or update205206 ⚠️ "Initial API design with REST" (90 days old)207 Superseded by: "GraphQL adoption" (10 days ago)208 Recommendation: Archive209210---211Suggested Removals: 3212Suggested Updates: 2213Suggested Archives: 3214215Apply changes? [y/N]216```217218**Safety Features**:219- Shows what will be removed before doing it220- Requires confirmation for destructive operations221- Backs up before cleanup (`.claude/memory/.backup/`)222- Dry-run mode for safe preview223224**When to use**:225- ✅ Monthly maintenance routine226- ✅ Before major milestones (keep memory lean)227- ✅ When memory grows >20KB (optimize)228- ✅ After pivots or major changes (clean old context)229- ✅ When Claude references outdated info230231### `/index [--update] [--refresh] [focus_area]`232Create and maintain persistent project understanding through comprehensive project mapping.233234**What it does**:235- Analyzes project structure and architecture236- Maps dependencies and relationships237- Identifies key components and patterns238- Creates searchable project index239- Updates index as project evolves240241**Usage**:242```bash243/index # Create initial project index244/index --update # Update existing index245/index --refresh # Rebuild index from scratch246/index backend # Focus on backend code247```248249**Output**:250- `.claude/index/` - Project mapping and analysis251- Architectural overview252- Component relationships253- Key patterns and conventions254255**When to use**:256- ✅ New project onboarding257- ✅ After major refactoring258- ✅ Before large features (understand context)259- ✅ Periodic updates (monthly)260261### `/handoff`262Create transition documents with context analysis for session continuity.263264**What it does**:265- Analyzes current session context and progress266- Documents work state and decisions267- Creates transition summary for next session268- Preserves token usage and memory state269- Updates symlink to latest handoff270271**Usage**:272```bash273/handoff # Create handoff document274```275276**Output**:277- `.claude/transitions/YYYY-MM-DD_NNN/handoff.md`278- Session summary and progress279- Current work state and next steps280- Context health metrics281- Recommendations for next session282283**When to use**:284- ✅ End of work session (before closing)285- ✅ Context approaching 80%+ usage286- ✅ Before major context switches287- ✅ Milestone completions288289**Next step**: Use `/clear` then `/continue` to resume from this handoff290291### `/continue`292Auto-load and resume from the most recent handoff document with verification.293294**What it does**:295- Finds latest handoff via `.claude/transitions/latest/handoff.md` symlink296- Verifies symlink points to actual newest handoff (not stale)297- Loads handoff context automatically298- Briefs you on session focus, active work, and next steps299300**Usage**:301```bash302# After /clear, simply:303/continue # Auto-loads latest handoff304```305306**Output Example**:307```308📋 Continuing from: .claude/transitions/2025-10-18_005/handoff.md309310Session Focus: Plugin v1.0.0 delivery311Active Work: Completed work unit 009, shipped v1.0.0312Next Steps: Applied AI website work313314Main Takeaways:315- Plugin architecture refactored to 6 focused plugins316- Web development plugin fixed and ready317318Ready to continue. What would you like to work on?319```320321**When to use**:322- ✅ After `/clear` to resume work323- ✅ Starting new session324- ✅ Returning after break325326**Workflow**:327```bash328# End session329/handoff330331# Clear conversation332/clear333334# Resume in new session335/continue336```337338### `/performance`339View token usage and performance metrics across all components.340341**What it does**:342- Shows real-time token breakdown by component343- Tracks conversation, MCP, memory, system usage344- Identifies optimization opportunities345- Monitors context health (70%, 80%, 90% thresholds)346- Provides actionable recommendations347348**Usage**:349```bash350/performance # View current metrics351```352353**Output Example**:354```355Token Usage Breakdown356=====================357Messages (conversation): 45,234 tokens (30%)358MCP Tools (servers): 18,500 tokens (12%)359Memory Files (context): 8,100 tokens (5%)360System (prompt): 12,000 tokens (8%)361Reserved (buffer): 15,000 tokens (10%)362Available: 51,166 tokens (35%)363364Total: 150,000 / 200,000 (75%)365Status: ⚠️ Warning - Optimize proactively366367Recommendations:368- Consider /clear after /handoff (free conversation tokens)369- Disable unused MCP servers (12K tokens)370- Review memory files for optimization371```372373**When to use**:374- ✅ Session start (baseline metrics)375- ✅ Every 10-15 interactions (monitor)376- ✅ Before major operations (check headroom)377- ✅ When responses seem degraded378379## Auto-Reflection380381The memory plugin integrates with other commands to suggest updates automatically:382383**After /ship**:384```385Feature shipped: User authentication386387Memory Update Suggestions:3881. Add to decisions.md:389 "Use JWT for authentication (bcrypt for password hashing)"3903912. Add to lessons_learned.md:392 "Pre-hashing passwords before validation improves security"3933943. Update dependencies.md:395 "Added: jsonwebtoken v9.0.0, bcrypt v5.1.0"396397Run /memory-update to apply? [y/N]398```399400**After /fix**:401```402Fixed: Memory leak in data processing403404Memory Update Suggestion:405Add to lessons_learned.md:406"Large datasets must be processed in streams, not loaded entirely into memory"407408Run /memory-update to apply? [y/N]409```410411**After /review**:412```413Code review completed: Found 12 issues414415Memory Update Suggestion:416Add to conventions.md:417"Always validate input before processing (3 validation issues found today)"418419Run /memory-update to apply? [y/N]420```421422## Memory File Guidelines423424### project_state.md425**Purpose**: Current project status and structure426**Update Frequency**: Weekly or at major milestones427**Contents**:428- Project overview429- Current phase/status430- Active work units431- Key metrics432- Recent changes433434**Example**:435```markdown436# Project State437438## Overview439Building user authentication system for SaaS platform.440441## Current Status442Phase: Implementation (Week 3 of 4)443Active Work: OAuth integration444Tests: 87% coverage445446## Structure447- `/src/auth` - Authentication modules448- `/src/users` - User management449- `/tests/integration` - Integration tests450451## Recent Changes452- 2024-10-15: Migrated from MongoDB to PostgreSQL453- 2024-10-12: Added JWT authentication454```455456### decisions.md457**Purpose**: Architectural and design decisions458**Update Frequency**: When making decisions459**Contents**:460- Technology choices461- Architecture patterns462- Design tradeoffs463- Rationale for decisions464465**Example**:466```markdown467# Architectural Decisions468469## Database: PostgreSQL470**Decision**: Use PostgreSQL instead of MongoDB471**Rationale**:472- Need ACID transactions473- Complex relational data474- Team expertise in SQL475**Date**: 2024-10-15476477## Authentication: JWT478**Decision**: JWT-based authentication479**Rationale**:480- Stateless (scales better)481- Standard format482- Easy client integration483**Date**: 2024-10-12484```485486### lessons_learned.md487**Purpose**: Insights and patterns discovered488**Update Frequency**: When learning something valuable489**Contents**:490- Mistakes and solutions491- Performance insights492- Best practices discovered493- "Next time" notes494495**Example**:496```markdown497# Lessons Learned498499## Stream Large Datasets500**Context**: Processing 10GB CSV files501**Problem**: Loading entire file into memory caused crashes502**Solution**: Use streaming with 100MB chunks503**Lesson**: Always stream data >1GB504**Date**: 2024-10-10505506## Pre-hash Passwords507**Context**: User authentication implementation508**Problem**: Hashing during validation was slow509**Solution**: Hash passwords before storing510**Lesson**: Expensive operations should happen once511**Date**: 2024-10-12512```513514### conventions.md515**Purpose**: Code style and naming conventions516**Update Frequency**: When establishing patterns517**Contents**:518- Naming conventions519- Code style rules520- File organization521- Testing patterns522523**Example**:524```markdown525# Conventions526527## Naming528- **Files**: kebab-case (user-service.js)529- **Classes**: PascalCase (UserService)530- **Functions**: camelCase (getUserById)531- **Constants**: UPPER_SNAKE (MAX_RETRIES)532533## Testing534- Test files: `*.test.js`535- One describe block per function536- Test structure: Arrange, Act, Assert537- Coverage target: >80%538539## File Organization540- One class per file541- Max 300 lines per file542- Group related functions543```544545### dependencies.md546**Purpose**: External libraries and tools547**Update Frequency**: When adding/updating dependencies548**Contents**:549- Libraries and versions550- CLI tools551- Services/APIs552- Configuration requirements553554**Example**:555```markdown556# Dependencies557558## Core Libraries559- **express**: 4.18.2 (Web framework)560- **postgresql**: 14.5 (Database)561- **jsonwebtoken**: 9.0.0 (Authentication)562- **bcrypt**: 5.1.0 (Password hashing)563564## Development Tools565- **jest**: 29.3.1 (Testing)566- **eslint**: 8.28.0 (Linting)567- **prettier**: 2.8.0 (Formatting)568569## Services570- **GitHub**: Code hosting571- **AWS RDS**: PostgreSQL hosting572- **Sentry**: Error monitoring573```574575## Best Practices576577### Do578- ✅ Update memory after significant work579- ✅ Keep entries concise (2-4 lines max)580- ✅ Date important decisions581- ✅ Remove outdated information582- ✅ Run /memory-gc monthly583- ✅ Review memory before starting work584585### Don't586- ❌ Copy entire code snippets (link instead)587- ❌ Document temporary decisions588- ❌ Keep superseded information589- ❌ Let memory grow >25KB590- ❌ Forget to update after major changes591592### Optimization Tips5935941. **Keep It Lean**: Target <20KB total memory5952. **Be Specific**: "Use PostgreSQL" > "Consider different databases"5963. **Date Decisions**: Helps identify stale entries5974. **One Topic Per Entry**: Easier to update/remove5985. **Link, Don't Copy**: Reference code/docs instead of duplicating599600## Integration with Other Plugins601602### Workflow Plugin603**Auto-reflection points**:604- `/explore complete`: Suggest project_state update605- `/plan created`: Suggest decisions.md entries606- `/ship complete`: Prompt for lessons_learned607608### Development Plugin609**Auto-reflection points**:610- `/review complete`: Suggest conventions updates611- `/fix applied`: Prompt for lessons_learned612- `/test coverage`: Update quality metrics613614### System Plugin615- `/status` shows memory state616- `/cleanup` can archive old memory617- `/audit` validates memory structure618619## Configuration620621### Memory Settings (`.claude/config.json`)622```json623{624 "memory": {625 "autoReflection": true,626 "staleThresholdDays": 30,627 "maxMemorySizeKB": 25,628 "autoBackup": true,629 "gcFrequency": "monthly"630 }631}632```633634### Auto-Reflection Triggers635```json636{637 "memory": {638 "reflectionTriggers": {639 "ship": true,640 "fix": true,641 "review": true,642 "explore": false643 }644 }645}646```647648### GC Settings649```json650{651 "memory": {652 "gc": {653 "autoClean": false,654 "requireConfirmation": true,655 "createBackup": true,656 "staleThresholdDays": 30657 }658 }659}660```661662## Dependencies663664### Required665None - Memory plugin is standalone666667### Optional MCP Tools668- **Sequential Thinking**: Enhances memory analysis and suggestions669670**Graceful Degradation**: All commands work without MCP tools.671672## Metrics673674The memory plugin tracks:675- **Memory size**: Total KB across all files676- **File count**: Number of memory files677- **Update frequency**: How often memory is updated678- **Stale entries**: Count of entries >30 days old679- **GC statistics**: Entries removed, size freed680681View with:682```bash683/memory-review684/status verbose685```686687## Troubleshooting688689### Memory files not loading690- **Check location**: Files must be in `.claude/memory/`691- **Check syntax**: Valid markdown required692- **Check permissions**: Files must be readable693694### /memory-gc removes too much695- **Adjust threshold**: Increase `staleThresholdDays` in config696- **Use --dry-run**: Preview before actual cleanup697- **Manual review**: Review suggestions before confirming698699### Memory growing too large700- **Run /memory-gc**: Clean stale entries701- **Remove code snippets**: Link instead of copying702- **Archive old content**: Move to `.claude/archives/`703- **Split files**: Break large files into focused ones704705### Auto-reflection not working706- **Check config**: Verify `autoReflection: true`707- **Check triggers**: Ensure command triggers are enabled708- **Manual update**: Use `/memory-update` directly709710## Examples711712### Example 1: New Project Setup713```bash714# Review current memory (likely empty)715/memory-review716717# Add initial project state718/memory-update719> add project_state.md720> "New SaaS authentication project, using Node.js + PostgreSQL"721722# Document initial decisions723/memory-update724> add decisions.md725> "Technology stack: Node.js, Express, PostgreSQL, JWT"726```727728### Example 2: After Feature Completion729```bash730# Ship feature731/ship --pr732733# Auto-reflection suggests updates734Memory Update Suggestions:7351. Add decision: "Use JWT for authentication"7362. Add lesson: "Pre-hash passwords for performance"737738# Apply suggestions739/memory-update740> (apply suggestions)741742# Review updated state743/memory-review744```745746### Example 3: Monthly Maintenance747```bash748# Review current state749/memory-review750# Shows: lessons_learned.md is 45 days old751752# Run garbage collection753/memory-gc --dry-run754# Shows: 5 stale entries found755756# Apply cleanup757/memory-gc758> Confirm cleanup? y759760# Verify761/memory-review762# Shows: Memory optimized, all files current763```764765## Support766767- **Documentation**: [Memory Management Guide](../../docs/guides/memory-management.md)768- **Issues**: [GitHub Issues](https://github.com/applied-artificial-intelligence/claude-code-toolkit/issues)769- **Discussions**: [GitHub Discussions](https://github.com/applied-artificial-intelligence/claude-code-toolkit/discussions)770771## License772773MIT License - see [LICENSE](../../LICENSE) for details.774775---776777**Version**: 1.1.0778**Category**: Core779**Commands**: 7 (memory-review, memory-update, memory-gc, index, handoff, continue, performance)780**Dependencies**: None781**MCP Tools**: Optional (sequential-thinking)782
Full transparency — inspect the skill content before installing.