ChatCrystal

---

ChatCrystal は、AI コーディングツール（Claude Code、Cursor、Codex CLI、Trae、GitHub Copilot）との会話を収集し、LLM を使って検索可能な構造化ノートにまとめ、個人用ナレッジベースを構築します。

インストール

npm install -g chatcrystal

Node.js >= 20 と LLM サービス（Ollama、OpenAI、OrcaRouter、Anthropic、Google AI、または OpenAI 互換 API）が必要です。

クイックスタート

crystal import                     # Scan and import AI conversations
crystal summarize --all            # Batch summarize into notes
crystal search "React state"       # Semantic search your knowledge

最初のコマンドを実行すると、サーバーがバックグラウンドで自動起動します。手動でのセットアップは不要です。

クラウド接続

Docker のクラウドインスタンスを使用する場合、共有トークンを一度保存します。

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

crystal import は引き続きローカルデバイス上の履歴をスキャンして解析し、正規化した会話をクラウドインスタンスにアップロードします。クラウドサーバーがローカルのファイルシステムをスキャンすることはありません。crystal mcp は保存済みの接続情報とトークンを再利用します。

クラウド接続には HTTPS を推奨しますが、選択したデプロイ方法で HTTP を使用する場合は HTTP も利用できます。

Docker クラウドトークンを管理するには：

# Rotate when you still know the current token.
crystal --base-url https://chatcrystal.example.com token rotate "new-long-token-at-least-16-chars" --current "old-token"

# Reset stored auth from the Docker host when the token is lost.
docker compose exec chatcrystal crystal token reset --yes
docker compose exec chatcrystal cat /data/setup-code

デプロイ環境で CHATCRYSTAL_API_TOKEN が設定されている場合は、token reset を使うのではなく、その環境変数を変更してコンテナを再作成してください。

CLI コマンド

# Knowledge retrieval
crystal search <query> [--limit 10]     # Semantic search
crystal notes list [--tag X]            # Browse notes
crystal notes get <id>                  # View note detail
crystal notes relations <id>            # View note relations
crystal tags                            # List tags with counts

# Data management
crystal import [--source claude-code]   # Import conversations
crystal summarize <id>                  # Summarize one conversation
crystal summarize --all                 # Batch summarize
crystal summarize --retry-errors        # Retry failed summaries
crystal status                          # Server status and DB stats

# Configuration
crystal config get                      # View config
crystal config set llm.provider openai  # Update config
crystal config test                     # Test LLM connection

# Server management
crystal serve                           # Start server (foreground)
crystal serve -d                        # Start server (daemon)
crystal serve stop                      # Stop daemon
crystal serve status                    # Check if running

グローバルオプション： --base-url <url>（サーバーアドレス）、--token <token>（クラウド API トークン）、--json（JSON 出力を強制）、--version

出力： TTY を認識して出力します。ターミナルでは色付きの表を表示し、パイプに渡す場合は JSON を出力します。

MCP サーバー

AI コーディングツールと連携すると、コーディング中に会話履歴から知識を取得できます。

crystal mcp                             # Start MCP stdio server

Claude Code

settings.json に追加します。

{
  "mcpServers": {
    "chatcrystal": {
      "command": "crystal",
      "args": ["mcp"]
    }
  }
}

MCP ツール

ツール	説明
search_knowledge	関連度順の検索結果が必要な場合に、ノートを対象にセマンティック検索します
get_note	ノートの内容全体（要約、結論、コードスニペット）を取得します
list_notes	タグまたはタイトル／要約のキーワードで、ページ分割されたノートの要約を閲覧します
get_relations	関連タイプ付きで関連ノートを取得します
recall_for_task	プロジェクトの記憶を先に読み込み、続けて必要に応じて全体の教訓を読み込む、読み取り専用のタスク記憶機能です
validate_task_memory	タスクの記憶を書き込む前にドライランで検証します。受け入れ可否、理由、警告、ノートのフィールドを返します
write_task_memory	有意義な作業の後に、再利用可能なタスクの記憶を保存します

設定

実行時設定は、アクティブなデータディレクトリ内の config.json に保存されます。CLI、MCP、リポジトリ／開発用チェックアウト、npm のグローバルインストール、Electron では、デフォルトで ~/.chatcrystal/data を使用します。設定を永続化するには crystal config set を使用してください。.env は任意のローカル上書きレイヤーとしてのみ引き続き利用できます。

# LLM (ollama/openai/orcarouter/anthropic/google/azure/custom)
crystal config set llm.provider openai
crystal config set llm.model gpt-4o
crystal config set llm.apiKey sk-...

# Embedding (ollama/openai/google/azure/custom)
crystal config set embedding.provider ollama
crystal config set embedding.model nomic-embed-text

OrcaRouter は ChatCrystal に組み込まれた Base URL https://api.orcarouter.ai/v1 を使用します。llm.provider を orcarouter に設定し、API Key を指定して、Web UI で検出されたモデルを選択してください。llm.baseURL の設定は不要です。OrcaRouter API Key を取得。

データソース

以下のソースを自動的に検出してインポートします。

ソース	パス
Claude Code	~/.claude/projects/**/*.jsonl
Codex CLI	~/.codex/sessions/**/*.jsonl
Cursor	プラットフォーム固有の state.vscdb
Trae	プラットフォーム固有の state.vscdb
GitHub Copilot	VS Code の chatSessions/*.jsonl / *.json

Web UI とデスクトップアプリ

ChatCrystal には Web UI と Electron デスクトップアプリもあります。詳細については、GitHub リポジトリをご覧ください。

ライセンス

Apache License 2.0