GZOO Cortex

開発者向けのローカルファーストなナレッジグラフ。 プロジェクトファイルを監視し、LLMを使用してエンティティと関係を抽出します。すべてのプロジェクトを横断して、自然言語でクエリを実行できます。

「プロジェクト全体でどのようなアーキテクチャの決定を行ってきたか？」

Cortexは、README、TypeScriptファイル、設定ファイル、会話のエクスポートから決定事項を見つけ出し、ソースの引用付きで回答を合成します。

なぜ必要なのか

複数のプロジェクトを掛け持ちしていると、決定事項、パターン、コンテキストが何百ものファイルに散らばってしまいます。3ヶ月前に何を決定したか忘れてしまったり、別のリポジトリですでに解決した問題を再解決してしまったりすることがあります。

Cortexはプロジェクトディレクトリを監視し、知識を自動的に抽出して、必要な時にいつでも提供します。

Related MCP server: Graft

機能

• 監視: プロジェクトファイル（md, ts, js, json, yaml）の変更を監視

• 抽出: エンティティ（決定事項、パターン、コンポーネント、依存関係、制約、アクションアイテム）を抽出

• 推論: プロジェクトを横断したエンティティ間の関係を推論

• 検出: 決定事項が矛盾している場合に競合を検出

• クエリ: ソースの引用付きで自然言語によるクエリが可能

• ルーティング: クラウドLLMとローカルLLMをインテリジェントに切り替え

• プライバシー: 制限付きプロジェクトはマシン外に送信されません

• Webダッシュボード: ナレッジグラフの可視化、ライブフィード、クエリエクスプローラー

• MCPサーバー: Claude Codeとの直接統合

クイックスタート

1. インストール

npm install -g @gzoo/cortex

またはソースからインストール:

git clone https://github.com/gzoonet/cortex.git
cd cortex
npm install && npm run build && npm link

2. セットアップ

対話型ウィザードを実行します:

cortex init

以下の設定を行います:

• LLMプロバイダー — Anthropic, Google Gemini, DeepSeek, Groq, OpenRouter, または Ollama (ローカル)

• APIキー — ~/.cortex/.env に安全に保存

• ルーティングモード — クラウド優先、ハイブリッド、ローカル優先、またはローカルのみ

• 監視ディレクトリ — Cortexが監視するディレクトリ

• 予算制限 — 月間のLLM利用上限

設定は ~/.cortex/cortex.config.json に保存されます。APIキーは ~/.cortex/.env に保存されます。

3. プロジェクトの登録

cortex projects add my-app ~/projects/app
cortex projects add api ~/projects/api
cortex projects list                       # verify

4. 監視とクエリ

cortex watch                               # start watching for changes
cortex query "what caching strategies am I using?"
cortex query "what decisions have I made about authentication?"
cortex find "PostgreSQL" --expand 2
cortex contradictions

5. Webダッシュボード

cortex serve                               # open http://localhost:3710

ファイルとディレクトリの除外

Cortexはデフォルトで node_modules、dist、.git などの一般的なディレクトリを無視します。追加する場合は以下を実行します:

cortex config exclude add docs             # exclude a directory
cortex config exclude add "*.log"          # exclude by pattern
cortex config exclude list                 # see all excludes
cortex config exclude remove docs          # remove an exclude

仕組み

Cortexはファイルが変更されるたびにパイプラインを実行します:

1. 解析 — ファイルの内容を言語対応パーサー（コードにはtree-sitter、Markdownにはremark）でチャンク化

2. 抽出 — LLMがエンティティ（決定事項、コンポーネント、パターンなど）を特定

3. 関連付け — LLMが新規および既存のエンティティ間の関係を推論

4. 検出 — 矛盾や重複を自動的にフラグ付け

5. 保存 — エンティティ、関係、ベクトルをSQLite + LanceDBに保存

6. クエリ — 自然言語クエリがグラフを検索し、回答を合成

すべてのデータは ~/.cortex/ 内にローカルで保持されます。LLM API呼び出しのみがマシン外へ送信されます（制限付きプロジェクトでは送信されません）。

LLMプロバイダー

Cortexはプロバイダー非依存です。以下をサポートしています:

• Anthropic Claude (Sonnet, Haiku) — ネイティブAnthropic API経由

• Google Gemini — OpenAI互換API経由

• DeepSeek (Reasoner, Chat) — 高い推論能力、非常に安価

• Groq — 無料枠がある高速推論

• OpenAI互換API — OpenRouter、ローカルプロキシなど

