engrava

Engrava MCP

Engrava 用のModel Context Protocol サーバーです。
エージェントのメモリデータベースを、stdio 経由であらゆる MCP クライアント（Claude Desktop、Claude Code、Cursor、Windsurf、VS Code など）に公開します。

engrava-mcp は、Engrava の公開 API を利用する、単独で実行可能なパッケージです。Engrava をメモリサーバーとして実行する方法はこれだけです。engrava ライブラリ自体には MCP コードは含まれていません。

uv tool install engrava-mcp   # recommended for daily use: a persistent install
engrava-mcp                   # spawned by your MCP client over stdio

uvx engrava-mcp を使えばインストールせずに実行でき、pip install engrava-mcp でも利用できます。uvx は環境をキャッシュに保持します。キャッシュが空の場合、初回の起動ではダウンロードが完了するまで待つ必要があります。ダウンロード量が最も大きい [local] エクストラについては、オプションのプロバイダーを参照してください。

engrava-mcp をインストールすると、依存関係として engrava もインストールされるため、同じ環境で import engrava ライブラリも利用できます。

互換性

engrava-mcp のバージョンは Engrava のバージョンに対応しています。**engrava-mcp X.Y.z は engrava X.Y を対象とし、engrava >=X.Y,<X.(Y+1) が必要です。**これは分かりやすさのための一方向のバージョン対応であり、**連動してリリースされるわけではありません。**Engrava は独自のリリースサイクルで提供され、engrava-mcp のパッチリリースは個別に行われます。

engrava-mcp	対応する engrava
0.5.x	>=0.5,<0.6
0.6.x	>=0.6,<0.7
0.7.x	>=0.7,<0.8

正しい依存関係の範囲は、依存関係の指定に記載されています。通常のインストールでは、互換性のある engrava が自動的に選択されます。engrava のバージョンを自分で固定する場合は、この範囲内にしてください。表の最終行より新しい engrava に対応する engrava-mcp がまだない場合、その組み合わせは未検証／未サポートです。壊れているわけではありません。対応する engrava-mcp がリリースされるまでは、サポートされている組み合わせを使用してください。

どのパッケージを選べばよいですか？

目的	インストール
Engrava の Python API を使って開発する（自分のコードでメモリ DB を利用する）	pip install engrava
MCP クライアント向けのメモリサーバーとして Engrava を実行する	uvx engrava-mcp（または pip install engrava-mcp）

これ以外の選択肢はありません。

engrava[mcp] からの移行

以前はサーバーは Engrava に engrava[mcp] エクストラとして同梱され、engrava 内の engrava-mcp コマンドとして提供されていました。Engrava 0.5.0 からは、こちらのパッケージで提供されます。

以前	以後
pip install "engrava[mcp]"	pip install engrava-mcp（または uvx engrava-mcp）
engrava-mcp（engrava によってインストール）	engrava-mcp（このパッケージによってインストール）
クライアントの mcp.json："command": "engrava-mcp"	クライアントの mcp.json："command": "uvx", "args": ["engrava-mcp"]

• **注意：**Engrava 0.5 に対して pip install "engrava[mcp]" を実行しても、エラーにはなりません。pip は現在は認識されないエクストラを無視して、基本の engrava をそのままインストールするため、サーバーがインストールされたように見えて、実際にはインストールされていないことがあります。代わりに engrava-mcp をインストールしてください。
• 固定している要件文字列（engrava[mcp]>=...）を更新し、再インストールするだけでなく、依存先を engrava-mcp に変更してください。
• **ストアの設定は変更されません。**同じ engrava.yaml／環境変数をそのまま使用できます（設定を参照）。

設定

サーバーは、以下の優先順位で環境変数からストアを解決します。

