ChatCrystal

---

ChatCrystal 收集 AI 编码工具（Claude Code、Cursor、Codex CLI、Trae、GitHub Copilot）中的对话，使用大模型将其提炼为可搜索的结构化笔记，并构建你的个人知识库。

安装

npm install -g chatcrystal

需要 Node.js >= 20 和 LLM 服务（Ollama、OpenAI、OrcaRouter、Anthropic、Google AI，或任何兼容 OpenAI 的 API）。

快速开始

crystal import                     # Scan and import AI conversations
crystal summarize --all            # Batch summarize into notes
crystal search "React state"       # Semantic search your knowledge

首次执行命令时，服务会在后台自动启动。无需手动设置。

云端连接

对于 Docker 云端实例，只需保存一次共享令牌：

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

crystal import 仍会在本地设备上扫描并解析历史记录，然后将标准化后的对话上传到云端实例。云端服务不会扫描你的本地文件系统。crystal mcp 会复用已保存的连接和令牌。

云端连接建议使用 HTTPS，但如果你选择的部署方式使用 HTTP，也可以正常工作。

管理 Docker 云端令牌：

# Rotate when you still know the current token.
crystal --base-url https://chatcrystal.example.com token rotate "new-long-token-at-least-16-chars" --current "old-token"

# Reset stored auth from the Docker host when the token is lost.
docker compose exec chatcrystal crystal token reset --yes
docker compose exec chatcrystal cat /data/setup-code

如果部署环境中设置了 CHATCRYSTAL_API_TOKEN，请更改该环境变量并重新创建容器，而不要使用 token reset。

CLI 命令

# Knowledge retrieval
crystal search <query> [--limit 10]     # Semantic search
crystal notes list [--tag X]            # Browse notes
crystal notes get <id>                  # View note detail
crystal notes relations <id>            # View note relations
crystal tags                            # List tags with counts

# Data management
crystal import [--source claude-code]   # Import conversations
crystal summarize <id>                  # Summarize one conversation
crystal summarize --all                 # Batch summarize
crystal summarize --retry-errors        # Retry failed summaries
crystal status                          # Server status and DB stats

# Configuration
crystal config get                      # View config
crystal config set llm.provider openai  # Update config
crystal config test                     # Test LLM connection

# Server management
crystal serve                           # Start server (foreground)
crystal serve -d                        # Start server (daemon)
crystal serve stop                      # Stop daemon
crystal serve status                    # Check if running

全局选项： --base-url <url>（服务地址）、--token <token>（云端 API 令牌）、--json（强制输出 JSON）、--version

输出： 根据 TTY 状态自动适配——终端中显示彩色表格，通过管道传递时输出 JSON。

MCP 服务

与 AI 编码工具集成，使其在编码时能够从你的对话历史中检索知识。

crystal mcp                             # Start MCP stdio server

Claude Code

添加到 settings.json：

{
  "mcpServers": {
    "chatcrystal": {
      "command": "crystal",
      "args": ["mcp"]
    }
  }
}

MCP 工具

工具	说明
search_knowledge	当你需要按相关性排序的匹配结果时，对笔记进行语义搜索
get_note	获取完整的笔记内容（摘要、结论、代码片段）
list_notes	按标签或标题／摘要关键词浏览分页笔记摘要
get_relations	获取相关笔记及其关系类型
recall_for_task	只读的任务回忆功能：先加载项目记忆，再按需加载全局经验
validate_task_memory	写入任务记忆前进行试运行验证；返回是否接受、原因、警告和笔记字段
write_task_memory	在完成有意义的工作后保存可复用的任务记忆

配置

运行时配置保存在当前数据目录下的 config.json 中。CLI、MCP、仓库／开发环境检出、npm 全局安装和 Electron 默认使用 ~/.chatcrystal/data。使用 crystal config set 设置持久配置。.env 仍可作为可选的本地覆盖层使用。

# LLM (ollama/openai/orcarouter/anthropic/google/azure/custom)
crystal config set llm.provider openai
crystal config set llm.model gpt-4o
crystal config set llm.apiKey sk-...

# Embedding (ollama/openai/google/azure/custom)
crystal config set embedding.provider ollama
crystal config set embedding.model nomic-embed-text

OrcaRouter 使用 ChatCrystal 内置的 https://api.orcarouter.ai/v1 基础 URL。将 llm.provider 设置为 orcarouter，提供 API Key，并在 Web UI 中选择发现的模型；无需设置 llm.baseURL。获取 OrcaRouter API Key。

数据来源

自动检测并导入以下来源的数据：

来源	路径
Claude Code	~/.claude/projects/**/*.jsonl
Codex CLI	~/.codex/sessions/**/*.jsonl
Cursor	平台特定的 state.vscdb
Trae	平台特定的 state.vscdb
GitHub Copilot	VS Code chatSessions/*.jsonl / *.json

Web UI 和桌面应用

ChatCrystal 还提供 Web UI 和 Electron 桌面应用。详情请参阅 GitHub 仓库。

许可证

Apache License 2.0