MESA Core · v0.9.3
Installation & deployment
This guide has equivalent English and Turkish versions. The source sections behind this page are at the bottom.
Install the released package#
Python 3.11–3.13 is the tested matrix. Linux/macOS run natively; Windows uses Docker or WSL. Install the version matched to these guides:
pip install mesa-memory==0.9.3
mesa startThe CLI provisions the local catalog, grants, storage and credentials. Models default off; documents can be ingested and searched with BM25. Optional adapters and ml extras support the selected model providers. No separate database server is required.
Use the pinned source checkout#
For development, use the released Git object and lockfile:
git clone --branch v0.9.3 --depth 1 https://github.com/Yasou13/MESA.git
cd MESA
uv sync --locked --python 3.11
uv pip checkRun local Docker#
docker compose -f docker-compose.v4.yml up --build -d
docker compose -f docker-compose.v4.yml exec -T mesa-v4 mesa add - --source file://document.txt < document.txt
docker compose -f docker-compose.v4.yml exec mesa-v4 mesa search "archive"Run Compose from the pinned source checkout, with your own document.txt present. The container runs mesa start, binds internally to 0.0.0.0 and publishes only on the host loopback. Its volume retains data and credentials at /var/lib/mesa/credentials.json. One combined writer owns each storage root. Readiness and local startup do not qualify production.
Package index and optional extras#
On 17 November 2026, GitHub tag v0.9.3 and PyPI 0.9.3 publication were verified. Both the wheel and sdist are present and not yanked. Base installation and upgrade:
pip install mesa-memory==0.9.3
pip install --upgrade mesa-memory==0.9.3OpenAI and Ollama SDKs are included in the base package. Anthropic needs [adapters]; local embedding and BGE reranking need [ml]. Install only the extras needed for your selected provider:
pip install "mesa-memory[adapters]==0.9.3"
pip install "mesa-memory[ml]==0.9.3"Publication does not change the Alpha / production NO-GO status.
Diagrams
The three stores are embedded files under one root, so they are backed up and restored together. Models-off combined operation accepts documents and supports BM25. Legal rules need no model; open-ended SPO extraction requires explicit enablement.
All diagrams with their design rationale: Architecture →
Source reference for this page
The sections of the upstream file that back this page, unchanged. Source section links open the appendix automatically.
Installation#
Install MESA:
pip install mesa-memorySupported natively on Linux and macOS. On Windows, use Docker or WSL.
The development version can be installed directly from git: pip install "mesa-memory @ git+https://github.com/Yasou13/MESA".
Or install from source with uv:
git clone https://github.com/Yasou13/MESA.git
cd MESA
uv sync --locked --python 3.11
uv pip checkQuickstart#
1. Start the server#
For standard local usage, mesa start automatically provisions local storage (~/.mesa/data), writes credentials (~/.mesa/credentials.json), sets model-disabled defaults, and starts the loopback server on http://127.0.0.1:8000:
mesa start2. Add and search documents#
In another terminal, add and search documents immediately without manual credential configuration:
mesa add document.txt --source file://document.txt
mesa search "your query"
mesa statusBy default, mesa add waits for all chunks to commit and the revision to become active, printing searchable when complete (pass --no-wait to return immediately). To delete an ingested document, run mesa delete <document_id> or mesa delete --source <ref>.
3. Python SDK#
Use the high-level Mesa client to ingest documents and query evidence contexts:
from pathlib import Path
from mesa_client import Mesa
mesa = Mesa()
mesa.add(Path("document.txt").read_text(), source="file://document.txt", wait=True)
print(mesa.context("your query"))Mesa() uses MESA_API_KEY and MESA_BASE_URL when they are set, otherwise the local credentials in ~/.mesa/credentials.json.
4. Connect MCP clients#
Connect Claude Desktop or any MCP client by generating a ready-to-paste configuration block:
mesa mcp-config5. Internal models (optional)#
Models stay off by default. Documents are stored and found through BM25 lexical search without any model running.
To enable semantic vector search and fact extraction with local Ollama, add to ~/.mesa/.env:
MESA_MODEL_ENABLED=true
MESA_LLM_MODEL=ollama:qwen2.5:7b
MESA_EMBEDDING_MODEL=ollama:bge-m3Under decision D31, local openai_compatible servers (e.g. vLLM started with --port 8001, at http://127.0.0.1:8001/v1, since MESA itself uses port 8000) are also permitted with MESA_EXTERNAL_PROVIDER_ENABLED=false on a local endpoint and require no API key. For external cloud APIs (OpenAI, Anthropic), set MESA_EXTERNAL_PROVIDER_ENABLED=true and supply the required API keys.
Missing extras raise clear, actionable installation messages:
- Anthropic LLM requires the adapters extra:
pip install "mesa-memory[adapters]" - Local embedding (
sentence-transformers) →pip install "mesa-memory[ml]"
6. Graph toggle#
To run without the Kùzu graph database, set:
MESA_GRAPH_ENABLED=falseGRAPH lanes end SKIPPED, and turning the flag back on later backfills the graph at startup.
7. Docker#
Run MESA in a single-user local container (D32):
docker compose -f docker-compose.v4.yml up --build -dCredentials are written to /var/lib/mesa/credentials.json in the container volume:
docker compose -f docker-compose.v4.yml exec mesa-v4 cat /var/lib/mesa/credentials.json
docker compose -f docker-compose.v4.yml exec -T mesa-v4 mesa add - --source file://document.txt < document.txt
docker compose -f docker-compose.v4.yml exec mesa-v4 mesa search "your query"No environment variables are required: models and external providers default
off. The image runs mesa start --host 0.0.0.0 as a non-root user; Compose
publishes only 127.0.0.1:8000. Credentials retain a loopback base URL for CLI
use inside the container. The named volume keeps data and credentials on
restart. MESA_API_KEY and MESA_PRINCIPAL_ID are optional for existing
bootstrap setups; when set, the mesa commands inside the container use that
key first, so add -e MESA_API_KEY= after exec to use the local credentials. Ollama defaults to http://host.docker.internal:11434,
which reaches the Docker host. The default image includes adapters; add
sentence-transformers with
docker compose -f docker-compose.v4.yml build --build-arg MESA_EXTRAS=ml,adapters.
8. Google Colab#
Run MESA with GPU-accelerated Ollama in Google Colab:
Advanced Operator & Production Profiles#
Use Python 3.11–3.13 (the CI matrix) and
uv.
Docker with Compose is needed only for containers. Run from the repository:
uv sync --locked --python 3.11
uv pip checkpyproject.toml declares supported dependency ranges and
uv.lock fixes the graph used by CI/Docker. CI pins its installer
version in the workflow; an installed dependency range is not a model download.
Choose --python 3.11, 3.12 or 3.13 if appropriate. Leaving the interpreter
unspecified can select a newer Python outside the tested matrix. Use
uv sync --locked --python 3.11 --extra dev when running developer tests.
SQLite (with FTS5) comes from the Python interpreter; LanceDB, PyArrow and Kùzu
are installed as core Python dependencies. No separate database server, Docker
container, manual SQL import or ML extra is needed for models-disabled startup.
Native wheels depend on Python/platform availability. The isolated installation
verified for this guide is Linux x86_64 / Python 3.11; other platforms were not
verified in this developer-experience pass.
| Extra | When needed |
|---|---|
dev | Local checks and development |
adapters | Provider SDK integrations |
ml | Local transformer/embedding dependencies |
loadtest | Explicit load-test work |
mcp | Compatibility extra; MCP itself is already a core dependency |
For a provider setup that needs both SDKs and local models:
uv sync --locked --python 3.11 --extra adapters --extra ml
uv pip checkInstall only the extras needed by the selected runtime. Model downloads,
credentials and operational provider endpoints are separate prerequisites.
Choose topology and storage#
| Use | Profile / Compose file | Storage rule |
|---|---|---|
| Canonical V4 | combined / docker-compose.v4.yml | One process owns API, consumers and stores |
| Local model-disabled startup | combined, models/providers false | V4 storage and BM25 search without model calls |
Choose a dedicated absolute writable storage root. Do not use the repository,
home directory or filesystem root. V3 and V4 must not write the same root.
Fresh combined startup initializes the databases automatically; keep SQLite,
LanceDB, Kùzu and the policy database together under that root. The runtime has
one owner: stop it before running offline admin or migration commands.
The runtime does not load .env implicitly; the explicit dotenv precedence is
explained in configuration.
Native V4 startup#
Before startup:
- Select a new or compatible V4 storage root and provision credentials/ACL using
- Install the selected extraction and embedding dependencies; configure their
provider/model identity. External text-embedding-3-small requires dimension
1536; the local BAAI/bge-m3 default is 1024. Equal dimensions alone are insufficient.
- Select validation mode. Mode 0 has no LLM validator but still needs canonical
extraction and embeddings; mode 2 requires distinct A/B validator identities.
- Supply the issued API key and provider secrets privately to the process.
Example profile after those prerequisites (the storage path is an operator
example, not an automatically provisioned directory):
export MESA_STORAGE_ROOT=/srv/mesa/v4-data
export MESA_RUNTIME_PROFILE=combined
export MESA_LOAD_DOTENV=false
export MESA_MODEL_ENABLED=true
export MESA_TIER3_MODE=0
export MESA_PRINCIPAL_ID=service-api
# Set MESA_EXTERNAL_PROVIDER_ENABLED to match the reviewed providers.
.venv/bin/python -m mesa_memory.runtime_entrypointThe launcher binds 0.0.0.0; use the explicit loopback command from the
quickstart for local use. Readiness is /health/init; /health requires a key.
The V4 example creates the catalog and session,
inserts a source, polls its mutation and checks evidence. Its docs-* identities
require the grants shown in the quickstart.
Compose#
V4 provisions local credentials automatically, with models and external
providers off. Existing deployments may supply MESA_API_KEY and
MESA_PRINCIPAL_ID privately. For model-enabled operation, set the model flags
and provider configuration above:
docker compose -f docker-compose.v4.yml config --quiet
docker compose -f docker-compose.v4.yml up --build -d
docker compose -f docker-compose.v4.yml psFor V3 lexical compatibility:
docker compose config --quiet
docker compose up --build -dCompose publishes the API on loopback. V4 mounts its named volume under
/var/lib/mesa, with storage at /var/lib/mesa/data. Host provisioning against
/srv/mesa/v4-data does not provision that named volume: run admin commands
against the actual deployment's policy database, with the same credential and
ACL scope. Do not add a second writer to the volume. Rendering Compose with
models disabled supports V4 storage and BM25 search.
Upgrade and verification#
Use migration for schema/representation upgrades,
backup and restore for recovery, and
projection rebuild for the offline runner. Projection
rebuild does not convert a V3 database to V4.
Run developer checks for the affected contracts. Passing these
checks does not replace real-provider, migration/restore or soak release evidence.
