Engraphy

Engraphy

人間の心をモデルに、AI エージェントに連想記憶をもたらす MCP サーバーです。

クイックスタート · ドキュメント · ツールリファレンス · デザインセット · コントリビューション

名前の由来は、記憶科学で記憶痕跡、つまり脳に残る記憶の痕跡である エングラムを形成する過程を指す古い用語、engraphyです。Engraphyは エージェントのためにそれを実現します。新しい記憶を書き込む前に、すでに 知っていることと照合し、言い換えを統合し、本当に新しい事実を関連付け、 気づかれないまま上書きされることはありません。何も削除されないため、 履歴をたどることができます。

Engraphyはセルフホスト可能です。エージェントが学んだことを、Postgres + pgvector上の型付きナレッジグラフとして 保存します。書き込み時には既存の記憶と重複を自動的に排除し、検索では 意味検索と語彙検索を組み合わせ、ユーザー間の分離はデータベースによって 保証されます。また、記憶の全体構造はアプリケーションごとに パック として宣言します。

このプロジェクトは、参照用 MCP メモリーサーバーのフラットなJSON、 シングルユーザー、stdioモデルを、並行処理、言い換え、重複、そして 何年にもわたって蓄積する記憶に耐えられるものに置き換えるために作られました。 Model Context Protocolに対応しているため、 VS Code拡張機能、デスクトップアプリ、別のエージェントなど、あらゆるMCP クライアントがHTTP経由で利用できます。

ソース公開型です。 Business Source License 1.1のもとでライセンスされています。 内容の閲覧、実行、拡張、自社製品での本番利用が可能です。Engraphy自体を 第三者向けのホスト型またはマネージドサービスとして提供する権利は、 Change Dateまではライセンサーに留保されます。その日以降はApache-2.0に 切り替わります。ライセンスをご覧ください。

---

主な機能

• 型付きメモリーグラフ。 メモリーは、型付きのノード（fact、decision、 person、event、…）を型付きのエッジ（involves、references、 supersedes、…）で結んだものです。型、その属性スキーマ、どの型同士をエッジで 接続できるかを定めるルールは、スペースごとにパックで宣言され、 Postgres によって適用されます。
• 書き込み時に重複を自動判定。 書き込みはすべて埋め込みベクトル化され、既存の メモリーと比較して分類されます。ほぼ逐語的な言い換えは自動でマージされます。 新規性がありながら関連する事実は、それ自体で検索可能なノードとして保持され、 エッジで結ばれます（何かにひそかに吸収されることはありません）。判定が難しい 場合は、呼び出し元が解決するための重複チェック待ちとして保留されます。すべての 書き込みは、影響した内容を示す共鳴レポートを返します。
• ハイブリッド検索。 search はベクトル検索（埋め込みのコサイン類似度）と 字句検索（Postgres の全文検索）を Reciprocal Rank Fusion で統合し、 traverse はエッジをたどります。属性値は検索対象に含まれるため、型付き属性に のみ保存された事実も検索できます。
• データベースが適用する分離。 複数のスペースと、スペース内の複数のプリンシパルは、 忘れられる可能性のあるアプリケーション側のチェックではなく、スーパーユーザー以外の ロールで実行される Postgres の行レベルセキュリティによって分離されます。サーバーは NOBYPASSRLS ロールで接続します。
• LLM 向けに設計されたスコープルーティング。 各スコープには、その対象を説明する 情報が含まれています。読み取り専用の scope_guide ツールは、そのルーティング情報を 返すため、エージェントは新しいメモリーを書き込む前に、どこに保存するかを判断できます。
• スペースの初期設定から、トークンの発行、データのインポート、パックの適用、 リストアの検証まで、あらゆる操作に対応するオペレーター向け CLI と MCP ツール群。

仕組み

flowchart LR
    C[MCP client<br/>VS Code · desktop · agent] -->|HTTP + bearer token| S[Engraphy server<br/>FastMCP]
    S --> E[Embedding<br/>nomic-embed-text-v1.5]
    S --> DB[(Postgres 16 + pgvector<br/>nodes · edges · scopes<br/>RLS · schema enforcement)]
    P[Pack<br/>types · edges · briefing] -.declares.-> DB

