# ChatCrystal

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 61
- Author: ZengLiangYi
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/ZengLiangYi/ChatCrystal/tree/HEAD/server
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/chatcrystal

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `CHATCRYSTAL_BASE_URL`, `CHATCRYSTAL_API_TOKEN` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env CHATCRYSTAL_BASE_URL=<CHATCRYSTAL_BASE_URL> --env CHATCRYSTAL_API_TOKEN=<CHATCRYSTAL_API_TOKEN> --transport stdio server -- npx -y chatcrystal
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add server --env CHATCRYSTAL_BASE_URL=<CHATCRYSTAL_BASE_URL> --env CHATCRYSTAL_API_TOKEN=<CHATCRYSTAL_API_TOKEN> -- npx -y chatcrystal
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e CHATCRYSTAL_BASE_URL=<CHATCRYSTAL_BASE_URL> -e CHATCRYSTAL_API_TOKEN=<CHATCRYSTAL_API_TOKEN> server npx -y chatcrystal
```
Replace <…> with your own values

## When to use it
- 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
- 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

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md