Chaos Cypher

Chaos Cypher Knowledge Engine

ドキュメントを、閲覧、検索、対話でき、持ち運びもできるナレッジグラフに変換します。すべてご自身のマシン上で動作します。

Chaos Cypher は、ローカルファーストの GraphRAG プラットフォームです。知識を見て、信頼し、所有できます。ドキュメント、音声、動画、画像、貼り付けたテキスト、ウェブページなどのソースを指定すると、30 以上の形式を自動検出し、エンティティと関係を抽出して、実際に目で見て探索できるナレッジグラフを構築します。ブラックボックスのベクトルデータの塊ではありません。検索、対話、調整を行い、その結果をポータブルなLexicon ナレッジパッケージ（.ccx）としてエクスポートして、バックアップ、共有、または別のインスタンスへの読み込みができます。

Chaos Cypher を選ぶ理由

• ローカルファーストの GraphRAG — ソース → 抽出 → グラフ → 検索と対話の流れで処理し、埋め込みはご自身のシステム上で生成します。お好みの LLM を使用するか、Ollama で完全オフラインで実行できます。
• 検証可能なナレッジグラフ — すべてのエンティティと関係を表示でき、ソースまで追跡できます。抽出結果をただ信頼するのではなく、修正できます。
• ポータブルなナレッジパッケージ — グラフを自己完結型パッケージとしてインポートおよびエクスポートできます。知識はあなたのものであり、移動、バージョン管理、保管ができます。
• MCP サーバーを内蔵 — Claude Desktop、Cursor、または任意の MCP クライアントをグラフに直接接続できます。検索、トラバーサル、グラフ構築用の44 個のツールを利用できます。
• セルフホスト可能な管理 — データの保存場所と、データに使用するモデルを選べます。オールインワンコンテナーにより、ご自身で管理するハードウェア上でスタック全体を実行できます。

主な機能

中核となるインテリジェンス

• ナレッジグラフキャンバス — 型付け、フィルター、ズームに対応し、コーパス全体の概要から個々のエンティティとそのソースまで確認できます
• GraphRAG 検索 — グラフ トラバーサルとベクトル検索を統合（Personalized PageRank + Reciprocal Rank Fusion）。キーワード、セマンティック、ハイブリッドの各モードも利用できます
• 引用付き AI チャット — コンテンツに基づいた回答を生成し、その回答の根拠となったソースまで追跡できます

データ基盤

• 品質分析 — グラフの充実度を 0～100 のスケールで評価し、信頼性の低いソースを特定する内訳を表示します
• 30 以上のソース形式 — PDF、DOCX、Markdown、HTML、EPUB、音声（MP3/WAV/FLAC）、動画（MP4/MKV/MOV）、 画像、ZIP アーカイブなど
• LLM を自由に組み合わせ — Ollama、OpenAI、Anthropic、Gemini に対応し、操作ごとに設定できます

自動化と連携

• 自動化 — トリガーと条件分岐を備えたビジュアルワークフロービルダー
• MCP サーバー — Claude Desktop、Cursor、ChatGPT、その他の MCP クライアント向けに 44 個のツールを提供
• プラグインシステム — Python 製のドキュメントローダー、抽出ドメイン、ワークフローツールを追加できます

マシンから外部に送信されるデータ

デフォルトでは、設定した LLM 呼び出しを除き、マシンから外部に送信されるデータはありません。 埋め込みはローカルで計算され、ドキュメント、グラフ、エクスポートデータはすべて、ご自身が所有する Docker ボリューム内に保存されます。Chaos Cypher をホスト型 LLM プロバイダー（OpenAI、Anthropic、Gemini）に接続した場合、抽出やチャットのために送信されるテキストは、そのプロバイダーに送られます。すべてをデバイス内にとどめるには、Ollama のようなローカルモデルを選択してください。

Chaos Cypher が防御する対象、設計上許容するもの、LAN またはインターネットに公開するデプロイを強化する方法について詳しくは、セルフホスト型脅威モデルをお読みください。

---

📸 実際の動作を見る

ドキュメントの追加から、質問して回答をソース内の該当箇所へたどるまでを、手短にご紹介します。

