ZengLiangYi/ChatCrystal

**Local-first AI PKM for coding conversations**
Website ·
Download Desktop ·
npm ·
Docs ·
简体中文
---
ChatCrystal is a local-first AI PKM app for developers who solve real problems with Claude Code, Cursor, Codex CLI, Trae, and GitHub Copilot.
It turns scattered AI coding conversations into structured notes, semantic search, a tag knowledge graph, Markdown exports, and MCP memory your agents can reuse. If this fits your workflow, a star helps more builders find a private, local-first way to keep their AI work memory.
Quick Start
Desktop App (Recommended)
Download the latest Windows installer from GitHub Releases. After installing, launch ChatCrystal, configure your LLM and embedding providers in Settings, then click **Import**.
CLI / Web
Then open http://localhost:3721 in your browser.
Docker Cloud
Prefer self-hosting ChatCrystal for multiple devices? See Docker Cloud Deployment after the product overview.
What It Does
- **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 tag knowledge graph** where knowledge points are tags and edges show normalized co-occurrence.
- **Exposes CLI and MCP tools** so agents can recall and write back reusable experience.
- **Runs locally** with configurable LLM and embedding providers.
Screenshots
Conversations
Notes
Semantic Search
Knowledge Graph
Common Commands
Documentation
| Topic | English | 简体中文 |
|---|---|---|
| User guide | docs/USER_GUIDE.md | docs/USER_GUIDE.zh-CN.md |
| Development | docs/DEVELOPMENT.md | docs/DEVELOPMENT.zh-CN.md |
| MCP and agents | docs/MCP.md | docs/MCP.zh-CN.md |
| Experience quality gate | docs/EXPERIENCE_GATE.md | docs/EXPERIENCE_GATE.zh-CN.md |
| Agent skills | docs/agent-skills.md | docs/agent-skills.zh-CN.md |
Requirements
- Node.js >= 24
- 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.
ChatCrystal includes first-class OrcaRouter support for LLM generation. OrcaRouter is OpenAI-compatible; its Base URL is built in, so enter only your API Key and use **Settings** to fetch and select an available model.
Local Development
Development server ports:
- API/server: http://localhost:3721
- Vite client: http://localhost:13721
See docs/DEVELOPMENT.md for architecture, testing, build, and release details.
Docker Cloud Deployment
The default Compose deployment runs only the ChatCrystal service. It stores data in the chatcrystal-data volume mounted at /data inside the container.
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.