ChatCrystal — Claude Code MCP server: memory from AI chats
Imports conversations from Claude, Cursor and Codex CLI, distills them into notes, and serves them to your agent over MCP. Useful when you need to recall what you already solved.
claude mcp add --env CHATCRYSTAL_BASE_URL=<CHATCRYSTAL_BASE_URL> --env CHATCRYSTAL_API_TOKEN=<CHATCRYSTAL_API_TOKEN> --transport stdio server -- npx -y chatcrystalWhat ChatCrystal does
ChatCrystal scans chat histories from Claude, Cursor, Codex CLI, Trae and GitHub Copilot, runs them through an LLM, and stores structured notes. From there you get semantic search with crystal search "React state", notes by tag, and relations between notes. Data stays local in ~/.chatcrystal/data.
The MCP server starts with crystal mcp. It exposes seven tools: knowledge search, full note retrieval, paginated listing, relations, plus recall_for_task, validate_task_memory and write_task_memory. Those last three let the agent pull task memory first, dry-run a note before writing it, then persist it. Install is global: npm install -g chatcrystal.
Nothing runs without an LLM provider. You need Ollama, OpenAI, Anthropic, Google AI, OrcaRouter or any OpenAI-compatible API, and Node.js 20 or newer. Provider and key go through crystal config set llm.provider and crystal config set llm.apiKey. For a Docker cloud instance, save the token once with crystal connect; crystal mcp reuses that connection. If CHATCRYSTAL_API_TOKEN is set in the deployment environment, rotate it by changing the variable and recreating the container — token reset is not the path there.
What it helps with
- find what you already discussed with the agent about a module
- turn long sessions into short notes with conclusions and snippets
- load task memory before the agent starts writing code
- dry-run a note before it lands in the knowledge base
- sort accumulated conversations by tags and relations
Example prompts for the agent
- Search my notes for everything about React state and show the relations
- Recall task memory for the auth refactor, then propose a plan
- Validate this note as a dry run and save it as task memory if it passes
How to install ChatCrystal
Platform CLI
claude mcp add --env CHATCRYSTAL_BASE_URL=<CHATCRYSTAL_BASE_URL> --env CHATCRYSTAL_API_TOKEN=<CHATCRYSTAL_API_TOKEN> --transport stdio server -- npx -y chatcrystalReplace <…> with your own values
Platform CLI
codex mcp add server --env CHATCRYSTAL_BASE_URL=<CHATCRYSTAL_BASE_URL> --env CHATCRYSTAL_API_TOKEN=<CHATCRYSTAL_API_TOKEN> -- npx -y chatcrystalReplace <…> with your own values
Config file
{
"mcpServers": {
"server": {
"command": "npx",
"args": [
"-y",
"chatcrystal"
],
"env": {
"CHATCRYSTAL_BASE_URL": "<CHATCRYSTAL_BASE_URL>",
"CHATCRYSTAL_API_TOKEN": "<CHATCRYSTAL_API_TOKEN>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"chatcrystal"
],
"env": {
"CHATCRYSTAL_BASE_URL": "<CHATCRYSTAL_BASE_URL>",
"CHATCRYSTAL_API_TOKEN": "<CHATCRYSTAL_API_TOKEN>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e CHATCRYSTAL_BASE_URL=<CHATCRYSTAL_BASE_URL> -e CHATCRYSTAL_API_TOKEN=<CHATCRYSTAL_API_TOKEN> server npx -y chatcrystalReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about ChatCrystal
How do I install ChatCrystal in Claude Code?
Run claude mcp add chatcrystal -e CHATCRYSTAL_API_TOKEN=<CHATCRYSTAL_API_TOKEN> -- npx -y chatcrystal. With a base URL: `claude mcp add --env CHATCRYSTAL_BASE_URL=<CHATCRYSTAL_BASE_URL> --env CHATCRYSTAL_API_TOKEN=<CHATCRYSTAL_API_TOKEN> --transport stdio server -- npx -y chatcrystal`.
What does ChatCrystal do?
It imports chat histories from AI coding tools, summarizes them into notes, and exposes those notes to your agent through MCP tools: search, note retrieval, relations and task memory.
What do I need to run it?
Node.js 20 or newer and an LLM service: Ollama, OpenAI, Anthropic, Google AI, OrcaRouter or any OpenAI-compatible API. Set the provider and key with crystal config set.