• Ollama (Mistral, Llamaなど) — 完全ローカル、クラウド不要

ルーティングモード

ハイブリッドモードでは、大量のタスク（エンティティ抽出、ランキング）をOllamaに、推論が必要なタスク（関係推論、クエリ）をクラウドプロバイダーにルーティングします。

要件

• Node.js 20以上

• LLM APIキー（クラウドモードの場合） — Anthropic, Google Gemini, DeepSeek, Groq, またはOpenAI互換プロバイダー

• Ollama（ハイブリッド/ローカルモードの場合） — インストール

設定

すべての設定は ~/.cortex/cortex.config.json にあります。APIキーは ~/.cortex/.env にあります。

cortex config list                       # see all non-default settings
cortex config set llm.mode hybrid        # switch routing mode
cortex config set llm.budget.monthlyLimitUsd 10  # set budget
cortex config exclude add vendor         # exclude a directory from watching
cortex privacy set ~/clients restricted  # mark directory as restricted

設定の詳細は以下を参照してください: docs/configuration.md

コマンド

CLIの詳細は以下を参照してください: docs/cli-reference.md

Webダッシュボード

cortex serve を実行すると、http://localhost:3710 でフル機能のWebダッシュボードが開きます:

• ダッシュボードホーム — グラフ統計、最近のアクティビティ、エンティティタイプの内訳

• ナレッジグラフ — クラスタリング機能付きのインタラクティブなD3フォースグラフ

• ライブフィード — WebSocket経由のリアルタイムなファイル変更およびエンティティ抽出イベント

• クエリエクスプローラー — ストリーミング応答による自然言語クエリ

• 矛盾解決ツール — 競合する決定事項の確認と解決

MCPサーバー (Claude Code統合)

CortexにはMCPサーバーが含まれており、Claude Codeがナレッジグラフを直接クエリできます:

claude mcp add cortex --scope user -- npx @gzoo/cortex mcp

これにより、Claude Codeで12個のツールが利用可能になります:

アーキテクチャ

8つのパッケージからなるモノレポ構成:

• @cortex/core — 型、EventBus、設定ローダー、エラークラス

• @cortex/ingest — ファイルパーサー（tree-sitter + remark）、チャンカー、ウォッチャー、パイプライン

• @cortex/graph — SQLiteストア、LanceDBベクトル、クエリエンジン

• @cortex/llm — Anthropic/Gemini/OpenAI互換/Ollamaプロバイダー、ルーター、プロンプト、キャッシュ

• @cortex/cli — 18個のコマンドを持つCommander.js CLI

• @cortex/mcp — Model Context Protocolサーバー (stdioトランスポート、12ツール)

• @cortex/server — Express REST API + WebSocketリレー

• @cortex/web — React + Vite + D3 Webダッシュボード

アーキテクチャの詳細は以下を参照してください: docs/

プライバシーとセキュリティ

• restricted（制限付き）に分類されたファイルは、クラウドLLMに決して送信されません

• 機密ファイル (.env, .pem, .key) は自動検出され、ブロックされます

• APIキーのシークレットは、クラウド送信前にスキャンされ、編集（削除）されます

• すべてのデータは ~/.cortex/ にローカル保存されます — 外部への通信は行われません

セキュリティアーキテクチャの詳細は以下を参照してください: docs/security.md

使用技術

• SQLite (better-sqlite3経由) — エンティティと関係の保存

• LanceDB — セマンティック検索用のベクトル埋め込み

• Anthropic Claude — クラウドLLMプロバイダー

• Google Gemini — クラウドLLMプロバイダー (OpenAI互換API経由)

• DeepSeek — クラウドLLMプロバイダー (推論 + チャット)

• Groq — 高速クラウド推論

• Ollama — ローカルLLM推論

• tree-sitter — 言語対応ファイル解析

• Chokidar — クロスプラットフォームのファイル監視

• Commander.js — CLIフレームワーク

• React + Vite — Webダッシュボード

• D3 — ナレッジグラフの可視化

貢献

ガイドラインについては CONTRIBUTING.md を参照してください。

ライセンス

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

について

GZOO によって構築されました — AIを活用したビジネス自動化プラットフォーム。

Cortexは、複数のクライアントプロジェクト間でコンテキストを維持するための社内ツールとして始まりました。複数のプロジェクトを掛け持ちするすべての開発者がコンテキストを失っていることに気づき、この「自動ファイル監視 + ナレッジグラフ + 自然言語クエリ」というアプローチこそが解決策であると考え、オープンソース化しました。