書き込みは埋め込みベクトル化され、類似度に基づいてマージ／マージリンク／保留／ 新規に分類された後、呼び出し元の ID のもとで確定されます。読み取り （search、get、traverse、briefing）は RLS のもとで実行されるため、呼び出し元には 付与されたスコープのみが表示されます。パックでは、スペースのノード型、エッジ型、 属性スキーマ、セッション開始時のブリーフィングを宣言するため、1 つのエンジンで さまざまな構造のメモリーアプリケーションに対応できます。 アーキテクチャ概要では、書き込みと読み取りの全経路を説明しています。

クイックスタート

必要なもの：Docker（Compose を含む）。クラウドプロファイルでは、1 つのコマンドで Postgres の起動、マイグレーションの実行、アプリケーションロールの設定、サーバーの 起動が行われます。

# 1. Configure secrets (never committed)
cp deploy/.env.example .env   # then edit, or:
printf 'POSTGRES_PASSWORD=%s\nENGRAPHY_APP_ROLE_PASSWORD=%s\n' \
  "$(openssl rand -hex 16)" "$(openssl rand -hex 16)" > .env

# 2. Bring up Postgres + migrate + provision + serve
docker compose up -d          # the embedding model ships baked into the image

# 3. Create a space, apply the starter pack, mint a client token
docker compose --profile admin run --rm admin \
  engraphy-admin space create --id personal --display-name "My Memory" --principal me
docker compose --profile admin run --rm admin \
  engraphy-admin pack apply packs/starter/pack.yaml --space personal
docker compose --profile admin run --rm admin \
  engraphy-admin token create --space personal --principal me \
    --client-name my-editor --role readwrite

サーバーは 127.0.0.1:8000 で起動しています（外部公開するには、手前に TLS 終端を行う リバースプロキシを設置してください）。ベアラートークンを使って、任意の MCP クライアントを 接続してください。セットアップガイドでは、Docker を使わないローカルでの セットアップ方法も説明しています。

または、スクリプトに任せる

up.sh と provision.sh（Windows 版の up.ps1／provision.ps1）は、上記とまったく同じ手順を実行し、コピー＆ペーストで済ませるクイックスタートにはない待機処理を追加します。

./up.sh          # writes .env with random passwords, starts the stack,
                 # then blocks until /healthz returns 200
./provision.sh   # creates the space, applies the starter pack, mints a token,
                 # and prints the client settings to paste in

初回起動時、モデルキャッシュの初期化にかかる間、compose は starting を報告し続けます。これは外部から見るとクラッシュループと区別がつかないため、up.sh は compose のヘルスステータスではなく /healthz をポーリングします。実際の稼働を示すのは 200 応答です。

どちらのスクリプトも安全に再実行できます。既存の .env は上書きされず、既存のスペースや適用済みのパックはエラーではなくスキップされるため、再実行しても新しいトークンが発行されます。

すべての値はパラメーター化されており、デフォルト値のままで動作します。

	デフォルト	上書き方法
スペース ID	default	./provision.sh myspace または -Space myspace
プリンシパル	me	./provision.sh myspace alice または -Principal alice
クライアント名	my-client	3 番目の位置引数、または -ClientName
パック	/app/packs/starter/pack.yaml	ENGRAPHY_PACK または -Pack
ホストポート	8000	.env の ENGRAPHY_HOST_PORT、または -Port
ヘルスチェックのタイムアウト	起動時 1800 秒、プロビジョニング時 600 秒	ENGRAPHY_WAIT_SECS または -WaitSeconds

トークンは 1 度だけ表示され、スクリプトによってディスクに書き込まれることはありません。サーバーに保存されるのは SHA-256 のみです。トークンを紛失した場合は、provision.sh を再実行して新しいトークンを発行してください。

クライアントからの利用

Engraphy は MCP サーバーなので、クライアントから接続してツールを呼び出します。

