mcp-memento

MCP Memento

確信度の追跡、関係性のマッピング、ナレッジの品質維持を備えた、MCP クライアント向けのインテリジェントなメモリ管理です。

Memento は、複数のプラットフォームで永続的なメモリ機能を提供する MCP サーバーです。

• IDE：Zed、Cursor、Windsurf、VSCode、Claude Desktop
• CLI エージェント：Gemini CLI、Claude CLI、カスタムエージェント
• プログラムからの利用：MCP クライアント（Python）、Docker デプロイ、CLI によるエクスポート／インポート
• アプリケーション：MCP 互換のあらゆるアプリケーション

すべての開発ツールから利用でき、使うほど賢くなる個人またはチーム向けのナレッジベースを構築できます。

目次

• 🌱 やさしい入門
• ✨ 主な機能
• 🚀 クイックスタート
• ⚙️ 設定
• 📖 基本概念
• 🔗 インテグレーション
• 🛠️ 基本的な使用例
• 📚 ドキュメントの構成
• 🏗️ アーキテクチャの概要
• 📜 背景
• 🙏 謝辞
• 🤝 コントリビューション
• 📄 ライセンス
• 🔗 リンク

🌱 やさしい入門

Memento とは？ 複雑なバグの解決、難しい設定の理解、新しいコーディングパターンの確立に取り組んでいると想像してください。通常、数週間もすれば細かなことは忘れてしまいます。Memento は、AI アシスタントのための「長期記憶ドライブ」です。解決策、決定事項、事実を AI が保存できるようにし、数か月後でもプロジェクトをまたいで瞬時に思い出せるようにします。

💡 エージェント的な考え方：従来の開発者向けガイド スクリプトに書かれたとおりに自動で処理が行われる、決定論的なソフトウェアに慣れている場合、AI エージェントとのやり取りでは、考え方を少し変える必要があります。

Memento は、画面を見守って何を記憶するかを魔法のように判断する自律型エージェントではありません。Memento は、Claude、Cursor、Gemini などの AI アシスタントに提供されるツールセットです。

• 作業するのは AI です： ツールセットをいつ使うか、AI に指示する必要があります。明示的な指示や事前に定めたルールがない限り、何も保存されません。
• 管理するのはあなたです： 保存する内容はあなたが管理します。チャット中に「このデータベース接続文字列を保存して」と AI に伝えることも、標準業務手順（システムプロンプトや .cursorrules／CLAUDE.md ファイル）を AI に与えて、バグ修正やアーキテクチャ上の決定事項などを自動で保存するよう設定することもできます。

習慣を身につける方法：

1. セッションの開始時： AI に「認証システムについて、何がわかっていますか？」と尋ね、コンテキストを呼び出します。
2. 作業中： 難しい問題を解決したら、「Redis のタイムアウトを修正しました。この解決策を保存してください」と伝えます。
3. セッションの終了時： AI に「今日達成したことの要約を保存してください」と伝えます。

または、AI にカスタム指示を追加して（エージェント設定ガイドを参照）、毎回頼まなくてもこれらの手順を自動で実行するように設定できます。

✨ 主な機能

🧠 インテリジェントな信頼度システム

• 自動減衰：使用されていない知識の信頼度は時間とともに低下します（月5％）。
• 重要情報の保護：セキュリティ／認証／API キーに関する記憶は減衰しません。
• 検証時の向上：知識の利用に成功すると、信頼度が上がります。
• スマートな並べ替え：検索結果は confidence × importance に基づいて順位付けされます。

🔗 関係性のマッピング

• 35 種類の関係性：Relationship Types Reference を参照。7 つの意味カテゴリにわたる SOLVES、CAUSES、IMPROVES、USED_IN などがあります。
• グラフナビゲーション：概念間のつながりを見つけます。
• パターン検出：繰り返し現れる解決パターンを特定します。

📊 3 つのプロファイル

プロファイル	ツール	最適な用途
Core	13 個のツール	すべてのユーザー — 基本的な操作
Extended	17 個のツール	パワーユーザー — 統計、コンテキスト検索、減衰制御
Advanced	25 個のツール	管理者 — グラフ分析

🗃️ クロスプラットフォームストレージ

• SQLite バックエンド：依存関係なしのローカルストレージです。
• 全文検索：すべての記憶を対象に、高速であいまい検索を行えます。
• 自動メンテナンス：信頼度の減衰と関係性の整合性を管理します。
• 共有データベース：すべての連携機能で同じデータベースを使用できます。

