novamem · docs

Appearance

Environment variable reference ​

Every novamem-server config knob lives in env vars. The schema is enforced at startup by packages/server/src/config.ts — boot fails fast if anything required is missing.

Required for production ​

VariableRequired whenWhat it does
POSTGRES_PASSWORDalwaysThe Postgres password. Compose substitutes it into NOVAMEM_WARM_URL and the postgres container's POSTGRES_PASSWORD.
NOVAMEM_COOKIE_SECRETNOVAMEM_AUTH_MODE != noneSigns HttpOnly session cookies. Generate with openssl rand -hex 32. Must be stable across restarts; rotating invalidates every active session.
NOVAMEM_BOOTSTRAP_ADMIN_PASSWORDfirst-boot onlySeeds an initial admin user via Better Auth on the very first start (when no users exist). Auto-scrubbed from process.env after seeding.

Server transport ​

VariableDefaultDescription
NOVAMEM_HOST0.0.0.0Bind address. Use 127.0.0.1 to confine to localhost.
NOVAMEM_PORT7778HTTP port. Both REST and /mcp/sse are served here.
NOVAMEM_BASE_URLhttp://localhost:7778Public origin used for the dashboard's HTML head + Better Auth callback URLs. Update when you put novamem behind a reverse proxy.
NOVAMEM_RATE_LIMIT_PER_MINUTE600Per-IP cap. SSE bypasses it (one long-lived connection); see MAX_SESSIONS_PER_USER for SSE limits.
NOVAMEM_CORS_ORIGINS``Comma-separated list of allowed origins. Empty disables cross-origin browser access.
NOVAMEM_INSECURE_COOKIES0When 1, drops the Secure flag on session cookies. Dev only. Do not enable in production.

Authentication ​

VariableDefaultDescription
NOVAMEM_AUTH_MODEuserOne of none, bearer, tenant, user. user is the modern default — Better Auth sessions for the dashboard, per-user nm_… bearers for MCP. none is dev-only — every request becomes the public tenant.
NOVAMEM_AUTH_TOKEN—Required when mode = bearer. Single shared bearer token; useful for one-process deploys where you want a static credential.
NOVAMEM_BOOTSTRAP_ADMIN_EMAILadmin@example.comEmail for the bootstrap admin.
NOVAMEM_ADMIN_DASHBOARD1Master switch. Set 0 to 404 the entire /admin/* and /v1/admin/metrics surface.

Datastores ​

VariableDefaultDescription
NOVAMEM_WARM_URLpostgres://novamem:CHANGE_ME@localhost:5432/novamemPostgres connection string for the warm tier + Better Auth tables + audit log.
NOVAMEM_PG_POOL_MAX20Pool size cap. Bound below your Postgres max_connections.
NOVAMEM_COLD_URLhttp://localhost:6333Qdrant REST endpoint for the cold (vector) tier.
NOVAMEM_COLD_VECTOR_SIZE384Embedding dimension. Must match NOVAMEM_EMBEDDINGS_DIM.
NOVAMEM_GRAPH_ENABLEDtrueWhen false, the engine skips graph writes + reads and emits degraded:true on every search.
NOVAMEM_GRAPH_URLredis://localhost:6379FalkorDB endpoint (Redis protocol).

Embeddings ​

VariableDefaultDescription
NOVAMEM_EMBEDDINGS_PROVIDERlocal-transformerslocal-transformers runs @xenova/transformers in-process (no API key, ~1 GB RAM on first call). openai-compatible calls an external HTTP endpoint.
NOVAMEM_EMBEDDINGS_ENDPOINT—Required when provider is openai-compatible. e.g. https://api.openai.com/v1.
NOVAMEM_EMBEDDINGS_MODEL—e.g. text-embedding-3-small (OpenAI) or nomic-embed-text (Ollama).
NOVAMEM_EMBEDDINGS_API_KEY—API key for the external endpoint.
NOVAMEM_EMBEDDINGS_DIM384Vector dimension produced by the model. Must match Qdrant collection size.

Memory engine ​

VariableDefaultDescription
NOVAMEM_DECAY_INTERVAL_MS21600000 (6 h)How often the synaptic-decay sweep runs. Set 0 to disable.
NOVAMEM_DECAY_DAYS7Base half-life. Effective lifespan grows with hits: effectiveDays = NOVAMEM_DECAY_DAYS · log₂(hits + 1).
NOVAMEM_SSE_KEEPALIVE_MS25000SSE : ping cadence. Must be shorter than the client's HTTP body-read timeout (undici defaults to 5 min).

Logging & telemetry ​

VariableDefaultDescription
LOG_LEVELinfoPino log level: trace · debug · info · warn · error.
OTEL_EXPORTER_OTLP_ENDPOINT—When set, the server enables OpenTelemetry traces for HTTP + engine spans, exported via OTLP/gRPC.
OTEL_SERVICE_NAMEnovamemResource attribute for emitted spans.

See also ​