memory

/memory — Project Memory

---

Step 0: Resolve memory directory

# Claude Code uses git root (not cwd) and replaces / and . with - for project key
GIT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
PROJ_KEY=$(echo "$GIT_ROOT" | tr '/.' '-' | sed 's/^-//')
MEM_DIR="$HOME/.claude/projects/-${PROJ_KEY}/memory"

Resolve memory.js:

MEM="${CLAUDE_PLUGIN_ROOT}/scripts/memory.js"

---

If not initialized (no memory.js and no plugin found)

Bootstrap for this project:

1. Create memory dir: mkdir -p "$MEM_DIR"
2. Do NOT copy memory.js if the plugin is installed — use $MEM resolved above. Only copy if plugin is not installed and no $MEM found.
3. Ask: "What workstreams does the project have?" → create workstreams.json
4. Ask: "Describe your role in 1-2 sentences" → Profile
5. Ask: "Key links?" → Reference
6. Create MEMORY.md:

# {Project} — Memory

## API
\```bash
node {absolute $MEM path} --dir={MEM_DIR} <command>
\```

## Profile
{user answer}

## Rules

### Save
- Decision with reasoning → memory file with **Why:** and **How to apply:**
- User corrects you or confirms non-obvious choice → feedback memory
- Something surprising or counter-intuitive → note + memory
- Convert relative dates to absolute: "Thursday" → "2026-04-10"

### Don't save
- What git log already knows (commits, who changed what)
- What the code already shows (patterns, architecture)
- What CLAUDE.md already says
- Ephemeral task state (use TodoWrite)

### Format
- MEMORY.md = index only, max 200 lines. Details in separate .md files
- Each .md file has frontmatter: name, description, type (feedback/project/user/reference)
- workstreams.json = source of truth for aliases
- Use --brief for quick overviews, full output only when needed

### Session lifecycle
- Start of work → /session-start or /session-continue
- Ideas for later → /park (don't lose the thought)
- After big block of work → /reflect (workarounds, repetitions, insights → backlog)
- Before compact: save key decisions + update handoff
- Long session + topic changed → suggest /session-end
- End of work → /session-end (handoff for next session)

## Reference
{user links}