### Install Dependencies and Start Dev Server

Source: https://github.com/zengliangyi/chatcrystal/blob/main/CONTRIBUTING.md

Clone the repository, install dependencies, and start the development server for both frontend and backend. Ensure Node.js version is 20 or higher.

```bash
git clone https://github.com/<your-username>/ChatCrystal.git
cd ChatCrystal

npm install

npm run dev
```

--------------------------------

### Install ChatCrystal from Source

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/USER_GUIDE.md

Clone the ChatCrystal repository and install dependencies to run the application from source. This starts the API server and Vite client.

```bash
git clone https://github.com/ZengLiangYi/ChatCrystal.git
cd ChatCrystal
npm install
npm run dev
```

--------------------------------

### Install ChatCrystal CLI Globally

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/USER_GUIDE.md

Install the ChatCrystal command-line interface globally using npm. After installation, start the server and import data.

```bash
npm install -g chatcrystal
crystal serve -d
crystal import
```

--------------------------------

### CLI: Start Server (Foreground)

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Starts the ChatCrystal server in the foreground. This is the default mode.

```bash
crystal serve
```

--------------------------------

### Install ChatCrystal Task Writeback Skill

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/agent-skills.md

Installs the 'chatcrystal-task-writeback' skill from the ChatCrystal GitHub repository using the 'skills' CLI.

```bash
npx skills add https://github.com/ZengLiangYi/ChatCrystal --skill chatcrystal-task-writeback
```

--------------------------------

### Install ChatCrystal Core

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/agent-skills.md

Installs the ChatCrystal Core package globally using npm.

```bash
npm install -g chatcrystal
```

--------------------------------

### Install All ChatCrystal Skills

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/agent-skills.md

Installs all three ChatCrystal skills (task recall, debug recall, task writeback) from the repository by running individual commands.

```bash
npx skills add https://github.com/ZengLiangYi/ChatCrystal --skill chatcrystal-task-recall
npx skills add https://github.com/ZengLiangYi/ChatCrystal --skill chatcrystal-debug-recall
npx skills add https://github.com/ZengLiangYi/ChatCrystal --skill chatcrystal-task-writeback
```

--------------------------------

### Install ChatCrystal Task Recall Skill

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/agent-skills.md

Installs the 'chatcrystal-task-recall' skill from the ChatCrystal GitHub repository using the 'skills' CLI.

```bash
npx skills add https://github.com/ZengLiangYi/ChatCrystal --skill chatcrystal-task-recall
```

--------------------------------

### Production Server

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Starts the production server, which serves the frontend statically on port 3721.

```bash
npm start
```

--------------------------------

### Install ChatCrystal Debug Recall Skill

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/agent-skills.md

Installs the 'chatcrystal-debug-recall' skill from the ChatCrystal GitHub repository using the 'skills' CLI.

```bash
npx skills add https://github.com/ZengLiangYi/ChatCrystal --skill chatcrystal-debug-recall
```

--------------------------------

### Start Local ChatCrystal Server

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/agent-skills.md

Starts the local ChatCrystal server in detached mode.

```bash
crystal serve -d
```

--------------------------------

### Start MCP stdio server

Source: https://github.com/zengliangyi/chatcrystal/blob/main/server/README.md

Starts the MCP (Machine Communication Protocol) stdio server for integration with AI coding tools.

```bash
crystal mcp                             # Start MCP stdio server
```

--------------------------------

### ChatCrystal Quick Start Commands

Source: https://github.com/zengliangyi/chatcrystal/blob/main/server/README.md

Basic commands to import conversations, summarize them, and search your knowledge base.

```bash
crystal import
crystal summarize --all
crystal search "React state"
```

--------------------------------

### Electron Main Process Setup

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

The main process for the Electron app. Handles single-instance locking, embedded Fastify server startup, window creation, and system tray management.

```typescript
// electron/main.ts
import { app, BrowserWindow, ipcMain, Tray, Menu } from 'electron';
import path from 'path';
import Fastify from 'fastify';
import cors from '@fastify/cors';

let mainWindow: BrowserWindow | null;
let tray: Tray | null;

const isSecondInstance = app.requestSingleInstanceLock();
if (isSecondInstance) {
  app.quit();
}
app.on('second-instance', () => {
  if (mainWindow) {
    if (mainWindow.isMinimized()) mainWindow.restore();
    mainWindow.focus();
  }
});

const createWindow = async () => {
  mainWindow = new BrowserWindow({
    width: 1024,
    height: 768,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      // contextIsolation: true, // Default is true
      // nodeIntegration: false, // Default is false
    },
  });

  // Load the index.html of the app.
  // Use file:// URL for packaged apps
  const indexPath = path.join(__dirname, '../client/dist/index.html');
  await mainWindow.loadURL(`file://${indexPath}`);

  // Open the DevTools (optional)
  // mainWindow.webContents.openDevTools();

  mainWindow.on('closed', () => {
    mainWindow = null;
  });

  // Setup System Tray
  setupTray();
};

