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 with python3 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 keyEnvironment variableDefaultRestartDescription
auto_migrateMNEMOSYNE_AUTO_MIGRATEtruenoRun packaged migrations automatically on database open.
auto_sleep_enabledMNEMOSYNE_AUTO_SLEEP_ENABLEDtruenoRun consolidation automatically on a background daemon.
backup_dirMNEMOSYNE_BACKUP_DIR(unset)yesDirectory for mnemosyne backups snapshots.
blob_dirMNEMOSYNE_BLOB_DIR(unset)yesDirectory for content-addressed blob storage.
conflict_llm_api_keyMNEMOSYNE_CONFLICT_LLM_API_KEY(unset)noAPI key for the conflict detection endpoint.
conflict_llm_base_urlMNEMOSYNE_CONFLICT_LLM_BASE_URL(unset)noBase URL for the conflict detection endpoint.
conflict_llm_modelMNEMOSYNE_CONFLICT_LLM_MODEL(unset)noModel for conflict detection calls.
cross_sessionMNEMOSYNE_CROSS_SESSIONfalsenoAllow recall to return memories from other sessions.
data_dirMNEMOSYNE_DATA_DIR(unset)yesRoot directory for all Mnemosyne data. Overrides the $HERMES_HOME default.
db_pathMNEMOSYNE_DB_PATH(unset)yesExplicit path to the primary SQLite database file.
default_ownerMNEMOSYNE_DEFAULT_OWNER(unset)yesDefault owner ID for canonical facts and shared memory.
default_scopeMNEMOSYNE_DEFAULT_SCOPEsessionnoDefault scope for new memories: session or global.
degrade_batchMNEMOSYNE_DEGRADE_BATCH100noRows degraded per maintenance pass.
embedding_api_keyMNEMOSYNE_EMBEDDING_API_KEY(unset)noAPI key for a remote embedding provider. Falls back to OPENAI_API_KEY.
embedding_api_urlMNEMOSYNE_EMBEDDING_API_URL(unset)yesBase URL of an OpenAI-compatible embedding endpoint.
embedding_dimMNEMOSYNE_EMBEDDING_DIM384yesOverride the embedding dimension. Must match the dimension stored in the existing vec tables.
embedding_modelMNEMOSYNE_EMBEDDING_MODELBAAI/bge-small-en-v1.5yesEmbedding model name. Local fastembed model, or an API model when routed to a provider.
embeddings_offMNEMOSYNE_EMBEDDINGS_OFFfalsenoAlias for no_embeddings.
embeddings_via_apiMNEMOSYNE_EMBEDDINGS_VIA_APIfalsenoForce API mode for embeddings instead of inferring it from the model name.
enhanced_recallMNEMOSYNE_ENHANCED_RECALLfalsenoEnable the enhanced recall pipeline with fact, graph, and episodic fusion.
ep_limitMNEMOSYNE_EP_LIMIT50000noMaximum rows retained in episodic_memory.
fact_recall_enabledMNEMOSYNE_FACT_RECALL_ENABLED0 1 (declared true)noEnable structured fact matching during recall.
fastembed_cache_dirMNEMOSYNE_FASTEMBED_CACHE_DIR(unset)yesCache directory for downloaded fastembed ONNX models.
force_localMNEMOSYNE_FORCE_LOCALfalsenoSkip the remote chain and use the local GGUF model directly.
fts_weightMNEMOSYNE_FTS_WEIGHT0.3noFTS5 rank weight in hybrid ranking.
homeMNEMOSYNE_HOME(unset)yesBase Hermes home directory used to derive default paths.
host_llm_enabledMNEMOSYNE_HOST_LLM_ENABLEDfalsenoRoute LLM work through a host-registered backend. See core/llm_backends.py.
host_llm_modelMNEMOSYNE_HOST_LLM_MODEL(unset)noModel override passed to the host backend.
host_llm_n_ctxMNEMOSYNE_HOST_LLM_N_CTX32000 2 (declared 2048)noContext budget assumed for the host backend.
host_llm_providerMNEMOSYNE_HOST_LLM_PROVIDER(unset)noProvider override passed to the host backend.
ignore_patternsMNEMOSYNE_IGNORE_PATTERNS(unset)noComma separated regexes; matching content is never stored.
importance_weightMNEMOSYNE_IMPORTANCE_WEIGHT0.2noImportance weight in hybrid ranking.
lenient_fact_matchMNEMOSYNE_LENIENT_FACT_MATCHfalsenoMatch facts by substring instead of exact equality.
llm_api_keyMNEMOSYNE_LLM_API_KEY(unset)noAPI key for the remote chat endpoint.
llm_base_urlMNEMOSYNE_LLM_BASE_URL(unset)noBase URL of an OpenAI-compatible chat endpoint.
llm_conflict_detectionMNEMOSYNE_LLM_CONFLICT_DETECTIONfalsenoEnable LLM-based contradiction detection during sleep.
llm_enabledMNEMOSYNE_LLM_ENABLEDtrue 3 (declared false)noEnable LLM summarization during sleep consolidation.
llm_fallback_api_keyMNEMOSYNE_LLM_FALLBACK_API_KEY(unset)noAPI key for the fallback chat endpoint.
llm_fallback_base_urlMNEMOSYNE_LLM_FALLBACK_BASE_URL(unset)noBase URL for the fallback chat endpoint.
llm_fallback_modelsMNEMOSYNE_LLM_FALLBACK_MODELS(unset)noComma separated models to try if the primary fails.
llm_fileMNEMOSYNE_LLM_FILE(unset)yesGGUF filename within the repo.
llm_max_tokensMNEMOSYNE_LLM_MAX_TOKENS2048 4 (declared 512)noMaximum output tokens per LLM summary.
llm_modelMNEMOSYNE_LLM_MODEL(unset)noModel identifier for remote chat calls.
llm_n_ctxMNEMOSYNE_LLM_N_CTX2048noContext window for local GGUF inference.
llm_n_threadsMNEMOSYNE_LLM_N_THREADS4noCPU threads for local GGUF inference.
llm_repoMNEMOSYNE_LLM_REPO(unset)yesHugging Face repo holding the local GGUF model.
llm_timeoutMNEMOSYNE_LLM_TIMEOUT60noPer-request timeout in seconds for LLM calls.
no_embeddingsMNEMOSYNE_NO_EMBEDDINGSfalsenoDisable dense retrieval entirely. Recall degrades to lexical FTS5.
persona_daily_sync_hourMNEMOSYNE_PERSONA_DAILY_SYNC_HOUR3noLocal hour at which the daily persona sync runs.
persona_enabledMNEMOSYNE_PERSONA_ENABLEDtruenoInject L3 persona facts into the system prompt.
persona_intervalMNEMOSYNE_PERSONA_INTERVAL50 5 (declared 10)noTurns between persona refreshes.
persona_token_capMNEMOSYNE_PERSONA_TOKEN_CAP1500 6 (declared 500)noToken budget for injected persona facts.
polyphonic_recallMNEMOSYNE_POLYPHONIC_RECALLfalsenoEnable the polyphonic multi-voice recall engine with RRF fusion.
prefetch_content_charsMNEMOSYNE_PREFETCH_CONTENT_CHARS2000noTruncate prefetched memory content to this many characters. 0 disables truncation.
proactive_linkingMNEMOSYNE_PROACTIVE_LINKING0 7 (declared true)noCreate cross-memory graph edges on insertion.
query_intentMNEMOSYNE_QUERY_INTENT0 8 (declared true)noClassify query intent and adjust scoring weights accordingly.
recall_diagnosticsMNEMOSYNE_RECALL_DIAGNOSTICSfalsenoCollect per-stage recall diagnostics. See explain=True.
recall_extra_stopwordsMNEMOSYNE_RECALL_EXTRA_STOPWORDS(unset)noExtra comma or space separated stopwords for lexical recall.
recency_halflifeMNEMOSYNE_RECENCY_HALFLIFE168noHours until the recency decay factor halves.
reflect_disabled_for_cronMNEMOSYNE_REFLECT_DISABLED_FOR_CRONtruenoSkip reflection when running in a cron context.
reflect_max_calls_per_sessionMNEMOSYNE_REFLECT_MAX_CALLS_PER_SESSION3noMaximum reflection passes per session.
shared_db_pathMNEMOSYNE_SHARED_DB_PATH(unset)yesPath to the shared cross-agent surface database.
shmr_batch_sizeMNEMOSYNE_SHMR_BATCH_SIZE50noMemories per SHMR harmonization batch.
shmr_harmony_thresholdMNEMOSYNE_SHMR_HARMONY_THRESHOLD0.60 9 (declared 0.5)noHarmony score required to merge a cluster into a belief.
shmr_max_iterationsMNEMOSYNE_SHMR_MAX_ITERATIONS3 10 (declared 10)noMaximum clustering iterations per SHMR batch.
shmr_min_cluster_sizeMNEMOSYNE_SHMR_MIN_CLUSTER_SIZE2 11 (declared 3)noMinimum memories required to form a cluster.
shmr_modelMNEMOSYNE_SHMR_MODEL(unset)noLLM model for SHMR summarization. Empty uses the default chain.
shmr_similarity_thresholdMNEMOSYNE_SHMR_SIMILARITY_THRESHOLD0.7noCosine similarity required to cluster two memories.
shmr_temperatureMNEMOSYNE_SHMR_TEMPERATURE0.2 12 (declared 0.3)noSampling temperature for SHMR summarization.
skip_contextsMNEMOSYNE_SKIP_CONTEXTScron,flush,subagent,background,skill_loopnoComma separated host context names that should not write memories.
skip_embeddingsMNEMOSYNE_SKIP_EMBEDDINGSfalsenoAlias for no_embeddings.
sleep_batchMNEMOSYNE_SLEEP_BATCH5000noWorking memory rows processed per sleep cycle.
sleep_model_refresh_auto_applyMNEMOSYNE_SLEEP_MODEL_REFRESH_AUTO_APPLYtruenoApply high-confidence proposals without review.
sleep_model_refresh_auto_apply_min_confidenceMNEMOSYNE_SLEEP_MODEL_REFRESH_AUTO_APPLY_MIN_CONFIDENCE0.90 13 (declared 0.7)noMinimum confidence to auto-apply a proposal.
sleep_model_refresh_categoriesMNEMOSYNE_SLEEP_MODEL_REFRESH_CATEGORIESuser,workflow,projectnoComma separated canonical categories eligible for refresh.
sleep_model_refresh_conflict_min_confidenceMNEMOSYNE_SLEEP_MODEL_REFRESH_CONFLICT_MIN_CONFIDENCE0.98 14 (declared 0.8)noMinimum confidence to auto-apply a proposal that contradicts a current fact.
sleep_model_refresh_conflict_min_evidenceMNEMOSYNE_SLEEP_MODEL_REFRESH_CONFLICT_MIN_EVIDENCE3 15 (declared 5)noMinimum supporting memories for a contradicting change.
sleep_model_refresh_enabledMNEMOSYNE_SLEEP_MODEL_REFRESH_ENABLEDtruenoLet sleep propose updates to canonical facts.
sleep_model_refresh_max_tokensMNEMOSYNE_SLEEP_MODEL_REFRESH_MAX_TOKENS2048 16 (declared 1024)noToken budget for a refresh proposal.
sleep_model_refresh_min_evidenceMNEMOSYNE_SLEEP_MODEL_REFRESH_MIN_EVIDENCE2 17 (declared 3)noMinimum supporting memories before proposing a change.
sleep_model_refresh_temperatureMNEMOSYNE_SLEEP_MODEL_REFRESH_TEMPERATURE0.1 18 (declared 0.3)noSampling temperature for refresh proposals.
sleep_promptMNEMOSYNE_SLEEP_PROMPT(unset)noOverride the consolidation summarization prompt.
smart_compressMNEMOSYNE_SMART_COMPRESStruenoUse LLM summarization rather than truncation when degrading a tier.
sp_maxMNEMOSYNE_SP_MAX1000noMaximum scratchpad entries retained.
sync_encryptMNEMOSYNE_SYNC_ENCRYPTfalsenoEncrypt sync payloads client-side with XChaCha20-Poly1305.
sync_hostMNEMOSYNE_SYNC_HOST127.0.0.1yesBind address for mnemosyne sync-serve.
sync_keyMNEMOSYNE_SYNC_KEY(unset)noPassphrase used to derive the client-side encryption key.
sync_portMNEMOSYNE_SYNC_PORT8765yesBind port for mnemosyne sync-serve.
sync_remoteMNEMOSYNE_SYNC_REMOTE(unset)yesRemote sync server URL.
sync_rolesMNEMOSYNE_SYNC_ROLESusernoConversation roles synced into memory. Defaults to user turns only.
sync_turn_assistant_limitMNEMOSYNE_SYNC_TURN_ASSISTANT_LIMIT10noMaximum assistant turns captured per sync pass.
sync_turn_user_limitMNEMOSYNE_SYNC_TURN_USER_LIMIT10noMaximum user turns captured per sync pass.
temporal_halflife_hoursMNEMOSYNE_TEMPORAL_HALFLIFE_HOURS24 19 (declared 168)noHours until the temporal recall boost decays by half.
tier1_weightMNEMOSYNE_TIER1_WEIGHT1.0noRecall score multiplier for tier 1 (fresh) episodic memories.
tier2_daysMNEMOSYNE_TIER2_DAYS30noAge in days at which an episodic memory degrades to tier 2.
tier2_weightMNEMOSYNE_TIER2_WEIGHT0.5noRecall score multiplier for tier 2 memories.
tier3_daysMNEMOSYNE_TIER3_DAYS180noAge in days at which an episodic memory degrades to tier 3.
tier3_max_charsMNEMOSYNE_TIER3_MAX_CHARS300noCharacter budget for tier 3 compressed content.
tier3_weightMNEMOSYNE_TIER3_WEIGHT0.25noRecall score multiplier for tier 3 memories.
vec_typeMNEMOSYNE_VEC_TYPEint8yessqlite-vec element type: int8, float32, or bit.
vec_weightMNEMOSYNE_VEC_WEIGHT0.5noVector similarity weight in hybrid ranking. Normalized with the next two to sum to 1.0.
wm_bump_cap_hoursMNEMOSYNE_WM_BUMP_CAP_HOURS24noMaximum window in which a recall can refresh a row's recency.
wm_max_itemsMNEMOSYNE_WM_MAX_ITEMS10000noMaximum rows retained in working_memory before eviction.
wm_pinned_idsMNEMOSYNE_WM_PINNED_IDS(unset)noComma separated memory IDs that are never evicted.
wm_ttl_hoursMNEMOSYNE_WM_TTL_HOURS168noAge at which a working memory row becomes eligible for consolidation or trim.
write_classifierMNEMOSYNE_WRITE_CLASSIFIER(unset)noWrite 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 variableDescription
MNEMOSYNE_AUTHOR_IDIdentifier recorded as the author of new memories.
MNEMOSYNE_AUTHOR_TYPEAuthor kind: user, assistant, system.
MNEMOSYNE_AUTO_SLEEP_TIMEOUTSeconds the Hermes provider waits for a background sleep to finish.
MNEMOSYNE_BANKDefault memory bank for CLI operations.
MNEMOSYNE_BEAM_MODEEnable BEAM mode extensions in the polyphonic engine.
MNEMOSYNE_BEAM_OPTIMIZATIONSEnable BEAM benchmark optimizations.
MNEMOSYNE_BINARY_BONUSA/B toggle for the binary vector bonus in episodic scoring.
MNEMOSYNE_BUSY_TIMEOUT_MSSQLite busy_timeout in milliseconds.
MNEMOSYNE_CHANNEL_IDChannel or session identifier for memory scoping.
MNEMOSYNE_CONTEXT_INCLUDE_CONSOLIDATEDInclude already-consolidated rows in assembled context.
MNEMOSYNE_CROSS_TIER_DEDUPA/B toggle for deduplication across working and episodic results.
MNEMOSYNE_EMBEDDING_DOC_PREFIXPrefix prepended to documents before embedding. Applied verbatim.
MNEMOSYNE_EMBEDDING_QUERY_PREFIXPrefix prepended to queries before embedding. Applied verbatim.
MNEMOSYNE_EMBEDDING_THREADSThread count for local ONNX embedding inference.
MNEMOSYNE_EXTRACTION_MODELModel used by the cloud extraction client.
MNEMOSYNE_EXTRACTION_PROMPTOverride the fact extraction prompt.
MNEMOSYNE_FACT_BONUSA/B toggle for the fact match bonus in episodic scoring.
MNEMOSYNE_GRAPH_BONUSA/B toggle for the graph traversal bonus in episodic scoring.
MNEMOSYNE_HOST_LLM_TIMEOUTTimeout in seconds for host LLM backend calls.
MNEMOSYNE_IMPORTED_WEIGHTVeracity multiplier for imported memories.
MNEMOSYNE_INFERRED_WEIGHTVeracity multiplier for inferred memories.
MNEMOSYNE_MCP_BANKMemory bank used by the MCP server.
MNEMOSYNE_MCP_TOKENBearer token for MCP SSE auth. Required for any non-loopback bind.
MNEMOSYNE_PERSONA_FILEPath to an external persona facts file.
MNEMOSYNE_PREFETCH_MODEL_SLOT_LIMITMaximum canonical slots prefetched per turn.
MNEMOSYNE_PREFETCH_MODEL_SLOT_MIN_OVERLAPMinimum token overlap for a canonical slot to count as relevant.
MNEMOSYNE_PREFETCH_PROFILEPrefetch profile name, for example general or coding.
MNEMOSYNE_SESSION_END_TIMEOUTSeconds allowed for end-of-session memory writes.
MNEMOSYNE_SHUTDOWN_DRAIN_TIMEOUTSeconds allowed to drain pending writes on shutdown.
MNEMOSYNE_STATED_WEIGHTVeracity multiplier for directly stated memories.
MNEMOSYNE_SYNC_KEY_SOURCEWhere the sync passphrase comes from: keyring or prompt.
MNEMOSYNE_SYNC_MODESync mode selector used by the Hermes sync adapter.
MNEMOSYNE_SYNC_TOKENBearer token presented to the sync server.
MNEMOSYNE_SYNC_TURN_SLOW_THRESHOLDMilliseconds after which a turn sync is logged as slow.
MNEMOSYNE_TOOL_WEIGHTVeracity multiplier for tool-produced memories.
MNEMOSYNE_UNKNOWN_WEIGHTVeracity multiplier for memories of unknown provenance.
MNEMOSYNE_USE_CAVEMANUse the AAAK keyword compression fallback for consolidation.
MNEMOSYNE_VERACITY_MULTIPLIERA/B toggle for applying veracity multipliers at all.
MNEMOSYNE_VOICE_FACTSet to 0 to disable the polyphonic fact voice.
MNEMOSYNE_VOICE_GRAPHSet to 0 to disable the polyphonic graph voice.
MNEMOSYNE_VOICE_TEMPORALSet to 0 to disable the polyphonic temporal voice.
MNEMOSYNE_VOICE_VECTORSet 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

  1. fact_recall_enabled -- effective default 0, set in mnemosyne/core/beam.py, not the true declared in config.py.

  2. host_llm_n_ctx -- effective default 32000, set in mnemosyne/core/local_llm.py, not the 2048 declared in config.py.

  3. llm_enabled -- effective default true, set in mnemosyne/core/local_llm.py, not the false declared in config.py. Note the direction: config.py declares this off while the module defaults it on.

  4. llm_max_tokens -- effective default 2048, set in mnemosyne/core/local_llm.py, not the 512 declared in config.py.

  5. persona_interval -- effective default 50, set in mnemosyne/core/persona.py, not the 10 declared in config.py.

  6. persona_token_cap -- effective default 1500, set in mnemosyne/core/persona.py, not the 500 declared in config.py.

  7. proactive_linking -- effective default 0, set in mnemosyne/core/beam.py, not the true declared in config.py.

  8. query_intent -- effective default 0, set in mnemosyne/core/beam.py, not the true declared in config.py.

  9. shmr_harmony_threshold -- effective default 0.60, set in mnemosyne/core/shmr.py, not the 0.5 declared in config.py.

  10. shmr_max_iterations -- effective default 3, set in mnemosyne/core/shmr.py, not the 10 declared in config.py.

  11. shmr_min_cluster_size -- effective default 2, set in mnemosyne/core/shmr.py, not the 3 declared in config.py.

  12. shmr_temperature -- effective default 0.2, set in mnemosyne/core/shmr.py, not the 0.3 declared in config.py.

  13. sleep_model_refresh_auto_apply_min_confidence -- effective default 0.90, set in mnemosyne/core/model_refresh.py, not the 0.7 declared in config.py.

  14. sleep_model_refresh_conflict_min_confidence -- effective default 0.98, set in mnemosyne/core/model_refresh.py, not the 0.8 declared in config.py.

  15. sleep_model_refresh_conflict_min_evidence -- effective default 3, set in mnemosyne/core/model_refresh.py, not the 5 declared in config.py.

  16. sleep_model_refresh_max_tokens -- effective default 2048, set in mnemosyne/core/model_refresh.py, not the 1024 declared in config.py.

  17. sleep_model_refresh_min_evidence -- effective default 2, set in mnemosyne/core/model_refresh.py, not the 3 declared in config.py.

  18. sleep_model_refresh_temperature -- effective default 0.1, set in mnemosyne/core/model_refresh.py, not the 0.3 declared in config.py.

  19. temporal_halflife_hours -- effective default 24, set in mnemosyne/core/beam.py, not the 168 declared in config.py.