MESA Core stores source-backed agent memory and returns scoped evidence over HTTP, Python clients and MCP. SQLite owns the catalog, assertions, mutation ledger and artifact ownership. LanceDB and Kùzu provide derived projections.
Package version is 0.8.1. V4 is the current API. Production qualification remains at the release candidate stage: NO-GO until the release gates pass for the intended commit. The v0.8.1 publication status is separate from production certification.
git clone https://github.com/Yasou13/MESA.git
cd MESA
uv sync --locked --python 3.11
uv pip checkPython 3.11–3.13 are the CI matrix; package metadata declares Python >=3.11.
Install uv first.
The command selects a supported interpreter; substitute 3.11–3.13 if needed.
The base install includes native storage and HTTP/SDK support; dev, provider
SDKs and local model dependencies are optional extras.
Then follow the local quickstart, which provisions
a disposable root, credentials and an authorized session before insertion.
| Goal | Read |
|---|---|
| Check startup without model calls | Model-disabled startup |
| Run canonical V4 ingestion | V4 provider prerequisites and installation |
| Use Docker or choose providers | Installation, configuration |
| Connect a client | API and SDK, MCP |
| Understand or change the system | Architecture, contributing |
| Find any other guide | Documentation index |
V4 runs one combined storage owner per root. An authenticated session binds
a principal, tenant, workspace, agent and immutable dataset set. Insertion
admits durable work; validation and ordered projections precede COMMITTED.
Retrieval combines vector, BM25, assertion and graph lanes with weighted rank
fusion, then packs source evidence into a bounded context.
FactExtractionService owns canonical V4 extraction. Validation can use deterministic checks (mode 0), a
single LLM (mode 1), or dual LLM consensus (mode 2). Mode 0 disables LLM
validation, not canonical extraction and embedding requirements.
docker-compose.v4.yml defines the V4 single-owner topology.
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.
GET /v4/capability reports runtime capabilities. Embedded storage requires a
single writer and workload-specific capacity testing. Projection rebuild is
offline, full-root and disabled by default. Historical benchmarks and audits
are not current production measurements. Evidence linkage and model consensus
do not establish source truth or legal correctness.
See limitations, operations, security and vulnerability reporting.
Use testing for focused checks, optional dependencies and document validation. Changes are recorded in CHANGELOG.md.
MIT.