const setupTray = () => {
  const iconPath = process.env.ELECTRON_PACKAGED
    ? path.join(process.resourcesPath, 'icon.png')
    : path.join(__dirname, '../icon.png'); // Adjust path for development

  tray = new Tray(iconPath);
  const contextMenu = Menu.buildFromTemplate([
    { label: 'Show App', click: () => mainWindow?.show() },
    { label: 'Open in Browser', click: () => mainWindow?.webContents.openDevTools() }, // Placeholder
    { type: 'separator' },
    { label: 'Quit', role: 'quit' },
  ]);
  tray.setToolTip('Chatcrystal');
  tray.setContextMenu(contextMenu);

  tray.on('click', () => {
    mainWindow?.show();
  });
};

const startEmbeddedServer = async () => {
  const server = Fastify({
    logger: { prettyPrint: true },
  });
  await server.register(cors, { origin: '*' });

  server.get('/api/version', async () => ({ version: app.getVersion() }));

  // Add other API routes here...

  try {
    await server.listen({ port: 0 }); // Port 0 lets the OS choose a free port
    const address = server.server.address();
    if (address && typeof address === 'object' && address.port) {
      console.log(`Embedded server listening on port ${address.port}`);
      // Optionally communicate this port to the renderer process
      ipcMain.handle('get-server-port', () => address.port);
    }
  } catch (err) {
    console.error('Failed to start embedded server:', err);
  }
};

app.whenReady().then(async () => {
  await startEmbeddedServer();
  await createWindow();

  app.on('activate', () => {
    if (BrowserWindow.getAllWindows().length === 0) {
      createWindow();
    }
  });
});

app.on('window-all-closed', () => {
  if (process.platform !== 'darwin') {
    // Keep the app running in the background if tray icon exists
    if (!tray) {
      app.quit();
    }
  }
});

app.on('before-quit', async () => {
  // Graceful shutdown logic: stop watcher, save DB, close server, destroy tray
  console.log('App is quitting. Performing graceful shutdown...');
  // Example: await stopWatcher();
  // Example: await dbService.saveAll();
  // Example: await embeddedServer.close();
  if (tray) {
    tray.destroy();
  }
});

```

--------------------------------

### Agent Configuration for ChatCrystal MCP

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/MCP.md

Configure your agent to connect to the ChatCrystal MCP server using its command and arguments. This example shows the basic setup for the 'chatcrystal' MCP server.

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

--------------------------------

### Electron App Build

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Builds the Electron desktop application and creates an NSIS installer in the 'release/' directory.

```bash
npm run build:electron
```

--------------------------------

### Start the MCP Server

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/MCP.md

Use the `crystal mcp` command to start the ChatCrystal MCP server. This server uses stdio transport and can be configured via `command` and `args`.

```bash
crystal mcp
```

--------------------------------

### ChatCrystal Configuration JSON Example

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/USER_GUIDE.md

Example of the config.json file used by ChatCrystal to store runtime configuration for LLM and embedding providers.

```json
{
  "llm": {
    "provider": "ollama",
    "baseURL": "http://localhost:11434",
    "model": "qwen2.5:7b",
    "apiKey": ""
  },
  "embedding": {
    "provider": "ollama",
    "baseURL": "http://localhost:11434",
    "model": "nomic-embed-text",
    "apiKey": ""
  },
  "enabledSources": ["claude-code", "codex", "cursor", "trae", "copilot"]
}
```

--------------------------------

### Fastify Server Setup

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

The backend is built with Fastify v5, including CORS and static file serving for production SPA fallback. It uses sql.js for SQLite database management.

```typescript
import Fastify from "fastify";
import cors from "@fastify/cors";
import staticFiles from "@fastify/static";
import path from "path";

const server = Fastify({
  logger: true,
});

server.register(cors, {
  origin: "*", // Adjust for production
});

// Serve static files for production SPA fallback
server.register(staticFiles, {
  root: path.join(__dirname, "../client/dist"),
  prefix: "/",
  index: "index.html",
  // Enable fallback for SPA routing
  fallback: "index.html",
});

// Example route
server.get("/api/status", async (request, reply) => {
  return { status: "ok", version: "1.0.0" };
});

const start = async () => {
  try {
    await server.listen({ port: 3000, host: "0.0.0.0" });
    console.log(`Server listening on http://localhost:3000`);
  } catch (err) {
    server.log.error(err);
    process.exit(1);
  }
};

start();

