> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorycrystal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Which variables matter, who uses them, and how they map to the install scripts, MCP servers, and backend runtime.

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`:

```env theme={"system"}
CONVEX_URL=https://your-deployment.convex.cloud
GEMINI_API_KEY=
OPENROUTER_API_KEY=
GEMINI_EMBEDDING_MODEL=gemini-embedding-2-preview
OPENAI_API_KEY=sk-...
OBSIDIAN_VAULT_PATH=/path/to/your/obsidian/vault
CRYSTAL_MCP_MODE=stdio
CRYSTAL_MCP_HOST=127.0.0.1
CRYSTAL_MCP_PORT=8788
EMBEDDING_PROVIDER=gemini
MEMORY_CRYSTAL_API_KEY=
MEMORY_CRYSTAL_API_URL=https://your-deployment.convex.site
```

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:

```bash theme={"system"}
npm run crystal:doctor
```

## 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`