MESA Core · v0.9.3

Configuration

v0.9.3 source: docs/configuration.md

This guide has equivalent English and Turkish versions. The source sections behind this page are at the bottom.

Local defaults and operator configuration#

mesa start provisions ~/.mesa/data, a local catalog and ~/.mesa/credentials.json; models and external providers default off. Direct runtime launchers still require explicit MESA_STORAGE_ROOT, MESA_RUNTIME_PROFILE=combined, keys and ACLs. Mesa() reads explicit arguments, environment connection settings, then local credentials.

Optional models, graph and validation#

Use MESA_LLM_MODEL=provider:model and MESA_EMBEDDING_MODEL=provider:model. For example:

bash
MESA_MODEL_ENABLED=true
MESA_LLM_MODEL=ollama:qwen2.5:7b
MESA_EMBEDDING_MODEL=ollama:bge-m3

Put local settings in ~/.mesa/.env and restart the local server. The selected provider must be installed and running. MESA_EMBEDDING_ENABLED defaults to the model flag. MESA_EXTRACTION_ENABLED=false is the default even when models are enabled; set it explicitly to true for open-ended SPO extraction. Both off still allows ingestion and BM25 search; disabled VECTOR lanes are SKIPPED. MESA_GRAPH_ENABLED=false avoids opening Kùzu, marks GRAPH lanes SKIPPED and reports graph as degraded. Re-enabling a lane backfills it on combined startup.

MESA_TIER3_MODE: 0 deterministic checks, 1 one validator, 2 distinct A/B validators. MESA_RRF_K=60, vector weight 8.0 and BM25/assertion/graph weights 1.0 control fusion. MESA_RRF_VECTOR_WEIGHT=1 restores the previous vector weight; zero removes a lane’s contribution. Durable rebuild remains disabled by default.

Provider and storage boundaries#

Local Ollama/OpenAI-compatible endpoints can run with MESA_EXTERNAL_PROVIDER_ENABLED=false; cloud providers require it to be true and need their keys. Embedding identity includes model, revision, dimension and normalization. Active vectors require an explicit rebuild before an identity change. See the full pinned setting table below; configuration is separate from operational availability.

Article-aware chunking and retries#

MESA_CHUNKING=auto|plain defaults to auto. At least three Turkish article headings at line starts trigger article-boundary splitting; long pieces remain bounded to 512 tokens and preserve exact source text. plain keeps the previous plan for new revisions. Existing ACTIVE revisions do not change. A retry preserves the plan matching the admitted text, even after restart or a setting change. If the admitted prefix matches two different plans, admission fails closed with HTTP 409 without appending chunks.

Optional BGE reranking#

MESA_RERANK_ENABLED=false is the default. Enabling it needs the [ml] extra. MESA_RERANK_MODEL=BAAI/bge-reranker-v2-m3 and MESA_RERANK_DEPTH=50 (range 1–50) configure the stage. The model loads lazily on first use, adding cold-start latency. After fusion, authorized full chunk texts are scored in a worker thread outside the shared search connection. Results add rerank_score; rrf_score and final_score retain their fusion values. Ties keep fused order. See DEV evidence and device latency.

MESA_LEGAL_RULES_ENABLED=true is independent of models. In auto plans, ordinary articles inherit a law number from metadata.law_number or a supported header in the first 3,000 characters; continuation chunks keep the article identity. Preambles, GEÇİCİ/EK articles and plain plans receive no automatic identity. Typed identities accept 3–5 digit law numbers; inconsistent number/code pairs and unknown names are rejected.

New chunks keep versioned legal items separately from SPO facts. false prevents new identities/items, bypasses legal citation/ranking/exact-match and graph citation parsing, and hides existing legal overlays in result copies without deleting stored data. Generic lexical/vector/graph retrieval remains enabled. Set MESA_EXTRACTION_ENABLED=true explicitly if model-based SPO facts are wanted; merely enabling models no longer enables extraction.

v0.9.3 embedding identity and startup#

The default is MESA_EMBEDDING_MODEL=local:BAAI/bge-m3, MESA_EMBEDDING_DIMENSION=1024, normalized. Models remain off by default. Download the local model before enabling it. For an older store created with the previous default, keep both settings below, or rebuild before changing identity:

bash
MESA_EMBEDDING_MODEL=local:magibu/embeddingmagibu-200m
MESA_EMBEDDING_DIMENSION=768

Startup rejects MESA_TIER3_MODE=1/2 without an active consolidation loop; extraction must be enabled. Bootstrap MESA_API_KEY values containing . are rejected at startup.

Sections that moved to their own page
Source reference for this page

The sections of the upstream file that back this page, unchanged. Source section links open the appendix automatically.

Source: mesa_memory/config.py, load_runtime_profile and MesaConfig.

Defaults below are field declarations, not evidence of an operational model.

Startup and precedence#

MESA_RUNTIME_PROFILE and MESA_STORAGE_ROOT are required by the runtime

loader. Profiles: combined, test-isolated. V4 requires one combined writer.

