--- title: "Getting started with ChatCrystal: install, import, and search" description: Verify installation, the local service, both model configurations, import, summarization, and search with the actual ChatCrystal 0.6.1 CLI. image: "https://zengliangyi.com/og/blog/en/chatcrystal-getting-started.png" --- Turning AI coding conversations into reusable notes requires several working paths: the tool starts, history imports, models process it, and notes can be retrieved. Verify one record first. That makes failures easier to locate than processing all your history immediately. This guide targets [ChatCrystal](/en/projects/chatcrystal) 0.6.1 at commit [`7642768`](https://github.com/ZengLiangYi/ChatCrystal/tree/764276814e5c5a33ecbfeae63754f74b9261a3a8), using a local CLI workflow. Downloads and inference depend on your network and hardware; there is no promised completion time. ## Choose an installation entry point The desktop application and npm package are different artifacts. For a window that displays conversations, select a desktop release for your platform from [GitHub Releases](https://github.com/ZengLiangYi/ChatCrystal/releases). The commands below use the npm CLI. The [npm package file list](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/package.json) includes compiled server and shared modules, without `client/dist`. The server serves a web interface only when it finds a frontend build directory. Installing the npm package therefore does not guarantee a complete interface at port 3721; the CLI can call the API directly for this workflow. ## Install and verify the command This package version declares Node.js 24 or later. Check the environment, then install the version covered here: ```bash node --version npm install -g chatcrystal@0.6.1 crystal --version crystal --help ``` If `crystal` is missing, check whether the global executable directory associated with `npm prefix -g` is on `PATH`, and whether this terminal uses the Node installation you just configured. Open a new terminal and verify again before repeatedly reinstalling across different Node managers. ## Start the local service ```bash crystal serve -d crystal status ``` The default server port is 3721. [Runtime path resolution](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/runtime/paths.ts) defaults to `.chatcrystal/data` in your home directory; `DATA_DIR` can select another location before startup. Record the actual directory. Backups must account for the database, configuration, and vector index. This workflow uses the default local port and implicit local connection. For a conflict, identify the process occupying the port and coordinate use of the default. The current CLI rejects explicitly configured loopback connections that do not report cloud mode, so changing to 3722 and passing `--base-url` cannot be promised to make this local workflow work. Saved remote settings can also change the command target; inspect the connection information in status first. ## Configure generation and retrieval separately The language model produces structured notes; the embedding model produces search vectors. These two Ollama models appear in the current defaults and serve as a reproducible example. Evaluate suitability for your hardware and material separately. After installing and starting [Ollama](https://docs.ollama.com/quickstart): ```bash ollama pull qwen2.5:7b ollama pull nomic-embed-text crystal config get ``` Confirm both configurations point to your local model service. To reset the relevant settings: ```bash crystal config set llm.provider ollama crystal config set llm.baseURL http://localhost:11434 crystal config set llm.model qwen2.5:7b crystal config set embedding.provider ollama crystal config set embedding.baseURL http://localhost:11434 crystal config set embedding.model nomic-embed-text crystal config test ``` With an existing index, some embedding changes require confirmation. Read the warnings and plan rebuilding before adding `--confirm`. The connection test reports LLM and embedding results separately; inspect both. Its short requests do not establish long-conversation summary quality or successful indexing of every note. Local storage does not establish local inference. Remote endpoints receive the relevant text; see [local-first data boundaries](/en/blog/local-first-ai-data-boundaries). For the configuration distinction, read [LLMs and embeddings](/en/blog/llm-and-embedding-separation). ## Import and select one conversation ```bash crystal import crystal status crystal summarize ``` On first startup with an empty database, [initialization](https://github.com/ZengLiangYi/ChatCrystal/blob/764276814e5c5a33ecbfeae63754f74b9261a3a8/server/src/services/seed.ts) attempts to insert demo conversations and notes. Records starting with `demo-` are not your imported history, and a nonzero status total does not establish successful real import. Default local import scans enabled sources and stores parseable history in the application database. Successful import alone does not generate notes. With no argument, `summarize` lists pending conversations so you can choose an ID. Scanned, skipped, and failed counts mean different things. If no conversations appear, check available history, source paths, and the server process’s read permissions. If the command asks to confirm a remote upload, inspect the target address. In cloud mode, the CLI scans local history and uploads parsed conversations; that is a different data path from importing into the local database. ## Generate a note and check search Choose a genuinely imported conversation containing a concrete problem, resolution, and verification or reusable experience. Replace the example position below with that ID, rather than selecting a demo record: ```text crystal summarize crystal notes list crystal --json search "a specific error or solution discussed earlier" --limit 5 ``` The search uses `--json` to select the non-interactive branch that forwards `--limit`; its return value is an array of results. Check that the summary retains the problem’s conditions, resolution, and verification. Then inspect the returned search notes. Summarization first applies an experience gate. A conversation that does not qualify can normally become `filtered`, return an empty result, and produce no note; this differs from a failed model call. Continue verification with another history containing useful experience. Note creation does not prove vectors are ready: summarization, indexing, and the query endpoint can fail separately. An empty result can also reflect thresholds or phrasing, so a single query does not establish data loss. The acceptance criteria are a traceable original conversation, a trustworthy note, and a search result whose source you can understand. Once that path works, consider batch summarization and agent integration. Use `crystal serve status` to inspect the service and `crystal serve stop` to stop the local daemon; stopping it does not replace a backup. Share: ## Related Posts [## Exporting ChatCrystal Notes to Obsidian Export every page of ChatCrystal notes, build Obsidian links with stable IDs, and distinguish a readable snapshot from editing and incremental synchronization. 曾亮懿 June 11, 2026 6 min read #ChatCrystal #Obsidian #Node.js #Knowledge management](/en/blog/chatcrystal-to-obsidian) [## AI Conversation Formats: JSONL Events vs SQLite Snapshots Compare 5 AI adapter formats: separate JSONL events from SQLite keys, and inspect indexed, orphan, and unknown-version chat transcripts in memory stores. 曾亮懿 October 7, 2026 4 min read #ChatCrystal #Node.js #SQLite](/en/blog/ai-conversation-format-divergence) [## How Claude Code, Cursor, Copilot, and Trae Store Chats on Disk Compare Claude Code, Cursor, Copilot, and Trae storage paths. Distinguish raw copies from exports, and verify migration retention with test manifests. 曾亮懿 October 7, 2026 4 min read #ChatCrystal #Node.js #SQLite](/en/blog/ai-conversation-management-options) ## From writing to code Explore ChatCrystal, developer tools and daily learning notes on my GitHub. Questions about the implementation are welcome. [Visit my GitHub](https://github.com/ZengLiangYi) ```json { "@context": "https://schema.org", "@type": "WebSite", "name": "ZengLiangYi Blog", "alternateName": [ "Zeng Liangyi", "ZengLiangYi", "zengliangyi.com" ], "url": "https://zengliangyi.com", "description": "曾亮懿的个人网站。记录 AI Native 探索、开发者工具与全栈产品实践。" } { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "Getting started with ChatCrystal: install, import, and search", "description": "Verify installation, the local service, both model configurations, import, summarization, and search with the actual ChatCrystal 0.6.1 CLI.", "url": "https://zengliangyi.com/en/blog/chatcrystal-getting-started/", "image": "https://zengliangyi.com/images/blog/chatcrystal-getting-started.svg", "datePublished": "2026-10-03T00:00:00.000Z", "dateModified": "2026-10-03T00:00:00.000Z", "author": { "@type": "Person", "name": "曾亮懿", "url": "https://zengliangyi.com/en/about" }, "publisher": { "@type": "Organization", "name": "ZengLiangYi Blog", "logo": { "@type": "ImageObject", "url": "https://zengliangyi.com/favicon-96x96.png" } }, "mainEntityOfPage": { "@type": "WebPage", "@id": "https://zengliangyi.com/en/blog/chatcrystal-getting-started/" } } { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://zengliangyi.com/en" }, { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://zengliangyi.com/en/blog" }, { "@type": "ListItem", "position": 3, "name": "Getting started with ChatCrystal: install, import, and search", "item": "https://zengliangyi.com/en/blog/chatcrystal-getting-started/" } ] } ```