```

--------------------------------

### Development Server

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Starts the development server with hot module replacement for both the server and client. The server runs on port 3721 and the client on port 13721.

```bash
npm run dev
```

--------------------------------

### Build and Run ChatCrystal Desktop App

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/USER_GUIDE.md

Build and run the Electron-based desktop application for ChatCrystal. The installer is generated in the 'release/' directory.

```bash
npm run dev:electron
npm run build:electron
```

--------------------------------

### Get Configuration

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/DEVELOPMENT.md

Fetches the current configuration, with sensitive information redacted.

```APIDOC
## GET /api/config

### Description
Fetches the current configuration, with sensitive information redacted.

### Method
GET

### Endpoint
/api/config

### Response
#### Success Response (200)
- **field1** (type) - Description
```

--------------------------------

### PR Title Format Example

Source: https://github.com/zengliangyi/chatcrystal/blob/main/CONTRIBUTING.md

Example of a Pull Request title adhering to the commit convention format.

```text
feat(client): add dark mode toggle
```

--------------------------------

### Docker Compose Deployment

Source: https://github.com/zengliangyi/chatcrystal/blob/main/README.md

Clone the repository, navigate to the directory, and start the ChatCrystal service using Docker Compose. This command pulls the latest image and runs it in detached mode.

```bash
git clone https://github.com/ZengLiangYi/ChatCrystal.git
cd ChatCrystal
docker compose up -d
```

--------------------------------

### React SPA Setup

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

A React Single Page Application built with Vite v8 and React Router v7. It uses TanStack React Query for state management and Tailwind CSS for styling.

```typescript
// client/src/main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import { App } from './App';
import './index.css';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { BrowserRouter } from 'react-router-dom';

const queryClient = new QueryClient();

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <BrowserRouter>
      <QueryClientProvider client={queryClient}>
        <App />
      </QueryClientProvider>
    </BrowserRouter>
  </React.StrictMode>
);

```

--------------------------------

### ChatCrystal CLI Commands - Server Management

Source: https://github.com/zengliangyi/chatcrystal/blob/main/server/README.md

Commands for managing the ChatCrystal server, including starting, stopping, and checking its status.

```bash
# Server management
crystal serve                           # Start server (foreground)
crystal serve -d                        # Start server (daemon)
crystal serve stop                      # Stop daemon
crystal serve status                    # Check if running
```

--------------------------------

### Create a New Feature Branch

Source: https://github.com/zengliangyi/chatcrystal/blob/main/CONTRIBUTING.md

Branching strategy for starting new feature development from the main branch.

```bash
git checkout -b feat/your-feature
```

--------------------------------

### Common ChatCrystal CLI Commands

Source: https://github.com/zengliangyi/chatcrystal/blob/main/README.md

Provides a list of common commands for interacting with the ChatCrystal server and its features, such as status checks, importing conversations, semantic search, managing notes, and starting the server.

```bash
crystal status                          # Server status and DB stats
crystal import [--source claude-code]   # Scan and import conversations
crystal search "query" [--limit 10]     # Semantic search
crystal notes list [--tag X]            # Browse notes
crystal notes get <id>                  # View note detail
crystal summarize --all                 # Batch summarize
crystal config get                      # View config
crystal serve -d                        # Start server in background
crystal serve stop                      # Stop background server
crystal mcp                             # Start MCP stdio server
```

--------------------------------

### CLI: Get Note Detail

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Retrieves and displays the detailed content of a specific note using its ID.

```bash
crystal notes get <id>
```

--------------------------------

### Conventional Commits Format

Source: https://github.com/zengliangyi/chatcrystal/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification for various types and scopes.

```text
<type>(<scope>): <description>

