# Install globally
npm install -g claude-code-memory

# Interactive setup (API key + hooks)
memory-mcp setup

# Initialize a project
memory-mcp init ~/Projects/my-app

graph TB
    subgraph "Phase 1: Silent Capture"
        A[Claude Code Session] -->|User sends message| B[Claude responds]
        B -->|Hook fires: Stop/PreCompact/SessionEnd| C[extractor.js]
        C --> D[Read transcript from cursor]
        D --> E[Chunk if >6000 chars]
        E --> F[Send to Haiku LLM]
        F -->|Extract memories as JSON| G[Dedup via Jaccard similarity]
        G --> H[Save to .memory/state.json]
        H --> I[Decay confidence scores]
        I --> J{Consolidation needed?}
        J -->|>80 memories or every 10 extractions| K[Haiku merges/drops]
        J -->|No| L[Sync CLAUDE.md]
        K --> L
    end

    subgraph "Phase 2: Recovery"
        M[New session starts] -->|Built-in behavior| N[Claude reads CLAUDE.md]
        N --> O[Claude has full project context]
    end

    subgraph "Phase 3: Deep Recall"
        O --> P{Need specific context?}
        P -->|memory_search| Q[Keyword search across memories]
        P -->|memory_ask| R[Haiku synthesizes answer from top 30 matches]
        P -->|memory_related| S[Tag-based retrieval]
    end

    subgraph "Data Store"
        H -.-> T[(.memory/state.json<br/>Full memory store)]
        L -.-> U[(CLAUDE.md<br/>~150 line summary)]
        T -.->|MCP tools read| Q
        T -.->|MCP tools read| R
        T -.->|MCP tools read| S
    end

    style A fill:#4a9eff,color:#fff
    style F fill:#ff6b6b,color:#fff
    style K fill:#ff6b6b,color:#fff
    style R fill:#ff6b6b,color:#fff
    style T fill:#ffd93d,color:#000
    style U fill:#6bcb77,color:#000

npm install -g claude-code-memory --force

memory-mcp setup

memory-mcp setup              Interactive first-time setup
memory-mcp init [dir]          Initialize memory for a project
memory-mcp status [dir]        Show memory status and health
memory-mcp statusline [dir]    Compact one-line status (great for shell prompts)
memory-mcp context [dir]       Show context metrics and token usage
memory-mcp context --html      Generate visual HTML dashboard
memory-mcp search <query>      Search memories by keyword
memory-mcp ask <question>      Ask a question, get answer from memory
memory-mcp consolidate [dir]   Merge duplicates, prune stale memories
memory-mcp key [api-key]       Set or check Anthropic API key
memory-mcp snapshots [dir]     List git snapshot history
memory-mcp snapshot-enable     Enable automatic git snapshots
memory-mcp snapshot-disable    Disable git snapshots
memory-mcp help                Show help

Context Dashboard

  Project: my-app

  Total Context
  2.8K estimated tokens

  Tier 1 CLAUDE.md (auto-loaded)
  █████████████████░░░░░░░░░░░░░ 1.0K
  45 lines, 44 in memory block

  Tier 2 .memory/state.json (searchable)
  ██████████████████████████████ 1.8K
  29 active, 5 archived, 24 superseded

  Memories by Type
  architecture ███░░░░░░░░░░░░░░░░░   8 memories (291 tokens)
  decision     ██████░░░░░░░░░░░░░░  18 memories (540 tokens)
  gotcha       ████░░░░░░░░░░░░░░░░  10 memories (332 tokens)
  progress     ██████░░░░░░░░░░░░░░  19 memories (538 tokens)

  Git Snapshots
  ● Enabled on __memory-snapshots
  42 commits → origin

# Enable during init (you'll be prompted)
memory-mcp init ~/Projects/my-app

# Or enable later
memory-mcp snapshot-enable

# View snapshot history
memory-mcp snapshots

# Compare two snapshots
memory-mcp snapshot-diff abc123 def456

# Restore to a previous state
memory-mcp snapshot-restore abc123

# Disable (preserves existing snapshots)
memory-mcp snapshot-disable

architecture   "Next.js 14 app router with Supabase backend, Stripe for billing"
decision       "Chose server components for public pages because of SEO requirements"
pattern        "All API routes validate input with zod and return NextResponse"
gotcha         "Supabase RLS policy on word_lists requires user_id OR org_id, not both"
progress       "Auth complete, billing webhook handling in progress"
context        "Client wants launch by March, focus on core features only"

your-project/
├── CLAUDE.md              ← auto-updated memory summary (read on session start)
├── .memory/
│   ├── state.json         ← full memory store
│   └── cursor.json        ← tracks what's been processed
├── .mcp.json              ← MCP server configuration
└── .claude/
    └── settings.json      ← hook configuration

# MyProject
A brief description

_Last updated: 2026-01-27 | 45 active memories, 62 total_

## Architecture
- Next.js 14 app router with Supabase backend
- Auth via NextAuth with Google and email providers

## Key Decisions
- Chose server components for SEO pages
- Using Supabase RLS instead of API-level auth

## Patterns & Conventions
- All API routes use zod validation
- Tailwind only, no CSS modules

## Gotchas & Pitfalls
- RLS policy requires user_id OR org_id, not both

## Current Progress
- Auth: complete
- Billing: in progress

## Context
- Launch target: March

_For deeper context, use memory_search, memory_related, or memory_ask tools._

memory-mcp setup  # select "global" when prompted

memory-mcp init /path/to/project