▶️ 音声なしのナレーション字幕付きフルツアーは、chaoscypher.comでご覧いただけます。

ダッシュボード — ナレッジベースの概要をひと目で確認できます。エンティティ数とリレーションシップ数、品質と密度のスコア、グラフのライブプレビューが表示されます。

ナレッジグラフ — すべてのソースが、探索可能な色分けされたグラフになります。パン、ズーム、検索、フィルターを使って、抽出された内容を正確に確認できます。

エンティティ — 抽出されたエンティティを調べられます。型付きの方向性を持つリレーションシップが重要度順に並び、統計情報とソースドキュメントまでたどれる出所情報も確認できます。

ソース — 各ドキュメントの処理パイプラインを透明性のある形で確認できます。読み込み → クリーニング → チャンク分割 → 抽出 → インデックス作成の各段階に加え、ソースごとのエンティティ分布も表示されます。

チャット — 自然な言葉で質問すると、エンティティの引用がインラインで付いた GraphRAG の回答が得られます。引用をクリックしてグラフを確認できます。

---

🚀 クイックスタート

前提条件： Docker（Compose 対応）。エンドユーザーに必要なのはこれだけです。埋め込みは CPU でローカル実行されます。LLM プロバイダーも必要です。Ollamaを使えば、すべてをデバイス内にとどめられます。

公開済みコンテナを実行する（推奨）

推奨されるインストール方法は、GitHub Container Registry で公開されているオールインワンイメージを使う方法です。

docker run -d --name chaoscypher \
  -p 80:80 \
  -p 443:443 \
  -v chaoscypher-data:/data \
  --add-host=host.docker.internal:host-gateway \
  ghcr.io/chaoscypherinc/chaoscypher:latest

# Then open http://localhost  (443 is published so HTTPS works if you enable TLS)

Compose を使いますか？これを docker-compose.yml として保存し、docker compose up -d を実行してください。

name: chaoscypher
services:
  chaoscypher:
    image: ghcr.io/chaoscypherinc/chaoscypher:latest
    container_name: chaoscypher
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - chaoscypher-data:/data
    extra_hosts:
      # Lets the container reach an Ollama running on the host (Linux engines
      # don't resolve host.docker.internal without this)
      - "host.docker.internal:host-gateway"
    restart: unless-stopped
volumes:
  chaoscypher-data:

イメージは、.github/workflows/publish-ghcr.yml によって、vX.Y.Z のリリースごとにビルドされてプッシュされます。

PyPI から CLI をインストールする

ターミナルを中心に使いますか？スタンドアロン CLI は、pipx（または通常の pip）でインストールできます。

pipx install chaoscypher-cli
chaoscypher setup                 # wizard: pick an LLM provider
chaoscypher source add paper.pdf

4 つの Python パッケージ（chaoscypher-core、-cortex、-neuron、-cli）はすべて、リリースごとに PyPI で公開されます。chaoscypher-core を使えば、同じ抽出・検索エンジンを埋め込み可能なライブラリとして利用できます。開発者向けクイックスタートをご覧ください。

ソースからビルドする（代替方法／開発用）

リポジトリをクローンして、公開済みイメージを使わずにオールインワンイメージをローカルでビルドします。

git clone https://github.com/chaoscypherinc/chaoscypher.git
cd chaoscypher
make docker-up      # builds + starts the all-in-one container
# Open http://localhost

約5分で試す

クイックスタート では詳しく説明しています。インポートと検索は約5分で利用できます。 抽出とチャットは、LLM プロバイダーを設定すると利用可能になります（Ollama の場合は、 モデルを一度ダウンロードする必要があります）。

1. アプリを起動する — 上記のいずれかの方法で起動し、http://localhost を開きます。
2. シングルユーザー用のログインを作成する — 初回起動時のセットアップページで作成します。
3. LLM プロバイダーを選ぶ — 設定で、完全にオフラインで使う場合はローカルの Ollama モデルを指定するか、OpenAI／Anthropic／Gemini の API キーを追加します。
4. ソースを追加する — ドキュメントをアップロードするか、テキストを貼り付けます。Chaos Cypher は バックグラウンドでエンティティと関係を抽出します（Queue Monitor で進行状況を確認できます）。
5. グラフを探索する — ナレッジグラフビューを開いて抽出内容を確認し、横断検索したり、ソースとチャットしたりできます。
6. ナレッジパッケージをエクスポートする — 結果に満足したら、バックアップしたり、別の場所に読み込んだりできるようにエクスポートします。

