Chatcrystal

---

ChatCrystal 是一款以本地优先的 AI 个人知识管理应用，面向使用 Claude Code、Cursor、Codex CLI、Trae 和 GitHub Copilot 解决实际问题的开发者。

它能将零散的 AI 编程对话整理为结构化笔记、语义搜索、标签知识图谱、Markdown 导出内容，以及供 Agent 重复使用的 MCP 记忆。如果这符合你的工作流，欢迎点亮星标，让更多开发者找到一种私密、本地优先的方式来保存 AI 工作记忆。

快速开始

桌面应用（推荐）

从 GitHub Releases 下载最新的 Windows 安装程序。安装后，启动 ChatCrystal，在设置中配置大模型和嵌入服务提供商，然后点击 导入。

命令行 / Web

npm install -g chatcrystal
crystal serve -d
crystal import

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

Docker 云端部署

想为多台设备自托管 ChatCrystal？请在了解产品概况后查看Docker 云端部署。

功能介绍

• 导入 AI 编程对话：从本地工具数据目录导入。
• 将对话提炼为结构化笔记：包含标题、摘要、结论、代码片段和标签。
• 通过语义搜索查找知识：利用嵌入向量和感知关联的结果扩展功能。
• 构建标签知识图谱：知识点以标签表示，边表示经过规范化的共现关系。
• 提供命令行和 MCP 工具：供 Agent 回忆并写回可复用经验。
• 在本地运行：可配置大模型和嵌入服务提供商。

截图

常用命令

crystal status                          # Server status and DB stats
crystal import [--source claude-code]   # Scan and import conversations
crystal search "query" [--limit 10]     # Semantic search
crystal notes list [--tag X]            # Browse notes
crystal notes get <id>                  # View note detail
crystal summarize --all                 # Batch summarize
crystal config get                      # View config
crystal serve -d                        # Start server in background
crystal serve stop                      # Stop background server
crystal mcp                             # Start MCP stdio server

文档

主题	English	简体中文
用户指南	docs/USER_GUIDE.md	docs/USER_GUIDE.zh-CN.md
开发	docs/DEVELOPMENT.md	docs/DEVELOPMENT.zh-CN.md
MCP 和 Agent	docs/MCP.md	docs/MCP.zh-CN.md
体验质量门槛	docs/EXPERIENCE_GATE.md	docs/EXPERIENCE_GATE.zh-CN.md
Agent 技能	docs/agent-skills.md	docs/agent-skills.zh-CN.md

架构与技术深入探讨

如需了解 ChatCrystal 背后的工程讨论、数据隐私边界和设计决策，请参阅以下文章：

• 架构与隐私边界
  • 本地优先与云端 AI：了解数据边界
  • 从 RAG 到知识图谱：在检索中保留关系
• 本地检索与向量工程
  • 配置嵌入模型：根据检索样本选择并验证重建
  • 选择本地向量存储：Vectra、Chroma 和 hnswlib
• 对话解析与协议集成
  • 多格式对话解析：JSONL、事件和 SQLite 读取边界
  • 设置 ChatCrystal MCP：让 Claude Code 调用可供审核
  • 面向 AI Agent 的知识库：回忆、验证与写回

要求

• Node.js >= 24
• 用于摘要的 LLM 提供商
• 用于语义搜索的嵌入提供商

LLM 提供商和嵌入提供商需要分别配置。Claude、GPT 和 Qwen 等大模型并非嵌入模型。提供商示例请参阅用户指南。

ChatCrystal 原生支持 OrcaRouter 进行 LLM 生成。OrcaRouter 兼容 OpenAI；其 Base URL 已内置，因此只需输入 API Key，然后使用 设置 获取并选择可用模型。

本地开发

git clone https://github.com/ZengLiangYi/ChatCrystal.git
cd ChatCrystal
corepack enable
pnpm install
pnpm dev

开发服务器端口：

• API/服务器：http://localhost:3721
• Vite 客户端：http://localhost:13721

有关架构、测试、构建和发布的详细信息，请参阅 docs/DEVELOPMENT.md。

Docker 云部署

默认的 Compose 部署仅运行 ChatCrystal 服务。数据存储在 chatcrystal-data 卷中，该卷挂载到容器内的 /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 软件包设为公开；发布工作流会在通过前验证匿名拉取权限。

默认情况下，Compose 会将 ChatCrystal 绑定到 0.0.0.0:3721，以便其他设备通过主机 IP 访问云端核心。设置 CHATCRYSTAL_HOST_PORT 可更改主机端口；若由仅限本地访问的反向代理转发流量，则设置 BIND_ADDRESS=127.0.0.1。若要公开访问云端，建议使用 HTTPS 反向代理，以便更安全地传输令牌。

在 Windows Docker Desktop 上，即使已发布端口，也可能需要额外配置主机网络，才能通过主机的局域网 IP 访问。测试云模式时，请先在客户端设备上验证 http://<host-ip>:<host-port>/api/health；如果无法连接，请配置 Windows 端口转发或防火墙规则，或者将云端核心部署到真正的远程主机上。

首次启动时，如果未设置 CHATCRYSTAL_API_TOKEN，请打开 Web UI，输入容器日志中打印或存储于 /data/setup-code 的设置代码，然后为你的设备选择一个共享 API 令牌。

若要轮换或重置 Docker 云端令牌：

# If you still know the current token, rotate it online.
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"

# If you forgot the token and did not set CHATCRYSTAL_API_TOKEN, reset stored auth in the container.
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，该环境变量就是当前使用的令牌来源。请在 .env 或 Compose 环境中更改该变量，并运行 docker compose up -d --force-recreate 重新创建容器。

若要使用现有的 Ollama 或外部 API，请在 Web UI 或环境中配置提供方 URL。在 Docker 中，localhost 指的是容器内部；可使用 CHATCRYSTAL_DOCKER_LLM_BASE_URL 和 CHATCRYSTAL_DOCKER_EMBEDDING_BASE_URL 覆盖 Compose 构建时的提供方 URL。Docker Desktop 可通过 http://host.docker.internal:11434 访问主机上的 Ollama，也可以使用远程 HTTPS/OpenAI 兼容 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。建议通过 HTTPS 访问云端，但如果你选择的部署方式使用 HTTP，也可以正常工作。

联系我们

许可证

Apache License 2.0