API reference

Environment variables

Every variable the server and the SDKs read.

llms.txt

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.

VariableDefaultPurpose
MENTEDB_LLM_PROVIDERnoneopenai, anthropic, ollama, bedrock (needs --features bedrock), or none
MENTEDB_LLM_API_KEYLLM API key
MENTEDB_LLM_MODELprovider defaultModel name. Defaults: claude-haiku-5-5 (anthropic), us.anthropic.claude-haiku-5-5 (bedrock), gpt-4o-mini (openai), llama3 (ollama)
MENTEDB_LLM_READER_MODELModel for judge calls (entity linking, communities, the user model, conflict detection, topic canonicalization); unset uses the LLM model (--llm-reader-model)
MENTEDB_LLM_TIMEOUT_SECS120Whole request timeout for one LLM call
MENTEDB_LLM_BASE_URLFor Ollama or a proxy
MENTEDB_LLM_REGIONAWS_REGION, else us-east-1Bedrock region for extraction
MENTEDB_LLM_MAX_OUTPUT_TOKENS16000Output ceiling per LLM call, thinking included
MENTEDB_LLM_EFFORTClaude effort: low, medium or high; unset keeps the model default
MENTEDB_AUTO_EXTRACTfalsePer-turn fact extraction (--auto-extract)
MENTEDB_EMBEDDING_PROVIDERcandle/hashcandle, bedrock (needs --features bedrock), hash, or none (--embedding-provider)
MENTEDB_EMBEDDING_MODELcohere.embed-english-v3Bedrock embedding model: cohere.embed-english-v3, cohere.embed-multilingual-v3, amazon.titan-embed-text-v2:0 or amazon.titan-embed-text-v1
MENTEDB_EMBEDDING_REGIONAWS_REGION, else us-east-1Bedrock region for embeddings
MENTEDB_EMBEDDING_TIMEOUT_MS3000Whole call timeout for one Bedrock embedding request
MENTEDB_CONTRADICTION_POLICYsupersedesupersede closes the older of two contradicting memories; flag keeps both and links them with a contradicts edge
MENTEDB_MAINTENANCE_INTERVAL_HOURS24Sweep interval; 0 disables
MENTEDB_DECAY_EXEMPT_TAGSscope:alwaysComma separated tags whose memories never fade or archive (replaces the default)
MENTEDB_DECAY_EXEMPT_ATTRIBUTEdecay_exemptAttribute that exempts a memory when boolean true; empty turns it off
MENTEDB_REFRESH_ACCESS_ON_SEARCHoffHybrid and batch search hits refresh accessed_at and access_count, written at the next flush
MENTEDB_ENRICH_COPY_ATTRIBUTESComma separated attributes derived memories copy from their sources
MENTEDB_ENRICH_CANDIDATE_TYPESepisodicComma separated memory types enrichment reads
MENTEDB_ENRICH_WORKERS1Threads in the enrichment pool, and runs at once
MENTEDB_JWT_SECRETHS256 shared secret: enables auth and lets the server issue tokens (--jwt-secret)
MENTEDB_JWT_PUBLIC_KEY_FILEPEM public key (RSA, EC P-256 or Ed25519); verifies tokens signed elsewhere, instead of the secret
MENTEDB_JWT_PUBLIC_KEYThe public key inline, as PEM text or base64 DER, instead of the file (set one, not both)
MENTEDB_ALLOW_UNSCOPED_TOKENSoffWith a public key, accept non admin tokens without dbs (meaning every database)
MENTEDB_JWT_DBS_SUB_PATTERNGlob every dbs entry must match with {sub} replaced by the token's sub, for example tenant.{sub}.*
MENTEDB_JWT_ISSUERRequired iss claim, when set
MENTEDB_JWT_AUDIENCERequired aud claim, when set
MENTEDB_ADMIN_KEYAdmin key for token issuance, database admin, backups and the console (--admin-key)
MENTEDB_MAX_OPEN_DATABASES256Named databases kept open; the least recently used idle one closes past this
MENTEDB_AUTO_CREATE_DATABASEStrueCreate a named database on first use; false returns 404 instead
MENTEDB_BACKUP_DIR<data-dir>/backupsWhere backup files are written, one subdirectory per database
MENTEDB_TLS_CERT_FILEPEM certificate chain; with the key, serves HTTPS and gRPC over TLS (--tls-cert)
MENTEDB_TLS_KEY_FILEPEM private key for the certificate (--tls-key)
MENTEDB_TLS_CERT_PEM, MENTEDB_TLS_KEY_PEMThe certificate chain and key as PEM text, instead of files
MENTEDB_GRPConoff (or 0, false, no, disabled) turns the gRPC listener off; so does --grpc-port 0
MENTEDB_SHUTDOWN_DRAIN_SECS10Seconds requests in flight get to finish after SIGTERM or Ctrl+C, before databases are flushed and closed
MENTEDB_RATE_LIMIT_BURST100Requests per caller bucket; 0 turns rate limiting off
MENTEDB_RATE_LIMIT_PER_SEC10Bucket refill per second; 0 turns rate limiting off
MENTEDB_REQUEST_TIMEOUT_MSUpper bound on every request (504 past it); unset or 0 means none. x-mentedb-deadline-ms can only shorten it
MENTEDB_LIST_MAX_LIMIT1000Largest page GET /memories returns
MENTEDB_BATCH_MAX_DATABASES32Most databases one POST /v1/batch/search may name
MENTEDB_READY_PROBE_DBreadiness-probeNamed database /v1/ready opens to prove databases can be locked; empty turns the check off
MENTEDB_EXTRACTION_QUALITY_THRESHOLD0.7Min confidence to store an extracted fact
MENTEDB_EXTRACTION_DEDUP_THRESHOLD0.85Similarity above which an extraction is a duplicate
MENTEDB_API_KEYCloud API key (mdb_...) for the REST endpoint and MCP connector
MENTEDB_CLOUD_URLhttps://api.mentedb.comOverride 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.