Getting started with ChatCrystal: install, import, and search

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 0.6.1 at commit 7642768, 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. The commands below use the npm CLI.

The npm package file list 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:

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

crystal serve -d
crystal status

The default server port is 3721. Runtime path resolution 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:

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:

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. For the configuration distinction, read LLMs and embeddings.

Import and select one conversation

crystal import
crystal status
crystal summarize

On first startup with an empty database, initialization 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:

crystal summarize <conversation-id>
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.