MESA Core · v0.9.3
Yapılandırma
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:
MESA_MODEL_ENABLED=true
MESA_LLM_MODEL=ollama:qwen2.5:7b
MESA_EMBEDDING_MODEL=ollama:bge-m3Yerel 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:
MESA_EMBEDDING_MODEL=local:magibu/embeddingmagibu-200m
MESA_EMBEDDING_DIMENSION=768Baş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.
- Providers and capacity → Embedding ve model sağlayıcıları
- Minimal V4 provider setup → Embedding ve model sağlayıcıları
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 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.
