pulse8-ai-cortex-knowledge-vault

PULSE8.ai Cortex

AI エージェントのためのオープンソースのナレッジレイヤー
知識は積み重なります。

PULSE8.ai Cortex は、AI エージェントのためのオープンソースのナレッジレイヤーです。Git を基盤とするメモリ、型付きナレッジグラフ、そしてプレーンな Markdown 上での MCP を活用した検索機能を備えています。これにより、エージェントはクエリのたびに知識を再導出するのではなく、永続的な知識を構築し、発展させ、再利用できます。

内部では、AI エージェントと人間が使える統合型のボルトとして動作し、型付きナレッジグラフ、全文検索とハイブリッド検索、MarkItDown を活用したファイルコンパイラーを備えています。ファイル（PDF、DOCX、PPTX、XLSX、HTML、画像など）を投入すると、エージェントが知識の読み取り、書き込み、検索、リンク、コンパイルを行えます。データベースは不要です。

Andrej Karpathy の LLM Wiki パターンに着想を得ています。これは、クエリのたびに知識を再導出するのではなく、LLM が維持する、永続的で積み重なっていくナレッジベースです。検索機能は Tobi Lütke の QMD を活用しています。

---

なぜ PULSE8.ai Cortex なのか？

ほとんどの AI エージェントはツールにアクセスできますが、知識を蓄積することはできません。

従来の RAG システムはドキュメントを検索します。PULSE8.ai Cortex は、時間とともに成長し、エージェントや人間が利用するほど価値が高まる、永続的で進化するナレッジレイヤーを構築します。

PULSE8.ai Cortex を使うと、エージェントは次のことができます。

• やり取りから学習する — 読み取り、書き込み、取り込み、コンパイルのすべてのイベントが記録され、グラフにリンクされます
• ナレッジグラフを構築し、たどる — Wiki リンク、タグ、型付きエッジが自動的に維持されます
• 構造化された知見を保存する — 型付きノード（note、agent_def、session、daily、feedback）を含む Markdown ノート
• プロジェクトをまたいでコンテキストを取得する — vault_context は、任意のシードクエリからランク付けされたサブグラフを構築します
• MCP を通じて知識を共有する — 1 つのボルトを、MCP 互換のあらゆるクライアントで利用できます
• 長期記憶を維持する — ファイルはセッション、デプロイ、モデルのアップグレードをまたいで保持されます
• Git で知識をバージョン管理する — ボルトは Markdown ファイルだけで構成されるプレーンなディレクトリで、最初から差分の確認に適しています

項目	従来の RAG	PULSE8.ai Cortex
重視するもの	ドキュメント	知識
メモリ	セッション単位	永続的
構造	チャンク	Markdown + 型付きグラフ
進化	静的インデックス	継続的、ファイル監視型
バージョン管理	なし	Git を基盤
エージェント間の連携	限定的	中核機能（MCP）

PULSE8.ai Cortex の利用に適した場面

最適なユースケース

• ✅ AI エージェント向けの永続メモリ
• ✅ 複数のエージェント間でのナレッジ共有
• ✅ Git でバージョン管理された組織のナレッジ
• ✅ MCP 互換のナレッジ検索
• ✅ 専用のグラフデータベースを使わないナレッジグラフ
• ✅ 組織のナレッジの長期的な蓄積
• ✅ 人間と AI による共同ナレッジ管理

向いていないケース

• ❌ シンプルな全文ドキュメント検索（検索エンジンを使用してください）
• ❌ グラフを使わない、純粋なベクトル検索（ベクトル DB を使用してください）
• ❌ 短期間で終了するステートレスな会話
• ❌ 永続的なナレッジの進化を必要としないワークフロー

PULSE8.ai Cortex と代替手段の比較

機能	PULSE8.ai Cortex	従来型 RAG	GraphRAG
永続的なナレッジ	✅	❌	⚠️
Markdown ネイティブのストレージ	✅	❌	❌
すぐに使える MCP 互換性	✅	❌	❌
ナレッジグラフ	✅	❌	✅
Git によるバージョン管理	✅	❌	❌
エージェントメモリレイヤー	✅	❌	⚠️
人間と AI による共同作業	✅	❌	⚠️
継続的なナレッジの進化	✅	❌	⚠️
データベース不要	✅	❌	❌

連携先

PULSE8.ai Cortex は MCP に対応しているため、MCP に対応するあらゆる AI クライアントと接続できます。同じボルトにストリーミング可能な HTTP または stdio 経由でアクセスでき、/api/v1/ の REST API にも 1 対 1 でミラーリングされます。

