Configuration
August 5, 2026 · View on GitHub
Generated file. Do not edit by hand. Source:
mnemosyne/core/config.py(ENV_VAR_MAP,DEFAULTS,REQUIRES_RESTART). Regenerate withpython3 scripts/generate-docs.py.
Mnemosyne reads configuration from a YAML file and from environment variables.
Precedence is config.yaml > environment variable > built-in default.
config.yaml lives at $MNEMOSYNE_DATA_DIR/config.yaml, falling back to
$HERMES_HOME/mnemosyne/config.yaml and then ~/.hermes/mnemosyne/config.yaml.
Nested YAML works, and leaf keys resolve too, so memory.mnemosyne.wm_max_items
and wm_max_items are equivalent.
Keys marked restart are read once at startup. Changing them at runtime warns and does not take effect until the process restarts.
There are 106 configuration keys. A further
42 environment variables are read directly from the
environment and are not settable in config.yaml; they are listed separately below.
Configuration keys (106)
| Config key | Environment variable | Default | Restart | Description |
|---|---|---|---|---|
auto_migrate | MNEMOSYNE_AUTO_MIGRATE | true | no | Run packaged migrations automatically on database open. |
auto_sleep_enabled | MNEMOSYNE_AUTO_SLEEP_ENABLED | true | no | Run consolidation automatically on a background daemon. |
backup_dir | MNEMOSYNE_BACKUP_DIR | (unset) | yes | Directory for mnemosyne backups snapshots. |
blob_dir | MNEMOSYNE_BLOB_DIR | (unset) | yes | Directory for content-addressed blob storage. |
conflict_llm_api_key | MNEMOSYNE_CONFLICT_LLM_API_KEY | (unset) | no | API key for the conflict detection endpoint. |
conflict_llm_base_url | MNEMOSYNE_CONFLICT_LLM_BASE_URL | (unset) | no | Base URL for the conflict detection endpoint. |
conflict_llm_model | MNEMOSYNE_CONFLICT_LLM_MODEL | (unset) | no | Model for conflict detection calls. |
cross_session | MNEMOSYNE_CROSS_SESSION | false | no | Allow recall to return memories from other sessions. |
data_dir | MNEMOSYNE_DATA_DIR | (unset) | yes | Root directory for all Mnemosyne data. Overrides the $HERMES_HOME default. |
db_path | MNEMOSYNE_DB_PATH | (unset) | yes | Explicit path to the primary SQLite database file. |
default_owner | MNEMOSYNE_DEFAULT_OWNER | (unset) | yes | Default owner ID for canonical facts and shared memory. |
default_scope | MNEMOSYNE_DEFAULT_SCOPE | session | no | Default scope for new memories: session or global. |
degrade_batch | MNEMOSYNE_DEGRADE_BATCH | 100 | no | Rows degraded per maintenance pass. |
embedding_api_key | MNEMOSYNE_EMBEDDING_API_KEY | (unset) | no | API key for a remote embedding provider. Falls back to OPENAI_API_KEY. |
embedding_api_url | MNEMOSYNE_EMBEDDING_API_URL | (unset) | yes | Base URL of an OpenAI-compatible embedding endpoint. |
embedding_dim | MNEMOSYNE_EMBEDDING_DIM | 384 | yes | Override the embedding dimension. Must match the dimension stored in the existing vec tables. |
embedding_model | MNEMOSYNE_EMBEDDING_MODEL | BAAI/bge-small-en-v1.5 | yes | Embedding model name. Local fastembed model, or an API model when routed to a provider. |
embeddings_off | MNEMOSYNE_EMBEDDINGS_OFF | false | no | Alias for no_embeddings. |
embeddings_via_api | MNEMOSYNE_EMBEDDINGS_VIA_API | false | no | Force API mode for embeddings instead of inferring it from the model name. |
enhanced_recall | MNEMOSYNE_ENHANCED_RECALL | false | no | Enable the enhanced recall pipeline with fact, graph, and episodic fusion. |
ep_limit | MNEMOSYNE_EP_LIMIT | 50000 | no | Maximum rows retained in episodic_memory. |
fact_recall_enabled | MNEMOSYNE_FACT_RECALL_ENABLED | 0 1 (declared true) | no | Enable structured fact matching during recall. |
fastembed_cache_dir | MNEMOSYNE_FASTEMBED_CACHE_DIR | (unset) | yes | Cache directory for downloaded fastembed ONNX models. |
force_local | MNEMOSYNE_FORCE_LOCAL | false | no | Skip the remote chain and use the local GGUF model directly. |
fts_weight | MNEMOSYNE_FTS_WEIGHT | 0.3 | no | FTS5 rank weight in hybrid ranking. |
home | MNEMOSYNE_HOME | (unset) | yes | Base Hermes home directory used to derive default paths. |
host_llm_enabled | MNEMOSYNE_HOST_LLM_ENABLED | false | no | Route LLM work through a host-registered backend. See core/llm_backends.py. |
host_llm_model | MNEMOSYNE_HOST_LLM_MODEL | (unset) | no | Model override passed to the host backend. |
host_llm_n_ctx | MNEMOSYNE_HOST_LLM_N_CTX | 32000 2 (declared 2048) | no | Context budget assumed for the host backend. |
host_llm_provider | MNEMOSYNE_HOST_LLM_PROVIDER | (unset) | no | Provider override passed to the host backend. |
ignore_patterns | MNEMOSYNE_IGNORE_PATTERNS | (unset) | no | Comma separated regexes; matching content is never stored. |
importance_weight | MNEMOSYNE_IMPORTANCE_WEIGHT | 0.2 | no | Importance weight in hybrid ranking. |
lenient_fact_match | MNEMOSYNE_LENIENT_FACT_MATCH | false | no | Match facts by substring instead of exact equality. |
llm_api_key | MNEMOSYNE_LLM_API_KEY | (unset) | no | API key for the remote chat endpoint. |
llm_base_url | MNEMOSYNE_LLM_BASE_URL | (unset) | no | Base URL of an OpenAI-compatible chat endpoint. |
llm_conflict_detection | MNEMOSYNE_LLM_CONFLICT_DETECTION | false | no | Enable LLM-based contradiction detection during sleep. |
llm_enabled | MNEMOSYNE_LLM_ENABLED | true 3 (declared false) | no | Enable LLM summarization during sleep consolidation. |
llm_fallback_api_key | MNEMOSYNE_LLM_FALLBACK_API_KEY | (unset) | no | API key for the fallback chat endpoint. |
llm_fallback_base_url | MNEMOSYNE_LLM_FALLBACK_BASE_URL | (unset) | no | Base URL for the fallback chat endpoint. |
llm_fallback_models | MNEMOSYNE_LLM_FALLBACK_MODELS | (unset) | no | Comma separated models to try if the primary fails. |
llm_file | MNEMOSYNE_LLM_FILE | (unset) | yes | GGUF filename within the repo. |
llm_max_tokens | MNEMOSYNE_LLM_MAX_TOKENS | 2048 4 (declared 512) | no | Maximum output tokens per LLM summary. |
llm_model | MNEMOSYNE_LLM_MODEL | (unset) | no | Model identifier for remote chat calls. |
llm_n_ctx | MNEMOSYNE_LLM_N_CTX | 2048 | no | Context window for local GGUF inference. |
llm_n_threads | MNEMOSYNE_LLM_N_THREADS | 4 | no | CPU threads for local GGUF inference. |
llm_repo | MNEMOSYNE_LLM_REPO | (unset) | yes | Hugging Face repo holding the local GGUF model. |
llm_timeout | MNEMOSYNE_LLM_TIMEOUT | 60 | no | Per-request timeout in seconds for LLM calls. |
no_embeddings | MNEMOSYNE_NO_EMBEDDINGS | false | no | Disable dense retrieval entirely. Recall degrades to lexical FTS5. |
persona_daily_sync_hour | MNEMOSYNE_PERSONA_DAILY_SYNC_HOUR | 3 | no | Local hour at which the daily persona sync runs. |
persona_enabled | MNEMOSYNE_PERSONA_ENABLED | true | no | Inject L3 persona facts into the system prompt. |
persona_interval | MNEMOSYNE_PERSONA_INTERVAL | 50 5 (declared 10) | no | Turns between persona refreshes. |
persona_token_cap | MNEMOSYNE_PERSONA_TOKEN_CAP | 1500 6 (declared 500) | no | Token budget for injected persona facts. |
polyphonic_recall | MNEMOSYNE_POLYPHONIC_RECALL | false | no | Enable the polyphonic multi-voice recall engine with RRF fusion. |
prefetch_content_chars | MNEMOSYNE_PREFETCH_CONTENT_CHARS | 2000 | no | Truncate prefetched memory content to this many characters. 0 disables truncation. |
proactive_linking | MNEMOSYNE_PROACTIVE_LINKING | 0 7 (declared true) | no | Create cross-memory graph edges on insertion. |
query_intent | MNEMOSYNE_QUERY_INTENT | 0 8 (declared true) | no | Classify query intent and adjust scoring weights accordingly. |
recall_diagnostics | MNEMOSYNE_RECALL_DIAGNOSTICS | false | no | Collect per-stage recall diagnostics. See explain=True. |
recall_extra_stopwords | MNEMOSYNE_RECALL_EXTRA_STOPWORDS | (unset) | no | Extra comma or space separated stopwords for lexical recall. |
recency_halflife | MNEMOSYNE_RECENCY_HALFLIFE | 168 | no | Hours until the recency decay factor halves. |
reflect_disabled_for_cron | MNEMOSYNE_REFLECT_DISABLED_FOR_CRON | true | no | Skip reflection when running in a cron context. |
reflect_max_calls_per_session | MNEMOSYNE_REFLECT_MAX_CALLS_PER_SESSION | 3 | no | Maximum reflection passes per session. |
shared_db_path | MNEMOSYNE_SHARED_DB_PATH | (unset) | yes | Path to the shared cross-agent surface database. |
shmr_batch_size | MNEMOSYNE_SHMR_BATCH_SIZE | 50 | no | Memories per SHMR harmonization batch. |
shmr_harmony_threshold | MNEMOSYNE_SHMR_HARMONY_THRESHOLD | 0.60 9 (declared 0.5) | no | Harmony score required to merge a cluster into a belief. |
shmr_max_iterations | MNEMOSYNE_SHMR_MAX_ITERATIONS | 3 10 (declared 10) | no | Maximum clustering iterations per SHMR batch. |
shmr_min_cluster_size | MNEMOSYNE_SHMR_MIN_CLUSTER_SIZE | 2 11 (declared 3) | no | Minimum memories required to form a cluster. |
shmr_model | MNEMOSYNE_SHMR_MODEL | (unset) | no | LLM model for SHMR summarization. Empty uses the default chain. |
shmr_similarity_threshold | MNEMOSYNE_SHMR_SIMILARITY_THRESHOLD | 0.7 | no | Cosine similarity required to cluster two memories. |
shmr_temperature | MNEMOSYNE_SHMR_TEMPERATURE | 0.2 12 (declared 0.3) | no | Sampling temperature for SHMR summarization. |
skip_contexts | MNEMOSYNE_SKIP_CONTEXTS | cron,flush,subagent,background,skill_loop | no | Comma separated host context names that should not write memories. |
skip_embeddings | MNEMOSYNE_SKIP_EMBEDDINGS | false | no | Alias for no_embeddings. |
sleep_batch | MNEMOSYNE_SLEEP_BATCH | 5000 | no | Working memory rows processed per sleep cycle. |
sleep_model_refresh_auto_apply | MNEMOSYNE_SLEEP_MODEL_REFRESH_AUTO_APPLY | true | no | Apply high-confidence proposals without review. |
sleep_model_refresh_auto_apply_min_confidence | MNEMOSYNE_SLEEP_MODEL_REFRESH_AUTO_APPLY_MIN_CONFIDENCE | 0.90 13 (declared 0.7) | no | Minimum confidence to auto-apply a proposal. |
sleep_model_refresh_categories | MNEMOSYNE_SLEEP_MODEL_REFRESH_CATEGORIES | user,workflow,project | no | Comma separated canonical categories eligible for refresh. |
sleep_model_refresh_conflict_min_confidence | MNEMOSYNE_SLEEP_MODEL_REFRESH_CONFLICT_MIN_CONFIDENCE | 0.98 14 (declared 0.8) | no | Minimum confidence to auto-apply a proposal that contradicts a current fact. |
sleep_model_refresh_conflict_min_evidence | MNEMOSYNE_SLEEP_MODEL_REFRESH_CONFLICT_MIN_EVIDENCE | 3 15 (declared 5) | no | Minimum supporting memories for a contradicting change. |
sleep_model_refresh_enabled | MNEMOSYNE_SLEEP_MODEL_REFRESH_ENABLED | true | no | Let sleep propose updates to canonical facts. |
sleep_model_refresh_max_tokens | MNEMOSYNE_SLEEP_MODEL_REFRESH_MAX_TOKENS | 2048 16 (declared 1024) | no | Token budget for a refresh proposal. |
sleep_model_refresh_min_evidence | MNEMOSYNE_SLEEP_MODEL_REFRESH_MIN_EVIDENCE | 2 17 (declared 3) | no | Minimum supporting memories before proposing a change. |
sleep_model_refresh_temperature | MNEMOSYNE_SLEEP_MODEL_REFRESH_TEMPERATURE | 0.1 18 (declared 0.3) | no | Sampling temperature for refresh proposals. |
sleep_prompt | MNEMOSYNE_SLEEP_PROMPT | (unset) | no | Override the consolidation summarization prompt. |
smart_compress | MNEMOSYNE_SMART_COMPRESS | true | no | Use LLM summarization rather than truncation when degrading a tier. |
sp_max | MNEMOSYNE_SP_MAX | 1000 | no | Maximum scratchpad entries retained. |
sync_encrypt | MNEMOSYNE_SYNC_ENCRYPT | false | no | Encrypt sync payloads client-side with XChaCha20-Poly1305. |
sync_host | MNEMOSYNE_SYNC_HOST | 127.0.0.1 | yes | Bind address for mnemosyne sync-serve. |
sync_key | MNEMOSYNE_SYNC_KEY | (unset) | no | Passphrase used to derive the client-side encryption key. |
sync_port | MNEMOSYNE_SYNC_PORT | 8765 | yes | Bind port for mnemosyne sync-serve. |
sync_remote | MNEMOSYNE_SYNC_REMOTE | (unset) | yes | Remote sync server URL. |
sync_roles | MNEMOSYNE_SYNC_ROLES | user | no | Conversation roles synced into memory. Defaults to user turns only. |
sync_turn_assistant_limit | MNEMOSYNE_SYNC_TURN_ASSISTANT_LIMIT | 10 | no | Maximum assistant turns captured per sync pass. |
sync_turn_user_limit | MNEMOSYNE_SYNC_TURN_USER_LIMIT | 10 | no | Maximum user turns captured per sync pass. |
temporal_halflife_hours | MNEMOSYNE_TEMPORAL_HALFLIFE_HOURS | 24 19 (declared 168) | no | Hours until the temporal recall boost decays by half. |
tier1_weight | MNEMOSYNE_TIER1_WEIGHT | 1.0 | no | Recall score multiplier for tier 1 (fresh) episodic memories. |
tier2_days | MNEMOSYNE_TIER2_DAYS | 30 | no | Age in days at which an episodic memory degrades to tier 2. |
tier2_weight | MNEMOSYNE_TIER2_WEIGHT | 0.5 | no | Recall score multiplier for tier 2 memories. |
tier3_days | MNEMOSYNE_TIER3_DAYS | 180 | no | Age in days at which an episodic memory degrades to tier 3. |
tier3_max_chars | MNEMOSYNE_TIER3_MAX_CHARS | 300 | no | Character budget for tier 3 compressed content. |
tier3_weight | MNEMOSYNE_TIER3_WEIGHT | 0.25 | no | Recall score multiplier for tier 3 memories. |
vec_type | MNEMOSYNE_VEC_TYPE | int8 | yes | sqlite-vec element type: int8, float32, or bit. |
vec_weight | MNEMOSYNE_VEC_WEIGHT | 0.5 | no | Vector similarity weight in hybrid ranking. Normalized with the next two to sum to 1.0. |
wm_bump_cap_hours | MNEMOSYNE_WM_BUMP_CAP_HOURS | 24 | no | Maximum window in which a recall can refresh a row's recency. |
wm_max_items | MNEMOSYNE_WM_MAX_ITEMS | 10000 | no | Maximum rows retained in working_memory before eviction. |
wm_pinned_ids | MNEMOSYNE_WM_PINNED_IDS | (unset) | no | Comma separated memory IDs that are never evicted. |
wm_ttl_hours | MNEMOSYNE_WM_TTL_HOURS | 168 | no | Age at which a working memory row becomes eligible for consolidation or trim. |
write_classifier | MNEMOSYNE_WRITE_CLASSIFIER | (unset) | no | Write classifier mode controlling which content is stored. |
Keys whose effective default bypasses config.py (19)
For these keys a module-level constant reads the environment variable directly with its own fallback, so the value in DEFAULTS is not what the runtime uses and a config.yaml entry alone does not reach the module. Treat the environment variable as authoritative.
This list is derived by scanning the package for os.environ.get("MNEMOSYNE_...", default) and diffing against DEFAULTS, so it cannot fall out of date.
Environment-only variables (42)
These are read with os.environ at their point of use and bypass
MnemosyneConfig entirely. They cannot be set in config.yaml.
| Environment variable | Description |
|---|---|
MNEMOSYNE_AUTHOR_ID | Identifier recorded as the author of new memories. |
MNEMOSYNE_AUTHOR_TYPE | Author kind: user, assistant, system. |
MNEMOSYNE_AUTO_SLEEP_TIMEOUT | Seconds the Hermes provider waits for a background sleep to finish. |
MNEMOSYNE_BANK | Default memory bank for CLI operations. |
MNEMOSYNE_BEAM_MODE | Enable BEAM mode extensions in the polyphonic engine. |
MNEMOSYNE_BEAM_OPTIMIZATIONS | Enable BEAM benchmark optimizations. |
MNEMOSYNE_BINARY_BONUS | A/B toggle for the binary vector bonus in episodic scoring. |
MNEMOSYNE_BUSY_TIMEOUT_MS | SQLite busy_timeout in milliseconds. |
MNEMOSYNE_CHANNEL_ID | Channel or session identifier for memory scoping. |
MNEMOSYNE_CONTEXT_INCLUDE_CONSOLIDATED | Include already-consolidated rows in assembled context. |
MNEMOSYNE_CROSS_TIER_DEDUP | A/B toggle for deduplication across working and episodic results. |
MNEMOSYNE_EMBEDDING_DOC_PREFIX | Prefix prepended to documents before embedding. Applied verbatim. |
MNEMOSYNE_EMBEDDING_QUERY_PREFIX | Prefix prepended to queries before embedding. Applied verbatim. |
MNEMOSYNE_EMBEDDING_THREADS | Thread count for local ONNX embedding inference. |
MNEMOSYNE_EXTRACTION_MODEL | Model used by the cloud extraction client. |
MNEMOSYNE_EXTRACTION_PROMPT | Override the fact extraction prompt. |
MNEMOSYNE_FACT_BONUS | A/B toggle for the fact match bonus in episodic scoring. |
MNEMOSYNE_GRAPH_BONUS | A/B toggle for the graph traversal bonus in episodic scoring. |
MNEMOSYNE_HOST_LLM_TIMEOUT | Timeout in seconds for host LLM backend calls. |
MNEMOSYNE_IMPORTED_WEIGHT | Veracity multiplier for imported memories. |
MNEMOSYNE_INFERRED_WEIGHT | Veracity multiplier for inferred memories. |
MNEMOSYNE_MCP_BANK | Memory bank used by the MCP server. |
MNEMOSYNE_MCP_TOKEN | Bearer token for MCP SSE auth. Required for any non-loopback bind. |
MNEMOSYNE_PERSONA_FILE | Path to an external persona facts file. |
MNEMOSYNE_PREFETCH_MODEL_SLOT_LIMIT | Maximum canonical slots prefetched per turn. |
MNEMOSYNE_PREFETCH_MODEL_SLOT_MIN_OVERLAP | Minimum token overlap for a canonical slot to count as relevant. |
MNEMOSYNE_PREFETCH_PROFILE | Prefetch profile name, for example general or coding. |
MNEMOSYNE_SESSION_END_TIMEOUT | Seconds allowed for end-of-session memory writes. |
MNEMOSYNE_SHUTDOWN_DRAIN_TIMEOUT | Seconds allowed to drain pending writes on shutdown. |
MNEMOSYNE_STATED_WEIGHT | Veracity multiplier for directly stated memories. |
MNEMOSYNE_SYNC_KEY_SOURCE | Where the sync passphrase comes from: keyring or prompt. |
MNEMOSYNE_SYNC_MODE | Sync mode selector used by the Hermes sync adapter. |
MNEMOSYNE_SYNC_TOKEN | Bearer token presented to the sync server. |
MNEMOSYNE_SYNC_TURN_SLOW_THRESHOLD | Milliseconds after which a turn sync is logged as slow. |
MNEMOSYNE_TOOL_WEIGHT | Veracity multiplier for tool-produced memories. |
MNEMOSYNE_UNKNOWN_WEIGHT | Veracity multiplier for memories of unknown provenance. |
MNEMOSYNE_USE_CAVEMAN | Use the AAAK keyword compression fallback for consolidation. |
MNEMOSYNE_VERACITY_MULTIPLIER | A/B toggle for applying veracity multipliers at all. |
MNEMOSYNE_VOICE_FACT | Set to 0 to disable the polyphonic fact voice. |
MNEMOSYNE_VOICE_GRAPH | Set to 0 to disable the polyphonic graph voice. |
MNEMOSYNE_VOICE_TEMPORAL | Set to 0 to disable the polyphonic temporal voice. |
MNEMOSYNE_VOICE_VECTOR | Set to 0 to disable the polyphonic vector voice. |
Recall scoring weights
vec_weight, fts_weight, and importance_weight are normalized to sum to 1.0
at query time. They are the highest-leverage tuning knobs in the system.
They resolve at request time as config.yaml > MNEMOSYNE_*_WEIGHT > defaults.
A config reload applies to the next request, and enhanced-recall cache entries
are isolated by the effective weight snapshot.
Footnotes
-
fact_recall_enabled-- effective default0, set inmnemosyne/core/beam.py, not thetruedeclared inconfig.py. ↩ -
host_llm_n_ctx-- effective default32000, set inmnemosyne/core/local_llm.py, not the2048declared inconfig.py. ↩ -
llm_enabled-- effective defaulttrue, set inmnemosyne/core/local_llm.py, not thefalsedeclared inconfig.py. Note the direction:config.pydeclares this off while the module defaults it on. ↩ -
llm_max_tokens-- effective default2048, set inmnemosyne/core/local_llm.py, not the512declared inconfig.py. ↩ -
persona_interval-- effective default50, set inmnemosyne/core/persona.py, not the10declared inconfig.py. ↩ -
persona_token_cap-- effective default1500, set inmnemosyne/core/persona.py, not the500declared inconfig.py. ↩ -
proactive_linking-- effective default0, set inmnemosyne/core/beam.py, not thetruedeclared inconfig.py. ↩ -
query_intent-- effective default0, set inmnemosyne/core/beam.py, not thetruedeclared inconfig.py. ↩ -
shmr_harmony_threshold-- effective default0.60, set inmnemosyne/core/shmr.py, not the0.5declared inconfig.py. ↩ -
shmr_max_iterations-- effective default3, set inmnemosyne/core/shmr.py, not the10declared inconfig.py. ↩ -
shmr_min_cluster_size-- effective default2, set inmnemosyne/core/shmr.py, not the3declared inconfig.py. ↩ -
shmr_temperature-- effective default0.2, set inmnemosyne/core/shmr.py, not the0.3declared inconfig.py. ↩ -
sleep_model_refresh_auto_apply_min_confidence-- effective default0.90, set inmnemosyne/core/model_refresh.py, not the0.7declared inconfig.py. ↩ -
sleep_model_refresh_conflict_min_confidence-- effective default0.98, set inmnemosyne/core/model_refresh.py, not the0.8declared inconfig.py. ↩ -
sleep_model_refresh_conflict_min_evidence-- effective default3, set inmnemosyne/core/model_refresh.py, not the5declared inconfig.py. ↩ -
sleep_model_refresh_max_tokens-- effective default2048, set inmnemosyne/core/model_refresh.py, not the1024declared inconfig.py. ↩ -
sleep_model_refresh_min_evidence-- effective default2, set inmnemosyne/core/model_refresh.py, not the3declared inconfig.py. ↩ -
sleep_model_refresh_temperature-- effective default0.1, set inmnemosyne/core/model_refresh.py, not the0.3declared inconfig.py. ↩ -
temporal_halflife_hours-- effective default24, set inmnemosyne/core/beam.py, not the168declared inconfig.py. ↩