Skip to content

MESA v0.9.0

Choose a tag to compare

@Yasou13 Yasou13 released this 28 Oct 17:40
7062faf

MESA v0.9.0 brings together the MVP work delivered across Rounds 1–12: a smaller V4-only core, model-optional document search, durable processing, safer document lifecycle handling, and local CLI/SDK/MCP onboarding.

MESA stores source-linked evidence for AI applications. SQLite remains the source of truth; LanceDB and Kùzu are derived projections. MESA returns evidence with document, revision and passage provenance; the calling application writes the final answer.

Install and start

Requires Python 3.11+. Linux and macOS are supported natively; use Docker or WSL on Windows.

pip install "mesa-memory[adapters]==0.9.0"
mesa start

In another terminal:

mesa add document.txt --source file://document.txt
mesa search "your query"
mesa mcp-config

Models are off by default. Documents can be stored and found through BM25 without an LLM or embedding model. Optional models add fact extraction and semantic retrieval.

Highlights

  • Local single-user setup with generated credentials, loopback binding, and mesa start, add, search, delete, status, and mcp-config.
  • A convenient Python Mesa SDK and whole-document ingestion through POST /v4/documents.
  • Lossless chunking, deterministic chunk identifiers, duplicate detection, durable retry, and revision tracking.
  • Unified provider:model settings for LLMs and embeddings, plus local Ollama and OpenAI-compatible endpoints.
  • An optional graph backend, explicit degraded-source reporting, and backfill when disabled projections are enabled again.
  • A PyPI package, local Docker workflow, Colab quickstart, and rewritten onboarding documentation.

What changed in Rounds 1–12

Round Delivered changes
1 — Offline baseline and V4 contracts Bundled the cl100k_base tokenizer data so token counting works offline. Ported release-gate coverage for authorization, principal/session isolation, durable dispatch and finalization to V4. Removed obsolete V3 MCP tools and moved MCP health checks to /health; removed unused evaluation/script packaging and hooks.
2 — V3 and obsolete runtime cleanup Removed V3 HTTP routes and client methods, the split api-only/worker-only profiles and Compose topology, obsolete background/retrieval/tracing modules, and legacy ingestion/consolidation branches. Kept canonical V4 fact extraction and durable processing. Raised the supported Python floor to 3.11 while updating compatible security fixes in the lockfile.
3 — Dependency and configuration cleanup Removed unreferenced dependencies, obsolete extras, dead configuration fields and 13 unused MemoryDAO methods. Updated installation, CI and documentation contracts for the reduced dependency surface.
4 — Retry completion and queue location Fixed V4 records becoming stranded in RETRY_PENDING, terminal failure handling and false acknowledgments. Put runtime dead-letter files under the configured storage root.
5 — Recovery and extraction fallback Added spaced retry backoff, startup crash recovery and working dead-letter replay. Made LLM storage validation opt-in. Unusable extraction output falls back to storing the source chunk without facts; provider failures still surface as failures. Separated timing-sensitive tests from the normal local gate.
6 — Model-free storage and search Enabled writes and BM25 search without models, independent extraction/embedding switches, skipped-vector backfill and identity-safe recovery. Added degraded_sources to search responses and configurable Ollama timeout, context window and generation options.
7 — Unified model configuration Standardized MESA_LLM_MODEL and MESA_EMBEDDING_MODEL on provider:model, added Ollama embedding support and dimension detection, and preserved fail-closed embedding identity checks. Corrected documentation for model-optional writes and search.
8 — Document lifecycle and privacy Fixed rebuild after delete/rollback, rejected reused revision numbers and writes to purged documents, and kept deleted/replaced content out of session context. Tightened historical revision filtering. Purge removes document text while preserving identifiers, hashes and shared ownership. Provider credentials now come from MESA-specific variables. See the graph-file limitation below.
9 — MCP and graph hardening Enabled direct stdio MCP operation without an embedded control-plane database. Improved MCP errors and agent-facing responses, always wrapped recalled source text as untrusted evidence, and added a recommended answering-system prompt. Restart resumes interrupted dispatch/projection work. Graph assertion text stays canonical in SQLite, with graph ranking reading authorized SQLite evidence.
10 — Local first-use workflow Added the Mesa convenience SDK, local CLI and POST /v4/documents. Whole-document ingestion preserves exact source slices, revision identity and retry idempotency. Added MESA_GRAPH_ENABLED=false, graph-aware readiness and later graph backfill. Fixed CLI result rendering and recalled-evidence wrapping.
11 — Onboarding, local providers and packaging Improved Turkish abbreviation/list/date chunk boundaries; rejected attempts to restore superseded text with a clear 409 response. Added bounded SDK retries for transient startup 503s and actionable missing-extra messages. Centralized local-endpoint checks, supported keyless local model servers, and made Docker provision persistent local credentials. Prepared v0.9.0 packaging, Colab and rewritten README/docs, with fresh-install and Docker checks.
12 — PyPI release preparation Switched general installation examples to the published PyPI package, retained one development-from-Git example, added the Colab restart note, dated the changelog and completed the README installation step. Final round checks covered packaging, rendered metadata, existing test preservation and the full local/MCP gates.

Publication follow-up: corrected an invalid PyPI Trove classifier before the successful upload in PR #136. Both the wheel and source distribution are published on PyPI.

Compatibility and upgrade notes

  • V3 interfaces have been removed. Integrations should use the current V4 HTTP API, Python SDK or MCP tools. The retired split runtime profiles and removed configuration fields/extras should be removed from deployment configuration.
  • Use MESA_LLM_MODEL and MESA_EMBEDDING_MODEL for model selection, and MESA-specific credential variables for providers.
  • Existing stores need the documented offline projection rebuild to adopt the graph representation with assertion text fields empty. Review the rebuild runbook and configuration guide before upgrading.

Verification

  • Release commit: 7062faf.
  • Same-commit MESA CI and external release gates: passed. Tagged-release CI: passed.
  • Clean wheel/sdist build and Twine checks passed. PyPI file hashes match the locally verified release artifacts.
  • A fresh Python 3.11 environment installed mesa-memory[adapters]==0.9.0 directly from PyPI. The downloaded wheel hash, version, SDK imports, mesa --help and dependency consistency checks passed.
  • The v0.9.0 tag is annotated and unsigned.

MVP status and known limitations

This is the v0.9 MVP release. Production qualification remains NO-GO until the documented production release gates are satisfied; publication and CI success do not certify production readiness.

Kùzu rebuilds can leave fragments of live document text in unused file bytes, and those fragments may survive a later purge. Strict-erasure deployments can disable the graph with MESA_GRAPH_ENABLED=false and retire existing graph generations/backups according to their retention policy. See security and privacy for the precise limitation and rebuild guidance.

Getting started · MCP setup · Colab quickstart · Full changelog