feat(client): add dark mode toggle
fix(server): handle empty conversation parsing
docs: update README installation steps
```

--------------------------------

### Example Auto Writeback Input for write_task_memory

Source: https://github.com/zengliangyi/chatcrystal/blob/main/skills/chatcrystal-task-writeback/SKILL.md

This JSON payload demonstrates the structure required when calling `write_task_memory` in automatic mode after a task with a stable run key. It includes details about the task, the memory content, and the desired scope.

```json
{
  "mode": "auto",
  "source_run_key": "agent-session-or-run-id",
  "scope": "project",
  "task": {
    "goal": "Fix MCP recall schema validation",
    "task_kind": "debug",
    "project_dir": "/path/to/project",
    "cwd": "/path/to/project",
    "branch": "fix/mcp-recall-schema",
    "files_touched": [
      "server/src/services/memory/schemas.ts",
      "server/src/cli/mcp/server.ts"
    ],
    "error_signatures": [
      "invalid_type",
      "recall_for_task schema mismatch"
    ],
    "source_agent": "codex"
  },
  "memory": {
    "summary": "MCP tool schemas must stay aligned with memory service request shapes; mismatches surface as validation failures before tool execution.",
    "outcome_type": "fix",
    "root_cause": "The MCP tool input shape diverged from the service schema.",
    "resolution": "Reused the shared request shape in the MCP server registration.",
    "files_touched": [
      "server/src/services/memory/schemas.ts",
      "server/src/cli/mcp/server.ts"
    ],
    "tags": [
      "mcp",
      "memory-loop",
      "schema"
    ]
  }
}
```

--------------------------------

### Example MCP Input for Task Recall

Source: https://github.com/zengliangyi/chatcrystal/blob/main/skills/chatcrystal-task-recall/SKILL.md

Use this JSON structure when calling the `recall_for_task` function for implementation or investigation tasks. It specifies the task goal, kind, project context, and memory retrieval options.

```json
{
  "mode": "task",
  "task": {
    "goal": "Add a paginated notes export endpoint",
    "task_kind": "implement",
    "project_dir": "/path/to/project",
    "cwd": "/path/to/project",
    "branch": "feature/export-notes",
    "related_files": [
      "server/src/routes/notes.ts",
      "shared/types/index.ts"
    ],
    "source_agent": "codex"
  },
  "options": {
    "project_limit": 5,
    "global_limit": 3,
    "include_relations": true
  }
}
```

--------------------------------

### Rotate or Reset Docker Cloud Token

Source: https://github.com/zengliangyi/chatcrystal/blob/main/README.md

Commands to manage the API token for a Docker deployment. You can rotate an existing token or reset it if forgotten. The setup code can be found in the container logs or a file.

```bash
# If you still know the current token, rotate it online.
crystal --base-url https://chatcrystal.example.com token rotate "new-long-token-at-least-16-chars" --current "old-token"
crystal connect https://chatcrystal.example.com --token "new-long-token-at-least-16-chars"

# If you forgot the token and did not set CHATCRYSTAL_API_TOKEN, reset stored auth in the container.
docker compose exec chatcrystal crystal token reset --yes
docker compose logs chatcrystal --tail=80
docker compose exec chatcrystal cat /data/setup-code
```

--------------------------------

### Build for Production

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Compiles the project for production deployment.

```bash
npm run build
```

--------------------------------

### Get Queue Status

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/DEVELOPMENT.md

Retrieves the current status of the processing queue.

```APIDOC
## GET /api/queue/status

### Description
Retrieves the current status of the processing queue.

### Method
GET

### Endpoint
/api/queue/status

### Response
#### Success Response (200)
- **field1** (type) - Description
```

--------------------------------

### Electron App Pack

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Builds an unpacked directory for the Electron application, which is faster for testing purposes.

```bash
npm run pack:electron
```

--------------------------------

### Get Knowledge Graph Data

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/DEVELOPMENT.md

Retrieves data for the knowledge graph.

```APIDOC
## GET /api/relations/graph

### Description
Retrieves data for the knowledge graph.

### Method
GET

### Endpoint
/api/relations/graph

### Response
#### Success Response (200)
- **field1** (type) - Description
```

--------------------------------

### Get Note Detail

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/DEVELOPMENT.md

Retrieves the detailed content of a specific note by its ID.

```APIDOC
## GET /api/notes/:id

### Description
Retrieves the detailed content of a specific note by its ID.

### Method
GET

### Endpoint
/api/notes/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the note to retrieve.

### Response
#### Success Response (200)
- **field1** (type) - Description
```

--------------------------------

### Get Conversation Detail

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/DEVELOPMENT.md

Retrieves the detailed information for a specific conversation by its ID.

```APIDOC
## GET /api/conversations/:id

### Description
Retrieves the detailed information for a specific conversation by its ID.

### Method
GET

### Endpoint
/api/conversations/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the conversation to retrieve.

### Response
#### Success Response (200)
- **field1** (type) - Description
```

--------------------------------

### CLI: View Config

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Displays the current configuration settings of the ChatCrystal application.

```bash
crystal config get
```

--------------------------------

### Configure Google AI Provider via Environment Variables

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/USER_GUIDE.md

Set environment variables to configure the Google AI LLM provider, including API key and model.

```bash
LLM_PROVIDER=google
LLM_API_KEY=AIza...
LLM_MODEL=gemini-2.0-flash
```

--------------------------------

### Run Experience Quality Gate Calibration

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/EXPERIENCE_GATE.md

Execute the calibration suite for the experience quality gate. This command is used to test the gate's performance against a predefined set of sample cases.

```bash
npm run eval:experience -w server
```

--------------------------------

### Configure OpenAI-Compatible Service via Environment Variables

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/USER_GUIDE.md

Set environment variables to configure an OpenAI-compatible LLM service, including base URL, API key, and model.

```bash
LLM_PROVIDER=custom
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_API_KEY=your-key
LLM_MODEL=anthropic/claude-sonnet-4
```

--------------------------------

### Perform Project Release

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/DEVELOPMENT.md

Initiate the release process for the project. This script handles version bumping, git tagging, and pushing for CI/CD.

```bash
npm run release
```

--------------------------------

### Development Commands

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/DEVELOPMENT.md

Common commands for running, building, and testing the ChatCrystal application in development and production.

```bash
npm run dev                   # Server 3721 + client 13721
npm run build                 # Build server and client
npm start                     # Production server
npm run lint                  # Biome + client ESLint
npm run lint:fix              # Apply safe lint fixes
npm run test -w server        # Server tests
npm run dev:electron          # Electron dev mode
npm run build:electron        # Build Windows installer
npm run pack:electron         # Build unpacked Electron app
npm run eval:experience -w server
```

--------------------------------

### Perform Project Release with Specific Version

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/DEVELOPMENT.md

Execute the release process and set the version to a specific value, such as '1.0.0'.

```bash
npm run release -- 1.0.0
```

--------------------------------

### Semantic Search

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/DEVELOPMENT.md

Performs a semantic search based on a query and returns results. The `expand` query parameter can be used to get more detailed results.

```APIDOC
## GET /api/search