カテゴリ	互換性のあるもの
AI エージェント	Claude Desktop、Claude Code、OpenAI Agents、Gemini、カスタムエージェントフレームワーク
開発ツール	Cursor、VS Code、JetBrains IDE
エージェントフレームワーク	LangGraph、LangChain、CrewAI、AutoGen
MCP エコシステム	MCP クライアント、MCP サーバー、MCP ツールレジストリ
人間向けツール	Obsidian、あらゆる Markdown エディター、あらゆる Git クライアント

ボルトは単なるファイルなので、人間とエージェントが同じナレッジを使って共同作業できます。独自形式も、ベンダーロックインもありません。

はじめる

メモ

PULSE8.ai Cortex を実行するには Docker が必要です。OpenRouter API キーは任意です。必要なのは、LLM を利用した Wiki 記事間の相互参照を行う場合のみです。ファイル変換は API キーなしですぐに利用できます。

1. リポジトリをクローンします：

  git clone https://github.com/synpulse8-opensource/pulse8-ai-cortex-knowledge-vault.git
  cd cortex-knowledge-vault

2. PULSE8.ai Cortex を起動します：

  ./scripts/start.sh

これにより **PULSE8.ai Cortex**（`:8420` の API と MCP）と **QMD**（`:3100` の検索）がビルドされて起動し、ヘルスチェックの完了を待ちます。これで準備完了です。

3. MCP クライアント（例：Claude Desktop）を http://localhost:8420/mcp/ に接続します。

停止するには：./scripts/stop.sh

ネイティブ QMD モード（macOS / Metal GPU）

macOS の Docker Desktop は Metal GPU をコンテナに公開できないため、コンテナ上の QMD は CPU のみで埋め込みを行います。そのため、規模の大きいボルトでは 10 倍以上遅くなります。代わりに QMD をネイティブで実行してください。qmd バイナリは Metal を自動的に使用します：

# One-time: install the qmd binary
brew install tobi/tap/qmd   # or: npm install -g @tobilu/qmd

# Start native QMD (background daemon) + Cortex in Docker
./scripts/start.sh --native-qmd

QMD デーモンの PID とログは .qmd-native.pid / .qmd-native.log に保存されます。両方を停止するには：./scripts/stop.sh --native-qmd（通常の ./scripts/stop.sh でも、実行中のネイティブ QMD は終了します）。

Cortex のみのモード（外部 QMD）

QMD を自分で管理している（すでに別の場所で実行している）場合は、Cortex コンテナのみを起動します：

./scripts/start.sh --cortex-only   # set QMD_URL in .env if not http://host.docker.internal:3100

停止するには：./scripts/stop.sh --cortex-only

GPU アクセラレーション対応の QMD（EC2／NVIDIA GPU 搭載 Linux）

NVIDIA GPU アクセラレーションを利用した本番環境へのデプロイについて：

docker compose -f docker-compose.yml -f docker-compose.gpu.yml up --build -d

インスタンスの選択、NVIDIA ツールキットのインストール、費用の見積もりについては、docs/ec2-gpu-setup.md の詳細ガイドをご覧ください。

機能

ナレッジグラフ	型付きグラフエンジン（NetworkX）— Wikilink、タグ、カスタムエッジに対応し、ファイルの変更ごとに自動で保守します
全文検索	デフォルトでハイブリッド検索（BM25 + ベクトル + 再ランキング）を使用する QMD 検索。キーワードモードとセマンティックモードを選択できます。結果は設定可能な TTL でキャッシュされます。
ファイルコンパイラー	MarkItDown を介して、未加工のソース（PDF、DOCX、PPTX、XLSX、HTML、画像など）を Markdown に変換します。LLM は相互参照にのみ使用します。
MCP サーバー	ストリーム可能な HTTP + stdio トランスポート — Claude Desktop、Cursor、あらゆる MCP クライアントで動作します
フィードバックと通知	vault_feedback が品質に関するフィードバックをノートとして記録します。オプションで Microsoft Teams の Webhook を使い、投稿ごとにアダプティブカードを送信できます
日次アクティビティログ	すべての書き込み／取り込み／コンパイルを daily/<date>.md にミラーリングし、検索可能な Wikilink 付きタイムラインとして記録します
一括取り込み	SHA-256 による重複排除と並列数制限により、ローカルディレクトリから数十〜数百のファイルを一度に取り込みます
REST API	/api/v1/ で、マルチパートファイルアップロードと一括取り込みを含むすべての MCP ツールに対応する FastAPI エンドポイントを提供します
Vault ウォッチャー	ファイルシステムをリアルタイムで監視し、グラフを自動的に同期します
リネージと監査	各エッジに extracted／inferred／manual のラベルを付与します。vault_trace を使うと、「なぜ Vault は X と述べているのか」をソース文書までさかのぼって確認できます
グラフクエリ	vault_path（X と Y をつなぐもの）、vault_impact（このノートから下流にあるもの）、vault_explain（出典情報付きのエンティティ概要）
キュレーションレポート	閲覧回数 + 結果フィードバック（useful／dead-end／corrected）により、古くなったノート、矛盾するノート、未読のノートを GET /api/v1/curation/report で確認できます
データベース不要	すべてのデータをファイルシステム上に Markdown + JSON として保存します

