ChatCrystal
Local-first memory that recalls notes distilled from your AI coding conversations
- Pricing
- Open source
- Platforms
- CLI, self-hosted, macOS
- Runs
- Locally
- Version
- 0.7.1
- Listing updated
- 3 days ago
About ChatCrystal
ChatCrystal is an open-source MCP server for knowledge and memory. It runs locally on your machine and is started by your AI client.
ChatCrystal collects conversation history from 32 coding agent harnesses, including Claude Code, Codex CLI, Cursor, Copilot, Gemini CLI, Cline and Goose, on the local machine and in WSL distros. A language model then distils each conversation into a summary, decisions, snippets, source metadata and tags, building a searchable personal knowledge base with a tag graph and Markdown export.
The MCP server, started with crystal mcp over stdio, gives coding agents access to that same knowledge so they can recall past decisions and write reusable task memories during a session. It reads from the local server at http://localhost:3721 by default, or from a ChatCrystal cloud or Docker instance via an optional URL and token.
Data lives in local SQLite and the project is Apache-2.0 licensed. You supply the language model: Ollama for fully local use, OpenAI, Anthropic, Google AI or any OpenAI-compatible API. It needs Node.js 20 or later and installs from npm as chatcrystal.
Install
Run in a terminal
claude mcp add chatcrystal --env CHATCRYSTAL_API_TOKEN='<CHATCRYSTAL_API_TOKEN>' -- npx -y chatcrystalAdd to claude_desktop_config.json
{
"mcpServers": {
"chatcrystal": {
"command": "npx",
"args": [
"-y",
"chatcrystal"
],
"env": {
"CHATCRYSTAL_API_TOKEN": "<CHATCRYSTAL_API_TOKEN>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"chatcrystal": {
"command": "npx",
"args": [
"-y",
"chatcrystal"
],
"env": {
"CHATCRYSTAL_API_TOKEN": "<CHATCRYSTAL_API_TOKEN>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"chatcrystal": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"chatcrystal"
],
"env": {
"CHATCRYSTAL_API_TOKEN": "<CHATCRYSTAL_API_TOKEN>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"chatcrystal": {
"command": "npx",
"args": [
"-y",
"chatcrystal"
],
"env": {
"CHATCRYSTAL_API_TOKEN": "<CHATCRYSTAL_API_TOKEN>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"chatcrystal": {
"command": "npx",
"args": [
"-y",
"chatcrystal"
],
"env": {
"CHATCRYSTAL_API_TOKEN": "<CHATCRYSTAL_API_TOKEN>"
}
}
}
}Configuration
CHATCRYSTAL_BASE_URLOptional ChatCrystal Core URL. Leave empty to use the local default at http://localhost:3721.CHATCRYSTAL_API_TOKENOptional token for a protected ChatCrystal Cloud or remote instance.
What it does
- 32 agent sources
- Imports histories from many coding agent harnesses, local and WSL.
- LLM-distilled notes
- Summaries, decisions, snippets and tags extracted per conversation.
- Semantic search
- Natural-language search balancing embeddings with lexical matches.
- Tag knowledge graph
- Tags become nodes with neighbourhoods and project context.
- Agent memory loop
- MCP tools recall and write task memories from the same knowledge base.
- Local or cloud
- Runs on localhost by default, with an optional Docker cloud instance.
Good for
- Let an agent recall how a past bug was fixed
- Search months of coding chats by topic
- Export a decision record as Markdown
- Share one knowledge base across several coding agents
Pricing
Open source
Free, Apache-2.0
Prices change. Check zengliangyi.github.io before you buy.
ChatCrystal FAQ
Does my data leave my machine?
The site says storage is local SQLite with no cloud dependency; you choose the language model provider.
Can I use a local model?
Yes, Ollama is supported for fully local AI.
What licence is it?
Apache-2.0.
What does it need?
Node.js 20 or newer and an LLM service.
How do I start the MCP server?
Run crystal mcp after installing the chatcrystal npm package.
Is ChatCrystal free?
Yes. ChatCrystal is open source, so you can use and self-host it for free.
How do I add ChatCrystal to Claude Code?
Run this command in your terminal: claude mcp add chatcrystal --env CHATCRYSTAL_API_TOKEN='<CHATCRYSTAL_API_TOKEN>' -- npx -y chatcrystal
What are the best alternatives to ChatCrystal?
The closest alternatives to ChatCrystal are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.
Alternatives to ChatCrystal

REA
MCP serverCLI and MCP server that lets coding agents reverse engineer apps and binaries
Runs locally- Open source
- 464K GitHub stars
- Developer tools

Codebase Memory
MCP serverLocal MCP server that builds a code knowledge graph for AI coding agents
Runs locally- Open source
- 48.7K GitHub stars
- Knowledge and memory

GitHub
MCP serverOfficial MCP server connecting AI assistants to GitHub repos, issues and workflows
Not checked yet- Remote
- Open source
- 34.5K GitHub stars
- Developer tools

Serena MCP: the IDE for your agent
MCP serverMCP toolkit giving coding agents symbol-level code retrieval and editing
Runs locally- Open source
- 31.5K GitHub stars
- Developer tools

XERJ
MCP serverLocal search engine for AI agents with cited answers over your code and docs
Runs locally- Open source
- 19.2K GitHub stars
- Knowledge and memory

Ouroboros
MCP serverSpec-first layer that pins requirements and verifies results of AI coding agent work
Runs locally- Open source
- 6.4K GitHub stars
- Developer tools