開発環境のセットアップ（ホットリロード対応）

サービスごとのホットリロードが必要なコントリビューター向けです（Python 3.14+、 Node.js 24+、および uv 0.11+ が必要です。uv は pip の代わりとなり、 コミット済みの uv.lock を読み込みます）。

make install      # First-time setup (packages + hooks + Docker test image)
export QUEUE_PASSWORD="$(openssl rand -base64 32)"  # required by the dev stack
make docker-dev   # Start multi-container dev environment
# Frontend: http://localhost:3000
# Cortex API: http://localhost:8080

---

📦 モノレポの構成

chaoscypher/
├── packages/
│   ├── core/      # 🧠 Core (Brain) - Business logic & domain models
│   ├── cortex/    # 🎛️ Cortex (Processing Center) - Full backend API
│   ├── neuron/    # ⚡ Neuron (Worker Cells) - Background task processing
│   ├── interface/ # 💻 Interface (Interaction Layer) - Web UI
│   ├── cli/       # 🔧 CLI - Command-line tools
│   ├── docker/    # 🐳 Docker - Orchestration
│   └── docs/      # 📚 Docs - Docusaurus documentation site
├── e2e/           # Public end-to-end test suite
├── scripts/       # Public build/test helper scripts
└── tools/         # Public lint/license tooling

---

🛠️ よく使うコマンド

Docker

make docker-up       # Start all-in-one container (http://localhost)
make docker-rebuild  # Rebuild and restart all-in-one
make docker-dev      # Start multi-container dev environment (hot-reload)
make docker-prod     # Start multi-container production (export QUEUE_PASSWORD first)
make docker-down     # Stop all Docker services

ログの表示

# All-in-one
docker logs -f chaoscypher

# Multi-container (the compose file requires QUEUE_PASSWORD for every subcommand)
docker logs -f chaoscypher-cortex

テスト

make docker-test     # Run tests in Docker (isolated)
make lint            # Python + frontend lint (make ci runs the full linter suite)
make ci              # Full CI pipeline

個別パッケージ

cc-cortex start              # Backend API
cc-neuron                    # Unified worker
cd packages/interface && npm run dev  # Frontend UI
chaoscypher --help           # CLI

---

📖 ドキュメント

• 公開ドキュメントサイト - ユーザー向けおよび開発者向けの完全なドキュメント
• コントリビューターガイド - コントリビューションのワークフロー、PR チェックリスト、レビュー時の確認事項
• AI コントリビューターガイド - AI コーディングアシスタント向けの公開ガイダンス
• コアアーキテクチャ - ヘキサゴナルアーキテクチャの詳細
• ドキュメントのソース - Docusaurus ドキュメントサイトのソース
• アーキテクチャ決定記録 - 公開 ADR
• セルフホスト時の脅威モデル - ローカルに保持されるデータと、公開範囲を安全にする方法

ドキュメントサイト（Docusaurus）

cd packages/docs && npm run build    # Build static site
cd packages/docs && npm start        # Dev server (http://localhost:3000)

---

🏗️ アーキテクチャの概要

Chaos Cypher は脳をイメージしたメタファーを用いて構成されており、 各パッケージがそれぞれ専門的な役割を担います。

┌─────────────────────────────────────────────────────────────┐
│                      Interface (UI)                          │
│                  React + TypeScript + Vite                   │
└─────────────────────────┬───────────────────────────────────┘
                          │
                 ┌────────▼────────┐
                 │  Cortex (API)   │
                 │  FastAPI + VSA  │
                 └────────┬────────┘
                          │
                 ┌────────▼────────┐
                 │   Core (Brain)  │
                 │    Hexagonal    │
                 └────────┬────────┘
                          │
           ┌──────────────┼──────────────┐
  ┌────────▼────────┐    │    ┌────────▼────────┐
  │ Neuron LLM      │    │    │ Neuron Ops      │
  │ (1 concurrent)  │    │    │ (8 concurrent)  │
  └─────────────────┘    │    └─────────────────┘
                         │
                ┌────────▼────────┐
                │ Storage Adapters│
                │ SQLite / Files  │
                └─────────────────┘

