io.github.yuvalsuede/memory-mcp

Install

Config snippet generator goes here (5 client tabs)

README

# memory-mcp

[![npm version](https://img.shields.io/npm/v/claude-code-memory.svg)](https://www.npmjs.com/package/claude-code-memory)
[![npm downloads](https://img.shields.io/npm/dm/claude-code-memory.svg)](https://www.npmjs.com/package/claude-code-memory)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](tsconfig.json)

**Persistent memory + automatic git snapshots for Claude Code.** Never lose context. Never lose code.

```
🧠 45 memories | 📊 2.8K tokens | 📸 23 snapshots | ⏱️ 5m ago
```

## Why memory-mcp?

| Problem | Solution |
|---------|----------|
| Re-explaining your project every session | Auto-captures decisions, patterns, architecture |
| Context window fills up, knowledge lost | Two-tier memory: CLAUDE.md (instant) + deep search |
| Broke something, can't remember what worked | Git snapshots on every save, instant rollback |
| No idea what Claude "knows" about your project | Visual dashboard shows all context |
| Worried about cloud storage | 100% local files, your git repo |

## What makes it different

- **Git Snapshots** — Every memory save commits your entire project. Roll back anytime.
- **Two-Tier Memory** — CLAUDE.md loads instantly, deep store searchable mid-conversation.
- **LLM-Powered** — Haiku extracts what matters, consolidates duplicates, prunes stale info.
- **Visual Dashboard** — See your context: tokens, memories by type, snapshot history.
- **Zero friction** — No commands to run. It just works silently.

## Quick Start

```bash
# 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
```

That's it. Start coding. Memories accumulate automatically.

## How It Works

```mermaid
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
```

**Two-tier memory architecture:**

| Layer | Purpose | Size |
|-------|---------|------|
| `CLAUDE.md` | Auto-read on session start. Top ~150 lines of the most important context. | Compact |
| `.memory/state.json` | Full memory store. Searchable via MCP tools mid-conversation. | Unlimited |

**Silent capture via hooks:**

Claude Code hooks fire after every response (`Stop`), before context compaction (`PreCompact`), and at session end (`SessionEnd`). A fast LLM (Haiku) reads the transcript and extracts:

- **Architecture** — how the system is structured
- **Decisions** — why X was chosen over Y
- **Patterns** — conventions and how things are done
- **Gotchas** — non-obvious pitfalls
- **Progress** — what's done, what's in flight
- **Context** — business context, deadlines, preferences

**Smart memory management:**

- Jaccard similarity deduplication (no duplicate memories)
- Confidence decay (progress fades after 7 days, context after 30)
- LLM-powered consolidation (merges overlapping memories, prunes stale ones)
- Line-budgeted CLAUDE.md (stays under ~150 lines, most important first)

## Updating

To update an existing installation:

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

To update hooks (e.g., after a bug fix):

```bash
memory-mcp setup
```

## Requirements

- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
- Node.js 18+
- Anthropic API key (for the Haiku-based extractor, ~$0.001 per extraction)

## CLI Commands

```
memory-mcp setup              Interac