memory-setup

/memory-setup — Initialize or upgrade project memory

Detects existing memory, adds what's missing, doesn't overwrite anything.

Step 1: Find memory directory

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"

Check what already exists:

echo "=== Memory dir: $MEM_DIR ==="
[ -d "$MEM_DIR" ] && echo "DIR: exists" || echo "DIR: missing"
[ -f "$MEM_DIR/MEMORY.md" ] && echo "MEMORY.md: exists" || echo "MEMORY.md: missing"
[ -f "$MEM_DIR/memory.js" ] && echo "memory.js: exists" || echo "memory.js: missing"
[ -f "$MEM_DIR/workstreams.json" ] && echo "workstreams.json: exists" || echo "workstreams.json: missing"
ls "$MEM_DIR"/*.md 2>/dev/null | wc -l | xargs -I{} echo "MD files: {}"
ls -d "$MEM_DIR"/*/ 2>/dev/null | wc -l | xargs -I{} echo "Subdirs: {}"

Report findings to the user before making any changes.

Step 2: Branch by state

A) No memory dir at all → fresh setup

If --fresh argument or no $MEM_DIR:

Before creating anything, show the user what will be set up:

Fresh memory setup for this project:
  Dir: {MEM_DIR}
  Will create: MEMORY.md, workstreams.json, memory-schema.json
  Subdirs: feedback/, decisions/, profile/, reference/, notes/, workstreams/
  Will ask: workstreams, role, language, key links

Proceed? (yes/skip)

Wait for confirmation before creating any files.

1. mkdir -p "$MEM_DIR"
2. If no CLAUDE_PLUGIN_ROOT: cp /path/to/memory-toolkit/scripts/memory.js "$MEM_DIR/"
3. Ask: "What are the main workstreams in this project?" → create workstreams.json
4. Profile interview → create profile/user-role.md (frontmatter type: user).

Ask sequentially, accept short answers, skip empty:

• Role: "What's your role and team?" (job title, company, team size)
• Initiative: "What's the broader initiative or goal you're driving here?"
• Communication style: "Anything about how you like to work? (pacing, directness, things that annoy you)"
• Domain terminology: "Any project-specific terms I should know? (e.g. портфель instead of sprint, custom SP units)"

Write as markdown with Section: headers, not a single paragraph. This profile gets auto-loaded via MEMORY.md and shapes how the agent communicates with you.

1. Ask: "What language do you prefer for documentation and rules? (e.g. English, Russian)" → create profile/language.md
2. Ask: "Key links (Jira, Figma, Slack, docs)?" → create reference/links.md
3. Create MEMORY.md from template (see Step 4)
4. Copy memory-schema.json: cp "${CLAUDE_PLUGIN_ROOT}/scripts/lib/memory-schema.default.json" "$MEM_DIR/memory-schema.json"
5. Create subdirectories: mkdir -p "$MEM_DIR"/{feedback,decisions,profile,reference,notes,workstreams}

B) Existing MEMORY.md → upgrade in place

This is the common path for users with Claude Code auto-memory.

1. Backup MEMORY.md before any changes:

``bash cp "$MEM_DIR/MEMORY.md" "$MEM_DIR/MEMORY.md.backup.$(date +%Y%m%d-%H%M%S)" `` Tell the user: "Backed up MEMORY.md to MEMORY.md.backup.{timestamp}"

1. Read existing MEMORY.md — understand current structure
2. Copy memory.js if missing
3. Analyze existing .md files — detect types from frontmatter
4. Propose changes (don't apply yet)

Step 3: Upgrade checklist (for path B)

Show the user what will be added/changed:

## Memory setup for {project}

Found: {N} memory files, MEMORY.md ({lines} lines)

Proposed changes:
  [ ] Backup MEMORY.md → MEMORY.md.backup.{timestamp}
  [ ] Ensure memory.js accessible (plugin or manual copy)
  [ ] Add API block to MEMORY.md
  [ ] Add Rules block to MEMORY.md  
  [ ] Add Session lifecycle block to MEMORY.md
  [ ] Create workstreams.json from existing files
  [ ] Create memory-schema.json (weighted eviction config)
  [ ] Create subdirectories (feedback/, decisions/, etc.)
  [ ] Move files to subdirectories by type
  [ ] Profile interview → profile/user-role.md (if missing)

Already in place:
  [x] MEMORY.md exists
  [x] {list what's already there}

Proceed? (or pick specific items)

Wait for user confirmation before making changes.

Step 4: Apply changes

4a: Resolve memory.js path

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

Use $MEM as an absolute path when writing the API block into MEMORY.md.

4b: Update MEMORY.md

Read current MEMORY.md. Ensure the structure follows this order:

1. Heading (first line)
2. API block (lines 3-6) — always near the top
3. Rules block (lines 8-30) — always before index entries
4. Index entries — the rest of the file

This order matters: Claude Code truncates MEMORY.md after 200 lines. By keeping API and Rules at the top, they survive truncation even if auto-memory adds many index entries.

API block (add if missing, right after heading — one compact line, use the absolute $MEM path resolved in 4a):

## API
`node {absolute path to memory.js} --dir={MEM_DIR} <command>`

Rules block (add if missing, after API and before index entries).

## 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 workstream 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
- Before compact: save key decisions + update handoff
- Long session + topic changed → suggest /session-end
- End of work → /session-end (handoff for next session)

Do NOT remove or rewrite existing content in MEMORY.md. Only add new blocks.

4c: Create workstreams.json

Scan existing files for patterns — group by frontmatter type or directory:

node "$MEM_DIR/memory.js" --dir="$MEM_DIR" list

Ask: "Based on these files, I see topics like {X, Y, Z}. Want me to create workstreams for them?"

4d: Add workstreams to MEMORY.md index

After creating workstreams.json, add a Workstreams section to MEMORY.md so they are visible in the index:

## Workstreams
- **{name}** — keywords: {keywords}

This ensures agents see workstreams without running memory.js workstreams.

4d-bis: Profile section in MEMORY.md

If profile/user-role.md exists (or was just created), ensure MEMORY.md has a ## Profile section indexing it:

## Profile
- [User role](profile/user-role.md) — {one-line description from frontmatter}

Place it right after the ## Rules block — profile is high-signal context, agent should see it early.

4d-ter: Profile interview for upgrade path

If path B (upgrade) and profile/user-role.md does NOT exist, run the same interview as Step 2A point 4. Skip if user declines.

4e: Create subdirectories and move files

Only if user agrees. For each .md file with frontmatter type:

type: feedback  → feedback/
type: project   → decisions/ or notes/ (by content)
type: user      → profile/
type: reference → reference/

After moving files — update paths in MEMORY.md index.

4f: Create memory-schema.json

If memory-schema.json is missing in $MEM_DIR:

if [ -f "${CLAUDE_PLUGIN_ROOT}/scripts/lib/memory-schema.default.json" ]; then
  cp "${CLAUDE_PLUGIN_ROO