Storage aliases are tried in order ROOT, PATH, DIR, DB_PATH; a .db filename

selects its parent. Reject filesystem/home/repository root. Test-isolated

requires an absolute child of MESA_RUNTIME_LAB_ROOT and forbids models,

external providers and dotenv.

No implicit .env search. MESA_LOAD_DOTENV=true requires explicit

MESA_DOTENV_PATH; startup loads and reparses the explicit environment. The explicit dotenv file wins over existing environment values (override=True);

this can change profile/storage/provider flags, so review the file before enabling it. Pydantic constructor fields override

environment in direct programmatic configuration. Unaliased fields use their

uppercase field name; comments mentioning MESA_* do not create aliases.

mesa start and the Docker image provision an active local registry key and

credentials automatically; no bootstrap variables are needed in local mode.

mesa start --host controls the bind address (default 127.0.0.1); the

credentials' client URL always uses 127.0.0.1. The Docker image binds

0.0.0.0 internally, while Compose publishes only to the host's loopback.

The direct runtime launcher requires MESA_API_KEY bootstrap or an existing active registry key at startup.

A bootstrap key requires the server-authored MESA_PRINCIPAL_ID; use offline

admin provisioning for ACL. MESA_PORT defaults to 8000; MESA_LOG_LEVEL to INFO

and MESA_LOG_FORMAT to json. Secrets must be injected privately.

Environment file and first startup#

The template uses a standalone combined owner with models

disabled. Copy it only if needed, replace the storage path with an absolute,

writable dedicated directory, and supply issued credentials privately. To load

it explicitly, set MESA_LOAD_DOTENV=true and MESA_DOTENV_PATH to its absolute

path in the launching shell; setting them only inside the file cannot enable

loading. Do not load dotenv in test-isolated. The quickstart's exported settings

work without creating any .env file.

Fresh combined startup creates/migrates SQLite and initializes LanceDB/Kùzu;

there is no manual fresh-database migration step. Keep old storage migrations

separate: use the upgrade procedure, never delete an

existing database to resolve a startup error. Startup failures occur in the server terminal before

readiness; check the named variable, writable path or missing selected extra

there. Do not paste secrets or entire environment files into bug reports.

Declared MesaConfig fields#

Field-declaration reference; compare it with MesaConfig when configuration changes.

required or derived defaults are explicit. Legacy controls are present for V3;

