Claude Desktop - Memory Crystal

Recommended: universal installer

Use the universal installer first. It can configure this target for hosted cloud or local Docker Convex and creates config backups before writing.

Agent Instructions

Copy and paste this directly into your agent:

Install Memory Crystal for Claude Desktop. Run the official installer command for this machine, follow the auth/backend prompts, and do not manually edit Claude Desktop config unless the installer fails and asks for a manual fallback. After installation, restart Claude Desktop and confirm the `memory-crystal` server loads.

macOS/Linux/WSL:
curl -fsSL https://memorycrystal.ai/crystal | bash -s -- --targets claude-desktop

Windows PowerShell:
iwr https://memorycrystal.ai/install.ps1 -OutFile install.ps1; .\install.ps1 -Targets claude-desktop

curl -fsSL https://memorycrystal.ai/crystal | bash -s -- --targets claude-desktop

For native Windows PowerShell, use:

iwr https://memorycrystal.ai/install.ps1 -OutFile install.ps1
.\install.ps1 -Targets claude-desktop

For local data storage, add --backend local in Bash or -Backend local in PowerShell. See Local-First Setup. Claude Desktop can still talk to Memory Crystal, but it uses the older kind of connection in this repo.

What this means in practice

Claude Desktop can be configured by the universal installer when its config file is present. The manual fallback below is the deprecated stdio/HTTP MCP package, not the preferred modern Streamable HTTP package. That distinction matters because the setup steps and assumptions are different from Claude Code.

How it actually works

Important repo surfaces:

mcp-server/README.md
mcp-server/src/index.ts
.env.example

This path is public and documented, but it should be described as a compatibility path, not the mainline path for all clients.

Universal installer path

The recommended first install path is the universal installer:

curl -fsSL https://memorycrystal.ai/crystal | bash

Use it when you want Memory Crystal to detect Claude Desktop, ask before changing config, and offer cloud or local-first backend mode. The dedicated commands below remain useful for single-client installs and compatibility.

Commands / examples

Add this to:

~/.claude/claude_desktop_config.json

{
  "mcpServers": {
    "memory-crystal": {
      "command": "crystal-mcp",
      "env": {
        "CRYSTAL_MCP_MODE": "stdio",
        "MEMORY_CRYSTAL_API_KEY": "your-api-key-here",
        "MEMORY_CRYSTAL_API_URL": "https://your-deployment.convex.site"
      }
    }
  }
}

CRYSTAL_MCP_MODE=stdio matters here because the deprecated local package can also run an explicit local HTTP listener. Claude Desktop’s command-launched path should use stdio.

Tool-use guidance

Use crystal_recall for blended durable memory and crystal_query_knowledge_base for named manuals, voice guides, transcripts, runbooks, or imported reference corpora. Use crystal_search_messages for exact prior wording. When a chat maps to a client, agent, channel, or repository, pass the matching agentId, channel, projectId, or repoSlug so recall stays scoped.

Common mistakes

assuming Claude Desktop uses the same preferred setup as Claude Code
documenting the deprecated package as if it were the current default
forgetting to explain why this path still exists

Source of truth

Primary files behind this page:

mcp-server/README.md
mcp-server/src/index.ts
.env.example

​Recommended: universal installer

​Agent Instructions

​What this means in practice

​How it actually works

​Universal installer path

​Commands / examples

​Tool-use guidance

​Common mistakes

​Source of truth