🚀 クイックスタート

1. インストール

# Install with pipx (recommended for MCP servers)
pipx install mcp-memento

# Or with pip
pip install mcp-memento

2. 基本設定

Memento は複数の設定方法に対応しています。わかりやすさのため、一貫して 1 つの方法を使用することをおすすめします。

方法 1：CLI 引数（推奨 — 最も明示的）

{
  "mcpServers": {
    "memento": {
      "command": "memento",
      "args": ["--profile", "extended", "--db", "~/.mcp-memento/context.db"]
    }
  }
}

方法 2：環境変数

{
  "mcpServers": {
    "memento": {
      "command": "memento",
      "args": [],
      "env": {
        "MEMENTO_PROFILE": "extended",
        "MEMENTO_DB_PATH": "~/.mcp-memento/context.db"
      }
    }
  }
}

方法 3：YAML 設定ファイル ~/.mcp-memento/config.yaml を作成します：

profile: extended
db_path: ~/.mcp-memento/context.db

次に、最小限の JSON 設定を使用します：

{
  "mcpServers": {
    "memento": {
      "command": "memento",
      "args": []
    }
  }
}

CLI エージェント（Gemini CLI）：

gemini --mcp-servers memento

注：正確なフラグ構文は、お使いの Gemini CLI のバージョンによって異なります。バージョンに応じた設定手順については、AGENT_CONFIGURATION.md を参照してください。

3. はじめに

設定が完了すると、AI アシスタントで次の操作ができるようになります。

# Store solutions and knowledge
store_memento(
    type="solution",
    title="Fixed Redis timeout with connection pooling",
    content="Increased connection timeout to 30s and added connection pooling...",
    tags=["redis", "timeout", "production_fix"],
    importance=0.8
)

# Find knowledge later
recall_mementos(query="Redis timeout solutions")

📌 注：上記のコードはMCP ツール呼び出しを表しています。Memento のツールを呼び出すために、AI アシスタント（Claude、Cursor、Gemini など）に与える指示です。 import して使用する Python ライブラリではありません。Python からプログラムでアクセスする方法については、Python Integration Guide を参照してください。

💬 自然言語：自然な会話を通じて Memento を利用することもできます。「これを覚えておいて……」「これを保存して……」「Memento……」などと AI アシスタントに伝えるだけで、コードは必要ありません。

📖 基本概念

Memento の概念（信頼度システム、タグ付け、関係性）について詳しく知るには、RULES.md と RELATIONSHIPS.md の包括的なドキュメントをお読みください。

🔗 連携機能

Memento は主要な開発ツールすべてに対応しています。

プラットフォーム	設定ガイド	備考
Zed Editor	IDE Integration	MCP をネイティブサポート
Cursor	IDE Integration	AI 搭載エディター
Windsurf	IDE Integration	最新のコードエディター
VSCode	IDE Integration	MCP 拡張機能経由
Claude Desktop	IDE Integration	デスクトップアプリ
Gemini CLI	Agent Integration	Google の CLI エージェント
Claude CLI	Agent Integration	Anthropic の CLI エージェント
Python / MCP Client	Python Integration	サーバーを組み込むか、MCP クライアント経由で呼び出します
Docker / CLI	API & Programmatic	MCP クライアント、Docker、エクスポート／インポート

こちらもご覧ください：Integration Overview では、適切な連携方法を選ぶためのガイダンスを紹介しています。

🛠️ 基本的な使用例

以下の例は、何かを記憶したり取得したりするよう依頼されたときに、AI アシスタント（Zed、Cursor、 Claude、Gemini CLI、…）がユーザーに代わって実行する MCP ツールの呼び出しを示しています。MCP ツールのインターフェースを反映したPython風の疑似コードで記述されており、直接インポートして使用するPythonライブラリではありません。

Pythonからプログラムでこれらのツールを呼び出すには、mcp クライアントライブラリを使用してください。 実際に動作する例については、Python連携を参照してください。

ナレッジの保存と取得

# Store a solution — the AI calls this tool when you say "remember this fix"
solution_id = store_memento(
    type="solution",
    title="Fixed memory leak in WebSocket handler",
    content="Added proper cleanup in on_close()...",
    tags=["websocket", "memory", "python"],
    importance=0.9
)

