MESA Core · v0.9.3
Configuration
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:
MESA_MODEL_ENABLED=true
MESA_LLM_MODEL=ollama:qwen2.5:7b
MESA_EMBEDDING_MODEL=ollama:bge-m3Put 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.
Turkish legal rules and explicit SPO extraction#
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:
MESA_EMBEDDING_MODEL=local:magibu/embeddingmagibu-200m
MESA_EMBEDDING_DIMENSION=768Startup 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.
- Providers and capacity → Embedding & model providers
- Minimal V4 provider setup → Embedding & model providers
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 field | Environment name | Declared default |
|---|---|---|
llm_provider | LLM_PROVIDER | 'claude' |
llm_model | MESA_LLM_MODEL | '' |
llm_base_url | MESA_LLM_BASE_URL | None |
llm_api_key | MESA_LLM_API_KEY | None |
llm_timeout_seconds | MESA_LLM_TIMEOUT_SECONDS | 60.0 |
embedding_base_url | MESA_EMBEDDING_BASE_URL | None |
embedding_api_key | MESA_EMBEDDING_API_KEY | None |
extraction_thinking | MESA_EXTRACTION_THINKING | False |
extraction_max_tokens | MESA_EXTRACTION_MAX_TOKENS | 4096 |
llm_embedding_model_name | LLM_EMBEDDING_MODEL | 'sentence-transformers/all-MiniLM-L6-v2' |
embedding_model | MESA_EMBEDDING_MODEL | 'local:BAAI/bge-m3' |
model_enabled | MESA_MODEL_ENABLED | False |
tier3_mode | MESA_TIER3_MODE | None |
tier3_llm_provider_a | MESA_TIER3_LLM_PROVIDER_A | None |
tier3_llm_model_name_a | MESA_TIER3_LLM_MODEL_A | None |
tier3_llm_provider_b | MESA_TIER3_LLM_PROVIDER_B | None |
tier3_llm_model_name_b | MESA_TIER3_LLM_MODEL_B | None |
external_provider_enabled | MESA_EXTERNAL_PROVIDER_ENABLED | False |
embedding_dimension | MESA_EMBEDDING_DIMENSION | detected at startup when enabled and unset; otherwise 1024 |
embedding_version | MESA_EMBEDDING_VERSION | 'v1' |
embedding_model_revision | MESA_EMBEDDING_MODEL_REVISION | None |
embedding_normalized | MESA_EMBEDDING_NORMALIZED | True |
context_window_limit | CONTEXT_WINDOW_LIMIT | 8000 |
lancedb_memory_limit_bytes | LANCEDB_MEMORY_LIMIT_BYTES | 1073741824 |
ram_allocation_fraction | RAM_ALLOCATION_FRACTION | 0.18 |
consolidation_batch_size | CONSOLIDATION_BATCH_SIZE | 20 |
consolidation_idle_timeout | CONSOLIDATION_IDLE_TIMEOUT | 10 |
histogram_max_size | HISTOGRAM_MAX_SIZE | 10000 |
metrics_admission_threshold | METRICS_ADMISSION_THRESHOLD | 0.8 |
metrics_divergence_threshold | METRICS_DIVERGENCE_THRESHOLD | 0.5 |
rrf_k | MESA_RRF_K | 60 |
rrf_vector_weight | MESA_RRF_VECTOR_WEIGHT | 8.0 |
rrf_bm25_weight | MESA_RRF_BM25_WEIGHT | 1.0 |
rrf_assertion_weight | MESA_RRF_ASSERTION_WEIGHT | 1.0 |
rrf_graph_weight | MESA_RRF_GRAPH_WEIGHT | 1.0 |
search_scope_cache | MESA_SEARCH_SCOPE_CACHE | True |
chunking | MESA_CHUNKING | 'auto' |
rerank_enabled | MESA_RERANK_ENABLED | False |
rerank_model | MESA_RERANK_MODEL | 'BAAI/bge-reranker-v2-m3' |
rerank_depth | MESA_RERANK_DEPTH | 50 |
t_route | MESA_T_ROUTE | 0.85 |
v4_rebuild_enabled | MESA_V4_REBUILD_ENABLED | False |
v4_graph_timeout_seconds | MESA_V4_GRAPH_TIMEOUT_SECONDS | 15.0 |
crossencoder_pool_multiplier | MESA_CROSSENCODER_POOL_MULTIPLIER | 3 |
legal_domain_mode | MESA_LEGAL_DOMAIN_MODE | False |
extraction_lang | MESA_EXTRACTION_LANG | 'tr' |
zero_cost_mode | MESA_ZERO_COST_MODE | False |
ollama_url | MESA_OLLAMA_URL | 'http://localhost:11434' |
ollama_timeout_seconds | MESA_OLLAMA_TIMEOUT_SECONDS | 300.0 |
ollama_num_ctx | MESA_OLLAMA_NUM_CTX | 8192 |
retry_max_attempts | MESA_RETRY_MAX_ATTEMPTS | 5 |
retry_min_wait_sec | MESA_RETRY_MIN_WAIT_SEC | 2 |
retry_max_wait_sec | MESA_RETRY_MAX_WAIT_SEC | 60 |
circuit_breaker_threshold | MESA_CIRCUIT_BREAKER_THRESHOLD | 10 |
circuit_breaker_cooldown_sec | MESA_CIRCUIT_BREAKER_COOLDOWN | 60.0 |
storage_path | MESA_STORAGE_PATH | derived from cwd; runtime requires explicit storage root |
human_review_queue_path | MESA_HUMAN_REVIEW_QUEUE_PATH | '' (server puts this file under MESA_STORAGE_ROOT; variable applies only outside the server) |
dead_letter_queue_path | MESA_DEAD_LETTER_QUEUE_PATH | '' (server puts this file under MESA_STORAGE_ROOT; variable applies only outside the server) |
queue_max_pending_records | MESA_QUEUE_MAX_PENDING_RECORDS | 50000 |
queue_max_pending_bytes | MESA_QUEUE_MAX_PENDING_BYTES | 2147483648 |
queue_max_pending_records_per_tenant | MESA_QUEUE_MAX_PENDING_RECORDS_PER_TENANT | 50000 |
queue_max_pending_bytes_per_tenant | MESA_QUEUE_MAX_PENDING_BYTES_PER_TENANT | 2147483648 |
queue_max_in_flight_records | MESA_QUEUE_MAX_IN_FLIGHT_RECORDS | 32 |
queue_max_in_flight_records_per_tenant | MESA_QUEUE_MAX_IN_FLIGHT_RECORDS_PER_TENANT | 8 |
queue_max_retry_pending_records | MESA_QUEUE_MAX_RETRY_PENDING_RECORDS | 10000 |
queue_max_retry_pending_records_per_tenant | MESA_QUEUE_MAX_RETRY_PENDING_RECORDS_PER_TENANT | 10000 |
queue_max_single_record_bytes | MESA_QUEUE_MAX_SINGLE_RECORD_BYTES | 8388608 |
queue_retry_after_seconds | MESA_QUEUE_RETRY_AFTER_SECONDS | 5 |
readiness_projection_backlog_max | MESA_READINESS_PROJECTION_BACKLOG_MAX | 1000 |
readiness_projection_dead_letter_max | MESA_READINESS_PROJECTION_DEAD_LETTER_MAX | 0 |
readiness_projection_stuck_max | MESA_READINESS_PROJECTION_STUCK_MAX | 0 |
readiness_cleanup_backlog_max | MESA_READINESS_CLEANUP_BACKLOG_MAX | 1000 |
readiness_cleanup_blocked_max | MESA_READINESS_CLEANUP_BLOCKED_MAX | 0 |
readiness_orphan_registry_max | MESA_READINESS_ORPHAN_REGISTRY_MAX | 0 |
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.
