{
  "markdown": "<div align=\"center\">\n\n<img src=\"electron/icon.png\" alt=\"ChatCrystal\" width=\"120\" />\n\n# ChatCrystal\n\n**Local-first AI PKM for coding conversations**\n\n[![GitHub release](https://img.shields.io/github/v/release/ZengLiangYi/ChatCrystal?style=flat-square)](https://github.com/ZengLiangYi/ChatCrystal/releases)\n[![npm](https://img.shields.io/npm/v/chatcrystal?style=flat-square)](https://www.npmjs.com/package/chatcrystal)\n[![ChatCrystal MCP server](https://glama.ai/mcp/servers/ZengLiangYi/ChatCrystal/badges/score.svg)](https://glama.ai/mcp/servers/ZengLiangYi/ChatCrystal)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square)](LICENSE)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D24-brightgreen?style=flat-square)](https://nodejs.org/)\n[![Platform](https://img.shields.io/badge/platform-Windows-lightgrey?style=flat-square)](#)\n[![Website](https://img.shields.io/badge/website-ChatCrystal-B8584B?style=flat-square)](https://zengliangyi.github.io/ChatCrystal/)\n\n[Website](https://zengliangyi.github.io/ChatCrystal/) ·\n[Download Desktop](https://github.com/ZengLiangYi/ChatCrystal/releases) ·\n[npm](https://www.npmjs.com/package/chatcrystal) ·\n[Docs](docs/USER_GUIDE.md) ·\n[简体中文](README.zh-CN.md)\n\n</div>\n\n---\n\n<div align=\"center\">\n<img src=\"docs/demo.webp\" alt=\"ChatCrystal Demo\" width=\"800\" />\n</div>\n\n<br>\n\nChatCrystal is a local-first AI PKM app for developers who solve real problems with Claude Code, Cursor, Codex CLI, Trae, and GitHub Copilot.\n\nIt 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.\n\n## Quick Start\n\n### Desktop App (Recommended)\n\nDownload the latest Windows installer from [GitHub Releases](https://github.com/ZengLiangYi/ChatCrystal/releases). After installing, launch ChatCrystal, configure your LLM and embedding providers in Settings, then click **Import**.\n\n### CLI / Web\n\n```bash\nnpm install -g chatcrystal\ncrystal serve -d\ncrystal import\n```\n\nThen open http://localhost:3721 in your browser.\n\n### Docker Cloud\n\nPrefer self-hosting ChatCrystal for multiple devices? See [Docker Cloud Deployment](#docker-cloud-deployment) after the product overview.\n\n## What It Does\n\n- **Imports AI coding conversations** from local tool data directories.\n- **Distills conversations into structured notes** with titles, summaries, conclusions, snippets, and tags.\n- **Searches knowledge semantically** with embeddings and relation-aware result expansion.\n- **Builds a tag knowledge graph** where knowledge points are tags and edges show normalized co-occurrence.\n- **Exposes CLI and MCP tools** so agents can recall and write back reusable experience.\n- **Runs locally** with configurable LLM and embedding providers.\n\n## Screenshots\n\n<div align=\"center\">\n<table>\n<tr>\n<td align=\"center\"><strong>Conversations</strong></td>\n<td align=\"center\"><strong>Notes</strong></td>\n</tr>\n<tr>\n<td><img src=\"docs/screenshots/en/conversations.png\" alt=\"Conversations\" width=\"400\" /></td>\n<td><img src=\"docs/screenshots/en/notes.png\" alt=\"Notes\" width=\"400\" /></td>\n</tr>\n<tr>\n<td align=\"center\"><strong>Semantic Search</strong></td>\n<td align=\"center\"><strong>Knowledge Graph</strong></td>\n</tr>\n<tr>\n<td><img src=\"docs/screenshots/en/search.png\" alt=\"Semantic Search\" width=\"400\" /></td>\n<td><img src=\"docs/screenshots/en/graph.png\" alt=\"Knowledge Graph\" width=\"400\" /></td>\n</tr>\n</table>\n</div>\n\n## Common Commands\n\n```bash\ncrystal status                          # Server status and DB stats\ncrystal import [--source claude-code]   # Scan and import conversations\ncrystal search \"query\" [--limit 10]     # Semantic search\ncrystal notes list [--tag X]            # Browse notes\ncrystal notes get <id>                  # View note detail\ncrystal summarize --all                 # Batch summarize\ncrystal config get                      # View config\ncrystal serve -d                        # Start server in background\ncrystal serve stop                      # Stop background server\ncrystal mcp                             # Start MCP stdio server\n```\n\n## Documentation\n\n| Topic | English | 简体中文 |\n|---|---|---|\n| User guide | [docs/USER_GUIDE.md](docs/USER_GUIDE.md) | [docs/USER_GUIDE.zh-CN.md](docs/USER_GUIDE.zh-CN.md) |\n| Development | [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | [docs/DEVELOPMENT.zh-CN.md](docs/DEVELOPMENT.zh-CN.md) |\n| MCP and agents | [docs/MCP.md](docs/MCP.md) | [docs/MCP.zh-CN.md](docs/MCP.zh-CN.md) |\n| Experience quality gate | [docs/EXPERIENCE_GATE.md](docs/EXPERIENCE_GATE.md) | [docs/EXPERIENCE_GATE.zh-CN.md](docs/EXPERIENCE_GATE.zh-CN.md) |\n| Agent skills | [docs/agent-skills.md](docs/agent-skills.md) | [docs/agent-skills.zh-CN.md](docs/agent-skills.zh-CN.md) |\n\n## Requirements\n\n- Node.js >= 24\n- An LLM provider for summarization\n- An embedding provider for semantic search\n\nLLM and embedding providers are configured separately. Large language models such as Claude, GPT, and Qwen are not embedding models. See the [user guide](docs/USER_GUIDE.md#configuration) for provider examples.\n\nChatCrystal includes first-class [OrcaRouter](https://www.orcarouter.ai/ref/ref_67516d927343232775e2) 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.\n\n## Local Development\n\n```bash\ngit clone https://github.com/ZengLiangYi/ChatCrystal.git\ncd ChatCrystal\ncorepack enable\npnpm install\npnpm dev\n```\n\nDevelopment server ports:\n\n- API/server: http://localhost:3721\n- Vite client: http://localhost:13721\n\nSee [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for architecture, testing, build, and release details.\n\n## Docker Cloud Deployment\n\nThe default Compose deployment runs only the ChatCrystal service. It stores data in the `chatcrystal-data` volume mounted at `/data` inside the container.\n\n```bash\ngit clone https://github.com/ZengLiangYi/ChatCrystal.git\ncd ChatCrystal\ndocker compose up -d\n```\n\nThe 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`.\n\nTo 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.\n\nCompose binds ChatCrystal to `0.0.0.0:3721` by default so other devices can reach the cloud core through the host IP. Set `CHATCRYSTAL_HOST_PORT` to change the host port, or set `BIND_ADDRESS=127.0.0.1` when a local-only reverse proxy fronts it. For public cloud access, an HTTPS reverse proxy is recommended for safer token transport.\n\nOn Windows Docker Desktop, a published port may still need extra host networking configuration before it is reachable through the host LAN IP. For cloud-mode testing, verify `http://<host-ip>:<host-port>/api/health` from the client device first; if it cannot connect, configure Windows port forwarding/firewall rules or deploy the cloud core on a real remote host.\n\nOn 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.\n\nTo rotate or reset the Docker cloud token:\n\n```bash\n# If you still know the current token, rotate it online.\ncrystal --base-url https://chatcrystal.example.com token rotate \"new-long-token-at-least-16-chars\" --current \"old-token\"\ncrystal connect https://chatcrystal.example.com --token \"new-long-token-at-least-16-chars\"\n\n# If you forgot the token and did not set CHATCRYSTAL_API_TOKEN, reset stored auth in the container.\ndocker compose exec chatcrystal crystal token reset --yes\ndocker compose logs chatcrystal --tail=80\ndocker compose exec chatcrystal cat /data/setup-code\n```\n\nIf 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`.\n\nTo 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.\n\n### Import from a Device into the Cloud Instance\n\nInstall or run the CLI on the device that has Claude Code, Cursor, Codex CLI, Trae, or GitHub Copilot history:\n\n```bash\ncrystal connect https://chatcrystal.example.com --token \"your-long-token\"\ncrystal import --yes\n```\n\nThe 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.\n\n## Contact Us\n\n<img src=\"docs/wechat.png\" alt=\"WeChat QR code\" width=\"220\" />\n\n## License\n\n[Apache License 2.0](LICENSE)\n",
  "bytes": 9561,
  "sha": "7eb720122525057035761488b96f0e8141194fdf071b6c268ec125230500e2f0",
  "repo_slug": "zengliangyi/chatcrystal",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_zengliangyi_chatcrystal_dbb66254/readme"
}