GZOO Cortex

公式

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

GitHub

GZOO Cortex MCPで何ができますか？

プロジェクトについて自然言語で質問する — cortex_ask を使用してナレッジグラフに問い合わせ、ソース引用付きの回答を取得します。
システムステータスとグラフ統計を確認する — get_status を使用して、エンティティ数、プロバイダの健全性、最近のアクティビティを確認します。
登録済みプロジェクトの一覧表示と管理 — list_projects、add_project、remove_project を使用して、追跡対象のディレクトリを表示および制御します。
名前やフィルタでエンティティを検索する — find_entity と search_entities で、決定事項、コンポーネント、パターンなどを特定します。
矛盾の確認と解決 — get_contradictions で矛盾する決定事項を表示し、resolve_contradiction で解決済みとしてマークします。
オンデマンドでファイルを取り込む — ingest_file で特定のファイルの抽出をトリガーし、ウォッチャーを待たずに処理します。

ドキュメント

GZOO Cortex

開発者のためのローカルファーストな知識グラフ。 プロジェクトファイルを監視し、 LLMを使用してエンティティと関係性を抽出し、すべてのプロジェクトに対して自然言語でクエリを実行できます。

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

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

理由

複数のプロジェクトに取り組んでいると、決定事項、パターン、コンテキストが何百ものファイルに散在します。3か月前に何を決めたか忘れてしまい、別のリポジトリで既に解決した問題を再度解決しようとします。

Cortexはプロジェクトディレクトリを監視し、知識を自動的に抽出し、必要なときにそれを提供します。

機能

プロジェクトファイル（md、ts、js、py、json、yaml）の変更を監視
エンティティの抽出: 決定事項、パターン、コンポーネント、依存関係、制約、アクションアイテム
プロジェクト間のエンティティ間の関係性を推論
決定事項が矛盾する場合の矛盾の検出
ソース引用付きの自然言語でのクエリ
セマンティック検索 — キーワードとベクトル（埋め込み）の類似性を組み合わせ、キーワードだけでなく意味でクエリをマッチング（オプション。セマンティック検索を参照）
クラウドLLMとローカルLLM間のインテリジェントなルーティング
プライバシーの尊重 — 制限付きプロジェクトはマシンから外部に出ません
知識グラフの可視化、ライブフィード、クエリエクスプローラーを備えたWebダッシュボード
Claude Codeとの直接統合のためのMCPサーバー

クイックスタート

1. インストール

npm install -g @gzoo/cortex

グローバルインストールが EACCES で失敗する場合は、代わりにユーザープレフィックスを使用してください。

mkdir -p ~/.local
npm config set prefix ~/.local
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @gzoo/cortex

またはソースからインストールします。

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

確認: cortex --version (現在のリリース: 0.8.1)

2. セットアップ

インタラクティブウィザードを実行します。

cortex init
cortex doctor                              # verify config, providers, and DB

これにより、以下が案内されます。

LLMプロバイダー — Anthropic、Google Gemini、DeepSeek、Groq、OpenRouter、またはOllama（ローカル）
APIキー — ~/.cortex/.env に安全に保存
ルーティングモード — クラウド優先、ハイブリッド、ローカル優先、またはローカルのみ
監視ディレクトリ — Cortexが監視するディレクトリ
予算制限 — 月間LLM使用量の上限

cortex init はグローバル設定を ~/.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 ingest "~/projects/app/src/**/*.ts"   # one-shot backfill
cortex serve                                 # dashboard + API + file watcher (recommended)

コマンド	機能
`cortex serve`	Webダッシュボード + API + ファイルウォッチャー (`ignoreInitial` — 起動時に再取り込みなし)
`cortex watch`	CLIのみのファイルウォッチャー (ダッシュボードなし)
`cortex ingest`	ワンショット取り込み。イベントはライブフィードに表示されません

watch と serve を同時に実行しないでください — ファイル変更の取得で競合します。ライブフィードには、cortex serve からのリアルタイムイベント（サーバー実行中のファイル保存）のみが表示されます。

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 serve --host 0.0.0.0

localhost以外のホストでは認証が自動的に適用されます。ベアラートークンが自動生成され、~/.cortex/.env に保存されます（grep CORTEX_SERVER_AUTH_TOKEN ~/.cortex/.env で読み取ります）。http://<host>:3710/?token=<token> でダッシュボードを一度開きます — トークンは、既にその所有を証明するリクエストに対してのみ埋め込まれ、その後ブラウザタブに保持されます（したがって、匿名の訪問者が受け取ることはありません）。リバースプロキシ背後でのAPI/WebSocket呼び出しは Authorization: Bearer <token> を使用します。

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

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はファイル変更ごとにパイプラインを実行します。