ベンチマーク

LongMemEval-S（500 件の質問、完全なハイスタック、ハイブリッド検索）で全体精度 45.0% を達成しました。エビデンス再現率@8 は 65.6%、判定モデルの誤りはゼロです。公開 REST API を通じて、取り込み → コンパイル → グラフ → 検索 → 回答まで、エンドツーエンドで測定しています。

カテゴリ	精度	再現率@8
single-session-assistant	96.4%	98.2%
single-session-user	71.4%	78.6%
knowledge-update	60.3%	75.6%
temporal-reasoning	25.6%	51.1%
multi-session	24.8%	54.1%
single-session-preference	23.3%	63.3%

すべての数値は、固定された設定（データセットの SHA-256、モデル、シード）から、次の 1 つのコマンドで再現できます。

uv run python -m evals.run_longmemeval --config evals/configs/longmemeval-s-hybrid.yaml

ハーネス（evals/）は質問ごとの JSONL トレースを公開し、判定モデルと回答モデルを分離しています。また、LongMemEval 公式のタイプ別採点プロンプトを使用し、判定モデルのブラインド方式による人手検証も含まれています。手法の詳細、注意事項、結果の生データについては、docs/benchmarks/ をご覧ください。

LLM なしで動作

Cortex は決定性を優先しています。取り込み（MarkItDown による変換）、ナレッジグラフ（ウィキリンク、タグ、derived_from エッジ）、QMD 検索はすべて LLM 呼び出しゼロで動作します。LLM は、相互参照、タグ付け、画像キャプション生成などの任意のエンリッチメント処理であり、依存関係ではありません。

LLM_BACKEND（環境変数）／CORTEX_LLM_BACKEND（Python）でバックエンドを選択します。

バックエンド	対応範囲
openai-compatible（デフォルト）	OpenRouter、Azure OpenAI、Ollama、vLLM、LM Studio など、OpenAI プロトコルを話すサービスすべて。LLM_BASE_URL をエンドポイントに設定してください。
bedrock	標準の AWS 認証情報チェーンを使用する AWS Bedrock（API キー不要）。boto3 が必要です。
none	LLM を明示的に一切使用しないモードです。LLM クライアントを構築せず、モデル呼び出しも行わないことが保証されており、エアギャップ環境へのデプロイに適しています。

ローカルの Ollama を使用するエアギャップ環境の例：

LLM_BACKEND=openai-compatible \
LLM_BASE_URL=http://localhost:11434/v1 \
LLM_API_KEY=ollama \
COMPILER_MODEL=llama3.1 \
./scripts/start.sh

または、完全に決定論的なモード：LLM_BACKEND=none ./scripts/start.sh（API キーは不要です）。

MCP リソース（トークン消費を抑えた大容量ペイロード）

PULSE8.ai Cortex は、Microsoft Copilot Studio CAT チームが推奨するリソースをツール入力として扱うパターンを実装しています。トークン消費の多いツール出力（大量の検索結果、完全なコンテキストウィンドウなど）をサーバー側に保持し、軽量なハンドルとしてツール間で渡せるため、LLM のコンテキストウィンドウを小さく保てます。

仕組み。 vault_search または vault_context に as_resource: true を渡すか、GET /api/v1/search に ?as_resource=true を指定します。ペイロード全体をインラインで返す代わりに、ハンドルが返されます。

{
  "resource_id": "7f8a3c...",
  "resource_uri": "cortex://resource/7f8a3c...",
  "summary": { "query": "...", "count": 8, "paths": ["..."] }
}

次の 3 つのトランスポートのいずれかを通じて読み取れます。

• MCP リソースプロトコル — cortex://resource/{id} URI を指定して resources/read を実行します（Claude Desktop、Cursor、Copilot Studio MCP）。
• フォールバックツール — 計画レイヤーにツールのみを公開するクライアント向けの vault_resource_read（一部の Copilot Studio 構成）。
• REST — GET /api/v1/resources/{resource_id}（ID 単体または完全な URI を受け付けます）。

ストアはメモリ内にあり、asyncio セーフで、TTL による削除と LRU による上限管理に対応しています。

環境変数	デフォルト	目的
CORTEX_RESOURCE_TTL_SECONDS	3600	保存されたリソースを読み取り時に遅延削除するまでの最大経過時間
CORTEX_RESOURCE_MAX_ITEMS	1000	最も古いエントリを破棄する前の LRU 上限

MCP と REST は同じ ResourceStore を共有します。MCP 経由でハンドルを作成し、REST 経由で読み取る（またはその逆）ことができます。

Microsoft Copilot Studio のセットアップ（エージェント向けの指示、ツールの選択、Custom Connector によるフォールバック）については、docs/copilot-studio.md に記載されています。Cortex のコードを変更する必要はありません。

MCP ツール

ツール	説明
vault_read	パスを指定してノートを読み取ります
vault_write	ノートを作成または更新します
vault_search	Vault を検索します（キーワード／セマンティック／ハイブリッド）。as_resource=true をサポートします
vault_link	グラフのエッジを作成、検索、または削除します
vault_context	コンテキストウィンドウを構築します：検索 → グラフのトラバーサル → ランク付けされたサブグラフ。as_resource=true をサポートします
vault_ingest	生コンテンツまたはバイナリファイルを取り込みます（バイナリには content_base64 を使用できます）
vault_compile	未処理の生ソースを MarkItDown 経由で Wiki の Markdown にコンパイルします
vault_feedback	Vault の品質に関するフィードバックを送信します（status: OPEN、related_paths と outcome（useful／dead-end／corrected）は任意）
vault_list_feedbacks	フィードバックノートのメタデータ（パス、タグ、ステータス。本文全体は含みません）を一覧表示します
vault_resource_read	サーバーに保存された MCP リソースを ID で読み取ります（resources/read に対応していないクライアント向けのフォールバック）
vault_trace	ノートの系譜をたどります：出所、生ソース、および extracted／inferred／manual のラベルが付いたエッジ
vault_path	2 つのノート間の最短経路を示します — 「X と Y をつなぐものは何か」。すべての経由点に型と出所ラベルが付きます
vault_impact	ノートの下流にあるすべての要素をたどります（変更影響分析）
vault_explain	ノートを説明します：要約、出所、ソース、リンクの入出力、矛盾

アーキテクチャ

┌──────────────────────────────────────────────┐
│  MCP Client (Claude Desktop, Cursor, etc.)   │
└──────────┬───────────────────────────────────┘
           │  MCP (HTTP or stdio)
┌──────────▼───────────────────────────────────┐
│  PULSE8.ai Cortex  :8420                     │
│  ┌──────────────────────────────────────┐     │
│  │ Auth (API Key or Microsoft Entra ID) │     │
│  └──────────────┬───────────────────────┘     │
│  ┌─────────┐ ┌──┴───────┐ ┌──────────────┐   │
│  │ MCP     │ │ REST API │ │ Vault Watcher│   │
│  │ /mcp/   │ │ /api/v1/ │ │ (watchfiles) │   │
│  └────┬────┘ └────┬─────┘ └──────┬───────┘   │
│       └───────────┼──────────────┘           │
│            ┌──────▼──────┐                   │
│            │ Graph Engine│                   │
│            │ + Compiler  │                   │
│            └─────────────┘                   │
└──────────┬───────────────────────────────────┘
           │
┌──────────▼───────────────────────────────────┐
│  QMD  :3100                                  │
│  BM25 + vector search, auto-indexes on start │
└──────────┬───────────────────────────────────┘
           │
┌──────────▼───────────────────────────────────┐
│  Vault (bind-mounted volume)                 │
│  wiki/ raw/ agents/ sessions/ daily/ feedback/ │
│  .cortex/ (graph.json, index.md, log.md)     │
└──────────────────────────────────────────────┘

Vault の構成

Vault は、目的別に整理された Markdown ファイルの通常のディレクトリです。Cortex は各ファイルを、グラフエンジンで使用され、REST および MCP のレスポンスで公開される型付きノード（NodeType）に分類します。

フォルダー	NodeType	目的
wiki/	note	コンパイル済みの相互リンクされたナレッジ記事
raw/	raw_source	コンパイラーが読み込む未処理のソース（PDF、DOCX、TXT、…）
agents/	agent_def	エージェントの定義
sessions/	session	セッションごとのノート／会話の文字起こし
daily/	daily	日次ノート（Obsidian Daily Notes の規約）
feedback/	feedback	Vault の品質に関するフィードバック（status、related_paths）
.cortex/	(スキップ)	Cortex の内部データ — graph.json、index.md、log.md、マニフェスト