変数	意味
ENGRAVA_MCP_CONFIG	engrava.yaml へのパスです。埋め込みプロバイダー、ベクトルバックエンド、ジャーナル、TTL を含む完全な設定で構築します。思考／エッジジャーナルはここで設定します。有効にするには、journal: enabled: true を設定します。推奨。
ENGRAVA_DB_PATH	SQLite データベースファイルへのパスです。絶対パスを使用してください。相対パスの場合、クライアントが選択するサーバーの作業ディレクトリを基準に解決されます。設定不要ですぐに使えますが、埋め込みプロバイダーは設定されないため、セマンティック検索（ベクトル検索）は機能しません。全文検索、グラフ、MindQL は引き続き機能します。この方法ではジャーナルなしでストアを構築します。ジャーナルを使うには ENGRAVA_MCP_CONFIG を使用してください。「設定不要」とは Engrava のデフォルト検索ポリシーを意味するため、この方法でも search_memory の recency_now は適用されます。新しさは、指定したタイムスタンプを基準に、Engrava のデフォルト検索ウェイトでスコア付けされます。
ENGRAVA_MCP_READ_ONLY	1／true／yes に設定すると、書き込みツールは登録されず、読み取りによって書き込みが発生することもありません。これには、アクセス追跡が有効なストアであれば通常はバッファーに記録され、終了時にフラッシュされる、遅延アクセス数更新も含まれます。そのため、このモードでは、どの設定方法でもすべてのツールの readOnlyHint アノテーションが正確になります。読み取り専用モードが制御するのはツールであり、データベースの開き方ではありません。起動時にサーバーは引き続きファイルを読み書き可能な状態で開き、ファイルが存在しない場合は作成し、Engrava のバージョンが使用するスキーマにアップグレードします。そのため、サーバーが書き込めないデータベースファイルは、このモードでも提供できません。

推奨： アプリケーションで使用しているものと同じ engrava.yaml を MCP サーバーに渡してください。埋め込みプロバイダー（およびそのモデル／キー）を宣言できるのは yaml だけです。セマンティック検索では、検索時に新しいクエリを埋め込むためにプロバイダーが必要です。ENGRAVA_DB_PATH だけを設定した場合、サーバーはセマンティック検索が機能しないことを示す起動時警告を出し、ENGRAVA_MCP_CONFIG を案内します。

検索時、サーバーはこの yaml で宣言されたプロバイダーを使ってクエリを埋め込みます。このサーバーによる書き込みで何かが埋め込まれるかどうかは、同じ yaml の embeddings.auto_embed で決まります。Engrava ではデフォルトで無効になっています。無効の場合、store_thought で作成した思考には埋め込みが付与されないため、search_memory のベクトルランキングでは一致しません。ただし、キーワードランキングでは一致する可能性があります。また、update_thought を実行しても、思考にすでに存在する埋め込みは更新されず、そのまま残ります。有効の場合、思考の作成時、または essence や content の変更時にもプロバイダーが呼び出されます。

ストアフック拡張機能には設定パスが必要です

ストアにフックする Engrava 拡張機能、つまり engrava.yaml の hooks: セクションを通じて設定する機能は、ENGRAVA_MCP_CONFIG を使って起動した場合にのみ接続されます。ENGRAVA_DB_PATH は設定を伴わないデータベースを開くため、Engrava のデフォルトフックで動作し、ストアフック拡張機能を接続できません。これは意図的な設計であり、最小限の読み書きファサードとして構成されています。

そのため、拡張機能をインストールして ENGRAVA_DB_PATH で起動しても、このサーバーではそのストアフックは接続されません。インストール済みパッケージが何らかの拡張機能を提供している場合、サーバーはその名前を示す起動時警告を出します。これは、各拡張機能が何をするかではなく、提供情報を報告するものです。サーバー自身は拡張機能を読み込まないため、「提供情報なし」と「提供情報はあるが、ここでは接続されていない」とを区別できます。インストール済みパッケージのメタデータを読み取る際に通常のエラーが発生した場合、サーバーは代わりにそのエラーの記録を試み、起動を続行します。どちらも Python の logging を通じて出力されるため、表示されるかどうか、またどこに表示されるかは、ロギング設定によって決まります。ストアフックを接続するには、hooks: セクションを含む engrava.yaml を指定して ENGRAVA_MCP_CONFIG で起動します。

hooks:
  class: "my_package.hooks.MyHooks"

engrava.yamlの例

database:
  path: /absolute/path/to/memory.db
embeddings:
  provider: openai-compatible # or: ollama, sentence-transformer, huggingface
  model: text-embedding-3-small
  api_key: ${OPENAI_API_KEY}

相対パスのdatabase.pathは、yamlファイルのフォルダーではなく、MCPクライアントが選択するサーバープロセスの作業ディレクトリを基準に解決されます。

クライアントの設定

MCPクライアントがstdio経由でサーバーに接続するように設定します。一般的なmcp.jsonエントリーの例を示します。

