{"id":47904366,"url":"https://github.com/zengliangyi/chatcrystal","last_synced_at":"2026-06-06T10:00:53.773Z","repository":{"id":347473509,"uuid":"1193284630","full_name":"ZengLiangYi/ChatCrystal","owner":"ZengLiangYi","description":"Crystallize knowledge from AI conversations. Import from Claude Code / Cursor / Codex CLI,   summarize with LLM, search by semantics.","archived":false,"fork":false,"pushed_at":"2026-06-03T10:10:13.000Z","size":9160,"stargazers_count":27,"open_issues_count":2,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-03T12:08:05.099Z","etag":null,"topics":["agent-skills","ai-memory","ai-tools","claude-code","codex","cursor","electron","knowledge-graph","knowledge-management","llm","mcp","mcp-server","ollama","semantic-search"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZengLiangYi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-27T04:02:57.000Z","updated_at":"2026-06-03T10:10:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"16568659-194f-473a-80e9-923f98b0be8b","html_url":"https://github.com/ZengLiangYi/ChatCrystal","commit_stats":null,"previous_names":["zengliangyi/chatcrystal"],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/ZengLiangYi/ChatCrystal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZengLiangYi%2FChatCrystal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZengLiangYi%2FChatCrystal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZengLiangYi%2FChatCrystal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZengLiangYi%2FChatCrystal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZengLiangYi","download_url":"https://codeload.github.com/ZengLiangYi/ChatCrystal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZengLiangYi%2FChatCrystal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33977371,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skills","ai-memory","ai-tools","claude-code","codex","cursor","electron","knowledge-graph","knowledge-management","llm","mcp","mcp-server","ollama","semantic-search"],"created_at":"2026-04-04T04:42:00.790Z","updated_at":"2026-06-06T10:00:53.767Z","avatar_url":"https://github.com/ZengLiangYi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"electron/icon.png\" alt=\"ChatCrystal\" width=\"120\" /\u003e\n\n# ChatCrystal\n\n**Turn your AI conversations into searchable knowledge**\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[![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%3D20-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-5A5FD6?style=flat-square)](https://zengliangyi.github.io/ChatCrystal/)\n\nEnglish | [简体中文](README.zh-CN.md)\n\n\u003c/div\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/demo.webp\" alt=\"ChatCrystal Demo\" width=\"800\" /\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\nChatCrystal 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.\n\nSupported sources: Claude Code, Cursor, Codex CLI, Trae, and GitHub Copilot.\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\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 \u0026\u0026 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://\u003chost-ip\u003e:\u003chost-port\u003e/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## 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\u003cdiv align=\"center\"\u003e\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eConversations\u003c/strong\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eNotes\u003c/strong\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/en/conversations.png\" alt=\"Conversations\" width=\"400\" /\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/en/notes.png\" alt=\"Notes\" width=\"400\" /\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eSemantic Search\u003c/strong\u003e\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\u003cstrong\u003eKnowledge Graph\u003c/strong\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/en/search.png\" alt=\"Semantic Search\" width=\"400\" /\u003e\u003c/td\u003e\n\u003ctd\u003e\u003cimg src=\"docs/screenshots/en/graph.png\" alt=\"Knowledge Graph\" width=\"400\" /\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\u003c/div\u003e\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 \u003cid\u003e                  # 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 \u003e= 20\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\n## Local Development\n\n```bash\ngit clone https://github.com/ZengLiangYi/ChatCrystal.git\ncd ChatCrystal\nnpm install\nnpm run 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## Wechat\nWechat: Yizel1\n\n## License\n\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzengliangyi%2Fchatcrystal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzengliangyi%2Fchatcrystal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzengliangyi%2Fchatcrystal/lists"}