分類の仕組み

優先順位（最初に一致したものが適用されます）：

1. Frontmatter の type:* — 明示的な指定が常に優先されます（例：agents/foo.md の type: note は NodeType.NOTE に解決されます）
2. フォルダーのプレフィックス — raw/ agents/ sessions/ daily/ feedback/ 内のファイルは、ファイル名のサフィックスがなくても、そのフォルダーの型を引き継ぎます（例：daily/2026-06-10.md → daily）
3. ファイル名のサフィックス（後方互換） — .agent.md、.session.md、.memory.md は引き続き、場所を問わず適用されます（例：wiki/legacy.agent.md → agent_def）
4. デフォルト — NodeType.NOTE

実際には、YYYY-MM-DD.md をそのまま daily/ に、サフィックスなしの planner.md を agents/ に置くだけで、名前を変更しなくてもグラフと API が正しく分類します。

日次アクティビティログ

すべての vault_write、vault_ingest、および成功した compile イベント（MCP および REST 経由）は、本日の UTC 日次ノート daily/YYYY-MM-DD.md に自動的にミラーリングされます。このファイルはその日の最初のイベント時に作成され、その後の各イベントで ## [HH:MM] event | summary ブロックと [[wiki-stem]] の Wiki リンクが追記されます（これにより、ウォッチャーは対象ノートへの LINKS_TO エッジを描画します）。この形式は Karpathy の log.md の検索可能なプレフィックスパターンに従っており、grep "^## \[" daily/2026-06-10.md を実行すると、その日のタイムラインをきれいに表示できます。

daily/、feedback/、.cortex/ を対象とする書き込みは、意図的にミラーリングされません（自己参照によるノイズを避けるためです）。非表示の .cortex/log.md 監査ログには影響せず、引き続きすべての操作が記録されます。

一括取り込み

多数のファイル（数十、数百の PDF、論文、ドキュメント）を一度に取り込む場合は、MCP 経由で 1 つずつ処理する代わりに、ワンクリックのシェルスクリプトを使用してください。ローカルディレクトリから直接（サブフォルダーも含めて再帰的に）読み込むため、通信のオーバーヘッドも、実行中のサーバーも必要ありません。SHA-256 ハッシュによる重複排除、上限付き並行処理でのコンパイル、最後に 1 回のインデックス再構築を行います。サブパスは vault の raw フォルダー内に保持されます（例：source/abcde/doc.html → raw/abcde/doc.html）。

ワンクリックスクリプト（推奨）

# Ingest all files from a directory
./scripts/bulk_ingest.sh ./my-papers/

# Dry-run to preview what would be ingested
./scripts/bulk_ingest.sh ./my-papers/ --dry-run

# Force re-ingest (bypass dedup manifest)
./scripts/bulk_ingest.sh ./my-papers/ --force

# Control LLM concurrency (default: 4)
./scripts/bulk_ingest.sh ./my-papers/ --concurrency 8

スクリプトは LLM キーと vault のパスに使用する .env を自動的に読み込み、概要を表示してから、パイプライン全体（コピー、コンパイル、再インデックス）を実行します。Cortex サーバーを実行しておく必要はありません。

Python CLI（直接実行）

CORTEX_VAULT_PATH=./example_vault uv run cortex-bulk-ingest --source ./my-papers/

Docker 内

# Set INGEST_DIR in .env or export it, then restart
export INGEST_DIR=/path/to/your/papers
docker compose up -d

# Run bulk ingest inside the container
docker exec pulse8-ai-cortex uv run cortex-bulk-ingest --source /ingest

REST API 経由

MCP を使わずにプログラムから利用する場合（Cortex サーバーの実行が必要です）：

curl -X POST http://localhost:8420/api/v1/bulk-ingest \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-secret-api-key" \
  -d '{"source_dir": "/ingest", "concurrency": 4}'

重複排除

重複排除マニフェストは .cortex/ingest-manifest.json に保存されます。ファイル名ではなくコンテンツハッシュで照合するため、ファイル名を変更しても再取り込みは行われず、別の名前で同じ内容のファイルがあってもスキップされます。

設定

サンプルをコピーして、値を入力してください：

cp .env.example .env