ツール	機能
write	重複チェックを伴う書き込みを行います。ノード、または重複チェックの判定とレゾナンスレポートを返します。
search	1 つのスコープ、またはすべてのスコープを対象に、セマンティック検索と字句検索を組み合わせた検索を行います。
traverse	開始ノードからグラフを再帰的にたどります。
get	ID を指定して、ノード全体とエッジの概要を取得します。
briefing	パックで宣言されたセッション開始時のセクション（期限のあるコミットメント、関連するメモなど）を取得します。
scope_guide	書き込み可能なすべてのスコープと、それぞれの管理対象を示すルーティングマニフェストです。
scope_list / scope_create	読み取り可能なスコープを一覧表示／プライベートなスコープを作成します。
link · update · supersede · resolve_duplicate	グラフを編集し、保留中の判定を確定します。
pending_list · stats · inbox_review	保留中の書き込み、使用状況のメトリクス、キャプチャ用インボックスを確認します。
admin_*	スペースを管理します（メンバー、トークン、権限付与、公開範囲）。

パラメーター、戻り値、各ツールの使用例については、ツールリファレンスを参照してください。ファーストパーティの VS Code 拡張機能は vscode-extension/ にあります。

ドキュメント

• docs/：開発者向けドキュメント。アーキテクチャ、 セットアップ、パック、 ツールリファレンス、デプロイ、 エンドツーエンドのチュートリアルが含まれます。
• design/：設計資料一式、データモデル、検索と 重複排除、認証とテナント管理、運用、パック／オントロジーシステム、 ベンチマークハーネスが含まれます。エンジニアリング上の検討内容はこちらにあります。
• skills/：Engraphy を適切に使うために LLM エージェントが読み込める簡潔なガイダンスです（書き込みと重複排除、検索、スコープと公開範囲、回答の規律）。

要件

• Postgres 16 と pgvector（pgvector/pgvector:pg16 イメージには両方が含まれます）。
• Python ≥ 3.12。
• マイグレーション用の dbmate（管理コンテナに同梱されています。Docker を使わない方法では、PATH 上にある場合にのみ必要です）。
• 埋め込みモデル nomic-ai/nomic-embed-text-v1.5（384 次元、ONNX Runtime 上で動作し、初回起動時にダウンロードしてキャッシュされます）。

プロジェクトの状況

v0.1.0。スキーマと強制適用カーネル、エンジンの動作（重複排除、ハイブリッド検索、グラフ探索、ブリーフィング）、認証と管理機能を備えた MCP サーバー、およびオペレーター向け CLI を実装済みです。ライブの Postgres を使ったテストスイートと、リリース済みのデプロイ成果物をエンドツーエンドで検証する CI ジョブでカバーしています。ベンチマーク用ハーネス（bench/、design/09）は、公開されている長期記憶データセットに対してエンジンを実行します。変更を測定するためのツールであり、マーケティング用の数値を得るためのものではありません。 bench/RUN-LOCOMO.mdでは、LoCoMo を自分で実行する手順を説明しています。OpenAI 互換のベース URL とキーが必要で、データセット、比較対象、モデル、評価者を固定しています。

コントリビューション

Issue とプルリクエストを歓迎します。CONTRIBUTING.mdでは、開発用データベースの起動方法、テストスイートの実行方法、3 つの CI ジョブで確認する内容、プロジェクトのスタイルガイドを説明しています。セキュリティ上の問題は、公開 Issue ではなく非公開のセキュリティアドバイザリから報告してください。

ライセンス

Engraphy はBusiness Source License 1.1の下でライセンスされています（LICENSEを参照）。

• 許可されていること： Engraphy を読み、変更、再配布、セルフホストし、自身のアプリケーションやエージェント向けのメモリレイヤーとして本番環境で使用できます。
• 禁止されていること： Change Date までは、Engraphy 自体をホスト型またはマネージドサービスとして第三者に提供できません。
• Change Date： 2026-08-22 + 4 年（2030-08-22）。この日にライセンスはApache License, Version 2.0に切り替わります。

Copyright (c) 2026 Devon Clark.