ChatCrystal

io.github.ZengLiangYi由 GitHub 账号 ZengLiangYi 发布v0.6.2更新于 Oct 30, 2026

Local-first AI PKM memory for coding conversations.

已验证STDIO仅桌面知识与记忆开发者工具

概览

AI 生成的概览

本地优先的 AI 编程对话个人知识库，让助手检索提炼后的笔记，并召回或保存可复用的任务记忆。

可以做什么
  • 检索与浏览笔记：语义搜索、按标签或关键词分页列出笔记摘要、读取包含结论与代码片段的完整笔记
  • 查看笔记之间的关联，含关系类型与置信度
  • 在编码、调试、迁移、重构或优化任务开始前召回任务记忆，先加载项目级记忆再加载全局经验
  • 先对候选任务记忆做无副作用的试运行校验，合格后再写入为结构化笔记
适用场景
适合希望助手复用以往 AI 编程会话中积累的坑点、修复方案与决策，而不是重复踩坑的场景。最适合已把 Claude Code、Cursor、Codex CLI 等工具的对话收集进本地 ChatCrystal 知识库的开发者。
运行要求
以本地 stdio 进程运行，通常通过 npx 或 crystal mcp 命令启动，需要 Node.js 20 或更高版本。需要运行中的 ChatCrystal Core 实例，默认地址为 localhost:3721，或通过 CHATCRYSTAL_BASE_URL 指定远程/云端实例。需配置 LLM 与嵌入服务提供方（Ollama、OpenAI、Anthropic、Google、Azure 或兼容 OpenAI 的 API）用于摘要与检索。受保护的云端实例可选使用 CHATCRYSTAL_API_TOKEN。
安装前请注意
知识库通过扫描本机 AI 编程工具的对话历史构建，这些对话（含代码与提示词）会保存在本地，云端模式下还会上传到所配置的实例。write_task_memory 会向知识库写入新笔记。LLM 与嵌入服务的 API 密钥在 ChatCrystal 设置中配置并发送给所选提供方。云端连接建议使用 HTTPS，并将 CHATCRYSTAL_API_TOKEN 视为机密。

安装

在 SourceWeft 中

  1. 打开 控制台中的 ChatCrystal，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

[ChatCrystal]

ChatCrystal

Crystallize knowledge from your AI conversations

[npm] [GitHub] [License: Apache-2.0]

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

Install

bash
npm install -g chatcrystal

Requires Node.js >= 20 and an LLM service (Ollama, OpenAI, OrcaRouter, Anthropic, Google AI, or any OpenAI-compatible API).

Quick Start

bash
crystal import                     # Scan and import AI conversationscrystal summarize --all            # Batch summarize into notescrystal search "React state"       # Semantic search your knowledge

The server auto-launches in background on first command. No manual setup needed.

Cloud Connection

For a Docker cloud instance, save the shared token once:

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

crystal import still scans and parses histories on the local device, then uploads normalized conversations to the cloud instance. The cloud server does not scan your local filesystem. crystal mcp reuses the same saved connection and token.

HTTPS is recommended for cloud connections, but HTTP works when that is the deployment you choose.

To manage a Docker cloud token:

bash
# 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 --yesdocker compose exec chatcrystal cat /data/setup-code

If CHATCRYSTAL_API_TOKEN is set in the deployment environment, change that environment variable and recreate the container instead of using token reset.

CLI Commands

bash
# Knowledge retrievalcrystal search <query> [--limit 10]     # Semantic searchcrystal notes list [--tag X]            # Browse notescrystal notes get <id>                  # View note detailcrystal notes relations <id>            # View note relationscrystal tags                            # List tags with counts
# Data managementcrystal import [--source claude-code]   # Import conversationscrystal summarize <id>                  # Summarize one conversationcrystal summarize --all                 # Batch summarizecrystal summarize --retry-errors        # Retry failed summariescrystal status                          # Server status and DB stats
# Configurationcrystal config get                      # View configcrystal config set llm.provider openai  # Update configcrystal config test                     # Test LLM connection
# Server managementcrystal serve                           # Start server (foreground)crystal serve -d                        # Start server (daemon)crystal serve stop                      # Stop daemoncrystal serve status                    # Check if running

Global options: --base-url <url> (server address), --token <token> (cloud API token), --json (force JSON output), --version

