Chatcrystal

What is ChatCrystal?

ChatCrystal collects conversations from AI coding tools (Claude Code, Cursor, Codex CLI, Trae, GitHub Copilot), distills them into structured notes using LLMs, and builds a local searchable knowledge base from your real problem-solving history. It is for developers who want to turn AI-assisted coding conversations into reusable knowledge.

How to use ChatCrystal?

Install the Windows desktop app from GitHub Releases, or run npm install -g chatcrystal and use crystal serve -d plus crystal import to start a CLI/Web server at http://localhost:3721. For a Docker cloud deployment, clone the repo and run docker compose up -d. Configure an LLM provider and an embedding provider in Settings, then import conversations from supported tools.

Key features of ChatCrystal

• Imports AI coding conversations from local tool data directories.
• Distills conversations into structured notes with titles, summaries, and tags.
• Searches knowledge semantically with embeddings and relation-aware results.
• Builds a knowledge graph across related notes and decisions.
• Exposes both CLI and MCP tools for agent recall and write-back.
• Runs locally with configurable LLM and embedding providers.

Use cases of ChatCrystal

• Turning Claude Code or Cursor chat logs into a searchable personal knowledge base.
• Reusing past solutions by semantically searching for similar problems.
• Building a knowledge graph to visualize relationships between coding decisions.
• Using MCP tools to let AI agents recall and contribute to experience notes.
• Synchronizing conversation history from multiple devices to a self-hosted cloud instance.

FAQ from ChatCrystal

What data does ChatCrystal store and where?

It stores normalized conversations and structured notes locally. In the Docker cloud deployment, data lives in the chatcrystal-data volume at /data inside the container. The CLI scans local histories, parses them locally, and uploads normalized conversations to the cloud—the cloud never scans the local filesystem.

What are the runtime requirements?

Node.js >=20 is required. You also need an LLM provider for summarization and an embedding provider for semantic search. Large language models and embedding models are configured separately.

How does authentication work?

In Docker cloud, on first start without CHATCRYSTAL_API_TOKEN, you enter a setup code from container logs via the Web UI and choose a shared API token. The token can be rotated using crystal token rotate. If CHATCRYSTAL_API_TOKEN is set, it overrides stored auth.

Can ChatCrystal be used with MCP agents?

Yes. Run crystal mcp to start the MCP stdio server. See docs/MCP.md for more details.

Does ChatCrystal support multiple AI coding tools?

Yes. Supported sources include Claude Code, Cursor, Codex CLI, Trae, and GitHub Copilot. You import from a device using crystal import or the desktop app.