memory-mcp

memory-mcp

Claude Code 向けの永続メモリと Git スナップショットの自動作成機能です。コンテキストもコードも失いません。

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

memory-mcp を選ぶ理由

問題	解決策
セッションのたびにプロジェクトを説明し直す	判断、パターン、アーキテクチャを自動で記録
コンテキストウィンドウが埋まり、知識が失われる	2 層のメモリ：CLAUDE.md（即時）＋詳細検索
何かを壊したが、何が動いていたか思い出せない	保存のたびに Git スナップショットを作成し、すぐにロールバック
Claude がプロジェクトについて「把握している」内容がわからない	ビジュアルダッシュボードですべてのコンテキストを表示
クラウドストレージが心配	すべてローカルファイルで、Git リポジトリ内に保存

特長

• Git スナップショット — メモリを保存するたびに、プロジェクト全体をコミットします。いつでもロールバックできます。
• 2 層メモリ — CLAUDE.md はすぐに読み込まれ、詳細ストアは会話中に検索できます。
• LLM を活用 — Haiku が重要な情報を抽出し、重複を統合し、古い情報を整理します。
• ビジュアルダッシュボード — トークン数、種類別のメモリ、スナップショット履歴など、コンテキストを確認できます。
• 手間いらず — コマンドの実行は不要です。バックグラウンドで自動的に動作します。

クイックスタート

# 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

2 層のメモリアーキテクチャ：

層	目的	サイズ
CLAUDE.md	セッション開始時に自動読み込みされます。最も重要なコンテキストのうち、先頭から約 150 行を保持します。	コンパクト
.memory/state.json	メモリ全体を保存します。会話中に MCP ツールから検索できます。	無制限

フックによるバックグラウンドでの記録：

Claude Code のフックは、応答のたびに（Stop）、コンテキストの圧縮前に（PreCompact）、セッション終了時に（SessionEnd）実行されます。高速な LLM（Haiku）がトランスクリプトを読み取り、以下を抽出します。

• アーキテクチャ — システムの構成
• 判断 — Y ではなく X を選んだ理由
• パターン — 慣習や作業の進め方
• 注意点 — 直感的にはわかりにくい落とし穴
• 進捗 — 完了したこと、進行中のこと
• コンテキスト — ビジネス上の背景、期限、好み

スマートなメモリ管理：

• Jaccard 類似度による重複排除（メモリの重複を防止）
• 確信度の減衰（進捗は 7 日後、コンテキストは 30 日後に薄れます）
• LLM を活用した統合（重複するメモリを統合し、古いメモリを整理）
• 行数を調整した CLAUDE.md（約 150 行以内に保ち、重要な情報を先頭に配置）

更新

既存のインストールを更新するには：

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

フックを更新するには（バグ修正後など）：

memory-mcp setup

必要条件

• Claude Code CLI
• Node.js 18+
• Anthropic API キー（Haiku ベースの抽出機能に必要。抽出 1 回あたり約 $0.001）

CLI コマンド

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

コンテキストダッシュボード

memory-mcp context を使って、メモリの使用状況を可視化できます。

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

memory-mcp context --html を使うと、インタラクティブなブラウザダッシュボードを生成できます。

Git スナップショット

作業セッションに連動したプロジェクトの自動バージョン管理機能です。メモリを抽出するたびに、プロジェクト全体を非表示のブランチにコミットします。

# 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

仕組み：

• コミットは __memory-snapshots ブランチに記録されます（通常のワークフローでは表示されません）
• リモート（例：origin）へのプッシュは任意です
• コミットメッセージには、抽出されたメモリの内容が含まれます
• メモリファイルだけでなく、プロジェクト全体の状態を記録します

用途：

• 変更を壊してしまった後のロールバック
• 特定のセッション時点でのプロジェクトの状態を確認
• コンテキストの変化とあわせて、プロジェクトの変遷を追跡

MCP ツール（会話中に Claude が使用）

MCP サーバーとして設定すると、Claude はセッション中に次のツールにアクセスできます。

ツール	説明
memory_search	すべてのメモリをキーワード検索します
memory_related	タグまたは分野からメモリを取得します
memory_ask	質問をすると、メモリから LLM が合成した回答を取得します
memory_save	メモリを手動で保存します
memory_recall	フィルターを指定してすべてのメモリを一覧表示します
memory_delete	メモリを削除します
memory_consolidate	メモリの統合を実行します
memory_consciousness	意識ドキュメント全体を生成します
memory_stats	メモリの統計情報を表示します
memory_init	プロジェクト名と説明を設定します

保存される内容

メモリは 6 種類に分類されます。

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

CLAUDE.md の形式

既存の CLAUDE.md の内容を保持したまま、マーカーの間にメモリブロックが挿入されます。

# 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

プロジェクトごと：フックと MCP をプロジェクトごとに設定します。

memory-mcp init /path/to/project

設定

API キーは次の順序で解決されます。

1. ANTHROPIC_API_KEY 環境変数
2. ~/.memory-mcp/config.json
3. ~/.config/anthropic/api_key
4. ~/.anthropic/api_key

費用

抽出機能は、メモリの抽出と統合に Claude Haiku を使用します。一般的な費用は次のとおりです。

• 抽出 1 回あたり約 $0.001（Claude の各応答後）
• 統合 1 回あたり約 $0.005（抽出約 10 回ごと）
• 1 日のコーディング：約 $0.05～0.10

ライセンス

MIT