MCPメモリサービス
ChromaDBとセンテンストランスフォーマーを活用し、Claude Desktopにセマンティックメモリと永続ストレージ機能を提供するMCPサーバー。このサービスは、セマンティック検索機能を備えた長期メモリストレージを可能にし、会話やインスタンス間でのコンテキスト維持に最適です。
ヘルプ
TalkToGitHubでリポジトリと話しましょう!
特徴
- 文変換を用いた意味検索
- 自然言語による時間ベースの想起（例：「先週」、「昨日の朝」）
- タグベースの記憶検索システム
- 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メモリサービスは、様々なツールやユーティリティで拡張できます。利用可能なオプションの一覧については、 「統合」をご覧ください。