ZENGLIANGYI

---

ChatCrystal は、Claude Code、Cursor、Codex CLI、Trae、GitHub Copilot を使って実際の問題を解決する開発者向けの、ローカルファーストな AI PKM アプリです。

散在する AI コーディングの会話を、構造化されたノート、セマンティック検索、タグナレッジグラフ、Markdown エクスポート、エージェントが再利用できる MCP メモリに変換します。このアプリがワークフローに合っていると感じたら、スターを付けていただくと、AI の作業記録をプライベートかつローカルファーストに管理する方法を、より多くの開発者に知ってもらう助けになります。

クイックスタート

デスクトップアプリ（推奨）

最新の Windows インストーラーをGitHub Releasesからダウンロードします。インストール後に ChatCrystal を起動し、設定で LLM と埋め込みプロバイダーを構成してから、Import をクリックします。

CLI／ウェブ

npm install -g chatcrystal
crystal serve -d
crystal import

次に、ブラウザーで http://localhost:3721 を開きます。

Docker Cloud

複数のデバイスで使うために ChatCrystal をセルフホストしたい場合は、製品の概要の後にあるDocker Cloud のデプロイをご覧ください。

機能

• AI コーディングの会話をインポート：ローカルのツールデータディレクトリから会話をインポートします。
• 会話を構造化されたノートに整理：タイトル、要約、結論、スニペット、タグを付けます。
• 知識を意味的に検索：埋め込みと、関連性を考慮した検索結果の拡張を行います。
• タグナレッジグラフを構築：知識のポイントをタグとして表し、エッジで正規化された共起関係を示します。
• CLI と MCP ツールを提供：エージェントが再利用可能な知見を呼び出し、書き戻せるようにします。
• ローカルで実行：LLM と埋め込みプロバイダーを設定できます。

スクリーンショット

よく使うコマンド

crystal status                          # Server status and DB stats
crystal import [--source claude-code]   # Scan and import conversations
crystal search "query" [--limit 10]     # Semantic search
crystal notes list [--tag X]            # Browse notes
crystal notes get <id>                  # View note detail
crystal summarize --all                 # Batch summarize
crystal config get                      # View config
crystal serve -d                        # Start server in background
crystal serve stop                      # Stop background server
crystal mcp                             # Start MCP stdio server

ドキュメント

トピック	英語	簡体字中国語
ユーザーガイド	docs/USER_GUIDE.md	docs/USER_GUIDE.zh-CN.md
開発	docs/DEVELOPMENT.md	docs/DEVELOPMENT.zh-CN.md
MCP とエージェント	docs/MCP.md	docs/MCP.zh-CN.md
エクスペリエンス品質ゲート	docs/EXPERIENCE_GATE.md	docs/EXPERIENCE_GATE.zh-CN.md
エージェントスキル	docs/agent-skills.md	docs/agent-skills.zh-CN.md

アーキテクチャと技術的な詳細

エンジニアリングに関する議論、データプライバシーの境界、ChatCrystal の設計上の決定については、以下の記事をご覧ください。

• アーキテクチャとプライバシーの境界
  • ローカルファーストとクラウド AI：データ境界を理解する
  • RAG からナレッジグラフへ：検索で関係性を保持する
• ローカル検索とベクトルエンジニアリング
  • 埋め込みを設定する：検索サンプルに基づいて選択し、再構築を検証する
  • ローカルベクトルストアの選択：Vectra、Chroma、hnswlib
• 会話の解析とプロトコル統合
  • 複数形式の会話解析：JSONL、イベント、SQLite の読み取り境界
  • ChatCrystal MCP のセットアップ：Claude Code の呼び出しをレビュー可能にする
  • AI エージェント向けナレッジベース：想起、検証、書き戻し

要件

• Node.js >= 24
• 要約用の LLM プロバイダー
• セマンティック検索用の埋め込みプロバイダー

LLM プロバイダーと埋め込みプロバイダーは個別に設定します。Claude、GPT、Qwen などの大規模言語モデルは、埋め込みモデルではありません。プロバイダーの例については、ユーザーガイドをご覧ください。

ChatCrystal は、LLM による生成において OrcaRouter を標準でサポートしています。OrcaRouter は OpenAI 互換で、ベース URL は組み込み済みです。そのため、API キーのみを入力し、Settings を使用して利用可能なモデルを取得・選択してください。

ローカル開発

git clone https://github.com/ZengLiangYi/ChatCrystal.git
cd ChatCrystal
corepack enable
pnpm install
pnpm dev

