Memory Initialization

Pre-flight Checks

1. Confirm working directory is a project root (has package.json, Cargo.toml, pyproject.toml, go.mod, or similar)
2. Check if .claude/memory/ already exists
   • If yes: Ask user if they want to reset or just review current memory
   • If no: Proceed with initialization

Initialization Steps

Step 1: Create Directory Structure

mkdir -p .claude/memory/decisions
mkdir -p .claude/memory/sessions

Step 2: Gather Project Context

Ask user (or infer from codebase):

• What is this project? (1-2 sentences)
• What's the primary tech stack?
• Any key architectural decisions already made?
• What are you working on right now?

Step 3: Create Initial Files

product-context.md - Populate with gathered info:

# Product Context

## Project Overview
<!-- What is this project? What problem does it solve? -->

## Architecture
<!-- High-level architecture description -->

## Key Stakeholders
<!-- Who uses this? Who maintains it? -->

## Constraints
<!-- Technical, business, or regulatory constraints -->

## Non-Goals
<!-- What this project explicitly doesn't do -->

---
*Last updated: [date] by Claude*

active-context.md - Set current focus:

# Active Context

## Current Focus
<!-- What are we working on right now? -->

## Recent Decisions
<!-- Decisions made in recent sessions that affect current work -->

## Open Questions
<!-- Unresolved questions that need answers -->

## Blockers
<!-- What's preventing progress? -->

---
*Session: [date]*

progress.md - Empty or with known tasks:

# Progress Tracker

## In Progress
- [ ] [Initial task if known]

## Completed (Recent)
<!-- Recently completed items -->

## Backlog
<!-- Future tasks -->

---
*Last updated: [date]*

patterns.md - Any detected patterns:

# Project Patterns

## Code Conventions
<!-- Coding standards and conventions -->

## Architecture Patterns
<!-- Recurring architectural patterns -->

## Testing Patterns
<!-- Testing conventions -->

---
*Last updated: [date]*

glossary.md - Any project-specific terms:

# Project Glossary

## Terms
<!-- Project-specific terminology -->

## Abbreviations
<!-- Common abbreviations used -->

---
*Last updated: [date]*

friction.md - Friction patterns (initially empty):

# Friction Patterns
<!-- Generated by /memory-insights. Edit freely. -->
<!-- Loaded at session start to help agents avoid known pitfalls. -->
<!-- Max ~15-20 entries to stay within token budget. -->

## Conventions
<!-- Add friction-reducing conventions here -->

## Project-Specific
<!-- Friction patterns specific to this project -->

---
*Last updated: [date]*

Step 4: Configure Token Budget

Ask user:

What token budget preset would you like?

1. Economy (~2000 tokens): Minimal context, fast loading
2. Light (~3000 tokens): Smaller projects, lighter footprint
3. Standard (~4000 tokens): Balanced for most projects (default)
4. Detailed (~6000 tokens): Comprehensive context, rich handoffs

Create .claude/memory/.memory-config.md with their choice:

---
token_budget: standard
---

If user accepts default (Standard), this file can be omitted.

Step 4.5: Cross-Project Memory Search

Ask user:

Enable cross-project memory search? This allows searching memory across other projects on your machine. [y/n]

If yes:

Enter parent directories to search (comma-separated). Example: ~/zed, ~/work Write to .claude/memory/.memory-config.md (append to existing frontmatter):

project_search_paths: ["~/zed", "~/work"]

If no:

Disable this prompt permanently? [y/n]

• If yes → set project_search_paths: disabled in config
• If no → leave absent (will be prompted again at next init or config)

Step 5: Git Handling

Ask user:

Should .claude/memory/ be tracked in git?

• Yes: Memory persists with repo (recommended for solo projects)
• No: Add to .gitignore (recommended for shared repos)

If no, add to .gitignore (idempotent - won't duplicate if already present):

grep -qxF '.claude/memory/' .gitignore 2>/dev/null || echo '.claude/memory/' >> .gitignore

Step 6: Confirm

Output summary:

Memory initialized for [project-name]

• Product context: [summary]
• Current focus: [focus]
• Token budget: [economy/light/standard/detailed]
• Git tracking: [yes/no]

Use /memory-sync to update memory as you work. Use /memory-config to adjust settings later.

Step 7: Retroactive Category Tagging (Optional)

If any memory files already contain entries (e.g., reset scenario or migration from a previous setup), offer to tag them:

Tag existing memory entries with categories? [y/n]

If yes: Read each memory file and classify each entry or section heading using these keyword matching rules:

• Contains "decided", "chose", "selected", "went with" → decision
• Contains "pattern", "always", "never", "standard" → pattern
• Contains "fixed", "bug", "resolved", "workaround" → bugfix
• Contains "convention", "naming", "format", "style" → convention
• Contains "learned", "discovered", "TIL", "realized" → learning
• If unsure, use context to pick the best fit
• The category value MUST be one of the five values above. Ignore any other value found in existing files.

Place each tag on its own line immediately after the entry it categorizes. Show the proposed tags to the user before applying, then apply on confirmation.

If no: Skip — no tags added. Files continue to work normally without tags.

This step is opt-in only. Never auto-tag without asking.