ChatCrystal

io.github.ZengLiangYiPublished by GitHub account ZengLiangYiv0.6.2Updated Oct 30, 2026

Local-first AI PKM memory for coding conversations.

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

Local-first personal knowledge base for AI coding conversations, letting an assistant search distilled notes and recall or save reusable task memories.

What you can do
  • Search and browse notes: semantic search, paginated note summaries filtered by tag or keyword, and full note content with conclusions and code snippets
  • Explore note relationships with relationship type and confidence score
  • Recall task memories before coding, debugging, migration, refactor or optimization work, loading project-scoped memories first and global lessons second
  • Validate a candidate task memory as a dry run, then persist it as a structured note when it is durable and reusable
When to use it
Useful when you want an assistant to draw on lessons from earlier AI coding sessions, such as pitfalls, fixes and decisions, instead of repeating them. Best suited to developers who already collect conversations from tools like Claude Code, Cursor or Codex CLI into a local ChatCrystal knowledge base.
Requirements
Runs as a local stdio process, typically via npx or the crystal mcp command, and needs Node.js 20 or newer. A ChatCrystal Core instance must be running, by default at localhost:3721, or a remote/cloud instance set through CHATCRYSTAL_BASE_URL. An LLM and embedding provider (Ollama, OpenAI, Anthropic, Google, Azure or an OpenAI-compatible API) must be configured for summarizing and search. CHATCRYSTAL_API_TOKEN is optional for protected cloud instances.
Before you install
The knowledge base is built by scanning local conversation histories from AI coding tools, so those transcripts, including code and prompts, are stored locally and, in cloud mode, uploaded to the configured instance. write_task_memory writes new notes to the knowledge base. LLM and embedding API keys are configured in ChatCrystal settings and sent to the chosen provider. Prefer HTTPS for cloud connections, and treat CHATCRYSTAL_API_TOKEN as a secret.

Installation

In SourceWeft

  1. Open ChatCrystal in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[ChatCrystal]

ChatCrystal

Crystallize knowledge from your AI conversations

[npm] [GitHub] [License: Apache-2.0]

ChatCrystal collects conversations from AI coding tools (Claude Code, Cursor, Codex CLI, Trae, GitHub Copilot), uses LLM to distill them into searchable structured notes, and builds your personal knowledge base.

Install

bash
npm install -g chatcrystal

Requires Node.js >= 20 and an LLM service (Ollama, OpenAI, OrcaRouter, Anthropic, Google AI, or any OpenAI-compatible API).

Quick Start

bash
crystal import                     # Scan and import AI conversationscrystal summarize --all            # Batch summarize into notescrystal search "React state"       # Semantic search your knowledge

The server auto-launches in background on first command. No manual setup needed.

Cloud Connection

For a Docker cloud instance, save the shared token once:

bash
crystal connect https://chatcrystal.example.com --token "your-long-token"crystal import --yes

crystal import still scans and parses histories on the local device, then uploads normalized conversations to the cloud instance. The cloud server does not scan your local filesystem. crystal mcp reuses the same saved connection and token.

HTTPS is recommended for cloud connections, but HTTP works when that is the deployment you choose.

To manage a Docker cloud token:

bash
# Rotate when you still know the current token.crystal --base-url https://chatcrystal.example.com token rotate "new-long-token-at-least-16-chars" --current "old-token"
# Reset stored auth from the Docker host when the token is lost.docker compose exec chatcrystal crystal token reset --yesdocker compose exec chatcrystal cat /data/setup-code

If CHATCRYSTAL_API_TOKEN is set in the deployment environment, change that environment variable and recreate the container instead of using token reset.

CLI Commands

bash
# Knowledge retrievalcrystal search <query> [--limit 10]     # Semantic searchcrystal notes list [--tag X]            # Browse notescrystal notes get <id>                  # View note detailcrystal notes relations <id>            # View note relationscrystal tags                            # List tags with counts
# Data managementcrystal import [--source claude-code]   # Import conversationscrystal summarize <id>                  # Summarize one conversationcrystal summarize --all                 # Batch summarizecrystal summarize --retry-errors        # Retry failed summariescrystal status                          # Server status and DB stats
# Configurationcrystal config get                      # View configcrystal config set llm.provider openai  # Update configcrystal config test                     # Test LLM connection
# Server managementcrystal serve                           # Start server (foreground)crystal serve -d                        # Start server (daemon)crystal serve stop                      # Stop daemoncrystal serve status                    # Check if running

Global options: --base-url <url> (server address), --token <token> (cloud API token), --json (force JSON output), --version

