MCPメモリサービス

ライセンス: MIT 鍛冶屋のバッジ

ChromaDBとセンテンストランスフォーマーを活用し、Claude Desktopにセマンティックメモリと永続ストレージ機能を提供するMCPサーバー。このサービスは、セマンティック検索機能を備えた長期メモリストレージを可能にし、会話やインスタンス間でのコンテキスト維持に最適です。

ヘルプ

TalkToGitHubでリポジトリと話しましょう!

Related MCP server: TranscriptionTools MCP Server

特徴

文変換を用いた意味検索
自然言語による時間ベースの想起（例：「先週」、「昨日の朝」）
タグベースの記憶検索システム
ChromaDB を使用した永続ストレージ
自動データベースバックアップ
メモリ最適化ツール
完全一致検索
類似性分析のデバッグモード
データベースの健全性監視
重複検出とクリーンアップ
カスタマイズ可能な埋め込みモデル
クロスプラットフォーム互換性（Apple Silicon、Intel、Windows、Linux）
さまざまな環境に合わせたハードウェア対応の最適化
限られたハードウェアリソースに対する適切なフォールバック

インストール

クイックスタート（推奨）

拡張インストールスクリプトはシステムを自動的に検出し、適切な依存関係をインストールします。

# Clone the repository
git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Run the installation script
python install.py

install.pyスクリプトは次の処理を実行します。

システムアーキテクチャと利用可能なハードウェアアクセラレータを検出します
プラットフォームに適した依存関係をインストールします
環境に最適な設定を構成する
インストールを確認し、必要に応じて診断を提供します

Dockerのインストール

Docker を使用してメモリサービスを実行できます。

# Using Docker Compose (recommended)
docker-compose up

# Using Docker directly
docker build -t mcp-memory-service .
docker run -p 8000:8000 -v /path/to/data:/app/chroma_db -v /path/to/backups:/app/backups mcp-memory-service

さまざまなシナリオに合わせて複数の Docker Compose 構成を提供します。

docker-compose.yml - pip install を使用した標準設定
docker-compose.uv.yml - UV パッケージマネージャーを使用した代替構成
docker-compose.pythonpath.yml - 明示的な PYTHONPATH 設定による構成

代替構成を使用するには:

docker-compose -f docker-compose.uv.yml up

Windows インストール (特殊なケース)

Windows ユーザーは、プラットフォーム固有のホイールの可用性により、PyTorch のインストールで問題が発生する可能性があります。Windows 専用のインストールスクリプトをご利用ください。

# After activating your virtual environment
python scripts/install_windows.py

このスクリプトは次の処理を行います。

CUDAの可用性とバージョンの検出
正しいインデックス URL から適切な PyTorch バージョンをインストールする
PyTorchと競合せずに他の依存関係をインストールする
インストールの確認

Smithery経由でインストール

Smithery経由で Claude Desktop のメモリサービスを自動的にインストールするには:

npx -y @smithery/cli install @doobidoo/mcp-memory-service --client claude

詳細なインストールガイド

包括的なインストール手順とトラブルシューティングについては、『インストールガイド』を参照してください。

クロードMCP構成

標準構成

claude_desktop_config.jsonファイルに次の内容を追加します。

{
  "memory": {
    "command": "uv",
    "args": [
      "--directory",
      "your_mcp_memory_service_directory",  // e.g., "C:\\REPOSITORIES\\mcp-memory-service"
      "run",
      "memory"
    ],
    "env": {
      "MCP_MEMORY_CHROMA_PATH": "your_chroma_db_path",  // e.g., "C:\\Users\\John.Doe\\AppData\\Local\\mcp-memory\\chroma_db"
      "MCP_MEMORY_BACKUPS_PATH": "your_backups_path"  // e.g., "C:\\Users\\John.Doe\\AppData\\Local\\mcp-memory\\backups"
    }
  }
}

Windows 固有の構成 (推奨)

Windows ユーザーの場合は、PyTorch が適切にインストールされていることを確認するために、ラッパースクリプトを使用することをお勧めします。

{
  "memory": {
    "command": "python",
    "args": [
      "C:\\path\\to\\mcp-memory-service\\memory_wrapper.py"
    ],
    "env": {
      "MCP_MEMORY_CHROMA_PATH": "C:\\Users\\YourUsername\\AppData\\Local\\mcp-memory\\chroma_db",
      "MCP_MEMORY_BACKUPS_PATH": "C:\\Users\\YourUsername\\AppData\\Local\\mcp-memory\\backups"
    }
  }
}

ラッパースクリプトは次の処理を実行します。

PyTorchがインストールされ、適切に設定されているか確認する
必要に応じて正しいインデックス URL で PyTorch をインストールします
適切な構成でメモリサーバーを実行する

使用ガイド

Claude Desktop のメモリサービスと対話する方法の詳細な手順については、以下を参照してください。

呼び出しガイド- クロードでメモリ操作をトリガーする特定のキーワードとフレーズを学びます
インストールガイド- 詳細なセットアップ手順

メモリサービスは、クロードとの会話の中で自然言語コマンドを通じて呼び出されます。例えば：

店舗へ: 「私のプロジェクトの締め切りは 5 月 15 日です。覚えておいてください。」
取得するには: 「プロジェクトの締め切りについて私が言ったことを覚えていますか?」
削除するには: 「私の住所についてお伝えしたことは忘れてください。」

コマンドの完全なリストと詳細な使用例については、呼び出しガイドを参照してください。

メモリ操作

メモリサービスは、MCP サーバーを通じて次の操作を提供します。

