ChatCrystal

从 AI 对话中提炼自己的知识库
Crystallize knowledge from your AI conversations

简体中文 · English

ChatCrystal 将散落在 Claude Code、Cursor、Codex CLI 等 AI 编程工具中的对话统一采集到本地，用 LLM 提炼为可搜索的结构化技术笔记，形成个人知识库。

ChatCrystal collects conversations from AI coding tools (Claude Code, Cursor, Codex CLI), uses LLM to distill them into searchable structured notes, and builds your personal knowledge base — all running locally.

对话浏览 / Conversations	笔记摘要 / Notes
语义搜索 / Search	知识图谱 / Knowledge Graph

核心功能

• 多数据源采集 — 自动扫描并导入 Claude Code、Codex CLI、Cursor 的对话记录，支持文件监听实时同步
• LLM 摘要 — 通过 Vercel AI SDK 接入多种 LLM Provider，将对话提炼为结构化笔记（标题、摘要、关键结论、代码片段、标签）
• 语义搜索 — 基于 Embedding + 向量索引（vectra），按语义相关度检索笔记，支持沿关系边扩展结果
• 知识图谱 — LLM 自动发现笔记间的因果、依赖、引用等关系，力导向图可视化浏览
• 对话浏览 — Markdown 渲染、代码高亮、工具调用折叠，噪音过滤
• 多 Provider 支持 — 支持 Ollama、OpenAI、Anthropic、Google AI、Azure OpenAI 及任意 OpenAI 兼容服务，可在设置页面运行时切换
• 任务队列 — 批量摘要/Embedding 生成通过 p-queue 排队执行，支持实时进度追踪和取消
• 桌面应用 — Electron 打包，系统托盘驻留，关闭窗口最小化到托盘

技术栈

快速开始

前置依赖

• Node.js >= 20
• LLM 服务（以下任选其一）：
  • Ollama（本地推理，免费）
  • OpenAI / Anthropic / Google AI API Key
  • 任意 OpenAI 兼容服务（OpenRouter、Poe 等）

使用 Ollama 时，拉取所需模型：

ollama pull qwen2.5:7b          # LLM 摘要
ollama pull nomic-embed-text     # Embedding

安装

git clone https://github.com/ZengLiangYi/ChatCrystal.git
cd ChatCrystal
npm install
cp .env.example .env             # 按需修改配置

桌面应用（推荐）

npm run dev:electron             # 开发模式（Electron + Vite HMR）
npm run build:electron           # 构建 NSIS 安装包 → release/

构建后的安装包在 release/ 目录。安装后数据存储在 %APPDATA%/chatcrystal/data/。

Web 开发模式

npm run dev                      # 同时启动后端 (3721) + 前端 (13721)

访问 http://localhost:13721

Web 生产模式

npm run build                    # 构建前后端
npm start                        # 启动服务（前端由后端静态托管）

访问 http://localhost:3721

使用流程

1. 启动后，点击侧边栏「导入对话」扫描 Claude Code / Codex CLI / Cursor 对话
2. 在「对话」页浏览已导入的对话
3. 点击「生成摘要」或使用「批量生成」将对话提炼为笔记
4. 在「搜索」页通过语义搜索查找知识，可勾选「展开关联笔记」沿关系边扩展结果
5. 在「图谱」页浏览笔记之间的关联关系（力导向图，可拖拽缩放）
6. 在「笔记」页按标签筛选和浏览所有笔记
7. 在「设置」页切换 LLM/Embedding Provider 和模型

配置

可通过 .env 文件或设置页面（运行时热切换）配置：

# 服务端口
PORT=3721

# 数据源
CLAUDE_PROJECTS_DIR=~/.claude/projects
CODEX_SESSIONS_DIR=~/.codex/sessions
# CURSOR_DATA_DIR=          # 按平台自动检测，可手动覆盖

# LLM 摘要（支持 ollama/openai/anthropic/google/azure/custom）
LLM_PROVIDER=ollama
LLM_BASE_URL=http://localhost:11434
LLM_MODEL=qwen2.5:7b

# Embedding（支持 ollama/openai/google/azure/custom）
EMBEDDING_PROVIDER=ollama
EMBEDDING_BASE_URL=http://localhost:11434
EMBEDDING_MODEL=nomic-embed-text

