Configuration Reference
All MemoryRelay configuration is managed through environment variables. Set these in your .env file or pass them directly to your Docker containers.
Required Variables
These must be set for MemoryRelay to start.
| Variable | Example | Description |
|---|---|---|
DATABASE_URL | postgresql+asyncpg://user:pass@host:5432/memory_service | PostgreSQL connection string. Must use the postgresql+asyncpg:// driver prefix. |
SECRET_KEY | a-random-string-at-least-32-chars | Key used for JWT signing and other cryptographic operations. Use a cryptographically random value. |
The DATABASE_URL must use the postgresql+asyncpg:// driver. Standard postgresql:// or postgres:// prefixes will fail at startup because MemoryRelay requires an async database driver.
Database
| Variable | Default | Description |
|---|---|---|
DATABASE_URL | -- | PostgreSQL connection string with postgresql+asyncpg:// driver. |
DB_POOL_SIZE | 5 | Number of persistent database connections in the pool. |
DB_MAX_OVERFLOW | 10 | Maximum additional connections beyond pool size during peak load. |
Redis
| Variable | Default | Description |
|---|---|---|
REDIS_URL | redis://localhost:6379/0 | Redis connection string for caching and rate limiting. |
Embedding
| Variable | Default | Description |
|---|---|---|
EMBEDDING_PROVIDER | local | Embedding provider. Set to local for sentence-transformers or openai for OpenAI embeddings. |
EMBEDDING_MODEL | all-MiniLM-L6-v2 | Model name. For local: any sentence-transformers model. For OpenAI: text-embedding-3-small, text-embedding-3-large, or text-embedding-ada-002. |
EMBEDDING_DIMENSION | 384 | Vector dimension. Must match the model output. Common values: 384 (MiniLM), 1536 (OpenAI small/ada), 3072 (OpenAI large). |
OPENAI_API_KEY | -- | Required when EMBEDDING_PROVIDER=openai. Your OpenAI API key. |
Changing the embedding model or dimension after data has been stored requires re-embedding all existing memories. The old and new vectors are not compatible for similarity comparison.
Supported Embedding Configurations
| Provider | Model | Dimension | Notes |
|---|---|---|---|
local | all-MiniLM-L6-v2 | 384 | Default. Fast, runs on CPU, no external calls. |
local | all-mpnet-base-v2 | 768 | Higher quality, slower, more memory. |
openai | text-embedding-3-small | 1536 | Good balance of quality and cost. |
openai | text-embedding-3-large | 3072 | Highest quality, higher cost. |
openai | text-embedding-ada-002 | 1536 | Legacy model. Use text-embedding-3-small for new deployments. |
Security
| Variable | Default | Description |
|---|---|---|
SECRET_KEY | -- | JWT signing key. Must be at least 32 characters. |
CORS_ORIGINS | ["http://localhost:3000"] | JSON array of allowed CORS origins. Set to ["*"] to allow all origins (not recommended for production). |
RATE_LIMIT_PER_MINUTE | 100 | Maximum API requests per minute per API key. Set to 0 to disable rate limiting. |
# Example: allow multiple origins
CORS_ORIGINS=["https://app.your-domain.com","https://admin.your-domain.com"]
Setting CORS_ORIGINS=["*"] allows any website to make requests to your API. Only use this in development.
Email
MemoryRelay sends transactional emails (account verification, password reset) via NorthRelay.
| Variable | Default | Description |
|---|---|---|
NORTHRELAY_API_KEY | -- | API key for the NorthRelay email service. Email features are disabled if not set. |
EMAIL_FROM_ADDRESS | noreply@memoryrelay.ai | Sender email address for transactional emails. |
EMAIL_FROM_NAME | MemoryRelay | Display name shown in the "From" field. |
Application
| Variable | Default | Description |
|---|---|---|
APP_BASE_URL | http://localhost:3000 | Base URL for the web dashboard. Used in email links (verification, password reset). |
DEBUG | false | Enable debug mode. When true, enables SQL query logging to stdout and detailed error messages in API responses. |
Never enable DEBUG in production. SQL query logs may contain sensitive data, and detailed error messages can expose internal implementation details.
Example .env File
# === Required ===
DATABASE_URL=postgresql+asyncpg://memoryrelay:secure-password@db:5432/memory_service
SECRET_KEY=generate-a-random-string-at-least-32-characters-long
# === Database ===
DB_POOL_SIZE=10
DB_MAX_OVERFLOW=20
# === Redis ===
REDIS_URL=redis://redis:6379/0
# === Embedding ===
EMBEDDING_PROVIDER=local
EMBEDDING_MODEL=all-MiniLM-L6-v2
EMBEDDING_DIMENSION=384
# === Security ===
CORS_ORIGINS=["https://app.your-domain.com"]
RATE_LIMIT_PER_MINUTE=100
# === Email (optional) ===
NORTHRELAY_API_KEY=nr_your_api_key
EMAIL_FROM_ADDRESS=noreply@your-domain.com
EMAIL_FROM_NAME=MemoryRelay
# === Application ===
APP_BASE_URL=https://app.your-domain.com
DEBUG=false