---
name: memory-bank
description: >
  Build and synchronize a structured memory bank of project knowledge.
  Invoke for: "memory bank", "update memory bank", "sync memory", "knowledge sync",
  "update project knowledge", "synchronize memory bank", "memory bank update",
  "keep memory current", "project memory", "update knowledge base with code changes".
  Inspired by russbeye/claude-memory-bank pattern.
argument-hint: scope to sync (e.g. "src/api/", "after this PR", "full project")
allowed-tools: Read, Write, Edit, Grep, Glob, Bash
---

# Skill: Memory Bank — Structured Project Knowledge Sync

## Role
Build and maintain a structured memory bank at `.claude/memory/` that stays
synchronized with code changes. Acts as a long-term knowledge layer that survives
context compaction and session resets.
Inspired by russbeye/claude-memory-bank.

## Memory Bank Structure

```
.claude/memory/
├── hot/
│   └── hot-memory.md          # Always loaded (≤50 lines, key active context)
├── warm/
│   ├── architecture.md        # System design, component relationships
│   ├── decisions.md           # Key decisions with rationale
│   ├── patterns.md            # Recurring code patterns, idioms
│   ├── troubleshooting.md     # Known issues, workarounds, gotchas
│   └── api-surface.md         # Public API contracts and conventions
└── glacier/
    └── YYYY-MM-DD-<slug>.md   # Archived decisions + historical context
```

## When to invoke
- After a major refactor (sync architecture.md)
- After resolving a tricky bug (sync troubleshooting.md)
- After adding a new API endpoint (sync api-surface.md)
- After making an architectural decision (sync decisions.md)
- Periodically to keep memory current

## Instructions

### Full sync
1. Read all source files in scope (or all of `src/` for full sync)
2. Compare against existing warm-tier files
3. Update each warm-tier file with what's changed:
   - `architecture.md`: component diagram, module responsibilities, data flow
   - `decisions.md`: key choices with WHY, not just what
   - `patterns.md`: recurring idioms, anti-patterns seen
   - `troubleshooting.md`: tricky bugs, gotchas, workarounds
   - `api-surface.md`: endpoint signatures, request/response models
4. Update hot-memory.md with any critical new facts (keep ≤50 lines)
5. Archive stale but important context to glacier

### After a specific change
Use `/context-diff` first to understand what changed, then update only the relevant warm-tier files.

### Query mode
`/memory-bank query "src/auth/**"` — surface relevant warm-tier documentation for a path

## Path-Filtered Query

When given a path argument:
1. Identify which warm-tier file covers that domain
2. Return the relevant section
3. Note if it's stale (last updated >2 weeks ago)

## Output

```
## Memory Bank Sync: <scope>

### Updated
- warm/architecture.md → added FastAPI middleware order diagram
- warm/decisions.md → logged setuptools.build_meta decision
- warm/troubleshooting.md → added exc_info filtering gotcha

### Hot memory: updated active_feature key

### No changes needed
- warm/api-surface.md (current)
- warm/patterns.md (current)

### Archived to glacier
- Old routing design (pre-v0.9.0) → glacier/2026-04-05-routing-v1.md
```