API reference
Environment variables
Every variable the server and the SDKs read.
LLM configuration is environment-driven for self-host, and automatic on cloud. There is no configure_llm() call. These variables control the self-hosted server and the SDKs.
| Variable | Default | Purpose |
|---|---|---|
MENTEDB_LLM_PROVIDER | none | openai, anthropic, ollama, bedrock (needs --features bedrock), or none |
MENTEDB_LLM_API_KEY | LLM API key | |
MENTEDB_LLM_MODEL | provider default | Model name. Defaults: claude-haiku-5-5 (anthropic), us.anthropic.claude-haiku-5-5 (bedrock), gpt-4o-mini (openai), llama3 (ollama) |
MENTEDB_LLM_READER_MODEL | Model for judge calls (entity linking, communities, the user model, conflict detection, topic canonicalization); unset uses the LLM model (--llm-reader-model) | |
MENTEDB_LLM_TIMEOUT_SECS | 120 | Whole request timeout for one LLM call |
MENTEDB_LLM_BASE_URL | For Ollama or a proxy | |
MENTEDB_LLM_REGION | AWS_REGION, else us-east-1 | Bedrock region for extraction |
MENTEDB_LLM_MAX_OUTPUT_TOKENS | 16000 | Output ceiling per LLM call, thinking included |
MENTEDB_LLM_EFFORT | Claude effort: low, medium or high; unset keeps the model default | |
MENTEDB_AUTO_EXTRACT | false | Per-turn fact extraction (--auto-extract) |
MENTEDB_EMBEDDING_PROVIDER | candle/hash | candle, bedrock (needs --features bedrock), hash, or none (--embedding-provider) |
MENTEDB_EMBEDDING_MODEL | cohere.embed-english-v3 | Bedrock embedding model: cohere.embed-english-v3, cohere.embed-multilingual-v3, amazon.titan-embed-text-v2:0 or amazon.titan-embed-text-v1 |
MENTEDB_EMBEDDING_REGION | AWS_REGION, else us-east-1 | Bedrock region for embeddings |
MENTEDB_EMBEDDING_TIMEOUT_MS | 3000 | Whole call timeout for one Bedrock embedding request |
MENTEDB_CONTRADICTION_POLICY | supersede | supersede closes the older of two contradicting memories; flag keeps both and links them with a contradicts edge |
MENTEDB_MAINTENANCE_INTERVAL_HOURS | 24 | Sweep interval; 0 disables |
MENTEDB_DECAY_EXEMPT_TAGS | scope:always | Comma separated tags whose memories never fade or archive (replaces the default) |
MENTEDB_DECAY_EXEMPT_ATTRIBUTE | decay_exempt | Attribute that exempts a memory when boolean true; empty turns it off |
MENTEDB_REFRESH_ACCESS_ON_SEARCH | off | Hybrid and batch search hits refresh accessed_at and access_count, written at the next flush |
MENTEDB_ENRICH_COPY_ATTRIBUTES | Comma separated attributes derived memories copy from their sources | |
MENTEDB_ENRICH_CANDIDATE_TYPES | episodic | Comma separated memory types enrichment reads |
MENTEDB_ENRICH_WORKERS | 1 | Threads in the enrichment pool, and runs at once |
MENTEDB_JWT_SECRET | HS256 shared secret: enables auth and lets the server issue tokens (--jwt-secret) | |
MENTEDB_JWT_PUBLIC_KEY_FILE | PEM public key (RSA, EC P-256 or Ed25519); verifies tokens signed elsewhere, instead of the secret | |
MENTEDB_JWT_PUBLIC_KEY | The public key inline, as PEM text or base64 DER, instead of the file (set one, not both) | |
MENTEDB_ALLOW_UNSCOPED_TOKENS | off | With a public key, accept non admin tokens without dbs (meaning every database) |
MENTEDB_JWT_DBS_SUB_PATTERN | Glob every dbs entry must match with {sub} replaced by the token's sub, for example tenant.{sub}.* | |
MENTEDB_JWT_ISSUER | Required iss claim, when set | |
MENTEDB_JWT_AUDIENCE | Required aud claim, when set | |
MENTEDB_ADMIN_KEY | Admin key for token issuance, database admin, backups and the console (--admin-key) | |
MENTEDB_MAX_OPEN_DATABASES | 256 | Named databases kept open; the least recently used idle one closes past this |
MENTEDB_AUTO_CREATE_DATABASES | true | Create a named database on first use; false returns 404 instead |
MENTEDB_BACKUP_DIR | <data-dir>/backups | Where backup files are written, one subdirectory per database |
MENTEDB_TLS_CERT_FILE | PEM certificate chain; with the key, serves HTTPS and gRPC over TLS (--tls-cert) | |
MENTEDB_TLS_KEY_FILE | PEM private key for the certificate (--tls-key) | |
MENTEDB_TLS_CERT_PEM, MENTEDB_TLS_KEY_PEM | The certificate chain and key as PEM text, instead of files | |
MENTEDB_GRPC | on | off (or 0, false, no, disabled) turns the gRPC listener off; so does --grpc-port 0 |
MENTEDB_SHUTDOWN_DRAIN_SECS | 10 | Seconds requests in flight get to finish after SIGTERM or Ctrl+C, before databases are flushed and closed |
MENTEDB_RATE_LIMIT_BURST | 100 | Requests per caller bucket; 0 turns rate limiting off |
MENTEDB_RATE_LIMIT_PER_SEC | 10 | Bucket refill per second; 0 turns rate limiting off |
MENTEDB_REQUEST_TIMEOUT_MS | Upper bound on every request (504 past it); unset or 0 means none. x-mentedb-deadline-ms can only shorten it | |
MENTEDB_LIST_MAX_LIMIT | 1000 | Largest page GET /memories returns |
MENTEDB_BATCH_MAX_DATABASES | 32 | Most databases one POST /v1/batch/search may name |
MENTEDB_READY_PROBE_DB | readiness-probe | Named database /v1/ready opens to prove databases can be locked; empty turns the check off |
MENTEDB_EXTRACTION_QUALITY_THRESHOLD | 0.7 | Min confidence to store an extracted fact |
MENTEDB_EXTRACTION_DEDUP_THRESHOLD | 0.85 | Similarity above which an extraction is a duplicate |
MENTEDB_API_KEY | Cloud API key (mdb_...) for the REST endpoint and MCP connector | |
MENTEDB_CLOUD_URL | https://api.mentedb.com | Override the cloud endpoint |
For a fully local setup, point MENTEDB_LLM_PROVIDER=ollama and MENTEDB_LLM_BASE_URL=http://localhost:11434/api/chat (the full endpoint URL). Semantic search, auto-linking, and contradiction detection all depend on real embeddings: the Docker image ships local Candle embeddings, while a plain cargo install mentedb-server falls back to non-semantic hash embeddings unless built with --features local-embeddings.