Output: TTY-aware — colored tables in terminal, JSON when piped.

MCP Server

Integrate with AI coding tools so they can retrieve knowledge from your conversation history during coding.

bash
crystal mcp                             # Start MCP stdio server

Claude Code

Add to settings.json:

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

MCP Tools

ToolDescription
search_knowledgeSemantic search across notes when you need relevance-ranked matches
get_noteGet full note content (summary, conclusions, code snippets)
list_notesBrowse paginated note summaries by tag or title/summary keyword
get_relationsGet related notes with relationship types
recall_for_taskRead-only task recall that loads project memories first, then optional global lessons
validate_task_memoryDry-run validation before writing a task memory; returns acceptance, reasons, warnings, and note fields
write_task_memoryPersist reusable task memories after meaningful work

Configuration

Runtime configuration is stored in config.json under the active data directory. CLI, MCP, repo/dev checkouts, npm global installs, and Electron default to ~/.chatcrystal/data. Use crystal config set for persistent config. .env remains available only as an optional local override layer.

bash
# LLM (ollama/openai/orcarouter/anthropic/google/azure/custom)crystal config set llm.provider openaicrystal config set llm.model gpt-4ocrystal config set llm.apiKey sk-...
# Embedding (ollama/openai/google/azure/custom)crystal config set embedding.provider ollamacrystal config set embedding.model nomic-embed-text

OrcaRouter uses ChatCrystal's built-in https://api.orcarouter.ai/v1 Base URL. Set llm.provider to orcarouter, provide an API Key, and select a discovered model in the Web UI; no llm.baseURL is required. Get an OrcaRouter API Key.

Data Sources

Automatically detects and imports from:

SourcePath
Claude Code~/.claude/projects/**/*.jsonl
Codex CLI~/.codex/sessions/**/*.jsonl
CursorPlatform-specific state.vscdb
TraePlatform-specific state.vscdb
GitHub CopilotVS Code chatSessions/*.jsonl / *.json

Web UI & Desktop App

ChatCrystal also has a web UI and Electron desktop app. See the GitHub repository for details.

License

Apache License 2.0

来源：server/README.md，提交 7642768

工具

7

search_knowledge

Semantic search across your AI conversation knowledge base. Returns matching notes ranked by relevance.

输入参数limitquery必填

get_note

Get the full content of a note including title, summary, key conclusions, code snippets, and tags.

输入参数id必填

list_notes

List note summaries for browsing and narrowing the ChatCrystal knowledge base. Use this when you need paginated notes filtered by tag or title/summary keyword. Use search_knowledge instead for semantic relevance ranking, and get_note when you already have an id and need the full note body. Returns note metadata and summaries, not full note content.

输入参数tagpagesearch

get_relations

Get related notes for a given note, including relationship type and confidence score.

输入参数noteId必填

recall_for_task

Retrieve reusable task memories before starting substantive coding work. Use this at the beginning of implementation, debugging, migration, configuration, investigation, refactor, or optimization tasks to load project-scoped memories first and optional global lessons second. Use mode="debug" when the user reports an error, failing command, regression, or incident; include error_signatures and related_files when available. Use search_knowledge instead for ad hoc semantic note search that is not tied to the current task. This tool is read-only and returns ranked memories plus optional related-note context without writing anything.

输入参数modetask必填options

validate_task_memory

Dry-run validation for a candidate task memory before calling write_task_memory. Use this after meaningful work and before persisting a lesson to check whether the candidate is durable, specific, reusable, and shaped like a high-quality ChatCrystal note. It has no side effects and never writes to the knowledge base. Returns acceptance, rejection reason, warnings, and materialized note fields so agents can revise the candidate or skip weak work logs.

输入参数mode必填task必填scopememory必填source_run_key

write_task_memory

Persist a task memory only when it can become a high-quality ChatCrystal note: specific title, concrete summary, meaningful key conclusions, and a durable reusable lesson such as a pitfall, fix, decision, pattern, or symptom-to-resolution mapping. Do not write one-time environment checks, version/status reports, ordinary progress logs, or vague robustness claims. Weak auto writebacks are skipped by core validation and recorded only as receipts.

输入参数mode必填task必填scopememory必填source_run_key

版本历史

3
  1. v0.6.2最新Oct 23, 2026
  2. v0.6.1Sep 20, 2026
  3. v0.6.0Sep 16, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分