Skip to content

configuration.md

Latest commit

 

History

History
252 lines (208 loc) · 19.1 KB

configuration.md

File metadata and controls

252 lines (208 loc) · 19.1 KB
Raw

Configuration Reference

All configuration is via environment variables. Defaults are optimized for local development — just set OPENAI_API_KEY and run.

Data is stored in ~/.mnemory/ by default. Override with DATA_DIR env var. In Docker, DATA_DIR is set to /data for volume mounting.

LLM & Embeddings

Variable Default Description
OPENAI_API_KEY OpenAI API key (also used as fallback for LLM_API_KEY)
OPENAI_API_BASE OpenAI-compatible API base URL (also used as fallback for LLM_BASE_URL)
LLM_API_KEY (falls back to OPENAI_API_KEY) API key for LLM provider
LLM_BASE_URL (falls back to OPENAI_API_BASE, then https://api.openai.com/v1) OpenAI-compatible API base URL
LLM_MODEL gpt-5.4-mini LLM model for fact extraction and deduplication
LLM_REASONING_EFFORT Reasoning effort for LLM (none/minimal/low/medium/high). Models that don't support it auto-skip.
EMBED_MODEL text-embedding-3-small Embedding model
EMBED_BASE_URL (falls back to LLM_BASE_URL) Separate base URL for embeddings
EMBED_API_KEY (falls back to LLM_API_KEY) Separate API key for embedding provider
EMBED_DIMS 1536 Embedding dimensions

Model Selection

The default gpt-5.4-mini provides a good balance of quality and cost. Any OpenAI-compatible model with structured output (JSON schema) support works.

Model Provider Input $/M Output $/M LoCoMo Score Notes
gpt-5.4-mini OpenAI $0.75 $4.50 73.2* Default. Supports prompt caching (50% input discount) and batch API (50% off)
gpt-oss-120b Groq $0.15 $0.60 70.5 Recommended budget option. ~5x cheaper than gpt-5.4-mini
gpt-oss-120b OpenAI $0.039 $0.19 70.5 Same model, cheapest option via OpenAI direct
gpt-5-mini OpenAI $0.25 $2.00 73.2 Previous default, still fully supported

*LoCoMo score measured with gpt-5-mini. gpt-5.4-mini is expected to match or exceed this.

gpt-oss-120b setup requires a separate embedding provider since gpt-oss models don't serve embeddings:

LLM_MODEL=gpt-oss-120b
LLM_BASE_URL=https://api.groq.com/openai/v1   # or https://api.openai.com/v1
LLM_API_KEY=gsk-your-groq-key
EMBED_API_KEY=sk-your-openai-key               # embeddings stay on OpenAI
EMBED_BASE_URL=https://api.openai.com/v1

Not recommended: gpt-oss-20b fails security/injection e2e tests and has lower extraction quality (78/80 vs 80/80 for gpt-oss-120b). The smaller model is too aggressive in refusing to extract facts from content that contains boundary tag characters, and occasionally fails to generate session summaries.

Data Storage

Variable Default Description
DATA_DIR ~/.mnemory Base data directory (all paths below default to subdirectories of this)
QDRANT_HOST Qdrant host (empty = local embedded mode, set for remote Qdrant)
QDRANT_PORT 6333 Qdrant port
QDRANT_PATH {DATA_DIR}/qdrant Local embedded Qdrant storage path (used when QDRANT_HOST is not set)
QDRANT_API_KEY Qdrant API key (optional)
QDRANT_COLLECTION mnemory Qdrant collection name
ARTIFACT_BACKEND filesystem Artifact backend: filesystem (local) or s3 (production)
ARTIFACT_PATH {DATA_DIR}/artifacts Local filesystem path for artifacts
S3_ENDPOINT http://localhost:9000 S3/MinIO endpoint URL
S3_ACCESS_KEY (required for s3) S3 access key
S3_SECRET_KEY (required for s3) S3 secret key
S3_BUCKET mnemory S3 bucket name
S3_REGION S3 region (optional)

Server

Variable Default Description
MCP_HOST 0.0.0.0 Listen host
MCP_PORT 8050 Listen port
MCP_API_KEY Single API key for authentication (empty = no auth)
MCP_API_KEYS JSON dict mapping API keys to user IDs (see Authentication below)
MNEMORY_JWT_PUBLIC_KEY Path to a Cognis ES256 public key PEM for JWT validation
MNEMORY_JWKS_URL JWKS URL for Cognis-issued JWT validation (mutually exclusive with MNEMORY_JWT_PUBLIC_KEY)
INSTRUCTION_MODE proactive LLM behavioral instructions: passive, proactive, or personality (see Instruction Modes below)
ENABLE_DELETE_ALL false Enable the delete_all_memories tool (destructive, disabled by default)
ENABLE_METRICS true Enable the /metrics Prometheus endpoint
METRICS_CACHE_TTL 600 Cache TTL in seconds for Qdrant gauge aggregation on /metrics
MGMT_PORT Management port for /health and /metrics (see Management Port below)
MGMT_HOST (falls back to MCP_HOST) Bind host for the management port
SERVER_BASE_URL Base URL for generated download URLs (e.g., https://mnemory.example.com). If not set, URLs are relative paths.
DOWNLOAD_TOKEN_TTL 3600 Default lifetime in seconds for artifact download tokens (1 hour)
DOWNLOAD_TOKEN_MAX_TTL 86400 Maximum allowed lifetime in seconds for download tokens (24 hours)
LOG_LEVEL INFO Logging level

Memory Behavior

Variable Default Description
MAX_MEMORY_LENGTH 1000 Max characters for fast memory content
MAX_ARTIFACT_SIZE 10485760 Max bytes per artifact (10MB)
MAX_CORE_CONTEXT_LENGTH 4000 Max characters for recent context section in get_core_memories. Only affects graceful per-entry trimming of recent context — main sections are never truncated.
DEFAULT_RECENT_DAYS 7 Default days for recent context in core memories
RECENT_LIMIT_USER 25 Max recent user memories to include
RECENT_LIMIT_AGENT 25 Max recent agent memories to include
AUTO_CLASSIFY true Auto-classify memory metadata (type, categories, importance, pinned) via LLM when not provided
CLASSIFY_CACHE_TTL 300 TTL in seconds for the category cache used during auto-classification
CORE_MEMORIES_CACHE_TTL 300 TTL in seconds for the core memories cache (get_core_memories). Set to 0 to disable. Invalidated on memory mutations.
CORE_TOP_MEMORIES 10 Max non-pinned memories to include in core sections by importance. Set to 0 to disable (only pinned memories).
CORE_MAX_PER_SECTION 25 Max memories per section in core memories (Agent Identity, User Facts, etc.). Pinned memories are included first, then top-N fills up to the limit. Set to 0 for unlimited.
CORE_MIN_IMPORTANCE normal Minimum importance for non-pinned memories in core sections. Options: low, normal, high, critical
TTL_FACT (none) Default TTL in days for fact memories (empty = permanent)
TTL_PREFERENCE (none) Default TTL in days for preference memories (empty = permanent)
TTL_EPISODIC 90 Default TTL in days for episodic memories
TTL_PROCEDURAL 60 Default TTL in days for procedural memories
TTL_CONTEXT 7 Default TTL in days for context memories
TRACK_MEMORY_ACCESS true Update last_accessed_at and reset TTL on search/recall
VALIDATION_ENABLED true Accept independent user evidence as a confirmation during inferred deduplication
VALIDATION_MAX_SCORE_ROOTS 3 Maximum confirmation roots that affect the ranking boost
VALIDATION_MAX_SCORE_BOOST 0.10 Maximum multiplicative ranking boost from confirmations
VALIDATION_TTL_MULTIPLIER 2.0 TTL extension multiplier for a new independent confirmation
SLOW_DECAY_ENABLED false Gradually reduce ranking before hard expiry
SLOW_DECAY_HALF_LIFE_DAYS 30 Base ranking half-life when slow decay is enabled
SLOW_DECAY_SCORE_FLOOR 0.25 Minimum slow-decay multiplier
SLOW_DECAY_VALIDATION_HALF_LIFE_MULTIPLIER 2.0 Maximum half-life multiplier from validation
SLOW_DECAY_CANDIDATE_MULTIPLIER 3 Bounded retrieval overfetch before post-ranking
FSCK_RECOVERY_LEASE_SECONDS 300 Lease duration for one fsck operation recovery
FSCK_RECOVERY_MAX_ATTEMPTS 3 Maximum recovery attempts per fsck operation
FSCK_STRANDED_AFTER_SECONDS 3600 Age threshold for stranded-operation metrics
LEGACY_FAILED_RETRY_ENABLED false Permit explicit mutation of legacy failed sessions
LEGACY_FAILED_RETRY_MAX_BATCH 10 Hard upper bound for one retry batch
LEGACY_FAILED_RETRY_MAX_RAW_MEMORIES 100 Maximum raw memories in an eligible session
LEGACY_FAILED_RETRY_STOP_FAILURE_RATIO 0.20 Failure-ratio stop threshold
LEGACY_FAILED_RETRY_STOP_MIN_ATTEMPTS 5 Minimum attempts before ratio stopping
LEGACY_FAILED_RETRY_TIMEOUT_SECONDS 300 Maximum sequential retry-batch duration
SEARCH_SCORE_THRESHOLD 0.30 Minimum score for dense-only search results (0.0-1.0). Only used as fallback when hybrid search fails at query time
SEARCH_SCORE_THRESHOLD_HYBRID 0.0 Minimum score for hybrid (RRF) search results. RRF score range depends on Qdrant's k constant (default k=1 gives ~0.1-1.0, similar to cosine; k=60 gives ~0.01-0.03). Default 0.0 disables threshold filtering
DEDUP_SIMILARITY_THRESHOLD 0.4 Minimum similarity for deduplication matching during memory ingestion
SEARCH_SIMILARITY_WEIGHT 0.9 Weight for cosine similarity in search ranking (remainder goes to importance). Default 0.9 = 90% similarity, 10% importance
SEARCH_SPARSE_MODEL Qdrant/bm25 BM25 sparse embedding model for hybrid search. Default is recommended
SEARCH_KEYWORD_WEIGHT 0.2 Deprecated. Ignored — replaced by BM25 hybrid search. Kept for backward compatibility
DEFAULT_TIMEZONE Default IANA timezone for naive event_date values (e.g., Europe/Prague). Empty = server local timezone. Can be overridden per session via X-Timezone header
FIND_MEMORIES_QUERIES 5 Maximum number of search queries the LLM generates for find_memories (may return fewer or zero)
FIND_LLM_MODEL Override LLM model for find/ask pipeline — query generation, reranking, answer generation (empty = use main LLM_MODEL). Smaller models like gpt-4.1-nano work well for these structured tasks
FIND_REASONING_EFFORT low Reasoning effort for find/ask LLM calls. Defaults to low since query generation and reranking are simple structured tasks. Set empty to inherit LLM_REASONING_EFFORT
MAX_INPUT_LENGTH 400000 Max chars for input to add_memory(infer=True) and remember(). ~100k tokens
MEMORY_SESSION_TTL 86400 Default session idle TTL in seconds (24 hours). Each access (recall/remember) resets the timer
MEMORY_SESSION_SWEEP_INTERVAL 300 Interval in seconds between session cleanup sweeps (5 minutes)
SESSION_BACKEND sqlite Session persistence backend: memory (no persistence), sqlite (local file), redis (clustered). Auto-detects redis if REDIS_URL is set
SESSION_PATH {DATA_DIR}/sessions.db SQLite database path for session persistence (only used when SESSION_BACKEND=sqlite)
REDIS_URL Redis connection URL for session persistence (e.g., redis://host:6379/0). Required when SESSION_BACKEND=redis. When set without explicit SESSION_BACKEND, auto-selects redis
RECALL_MAX_RESULTS 10 Max search results returned by recall endpoint
REMEMBER_RATE_LIMIT 10 Max remember requests per minute per user. 0 = no limit
FSCK_CACHE_TTL 86400 How long memory check results are cached in seconds (24 hours)
FSCK_LLM_CONCURRENCY 4 Max concurrent LLM calls during memory check. Set to 1 for sequential
FSCK_LLM_MODEL Override LLM model for memory check (empty = use main LLM_MODEL)
FSCK_REASONING_EFFORT medium Reasoning effort for memory check LLM calls (empty = use main LLM_REASONING_EFFORT). Defaults to medium for better accuracy
FSCK_AUTO_INTERVAL 0 Interval in hours between automatic background memory checks. 0 = disabled
FSCK_AUTO_MIN_CONFIDENCE 0.95 Minimum confidence score (0.0-1.0) for a fix to be auto-applied
FSCK_AUTO_MIN_SEVERITY medium Minimum severity for a fix to be auto-applied. Options: low, medium, high
FSCK_MAX_MEMORIES 5000 Maximum memories per check run. If a user has more durable memories, a random sample is taken. 0 = no limit
FSCK_MAX_LLM_CALLS 200 Maximum LLM calls per check run. When budget is exhausted, the pipeline stops gracefully; unchecked memories are picked up in the next incremental auto-fsck run. 0 = no limit
LABELS_MAX_FIELDS 20 Max number of label keys per memory
LABELS_MAX_KEY_LENGTH 64 Max length of a label key (alphanumeric + underscore only)
LABELS_MAX_VALUE_LENGTH 1000 Max length of a string label value
LABELS_INDEXES Comma-separated list of label keys to index in Qdrant for fast filtering (e.g., project,topic,conversation_id). Only needed for remote Qdrant with large datasets
ALLOW_CLIENT_INFER true Whether client-facing tools (MCP, REST) can use infer=False. When false, infer is always forced to true for client requests. Internal callers (consolidation, remember) are unaffected
CONSOLIDATION_LLM_MODEL Optional separate LLM model for consolidation. Falls back to FSCK_LLM_MODEL, then LLM_MODEL. Consolidation benefits from a stronger model
CONSOLIDATION_REASONING_EFFORT Reasoning effort for consolidation LLM calls. Falls back to FSCK_REASONING_EFFORT, then LLM_REASONING_EFFORT
CONSOLIDATION_CHECK_INTERVAL 300 How often the consolidation loop checks for idle sessions (seconds). Separate from idle threshold which controls eligibility
CONSOLIDATION_IDLE_THRESHOLD 3600 Seconds before a session is eligible for within-session consolidation (1 hour)
CONSOLIDATION_BATCH_SIZE 100 Max raw memories per consolidation LLM call. Sessions with more are split into time-based batches
CONSOLIDATION_MAX_RAW_PER_USER 500 Max raw memories to process per user during cross-session consolidation
CONSOLIDATION_MAX_CLUSTERS 20 Max clusters to evaluate during cross-session consolidation
CONSOLIDATION_RAW_RETENTION_DAYS 30 Days to retain superseded raw memories before garbage collection. Artifact-bearing memories are always retained
RECALL_RAW_PENALTY 0.05 Score penalty for raw-layer memories in search results
RECALL_SUPERSEDED_PENALTY 0.15 Score penalty for superseded raw memories in search results

Instruction Modes

The INSTRUCTION_MODE env var controls how aggressively the LLM uses memory tools. These instructions are sent via the MCP protocol and injected into the LLM's system prompt by supporting clients.

Mode Description
passive Soft guidance — use memory when asked or clearly relevant. Minimal behavioral directives.
proactive Default. Always search before answering, proactively store new information, treat memory as primary context. Plug-and-play magic.
personality Proactive + identity development. The agent can develop and maintain its own personality, knowledge, and "soul" through role=assistant memories.

For most setups, proactive (default) is the right choice — it makes memory work automatically without any system prompt configuration. Use personality when all connected agents should develop their own identity. Use passive for manual control.

To activate personality behavior for a specific agent while keeping the server in proactive mode, add the personality snippet to that agent's system prompt instead. See system-prompts/ for templates.

Authentication

mnemory supports two authentication modes:

  • Standalone mode — API keys via MCP_API_KEY / MCP_API_KEYS
  • Cognis integration mode — ES256 JWTs signed by Cognis via Authorization: Bearer <jwt>

JWT validation is optional and additive. If both JWT validation and API keys are configured, mnemory tries JWT validation first for Bearer tokens and falls back to API key matching if JWT validation fails.

Cognis JWT Validation

Configure one verifier source:

MNEMORY_JWT_PUBLIC_KEY=/path/to/cognis-public.pem
# or
MNEMORY_JWKS_URL=https://cognis.example.com/.well-known/jwks.json
  • Verifies iss="cognis"
  • Requires aud to include "mnemory"
  • Binds user_id from JWT sub
  • Uses JWT agent_id when present, otherwise falls back to X-Agent-Id
  • Rejects requests when JWT agent_id and X-Agent-Id disagree

Session-Level Identity (MCP_API_KEYS)

Map API keys to user IDs so the LLM doesn't need to pass user_id in every tool call:

MCP_API_KEYS='{"mnm-key-for-filip": "filip", "mnm-shared-service-key": "*"}'
  • "key": "username" — authenticates AND binds user_id=username to the session
  • "key": "*" — authenticates only (wildcard), user_id must come from identity headers or tool parameter

Identity resolution priority (user_id):

  1. Cognis JWT sub claim — most secure, cannot be overridden
  2. API key mapping (non-wildcard) — cannot be overridden
  3. X-User-Id HTTP header — explicit identity header
  4. X-OpenWebUI-User-Email HTTP header — automatic Open WebUI integration
  5. Tool parameter — backward compatible fallback

Agent ID is set via the X-Agent-Id HTTP header per client connection:

  • Open WebUI: X-Agent-Id: open-webui
  • Claude Code: X-Agent-Id: claude-code

Timezone is set via the X-Timezone HTTP header per client connection. This overrides the DEFAULT_TIMEZONE env var for the session, affecting how naive event_date values are interpreted. Use an IANA timezone name (e.g., Europe/Prague, America/New_York).

MCP_API_KEY (single key) is kept for backward compatibility — it authenticates but does not bind to a user. If both MCP_API_KEYS and MCP_API_KEY are set, MCP_API_KEYS is checked first, then MCP_API_KEY as fallback.

When mnemory runs in JWT-only mode without API keys, artifact download tokens keep their existing ephemeral signing behavior across restarts. This is acceptable for Stage 0 Cognis integration, but production deployments that need stable raw artifact URLs should continue to configure an API key until a dedicated download-token signing secret is introduced.

Management Port

By default, /health and /metrics are served on the main port (MCP_PORT) and go through standard API key authentication. Set MGMT_PORT to run unauthenticated copies of these endpoints on a separate port — useful for Kubernetes probes and Prometheus scraping:

MGMT_PORT=9090          # /health and /metrics on port 9090, no auth
MGMT_HOST=127.0.0.1     # Optional: bind management to localhost only

When MGMT_PORT is set and differs from MCP_PORT:

  • /health and /metrics are served on MGMT_PORT without auth
  • The main port (MCP_PORT) still serves authenticated /health and /metrics
  • All MCP and REST API endpoints remain on the main port with auth

When MGMT_PORT is not set (default):

  • /health and /metrics are on the main port with standard auth
  • Kubernetes probes and Prometheus must send a valid API key