# Natural language search — called when you ask "what do you know about X"
results = recall_mementos(query="WebSocket memory leak", limit=5)

# Tag-based search — for precise filtering
redis_solutions = search_mementos(tags=["redis"], memory_types=["solution"])

信頼度の管理

# Find potentially obsolete knowledge
low_confidence = get_low_confidence_mementos(threshold=0.3)

# Boost confidence after verification
boost_memento_confidence(
    memory_id=verified_solution_id,
    boost_amount=0.15,
    reason="Verified in production deployment"
)

関係の作成

# Link solution to problem
create_memento_relationship(
    from_memory_id=solution_id,
    to_memory_id=problem_id,
    relationship_type="SOLVES",  # See all 35 types in docs/RELATIONSHIPS.md
    strength=0.9,
    context="Connection pooling resolved the timeout issue"
)

# Explore connected knowledge
related = get_related_mementos(
    memory_id=solution_id,
    relationship_types=["RELATED_TO", "USED_IN"],
    max_depth=2
)

自然言語でのやり取り（チャットベース）

Mementoは自然言語での会話を通じて機能します。AI アシスタントが意図を解釈し、適切なツールを自動的に呼び出します。

情報の保存：

User: Remember that we solved Redis timeout with connection pooling
AI: ✅ Memento stored - "Redis timeout solution: connection pooling"

ナレッジの取得：

User: What do you remember about Redis timeout?
AI: Found 2 solutions: 1) Connection pooling... 2) Query optimization...

「Memento」というキーワードの使用：

User: Memento the deployment script is in /scripts/deploy.sh
AI: ✅ Memento stored - "Deployment script location: /scripts/deploy.sh"

AGENT_CONFIGURATION.mdのガイドラインを設定すると、AIは重要な情報を自動的に保存することもできます。

⚙️ 設定

Mementoは複数の設定ソースに対応しています（優先順位の高い順）。

1. コマンドライン引数（最優先）

   memento --profile advanced --db ~/custom/path/memento.db --log-level DEBUG
   

2. 環境変数

   export MEMENTO_PROFILE="advanced"
   export MEMENTO_DB_PATH="~/custom/path/memento.db"
   export MEMENTO_LOG_LEVEL="DEBUG"
   export MEMENTO_ALLOW_CYCLES="false"   # Allow cycles in relationship graph
   

3. YAML設定ファイル

   • プロジェクト設定：カレントディレクトリの ./memento.yaml（グローバル設定を上書き）
   • グローバル設定：~/.mcp-memento/config.yaml

優先順位：CLI引数 > 環境変数 > プロジェクトのYAML > グローバルのYAML > デフォルト値

4. デフォルト値（最優先度が低い）

対応しているYAMLキー

以下のキーは設定ローダーによって読み込まれ、適用されます。YAMLファイルに含まれるその他のキーは、通知なく無視されます。

キー	型	デフォルト	説明
db_path	文字列	~/.mcp-memento/context.db	SQLiteデータベースファイルのパス
profile	文字列	core	ツールプロファイル（core、extended、advanced）
logging.level	文字列	INFO	ログレベル（DEBUG、INFO、WARNING、ERROR）
features.allow_relationship_cycles	bool	false	グラフ内の循環する関係を許可するかどうか

注：プロジェクトに同梱されている memento.yaml テンプレートには、追加のコメントアウトされたセクション（confidence、search、performance、memory、fts、project）が含まれています。 これらはまだ実装されていません。将来のリリースに向けたプレースホルダーであり、現在のサーバーの動作には影響しません。

設定ファイルの例

プロジェクト設定（./memento.yaml）：

db_path: ~/.mcp-memento/context.db
profile: extended
logging:
  level: INFO
features:
  allow_relationship_cycles: false

グローバル設定（~/.mcp-memento/config.yaml）：

db_path: ~/.mcp-memento/global.db
profile: extended
logging:
  level: INFO

📚 ドキュメントの構成

基本ガイド

• ツールリファレンス - すべてのMCPツールの完全ガイド
• 信頼度システム - 信頼度の追跡方法
• 関係の種類 - 35種類すべての関係とその例
• 使用ルール - ベストプラクティスと規約
• エージェント設定 - AI エージェント向けテンプレート

連携ガイド