Python fieldEnvironment nameDeclared default
llm_providerLLM_PROVIDER'claude'
llm_modelMESA_LLM_MODEL''
llm_base_urlMESA_LLM_BASE_URLNone
llm_api_keyMESA_LLM_API_KEYNone
llm_timeout_secondsMESA_LLM_TIMEOUT_SECONDS60.0
embedding_base_urlMESA_EMBEDDING_BASE_URLNone
embedding_api_keyMESA_EMBEDDING_API_KEYNone
extraction_thinkingMESA_EXTRACTION_THINKINGFalse
extraction_max_tokensMESA_EXTRACTION_MAX_TOKENS4096
llm_embedding_model_nameLLM_EMBEDDING_MODEL'sentence-transformers/all-MiniLM-L6-v2'
embedding_modelMESA_EMBEDDING_MODEL'local:BAAI/bge-m3'
model_enabledMESA_MODEL_ENABLEDFalse
tier3_modeMESA_TIER3_MODENone
tier3_llm_provider_aMESA_TIER3_LLM_PROVIDER_ANone
tier3_llm_model_name_aMESA_TIER3_LLM_MODEL_ANone
tier3_llm_provider_bMESA_TIER3_LLM_PROVIDER_BNone
tier3_llm_model_name_bMESA_TIER3_LLM_MODEL_BNone
external_provider_enabledMESA_EXTERNAL_PROVIDER_ENABLEDFalse
embedding_dimensionMESA_EMBEDDING_DIMENSIONdetected at startup when enabled and unset; otherwise 1024
embedding_versionMESA_EMBEDDING_VERSION'v1'
embedding_model_revisionMESA_EMBEDDING_MODEL_REVISIONNone
embedding_normalizedMESA_EMBEDDING_NORMALIZEDTrue
context_window_limitCONTEXT_WINDOW_LIMIT8000
lancedb_memory_limit_bytesLANCEDB_MEMORY_LIMIT_BYTES1073741824
ram_allocation_fractionRAM_ALLOCATION_FRACTION0.18
consolidation_batch_sizeCONSOLIDATION_BATCH_SIZE20
consolidation_idle_timeoutCONSOLIDATION_IDLE_TIMEOUT10
histogram_max_sizeHISTOGRAM_MAX_SIZE10000
metrics_admission_thresholdMETRICS_ADMISSION_THRESHOLD0.8
metrics_divergence_thresholdMETRICS_DIVERGENCE_THRESHOLD0.5
rrf_kMESA_RRF_K60
rrf_vector_weightMESA_RRF_VECTOR_WEIGHT8.0
rrf_bm25_weightMESA_RRF_BM25_WEIGHT1.0
rrf_assertion_weightMESA_RRF_ASSERTION_WEIGHT1.0
rrf_graph_weightMESA_RRF_GRAPH_WEIGHT1.0
search_scope_cacheMESA_SEARCH_SCOPE_CACHETrue
chunkingMESA_CHUNKING'auto'
rerank_enabledMESA_RERANK_ENABLEDFalse
rerank_modelMESA_RERANK_MODEL'BAAI/bge-reranker-v2-m3'
rerank_depthMESA_RERANK_DEPTH50
t_routeMESA_T_ROUTE0.85
v4_rebuild_enabledMESA_V4_REBUILD_ENABLEDFalse
v4_graph_timeout_secondsMESA_V4_GRAPH_TIMEOUT_SECONDS15.0
crossencoder_pool_multiplierMESA_CROSSENCODER_POOL_MULTIPLIER3
legal_domain_modeMESA_LEGAL_DOMAIN_MODEFalse
extraction_langMESA_EXTRACTION_LANG'tr'
zero_cost_modeMESA_ZERO_COST_MODEFalse
ollama_urlMESA_OLLAMA_URL'http://localhost:11434'
ollama_timeout_secondsMESA_OLLAMA_TIMEOUT_SECONDS300.0
ollama_num_ctxMESA_OLLAMA_NUM_CTX8192
retry_max_attemptsMESA_RETRY_MAX_ATTEMPTS5
retry_min_wait_secMESA_RETRY_MIN_WAIT_SEC2
retry_max_wait_secMESA_RETRY_MAX_WAIT_SEC60
circuit_breaker_thresholdMESA_CIRCUIT_BREAKER_THRESHOLD10
circuit_breaker_cooldown_secMESA_CIRCUIT_BREAKER_COOLDOWN60.0
storage_pathMESA_STORAGE_PATHderived from cwd; runtime requires explicit storage root
human_review_queue_pathMESA_HUMAN_REVIEW_QUEUE_PATH'' (server puts this file under MESA_STORAGE_ROOT; variable applies only outside the server)
dead_letter_queue_pathMESA_DEAD_LETTER_QUEUE_PATH'' (server puts this file under MESA_STORAGE_ROOT; variable applies only outside the server)
queue_max_pending_recordsMESA_QUEUE_MAX_PENDING_RECORDS50000
queue_max_pending_bytesMESA_QUEUE_MAX_PENDING_BYTES2147483648
queue_max_pending_records_per_tenantMESA_QUEUE_MAX_PENDING_RECORDS_PER_TENANT50000
queue_max_pending_bytes_per_tenantMESA_QUEUE_MAX_PENDING_BYTES_PER_TENANT2147483648
queue_max_in_flight_recordsMESA_QUEUE_MAX_IN_FLIGHT_RECORDS32
queue_max_in_flight_records_per_tenantMESA_QUEUE_MAX_IN_FLIGHT_RECORDS_PER_TENANT8
queue_max_retry_pending_recordsMESA_QUEUE_MAX_RETRY_PENDING_RECORDS10000
queue_max_retry_pending_records_per_tenantMESA_QUEUE_MAX_RETRY_PENDING_RECORDS_PER_TENANT10000
queue_max_single_record_bytesMESA_QUEUE_MAX_SINGLE_RECORD_BYTES8388608
queue_retry_after_secondsMESA_QUEUE_RETRY_AFTER_SECONDS5
readiness_projection_backlog_maxMESA_READINESS_PROJECTION_BACKLOG_MAX1000
readiness_projection_dead_letter_maxMESA_READINESS_PROJECTION_DEAD_LETTER_MAX0
readiness_projection_stuck_maxMESA_READINESS_PROJECTION_STUCK_MAX0
readiness_cleanup_backlog_maxMESA_READINESS_CLEANUP_BACKLOG_MAX1000
readiness_cleanup_blocked_maxMESA_READINESS_CLEANUP_BLOCKED_MAX0
readiness_orphan_registry_maxMESA_READINESS_ORPHAN_REGISTRY_MAX0

MCP and operator variables#

mesa_mcp/configuration.py owns separate MCPSettings; see MCP.

MCP stdio uses V4; direct V4 requires explicit tenant,

workspace and dataset settings plus workspace root and binding authorization.

MCP general context defaults to 2500 tokens/max8000; Core HTTP context defaults

to 2048; Codex binding profile caps are separate (8 memories/2500 tokens).

MESA_GATEWAY_ENCRYPTION_KEY and MESA_GATEWAY_CONTROL_DB are operator inputs.

Rebuild uses reviewed trusted/storage/work roots and full-root offline scope;

see runbook. Defaults and example pairings do not certify

provider availability or quality.

Canonical V4 insertion requires the combined processing consumer. A combined

runtime without models stores documents and finds them with BM25; vector search

starts when embedding is enabled (degraded_sources shows vector until then);

503 canonical_processing_unavailable happens only on a non-combined profile.