### Description
Performs a semantic search based on a query and returns results. The `expand` query parameter can be used to get more detailed results.

### Method
GET

### Endpoint
/api/search

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query.
- **expand** (boolean) - Optional - If true, returns expanded search results.

### Response
#### Success Response (200)
- **field1** (type) - Description
```

--------------------------------

### Configure Anthropic Provider via Environment Variables

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/USER_GUIDE.md

Set environment variables to configure the Anthropic LLM provider, including API key and model.

```bash
LLM_PROVIDER=anthropic
LLM_API_KEY=sk-ant-...
LLM_MODEL=claude-sonnet-4-20250514
```

--------------------------------

### Example MCP Input for Debug Recall

Source: https://github.com/zengliangyi/chatcrystal/blob/main/skills/chatcrystal-debug-recall/SKILL.md

This JSON structure is used when calling the `recall_for_task` function for debugging purposes. It specifies the mode, task details, and options for memory retrieval.

```json
{
  "mode": "debug",
  "task": {
    "goal": "Diagnose failing build after TypeScript upgrade",
    "task_kind": "debug",
    "project_dir": "/path/to/project",
    "cwd": "/path/to/project",
    "branch": "upgrade/typescript",
    "related_files": [
      "server/src/cli/mcp/server.ts",
      "tsconfig.base.json"
    ],
    "error_signatures": [
      "TS2322",
      "Type is not assignable"
    ],
    "source_agent": "codex"
  },
  "options": {
    "project_limit": 5,
    "global_limit": 3,
    "include_relations": true
  }
}
```

--------------------------------

### Build ChatCrystal from Source with Docker Compose

Source: https://github.com/zengliangyi/chatcrystal/blob/main/README.md

Use this command to build the ChatCrystal Docker image from source instead of pulling a pre-built image. This is useful for development or when using a specific build.

```bash
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build
```

--------------------------------

### Configure OpenAI Provider via Environment Variables

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/USER_GUIDE.md

Set environment variables to configure the OpenAI LLM provider, including API key and model.

```bash
LLM_PROVIDER=openai
LLM_API_KEY=sk-...
LLM_MODEL=gpt-4o
```

--------------------------------

### Configure OpenAI LLM

Source: https://github.com/zengliangyi/chatcrystal/blob/main/server/README.md

Set the LLM provider to OpenAI and specify the model and API key.

```bash
crystal config set llm.provider openai
crystal config set llm.model gpt-4o
crystal config set llm.apiKey sk-...
```

--------------------------------

### Perform Project Release with Version Increment

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/DEVELOPMENT.md

Execute the release process with a specified version increment. Use 'minor' for minor version bumps or 'major' for major version bumps.

```bash
npm run release -- minor
npm run release -- major
```

--------------------------------

### CLI: List Tags

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Lists all available tags along with their respective counts.

```bash
crystal tags
```

--------------------------------

### Demo Data Seeding Script

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

A Node.js (MJS) script designed to populate the database with sample demo data, useful for testing and demonstration purposes.

```javascript
// scripts/seed-demo.mjs
import Database from 'better-sqlite3';
import path from 'path';

// Assume DB path is configured or derived
const dbPath = path.join(process.env.DATA_DIR || '~/.chatcrystal/data', 'chatcrystal.db');
const db = new Database(dbPath);

function seedData() {
  console.log('Seeding demo data...');

  // Example: Insert sample conversations
  const insertConversation = db.prepare(
    'INSERT INTO conversations (id, title, createdAt) VALUES (?, ?, ?)'
  );
  insertConversation.run('conv-1', 'First Demo Conversation', new Date().toISOString());

  // Example: Insert sample messages
  const insertMessage = db.prepare(
    'INSERT INTO messages (conversationId, role, content, createdAt) VALUES (?, ?, ?, ?)'
  );
  insertMessage.run('conv-1', 'user', 'Hello, Chatcrystal!', new Date().toISOString());
  insertMessage.run('conv-1', 'assistant', 'Hi there! How can I help you today?', new Date().toISOString());

  // Add more seeding logic for other tables (notes, tags, etc.)

  console.log('Demo data seeding complete.');
}

