Memorious MCP

memorious-mcp

AI アシスタント向けの100%ローカルかつプライベートなセマンティックメモリ MCP（Model Context Protocol）サーバーです。ベクトル類似検索には ChromaDB、実装には FastMCP 2 を使用しています。すべてローカルで実行され、データがマシンの外に送信されることはありません。

概要

memorious-mcp は、store、recall、forget の3つの主要な操作を通じて、AI アシスタントに長期記憶機能を提供します。ChromaDB のベクトルデータベースを使ってセマンティック類似検索を実現するため、元の保存時と正確な表現が異なっていても、関連する記憶を取得できます。すべての処理と保存はマシン上でローカルに行われ、データがマシンの外に送信されることはないため、プライバシーとセキュリティが完全に保たれます。

主な機能

• 🏠 100%ローカルかつプライベート：すべてのデータ処理と保存はマシン上で行われ、クラウドに送信されることはありません
• 💾 永続メモリ：ChromaDB のディスクベースストレージを使用して、セッションをまたいでデータを保持します
• 🔍 セマンティック検索：ベクトル埋め込みにより、類似性に基づくメモリの取得を実現します
• ⚡ シンプルな API：メモリ管理のための直感的なツールが3つ用意されています
• 🚀 FastMCP との統合：効率的な MCP サーバー実装のために FastMCP を基盤として構築されています
• 🎯 標準キー設計：短く、埋め込みに適したキー（1～5語）に最適化されています
• 📂 フォルダー単位のストレージ：プロジェクトごとにメモリを分離します。

このプロジェクトが作られた理由

🔍 MCP エコシステムのギャップ：メモリ MCP サーバーの人気が高まる一方で、セマンティック類似検索と、ファイルベースで完全にローカルなフォルダー単位のストレージの両方を備えた既存のメモリサーバーはありませんでした。多くのメモリソリューションには、次のいずれかの問題があります。

• ☁️ 埋め込み、ストレージ、またはその両方にクラウドサービスや外部 API 呼び出しが必要（プライバシーを損なう）
• 🔤 完全一致のキーと値の照合のみをサポート（セマンティックな理解がない）
• 📁 フォルダー単位のローカルストレージをサポートしていない

ユースケース

• パーソナルアシスタントのメモリ：ユーザーの好み、習慣、個人情報を記憶します
• コンテキストの保持：セッションをまたいで会話のコンテキストを維持します
• ナレッジ管理：プロジェクト固有の情報を保存し、取得します
• パーソナライズ：保存された好みに基づき、AI アシスタントがパーソナライズされた回答を提供できるようにします
• プライバシー優先の AI：機密性の高い個人データをローカルに保ちながら、永続的なメモリを利用できます
• フォルダー単位の AI エージェント：プロジェクトごとにメモリを分離できるため、VS Code Copilot Chat Modes や Claude Code agents に最適です

インストール

VS Code の場合

まず、uv とその uvx コマンドがインストールされていることを確認してください。

ほとんどの MCP クライアントの場合

MCP クライアントの設定に追加してください。

{
  "mcpServers": {
    "memorious": {
      "command": "uvx",
      "args": ["memorious-mcp"]
    }
  }
}

開発／ローカルインストール

uv sync

開発／ローカルインストールの場合：

{
  "mcpServers": {
    "memorious": {
      "command": "uv",
      "args": ["run", "memorious-mcp"],
      "cwd": "/path/to/memorious-mcp"
    }
  }
}

ツール

store

ベクトル類似検索に適した短い標準キーを使って、事実、好み、または情報を保存します。

パラメーター：

• key（string）：短い標準キー（1～5語、スペース区切り）
• value（string）：保存する情報の内容

recall

セマンティック類似検索を使って、保存された記憶を取得します。

パラメーター：

• key（string）：類似検索に使うクエリーキー
• top_k（int、デフォルト：3）：返す結果の最大数

forget

クエリキーに一致する記憶を削除します。

パラメーター:

• key (string): 削除する記憶を検索するためのクエリキー
• top_k (int, default: 3): 検討する最も近い一致候補の数

Claude CLI の設定

Claude CLI に memorious-mcp を追加するには、次のコマンドを使用します。

# Add the MCP server using uvx (recommended)
claude mcp add memorious-mcp uvx memorious-mcp

# Alternative: for development/local installation
claude mcp add memorious-mcp uv run --project <memorious_mcp_src> memorious-mcp

設定済みの MCP サーバーを一覧表示できます。

claude mcp list

必要に応じて、サーバーを削除できます。

claude mcp remove memorious-mcp

ツールのシグネチャの例

• store(key: str, value: str) -> {"id": str}
• recall(key: str, top_k: int = 3) -> {"results": [...]} 各結果には id、key、value、distance、timestamp が含まれます
• forget(key: str, top_k: int = 3) -> {"deleted_ids": [...]}

テスト

次のコマンドでテストを実行します。

# Using uv
uv run python -m pytest tests/ -v

# Or if pytest is available globally
pytest tests/ -v

技術的な詳細

• バックエンド: 永続ディスクストレージを使用する ChromaDB
• 埋め込み: ChromaDB のデフォルトの埋め込み関数を使用します（ローカルで処理）
• ストレージの場所: ./.memorious ディレクトリ（設定可能）
• Python のバージョン: Python ≥3.12 が必要です
• ライセンス: MIT
• プライバシー: ネットワークリクエストやクラウドへの依存はなく、すべてのデータはローカルに保存されます

パッケージ構成

このプロジェクトは標準的な Python パッケージのレイアウトに従っています。

memorious-mcp/
├── src/
│   └── memorious_mcp/
│       ├── __init__.py
│       ├── main.py                 # MCP server entry point
│       └── backends/
│           ├── __init__.py
│           ├── memory_backend.py   # Abstract base class
│           └── chroma_backend.py   # ChromaDB implementation
├── tests/
│   └── test_chroma_backend.py      # Integration tests
├── pyproject.toml                  # Package configuration
└── README.md

このサーバーは stdio トランスポートを使用するローカル／CLI 統合向けに設計されており、プライバシーとデータセキュリティが最優先される個人用 AI アシスタントや開発ワークフローに適しています。

制限事項

⚠️ 重要なセキュリティ上の注意事項

データがローカルマシンから外部に送信されないため、100%安全かつプライベートですが、保存する内容には引き続き注意してください。

• データは暗号化されずに保存されます: 保存されたすべてのデータは、.memorious ディレクトリ内のディスクに暗号化されずに永続化されます
• 秘密情報の保存は避けてください: パスワード、API キー、秘密鍵、個人識別番号、金融情報、その他の機密認証情報は保存しないでください
• ローカルファイルへのアクセス: あなたのマシンと .memorious ディレクトリにアクセスできる人は、保存されたすべての記憶を読み取ることができます
• 注意してください: MCP サーバーは、機密情報を保存しないようクライアントの LLM に警告しますが、この保護策だけに頼らないでください
• バックアップに関する注意: .memorious フォルダーを含むディレクトリのバックアップや同期には注意してください

コントリビューション

コントリビューションを歓迎します。テストを含めて PR を作成してください。