解析 — ファイルコンテンツは言語認識パーサー（コードはtree-sitter、マークダウンはremark）によってチャンク化されます
抽出 — LLMがエンティティ（決定事項、コンポーネント、パターンなど）を識別します
関連付け — LLMが新規および既存のエンティティ間の関係性を推論します
検出 — 矛盾と重複が自動的にフラグ付けされます
保存 — エンティティ、関係性、ベクトルがSQLite + LanceDBに保存されます
クエリ — 自然言語クエリがグラフを検索し、回答を合成します

すべてのデータは ~/.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など) — 完全ローカル、クラウド不要

コスト追跡は、DeepSeek、Gemini、Groq、OpenRouterモデルに対してプロバイダー認識のレートを使用し、一律のAnthropicフォールバックではありません。

埋め込み（セマンティック検索用）は、チャットモデルとは独立した別個のプロバイダーとして設定されるため、チャットをDeepSeekで実行し、埋め込みをOpenAIで実行できます。セマンティック検索を参照してください。

ルーティングモード

モード	クラウドコスト	品質	Ollama必須
`cloud-first`	プロバイダーにより変動	最高	いいえ
`hybrid`	削減	高	はい
`local-first`	最小限	良好	はい
`local-only`	$0	良好	はい

クラウド優先モードでは、すべてのタスクがクラウドプロバイダーにルーティングされます。Ollamaは不要で、予算フォールバックが有効な場合にのみ使用されます。ハイブリッドモードでは、大量のタスク（エンティティ抽出、ランキング）をOllamaに、推論の多いタスク（関係性推論、クエリ）をクラウドプロバイダーにルーティングします。

要件

Node.js 20以上
クラウドモード用のLLM APIキー — Anthropic、Google Gemini、DeepSeek、Groq、または任意のOpenAI互換プロバイダー
Ollama — hybrid、local-first、または local-only モードのみ（インストール）

設定

設定は階層化されており、後のソースが前のものを上書きします。

優先度	場所	スコープ
1	組み込みデフォルト	グローバル
2	`~/.cortex/cortex.config.json`	グローバル (`cortex init` によって作成)
3	`./cortex.config.json`	プロジェクト上書き (オプション)
4	`CORTEX_*` 環境変数	セッション

APIキーは ~/.cortex/.env に個別に保存されます（設定JSONには決して保存されません）。

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
cortex doctor                            # validate setup

完全な設定リファレンス: docs/configuration.md

セマンティック検索（埋め込み）

Cortexはキーワード（全文）検索とベクトル類似性を組み合わせ、クエリが正確な単語ではなく意味でマッチングするようにします。埋め込みはオプションでデフォルトではオフです — クラウド埋め込みプロバイダーで有効にします（ローカルGPUやOllamaは不要）。

cortex config set llm.embeddings.enabled true
cortex config set llm.embeddings.baseUrl https://api.openai.com/v1
cortex config set llm.embeddings.model text-embedding-3-small
cortex config set llm.embeddings.apiKeySource env:OPENAI_API_KEY
cortex config set llm.embeddings.dimensions 1536
# then add the key to ~/.cortex/.env:
echo 'OPENAI_API_KEY=sk-...' >> ~/.cortex/.env

埋め込みプロバイダーはチャットプロバイダーから独立しています — チャットをDeepSeek（またはAnthropic、Groqなど）で実行し、埋め込みをOpenAIで実行します。任意のOpenAI互換埋め込みエンドポイントが機能します。

新しいファイルは取り込み時に自動的に埋め込まれます。既に取り込んだグラフのインデックスを構築するには、1回限りの再インデックスを実行します。

cortex reindex                 # all projects
cortex reindex my-app          # a single project

コマンド