try {
  seedData();
} catch (error) {
  console.error('Error seeding demo data:', error);
} finally {
  db.close();
}

```

--------------------------------

### ChatCrystal CLI Commands

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/USER_GUIDE.md

A list of available ChatCrystal CLI commands for managing the server, importing data, searching, browsing notes, and configuring settings.

```bash
crystal status                          # Server status and DB stats
crystal import [--source claude-code]   # Scan and import conversations
crystal search "query" [--limit 10]     # Semantic search
crystal notes list [--tag X]            # Browse notes
crystal notes get <id>                  # View note detail
crystal notes relations <id>            # View note relations
crystal tags                            # List tags with counts
crystal summarize <id>                  # Summarize one conversation
crystal summarize --all                 # Batch summarize
crystal config get                      # View config
crystal config set llm.provider openai  # Update config
crystal config test                     # Test LLM connection
crystal serve -d                        # Start server in background
crystal serve stop                      # Stop background server
crystal mcp                             # Start MCP stdio server
```

--------------------------------

### Electron App Development

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Runs the Electron desktop application in development mode, enabling Vite HMR and an Electron window for rapid development.

```bash
npm run dev:electron
```

--------------------------------

### CLI: Import Conversations

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Scans and imports conversations from specified AI coding tools. Use the --source flag to specify the tool, e.g., 'claude-code'.

```bash
crystal import [--source claude-code]
```

--------------------------------

### Run Primary Server Tests

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/DEVELOPMENT.md

Execute primary verification tests for the server component. Use these focused tests during development iterations.

```bash
npm run test -w server
npm run build
npm run lint
npm run eval:experience -w server
```

--------------------------------

### CLI: List Notes

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Browses a list of generated notes. Use the --tag option to filter notes by a specific tag.

```bash
crystal notes list [--tag X]
```

--------------------------------

### ChatCrystal CLI Commands - Configuration

Source: https://github.com/zengliangyi/chatcrystal/blob/main/server/README.md

Commands for viewing and updating ChatCrystal configuration, including LLM provider settings.

```bash
# Configuration
crystal config get                      # View config
crystal config set llm.provider openai  # Update config
crystal config test                     # Test LLM connection
```

--------------------------------

### CLI: Test LLM Connection

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Tests the connection to the configured LLM provider.

```bash
crystal config test
```

--------------------------------

### Import Local History to Cloud Instance

Source: https://github.com/zengliangyi/chatcrystal/blob/main/README.md

Connect to a remote ChatCrystal instance using a token and then import local AI conversation histories. The CLI handles parsing locally and uploading to the cloud.

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

--------------------------------

### Import Service

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Handles scanning data sources, deduplicating entries based on file size and modification time, and performing batch inserts into the database.

```typescript
// services/import.ts
import fs from "fs";
import path from "path";
import { DatabaseService } from "./db";

interface FileInfo {
  path: string;
  size: number;
  mtime: Date;
}

export class ImportService {
  constructor(private dbService: DatabaseService) {}

  async scanDirectory(dirPath: string): Promise<FileInfo[]> {
    let files: FileInfo[] = [];
    const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });

    for (const entry of entries) {
      const fullPath = path.join(dirPath, entry.name);
      if (entry.isDirectory()) {
        files = files.concat(await this.scanDirectory(fullPath));
      } else if (entry.isFile()) {
        const stats = await fs.promises.stat(fullPath);
        files.push({
          path: fullPath,
          size: stats.size,
          mtime: stats.mtime,
        });
      }
    }
    return files;
  }

  async importFiles(sourcePaths: string[]): Promise<void> {
    let allFiles: FileInfo[] = [];
    for (const sourcePath of sourcePaths) {
      allFiles = allFiles.concat(await this.scanDirectory(sourcePath));
    }

    const existingFiles = await this.dbService.getExistingFiles(); // Fetch metadata of already imported files

    const filesToImport = allFiles.filter(file => {
      const existing = existingFiles.find(ef => ef.path === file.path);
      // Deduplicate by path, size, and mtime
      return !existing || existing.size !== file.size || existing.mtime.getTime() !== file.mtime.getTime();
    });

    // Prepare data for batch insert
    const importData = filesToImport.map(file => ({
      path: file.path,
      size: file.size,
      mtime: file.mtime.toISOString(),
      // Add other relevant data extracted from the file content here
    }));

    if (importData.length > 0) {
      await this.dbService.batchInsertFiles(importData);
      console.log(`Imported ${importData.length} new or updated files.`);
    } else {
      console.log("No new or updated files to import.");
    }
  }
}

