Run and configuration

This page documents startup, runtime settings, and operational checks for MemState deployments.

Boot sequence

  1. Load settings from environment and optional .env (MEMSTATE_* prefix, plus GROQ_API_KEY fallback).
  2. Start Uvicorn with import path memstate.api.main:app and configured host/port.
  3. Lazy-create singleton executor and reasoner when first route call requests dependencies.
  4. Open and initialize Kuzu schema through get_store() on first store access.

Local run

pip install -e .
python -m memstate.api.cli

Default bind: 0.0.0.0:8765. UI: http://127.0.0.1:8765/ui/

Core environment variables

Variable Default Purpose
MEMSTATE_KUZU_PATHmemstate.kuzuEmbedded database file path.
MEMSTATE_API_HOST0.0.0.0HTTP bind host.
MEMSTATE_API_PORT8765HTTP bind port.
MEMSTATE_API_KEYunsetOptional API key for protected JSON routes.
MEMSTATE_OLLAMA_BASE_URLhttp://127.0.0.1:11434Ollama provider endpoint.
MEMSTATE_OLLAMA_MODELllama3.2:latestDefault Ollama model id.
MEMSTATE_GROQ_MODELopenai/gpt-oss-20bDefault Groq model id.
GROQ_API_KEYunsetGroq credential (loaded without prefix).
MEMSTATE_ADMIN_KEYunsetStronger key for protected config updates (e.g. system context). Falls back to MEMSTATE_API_KEY.
MEMSTATE_OLLAMA_ALLOW_REMOTEfalseAllow client-supplied Ollama URLs to non-localhost hosts. Disabled by default (SSRF risk).
MEMSTATE_GROQ_WHISPER_MODELwhisper-large-v3-turboGroq Whisper model for speech-to-text transcription endpoints.

Chat/Study operational tuning

Variable Default Operational impact
MEMSTATE_CHAT_INTENT_TURNS8Intent classifier context depth.
MEMSTATE_CHAT_MAX_TOOL_ROUNDS32Max tool-loop rounds for normal chat flow.
MEMSTATE_CHAT_CHUNK_THRESHOLD_CHARS10000Threshold for Study two-phase ingest.
MEMSTATE_CHAT_CHUNK_PER_SEGMENT_TOOL_ROUNDS72Tool budget used in Study phase A.
MEMSTATE_STUDY_PHASE_DELAY_SECONDS8.0Pause between Study phase A and phase B.
MEMSTATE_GROQ_RATE_LIMIT_MAX_RETRIES20Max retries on Groq 429 / rate_limit_exceeded (1–100).
MEMSTATE_GROQ_RATE_LIMIT_BACKOFF_CAP_SECONDS120.0Cap (seconds) for Groq rate-limit backoff sleep per retry (1–600).
MEMSTATE_QUERY_FIELD_SALIENCE_BUMP0.1Per-field salience increase when read tools return field data on query intent (0–2).
MEMSTATE_FIELD_SALIENCE_MAX10.0Upper bound for field salience values (0.1–10).

Health and diagnostics

  • GET /health: process liveness.
  • GET /health/graph: verifies graph open and read query against configured path.
  • GET /health/falkordb: compatibility alias to graph health endpoint.
If graph health reports lock errors, ensure no duplicate MemState process is using the same DB path and avoid cloud-sync locked folders.

Client integration environment

MemoryClient reads:

  • MEMSTATE_API_URL (default http://127.0.0.1:8765)
  • MEMSTATE_API_KEY (optional)