• 🧠 Core (packages/core/) — フレームワークに依存しないビジネスロジック（ヘキサゴナルアーキテクチャ）
• 🎛️ Cortex (packages/cortex/) — 垂直スライスアーキテクチャを採用した FastAPI バックエンド
• ⚡ Neuron (packages/neuron/) — LLM 処理と運用処理を担うバックグラウンドワーカー
• 💻 Interface (packages/interface/) — React + TypeScript のウェブ UI
• 🔧 CLI (packages/cli/) — 単独で使用できるコマンドラインインターフェース
• 🐳 Docker (packages/docker/) — オーケストレーション（docker-compose ファイル）

簡単に言うと： UI は単一の API と通信し、API は実処理をすべてフレームワークに依存しない コアに委譲します。また、時間のかかるジョブ（抽出、エクスポート）はバックグラウンドワーカーで実行するため、 アプリの応答性が保たれます。

垂直スライスアーキテクチャ（Cortex バックエンド）

機能は、API → Service → Repository → Database までの完全な機能を備えた自己完結型の垂直スライスとして構成されています。

packages/cortex/src/chaoscypher_cortex/features/{feature}/
├── __init__.py        # Barrel exports
├── models.py          # Pydantic DTOs (Request/Response)
├── repository.py      # Data access (SQLModel entities) — only where the slice owns tables; most delegate to Core
├── service.py         # Business logic
└── api.py             # REST endpoints + factory DI

ヘキサゴナルアーキテクチャ（コアライブラリ）

packages/core/ ライブラリでは、柔軟性と再利用性を最大限に高めるため、ヘキサゴナルアーキテクチャを採用しています。

• ポート： プロトコル定義（契約）
• アダプター： ストレージの実装（SQLite、ファイル、LLM、ウェブ）
• サービス： ビジネスロジック（フレームワークに非依存）
• リポジトリ： ストレージアダプターを使用するドメインリポジトリ

キューシステム

1つの統合された Neuron ワーカーが、両方のキューを処理します。

• LLM キュー（デフォルトで同時実行数は1。有効化された Ollama インスタンスごとに1つ） - チャット、埋め込み、エンティティ抽出、ツールからの LLM 呼び出し
• Operations キュー（同時実行数は8） - ソース処理、エクスポート、ワークフロー

モニター： http://localhost/queues （オールインワン。開発スタック： http://localhost:3000/queues）

---

🔄 開発ワークフロー

# Make changes in any package
cd packages/cortex
# Edit code...

# Changes are immediately available (editable install)
# If using Docker, hot-reload will restart services

# Run tests
uv run pytest packages/*/tests --import-mode=importlib   # or: make test

# Commit changes (Conventional Commits — see CONTRIBUTING.md)
git add .
git commit -m "feat(cortex): add new feature"
git push

---

🤝 コントリビューション

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更を加え、テストを追加します
4. すべてのテストが成功することを確認します
5. Conventional Commits に従って変更をコミットします（git commit -m 'feat(scope): add amazing feature'）
6. ブランチにプッシュします（git push origin feature/amazing-feature）
7. プルリクエストを作成します

---

💬 コミュニティとサポート

• 質問、アイデア、成果の共有 → GitHub Discussions
• バグや機能リクエスト → Issue Tracker
• 最新情報 → Blog · Changelog · Roadmap

Chaos Cypher が役に立った場合、リポジトリに ⭐ を付けていただけると、ほかの セルフホスト利用者が見つけやすくなります。

---

📄 ライセンス

Chaos Cypher は GNU Affero General Public License v3.0 only (AGPL-3.0-only) の下でライセンスされています。ルートの LICENSE ファイルをご確認ください。別途、 プロプライエタリなエンタープライズ版も利用できます。外部からのコントリビューションは、プロジェクトの CLA に基づいて受け付けています。

---

🔗 リンク

• 公開ドキュメントサイト
• ブログ
• ドキュメントのソース
• GitHub Discussions
• Issue Tracker
• コントリビューターガイド
• AI コントリビューターガイド