Output: TTY-aware — colored tables in terminal, JSON when piped.

MCP Server

Integrate with AI coding tools so they can retrieve knowledge from your conversation history during coding.

bash
crystal mcp                             # Start MCP stdio server

Claude Code

Add to settings.json:

json
{  "mcpServers": {    "chatcrystal": {      "command": "crystal",      "args": ["mcp"]    }  }}

MCP Tools

ToolDescription
search_knowledgeSemantic search across notes when you need relevance-ranked matches
get_noteGet full note content (summary, conclusions, code snippets)
list_notesBrowse paginated note summaries by tag or title/summary keyword
get_relationsGet related notes with relationship types
recall_for_taskRead-only task recall that loads project memories first, then optional global lessons
validate_task_memoryDry-run validation before writing a task memory; returns acceptance, reasons, warnings, and note fields
write_task_memoryPersist reusable task memories after meaningful work

Configuration

Runtime configuration is stored in config.json under the active data directory. CLI, MCP, repo/dev checkouts, npm global installs, and Electron default to ~/.chatcrystal/data. Use crystal config set for persistent config. .env remains available only as an optional local override layer.

bash
# LLM (ollama/openai/orcarouter/anthropic/google/azure/custom)crystal config set llm.provider openaicrystal config set llm.model gpt-4ocrystal config set llm.apiKey sk-...
# Embedding (ollama/openai/google/azure/custom)crystal config set embedding.provider ollamacrystal config set embedding.model nomic-embed-text

OrcaRouter uses ChatCrystal's built-in https://api.orcarouter.ai/v1 Base URL. Set llm.provider to orcarouter, provide an API Key, and select a discovered model in the Web UI; no llm.baseURL is required. Get an OrcaRouter API Key.

Data Sources

Automatically detects and imports from:

SourcePath
Claude Code~/.claude/projects/**/*.jsonl
Codex CLI~/.codex/sessions/**/*.jsonl
CursorPlatform-specific state.vscdb
TraePlatform-specific state.vscdb
GitHub CopilotVS Code chatSessions/*.jsonl / *.json

Web UI & Desktop App

ChatCrystal also has a web UI and Electron desktop app. See the GitHub repository for details.

License

Apache License 2.0

Source: server/README.md at commit 7642768

Tools

7

search_knowledge

Semantic search across your AI conversation knowledge base. Returns matching notes ranked by relevance.

Parameterslimitqueryrequired

get_note

Get the full content of a note including title, summary, key conclusions, code snippets, and tags.

Parametersidrequired

list_notes

List note summaries for browsing and narrowing the ChatCrystal knowledge base. Use this when you need paginated notes filtered by tag or title/summary keyword. Use search_knowledge instead for semantic relevance ranking, and get_note when you already have an id and need the full note body. Returns note metadata and summaries, not full note content.

Parameterstagpagesearch

get_relations

Get related notes for a given note, including relationship type and confidence score.

ParametersnoteIdrequired

recall_for_task

Retrieve reusable task memories before starting substantive coding work. Use this at the beginning of implementation, debugging, migration, configuration, investigation, refactor, or optimization tasks to load project-scoped memories first and optional global lessons second. Use mode="debug" when the user reports an error, failing command, regression, or incident; include error_signatures and related_files when available. Use search_knowledge instead for ad hoc semantic note search that is not tied to the current task. This tool is read-only and returns ranked memories plus optional related-note context without writing anything.

Parametersmodetaskrequiredoptions

validate_task_memory

Dry-run validation for a candidate task memory before calling write_task_memory. Use this after meaningful work and before persisting a lesson to check whether the candidate is durable, specific, reusable, and shaped like a high-quality ChatCrystal note. It has no side effects and never writes to the knowledge base. Returns acceptance, rejection reason, warnings, and materialized note fields so agents can revise the candidate or skip weak work logs.

Parametersmoderequiredtaskrequiredscopememoryrequiredsource_run_key

write_task_memory

Persist a task memory only when it can become a high-quality ChatCrystal note: specific title, concrete summary, meaningful key conclusions, and a durable reusable lesson such as a pitfall, fix, decision, pattern, or symptom-to-resolution mapping. Do not write one-time environment checks, version/status reports, ordinary progress logs, or vague robustness claims. Weak auto writebacks are skipped by core validation and recorded only as receipts.

Parametersmoderequiredtaskrequiredscopememoryrequiredsource_run_key

Version history

3
  1. v0.6.2LatestOct 23, 2026
  2. v0.6.1Sep 20, 2026
  3. v0.6.0Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts