MESA Core · v0.9.3

Installation & deployment

v0.9.3 source: docs/getting-started.md

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:

bash
pip install mesa-memory==0.9.3
mesa start

The 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:

bash
git clone --branch v0.9.3 --depth 1 https://github.com/Yasou13/MESA.git
cd MESA
uv sync --locked --python 3.11
uv pip check

Run local Docker#

bash
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:

bash
pip install mesa-memory==0.9.3
pip install --upgrade mesa-memory==0.9.3

OpenAI 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:

bash
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

UML · Deployment diagramOne process, one storage root, optional model providers
«device»Host · VM or Docker Compose service «execution environment»Python 3.11–3.13 · uvicorn «artifact»mesa · combined runtimeAPI + workers + MemoryDAO {replicas = 1} «volume»MESA_STORAGE_ROOT «artifact»SQLite«artifact»LanceDB«artifact»Kùzu owns «device»Client app · agent · SDK HTTP APIX-API-Key «external»Model providers only if models enabled extraction · validation · embeddings «device»Backup target offline Never point two processesat one storage root.Scale admission, not writers.

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:

bash
pip install mesa-memory

Supported 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:

bash
git clone https://github.com/Yasou13/MESA.git
cd MESA
uv sync --locked --python 3.11
uv pip check

Quickstart#

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:

bash
mesa start

2. Add and search documents#

In another terminal, add and search documents immediately without manual credential configuration:

bash
mesa add document.txt --source file://document.txt
mesa search "your query"
mesa status

By 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:

python
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:

bash
mesa mcp-config

5. 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:

bash
MESA_MODEL_ENABLED=true
MESA_LLM_MODEL=ollama:qwen2.5:7b
MESA_EMBEDDING_MODEL=ollama:bge-m3

Under 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:

bash
MESA_GRAPH_ENABLED=false

GRAPH 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):

bash
docker compose -f docker-compose.v4.yml up --build -d

Credentials are written to /var/lib/mesa/credentials.json in the container volume:

bash
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:

Colab Quickstart

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:

bash
uv sync --locked --python 3.11
uv pip check

pyproject.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.

ExtraWhen needed
devLocal checks and development
adaptersProvider SDK integrations
mlLocal transformer/embedding dependencies
loadtestExplicit load-test work
mcpCompatibility extra; MCP itself is already a core dependency

For a provider setup that needs both SDKs and local models:

bash
uv sync --locked --python 3.11 --extra adapters --extra ml
uv pip check

Install only the extras needed by the selected runtime. Model downloads,

credentials and operational provider endpoints are separate prerequisites.

Choose topology and storage#

UseProfile / Compose fileStorage rule
Canonical V4combined / docker-compose.v4.ymlOne process owns API, consumers and stores
Local model-disabled startupcombined, models/providers falseV4 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:

  1. Select a new or compatible V4 storage root and provision credentials/ACL using

runbook section 2.

  1. 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.

  1. Select validation mode. Mode 0 has no LLM validator but still needs canonical

extraction and embeddings; mode 2 requires distinct A/B validator identities.

  1. 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):

bash
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_entrypoint

The 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:

bash
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 ps

For V3 lexical compatibility:

bash
docker compose config --quiet
docker compose up --build -d

Compose 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.