ChatCrystal
ChatCrystal’s MCP server lets agents search, browse, relate, and write back reusable knowledge from a local-first AI conversation memory base.
Semantically search conversation-derived notes and rank results by relevance.
Retrieve full note content, including summaries, conclusions, snippets, and tags.
List and paginate note summaries, filtered by tag or literal title/summary keyword.
Find related notes with relationship type and confidence scores.
Recall project-scoped and global task memories before coding, debugging, migration, refactoring, or investigation work.
Dry-run validate candidate task memories to check whether they are durable and reusable before saving.
Persist high-quality task memories as notes, with support for idempotency keys to avoid duplicates.
Imports coding conversations from GitHub Copilot, distills them into structured notes with semantic search and knowledge graph, and provides MCP tools for agents to reuse insights.
ChatCrystal
Local-first AI PKM for coding conversations
Website · Author & Blog · Download Desktop · npm · Docs · 简体中文
ChatCrystal is a local-first AI PKM app for developers who solve real problems with AI coding agents: Claude Code, Claude Desktop, Codex CLI, Cursor, Trae, GitHub Copilot Chat and CLI, Gemini CLI, Qwen Code, OpenCode, Cline, Roo Code, Kilo Code, Continue, DeepSeek Harness, WorkBuddy, CodeBuddy, Antigravity, Droid, Goose, Pi, omp, Raft, Cindy, Qoder/Qoder CN, ZCode, Hermes, Alma, Grok Build, Kimi Code, and MiniMax Code — 32 agent harnesses in total.
It turns scattered AI coding conversations into structured notes, semantic search, a tag knowledge graph, Markdown exports, and MCP memory your agents can reuse. If this fits your workflow, a star helps more builders find a private, local-first way to keep their AI work memory.
Quick Start
Desktop App (Recommended)
Download the latest Windows installer from GitHub Releases. After installing, launch ChatCrystal and configure your LLM and embedding providers in Settings. Conversation history is synced automatically in the background on startup and when agent session files change — there is no import step to wait for. The sidebar shows the sync state and lets you trigger or cancel a pass. Rows that are still parsing appear immediately with an Indexing marker and load their transcript when opened.
CLI / Web
npm install -g chatcrystal
crystal serve -d
crystal importThen open http://localhost:3721 in your browser.
Docker Cloud
Prefer self-hosting ChatCrystal for multiple devices? See Docker Cloud Deployment after the product overview.
Related MCP server: decisionnode/DecisionNode
What It Does
Imports AI coding conversations from 32 agent harnesses: Claude Code, Claude Desktop, Codex CLI, Cursor, Trae, GitHub Copilot Chat and CLI, Gemini CLI, Qwen Code, OpenCode, Cline, Roo Code, Kilo Code, Continue, DeepSeek Harness, WorkBuddy, CodeBuddy, Antigravity, Droid, Goose, Pi, omp, Raft, Cindy, Qoder/Qoder CN, ZCode, Hermes, Alma, Grok Build, Kimi Code, and MiniMax Code.
Syncs automatically in the background — a startup pass plus targeted file-watch passes keep conversations current without a manual import; the list fills as soon as each source is scanned, transcripts are parsed in worker threads (and cached for later), and sync progress is visible in the sidebar.
Stays fast — parsed transcripts are cached locally as gzip snapshots, so later reads, interrupted syncs, and detail loads do not re-parse every file; the cache self-prunes to 512 MB / 30 days.
Reads WSL sessions on Windows — Claude Code, Codex, Gemini CLI, Qwen Code, OpenCode, Cline, Continue, DeepSeek Harness and other agents installed inside a WSL distro are imported from the distro home (running distros are scanned by default).
Distills conversations into structured notes with titles, summaries, conclusions, snippets, and tags.
Searches knowledge semantically with embeddings and relation-aware result expansion.
Builds a tag knowledge graph where knowledge points are tags and edges show normalized co-occurrence.
Exposes CLI and MCP tools so agents can recall and write back reusable experience.
Runs locally with configurable LLM and embedding providers.
Screenshots
Common Commands
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 serverDocumentation
Topic | English | 简体中文 |
User guide | ||
Development | ||
MCP and agents | ||
Experience quality gate | ||
Agent skills |
Architecture & Technical Deep Dives
For engineering discussions, data privacy boundaries, and design decisions behind ChatCrystal, see the following articles:
Architecture & Privacy Boundaries
Local Retrieval & Vector Engineering
Conversation Parsing & Protocol Integration
Requirements
Node.js >= 24
An LLM provider for summarization
An embedding provider for semantic search
LLM and embedding providers are configured separately. Large language models such as Claude, GPT, and Qwen are not embedding models. See the user guide for provider examples.
ChatCrystal includes first-class OrcaRouter support for LLM generation. OrcaRouter is OpenAI-compatible; its Base URL is built in, so enter only your API Key and use Settings to fetch and select an available model.
Local Development
git clone https://github.com/ZengLiangYi/ChatCrystal.git
cd ChatCrystal
corepack enable
pnpm install
pnpm devDevelopment server ports:
API/server: http://localhost:3721
Vite client: http://localhost:13721
See docs/DEVELOPMENT.md for architecture, testing, build, and release details. Release history lives in CHANGELOG.md.
Docker Cloud Deployment
The default Compose deployment runs only the ChatCrystal service. It stores data in the chatcrystal-data volume mounted at /data inside the container.
git clone https://github.com/ZengLiangYi/ChatCrystal.git
cd ChatCrystal
docker compose up -dThe default docker-compose.yml pulls ghcr.io/zengliangyi/chatcrystal:latest from GitHub Container Registry. Set CHATCRYSTAL_IMAGE_TAG to pin a published version. To build from source instead, run docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build.
To update an existing Docker deployment, run docker compose pull && docker compose up -d. Maintainers only: after the first GHCR publish, make the ghcr.io/zengliangyi/chatcrystal package public in GitHub Packages; the release workflow verifies anonymous pull access before passing.
Compose binds ChatCrystal to 0.0.0.0:3721 by default so other devices can reach the cloud core through the host IP. Set CHATCRYSTAL_HOST_PORT to change the host port, or set BIND_ADDRESS=127.0.0.1 when a local-only reverse proxy fronts it. For public cloud access, an HTTPS reverse proxy is recommended for safer token transport.
On Windows Docker Desktop, a published port may still need extra host networking configuration before it is reachable through the host LAN IP. For cloud-mode testing, verify http://<host-ip>:<host-port>/api/health from the client device first; if it cannot connect, configure Windows port forwarding/firewall rules or deploy the cloud core on a real remote host.
On first start without CHATCRYSTAL_API_TOKEN, open the Web UI and enter the setup code printed in container logs or stored at /data/setup-code, then choose one shared API token for your devices.
To rotate or reset the Docker cloud token:
# 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-codeIf your deployment sets CHATCRYSTAL_API_TOKEN, that environment variable is the active token source. Change it in your .env or Compose environment and recreate the container with docker compose up -d --force-recreate.
To use an existing Ollama or external API, configure provider URLs in the Web UI or environment. In Docker, localhost means inside the container; use CHATCRYSTAL_DOCKER_LLM_BASE_URL and CHATCRYSTAL_DOCKER_EMBEDDING_BASE_URL for Compose-time provider URL overrides. Docker Desktop can reach host Ollama at http://host.docker.internal:11434, or you can use a remote HTTPS/OpenAI-compatible API.
Import from a Device into the Cloud Instance
Install or run the CLI on the device that has AI coding agent history (Claude Code, Codex CLI, Gemini CLI, OpenCode, Cline, and 27 more supported sources):
crystal connect https://chatcrystal.example.com --token "your-long-token"
crystal import --yesThe CLI scans local histories, parses them locally, and uploads normalized conversations to the cloud. The cloud never scans your local filesystem. Imported conversations are not summarized automatically; use the Web UI or crystal summarize --all when you are ready. HTTPS is recommended for cloud access, but HTTP works when that is the deployment you choose.
Contact Us
License
Available Tools
7 toolsget_noteA
Get the full content of a note including title, summary, key conclusions, code snippets, and tags.
Inputs: id (required).
get_relationsA
Get related notes for a given note, including relationship type and confidence score.
Inputs: noteId (required).
list_notesA
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.
Inputs: tag, page, search.
recall_for_taskA
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.
Inputs: task (required), mode, options.
search_knowledgeA
Semantic search across your AI conversation knowledge base. Returns matching notes ranked by relevance.
Inputs: query (required), limit.
validate_task_memoryA
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.
Inputs: mode (required), task (required), memory (required), scope, +1 more.
write_task_memoryA
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.
Inputs: mode (required), task (required), memory (required), scope, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool serves a clearly distinct purpose: getting full notes, listing summaries, semantic search, task-specific recall, relation retrieval, validation, and writing. No overlapping functionality.
All tool names follow a consistent verb_noun pattern using lowercase and underscores, e.g., get_note, list_notes, write_task_memory, ensuring predictability.
With 7 tools, the set is well-scoped for a knowledge base server, covering creation, retrieval, search, and validation without being overwhelming or sparse.
The tool surface covers core operations but lacks update and delete capabilities for notes, which may create dead ends if an agent needs to modify or remove a memory.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Related MCP Servers
- AlicenseAqualityBmaintenancePersistent memory MCP server for AI coding agents (Claude Code, Codex, Gemini CLI). Hybrid retrieval (vector + BM25), cross-encoder reranking, knowledge graph, session checkpoint/resume, and multi-scope isolation. Local-first with LanceDB.3026 npm15MIT
- AlicenseAqualityDmaintenanceRecord development decisions as structured JSON, embed them as vectors via Gemini, and search semantically over MCP. Works with Claude Code, Cursor, Windsurf, and any MCP client.914 npm82MIT
- AlicenseAqualityCmaintenancePersistent memory MCP server for Claude Code, Cursor, and GitHub Copilot. Semantic search, Git sync, project-based, Persistent memory MCP server for Claude Code, Cursor, and GitHub Copilot. Semantic search, Git sync, project-based organization, and team collaboration via Model Context Protocol.15345 npm2MIT
- AlicenseAqualityBmaintenancePath-scoped team memories, rules and skills for AI coding agents.301MIT