開発サーバーのポート：

• API／サーバー：http://localhost:3721
• Vite クライアント：http://localhost:13721

アーキテクチャ、テスト、ビルド、リリースの詳細については、docs/DEVELOPMENT.mdをご覧ください。

Docker クラウドデプロイ

デフォルトの Compose デプロイでは、ChatCrystal サービスのみが実行されます。データは、コンテナ内の /data にマウントされる chatcrystal-data ボリュームに保存されます。

git clone https://github.com/ZengLiangYi/ChatCrystal.git
cd ChatCrystal
docker compose up -d

デフォルトの docker-compose.yml は、GitHub Container Registry から ghcr.io/zengliangyi/chatcrystal:latest を取得します。公開済みのバージョンに固定するには、CHATCRYSTAL_IMAGE_TAG を設定します。代わりにソースからビルドする場合は、docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build を実行します。

既存の Docker デプロイを更新するには、docker compose pull && docker compose up -d を実行します。メンテナーのみ：初回の GHCR への公開後、GitHub Packages で ghcr.io/zengliangyi/chatcrystal パッケージを公開設定にしてください。リリースワークフローでは、匿名でのプルが可能であることを確認してから処理を続行します。

Compose はデフォルトで ChatCrystal を 0.0.0.0:3721 にバインドするため、ほかのデバイスからホスト IP 経由でクラウドコアにアクセスできます。ホストポートを変更するには CHATCRYSTAL_HOST_PORT を設定します。または、ローカル専用のリバースプロキシを前段に置く場合は、BIND_ADDRESS=127.0.0.1 を設定します。パブリッククラウドからアクセスする場合は、トークンをより安全に転送するため、HTTPS リバースプロキシの使用をおすすめします。

Windows Docker Desktop では、公開したポートにホストの LAN IP 経由でアクセスするために、追加のホストネットワーク設定が必要になる場合があります。クラウドモードのテストでは、まずクライアントデバイスから http://<host-ip>:<host-port>/api/health にアクセスできることを確認してください。接続できない場合は、Windows のポート転送やファイアウォールのルールを設定するか、クラウドコアを実際のリモートホストにデプロイしてください。

CHATCRYSTAL_API_TOKEN を設定せずに初回起動した場合は、Web UI を開き、コンテナログに出力されるか /data/setup-code に保存されているセットアップコードを入力してから、デバイス間で共有する API トークンを 1 つ選択します。

Docker クラウドのトークンをローテーションまたはリセットするには：

# If you still know the current token, rotate it online.
crystal --base-url https://chatcrystal.example.com token rotate "new-long-token-at-least-16-chars" --current "old-token"
crystal connect https://chatcrystal.example.com --token "new-long-token-at-least-16-chars"

# If you forgot the token and did not set CHATCRYSTAL_API_TOKEN, reset stored auth in the container.
docker compose exec chatcrystal crystal token reset --yes
docker compose logs chatcrystal --tail=80
docker compose exec chatcrystal cat /data/setup-code

デプロイで CHATCRYSTAL_API_TOKEN を設定している場合、その環境変数が有効なトークンのソースです。.env または Compose 環境変数で値を変更し、docker compose up -d --force-recreate でコンテナを再作成してください。

既存の Ollama や外部 API を使用するには、Web UI または環境変数でプロバイダーの URL を設定します。Docker 内では、localhost はコンテナ内を指します。Compose 実行時にプロバイダー URL を上書きするには、CHATCRYSTAL_DOCKER_LLM_BASE_URL と CHATCRYSTAL_DOCKER_EMBEDDING_BASE_URL を使用してください。Docker Desktop からホスト上の Ollama にアクセスするには http://host.docker.internal:11434 を使用できます。または、リモートの HTTPS／OpenAI 互換 API を使用できます。

デバイスからクラウドインスタンスにインポートする

Claude Code、Cursor、Codex CLI、Trae、または GitHub Copilot の履歴があるデバイスに CLI をインストールするか、実行してください：

crystal connect https://chatcrystal.example.com --token "your-long-token"
crystal import --yes

CLI はローカルの履歴をスキャンしてローカルで解析し、正規化された会話をクラウドにアップロードします。クラウドがローカルのファイルシステムをスキャンすることはありません。インポートした会話は自動では要約されません。準備ができたら、Web UI または crystal summarize --all を使用してください。クラウドへのアクセスには HTTPS をおすすめしますが、選択したデプロイ構成が HTTP の場合は HTTP も使用できます。

お問い合わせ

ライセンス

Apache License 2.0