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 分