変数	必須	デフォルト	説明
LLM_BACKEND	いいえ	openai-compatible	LLM バックエンド：openai-compatible、bedrock（AWS 認証情報チェーン）、または none（LLM 呼び出しなし）
LLM_API_KEY	いいえ	—	OpenRouter（または互換サービス）の API キー（相互参照専用）
COMPILER_MODEL	いいえ	anthropic/claude-sonnet-4	相互参照の検出に使用するモデル
LLM_BASE_URL	いいえ	https://openrouter.ai/api/v1	LLM API のベース URL
VAULT_DIR	いいえ	./example_vault	Vault ディレクトリのパス
INGEST_DIR	いいえ	./ingest	一括取り込み元ディレクトリのパス（Docker では /ingest としてマウント）
QMD_REFRESH_INTERVAL_SECONDS	いいえ	900	定期的な再インデックスの間隔（秒。無効にするには 0 を指定）
QMD_SEARCH_MODE	いいえ	hybrid	指定がない場合のデフォルトの検索モード：hybrid（BM25 + ベクトル + 再ランキング）、semantic、または keyword
QMD_CACHE_TTL_SECONDS	いいえ	30	検索結果キャッシュの TTL。読み取り頻度の高い Vault では値を大きくすると、QMD の呼び出しの繰り返しを省略できます
QMD_SEARCH_TIMEOUT_SECONDS	いいえ	120	リクエストごとの検索タイムアウト（CPU のみのホストで hybrid を使う場合は値を大きくしてください）
QMD_EMBED_TIMEOUT_MS	いいえ	600000	埋め込みのタイムアウト（ミリ秒。CPU のみのデプロイでは値を大きくしてください）
QMD_URL	いいえ	—	Cortex のみのモードで使用する外部 QMD URL（例：http://host.docker.internal:3100）
AUTH_METHOD	いいえ	none	認証方法：none、apikey、または oidc（認証を参照）
API_KEY	いいえ	—	x-api-key ヘッダー用の静的 API キー（AUTH_METHOD=apikey の場合に使用）
OIDC_TENANT_ID	いいえ	—	Microsoft Entra ID のテナント ID（AUTH_METHOD=oidc の場合に使用）
OIDC_CLIENT_ID	いいえ	—	Microsoft Entra ID アプリのクライアント ID
OIDC_CLIENT_SECRET	いいえ	—	Microsoft Entra ID のクライアントシークレット
OIDC_BASE_URL	いいえ	http://localhost:8420	Cortex サーバーの公開ベース URL（OAuth コールバックに使用）
TEAMS_WEBHOOK_URL	いいえ	—	受信 Webhook／Power Automate URL。新しいフィードバックノートごとにアダプティブカードを投稿します
TEAMS_APP_BASE_URL	いいえ	—	Teams カードに「Cortex で表示」リンクを表示するための、任意の公開 Cortex ベース URL
OPENROUTER_API_KEY と CORTEX_LLM_API_KEY は、LLM_API_KEY のエイリアスとして使用できます。上記の変数は .env に設定され（Docker は Compose 経由で読み込みます）、アプリで使用される CORTEX_* 設定にマッピングされます。

認証

Cortex は、REST API（/api/v1/）と MCP エンドポイント（/mcp/）の両方を保護する、2 つの認証方式をサポートしています。.env で AUTH_METHOD を設定して選択します。

AUTH_METHOD	説明
none	デフォルトです。すべてのエンドポイントが公開され、認証は不要です。
apikey	静的 API キーです。クライアントは x-api-key ヘッダーを渡します。
oidc	Microsoft Entra ID（Azure AD）による OAuth 2.0 + MFA 対応です。

API キー（AUTH_METHOD=apikey）

最も簡単な方法です。.env で方式とキーを設定します。

AUTH_METHOD=apikey
API_KEY=your-secret-api-key

クライアントは x-api-key ヘッダーでキーを渡します。

# REST API
curl http://localhost:8420/api/v1/health \
  -H "x-api-key: your-secret-api-key"

# MCP (via curl)
curl -X POST http://localhost:8420/mcp/ \
  -H "x-api-key: your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'

OAuth の検出エンドポイントは提供されないため、ログインのポップアップは表示されません。有効なキーを含まないリクエストには 401 が返されます。

Microsoft Entra ID（AUTH_METHOD=oidc）

MFA 対応の対話型ログインが必要なエンタープライズ環境向けです。

AUTH_METHOD=oidc
OIDC_TENANT_ID=your-tenant-id
OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_BASE_URL=http://localhost:8420

これにより、次の機能が有効になります。

• REST API：GET /api/v1/login を介した OAuth 2.0 認可コードフローです。ログイン後、アクセストークンを Authorization: Bearer <token> として渡します。API_KEY が設定されている場合は、有効な x-api-key ヘッダーもフォールバックとして受け付けられます。
• MCP エンドポイント：FastMCP に組み込まれた OIDCProxy が、ブラウザーを使った対話型ログインを処理します。

Azure AD アプリの登録

OIDC を使用するには、Azure Portal でアプリを登録します。