コアメモリ操作

store_memory - オプションのタグを使用して新しい情報を保存する
retrieve_memory - 関連する記憶の意味的検索を実行する
recall_memory - 自然言語の時間表現を使って記憶を思い出す
search_by_tag - 特定のタグを使って思い出を探す
exact_match_retrieve - コンテンツが完全に一致する思い出を検索
debug_retrieve - 類似度スコアで記憶を取得する

データベース管理

create_backup - データベースのバックアップを作成する
get_stats - メモリ統計を取得する
optimize_db - データベースのパフォーマンスを最適化する
check_database_health - データベースの健全性メトリクスを取得する
check_embedding_model - モデルの状態を確認する

メモリ管理

delete_memory - ハッシュで特定のメモリを削除する
delete_by_tag - 特定のタグが付いたすべての思い出を削除する
cleanup_duplicates - 重複したエントリを削除する

設定オプション

環境変数を使用して設定します。

CHROMA_DB_PATH: Path to ChromaDB storage
BACKUP_PATH: Path for backups
AUTO_BACKUP_INTERVAL: Backup interval in hours (default: 24)
MAX_MEMORIES_BEFORE_OPTIMIZE: Threshold for auto-optimization (default: 10000)
SIMILARITY_THRESHOLD: Default similarity threshold (default: 0.7)
MAX_RESULTS_PER_QUERY: Maximum results per query (default: 10)
BACKUP_RETENTION_DAYS: Number of days to keep backups (default: 7)
LOG_LEVEL: Logging level (default: INFO)

# Hardware-specific environment variables
PYTORCH_ENABLE_MPS_FALLBACK: Enable MPS fallback for Apple Silicon (default: 1)
MCP_MEMORY_USE_ONNX: Use ONNX Runtime for CPU-only deployments (default: 0)
MCP_MEMORY_USE_DIRECTML: Use DirectML for Windows acceleration (default: 0)
MCP_MEMORY_MODEL_NAME: Override the default embedding model
MCP_MEMORY_BATCH_SIZE: Override the default batch size

ハードウェアの互換性

プラットフォーム	建築	アクセル	状態
macOS	Appleシリコン（M1/M2/M3）	MPS	✅ 完全にサポートされています
macOS	Rosetta 2 搭載の Apple Silicon	CPU	✅ フォールバックでサポートされています
macOS	インテル	CPU	✅ 完全にサポートされています
ウィンドウズ	x86_64	CUDA	✅ 完全にサポートされています
ウィンドウズ	x86_64	ダイレクトML	✅ サポートされています
ウィンドウズ	x86_64	CPU	✅ フォールバックでサポートされています
リナックス	x86_64	CUDA	✅ 完全にサポートされています
リナックス	x86_64	ROCm	✅ サポートされています
リナックス	x86_64	CPU	✅ フォールバックでサポートされています
リナックス	ARM64	CPU	✅ フォールバックでサポートされています

テスト

# Install test dependencies
pip install pytest pytest-asyncio

# Run all tests
pytest tests/

# Run specific test categories
pytest tests/test_memory_ops.py
pytest tests/test_semantic_search.py
pytest tests/test_database.py

# Verify environment compatibility
python scripts/verify_environment_enhanced.py

# Verify PyTorch installation on Windows
python scripts/verify_pytorch_windows.py

# Perform comprehensive installation verification
python scripts/test_installation.py

トラブルシューティング

詳細なトラブルシューティング手順については、インストールガイドを参照してください。

簡単なトラブルシューティングのヒント

Windows PyTorch エラー: python scripts/install_windows.pyを使用する
macOS Intel 依存関係の競合: python install.py --force-compatible-depsを使用する
再帰エラー: python scripts/fix_sitecustomize.pyを実行します
環境検証: python scripts/verify_environment_enhanced.pyを実行します。
メモリの問題: MCP_MEMORY_BATCH_SIZE=4に設定し、より小さいモデルを試してください
Apple Silicon : Python 3.10+ が ARM64 用にビルドされていることを確認し、 PYTORCH_ENABLE_MPS_FALLBACK=1設定します
インストールテスト: python scripts/test_installation.pyを実行します。

プロジェクト構造

mcp-memory-service/
├── src/mcp_memory_service/      # Core package code
│   ├── __init__.py
│   ├── config.py                # Configuration utilities
│   ├── models/                  # Data models
│   ├── storage/                 # Storage implementations
│   ├── utils/                   # Utility functions
│   └── server.py                # Main MCP server
├── scripts/                     # Helper scripts
├── memory_wrapper.py            # Windows wrapper script
├── install.py                   # Enhanced installation script
└── tests/                       # Test suite

開発ガイドライン

型ヒント付きのPython 3.10+
モデルにデータクラスを使用する
モジュールと関数の三重引用符で囲まれたドキュメント文字列
すべてのI/O操作の非同期/待機パターン
PEP 8スタイルガイドラインに従う
新機能のテストを含める

ライセンス

MITライセンス - 詳細はLICENSEファイルを参照

謝辞

ベクターデータベースのChromaDBチーム
埋め込みモデルのためのSentence Transformersプロジェクト
プロトコル仕様のMCPプロジェクト

接触

電報

統合

MCPメモリサービスは、様々なツールやユーティリティで拡張できます。利用可能なオプションの一覧については、「統合」をご覧ください。

MCP メモリダッシュボード- メモリの閲覧と管理のための Web UI
Claude メモリコンテキスト- Claude プロジェクトの指示にメモリコンテキストを挿入します

MCP Memory Service