コマンド	説明
`cortex init`	インタラクティブセットアップウィザード
`cortex doctor`	設定、プロバイダー、プロジェクト、シークレット、データベースの検証
`cortex projects add/list/remove/show`	登録済みプロジェクトの管理
`cortex serve`	Webダッシュボード + API + ファイルウォッチャー (ポート3710)
`cortex watch [project]`	CLIのみのファイルウォッチャー
`cortex ingest <file-or-glob>`	ワンショットファイル取り込み (ライブフィードとは別)
`cortex reindex [project]`	既存エンティティのセマンティック（埋め込み）検索インデックスの再構築
`cortex query <question>`	引用付き自然言語クエリ
`cortex find <term>`	名前によるエンティティ検索
`cortex status`	グラフ統計、コスト、プロバイダーステータス
`cortex costs`	詳細なコスト内訳
`cortex contradictions`	アクティブな矛盾の一覧表示
`cortex resolve <id>`	矛盾の解決
`cortex models list/pull/test/info`	Ollamaモデルの管理
`cortex mcp`	Claude Code用MCPサーバーの起動
`cortex report`	取り込み後のサマリー
`cortex privacy set/list`	ディレクトリのプライバシー設定
`cortex config list/get/set/validate`	設定の読み取り/書き込み
`cortex config exclude add/remove/list`	ファイル/ディレクトリ除外の管理
`cortex stop` / `cortex restart`	実行中の監視/サーブプロセスの管理
`cortex db`	データベース操作

完全なCLIリファレンス: docs/cli-reference.md

Webダッシュボード

cortex serve を実行すると、http://localhost:3710 で完全なWebダッシュボードが開き、以下が利用できます。

ダッシュボードホーム — グラフ統計、最近のアクティビティ、エンティティタイプの内訳
知識グラフ — クラスタリング、クリックして探索できるインタラクティブなD3-forceグラフ
ライブフィード — WebSocket経由のリアルタイムファイル変更およびエンティティ抽出イベント（cortex serve からのみ）
クエリエクスプローラー — ストリーミング応答付きの自然言語クエリ
矛盾リゾルバー — 競合する決定事項の確認と解決

リモートデプロイメント

localhostを超えてアクセスするには、すべてのインターフェースにバインドし、Cortexをリバースプロキシの背後に配置します。

cortex serve --host 0.0.0.0

nginx設定例 — /api/ と /ws を基本認証で保護し、静的アセットは認証なしで提供します（ダッシュボードはベアラートークンをHTMLに注入します）。

location /api/ {
    auth_basic "Cortex";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:3710;
    proxy_set_header Authorization "Bearer $CORTEX_TOKEN";
}

location /ws {
    auth_basic "Cortex";
    auth_basic_user_file /etc/nginx/.htpasswd;
    proxy_pass http://127.0.0.1:3710;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

location / {
    auth_basic off;
    proxy_pass http://127.0.0.1:3710;
}

設定で CORTEX_SERVER_AUTH_TOKEN または server.auth.token を設定します。認証が有効な場合、CortexはAPIとWebSocket呼び出しが自動的に認証されるように、トークンをダッシュボードHTMLに注入します。

MCPサーバー（Claude Code統合）

CortexにはMCPサーバーが含まれており、Claude Codeが知識グラフに直接クエリを実行できます。

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

これにより、Claude Codeに12のツールが提供されます。

ツール	説明
`cortex_ask`	プロジェクトに関する自然言語の質問
`get_status`	システムステータスとグラフ統計
`list_projects`	登録済みプロジェクトの一覧表示
`find_entity`	名前によるエンティティの検索
`query_cortex`	構造化された知識グラフクエリ
`get_contradictions`	検出された矛盾の一覧表示
`resolve_contradiction`	矛盾の解決
`search_entities`	フィルター付きエンティティ検索
`ingest_file`	ファイル取り込みのトリガー
`add_project`	新しいプロジェクトの登録
`remove_project`	プロジェクトの登録解除
`session_brief`	現在のセッションのコンテキストサマリー

アーキテクチャ

8つのパッケージを持つモノレポ:

@cortex/core — 型、EventBus、設定ローダー、エラークラス
@cortex/ingest — ファイルパーサー（tree-sitter + remark）、チャンカー、ウォッチャー、パイプライン
@cortex/graph — SQLiteストア、LanceDBベクトル、クエリエンジン
@cortex/llm — Anthropic/Gemini/OpenAI互換/Ollamaプロバイダー、ルーター、プロンプト、キャッシュ
@cortex/cli — 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 via 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は、複数のクライアントプロジェクトにわたってコンテキストを維持するための内部ツールとして始まりました。複数のことに取り組むすべての開発者がコンテキストを失うため、このアプローチ — 自動ファイル監視 + ナレッジグラフ + 自然言語クエリ — がそれを解決する正しい方法だと考え、オープンソース化しました。