graphmind

graphmind

graphmind は、エージェント向けの小さく永続的なメモリです。事実を一つずつ追加し、後から検索できるナレッジグラフです。 エンティティ（人、場所、プロジェクトなど、名前のあるもの）を記録し、それぞれにタイプと、増えていくプレーンテキストの観察事項を持たせ、型付きの関係（「Alice — lives_in → Lisbon」など）でつなぎます。 グラフ全体はディスク上の1つのJSONファイルに保存されるため、再起動後もメモリが残り、読みやすく、差分を確認でき、手作業で編集することもできます。

実行するデータベースも、登録が必要なサービスもありません。グラフファイルそのものが製品です。

インストール

npx @reneturcios/graphmind read

または、コンテナイメージを実行します。

docker run -i ghcr.io/cloudcorprecords/graphmind

コンテナはデフォルトでMCPサーバーを起動します（以下を参照）。CLIとして使うには、CLI引数を渡してください。コンテナを実行する場合は、実行のたびにグラフファイルを保持したいときに、作業ディレクトリにボリュームをマウントしてください。

グラフの保存場所

ストアファイルのパスは環境変数GRAPHMIND_FILEで指定され、デフォルトでは現在の作業ディレクトリにある./graphmind.jsonです。ファイルはサーバー（またはCLIコマンド）の起動時に読み込まれ、変更のたびに書き換えられるため、ディスク上には常に現在のグラフ全体が保存されます。

{
  "entities": [
    { "name": "Alice", "entityType": "person", "observations": ["Lives in Lisbon"] }
  ],
  "relations": [
    { "from": "Alice", "to": "Lisbon", "relationType": "lives_in" }
  ]
}

CLI

CLIは、MCPサーバーが書き込むものと同じストアファイルを読み取って調べるためのインターフェースです。

# Print the whole graph as JSON
graphmind read

# Print the subgraph matching a search term
graphmind search lisbon

# Point at a specific store file
GRAPHMIND_FILE=~/notes/graph.json graphmind read

graphmind --version

終了コード：成功時は0、ストアを読み書きできない場合は1、使い方に誤りがある場合は2です。

MCP サーバー

1つの実行ファイルで両方のインターフェースを提供します。mcpサブコマンドを実行すると、stdio MCPサーバーが起動します。

npx -y @reneturcios/graphmind mcp

MCPクライアントの設定：

{
  "mcpServers": {
    "graphmind": {
      "command": "npx",
      "args": ["-y", "@reneturcios/graphmind", "mcp"],
      "env": { "GRAPHMIND_FILE": "/path/to/graphmind.json" }
    }
  }
}

ツール

ツール	入力	説明
create_entities	entities：{name, entityType, observations}の配列	名前がまだ使われていないエンティティを追加します。既存の名前はスキップされ、保存済みのエンティティは変更されません。実際に作成されたエンティティのみを返します。
create_relations	relations：{from, to, relationType}の配列	完全に一致するトリプルがまだ存在しない関係を追加します。実際に作成された関係のみを返します。
add_observations	observations：{entityName, contents}の配列	既存のエンティティに観察事項の文字列を追加します。エンティティがすでに持つ文字列はスキップします。エンティティごとに追加された内容を返します。
delete_entities	entityNames：文字列の配列	指定されたエンティティと、それらのいずれかに接続するすべての関係を削除します。
delete_observations	deletions：{entityName, observations}の配列	指定されたエンティティから、指定された観察事項の文字列を削除します。
delete_relations	relations：{from, to, relationType}の配列	指定された完全一致のトリプルに該当する関係を削除します。
read_graph	(なし)	すべてのエンティティと関係を含むグラフ全体を返します。
search_nodes	query：文字列	エンティティ名、タイプ、観察事項を対象に、大文字と小文字を区別せず部分文字列検索します。一致したエンティティと、両端のエンティティがともに一致した関係を返します。
open_nodes	names：文字列の配列	指定されたエンティティと、それらの間の関係を返します。不明な名前はスキップされます。

知っておくとよい動作

• 名前が識別子です。 エンティティはその名前で識別されます。同じ名前のエンティティを2つ目として作成しようとしても、何も起こりません。名前を変更するには、削除してから作り直してください。
• 関係の両端には実在するエンティティが必要です。 create_relationsでは、fromとtoのエンティティがどちらもすでに存在している必要があります。どちらかが存在しない場合、呼び出し全体が失敗します。仮のエンティティは作成されないため、タイプミスがあればグラフがひそかに破損するのではなく、すぐに判明します。
• 観察事項は順序を保つ集合です。 エンティティがすでに持っている文字列を追加しても何も起こりません。新しい文字列は指定された順序で追加されます。
• 連鎖削除が発生するのはエンティティを削除したときだけです。 エンティティを削除するとその関係も削除されますが、観察事項や関係を削除しても、ほかのものには影響しません。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSEを参照してください。