@memorycrystal/mcp-server

@memorycrystal/mcp-server

Note: This is the deprecated local stdio/HTTP MCP server. For the current hosted Streamable HTTP server, see packages/mcp-server/.

Persistent memory for AI assistants via the Model Context Protocol.

Install

npm install -g @memorycrystal/mcp-server

Configure

Set environment variables:

• MEMORY_CRYSTAL_API_KEY — your Memory Crystal API key
• MEMORY_CRYSTAL_API_URL — your Memory Crystal backend base URL
• CRYSTAL_MCP_MODE=stdio — required for command-launched local MCP clients so crystal-mcp speaks stdio instead of starting the local HTTP listener

CRYSTAL_API_KEY is no longer supported. If your client or shell still sets it, upgrade Memory Crystal and replace it with MEMORY_CRYSTAL_API_KEY. MEMORY_CRYSTAL_BACKEND_URL and CRYSTAL_BASE_URL are also retired; use MEMORY_CRYSTAL_API_URL.

Claude Desktop

Add 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://convex.memorycrystal.ai"
      }
    }
  }
}

Claude Code

Add to .claude/mcp.json in your project:

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

Or run directly:

CRYSTAL_MCP_MODE=stdio MEMORY_CRYSTAL_API_URL=https://convex.memorycrystal.ai MEMORY_CRYSTAL_API_KEY=your-key crystal-mcp

Codex CLI

Add via the Codex CLI:

codex mcp add memory-crystal -- crystal-mcp

Then set environment variables CRYSTAL_MCP_MODE=stdio, MEMORY_CRYSTAL_API_KEY, and MEMORY_CRYSTAL_API_URL, or pass inline:

CRYSTAL_MCP_MODE=stdio MEMORY_CRYSTAL_API_URL=https://convex.memorycrystal.ai MEMORY_CRYSTAL_API_KEY=your-key npx @memorycrystal/mcp-server

Available Tools

21 tools are available in the deprecated local stdio/HTTP server:

Tool	Description
crystal_wake	Get a contextual briefing at session start
crystal_remember	Save a memory (decision, lesson, goal, etc.)
crystal_recall	Semantic search across your memories
crystal_recent	Get recently accessed memories
crystal_search_messages	Search conversation history
crystal_what_do_i_know	Summarize what's known about a topic
crystal_why_did_we	Explain the reasoning behind past decisions
crystal_who_owns	Find who owns or manages an entity
crystal_explain_connection	Explain how two concepts are connected
crystal_dependency_chain	Trace dependencies for a goal or project
crystal_preflight	Pre-flight check before destructive actions
crystal_trace	Trace a memory back to its source conversation
crystal_edit	Edit or refine an existing memory
crystal_checkpoint	Save a session checkpoint
crystal_forget	Archive (soft-delete) a memory
crystal_stats	Get memory usage stats
crystal_ideas	View Organic idea discoveries
crystal_idea_action	Star, dismiss, or mark an Organic idea as read
crystal_list_knowledge_bases	List available knowledge bases, including inactive collections when needed
crystal_query_knowledge_base	Search within a specific knowledge base
crystal_import_knowledge	Import reference chunks into a knowledge base

crystal_recent, crystal_search_messages, recall message matches, and wake/session summaries derived from recent messages redact likely secrets before returning output. Newly captured messages become searchable after the active turn completes, not during same-turn tool execution.

Memory Stores

• sensory — short-lived observation capsules; lower-authority fallback context, not raw transcript storage
• episodic — events and conversations
• semantic — facts and knowledge
• procedural — how-to knowledge and workflows
• prospective — goals and future intentions

Memory Categories

decision · lesson · person · rule · event · fact · goal · workflow · conversation