```

--------------------------------

### ChatCrystal MCP Tools

Source: https://github.com/zengliangyi/chatcrystal/blob/main/server/README.md

List of available MCP tools for integrating AI coding tools with ChatCrystal's knowledge base.

```markdown
| Tool |
|------|
| `search_knowledge` | Semantic search across notes |
| `get_note` | Get full note content (summary, conclusions, code snippets) |
| `list_notes` | Browse notes by tag or keyword |
| `get_relations` | Get related notes with relationship types |
| `recall_for_task` | Recall project-first memories for a coding task |
| `write_task_memory` | Persist reusable task memories after meaningful work |
```

--------------------------------

### Configure Ollama Embedding

Source: https://github.com/zengliangyi/chatcrystal/blob/main/server/README.md

Set the embedding provider to Ollama and specify the embedding model.

```bash
crystal config set embedding.provider ollama
crystal config set embedding.model nomic-embed-text
```

--------------------------------

### Release Script

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

A release helper script written in Node.js (MJS) to automate version bumping, tagging, and pushing Git repositories.

```javascript
// scripts/release.mjs
import { execSync } from 'child_process';
import readline from 'readline';

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
});

function askQuestion(query) {
  return new Promise(resolve => rl.question(query, resolve));
}

async function release() {
  try {
    const currentVersion = execSync('git describe --tags --abbrev=0').toString().trim();
    console.log(`Current version: ${currentVersion}`);

    const answer = await askQuestion('Enter new version (e.g., 1.2.3): ');
    const newVersion = answer.trim();

    if (!newVersion) {
      console.log('New version is required.');
      rl.close();
      return;
    }

    // 1. Update version in package.json (example)
    // execSync(`npm version ${newVersion} --no-git-tag-version`);
    console.log(`Simulating version update to ${newVersion}`);

    // 2. Create Git tag
    execSync(`git tag v${newVersion}`);
    console.log(`Created Git tag v${newVersion}`);

    // 3. Push tag
    execSync('git push origin --tags');
    console.log('Pushed tags to origin.');

    console.log('Release process completed successfully!');
  } catch (error) {
    console.error('Release process failed:', error.message);
  } finally {
    rl.close();
  }
}

release();

```

--------------------------------

### Electron System Tray

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Manages the system tray icon and context menu for the Electron application. Provides options to show the window, open in browser, and quit.

```typescript
// electron/tray.ts (Conceptual - logic often integrated into main.ts)
import { Tray, Menu, app, BrowserWindow } from 'electron';
import path from 'path';

export function setupTray(mainWindow: BrowserWindow | null) {
  const iconPath = process.env.ELECTRON_PACKAGED
    ? path.join(process.resourcesPath, 'icon.png')
    : path.join(__dirname, '../icon.png'); // Adjust path for development

  const tray = new Tray(iconPath);

  const contextMenu = Menu.buildFromTemplate([
    { label: 'Show App', click: () => mainWindow?.show() },
    { label: 'Open in Browser', click: () => {
        // Logic to open in default browser, potentially with a specific URL
        console.log('Open in browser clicked');
      }
    },
    { type: 'separator' },
    { label: 'Quit', role: 'quit' },
  ]);

  tray.setToolTip('Chatcrystal');
  tray.setContextMenu(contextMenu);

  tray.on('click', () => {
    if (mainWindow) {
      if (mainWindow.isMinimized()) mainWindow.restore();
      mainWindow.show();
    }
  });

  return tray;
}

```

--------------------------------

### Pull Ollama Models for ChatCrystal

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/USER_GUIDE.md

Ensure that the necessary embedding and LLM models are downloaded and available in Ollama for ChatCrystal to use.

```bash
ollama pull qwen2.5:7b
ollama pull nomic-embed-text
```

--------------------------------

### CLI: View Note Relations

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Displays the relationships between a specific note and other notes, identified by its ID.

```bash
crystal notes relations <id>
```

--------------------------------

### Copilot Adapter

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Parses JSONL session snapshots from VS Code's workspace storage. Handles sessions with `kind:0` and extracts request/response arrays.

```typescript
// adapters/copilot.ts
import { SourceAdapter } from "../parser/SourceAdapter";
import fs from "fs";

interface CopilotSession {
  kind: number;
  // Other session properties...
  chat: {
    // Assuming chat structure contains requests and responses
    requests: Array<{ message: { content: string } }>;
    responses: Array<{ message: { content: string } }>;
  };
}

export class CopilotAdapter implements SourceAdapter {
  async parse(filePath: string): Promise<any[]> {
    const content = await fs.promises.readFile(filePath, "utf-8");
    const sessions: CopilotSession[] = content.split("\n").map(JSON.parse);
    const conversations = [];

    for (const session of sessions) {
      if (session.kind === 0 && session.chat) {
        const conversation = [];
        for (const req of session.chat.requests) {
          conversation.push({ role: "user", content: req.message.content });
        }
        for (const res of session.chat.responses) {
          conversation.push({ role: "assistant", content: res.message.content });
        }
        conversations.push(conversation);
      }
    }
    return conversations;
  }
}

