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 <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

Global options: --base-url <url> (server address), --token <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

Tool	Description
search_knowledge	Semantic search across notes when you need relevance-ranked matches
get_note	Get full note content (summary, conclusions, code snippets)
list_notes	Browse paginated note summaries by tag or title/summary keyword
get_relations	Get related notes with relationship types
recall_for_task	Read-only task recall that loads project memories first, then optional global lessons
validate_task_memory	Dry-run validation before writing a task memory; returns acceptance, reasons, warnings, and note fields
write_task_memory	Persist reusable task memories after meaningful work

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:

Source	Path
Claude Code	~/.claude/projects/**/*.jsonl
Codex CLI	~/.codex/sessions/**/*.jsonl
Cursor	Platform-specific state.vscdb
Trae	Platform-specific state.vscdb
GitHub Copilot	VS Code chatSessions/*.jsonl / *.json

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