/memory — Project Memory

Step 0: Resolve memory directory

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" dir   # same folder as CC auto-memory (git root); prints the path, exits 1 if no memory yet

memory.js resolves the memory dir from cwd itself — no --dir needed. Each bash block runs in a fresh shell, so do not rely on variables set in another block.

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

Bootstrap for this project:

1. Create memory dir: mkdir -p "$(node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" dir)" (prints the path even when it does not exist yet)
2. Do NOT copy memory.js if the plugin is installed — use ${CLAUDE_PLUGIN_ROOT}/scripts/memory.js. Only copy if the plugin is not installed.
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 path to memory.js} <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}

7. Verify: node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" list
8. "Memory ready. You can start working — /memory for lookup."

Commands (when initialized)

All commands resolve the memory dir from cwd (or from the symlink location when called as memory/memory.js):

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" <command> [args]

No arguments

Show workstreams + quick actions:

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" workstreams

search <query>

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" search "<query>"

Summarize — don't dump raw. Highlight relevant to current task.

workstream <name>

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" workstream "<name>"

workstreams

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" workstreams

add-workstream <name> <keywords...>

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" add-workstream "<name>" <keywords...>

recent [n]

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" recent <n>

decisions [topic]

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" decisions "<topic>"

list [type]

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" list <type>

note <text>

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" note "<text>"

handoff [<workstream>]

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" handoff              # global handoff
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" handoff <workstream> # per-ws (falls back to global)

Prints NO_HANDOFF when neither per-workstream nor global file exists.

write-handoff --workstream=<name> --content=<file>

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" write-handoff --workstream=<name> --content=<path>
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" write-handoff --global --content=<path>   # workstreams/handoff.md

Frontmatter auto-added; modified and branch are stamped so the SessionStart hook can flag an old or other-branch handoff.

card <workstream> [--material]

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" card <workstream>             # the card, or NO_CARD
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" card <workstream> --material  # + decisions to draft or update it from

A workstream — a task, an experiment, an area — lives in a card, workstreams/<name>.md, kept current during work: what it is, why, what it doesn't do, where results live, what's open — sections as the workstream needs, status in free words. When a decision, an iteration result or an open question about it comes up, offer to update the card; draft from --material (decisions, corrections and reflections the watcher logged, newest first, with a marker where the card was last updated). Show the change, write only after the user agrees. Past ~150 lines move finished iterations out.

write-card --workstream=<name> --content=<file>

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" write-card --workstream=<name> --content=<path>

Writes workstreams/<name>.md (not the Write tool: CC's stamper would reshuffle the frontmatter); adds type: project, category: workstream if missing and stamps modified.

receipt [--json]

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" receipt

What this session left: memory files it wrote (by originSessionId), decisions / corrections / DOC / commits logged since its start, the workstreams it moved and whether their cards were updated. Writes nothing.

park / parked / unpark

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" park --title="<title>" --content=<path> [--workstream=<name>] [--kind=idea|task|question]
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" parked [<workstream>]          # parked items, oldest flagged, plus recent PARKED: notes
node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" unpark <file> --to=<where>     # the exit: picked-up | backlog | decision | ideas | drop

Parked is a state with an exit, not an ideas catalog: one file per item (workstreams/<name>/<slug>.md, or parked/<slug>.md), so recall can surface it. Use /park to draft and confirm.

unassigned [--days=30]

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" unassigned

Decisions that match no workstream's keywords, by day — material for proposing a new workstream when a theme recurs.

signals [--branch=<branch>]

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" signals   # JSON: card index, card gaps, new-workstream, parked, pending DOC, recently offered

Input for the SessionStart hook. It shows the user at most two invitations (💡 lines) and logs OFFERED: <key> so the same one does not come back for two weeks; the model gets only the card index. Workstreams stay optional.

classify --items=<json>

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" classify --items=<path-to-json>

Keyword-routes items by workstreams.json. Multi-label, case-insensitive. Unmatched → _unassigned.

session-activity

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" session-activity

Current session's items (and DOC: subset) since last SESSION_START marker in today's notes. JSON output.

session-changes

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" session-changes

Git commits + files union since session start. JSON output. Pipe with session-activity into classify for routing analysis (see /session-end Phase 1b).

docs

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" docs

DOC: notes since the last review (DOCS_REVIEWED marker) for /docs-reflect. --all lists every one; --mark-reviewed closes a review.

recurring

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" recurring

Find recurring feedback patterns.

reindex

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" reindex

Rebuild MEMORY.md index sorted by weight.

health

node "${CLAUDE_PLUGIN_ROOT}/scripts/memory.js" health

Check for dead links, stale entries, size overflow, duplicates.

Rules

• Don't dump raw output — summarize and highlight relevant
• If not initialized → bootstrap automatically, don't error
• MEMORY.md = index. Detailed content in separate .md files