ChatCrystal

Turn your AI conversations into searchable knowledge

English | 简体中文

ChatCrystal collects conversations from AI coding tools, distills them into structured notes with LLMs, and builds a local searchable knowledge base from your real problem-solving history.

Supported sources: Claude Code, Cursor, Codex CLI, Trae, and GitHub Copilot.

Download the latest Windows installer from GitHub Releases. After installing, launch ChatCrystal, configure your LLM and embedding providers in Settings, then click Import.

npm install -g chatcrystal
crystal serve -d
crystal import

Then open http://localhost:3721 in your browser.

The default Compose deployment runs only the ChatCrystal service. It stores data in the chatcrystal-data volume mounted at /data inside the container.

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

The default docker-compose.yml pulls ghcr.io/zengliangyi/chatcrystal:latest from GitHub Container Registry. Set CHATCRYSTAL_IMAGE_TAG to pin a published version. To build from source instead, run docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build.

To update an existing Docker deployment, run docker compose pull && docker compose up -d. Maintainers only: after the first GHCR publish, make the ghcr.io/zengliangyi/chatcrystal package public in GitHub Packages; the release workflow verifies anonymous pull access before passing.

Compose binds ChatCrystal to 127.0.0.1:3721 by default. Set CHATCRYSTAL_HOST_PORT to change the host port. For public cloud access, an HTTPS reverse proxy is recommended for safer token transport.

On first start without CHATCRYSTAL_API_TOKEN, open the Web UI and enter the setup code printed in container logs or stored at /data/setup-code, then choose one shared API token for your devices.

To rotate or reset the Docker cloud token:

# 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

If your deployment sets CHATCRYSTAL_API_TOKEN, that environment variable is the active token source. Change it in your .env or Compose environment and recreate the container with docker compose up -d --force-recreate.

To use an existing Ollama or external API, configure provider URLs in the Web UI or environment. In Docker, localhost means inside the container; use CHATCRYSTAL_DOCKER_LLM_BASE_URL and CHATCRYSTAL_DOCKER_EMBEDDING_BASE_URL for Compose-time provider URL overrides. Docker Desktop can reach host Ollama at http://host.docker.internal:11434, or you can use a remote HTTPS/OpenAI-compatible API.

Install or run the CLI on the device that has Claude Code, Cursor, Codex CLI, Trae, or GitHub Copilot history:

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

The CLI scans local histories, parses them locally, and uploads normalized conversations to the cloud. The cloud never scans your local filesystem. Imported conversations are not summarized automatically; use the Web UI or crystal summarize --all when you are ready. HTTPS is recommended for cloud access, but HTTP works when that is the deployment you choose.

• Imports AI coding conversations from local tool data directories.
• Distills conversations into structured notes with titles, summaries, conclusions, snippets, and tags.
• Searches knowledge semantically with embeddings and relation-aware result expansion.
• Builds a knowledge graph across related notes and decisions.
• Exposes CLI and MCP tools so agents can recall and write back reusable experience.
• Runs locally with configurable LLM and embedding providers.

Conversations	Notes
Semantic Search	Knowledge Graph

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

• Node.js >= 20
• An LLM provider for summarization
• An embedding provider for semantic search

LLM and embedding providers are configured separately. Large language models such as Claude, GPT, and Qwen are not embedding models. See the user guide for provider examples.

git clone https://github.com/ZengLiangYi/ChatCrystal.git
cd ChatCrystal
npm install
npm run dev

Development server ports:

• API/server: http://localhost:3721
• Vite client: http://localhost:13721

See docs/DEVELOPMENT.md for architecture, testing, build, and release details.

Wechat: Yizel1

Apache License 2.0