{
  "mcpServers": {
    "engrava": {
      "command": "engrava-mcp",
      "env": {
        "ENGRAVA_MCP_CONFIG": "/absolute/path/to/engrava.yaml"
      }
    }
  }
}

${OPENAI_API_KEY}などの${VAR}値は、サーバー自体の環境変数から読み込まれるため、クライアントが独自の環境変数を引き継ぐことが確認されていない限り、その変数を同じenvブロックに追加してください。

これはuv tool install engrava-mcpを実行済みであることを前提としています。クライアントがコマンドを見つけられない場合は、絶対パスを指定してください。uv tool dir --binでディレクトリを確認できます。インストールしていない場合は、"command": "uvx", "args": ["engrava-mcp"]を使用してください。

ゼロ設定のクイックスタートではENGRAVA_MCP_CONFIGの代わりにENGRAVA_DB_PATHを使用し、アプリが書き込み、エージェントが読み取るデプロイでは"ENGRAVA_MCP_READ_ONLY": "1"を追加してください。

uvxを使わずに実行する

engrava-mcp                  # console script
python -m engrava_mcp        # module run
python -m engrava_mcp.server # module run (server module directly)

オプションのプロバイダー

MCPのデプロイでは、サーバープロセスの外部で動作する埋め込みプロバイダーを推奨します。Ollama（provider: ollama）またはOpenAI互換エンドポイント（provider: openai-compatible）を使用してください。デフォルトのインストールにはすでに両方が含まれており、サーバー自身が埋め込みモデルを読み込むことはありません。

デフォルトのインストールでは、yamlで設定すると、ベクトルバックエンドとHTTPベースの埋め込みプロバイダー（OpenAI／Ollama）がサポートされます。より大規模なプロバイダーは、Engrava独自の追加機能に準じたオプションの追加機能として提供されます。

uvx --from "engrava-mcp[local]"  engrava-mcp   # sentence-transformers (local model)
uvx --from "engrava-mcp[hf]"     engrava-mcp   # HuggingFace Inference API
uvx --from "engrava-mcp[openai]" engrava-mcp   # OpenAI-compatible embeddings deps
uvx --from "engrava-mcp[ollama]" engrava-mcp   # Ollama embeddings deps

[local]ではサーバープロセス内でモデルを実行し、数ギガバイトの容量を追加する可能性があるPyTorchをインストールします。キャッシュが空の状態でuvxを初めて起動すると、ダウンロードの完了を待つ必要があります。2回目以降の起動ではキャッシュが再利用されます。uv tool install "engrava-mcp[local]"を実行すると、インストール時に一度だけダウンロードします。ローカルのモデルキャッシュにまだないモデルは、初めて読み込むときにダウンロードされます。

提供機能

• ツール（13個）： get_thought、search_memory、search_keywords、list_memory、query_memory、memory_stats、get_edges、list_edges（読み取り）；store_thought、update_thought、link_thoughts、delete_thought、delete_edge（書き込み。ENGRAVA_MCP_READ_ONLYによって制御されます）。
• リソース（3個）： engrava://thought/{thought_id}、engrava://stats、engrava://recent。
• プロンプト（3個）： summarize_recent_memory、find_related、reflect_on_topic。

query_memoryが受け付けるのはMindQLのFINDクエリのみです。生のSQLやその他のコマンドはすべて拒否されます。返される行数は最大5000行です。limit引数を指定すると、クエリ内のLIMITが置き換えられます。指定しない場合、1～5000の範囲外のLIMITは拒否されます。

get_edgesは、方向（IN／OUT／BOTH）を指定して思考のエッジをたどります。limitを指定すると、その数までのエッジを重みの高い順に返し、指定しない場合はすべてのエッジを返します。list_edgesでは、タイプ、ソース、メタデータで絞り込んでエッジを参照できます。

link_thoughtsでは、エッジのmetadata（list_edgesで絞り込み可能なJSONフィールド）を任意で指定できます。search_memoryでは、経過時間を測る基準時刻（トランザクション時刻）を示すrecency_now（ISO-8601タイムスタンプ）を任意で指定できます。新しさがランキングに加味されるのは、この値を渡した場合のみです。

開発

pip install -e ".[dev]"
ruff check src/ tests/
ruff format --check src/ tests/
mypy --strict src/
pytest --cov --cov-fail-under=90

ライセンス

MIT