注意：LLM 与 Embedding 需要分别配置。 语义搜索要求 Embedding 模型支持 /v1/embeddings 端点。大语言模型（如 Claude、GPT-4、Qwen）不能用作 Embedding 模型。常见可用的 Embedding 模型：

Provider	模型
Ollama（本地）	nomic-embed-text、mxbai-embed-large
OpenAI	text-embedding-3-small、text-embedding-3-large
Google	text-embedding-004

Provider 配置示例

# OpenAI
LLM_PROVIDER=openai
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o

# Anthropic
LLM_PROVIDER=anthropic
LLM_API_KEY=sk-ant-...
LLM_MODEL=claude-sonnet-4-20250514

# Google AI
LLM_PROVIDER=google
LLM_API_KEY=AIza...
LLM_MODEL=gemini-2.0-flash

# OpenAI 兼容服务（Poe / OpenRouter 等）
LLM_PROVIDER=custom
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_API_KEY=你的key
LLM_MODEL=anthropic/claude-sonnet-4

项目结构

ChatCrystal/
├── electron/                # Electron 主进程（窗口、托盘、生命周期）
├── shared/types/            # 共享 TypeScript 类型
├── server/src/
│   ├── db/                  # SQLite schema + 工具函数
│   ├── parser/              # 插件式对话解析器（Claude Code / Codex / Cursor）
│   ├── services/            # 导入、摘要、LLM、Embedding、关系发现、Provider
│   ├── routes/              # Fastify API 路由
│   ├── watcher/             # chokidar 文件监听
│   └── queue/               # p-queue 任务队列 + TaskTracker
├── client/src/
│   ├── pages/               # 页面组件（Dashboard、对话、笔记、搜索、图谱、设置）
│   ├── components/          # 通用组件（StatusBar、ActivityPanel 等）
│   ├── hooks/               # React Query hooks
│   ├── themes/              # 主题定义
│   └── providers/           # ThemeProvider
├── scripts/                 # 旧版托盘脚本（已被 Electron 替代）
├── electron-builder.yml     # Electron 打包配置
└── data/                    # 运行时数据（gitignored）

扩展数据源

实现 SourceAdapter 接口即可接入新的 AI 工具对话：

interface SourceAdapter {
  name: string;
  displayName: string;
  detect(): Promise<SourceInfo | null>;
  scan(): Promise<ConversationMeta[]>;
  parse(meta: ConversationMeta): Promise<ParsedConversation>;
}

目前已内置三个适配器：

在 server/src/parser/adapters/ 下新建适配器文件，注册到 parser/index.ts。

API

知识图谱

笔记生成摘要后，LLM 会自动分析其与已有笔记之间的关系。支持以下关系类型：

在笔记详情页底部可查看关联笔记，支持 AI 发现、手动添加、搜索选择目标笔记。在「图谱」页可通过力导向图可视化浏览整个知识网络。

常见问题

语义搜索返回 500 "Not Found"

Embedding 模型配置错误。确保 EMBEDDING_MODEL 使用的是专用 Embedding 模型（如 nomic-embed-text），而不是大语言模型（如 claude-haiku、qwen2.5）。大语言模型不支持 /v1/embeddings 端点。

启动时连不上 Ollama

确保 Ollama 服务已启动，且模型已拉取：

ollama pull qwen2.5:7b
ollama pull nomic-embed-text

对话导入为空

检查 .env 中 CLAUDE_PROJECTS_DIR 路径是否正确，确保对应目录下有 .jsonl 文件。

知识图谱为空

需要先生成笔记，再在笔记详情页点击「发现」，或使用 POST /api/relations/batch-discover 批量发现关联。

Features

• Multi-source ingestion — Auto-imports conversations from Claude Code, Codex CLI, and Cursor with real-time file watching
• LLM summarization — Distills conversations into structured notes (title, summary, key conclusions, code snippets, tags) via Vercel AI SDK
• Semantic search — Embedding-powered vector search (vectra) with relation-aware result expansion
• Knowledge graph — LLM-discovered relationships (causal, dependency, similarity, etc.) with force-directed visualization
• Multi-provider support — Ollama, OpenAI, Anthropic, Google AI, Azure OpenAI, or any OpenAI-compatible API
• Local-first — All data stays on your machine (sql.js + local embeddings via Ollama)
• Desktop app — Electron with system tray, single-instance lock, and window state persistence

License

MIT