MESA Core · v0.9.3
v0.9.3 sürüm notları
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.
v0.9.3 · 16 Kasım 2026#
Etiketli changelog sürümü 16 Kasım olarak tarihler. GitHub v0.9.3 etiketi 531209bc45805b478264f6dfa8a9e40a94e345cb commit’ine işaret eder. PyPI 0.9.3 wheel ve sdist dosyalarının mevcut ve geri çekilmemiş olması 17 Kasım 2026’da doğrulandı. pip install --upgrade mesa-memory==0.9.3 ile yükseltin. Alfa / üretim NO-GO sürer.
v0.9.3 veri alımı ve ayrıştırıcı ölçümleri#
Toplu veri alımı, mevcut worker geçişinde SQL ve çizge izdüşümleri ile outbox tamamlamasını gruplar. Changelog, 4.999.000 baytlık belgenin tam hazır olmasını 718,27 saniyeden 245,20 saniyeye (2,93× hızlanma) indirir: 4.882 mutation’ın tamamı COMMITTED, SQL ve GRAPH COMPLETED, VECTOR SKIPPED; parçalar kayıpsız geri okunmuştur. Round 20 P13-01/P13-02b bu koşulları kaydeder (modeller kapalı, çizge açık). Opus Round 20 kontrolü, son denetlenen dbf113b kodunda aynı kalıcı geri okumayla ayrıca 239,35 saniye (3,00×) raporlar. Bunlar yerel geliştirme ölçümleridir; kapasite veya hizmet garantisi değildir.
Hukuk ayrıştırması, sonuç vermesi mümkün olmayan karar atfı taramalarını atlar ve kanun adı temizliğini bağlı bir madde bulunana kadar erteler. API sınırındaki TCK/1 girdisinde yerel thread CPU süresinin beş denemedeki en iyi değeri 129,861 ms’den 52,330 ms’ye (2,48×) düşmüştür; kayıtlı çıktılar ve metin aralıkları aynıdır. İzole 200 ms CI CPU kontrolü yeniden engelleyicidir; 2 saniyelik takılma koruması sürer.
v0.9.3 embedding varsayılanı ve eski depolar#
Compose model varsayılanı dahil yeni varsayılan local:BAAI/bge-m3, 1024 boyut ve normalizasyon açıktır. Modeller varsayılan kapalı kalır. Modeli açmadan önce indirin. Eski varsayılanla oluşturulmuş depolar aşağıdaki iki ayarı birlikte korumalı veya embedding kimliğini değiştirmeden önce yeniden oluşturulmalıdır:
MESA_EMBEDDING_MODEL=local:magibu/embeddingmagibu-200m
MESA_EMBEDDING_DIMENSION=768v0.9.3 düzeltmeleri ve yayın davranışı#
Türk hukuk karşılaştırmaları ve tarih aramaları büyük İ/I harflerini tutarlı işler; özgün metin, konumlar ve kural sürümleri korunur. Kapsamlı FTS sorguları tekilleştirilmiş ı → i çeşitlerini ekler; YARGITAY ve yargıtay, YARGITAY KARARI metnini bulur. Aşağıdaki ASCII sınırlaması sürer.
MCP oturum başlangıcı, yeni depoda eksik workspace/dataset kayıtlarını oluşturup bir kez yeniden dener; oluşturma başarısızsa özgün oturum başlangıcı hatası korunur. Mode 0 oturum sonlandırması, consolidation döngüsü olmadan ertelenen kayıtları tamamlar. Etkin consolidation döngüsü olmayan MESA_TIER3_MODE=1/2 ayarı (çıkarım açık olmalıdır) ve . içeren başlangıç MESA_API_KEY sırları, başlangıçta açık hatayla reddedilir.
Etiketle tetiklenen PyPI yayınları artık derleme ve yayımlamadan önce tam yeniden kullanılabilir CI iş akışını bekler. Changelog bu bağlantının doğrulanmasını ilk canlı etiket çalışmasına bırakır; bu yenilemede o çalışma denetlenmedi.
v0.9.3 bilinen sorunlar ve ölçüm kapsamı#
/v4/* ve /control/* için dakikalık ve günlük hız sınırları uygulanmaz. ASCII yargitay, Yargıtay ile hâlâ eşleşmez; indeks tarafında Türkçe normalizasyon ertelenmiştir. Kùzu 0.11.3, çizge sayfalarının sonuna başlatılmamış bellek yazabilir: mantıksal çizge sorgularında hafıza metninin özellik olarak saklanmadığı doğrulansa da ham çizge dosyaları sürecin işlediği metin parçalarını içerebilir. Çizge dizinini SQLite gibi hassas kabul edin. Güncel sınırlara bakın.
0.9.3 için yeni erişim benchmark’ı çalıştırılmadı. Round 18 sonuçları 0.9.2 olarak kalır; aşağıdaki tarihsel demolar ve DEV ölçümleri kendi sürümlerini korur. Önceki 11,6 saniyelik arama ölçümü tarihsel 0.9.2 kanıtıdır; 0.9.3 bilinen sorunlar bölümünde listelenmez ve burada yeniden ölçülmedi.
v0.9.2 · 6 Kasım 2026#
Resmî yayın, 8cd2cfe1df5356e73b3bef83ae640850fd54c798 commit’ine sabittir. PyPI 0.9.2 wheel ve sdist yayını, geri çekilmemiş olması ve yayınla eşleşen SHA256 özetleri 7 Kasım 2026’da doğrulandı. Python >=3.11 gerekir; pip install --upgrade mesa-memory==0.9.2 ile yükseltin. V4 HTTP yolları uyumludur. Alfa / üretim NO-GO sürer.
Hukuki çıkarım ve arama#
Yeni parçalar; citation, decision_ref, date, amount, duration ve outcome türlerinde sürümlü kural öğeleri saklar. retrieval_provenance.legal_items, özgün parçaya göre konumlarla {version, items} döndürür. Bunlar modelin çıkardığı özne–yüklem–nesne (SPO) kayıtlarından ayrıdır ve birleştirme skoruna eklenmez. Purge bu öğelerin kaynak alıntılarını da siler.
İzinli başlıklar ve ilk parça kanun başlıkları, K. kısaltması dâhil kapsam önbellekli kanun adları öğretir. Tam kanun/madde veya kararın kendi esas/karar numarası eşleşmesi, belge sırasıyla en fazla üç sonucu başa alabilir. Karar kimliği, sıfırıncı parçanın ilk 300 karakterinde başlayan referansı gerektirir; sonraki alıntılar kimlik sayılmaz. Diğer sonuçlar birleşik veya yeniden sıralanmış düzenini korur. Yalnızca AYM/mahkeme adı geçmesi artık Anayasa sıralamasını tetiklemez.
Değişen varsayılanlar ve kabul#
MESA_LEGAL_RULES_ENABLED=true; kimlikleri, anlık görüntüleri ve hukuki aramayı açar. false; yeni otomatik hukuki kimlik/öğeleri, atıf çözümlemeyi, tam eşleşme önceliğini, hukuk katsayılarını ve çizge atıf ayrıştırmasını kapatır; kalıcı kimlikleri/anlık görüntüleri silmeden sonuç kopyalarındaki hukuki ekleri gizler. Genel arama çalışır. MESA_EXTRACTION_ENABLED=false, artık MESA_MODEL_ENABLED değerinden bağımsızdır; açık true SPO çıkarımını açar. Embedding varsayılanı model bayrağını izlemeyi sürdürür.
Belge kabulü, tam parçalama planını yeniden üretmeden kuyruk kapasitesini kısa süre bekler. add_document(deadline=600), HTTP isteğinde kalan belge süresini kullanır. Süren kuyruk baskısı yine 503 queue_over_capacity döndürebilir; aynı gövdeyi yeniden gönderin. HTTP 202 hazır olma değil, kabul anlamındadır.
Güvenlik ve ölçülen sınırlar#
Sınırlı ayrıştırma, worker thread ve işbirlikli çalışma; ölçülen kural çıkarımı, atıf, kapsam ve yoğun puanlama örneklerinde /health yanıt verebilirliğini düzeltir. 0.9.1’i de etkileyen istek yolu duraklamaları için yükseltme önerilir. Bu, yoğun sorguların hızlandığını kanıtlamaz: 1.000 adaylı arama yaklaşık 11,6 saniye sürmüştür. Modeller kapalı, çizge açıkken 4.999.000 baytlık belge yaklaşık yedi dakikada hazır olmuştur. Bunlar belirli geliştirme ölçümleridir; hizmet garantisi değildir.
Tam belge gizli bilgi taraması ve uç Unicode normalizasyonu saniye altı duraklamalar yaratabilir. UUID eşitlikleri ayrı doldurulmuş depolarda sıralamayı değiştirebilir; aynı depodaki korunan girdiler deterministiktir. Nesne olmayan belge isteklerinde INFO düzeyli 422 ayrıntı metni farklılığı sürer; durum, kod, konum ve OpenAPI uyumludur. Resmî yayın ayrıca Python 3.13 birleşim sonrası ayrıştırıcı testinin CI’da 200 ms sınırını aştığını kaydeder; hız düzeltmesi bu sürümün dışında, 0.9.3 için planlanmıştır.
Yayın doğrulaması ve kanıt#
Resmî yayın; 2.037 yerel test ve ayrı 10 MCP testi, PR kapsam işlerinin her birinde 2.032 geçen test raporlar (3.11: %88,09; 3.13: %88,07). PR #143, derleme kanıtı, SBOM ve köken raporları yayın sayfasındadır. Bunlar yayına atfedilen sonuçlardır; web sitesi çalışmasında yeniden yürütülmüş Core sertifikasyonu değildir. Bağımsız QA, Law ve E2E kanıtları kendi tarih ve kaynaklarına bağlı kalır. Tarihsel v0.9.0 demo kayıtları ve aşağıdaki v0.9.1 DEV ölçümleri tarihsel kalır.
Önceki sürüm v0.9.1 · 1 Kasım 2026#
GitHub sürümü, e2f984d4ad97c01782a347e29e44808e5a16dad3 commit’iyle yayımlandı. PyPI 0.9.1 paketi de yayımlandı ve doğrulandı; kurulum rehberini izleyin. Python >=3.11 gerekir. Alfa / üretim NO-GO sürer.
Neler değişti#
Round 13 dört kapsamlık önbellek, veri alımı indeksleri, event loop dışında scrypt ve CLI etkinleşme beklemesi ekler. Round 14 MESA_CHUNKING=auto|plain, ilk kullanımda yüklenen isteğe bağlı BGE yeniden sıralama, 8.0 vektör ağırlığı, erken terminal parça hatası ve kaynakla silme getirir. OpenAI/Ollama SDK’ları temel pakete taşınır. Diğer RRF ağırlıkları 1.0, k=60 kalır; sıfır ağırlık kanal katkısını kapatır. Mevcut ACTIVE sürümler ve V4 yol/istek sözleşmeleri uyumludur.
CLI varsayılan olarak ACTIVE bekler; --no-wait kabulden sonra döner. Etiketli Mesa.add SDK imzasında varsayılan hâlâ wait=False değeridir; beklemek için wait=True verin. RETRY_PENDING terminal değildir. CLI, SDK, yapılandırma ve yükseltme rehberlerine bakın.
Round 14 DEV kanıtı#
1 Kasım 2026 ölçümü: sabitlenmiş Türkçe Tier M korpusu, 141 belge, 5.041 parça; 101 DEV sorusu (85 yanıtlanabilir, 16 yanıtsız). Madde sınırlarını koruyan parçalama açık, bilgi çıkarımı kapalı, embedding ve çizge açık. Test bölümüne erişilmedi. Pasaj hit@5 ve MRR 85 yanıtlanabilir soruda; gecikme 101 sorunun tamamında ölçüldü. Arama limiti ve yeniden sıralama derinliği 50, reranker max_length 1024. Diğer kanal ağırlıkları 1.
| Vektör ağırlığı | Yeniden sıralama | Pasaj hit@5 | Pasaj MRR | Arama p50 (s) | Arama p95 (s) |
|---|---|---|---|---|---|
| 1 | Kapalı | 0.5176 | 0.3953 | 1.2693 | 2.0035 |
| 1 | Açık | 0.7412 | 0.6816 | 1.9548 | 2.5736 |
| 2 | Kapalı | 0.5765 | 0.4565 | 1.2708 | 1.9640 |
| 2 | Açık | 0.7529 | 0.7055 | 1.9569 | 2.6364 |
| 4 | Kapalı | 0.6588 | 0.5152 | 1.2836 | 1.9469 |
| 4 | Açık | 0.7765 | 0.7069 | 1.9279 | 2.6100 |
| 8 | Kapalı | 0.6706 | 0.5663 | 1.2849 | 1.9115 |
| 8 | Açık | 0.7647 | 0.6973 | 1.9161 | 2.5360 |
Yeniden sıralama varsayılan olarak kapalı olduğu için seçim reranker kapalı MRR’ye dayanır: ağırlık 8, yuvarlanmamış MRR’yi 0.171008 artırarak 0.02 koşulunu aşar. Bu taramada yeniden sıralama açıkken en yüksek MRR ağırlık 4’tedir. Sonuçlar bu korpusa özel geliştirme ölçümleridir; test bölümü kanıtı veya üretim sertifikasyonu değildir.
Ayrı CPU/GPU donanım ölçümü#
Bu ayrı ölçümde vektör ağırlığı 1’dir; yukarıdaki ağırlık 8 satırıyla birleştirilmemelidir.
| Donanım / yeniden sıralama | Pasaj hit@5 | Pasaj MRR | Arama p50 (s) | Arama p95 (s) |
|---|---|---|---|---|
| GPU / Kapalı | 0.5176 | 0.3953 | 1.2531 | 1.9953 |
| GPU / Açık | 0.7412 | 0.6816 | 1.9627 | 2.6029 |
| CPU / Açık | 0.7412 | 0.6816 | 26.9158 | 33.8756 |
Embedding: BAAI/bge-m3, 1024 boyut, normalize. Reranker: BAAI/bge-reranker-v2-m3. Donanım: Colab A100-SXM4 40GB ve Intel Xeon 2.20GHz, sekiz CPU thread’i. CPU satırında iki model de nicemleme olmadan CPU’ya taşınır. Modeller çalışma zamanı başlamadan edinildi. Python 3.13.16, Torch 2.11.0+cu130, sentence-transformers 5.7.0, transformers 5.21.0, NumPy 2.5.4, LanceDB 0.41.0, Kùzu 0.11.3 kullanıldı; bunlar Colab’da kurulu paketlerdir, ML lockfile sürümlerinin birebir aynısı değildir.
İstekler yetkilendirilmiş HTTP yolundan ASGI ile, TCP olmadan geçer. Ölçümler sıralı çalışır, veri dizinini/önbelleği yeniden kullanır ve her ölçümde ilk ısınma sorgusu dışarıda bırakılır. Gecikme embedding, kapsamlı arama ve isteğe bağlı yeniden sıralamayı içerir. Kontrollü donanım hızlanma iddiası değildir. Arama kilidi değişikliğinden sonra aynı veri dizini kullanılmış, 101 DEV sorusunun ilk 50 sonuç sözlüğü değişmemiştir.
Round 13 yerel DAO kontrolü#
Sentetik yerel kapsam önbelleği mikroölçümü: 3.500 parça, 20 sorgu; DAO p50 100.813 → 20.142 ms, p95 155.789 → 46.862 ms. HTTP, kimlik doğrulama ve model süresini içermez; tüm sistemin beş kat hızlandığını göstermez. Veri alımı indeks süreleri yalnız bookkeeping işlemlerini ölçer.
Kaynaklar ve korunan örnek#
Ana sayfa demosu ve hızlı başlangıç alındıları Core v0.9.0 kayıtları olarak etiketli kalır. OpenAPI snapshot’ı v0.9.1’den yenilendi; mevcut V4 yol/istek sözleşmeleri uyumludur. Model revision’ları, özetler, ısınma ve yuvarlanmamış ölçümler için sabit arama benchmark’ı ile ölçüm verisine bakın. Üretim NO-GO sürer.
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.
All notable changes to the MESA project will be documented in this file.
Entries describe the named release. Old performance and architecture claims
are historical; consult the current guides for present behavior.
The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.
[0.9.3] - 2026-11-16#
Fixed#
- MCP session creation now provisions the workspace and dataset when a fresh
store reports them missing, then retries once. If catalog creation fails,
callers receive the original session-start error rather than the create error.
- Ending a session in default Mode 0 now processes deferred records without a
consolidation loop, allowing finalization to complete.
- Turkish legal rule comparisons and date lookups handle uppercase İ/I
consistently with lowercase text. Original text, offsets and rule versions
are preserved.
- Scoped FTS queries include deduplicated
ı→ivariants, soYARGITAY
and yargıtay find text written YARGITAY KARARI.
- Context requests reject timestamps without timezone offsets with HTTP 422
before comparing ranges. Fact validation treats date-only values as UTC
when comparing them with timezone-aware timestamps, preventing datetime errors.
- Gateway circuit breakers release half-open probes after permanent errors or
cancellation. Non-retryable bridge writes enter a terminal failed state
instead of being sent again on every drain.
- Projection rebuild smoke checks use the same assertion text, including the
evidence span, as vector replay.
- Duplicate or stale projection completion calls preserve committed artifacts;
artifact compensation remains restricted to fenced mutations.
- SDK quickstart examples wait for ingestion before requesting context and close
document files. Documentation links and the architecture version are corrected,
and embedding setup notes explain downloading the model before enabling it.
- Parser regression checks retain their 200 ms budget using thread CPU time,
with a 2 s hang guard. Claude adapter tests skip when the optional anthropic
package is absent.
- Legal rule extraction skips impossible decision-reference scans and delays
law-name cleanup until an attached article is found. On the API-limit
TCK/1 input, best-of-five local thread CPU fell from 129.861 ms to
52.330 ms (2.48x faster), with identical saved outputs and spans. The
isolated 200 ms CI CPU-budget check is blocking again; the full local
suite retains its 2 s hang guard.
Changed#
- Bulk ingestion batches SQL and graph projections and outbox completion in
the existing worker pass. The measured 4,999,000-byte document reached full
readiness in 245.20 s versus 718.27 s before (2.93x faster), with all 4,882
mutations COMMITTED, SQL and GRAPH COMPLETED, VECTOR SKIPPED, and lossless
chunk readback. Durability and fencing behavior are preserved.
- The default embedding model is now
local:BAAI/bge-m3, with 1024 dimensions
and normalization enabled, including the Compose model default. Models remain
off by default. Stores created with the old default must keep both
MESA_EMBEDDING_MODEL=local:magibu/embeddingmagibu-200m and
MESA_EMBEDDING_DIMENSION=768, or rebuild before switching embedding identity.
- Tag-triggered PyPI releases wait for the complete reusable CI workflow before
building and publishing. The first live tag run will verify this wiring.
- Startup fails with a clear error when
MESA_TIER3_MODE=1/2has no active
consolidation loop; extraction must be enabled for these modes.
- Bootstrap
MESA_API_KEYsecrets containing.are rejected at startup.
Placeholder API keys and principal IDs in .env.example are commented out.
- Antigravity bridge write spools are isolated per workspace. Entries in the old
shared spool are left in place and are not migrated automatically.
Known issues#
- Kuzu 0.11.3 can write uninitialized memory into graph page tails, so raw graph files may contain fragments of text the process handled; MESA never stores memory text in the graph (checked by query), and the graph directory should be treated as sensitive like the SQLite file.
- Per-minute and daily rate limits are not enforced for
/v4/*and/control/*
in this version; the API documentation now states this limitation.
- The ASCII query
yargitaystill does not match text writtenYargıtay;
index-side Turkish folding remains deferred.
[0.9.2] - 2026-11-06#
This release hardens the Turkish legal extraction and retrieval features from
Round 16 and Round 17. V4 HTTP routes remain compatible. Production qualification
remains NO-GO pending the normal certification and production-like release gates.
Added#
- Rule-based Turkish legal item extraction for newly admitted chunks, capturing
versioned legal rule items with chunk offsets (citation, decision_ref,
date, amount, duration, and outcome). Extracted items are returned in
search provenance under legal_items separately from SPO facts, without
affecting fusion scores. Document purge erases their source quotes.
- Store-learned law names: authorized document titles and law headers provide
scope-cached and indexed law names, including the K. abbreviation.
- Exact-match-first slot: queries matching a decision's own docket/decision reference
or exact law/article occupy at most three leading search positions in document order,
preserving remaining result order. Decision matching requires references beginning in
the first 300 characters of an authorized first chunk; later quotations do not count.
Changed#
MESA_LEGAL_RULES_ENABLEDdefaults totrue. When set tofalse, it disables
automatic legal identity assignment and item extraction during ingestion. During
search, it disables legal processing (citation resolution, exact-match slot,
decision künye promotion, legal ranking factors, and graph citation parsing) and
suppresses stored legal result overlays in returned copies while keeping durable
identities and snapshots intact.
- Open-ended SPO fact extraction (
MESA_EXTRACTION_ENABLED) defaults tofalse
regardless of MESA_MODEL_ENABLED; an explicit true still enables it.
- Constitutional Court names (
Anayasa Mahkemesi, its suffix forms andAYM)
no longer activate Constitution citation ranking; separate statute citations in
the same query are preserved.
- Large-document admission waits for queue room on
queue_over_capacitywithout
repeating full document chunk planning.
Security#
- Fixed synchronous CPU-bound request-path stalls that also affect 0.9.1: rule
extraction, citation resolution, scope building, and heavy token scoring now bound
caller-text work and yield thread execution, keeping /health responsive under
high load. Users of 0.9.1 are recommended to upgrade.
Known issues#
- Heavy 1,000-candidate search takes approximately 11.6 s;
/healthresponsiveness
is restored for measured repros, but heavy-query execution time is not proved faster.
- Older whole-document secret scanning and extreme Unicode normalization can still
cause sub-second request-path stalls.
- UUID ties can change ordering across separately ingested stores; same-store
retrieval remains deterministic for retained inputs.
- Large documents take minutes to become fully ready: a 5 MB document
(4,999,000 bytes) took about 7 minutes (7m00.6s) to become ready with models off
and graph on.
- Non-object document requests keep an INFO-level 422 detail wording difference;
HTTP status, error code, location, and OpenAPI schema remain unchanged.
[0.9.1] - 2026-11-01#
This release combines Round 13 (speed) and Round 14 (retrieval quality and
document workflow improvements), merged in PRs #137 and #140. V4 HTTP routes
remain compatible. Production qualification remains NO-GO pending the
normal certification and production-like release gates.
Added#
- Lossless Turkish article-aware chunking for new document revisions, controlled
by MESA_CHUNKING=auto|plain (default auto). Admitted chunk text pins retry
plans; ambiguous prefixes return HTTP 409 without appending chunks.
- Optional lazy BGE cross-encoder reranking after fusion and outside the search
connection. It is off by default; enable with MESA_RERANK_ENABLED=true and
the existing [ml] extra. Results add rerank_score while preserving fusion
scores. Default model: BAAI/bge-reranker-v2-m3; depth: 50.
- Source-based document deletion through
Mesa.delete(source=...)and
mesa delete --source <ref>; document-ID deletion remains available.
- Versioned, bounded search-scope caching of authorized rows and temporary
BM25 indexes, invalidated by SQLite commits. Configure it through
MESA_SEARCH_SCOPE_CACHE (default true).
- Tag-triggered PyPI trusted publishing through GitHub Actions and OIDC.
Changed#
- Set the runtime vector RRF weight to 8.0 from the frozen Tier M dev benchmark
(passage MRR 0.3953 → 0.5663 with reranking off); other lane weights remain 1.0.
The full weight/reranker matrix and model environment are recorded in the
- Index ingest ledger lookups and reconcile revision activation once per commit
transition, reducing bookkeeping growth while preserving activation rules.
- Run query embedding before the shared search connection, and scrypt API-key
verification, issuance and rotation in worker threads. Graph-disabled search
skips graph seed preparation.
- Include the OpenAI and Ollama SDKs in the base installation:
pip install mesa-memory. Anthropic remains in [adapters].
mesa addwaits for the revision to become active by default; use--no-wait
to return after admission. SDK waiting also polls mutation status.
- Accept zero RRF lane weights to disable a lane's contribution.
Fixed#
- Fail promptly on terminal chunk mutations with their ID, state and error
class instead of waiting for the document timeout; keep retryable states
pending. CLI errors remain readable and exit with status 1.
- Retry
queue_over_capacityduring document admission within the SDK deadline. - Preserve timestamped runtime log handlers across Alembic migrations.
- Record projection-attempt start times from the actual outbox claim time.
- Preserve the missing-ML installation message when an earlier server lifespan
left tasks associated with a closed event loop.
Upgrade notes#
- Existing active revisions keep their chunks. Use
MESA_CHUNKING=plainfor
new revisions requiring the earlier chunking plan, and
MESA_RRF_VECTOR_WEIGHT=1 to retain the earlier vector weighting.
- The ingestion optimization adds SQLite indexes through the normal migrations.
Continue to follow the documented backup and single-owner upgrade procedure.
- Benchmark results describe the frozen Turkish Tier M dev split and the
documented model/hardware setup; they are not general performance guarantees.
[0.9.0] - 2026-10-28#
Added#
- Local CLI with subcommands
start,add,search,delete,status, andmcp-configfor standalone single-user operation. - Python SDK
Mesaclient with zero-config local defaults reading~/.mesa/credentials.json. - Lossless document ingestion endpoint
POST /v4/documentswith deterministic chunking, duplicate detection, and revision tracking. - Configurable graph switch (
MESA_GRAPH_ENABLED=false) enabling lightweight operation without KùzuDB and skipping graph lanes. - Unified model provider configuration via
MESA_LLM_MODELandMESA_EMBEDDING_MODELusingprovider:modelsyntax. - Local Docker operation running
mesa startwith shared volume credentials.
Changed#
- Document purge completely erases stored source and assertion text for privacy compliance while keeping audit state and hashes.
Fixed#
- Retry backoff, dead-letter recovery and queue replay fixes preventing records from hanging indefinitely in
RETRY_PENDING. - Admission 503 transient startup window retry in SDK and clear actionable installation messages for missing extras (
[adapters],[ml]). - Turkish abbreviation and list numbering handling in document chunker to prevent splitting mid-citation.
[0.8.1] - 2026-10-18#
Publication status#
The repository owner authorized this v0.8.1 source release on 2026-10-18.
It includes the MVP hardening and developer-experience changes merged in PR #112.
Production qualification remains NO-GO pending the normal release gates;
real LLM/embedding integration and a production-like 24-hour soak are not certified.
No local GPG signing key is available, so the annotated release tag is unsigned.
Signed-tag preflight success is not claimed. CI, wheel/SBOM artifacts and OIDC
attestations are verified separately for the release commit and tag.
Removed#
- Removed the obsolete standalone raw-log agent-ID backfill script.
- Removed obsolete manual backup/restore, MCP spoofing, Mem0 smoke and async I/O
benchmark scripts from tests/; removed their stale collection exclusions.
- Removed the unused dashboard/showcase frontend, its npm dependencies and build
configuration, and the obsolete run_demo_rag.py launcher. MCP control APIs
and operator approval CLI remain available; see control API.
Fixed#
- Scoped BM25 corpus statistics, pre-rank audit queries and audit metadata to
authorized tenant/dataset scope; unrelated data no longer influences results.
- Protected projection completion with claim/fencing ownership checks; prevented
cross-dataset repair deletions and false invalidation when vector lookups fail.
- Kept Kùzu caches consistent after delete and transaction rollback, including
composite assertion IDs; graph commit failures retry and cancellations roll back.
- Surfaced vector backend and embedding failures explicitly; removed the legacy
raw-memory fallback to an unrelated eight-dimensional embedding.
- Rejected reserved
_mesa_metadata and non-finite RRF weights while preserving
explicit zero confidence. Mapped context, catalog chunk and rollback errors
to actionable API responses instead of generic server errors.
- Added optional
legal_identityparity to synchronous and asynchronous V4 SDK
insertion; slowed default status polling to fit the shared minute request budget.
- Returned field-specific validation errors without echoing rejected input or
internal route paths, and retained startup error logging after migrations.
- Corrected standalone runtime defaults and documented a minimal supported
Python install. Updated CI import checks, documentation contracts and SQLite
fault-injection test doubles.
make healthnow checks the running API's readiness and authenticated health
using MESA_BASE_URL and MESA_API_KEY, without opening local databases.
Unhealthy responses and connection/authentication failures return a nonzero exit.
Documentation#
- Clarified provider prerequisites, immutable embedding identity, asynchronous
projection status, source evidence, session finalization and client cleanup.
The V4 quickstart displays assertion/source references. Models-disabled startup
is described as a health check; V3 ingestion still requires embeddings.
- Verified small SQLite/LanceDB/Kùzu flows, restart, populated tenant isolation
and completed rollback with explicitly controlled model boundaries. These
checks do not establish real-model quality or production-size capacity.
- Consolidated 37 Markdown pages into 20 maintained guides and decision records;
merged overlapping guides, retired obsolete ADR files and repaired document
contracts and links. Release-specific exceptions remain in this changelog.
- Consolidated documentation ownership and navigation; replaced the root V3
whitepaper with a current architecture entry point.
- Removed obsolete Colab guidance, the retired architecture/audit/benchmark
documents and their archive indexes. Merged the external benchmark ownership
note into the ecosystem guide and repaired incoming documentation links.
- Removed duplicated setup/recovery guidance, corrected MCP authorization and
rebuild/migration wording, and clarified ADR applicability. These documentation
changes do not certify a new release; prior tracked records remain in Git history.
[0.8.0] - 2026-10-15#
Publication status and exceptions#
Release date: 2026-10-15. Package version: 0.8.0.
The repository owner explicitly approved publication after reviewing the missing
certification evidence. This source release does not certify production readiness.
Actual publication and artifact status are recorded in GitHub Releases and the
release audit; a version bump alone is not publication proof.
Verification and known limitations#
- The preceding documentation PR passed both MESA CI and external release gates;
the version/release commit is checked independently before tagging.
- Real model/provider boot/restart/token-cost evidence, a production-like 24-hour
soak and new official Profile B certification are not supplied by this release.
- Full per-method docstring certification and the pre-existing full-tree Black
formatting debt remain incomplete; required scoped CI checks are preserved.
- No local GPG signing key is available: the annotated v0.8.0 tag is unsigned.
Signed-tag preflight success is not claimed. Build/SBOM/OIDC provenance status
is verified separately and must not be inferred from publication alone.
- Production status remains NO-GO until the normal certification gates pass.
Changes#
The development history since v0.7.1 contains selectable validation, canonical
embedding identity, durable offline projection rebuild, immutable revision
activation/ownership recovery, four-lane scoped retrieval, graph runtime closure,
atomic evidence packing, bounded opt-in query planning and typed legal identity.
The current documentation refresh aligns entry points, API examples, provider
defaults, configuration, ecosystem boundaries and limitations; removes unsourced
showcase metrics/PASS output; and adds scoped neutral V3 and provider-required V4 examples.
Independent review corrected conservative offline tokenizer counting, low-level
vector versus canonical authorization, V3 router descriptions and smoke checks
under Python optimization. Dashboard build dependency lock patches address two
detected HIGH advisories; audit/build proof remains separate from production gates.
See CHANGELOG v0.8.0 for the detailed implementation
history, migration for forward schema/representation
requirements, and release policy for immutable signed tagging,
same-commit CI, provider, backup/rebuild and 24-hour soak requirements.
No new model accuracy, legal correctness, official Profile B PASS, native
MESA_Data delivery, production-size memory bound or 24-hour soak result is
claimed. The earlier audit referred to reports/v0.8.0-documentation-release/;
that evidence directory is not present in this checkout. Verify publication and
artifact results in the release's own records; this prose is not a substitute
for missing run output or a signed-tag verification.
Added#
- Documentation source-truth refresh: Added a navigable documentation index,
configuration/CLI references, ingestion/retrieval/security/migration guides,
source-generated OpenAPI and neutral scoped examples. Model-disabled V3 smoke
and provider-required V4 ingestion are explicitly distinguished. Publication
is owner-approved; production certification remains NO-GO.
- Typed legal retrieval identity: V4 ingestion can carry a validated,
provenance-bound law/article/version identity. Canonical assertions persist
the identity through fallback projection, and scoped indexed pre-rank lookup
can recover a bare article chunk without trusting reserved caller metadata.
- Bounded adaptive context retrieval: Added an explicit opt-in context mode
that runs the original V4 query first, makes at most one semantic
reformulation call for weak results, executes at most two additional searches
with the same authorized scope, and feeds one deduplicated candidate list to
the existing ContextBuilder budget pass. Single-query retrieval remains the
default for HTTP, sync/async SDK and MCP callers.
- Selectable validation policy: Added explicit deterministic-only,
single-LLM and dual-LLM consensus modes with truthful runtime capability
reporting and durable per-mutation policy snapshots.
- Durable projection rebuild: Added storage-root-scoped rebuild operations,
append-only operation events, fenced leases/checkpoints, projection generation
pointers and retained-generation rollback.
- Administrative rebuild API and SDK: Added ADMIN-only submit, status, cancel
and retry interfaces, the deprecated storage-root alias, synchronous and
asynchronous Python clients, and the offline mesa-v4-rebuild runner.
- Closure evidence and operations telemetry: Added content-free CI evidence,
rebuild progress/parity/rollback metrics, provider rehearsal contracts and an
operator runbook.
Changed#
- V4 jurisdiction propagation: Context HTTP, sync/async SDK and MCP context
and recall calls now preserve the requested jurisdiction through retrieval.
- Round-8 SQLite durability: Canonical production SQLite connections now
explicitly request synchronous=FULL. Weaker NORMAL/OFF synchronization
is accepted only in the explicit test-isolated runtime profile. Auxiliary
connections preserve their established journal mode.
- Round-8 backup authority: Backup now verifies that a supplied writer-lock
handle owns the real storage lock file. Manifests explicitly record SQLite as
canonical per-database snapshots and vector/graph stores as rebuildable
projections copied under the exclusive writer boundary.
- Round-7 lifecycle and hash truth: Late manifest finalization now reuses
the canonical revision activation barrier. Declared whole-revision,
manifest and chunk hashes remain separate; direct insertion records an
unknown revision hash as NULL, including for multiple revisions of one
document.
- Opaque catalog storage identity: New physical catalog keys are
server-generated and public resolution is external-ID-only. API, SDK and MCP
provenance/status surfaces translate catalog scope back to public IDs.
- Historical mutation administration: Closed sessions remain valid
historical evidence, but rollback/replay now bind the mutation to the exact
principal/session tenant, workspace, dataset and agent scope plus explicit
ROLLBACK permission.
- Round-3 aggregate lifecycle: Revision manifests freeze explicitly,
revision and pipeline terminal success is derived from all required child
work, and non-head historical rollback returns a typed conflict.
- Tenant-scoped catalog identity: Public catalog identifiers can be reused
safely across tenants while the durable schema retains distinct physical
keys.
- Temporal and runtime parity: HTTP, sync/async SDK and MCP now carry
valid_at, valid_from and valid_to; long-lived MCP/routing state is
bounded with safe expiration and concurrency.
- Release hygiene: The shipped full-cognitive image receives vulnerability
and SBOM gates, and the legacy server launcher delegates to the canonical
runtime composition.
- Round-2 lifecycle certification: Projection writes now retain durable
compensation ownership until vector/graph cleanup succeeds; V3 replacement
stages the successor until secondary writes are safe; repeated mutations for
one revision activate its head idempotently.
- Runtime and extraction truth: Terminal LLM fallback preserves zero-to-many
facts, local embedding identity names the actual provider, model-disabled
imports avoid eager ML loading, and supported compose profiles forward the
declared provider and Tier-3 settings.
- Tenant and transport contracts: Durable queue accounting uses the real
tenant across agents; MCP identities include immutable scope and only recover
exact inactive-session conflicts; API errors and readiness failures use the
canonical structured contract.
- Truthful V4 capability contract: Capability responses now distinguish
vector, lexical, relational, validity and graph projection support, advertise
rebuild limits, and expose durable rebuild only when
MESA_V4_REBUILD_ENABLED is enabled.
- Projection runtime ownership: API, worker and rebuild runtimes now acquire
the same storage-root writer lock and resolve LanceDB/Kùzu paths through the
active SQLite generation pointer.
- Embedding identity: Canonical mutations now persist embedding provider,
model, version and dimension so projection replay fails closed on any provider
mismatch. Legacy rows with externally verified provenance can be completed by
the explicit, writer-locked mesa-v4-rebuild adopt-provider command.
Security#
- Dashboard build dependency patches: Updated existing transitive
nanoid
and source-map-js lock entries within supported ranges to address detected
HIGH advisories, without changing root ranges or running install scripts.
- Truthful replay boundary: Semantic
REJECTEDmutations return
409 NON_REPLAYABLE and remain terminal, while target-aware technical
projection/cleanup retry preserves a truthful aggregate pipeline state.
- Runtime-owned validation assurance: Reserved
_mesa_*metadata can no
longer be supplied by API writers or used to downgrade a mutation's
operator-selected validation mode.
- Rebuild maintenance admission: Mutating v3/v4 requests are rejected with
503 maintenance_pending while a rebuild is active; read, health and safe
operation-control paths remain available.
- Retrieval scope enforcement: Authorized tenant/dataset vector candidates
are filtered before ANN ranking, and rebuild verification exercises bounded
cross-tenant and cross-dataset negative retrieval smoke checks.
[0.7.1] - 2026-07-29#
Fixed#
- Patch release for the merged production hardening and CI security fixes.
[0.7.0] - 2026-07-23#
Added#
- V4 full-cognitive contract: Added a breaking, versioned catalog/session/
mutation API while preserving all v3 lexical-core endpoints.
- Canonical provenance model: Added tenant-scoped UUID5 entities, aliases,
external identifiers, immutable document revisions/source chunks and
SQLite-authoritative Graph V2 assertions.
- Durable projection ownership: Added pipeline-run events, ordered
SQL→vector→graph projection outbox processing, shared artifact ownership,
fenced cleanup and two-way reconciliation.
- V4 clients: Added synchronous/asynchronous SDK methods and MCP tools for
catalog, session, insert, search, status, context, replay and rollback.
- V4 combined deployment: Added the single-storage-owner
docker-compose.v4.yml topology.
Security#
- Catalog authorization: Added principal roles at tenant, workspace and
dataset scope plus explicit purge/rollback permissions. Agent identifiers
remain compute/persona context and are not the v4 tenant boundary.
- Rotation-safe API keys: Added key-ID addressed salted scrypt hashes,
revocation, rotation and multiple active principal-bound credentials.
- Rate-limit credential lifecycle: Daily and minute limits now use the
verified server-side principal_id; raw API credentials and request-supplied
tenant/agent values are not used as rate-limit identities. The migration
intentionally discards legacy daily_limits.agent_id rows because they may
contain credentials, causing a one-time daily-counter reset on upgrade.
Changed#
- Retrieval V2: Dataset-filtered vector, BM25 and graph ranks now use true
reciprocal rank fusion followed by a bounded legal/provenance rerank.
- PageRank safety: PageRank is observation-only telemetry and can no longer
quarantine or invalidate retrieval artifacts.
- V4 write path: Tier-3 validation precedes all active projections; direct
cross-store Saga writes remain only in the v3 compatibility path.
- Kùzu offline migration safety:
scripts/migrate_to_kuzu.pynow builds
and validates a versioned staging artifact under a process lock and SQLite
journal before same-filesystem promotion. Previous live artifacts are
retained for explicit rollback; --wipe is refused.
- Kùzu runtime schema safety: Startup no longer applies unversioned
ALTER TABLE statements to an existing graph. migrate_kuzu_schema.py
must first clone, checksum-validate, and promote an existing graph offline.
[0.6.1] - 2026-07-17#
Added#
- Multi-Stage CrossEncoder Reranking: Introduced Stage 2 learned reranking (
mesa_memory/retrieval/reranker.py) powered bycross-encoder/ms-marco-MiniLM-L-6-v2to substantially improve retrieval precision on top of Alpha Reciprocal Rank Fusion. - Candidate Pool Expansion: Added
crossencoder_pool_multiplierconfiguration (default:3x) to expand Stage 1 candidate pool size prior to CrossEncoder scoring. - Tenant-Isolated Batch Fetching: Implemented
MemoryDAO.get_nodes_by_ids_batch()inmesa_storage/dao.pyto fetch candidate payloads in a single optimized SQL query enforced with mandatoryWHERE agent_id = ? AND id IN (...)Row-Level Security. - Non-Blocking Inference & Lazy Loading: Offloaded CrossEncoder model prediction to
asyncio.run_in_executor()usingThreadPoolExecutorto prevent event-loop blocking. Added lazy singleton initialization inmesa_api/router.py. - Graceful Degradation: Added resilient fallback mechanisms ensuring that if model loading or runtime inference fails,
CrossEncoderRerankerlogs the warning and falls back cleanly to Stage 1 Alpha-reranked ordering. - Configuration & Environment Support: Added
MESA_CROSSENCODER_ENABLED,MESA_CROSSENCODER_MODEL, andMESA_CROSSENCODER_POOL_MULTIPLIERoptions (mesa_memory/config.pyand.env.example). - Comprehensive Test Suite: Shipped unit and integration tests in
tests/test_crossencoder_reranking.pycovering fallback behavior, score sorting, batch RLS isolation, and hybrid retrieval flow.
[0.5.2] - 2026-07-13#
Added#
- Comprehensive Benchmark Suite: Introduced the
mesa-benchmarkecosystem for rigorous, reproducible multi-tier evaluations of MESA's cognitive memory engine. - Competitor Integrations: Added out-of-the-box evaluation clients for industry competitors (Zep, Letta, Mem0) to run head-to-head performance comparisons.
- Google Colab Automation: Shipped robust Google Colab notebooks with zero-touch "Run All" support, automated Git clone syncing, missing dependency installations, and
qwen3:8b/llama3.2:3bsetup scripts. - Procedural Dataset Generator: Added a scalable synthetic dataset generator script for extensive load and stress testing.
- Statistical Reporting Engine: Overhauled the
MarkdownReporterwith beautiful aesthetic tables, Cohen's Kappa agreement tracking, and multi-model consensus contingency matrices.
Fixed#
- Evaluator & LLM Judge: Resolved silent fallback bugs in the LLM Judge, suppressed
LiteLLMdebug banners, and formatted provider prefixes properly. - Async & Connection Leaks: Refactored the benchmark architecture to resolve
asyncioevent loop conflicts and unclosed DB connection/tempdir leaks. - CI/CD Hardening:
- Mocked physical
config.yamldependencies in unit tests (MagicMock) to isolate the test suite. - Skipped network-dependent Ollama tests in GitHub Actions.
- Added missing
nest_asyncioanddatasetspackages topyproject.toml. - Suppressed
mypystatic typing errors andruff(E402,F841) linting errors across scratch and benchmark scripts.
[0.5.1] - 2026-06-03#
Added#
- Phase 4.1 - Self-Healing Graphs: Implemented Async Damped PageRank algorithm in the background to detect and quarantine hallucinated nodes based on
epistemic_uncertainty. - Phase 4.2 - Spreading Activation: Integrated Cognitive Salience calculations natively on KuzuDB to simulate energy spreading across the graph without Python bottlenecking.
- Phase 4.3 - Continuous Learning: Added Orthogonal Procrustes alignment for vector space rotations in LanceDB, enabling dynamic continuous learning.
- Persistent WAL Queue: Added a persistent SQLite-based WAL queue mechanism for LanceDB migrations, intercepting and queueing incoming vectors to ensure multi-worker safety during Blue/Green deployment alignment.
Changed#
- Cypher Optimization: Upgraded KuzuDB Cypher queries for Spreading Activation from Neo4j-specific inline
COUNT { ... }subqueries to standard KuzuDBOPTIONAL MATCHandcount()aggregation with explicit float casting. - DAO Orchestration: Decoupled
VectorEngine(lancedb_provider) from SQLite. All WAL queue orchestration (lancedb_is_migratinglock, queue insertions, and flushing) is now centralized entirely in theMemoryDAOlayer to maintain architectural boundaries.
Fixed#
- Phantom Write Vulnerability: Fully remediated Phantom Writes during LanceDB Blue/Green deployments by utilizing the atomic SQLite WAL queue.
- Global Lock Bottleneck: Resolved the Global Lock bottleneck during table promotion by replacing thread-blocking locking mechanisms with efficient async execution wrapping.
[0.5.0] - 2026-06-02#
Added#
- KùzuDB Native Integration: Full integration via
KuzuGraphProvider, serving as the foundational graph engine for Phase 4. - Asynchronous Graph I/O: Implemented a
ThreadPoolExecutorasynchronous wrapper pattern for all KùzuDB C++ bindings to protect the FastAPI event loop from blocking. - Composite Primary Keys: Introduced
agent_id::node_idindexing pattern for mathematically proven Zero-Trust isolation with O(log N) lookup times.
Fixed#
- Infinite Scalability (OOM Resolution): Eliminated the 50,000 node RAM ceiling and resolved Out-Of-Memory (OOM) crashes by offloading persistent topology to KùzuDB.
- DAO Layer Bypass: Resolved the architectural bypass in the session context API (
router.py), fully encapsulatingraw_logsqueries viadao.get_recent_session_logs().
Removed#
- NetworkX Eradicated: Complete deprecation and eradication of the legacy in-memory
networkxgraph engine. - Legacy SQLite Edges: Removed all legacy SQLite dual-write schema operations for graph edges, establishing KùzuDB as the single source of truth for topology.
[0.4.2] - 2026-06-01#
Security#
- **Zero-Trust Tenant Isolation on
raw_logs:** Added explicitagent_idcolumn to theraw_logstable and enforcedWHERE agent_id = ?predicates on allinsert_raw_log,get_raw_log, andupdate_raw_log_statusqueries inMemoryDAO. Injected_assert_valid_agent_id()at the entry point of each method, mathematically preventing cross-tenant data leakage on the ingestion path. - Migration Script: Added
scripts/migrate_raw_logs_agent_id.pyfor deterministic backfill ofagent_idfrom JSONpayloadon legacy databases.
Performance#
- Async Embedding Pipeline: Converted
_embed_textandcalculate_composite_similarityinlock.pytoasync def. All embedding calls now route throughawait embedder.aembed()orasyncio.run_in_executor(), eliminating event loop starvation under concurrent load. P99 latency verified at 27.85 ms (SLA: < 50 ms). - Bulk Graph Retrieval (N+1 Elimination): Refactored
HybridRetriever._build_graph_snapshot()to replace the per-nodeget_neighbors()loop with a single bulkSELECT * FROM edges WHERE agent_id = ?query. Reduces O(N) SQL round-trips to O(1) for graph construction. - Async File I/O in Consolidation Worker: Converted
PersistentQueue.__len__(),__getitem__(), andclear()from synchronousopen()calls to async viaasyncio.run_in_executor(), preventing event loop blocking during background consolidation.
Stability#
- OOM Prevention (MAX_GRAPH_NODES): Introduced a strict
MAX_GRAPH_NODES = 50,000cap in_build_graph_snapshot(). When the fetched node set exceeds this limit, nodes are sorted byupdated_at(newest first) and sliced to exactly 50,000 before NetworkX graph construction. An explicit warning is logged when the cap is triggered. RAM peak verified at 899.5 MB (limit: 2,048 MB).
DevOps#
- **Docker
MESA_API_KEYInjection:** AddedMESA_API_KEY=${MESA_API_KEY:-}todocker-compose.ymlenvironment array, preventing instant container crashes on fresh clones. - **
.env.exampleDocumentation:** Added missing internal tuning parameters:MESA_HYBRID_ALPHA,MESA_HYBRID_BETA,MESA_T_ROUTE,MESA_LEGAL_DOMAIN_MODE,MESA_MAX_RAM_MB. - Version Synchronization: Aligned
pyproject.toml, README badge, and release script tov0.4.2.
Quality Assurance#
- Coverage Threshold Restored: Reverted CI/CD coverage gate from 70% back to the mandated 85% minimum (
pyproject.toml+.github/workflows/ci.yml). Current coverage: 88.40%. - Mathematical Vector Fixtures: Created
tests/fixtures/vectors.pywithVEC_ORTHOGONAL(cos_sim=0.0),VEC_NEAR(cos_sim=0.79), andVEC_MATCH(cos_sim=0.95). Replaced all vacuously-true[0.1] * 768mocks intest_consolidation.pyandtest_p0a_batch.pywith genuine threshold assertions against the 0.80 merge threshold. - Async Coverage Tests: Added
tests/test_async_lock_loop.pycovering async embedding fallbacks, executor paths, and circuit breaker error handling. - Soak Test Verified: 5-minute load test (5,900 requests, 20 req/s, 30 concurrent) — 100% success ratio, zero OOM events, zero queue backpressure.
Removed#
- Dead Code: Deleted legacy
mesa_memory/retriever.py(self-importing module) and orphaned_sort_by_saliencefunction fromConsolidationLoop.
[0.4.1] - 2026-05-29#
Added#
- **feat(dx): Optional REBEL Model (
MESA_REBEL_ENABLED):** The 1.8 GBBabelscape/rebel-largemodel is now gated behind a boolean config flag (MESA_REBEL_ENABLED, defaulttrue). Setting tofalsecompletely skips model download and initialization, eliminating Docker build timeouts and reducing cold-start from ~5 min to <10 s for development and CI environments. - feat(dx): LLM-Fallback Triplet Extraction: When REBEL is disabled, triple extraction falls back to a zero-shot prompt via the configured Tier-3 LLM provider (Groq/Llama-3). The fallback produces the identical
{head, relation, tail}dict format consumed by_commit_triplets, requiring zero downstream changes. Includes a robust JSON parser that handles markdown fences,subject/predicate/objectkey aliases, and malformed LLM output. - docs(readme): Docker-First Quickstart Overhaul: README now opens with a 60-second copy-paste Docker quickstart block. All API examples updated to v3 endpoints (
/v3/memory/insert,/v3/memory/search,/v3/memory/status/{log_id},/v3/memory/purge) with correctX-API-Keyheaders. Added environment variables reference table. - docs(mcp): Claude Desktop MCP Integration Guide: New dedicated section with the exact
claude_desktop_config.jsonsnippet required to connect Claude Desktop to a local MESA instance via themesa_mcp.serverstdio transport. Documents bothrecord_memoryandsearch_memoryMCP tools.
[0.4.0] - 2026-05-29#
Fixed#
- Split-Brain Dual-Write Atomicity (P0): Implemented an atomic Saga pattern for SQLite/LanceDB dual-writes. SQLite
COMMITis now strictly deferred until the LanceDBupsertsucceeds; on failure, the transaction falls back to a SQLROLLBACK, eliminating split-brain orphan records across the relational and vector stores. - Async Embedder Event Loop Starvation (P0): Offloaded synchronous
embedder()calls on the search hot-path toasynciothread-pool executors (run_in_executor), preventing event loop starvation under concurrent query load. - LanceDB Filter Injection (P0): Enforced strict regex sanitization (
^[a-zA-Z0-9_-]+$) onagent_idvalues before interpolation into LanceDBWHEREclause filters, closing a filter injection vector in the vector search path.
[0.3.1] - 2026-05-23#
Added#
- Alpha-Reranking: Applied alpha-reranking and adaptive LLM routing.
Fixed#
- CI/CD Pipeline: Resolved mypy type check errors for CI/CD pipeline.
[0.3.0] - 2026-05-22#
🔴 Critical Security Fix#
- **Mandatory
agent_idEnforcement (P0 RLS Remediation):** 11 functions inmesa_storage/schemas.pypreviously acceptedagent_idas optional or omitted it from SQLWHEREclauses, creating cross-tenant data leakage vectors. All query, mutation, and traversal functions now require **mandatoryagent_id** with hardcodedAND agent_id = ?predicates. Affected:soft_delete_node,mark_consolidated,get_active_nodes,find_nodes_by_name,upsert_edge,soft_delete_edge,get_neighbors,get_active_edges,k_hop_neighbors,fts5_search. Thefts5_searchcall inmesa_api/router.pywas also patched to passagent_id=request.agent_id.
Added#
- Headless FastAPI v3 API (
mesa_api/router.py): Stateless daemon-mode REST server.POST /v3/memory/insert(fire-and-forget viaBackgroundTasks, <150ms TTFT),POST /v3/memory/search(synchronous await),DELETE /v3/memory/purge(soft-delete only). - Strict Pydantic V2 API Schemas (
mesa_api/schemas.py):min_length=1on all identity fields,__unset__sentinel rejection, content ≤32 KB, metadata ≤64 keys,strict=True, frozen response models. - Asynchronous Storage Engine (
mesa_storage/sqlite_engine.py):aiosqlitewith connection pooling, WAL mode,synchronous=NORMAL, 64 MB cache, health checks, and WAL checkpointing. - LanceDB Vector Engine (
mesa_storage/vector_engine.py): Async-compatible viaThreadPoolExecutor+run_in_executor. Multi-dimensional table routing, soft-delete withexpired_at, mandatoryagent_idon all operations. - SQLite FTS5 Lexical Pre-Filtering (
mesa_storage/schemas.py): Zero-VRAM full-text search via FTS5 virtual tables with trigger-based sync. Enables lexical pre-filtering before vector/graph operations. - Memory DAO (
mesa_storage/dao.py): High-level Data Access Object enforcing mandatoryagent_idon every method. - Isolated Maintenance Worker (
mesa_workers/maintenance.py): Background worker forVACUUM, hardDELETE FROM, and LanceDB compaction on a **dedicated synchronoussqlite3connection** withisolation_level=Noneandbusy_timeout=30s. Retention-window-gated purge. - REM Cycle Worker (
mesa_workers/rem_cycle.py): Async consolidation withmax_records_per_cyclebatch slicing and token budget enforcement. - Python Client SDK (
mesa_client/client.py): Sync/async HTTP clients viahttpxwith Pydantic V2 validation andtenacityretry logic. - LangChain Adapter (
mesa_client/langchain.py):MesaRetrieverimplementing LangChain'sBaseRetrieverprotocol. - Evaluation Pipeline (
mesa_evals/): 100-question Golden Dataset (Legal=35, Financial=35, Code=30), deterministic synthetic generator, multi-path eval runner, and CI/CD gatekeeper enforcing cost/latency SLAs. - k-hop Graph Traversal (
mesa_storage/schemas.py): BFSk_hop_neighbors()with mandatoryagent_idpropagation.
Changed#
- Architecture: Library → Daemon: MESA is now a headless FastAPI daemon. All interaction flows through v3 REST endpoints or the Python SDK.
- Storage Decoupling:
mesa_storageis a standalone package independent ofmesa_memory. - Soft-Delete / Hard-Delete Separation: API restricted to soft-deletes; physical deletion exclusively in
MaintenanceWorker. - Test suite: Expanded from 159+ to 409 tests.
Removed#
- Memgraph references: All legacy stubs and configuration purged.
Dependencies#
| Package | Version | Role |
|---|---|---|
aiosqlite | ≥0.22.0 | Non-blocking SQLite engine |
fastapi | ≥0.111.0 | Headless REST API server |
lancedb | ≥0.30.0 | Vector storage |
httpx | ≥0.28.0 | HTTP client for SDK |
pydantic | ≥2.13.0 | Strict V2 schema validation |
uvicorn | ≥0.29.0 | ASGI server |
[0.2.0] - 2026-05-15#
Added#
- FastAPI REST Layer (
mesa_memory/api/server.py): Production-ready HTTP server exposing/ingest,/query,/health, and/metricsendpoints with Pydantic request/response schemas and proper lifecycle management. - Prometheus Observability: Module-level
Counter,Histogram, andGaugemetrics for valence tier hits, admission rates, consolidation batch duration, and cross-validation divergence. Exposed viaGET /metricsfor Prometheus scraping. - CMB Fitness Scoring (
mesa_memory/valence/fitness.py): Composite scoring function (0.0–1.0) based on content word density, token cost efficiency, and novelty score. Integrated into the/ingestpipeline. - Multi-Hop Graph Traversal (
mesa_memory/retrieval/graph_traversal.py):find_path()function usingnetworkx.shortest_pathwith configurablemax_hopsand gracefulNetworkXNoPathhandling.
- Persistent ValenceMotor State:
save_state()andload_state()methods usingaiosqliteto persist_ewmad_thresholdandmemory_countacross process restarts via avalence_statekey-value table. - StorageFacade Integration:
initialize_all()now accepts an optionalvalence_motorparameter to automatically restore cognitive state on startup. - Docker Containerisation:
Dockerfile(python:3.10-slim, multi-layer caching, built-in healthcheck) anddocker-compose.yml(persistent volume mapping, env passthrough,unless-stoppedrestart policy). - Dependency Separation: Split
requirements.txtintorequirements-core.txt(lightweight API mode, ~200 MB) andrequirements-ml.txt(full ML mode with PyTorch/REBEL, ~3 GB). - Tutorial Script (
examples/hello_mesa.py): 3-scenario tutorial demonstrating single ingest, concurrent multi-agent ingestion, and multi-hop graph traversal. - Documentation: Enterprise-grade
README.mdwith Mermaid architecture diagram,docs/installation.md,docs/api-reference.md, andbenchmarks/v0.2.0_results.md.
Changed#
- DeterministicMockAdapter (
mesa_memory/adapter/mock.py): Extracted from inline demo script into a standalone module. Now handles Tier-3 validation prompts (decision/justification), batch extraction prompts (triplets/record_index), and context-query prompts. Deterministic SHA-256 embeddings (384-dim, unit-normalised). - AdapterFactory (
mesa_memory/adapter/factory.py): Expanded to routeclaude,ollama, andmockproviders alongsideopenai_compatible. AcceptsOptional[str]provider parameter with config fallback. - REBEL Pipeline (
mesa_memory/extraction/rebel_pipeline.py): Added hardware detection with CPU latency warning,_rebel_failurestracking list, and improved exception handling that logs"REBEL failed, triggering LLM fallback"instead of generic errors. - ObservabilityLayer: Prometheus metrics moved from instance-level (
__init__) to module-level singletons to preventValueError: Duplicated timeseries in CollectorRegistrywhenpytestcreates multiple instances.
Fixed#
- mypy strict compliance: Resolved type errors — incompatible dict types in
DeterministicMockAdapter, missing_rebel_failuresannotation, and implicitOptionalinAdapterFactory.get_adapter. - RBAC grant semantics: Tutorial and demo scripts now grant only
WRITE(which implicitly includesREADpercheck_accesslogic) instead of overwritingWRITEwithREADdue to the primary key constraint. - Prometheus duplicate registry: Module-level metric singletons prevent re-registration crashes across test fixtures and multi-instance scenarios.
[0.1.0] - 2026-05-11#
Added#
- 9-Module Architecture: Complete cognitive memory pipeline from ingestion through retrieval.
- Cognitive Memory Block (CMB) Schema (
mesa_memory/schema/cmb.py): Pydantic model with UUID7 IDs, embedding vectors, fitness scores, affective state, and resource cost tracking. - Valence Motor (
mesa_memory/valence/core.py): 3-tier admission gate with bootstrap cosine threshold, EWMAD drift calibration, and configurable recalibration intervals. - ECOD Anomaly Detection (
mesa_memory/valence/novelty.py): Embedding-space novelty scoring using cosine similarity distributions. - Drift Recalibration (
mesa_memory/valence/drift.py): Exponentially weighted threshold adaptation with sigmoid blending and configurable clamping. - REBEL Extraction Pipeline (
mesa_memory/extraction/rebel_pipeline.py): Thread-safe singleton holder for the Babelscape/rebel-large model with<triplet>/<subj>/<obj>token parsing. - Consolidation Loop (
mesa_memory/consolidation/loop.py): Batch orchestration with dual-LLM cross-validation, truncated JSON recovery, and salience-based record ordering. - Batch Orchestrator (
mesa_memory/consolidation/batch_orchestrator.py): Token-aware batch splitting with configurablemax_batch_tokens. - Tier-3 Validator (
mesa_memory/consolidation/tier3_validator.py): Asymmetric dual-LLM consensus with composite similarity scoring. - Graph Writer (
mesa_memory/consolidation/graph_writer.py): Atomic triplet commit with MVCC node versioning and hub-degree threshold checks. - Storage Facade (
mesa_memory/storage/__init__.py): Unified interface to SQLite raw log, LanceDB vector index, and NetworkX knowledge graph with atomic cross-layer consistency and orphan reconciliation. - Raw Log Storage (
mesa_memory/storage/raw_log.py): Async SQLite with WAL mode, soft-delete, and tier-3 deferred record fetching. - Vector Storage (
mesa_memory/storage/vector_index.py): LanceDB integration with dynamic RAM budgeting, memory limit enforcement, and kNN search. - NetworkX Graph Provider (
mesa_memory/storage/graph/networkx_provider.py): In-memory graph with SQLite persistence, MVCC node versioning, BFS subgraph extraction, and Personalized PageRank. - BaseGraphProvider ABC (
mesa_memory/storage/graph/base.py): Provider-agnostic async contract for all graph backends. - Hybrid Retriever (
mesa_memory/retrieval/hybrid.py): RRF-fused vector similarity + Personalized PageRank retrieval with cold-start fallback and token-limited context formatting. - Query Analyser (
mesa_memory/retrieval/core.py): spaCy-based entity extraction and query normalisation. - RBAC Access Control (
mesa_memory/security/rbac.py): SQLite-backed permission enforcement with advisory prompt injection detection. - Observability Layer (
mesa_memory/observability/metrics.py): Structured JSON logging with counters, gauges, and histograms. - Configuration System (
mesa_memory/config.py): Pydantic-settings with hierarchical RAM detection (psutil → env var → cgroup → safe-mode fallback). - LLM Adapters:
ClaudeAdapter,OllamaAdapter, andOpenAICompatibleAdapterwith local embedding fallback viasentence-transformers/all-MiniLM-L6-v2. - Test Suite: 159+ tests covering unit, integration, P0 hotfixes, and performance benchmarks.
- CI Pipeline: GitHub Actions workflow with Black, Ruff, mypy, pytest + coverage, and Codecov upload.
[0.9.3]: https://github.com/Yasou13/MESA/compare/v0.9.2...v0.9.3
[0.9.2]: https://github.com/Yasou13/MESA/compare/v0.9.1...v0.9.2
[0.9.1]: https://github.com/Yasou13/MESA/compare/v0.9.0...v0.9.1
[0.9.0]: https://github.com/Yasou13/MESA/compare/v0.8.1...v0.9.0
[0.8.1]: https://github.com/Yasou13/MESA/compare/v0.8.0...v0.8.1
[0.8.0]: https://github.com/Yasou13/MESA/compare/v0.7.1...v0.8.0
[0.7.1]: https://github.com/Yasou13/MESA/compare/v0.7.0...v0.7.1
[0.7.0]: https://github.com/Yasou13/MESA/compare/v0.6.1...v0.7.0
[0.6.1]: https://github.com/Yasou13/MESA/compare/v0.5.2...v0.6.1
[0.5.2]: https://github.com/Yasou13/MESA/compare/v0.5.1...v0.5.2
[0.5.1]: https://github.com/Yasou13/MESA/compare/v0.5.0...v0.5.1
[0.5.0]: https://github.com/Yasou13/MESA/compare/v0.4.2...v0.5.0
[0.4.2]: https://github.com/Yasou13/MESA/compare/v0.4.1...v0.4.2
[0.4.1]: https://github.com/Yasou13/MESA/compare/v0.4.0...v0.4.1
[0.4.0]: https://github.com/Yasou13/MESA/compare/v0.3.1...v0.4.0
[0.3.1]: https://github.com/Yasou13/MESA/compare/v0.3.0...v0.3.1
[0.3.0]: https://github.com/Yasou13/MESA/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/Yasou13/MESA/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/Yasou13/MESA/releases/tag/v0.1.0
