# ChatCrystal

> ChatCrystal is an open-source MCP server for knowledge and memory. Local-first memory that recalls notes distilled from your AI coding conversations. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, macOS, Windows, Linux
- **Website:** https://zengliangyi.github.io/ChatCrystal/
- **Repository:** https://github.com/zengliangyi/chatcrystal/tree/HEAD/server
- **MCP Registry name:** io.github.ZengLiangYi/chatcrystal
- **Categories:** knowledge and memory, developer tools
- **Listing updated:** 2026-11-14

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
claude mcp add chatcrystal --env CHATCRYSTAL_API_TOKEN='<CHATCRYSTAL_API_TOKEN>' -- npx -y chatcrystal
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "chatcrystal": {
      "command": "npx",
      "args": [
        "-y",
        "chatcrystal"
      ],
      "env": {
        "CHATCRYSTAL_API_TOKEN": "<CHATCRYSTAL_API_TOKEN>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "chatcrystal": {
      "command": "npx",
      "args": [
        "-y",
        "chatcrystal"
      ],
      "env": {
        "CHATCRYSTAL_API_TOKEN": "<CHATCRYSTAL_API_TOKEN>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "chatcrystal": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "chatcrystal"
      ],
      "env": {
        "CHATCRYSTAL_API_TOKEN": "<CHATCRYSTAL_API_TOKEN>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "chatcrystal": {
      "command": "npx",
      "args": [
        "-y",
        "chatcrystal"
      ],
      "env": {
        "CHATCRYSTAL_API_TOKEN": "<CHATCRYSTAL_API_TOKEN>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "chatcrystal": {
      "command": "npx",
      "args": [
        "-y",
        "chatcrystal"
      ],
      "env": {
        "CHATCRYSTAL_API_TOKEN": "<CHATCRYSTAL_API_TOKEN>"
      }
    }
  }
}
```

## 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

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/chatcrystal
