MESA Core · v0.9.3

Yapılandırma

v0.9.3 kaynak: docs/configuration.md

Bu rehberin Türkçe ve İngilizce sürümleri aynı konuyu açıklar. Bu sayfayla ilgili kaynak bölümleri en altta yer alır.

Yerel varsayılanlar ve operatör ayarları#

mesa start, ~/.mesa/data, yerel katalog ve ~/.mesa/credentials.json dosyasını hazırlar; modeller ve dış sağlayıcılar varsayılan olarak kapalıdır. Doğrudan çalışma zamanı başlatıcıları hâlâ açık MESA_STORAGE_ROOT, MESA_RUNTIME_PROFILE=combined, anahtar ve yetki ayarları ister. Mesa() önce açık parametreleri, ardından bağlantı ortam değişkenlerini ve yerel kimlik bilgilerini okur.

İsteğe bağlı modeller, çizge ve doğrulama#

MESA_LLM_MODEL=provider:model ve MESA_EMBEDDING_MODEL=provider:model kullanın. Örneğin:

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

Yerel ayarları ~/.mesa/.env dosyasına koyup sunucuyu yeniden başlatın. Seçilen sağlayıcı kurulu ve çalışır olmalıdır. MESA_EMBEDDING_ENABLED, model bayrağını izler. Modeller açık olsa da varsayılan MESA_EXTRACTION_ENABLED=false değeridir; açık uçlu SPO çıkarımı için açıkça true yapın. İkisi kapalıyken de veri alımı ve BM25 araması çalışır; VECTOR adımları SKIPPED olur. MESA_GRAPH_ENABLED=false, Kùzu’nun açılmasını önler, GRAPH adımlarını SKIPPED yapar ve çizgeyi kullanılamayan kaynaklar arasında bildirir. Adım yeniden açılırsa combined başlangıcında eksikler tamamlanır.

MESA_TIER3_MODE: 0 kurala dayalı kontroller, 1 tek doğrulayıcı, 2 farklı A/B doğrulayıcıları. MESA_RRF_K=60, vektör ağırlığı 8.0 ve BM25/bilgi kaydı/çizge ağırlıkları 1.0 birleştirmeyi yönetir. MESA_RRF_VECTOR_WEIGHT=1 önceki vektör ağırlığını getirir; sıfır ağırlık kanal katkısını kapatır. Kalıcı yeniden oluşturma varsayılan olarak kapalıdır.

Sağlayıcı ve depolama sınırları#

Yerel Ollama/OpenAI uyumlu uç noktalar MESA_EXTERNAL_PROVIDER_ENABLED=false ile çalışabilir; bulut sağlayıcıları true değerini ve anahtarlarını ister. Embedding kimliği model, sürüm, boyut ve normalizasyonu içerir. Etkin vektörler varken kimlik değişimi açık bir yeniden oluşturma gerektirir. Aşağıdaki sabitlenmiş tam ayar tablosuna bakın; yapılandırılmış olmak çalışır olmakla aynı değildir.

Madde sınırlarını koruyan parçalama ve yeniden deneme#

MESA_CHUNKING=auto|plain varsayılan olarak auto kullanır. Satır başında en az üç Türkçe madde başlığı varsa madde sınırları korunur; uzun parçalar en fazla 512 token olur ve kaynak metin aynen saklanır. plain, yeni sürümlerde önceki planı kullanır. Mevcut ACTIVE sürümler değişmez. Yeniden deneme, sunucu yeniden başlatılsa veya ayar değişse bile kabul edilmiş metne uyan planı korur. Kabul edilmiş önek iki farklı plana da uyuyorsa yeni parça eklenmeden HTTP 409 döner.

İsteğe bağlı BGE yeniden sıralama#

Varsayılan MESA_RERANK_ENABLED=false değeridir. Açmak için [ml] eki gerekir. MESA_RERANK_MODEL=BAAI/bge-reranker-v2-m3 ve MESA_RERANK_DEPTH=50 (1–50 aralığı) aşamayı yapılandırır. Model ilk kullanımda yüklenir; ilk sorguya yükleme gecikmesi eklenir. Birleştirmeden sonra izinli adayların tam parça metinleri, ortak arama bağlantısı dışında bir worker thread’de puanlanır. Sonuçlara rerank_score eklenir; rrf_score ve final_score birleştirme değerleri olarak kalır. Eşit puanlarda birleştirme sırası korunur. DEV kanıtı ve donanım gecikmelerine bakın.

Türk hukuk kuralları ve açık SPO çıkarımı#

MESA_LEGAL_RULES_ENABLED=true, modellerden bağımsızdır. Otomatik planlarda normal maddeler, metadata.law_number veya ilk 3.000 karakterdeki desteklenen başlıktan kanun numarası alır; devam parçaları madde kimliğini korur. Önsözler, GEÇİCİ/EK maddeler ve plain planları otomatik kimlik almaz. Türlü kimlik API’si 3–5 basamaklı kanun numaralarını kabul eder; tutarsız numara/kod çiftleri ve bilinmeyen adlar reddedilir.

Yeni parçalar sürümlü hukuki öğeleri SPO kayıtlarından ayrı saklar. false; yeni kimlik/öğeleri, hukuki atıf/sıralama/tam eşleşme ve çizge atıf ayrıştırmasını kapatır, kalıcı verileri silmeden sonuç kopyalarındaki hukuki ekleri gizler. Genel sözcük/vektör/çizge araması çalışır. Model tabanlı SPO kayıtları için MESA_EXTRACTION_ENABLED=true değerini açıkça ayarlayın; yalnızca modeli açmak artık çıkarımı açmaz.

v0.9.3 embedding kimliği ve başlangıç#

Varsayılan MESA_EMBEDDING_MODEL=local:BAAI/bge-m3, MESA_EMBEDDING_DIMENSION=1024 ve normalizasyon açıktır. Modeller varsayılan kapalı kalır. Yerel modeli açmadan önce indirin. Önceki varsayılanla oluşturulmuş eski depoda aşağıdaki iki ayarı birlikte koruyun veya kimliği değiştirmeden önce yeniden oluşturun:

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

Başlangıç, etkin consolidation döngüsü olmadan MESA_TIER3_MODE=1/2 ayarını reddeder; çıkarım açık olmalıdır. . içeren başlangıç MESA_API_KEY değerleri de başlangıçta reddedilir.

Kendi sayfasına taşınan bölümler
Kaynak belgedeki ilgili bölümler

Bu bölüm, kaynak belgenin bu sayfayla ilgili kısımlarını değiştirmeden gösterir. Kaynak içindeki bir bölüme giden bağlantıyı açtığınızda metin otomatik olarak görünür.

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.