Skip to content
MCP server

ChatCrystal

Local-first memory that recalls notes distilled from your AI coding conversations

Runs locallyStatus and history
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 chatcrystal

Add 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

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools