Skip to main content
Environment variables are little labels that tell the program important secrets and addresses. They answer questions like:
  • Where is the backend?
  • Which API key should I use?
  • Where is my local vault?

​
What this means in practice

Important variables across the repo include:

​
Client / MCP-facing

  • MEMORY_CRYSTAL_API_KEY
  • MEMORY_CRYSTAL_API_URL

​
Backend / embedding/runtime

  • GEMINI_API_KEY
  • OPENROUTER_API_KEY
  • GEMINI_EMBEDDING_MODEL
  • EMBEDDING_PROVIDER
  • CONVEX_URL
  • OPENAI_API_KEY
  • OBSIDIAN_VAULT_PATH

​
Local MCP/process wiring

  • CRYSTAL_MCP_MODE
  • CRYSTAL_MCP_HOST
  • CRYSTAL_MCP_PORT

​
How it actually works

Different layers use different names:
  • the docs and modern MCP setup prefer MEMORY_CRYSTAL_*
  • backend paths use provider-specific variables such as GEMINI_API_KEY and OPENROUTER_API_KEY
The right thing to document is not just the variable name, but which surface consumes it.

​
Commands / examples

Example from .env.example:
Use CRYSTAL_MCP_MODE=stdio for command-launched local MCP. Reserve CRYSTAL_MCP_MODE=http for the deprecated local network MCP listener. Helpful verification command:

​
Common mistakes

  • setting MEMORY_CRYSTAL_API_KEY and expecting it to work as a backend Gemini/OpenRouter provider key
  • using a Memory Crystal bearer token as GEMINI_API_KEY
  • forgetting MEMORY_CRYSTAL_API_URL for MCP server setups
  • assuming smoke-test failures are always code failures instead of environment misconfiguration

​
Source of truth

Primary files behind this page:
  • .env.example
  • scripts/crystal-doctor.sh
  • packages/mcp-server/README.md
  • mcp-server/README.md
  • apps/web/public/install.sh