```

--------------------------------

### Electron Preload Script

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

A minimal preload script for the Electron app's renderer process. It exposes essential APIs like `electronAPI.isElectron` and version information via contextBridge.

```typescript
// electron/preload.ts
import { contextBridge, ipcRenderer, App } from 'electron';

declare global {
  interface Window {
    electronAPI: {
      isElectron: boolean;
      getAppVersion: () => string;
      getServerPort: () => Promise<number>;
    };
  }
}

contextBridge.exposeInMainWorld('electronAPI', {
  isElectron: true,
  getAppVersion: () => app.getVersion(), // Assuming 'app' is available or passed via IPC
  getServerPort: async () => {
    try {
      return await ipcRenderer.invoke('get-server-port');
    } catch (error) {
      console.error('Error invoking getServerPort:', error);
      return 0; // Return 0 or throw error if port is critical
    }
  },
});

// If 'app' is not directly available, you might need to expose it via IPC as well:
// ipcRenderer.invoke('get-app-version').then(version => {
//   contextBridge.exposeInMainWorld('electronAPI', { ..., getAppVersion: () => version });
// });

```

--------------------------------

### Trigger Import

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/DEVELOPMENT.md

Initiates the import process for conversations.

```APIDOC
## POST /api/import/scan

### Description
Initiates the import process for conversations.

### Method
POST

### Endpoint
/api/import/scan

### Response
#### Success Response (200)
- **field1** (type) - Description
```

--------------------------------

### ChatCrystal CLI Commands - Knowledge Retrieval

Source: https://github.com/zengliangyi/chatcrystal/blob/main/server/README.md

Commands for searching and browsing your knowledge base, including semantic search and listing notes.

```bash
# Knowledge retrieval
crystal search <query> [--limit 10]     # Semantic search
crystal notes list [--tag X]            # Browse notes
crystal notes get <id>                  # View note detail
crystal notes relations <id>            # View note relations
crystal tags                            # List tags with counts
```

--------------------------------

### ChatCrystal CLI Commands - Data Management

Source: https://github.com/zengliangyi/chatcrystal/blob/main/server/README.md

Commands for managing your data, including importing conversations, summarizing, and retrying failed summaries.

```bash
# Data management
crystal import [--source claude-code]   # Import conversations
crystal summarize <id>                  # Summarize one conversation
crystal summarize --all                 # Batch summarize
crystal summarize --retry-errors        # Retry failed summaries
crystal status                          # Server status and DB stats
```

--------------------------------

### Claude Code Adapter

Source: https://github.com/zengliangyi/chatcrystal/blob/main/AGENTS.md

Parses JSONL files from `~/.claude/projects/`. Sanitizes specific tags like `<system-reminder>` and `<command-name>` before processing.

```typescript
// adapters/claude-code.ts
import { SourceAdapter } from "../parser/SourceAdapter";
import fs from "fs";
import path from "path";

export class ClaudeCodeAdapter implements SourceAdapter {
  async parse(filePath: string): Promise<any[]> {
    const content = await fs.promises.readFile(filePath, "utf-8");
    const lines = content.split("\n");
    const records = [];

    for (const line of lines) {
      if (!line.trim()) continue;
      try {
        let record = JSON.parse(line);
        // Sanitize specific tags
        if (record.content) {
          record.content = record.content
            .replace(/<system-reminder>.*?<\/system-reminder>/s, "")
            .replace(/<command-name>.*?<\/command-name>/s, "");
        }
        records.push(record);
      } catch (e) {
        console.error(`Failed to parse line: ${line}`, e);
      }
    }
    return records;
  }
}

```

--------------------------------

### Experience Gate Calibration Sample Set Structure

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/EXPERIENCE_GATE.md

Defines the structure for the default sample set used in the experience quality gate calibration. It includes metadata about the origin and whether real user data is contained.

```json
{
  "origin": "synthetic_calibration_cases",
  "contains_real_user_data": false
}
```

--------------------------------

### Agent Configuration with Environment Variables

Source: https://github.com/zengliangyi/chatcrystal/blob/main/docs/MCP.md

Pass environment variables to the MCP client by including an 'env' object in the agent's configuration. This allows for setting custom base URLs and API tokens.

```json
{
  "mcpServers": {
    "chatcrystal": {
      "command": "crystal",
      "args": ["mcp"],
      "env": {
        "CHATCRYSTAL_BASE_URL": "https://chatcrystal.example.com",
        "CHATCRYSTAL_API_TOKEN": "your-long-token"
      }
    }
  }
}
```