NeuroDock Cognitive Graph

neurodock-mcp-cognitive-graph

NeuroDock 基盤向けの永続的なエンティティメモリを、MCP サーバーとして公開します。人物、プロジェクト、決定事項、概念に関するユーザーの作業記憶を外部化することで、過度に集中しているセッションやコンテキストが切り替わったセッションでも、ゼロから始めずに済みます。

これはv0.0.3（現行リリース）です。ベクトル検索、fastembed 埋め込み、sqlite-vec は将来のバージョンに延期されています。詳しくは CHANGELOG.md をご覧ください。

インストール

uv add neurodock-mcp-cognitive-graph
# or
pip install neurodock-mcp-cognitive-graph

MCP サーバーとして使用する

~/.claude.json（Claude Code）または claude_desktop_config.json（Claude Desktop）に追加します。

{
  "mcpServers": {
    "neurodock-cognitive-graph": {
      "command": "uv",
      "args": ["run", "neurodock-mcp-cognitive-graph"]
    }
  }
}

クイックスタート

# From the workspace root.
uv sync --all-packages

# Start the server on stdio (Claude Desktop / Claude Code MCP config).
uv run neurodock-mcp-cognitive-graph

サーバーは、デフォルトでグラフを ~/.neurodock/cognitive-graph.sqlite に保存します。NEURODOCK_GRAPH_DB_PATH 環境変数で変更できます。

ツール（v0.0.3）

ツール	目的
recall_entity(name_or_alias)	人物／プロジェクト／決定事項／概念を検索します。エンティティ、その事実（最大500件）、1次近傍（最大20件）、および解決診断を返します。
record_fact(subject, predicate, object, source?, confidence?)	型付きエッジの事実を永続化します。(type, name) に基づいてエンティティを自動作成します。v0.1.0 の8つの述語語彙を適用します。
recall_decisions(project, since?)	プロジェクトの決定事項を日付の降順で返します。最大200件です。
weekly_rollup(project?)	直近7日間（UTC）のアクティビティ概要を、サーバー側のテンプレートで生成します。LLM 呼び出しはありません（ベンダー境界）。

入出力仕様の完全な定義は schemas/ にあります。src/neurodock_mcp_cognitive_graph/types.py の Pydantic v2 モデルは、これらのスキーマに対応しています。

述語語彙

v0.1.0 の8つの述語は、mentioned_in、 decided_in、reports_to、depends_on、resolved_by、blocked_by、tagged、 belongs_to です。未知の述語は PREDICATE_NOT_IN_VOCABULARY を発生させます。 拡張述語は v0.2 の type_extensions の仕組みを通じて追加されます。詳しくは ADR 0002 — cognitive-graph tool design をご覧ください。

プライバシー

• ローカルファーストです。ネットワークアクセスはありません。テレメトリーもありません。
• source 文字列はそのまま保存され、サーバーが取得することはありません。
• ユーザーコンテンツ（エンティティ名、決定事項のタイトル、事実のテキスト）はログに記録されません。 エラーログには構造化されたエラーコードのみが含まれます。

ストレージ

SQLiteです。ファイルは1つです。マイグレーションは src/neurodock_mcp_cognitive_graph/migrations/ に番号付きの .sql ファイルとして保存され、初回接続時に適用されます。スキーマの定義は migrations/0001_init.sql にあります。

アーキテクチャ

src/neurodock_mcp_cognitive_graph/
├── server.py            FastMCP wiring + CLI entrypoint
├── types.py             Pydantic v2 models (mirror of the JSON Schemas)
├── config.py            Resolves the SQLite path
├── clock.py             SystemClock / FixedClock
├── errors.py            ToolError envelope
├── resolution.py        Entity name/alias cascade (exact, alias only in v0.0.3)
├── rollup.py            Heuristic decision/blocker/next-action assembly
├── storage/
│   ├── base.py          Storage Protocol + row dataclasses
│   ├── memory.py        InMemoryStorage (used by tests)
│   └── sqlite.py        SQLiteStorage (production backing)
├── tools/
│   ├── recall_entity.py
│   ├── record_fact.py
│   ├── recall_decisions.py
│   └── weekly_rollup.py
└── migrations/
    └── 0001_init.sql

ADR の参照先

• ADR 0002 — cognitive-graph tool design — 設計の根拠、語彙、出力形式、および v0.0.3 での解決内容が CHANGELOG.md に記載されている未解決の3つの質問。
• ADR 0001 — chronometric tool design — このパッケージが受け継ぐ、複数箇所にまたがる先例（オフセット付き ISO 8601、粗いシグナルの列挙型、構造化エラー）。

テスト

uv run pytest packages/mcp-cognitive-graph/tests/ -v

ツールごとのユニットテスト、すべてのツールを実行し、jsonschema を使用してレスポンスを JSON Schema と照合する FastMCP プロトコル適合性テストスイート、および実際のファイルベースの SQLite ストアを使用するエンドツーエンドテストを含む、25 件のテストです。