• 連携の概要 - 適切な連携方法の選び方
• IDE連携 - Zed、Cursor、Windsurf、VSCode、Claude Desktop
• Python連携 - MCP クライアントの使用、サーバーの組み込み、CLIでのエクスポート／インポート
• エージェント連携 - CLIエージェントとカスタムアプリケーション
• APIとプログラムによる連携 - MCP クライアント（Python）、Dockerによるデプロイ、CLIでのエクスポート／インポート

開発と高度なトピック

• データベーススキーマ - データベース構造の技術解説
• コントリビューションガイドライン - 開発環境のセットアップとワークフロー

🏗️ アーキテクチャの概要

データベーススキーマ

Memento は、すべてのインテグレーションからアクセスできる統合された SQLite スキーマを使用します。

• コアテーブル：nodes（メモリの保存）、relationships（有向グラフ）
• 全文検索：nodes_fts — 高速検索のための FTS5 仮想テーブル（FTS5 を利用できない場合は、LIKE ベースの検索にフォールバックします）
• 信頼度の追跡：重要なメモリを保護しながら、自動的に信頼度を減衰させます

一貫した動作

システムはすべてのプラットフォームで同じように動作します。

1. 同じデータベース：すべてのツールが同じ SQLite ファイルにアクセスします
2. 同じ信頼度の追跡：あるツールでの更新が、すべての場所に反映されます
3. 同じ検索順位：結果は confidence × importance の順に並びます
4. 同じ関係タイプ：35 種類の意味的な関係タイプをどこからでも利用できます

📜 背景

Memento は、Gregory Dickson による MemoryGraph の簡素化された軽量フォークであり、IDE や CLI エージェントとの MCP インテグレーションに最適化されています。

このフォークは、移植性とトークン効率を重視しています。NetworkX、マルチバックエンドストレージ、双時間追跡、マルチテナントアーキテクチャといった重量級の依存関係を取り除き、信頼度ベースの減衰とガイドラインに基づく保存を備えた SQLite 専用バックエンドを採用しています。

チームでの共同作業とリモートデプロイ

複数のユーザーがタグ付け規則（team:[name]、author:[name]）を使用して、SQLite データベース（ネットワークストレージ上など）を共有できます。Memento はリモート MCP サーバーとして実行することもできますが、テナントの分離はなく、すべてのクライアントが同じデータベースを共有します。詳細はチームでの共同作業に関するガイドラインをご覧ください。

真のマルチテナントが必要な場合は、元の MemoryGraph プロジェクトをご利用ください。

MemoryGraph と Memento のどちらを選ぶべきですか？

• Memento を使用する場合：IDE や CLI ツールで軽量かつクロスプラットフォームなメモリ管理を行う場合
• MemoryGraph を使用する場合：マルチテナント、双時間追跡、またはカスタムバックエンドが必要なエンタープライズ向けのユースケース

🙏 謝辞

Memento は、Gregory Dickson の MemoryGraph プロジェクトの確かな基盤の上に構築されています。メモリ管理システムにおける先駆的な取り組みに感謝します。

このフォークは、MemoryGraph の中核概念との互換性を維持しながら、MCP インテグレーションや最新の開発ツールに特有のニーズに合わせて調整されています。MemoryGraph の高度な機能をフルに活用する必要がある方には、元のプロジェクトをご覧になることをおすすめします。

🧪 ベータ版のステータス

mcp-webgate はベータ版です。中核機能は安定しており、サーバーは本番環境で使用されていますが、設定 API は 1.0 より前に変更される可能性があります。

フィードバックを歓迎します。 期待どおりに動作しない場合や、挙動がおかしい場合、あるいは対応されていないユースケースがある場合は：

→ GitHub で issue を作成

バグ報告、設定に関する質問、機能リクエストは、いずれも今後の開発方針に役立ちます。

🤝 貢献

貢献を歓迎します！以下の詳細なガイドラインについては、CONTRIBUTING.mdをご覧ください。

• 開発環境のセットアップとワークフロー
• コードスタイルと規約
• テスト要件
• ドキュメントの標準
• プルリクエストの手順

📄 ライセンス

MIT License — 詳細はLICENSEをご覧ください。

🔗 リンク

• GitHub リポジトリ - ソースコードと issue
• MCP Protocol - Model Context Protocol の仕様
• PyPI パッケージ - Python Package Index
• MCP Registry - Model Context Protocol Registry

---

お困りですか？ ドキュメントをご確認いただくか、GitHub でissue を作成してください。