ChatCrystal

ChatCrystal

Crystallize knowledge from your AI conversations

ChatCrystal collects conversations from AI coding tools (Claude Code, Cursor, Codex CLI, Trae, GitHub Copilot), uses LLM to distill them into searchable structured notes, and builds your personal knowledge base.

Install

npm install -g chatcrystal

Requires Node.js >= 20 and an LLM service (Ollama, OpenAI, OrcaRouter, Anthropic, Google AI, or any OpenAI-compatible API).

Quick Start

crystal import                     # Scan and import AI conversations

crystal summarize --all # Batch summarize into notes crystal search "React state" # Semantic search your knowledge

The server auto-launches in background on first command. No manual setup needed.

Cloud Connection

For a Docker cloud instance, save the shared token once:

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

crystal import --yes

crystal import still scans and parses histories on the local device, then uploads normalized conversations to the cloud instance. The cloud server does not scan your local filesystem. crystal mcp reuses the same saved connection and token.

HTTPS is recommended for cloud connections, but HTTP works when that is the deployment you choose.

To manage a Docker cloud token:

# 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

If CHATCRYSTAL_API_TOKEN is set in the deployment environment, change that environment variable and recreate the container instead of using token reset.

CLI Commands

# Knowledge retrieval

crystal search [--limit 10] # Semantic search crystal notes list [--tag X] # Browse notes crystal notes get # View note detail crystal notes relations # View note relations crystal tags # List tags with counts

Data management

crystal import [--source claude-code] # Import conversations crystal summarize # 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

Global options: --base-url (server address), --token (cloud API token), --json (force JSON output), --version

Output: TTY-aware — colored tables in terminal, JSON when piped.

MCP Server

Integrate with AI coding tools so they can retrieve knowledge from your conversation history during coding.

crystal mcp                             # Start MCP stdio server

Claude Code

Add to settings.json:

{

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

MCP Tools

Configuration

Runtime configuration is stored in config.json under the active data directory. CLI, MCP, repo/dev checkouts, npm global installs, and Electron default to ~/.chatcrystal/data. Use crystal config set for persistent config. .env remains available only as an optional local override layer.

# 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 uses ChatCrystal's built-in https://api.orcarouter.ai/v1 Base URL. Set llm.provider to orcarouter, provide an API Key, and select a discovered model in the Web UI; no llm.baseURL is required. Get an OrcaRouter API Key.

Data Sources

Automatically detects and imports from:

Web UI & Desktop App

ChatCrystal also has a web UI and Electron desktop app. See the GitHub repository for details.

License

Apache License 2.0