Skip to main content
Use the universal installer first. It can configure this target for hosted cloud or local Docker Convex and creates config backups before writing.
For native Windows PowerShell, use:
For local data storage, add --backend local in Bash or -Backend local in PowerShell. See Local-First Setup. An MCP server is a tool box your AI can open. Memory Crystal gives that tool box memory tools like “remember this”, “search old conversations”, and “look inside a knowledge base”.

​
What this means in practice

There are two MCP server stories in this repo:

​
Current path

  • packages/mcp-server/
  • Streamable HTTP MCP
  • best for modern MCP-capable clients

​
Legacy path

  • mcp-server/
  • deprecated stdio/HTTP server
  • still relevant for older compatibility paths like Claude Desktop

​
Which clients use which path?

​
Use the current Streamable HTTP MCP path for:

  • Claude Code
  • Codex CLI
  • Factory Droid
  • other clients that support Streamable HTTP MCP

​
Use the deprecated stdio/HTTP package for:

  • Claude Desktop
  • older or compatibility-driven setups
When you launch the deprecated package as a command for a client, set CRYSTAL_MCP_MODE=stdio. Reserve http for the explicit local network listener.

​
How it actually works

The current package (packages/mcp-server) wraps Memory Crystal’s hosted HTTP API and exposes a Streamable HTTP MCP endpoint. The deprecated package (mcp-server) exposes the older local stdio/HTTP form of the same memory tool surface. Core tool areas include:
  • recall and search
  • remember and checkpoint
  • wake/trace/stats
  • knowledge-base list/query/import

​
Retrieval contract

  • crystal_recall and reasoning helpers are graph-aware blended memory lookups.
  • crystal_query_knowledge_base is the dedicated path for named manuals, voice guides, transcripts, runbooks, and imported reference corpora.
  • crystal_search_messages is retained transcript search and should be used for exact wording, not broad memory synthesis.
  • crystal_preflight is recall with rule/lesson/decision filters and should include projectId or repoSlug for repo-specific work.
  • agentId, channel, projectId, and repoSlug are scope inputs. Use them whenever the client knows the agent/client/repo boundary.
  • KB sourceRole values such as voice_style, persona_guardrail, canonical_reference, and client_context are provenance and ranking signals.

​
Universal installer path

The recommended first install path is the universal installer:
Use it when you want Memory Crystal to detect MCP clients, 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

Current package local run example:
Example client registration:

​
Common mistakes

  • using the deprecated package when a client supports the current HTTP transport
  • confusing hosted backend auth with local process config
  • documenting Claude Desktop like it uses the same path as Claude Code

​
Source of truth

Primary files behind this page:
  • packages/mcp-server/README.md
  • packages/mcp-server/package.json
  • packages/mcp-server/railway.toml
  • mcp-server/README.md
  • mcp-server/src/index.ts