1. Azure Active Directory → App registrations → New registration に移動します
2. リダイレクト URI を http://localhost:8420/api/v1/auth/callback に設定します（Web プラットフォーム）
3. Certificates & secrets で、クライアントシークレットを作成します
4. API permissions で、openid、profile、email を追加します（Microsoft Graph → Delegated）
5. Tenant ID、Client ID、Client Secret を .env にコピーします

MCP クライアントのセットアップ

Claude Desktop

設定例は [claude_desktop_config.example.json](claude_desktop_config.example.json) に含まれています。

API キーを使用した HTTP（推奨） — PULSE8.ai Cortex は常時稼働するサーバーとして動作します。

{
  "mcpServers": {
    "cortex": {
      "url": "http://localhost:8420/mcp/",
      "headers": {
        "x-api-key": "your-secret-api-key"
      }
    }
  }
}

認証なしの HTTP — 認証が設定されていない場合に使用します。

{
  "mcpServers": {
    "cortex": {
      "url": "http://localhost:8420/mcp/"
    }
  }
}

Stdio — Claude Desktop が必要に応じてサーバーを起動します（認証は不要です）。

{
  "mcpServers": {
    "cortex": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/cortex", "python", "-m", "cortex.mcp"],
      "env": {
        "CORTEX_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Cursor

.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "cortex": {
      "url": "http://localhost:8420/mcp/",
      "headers": {
        "x-api-key": "your-secret-api-key"
      }
    }
  }
}

仕組み

Watcher と Compiler は独立したコンポーネントです。

• Watcher はグラフを維持します。.md ファイルの追加、変更、削除を検知すると、ノードとエッジが自動的に更新されます。
• Compiler は MarkItDown を使ってソースファイルを Markdown に変換し、wiki/ に書き込みます。対応形式には、PDF、DOCX、PPTX、XLSX、HTML、CSV、JSON、XML、画像（EXIF/OCR）、プレーンテキストが含まれます。LLM は、記事間の相互参照を任意で検出する場合にのみ使用されます。

両者は間接的に連携します。Compiler が wiki/ に書き込み、Watcher がそれを検出してグラフを更新します。

対応ファイル形式

形式	拡張子
PDF	.pdf
Microsoft Word	.docx
Microsoft PowerPoint	.pptx
Microsoft Excel	.xlsx、.xls
HTML	.html、.htm
テキストベース	.csv、.json、.xml、.txt、.md
画像	.jpg、.pngなど（EXIF メタデータ）

検索では、2段階のパイプラインを使用します。

1. QMDがファイルの内容をキーワード検索／セマンティック検索します
2. PULSE8.ai Cortexがグラフのエッジ（ウィキリンク、タグ、一致したノート間の関係）を使って検索結果を充実させます

QMDは「何が関連しているか？」に答え、グラフは「これらの結果はどのようにつながっているか？」に答えます。

実際のユースケース

ソフトウェアエンジニアリングのナレッジベース

• アーキテクチャ決定記録（ADR）
• コーディング標準と規約
• エンジニアリングハンドブックと運用手順書
• プラットフォームとサービスのドキュメント
• ドメイン駆動設計モデル

銀行・金融サービス

• 製品ドキュメント
• 規制およびコンプライアンスに関する知識
• ビジネスドメインモデル
• 資産運用の専門知識
• 機関の業務プロセスに関するノウハウ

エンタープライズのナレッジ管理

• 社内 Wiki
• プロジェクトドキュメントと事後分析
• 得られた教訓と振り返り
• 組織の記憶
• ベストプラクティスとプレイブック

AI エージェントのメモリレイヤー

• エージェント間で共有されるメモリ
• 長期的な推論のコンテキスト
• セッションをまたいだ知識の蓄積
• 単一のボルト上でのマルチエージェント協業

ロードマップ

短期

• ナレッジグラフの可視化を強化
• エージェントのアクティビティタイムライン
• ナレッジ品質のスコアリング
• MCP 統合の追加

中期

• マルチボルトのフェデレーション
• エンタープライズのガバナンスとアクセス制御ポリシー
• ナレッジの来歴追跡
• エージェント間学習シグナル

長期

• 自己改善型の組織の記憶
• 自律的なナレッジキュレーション
• ナレッジ主導型のエージェントエコシステム

開発

# Install dependencies
uv sync --all-extras

# Run tests
uv run pytest tests/ -v

# Run shell tests (requires bats-core)
bats tests/test_start_sh.bats

# Start PULSE8.ai Cortex locally (without Docker)
CORTEX_MCP_TRANSPORT=http CORTEX_VAULT_PATH=./example_vault uv run python scripts/serve.py

ユーティリティスクリプト

スクリプト	説明
scripts/serve.py	開発サーバー（CORTEX_MCP_TRANSPORTに応じてHTTPまたはstdio）
scripts/compile.py	すべての未加工ソースを一括コンパイル
scripts/reindex.py	全件再インデックスとグラフの再構築
scripts/bulk_ingest.sh	ローカルディレクトリからワンクリックで一括取り込み
scripts/bulk_ingest.py	一括取り込み用のPython CLI（bulk_ingest.shから呼び出し）
scripts/lint.py	ボルト構造のLint

データの永続化

ボルトディレクトリは、ホストからコンテナにバインドマウントされています。すべてのデータはローカルディスク上に保存され、コンテナを再起動しても保持されます。

QMDの検索インデックスは、Dockerボリューム（qmd-cache）に保存されます。インデックスを完全に再構築するには：

docker compose down -v
./scripts/start.sh

リリース

リリースは GitHub Actions によって自動化されています。GitHub リリースを公開すると、すべてをビルドして公開する 3 つのワークフローが実行されます。

ワークフロー	公開先
publish-pypi.yml	PyPI
publish-docker.yml	GitHub Container Registry（ghcr.io）
publish-mcp.yml	MCP Registry（GitHub OIDC 認証）

リリースを作成するには：

1. バージョンを更新し、pyproject.toml と server.json のバージョンを揃えます。CHANGELOG.md も更新し、main にコミットします。

   # optional: validate the registry manifest locally before tagging
   mcp-publisher validate
   

2. GitHub リリースを作成します。UI（Releases →「Draft a new release」→ 新しいタグ vX.Y.Z）または CLI を使用します：

   git tag vX.Y.Z && git push origin vX.Y.Z
   gh release create vX.Y.Z --title "vX.Y.Z" --notes-file docs/releases/vX.Y.Z.md
   

3. これで完了です — リリースイベントによって 3 つのワークフローがすべて実行されます。publish-mcp.yml は、PyPI で新しいバージョンが提供されるまで待機します（これにより、この README の mcp-name 所有権マーカーを検証できます）。その後、トークンやローカルの mcp-publisher を使わず、GitHub OIDC を通じて io.github.synpulse8-opensource/* 配下にサーバーを公開します。

4. ワークフローの完了後、レジストリへの登録を確認します：

   curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=pulse8-ai-cortex-knowledge-vault"
   

重要

PyPI のバージョンは不変です。削除後であっても、バージョン番号を再利用することはできません。必ず新しいバージョンに更新し、既存のバージョンを再リリースしないでください。

コミュニティ

AI エージェントには、別のドキュメントストアではなく、専用のナレッジレイヤーが必要だと考えています。このビジョンに共感していただける方は、ぜひご参加ください。

• リポジトリにスターを付ける
• ディスカッションまたはイシューを作成する
• プルリクエストを送信する（貢献を参照）
• 銀行、エンジニアリング、研究など、ユースケースを共有する

力を合わせて、エージェント型 AI のためのナレッジレイヤーを構築しましょう。

貢献

貢献を歓迎します！プルリクエストを送信する前に、アイデアを話し合うためのイシューを作成してください。

# Fork and clone the repo
git clone https://github.com/<your-username>/cortex-knowledge-vault.git
cd cortex-knowledge-vault

# Create a branch
git checkout -b feat/my-feature

# Install dev dependencies
uv sync --all-extras

# Make changes, then run tests
uv run pytest tests/ -v

# Submit a pull request

問題の報告

バグの報告や機能のリクエストには、GitHub Issuesをご利用ください。

謝辞

PULSE8.ai Cortex は、オープンソースコミュニティのアイデアやツールを基盤としています。

• Andrej Karpathyによる**LLM Wiki** — LLM が維持する永続的なナレッジベースの中核的なパターンです。クエリごとに生のドキュメントから知識を再発見するのではなく、知識を段階的にまとめ、相互にリンクします。この gist は Cortex のアーキテクチャに直接着想を与えています。
• Tobi Lütkeによる**QMD** — Cortex の全文検索とハイブリッド検索をすべて支えるオンデバイス検索エンジンです。QMD は BM25、ベクトル検索、LLM による再ランキングを組み合わせ、すべてローカルで実行します。
• Microsoftによる**MarkItDown** — Cortex コンパイラーを支えるファイルから Markdown へのコンバーターです。PDF、Office ドキュメント、HTML、画像などを、Vault への取り込みに適した構造化 Markdown に変換します。

ライセンス

このプロジェクトは、PULSE8.ai Cortex Open Source License（追加条項付き Apache License 2.0）の下でライセンスされています。