ChatCrystal

May 29, 2026 · View on GitHub

ChatCrystal

ChatCrystal

从 AI 对话中提炼可搜索的知识库

GitHub release npm License: Apache-2.0 Node.js Platform Website

English | 简体中文

ChatCrystal 演示

ChatCrystal 会采集 AI 编程工具中的本地对话，用 LLM 提炼为结构化笔记，并基于真实问题解决过程建立一个可搜索的本地知识库。

支持的数据源：Claude Code、Cursor、Codex CLI、Trae、GitHub Copilot。

快速开始

桌面应用（推荐）

从 GitHub Releases 下载最新 Windows 安装包。安装后启动 ChatCrystal，在设置页配置 LLM 和 Embedding Provider，然后点击 Import。

CLI / Web

npm install -g chatcrystal
crystal serve -d
crystal import

然后在浏览器打开 http://localhost:3721。

Docker 云端部署

默认 Compose 只运行 ChatCrystal 一个服务。数据保存在 chatcrystal-data volume 中，并挂载到容器内 /data。

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

默认 docker-compose.yml 会从 GitHub Container Registry 拉取 ghcr.io/zengliangyi/chatcrystal:latest。如果要固定已发布版本，设置 CHATCRYSTAL_IMAGE_TAG。如果要从源码本地构建，使用 docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build。

如果要更新已有 Docker 部署，运行 docker compose pull && docker compose up -d。维护者注意：GHCR 首次发布后，需要在 GitHub Packages 中将 ghcr.io/zengliangyi/chatcrystal 设为 Public；发布 workflow 会验证匿名拉取权限，未公开时不会通过。

Compose 默认只绑定到宿主机 127.0.0.1:3721。如需调整宿主机端口，设置 CHATCRYSTAL_HOST_PORT。如果要公网访问，请在前面放一个 HTTPS 反向代理，并让 CLI / 浏览器连接 HTTPS 地址。不要让 bearer token 走明文 HTTP。

首次启动且没有设置 CHATCRYSTAL_API_TOKEN 时，打开 Web UI，输入容器日志或 /data/setup-code 中的 setup code，然后设置一个供所有设备共享的 API token。

Docker 云端 token 的轮换和重置方式如下：

# 如果还知道当前 token，可以在线轮换。
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"

# 如果忘记 token，且没有设置 CHATCRYSTAL_API_TOKEN，可以在容器内重置 stored auth。
docker compose exec chatcrystal crystal token reset --yes
docker compose logs chatcrystal --tail=80
docker compose exec chatcrystal cat /data/setup-code

如果部署时设置了 CHATCRYSTAL_API_TOKEN，实际生效的 token 来自环境变量，而不是 /data/auth.json。这时需要修改 .env 或 Compose 环境变量，然后用 docker compose up -d --force-recreate 重建容器。

如果使用已有 Ollama 或外部 API，可在 Web UI 或环境变量中配置 provider URL。在 Docker 中，localhost 指向容器内部；Compose 场景请用 CHATCRYSTAL_DOCKER_LLM_BASE_URL 和 CHATCRYSTAL_DOCKER_EMBEDDING_BASE_URL 覆盖 provider URL。Docker Desktop 上访问宿主机 Ollama 可用 http://host.docker.internal:11434，也可以使用远程 HTTPS / OpenAI-compatible API。

从本机设备导入到云端实例

在保存 Claude Code、Cursor、Codex CLI、Trae 或 GitHub Copilot 历史记录的设备上安装或运行 CLI：

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

CLI 会在本机扫描并解析历史记录，然后把标准化后的对话上传到云端。云端不会扫描你的本机文件系统。导入的对话不会自动生成摘要；准备好后再通过 Web UI 或 crystal summarize --all 批量生成。默认情况下，CLI 会拒绝把 ChatCrystal API token 发送到非本机 http:// 地址；云端访问请使用 HTTPS。

它能做什么

  • 导入 AI 编程对话，从本地工具数据目录扫描历史记录。
  • 提炼结构化笔记，包含标题、摘要、结论、代码片段和标签。
  • 语义搜索知识，支持 Embedding 检索和关联笔记扩展。
  • 构建知识图谱，展示笔记、问题、决策之间的关系。
  • 提供 CLI 与 MCP 工具，让 Agent 能召回经验并写回可复用成果。
  • 本地运行，LLM 与 Embedding Provider 可独立配置。

截图

对话浏览 笔记摘要
对话浏览 笔记摘要
语义搜索 知识图谱
语义搜索 知识图谱

常用命令

crystal status                          # 服务器状态与数据库统计
crystal import [--source claude-code]   # 扫描并导入对话
crystal search "关键词" [--limit 10]     # 语义搜索
crystal notes list [--tag 标签名]        # 浏览笔记
crystal notes get <id>                  # 查看笔记详情
crystal summarize --all                 # 批量生成摘要
crystal config get                      # 查看配置
crystal serve -d                        # 后台启动服务器
crystal serve stop                      # 停止后台服务器
crystal mcp                             # 启动 MCP stdio 服务

文档

主题English简体中文
用户指南docs/USER_GUIDE.mddocs/USER_GUIDE.zh-CN.md
开发者指南docs/DEVELOPMENT.mddocs/DEVELOPMENT.zh-CN.md
MCP 与 Agentdocs/MCP.mddocs/MCP.zh-CN.md
经验质量门槛docs/EXPERIENCE_GATE.mddocs/EXPERIENCE_GATE.zh-CN.md
Agent Skillsdocs/agent-skills.mddocs/agent-skills.zh-CN.md

运行要求

  • Node.js >= 20
  • 用于摘要生成的 LLM Provider
  • 用于语义搜索的 Embedding Provider

LLM 和 Embedding 需要分别配置。Claude、GPT、Qwen 等大语言模型不是 Embedding 模型。Provider 示例见用户指南。

本地开发

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

开发服务端口：

架构、测试、构建和发布说明见开发者指南。

欢迎提问

微信号: Yizel1

License

Apache License 2.0