MESA Core · v0.9.3

Get started with MESA

Check the prerequisites#

This is a local evaluation. You will add text and retrieve a result with its source; no model account is required. MESA does not write the final answer. A terminal is the application where you enter commands; open Terminal on Linux or macOS.

Linux and macOS#

You need Python 3.11–3.13 and pip. Check the version first:

bash
python3 --version

Success: the output begins with Python 3.11, 3.12 or 3.13. If Python is missing or a different version is installed, use the official Python downloads. If venv is missing on Linux, install your distribution’s Python venv package.

Windows: WSL#

mesa start does not run in native Windows PowerShell. Follow Microsoft’s WSL installation guide, open a Linux terminal and use the Linux commands below there. Check Python inside WSL.

Docker path#

If you prefer containers, install Docker and skip to Docker setup.

Install v0.9.3#

Run these commands in a new working directory. The virtual environment keeps MESA packages separate from your other Python projects.

The v0.9.3 package is published on PyPI; the command pins that verified version. See installation and extras.

bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install mesa-memory==0.9.3
mesa --help

Success: the help lists start, add, search and status. For mesa: command not found, run . .venv/bin/activate in the correct directory.

Start the local server#

In Terminal 1:

bash
mesa start

Success: the server starts at http://127.0.0.1:8000 and logs Application startup complete. Keep this window open. Local storage is in ~/.mesa/data and private credentials in ~/.mesa/credentials.json.

Models and external providers are off by default; an existing .env configuration can change those defaults. This guide uses word search.

Open Terminal 2 in the same working directory and activate the environment:

bash
. .venv/bin/activate

Create the UTF-8 sample document. Save its receipt in receipt.json for the next step:

bash
printf '%s\n' 'The Atlas archive opens at 09:00 on weekdays.' > archive-en.txt
mesa add archive-en.txt --source file://archive-en.txt --json > receipt.json
cat receipt.json

Selected receipt fields from the historical Core v0.9.0 recording are shown below. Your identifiers can differ; receipt.json contains your own complete receipt.

json
{
  "document_id": "doc-5239a0bb570c977f678a3a48e2947b81",
  "revision_number": 1,
  "chunk_count": 1,
  "mutation_ids": [
    "8db5a8d0-d6f0-592c-8d23-23d27662de2c"
  ]
}

Success: the receipt includes document_id, chunk_count and mutation_ids. mesa add now waits for the revision to become ACTIVE before returning successfully. With --no-wait, the receipt confirms admission only.

Verify processing has finished#

Save the following code as wait_for_document.py. It reads local credentials automatically and checks the terminal state of every mutation:

python
import json
from mesa_client import Mesa, MesaV4Client

receipt = json.load(open("receipt.json", encoding="utf-8"))
with Mesa() as local:
    with MesaV4Client(local.base_url, api_key=local.api_key) as client:
        for mutation_id in receipt["mutation_ids"]:
            state = client.wait_until_committed(mutation_id)
            print(mutation_id, state["state"])
            if state["state"] != "COMMITTED":
                raise SystemExit("Document processing failed")
bash
python wait_for_document.py

Success: every line ends with COMMITTED. Another terminal state makes the script fail; do not treat that document as successfully processed. On timeout, check that the server is running and run the same script again. The status API exposes the details.

mesa status reports server readiness and health; it does not verify that document mutations have finished.

See your first search result#

bash
mesa search "archive"

Historical Core v0.9.0 recorded CLI output (not a v0.9.3 recording):

text
[1] score: 0.033 | doc-5239a0bb570c977f678a3a48e2947b81
    The Atlas archive opens at 09:00 on weekdays.

Success: the result contains your document’s 09:00 text and document identifier. Identifiers and scores can differ; a score is not a truth probability. Inspect source and revision fields in the recorded example on the home page.

Empty result: run the completion script first, then search for the exact word in your document. Connection error: keep Terminal 1 running and check for healthy mesa status output. Port already in use: check for another MESA instance; this guide does not require deleting existing storage.

Docker setup#

This path needs Git, Docker Engine/Desktop and Compose. Open the pinned source release:

bash
git clone --branch v0.9.3 --depth 1 https://github.com/Yasou13/MESA.git
cd MESA
docker compose -f docker-compose.v4.yml up --build -d
docker compose -f docker-compose.v4.yml exec mesa-v4 mesa status

Success: the status output shows ready and healthy. Compose publishes port 8000 only on the host loopback address; the volume preserves data and credentials.

Run the document, completion and search steps inside the container. Open a shell with:

bash
docker compose -f docker-compose.v4.yml exec mesa-v4 sh

Skip virtual-environment activation in this shell. Create the sample file, then use the mesa add command and Python completion script above. Enter exit when done. A host-side mesa command does not automatically read container credentials. See the deployment guide for details.

Use Python or connect an MCP client#

After your first successful search, open the Python SDK examples or MCP guide. Generate MCP settings with:

bash
mesa mcp-config

The output contains your local API key; keep it private. MESA returns context; your application and its model write the final answer.

Enable optional models and graph#

You do not need this for your first search. For semantic search and extraction, review model configuration and providers. External providers can transmit data and incur usage charges. Re-enabling graph/embeddings can backfill skipped work at startup. Local success does not establish production qualification; production checks remain incomplete.

Advanced: models and graph

v0.9.3 waiting behavior#

mesa add returns successfully after the revision becomes ACTIVE. --no-wait returns admission only. Receipts and CLI output above are historical Core v0.9.0 evidence, not re-recorded with v0.9.3. The completion script remains an optional verification step.

Source and version
v0.9.3 source: docs/getting-started.md
Sections that moved to their own page
Source reference for this page

The sections of the upstream file that back this page, unchanged. Source section links open the appendix automatically.

This guide covers getting started with MESA as a new user, from installation to querying evidence, followed by advanced operator provisioning and production runtime profiles. Production qualification remains at the release candidate stage: NO-GO until the release gates pass for the intended commit.

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

Using MESA with your LLM#

When connecting an external language model to answer questions from MESA memory, supply a system prompt that enforces untrusted data boundaries and precise source citations. mesa_client exports RECOMMENDED_SYSTEM_PROMPT for this purpose:

python
from mesa_client import AsyncMesaV4Client, RECOMMENDED_SYSTEM_PROMPT

# System prompt for answering LLMs:
system_prompt = RECOMMENDED_SYSTEM_PROMPT

# Retrieved memory context goes into the prompt/message:
async with AsyncMesaV4Client(base_url="http://127.0.0.1:8000", api_key=api_key) as client:
    bundle = await client.get_context(session_id=session_id, query="What is the policy?")
    user_message = f"{bundle['context']}\n\nQuestion: What is the policy?"

The context returned in bundle["context"] is deterministically wrapped in <UNTRUSTED_MEMORY_EVIDENCE>...</UNTRUSTED_MEMORY_EVIDENCE>. The prompt instructs the model to treat everything within those tags strictly as data, never follow instructions contained within them, cite document and revision IDs for every claim, and decline to answer if the evidence is insufficient.


Local quickstart#

Run from the repository after uv sync --locked --python 3.11. This uses one

combined process, no model loading and no external provider access. It checks

installation, credentials and readiness. This profile stores V4 records and finds them through BM25

without embedding or extraction calls. VECTOR lanes end SKIPPED; enable

embedding later to backfill vectors at startup with the same identity.

Automatic local bootstrap (mesa start)#

For standard local usage, mesa start provisions local storage (~/.mesa/data), initializes credentials (~/.mesa/credentials.json), sets model-disabled defaults, and starts the loopback server:

bash
mesa start

In another terminal, add and search documents immediately without manually exporting credentials:

bash
mesa add notes.txt --source file://notes.txt
mesa search "notes"
mesa status

Provision before startup (manual)#

Choose a disposable location on a disk with sufficient free space. The example

uses a unique child under ~/mesa-doc-demos; do not reuse user storage.

/tmp may be memory-backed on some hosts.

bash
mkdir -p "$HOME/mesa-doc-demos"
export MESA_STORAGE_ROOT="$(mktemp -d "$HOME/mesa-doc-demos/run-XXXXXX")"
export MESA_RUNTIME_PROFILE=combined
export MESA_LOAD_DOTENV=false
export MESA_MODEL_ENABLED=false
export MESA_EXTERNAL_PROVIDER_ENABLED=false
export MESA_TIER3_MODE=0
export MESA_PRINCIPAL_ID=docs-principal
export MESA_PORT=18080
export MESA_API_KEY="$(.venv/bin/mesa-v4-admin issue-key --principal docs-principal)"
.venv/bin/mesa-v4-admin grant-role --principal docs-principal --tenant docs-tenant --role OWNER
.venv/bin/mesa-v4-admin grant-agent --principal docs-principal --agent docs-agent --permission SESSION_CREATE

Keep the issued key out of logs and shared terminal output. The commands write

only the new sample policy database. Start the following server in this terminal after provisioning. For client

commands, use another terminal with the same exported settings and key supplied

privately; a newly opened terminal does not automatically inherit these exports:

bash
.venv/bin/python -m uvicorn mesa_memory.api.server:app --host 127.0.0.1 --port 18080

Wait for readiness:

bash
curl --fail http://127.0.0.1:18080/health/init
curl --fail -H "X-API-Key: $MESA_API_KEY" http://127.0.0.1:18080/health

Readiness returns {"status":"ready"} on success; health reports store/queue

state. The normal launcher binds all interfaces internally; this explicit

uvicorn command limits the local example to loopback.

With MESA_API_KEY already exported, the same checks are available through:

bash
MESA_BASE_URL=http://127.0.0.1:18080 make health

This checks /health/init and authenticated /health with a five-second timeout

per request. It exits nonzero for missing/invalid credentials, connection errors,

invalid responses or unhealthy status. It does not open local databases, print

credentials or follow redirects. The default base URL is http://127.0.0.1:8000.

V4 canonical example (provider prerequisites)#

examples/v4_quickstart.py supplies required title/source/catalog IDs, freezes

one chunk, polls the mutation and checks source-linked evidence. It works with

the model-disabled combined environment above through BM25. For vector search

and fact extraction, set MESA_MODEL_ENABLED=true (or enable each model flag

separately), install the needed ml/adapters extras and provision reviewed

provider/model/dimension settings. Retain the same ACL and one-owner rules.

A concrete provider environment is in minimal V4 provider setup.

Follow configuration

and installation. The exact command after those prerequisites is:

bash
.venv/bin/python -m examples.v4_quickstart

The example prints assertion IDs and source/dataset/chunk references after

checking COMMITTED and provenance, then ends the session. The client's with

block closes HTTP resources; ending a session is a separate server operation.

wait_until_committed() can return failed terminal states; always check

state == "COMMITTED". A timeout does not cancel the mutation: inspect

client.status(mutation_id) before deciding what to retry.

Developer-experience verification on Linux/Python 3.11 used an isolated,

non-editable locked Core install, models-disabled startup/health checks,

and this V4 example with explicitly injected deterministic extraction/embedding.

SQLite, LanceDB, Kùzu and background processing were real. The test limited Kùzu

to a 64 MiB buffer pool, 256 MiB mapping and one query thread to fit the host's

available RAM; this is test sizing, not a production capacity result. No real

model was called. Real-provider V4 and Docker were not verified in this pass.

Restart and cleanup#

Stop this example's server with Ctrl-C and restart it with the same environment.

Query the saved session/mutation while the session is active. Do not run two

writers. End the session only after retrieval. Reads after end depend on retained

permissions; new writes require an active session. end_session can return

status=pending with a finalization_id: finalization is durable background

work, not an HTTP client close operation.

After stopping the server, retain or remove only this newly created sample root

using your file manager. No generic database/volume removal command is provided.

If the port is occupied choose another loopback port and set MESA_BASE_URL

for the example accordingly.

Python SDK#

For local scripting, rapid prototyping, and agent applications, the high-level Mesa client provides a clean interface with automatic credential discovery and catalog session handling:

python
from pathlib import Path

from mesa_client import Mesa

mesa = Mesa()
mesa.add(Path("kira.txt").read_text(), source="file://kira.txt", wait=True)
print(mesa.context("kira ne zaman ödenir?"))

Mesa() automatically discovers connection settings and API keys from environment variables (MESA_BASE_URL, MESA_API_KEY) or from <MESA_HOME or ~/.mesa>/credentials.json provisioned by mesa start. On first use, it ensures the configured workspace and dataset exist, starts a session, and reuses it for subsequent additions, searches, and context retrieval.

Waiting for documents#

Ingesting documents is durable and chunked. By default, mesa add waits until all chunks of the document's revision are committed and the revision becomes ACTIVE (printing "searchable" on completion); use --no-wait to submit without waiting. In Python, mesa.add(..., wait=True) polls the catalog revision status once per second until it becomes active or raises on failure/timeout, guaranteeing the entire document is searchable before subsequent queries execute.

Using MESA with your LLM#

When connecting an external language model to answer questions from MESA memory,

supply a system prompt that enforces untrusted data boundaries and precise source citations.

mesa_client exports RECOMMENDED_SYSTEM_PROMPT for this purpose:

python
from mesa_client import AsyncMesaV4Client, RECOMMENDED_SYSTEM_PROMPT

# System prompt for answering LLMs:
system_prompt = RECOMMENDED_SYSTEM_PROMPT

# Retrieved memory context goes into the prompt/message:
async with AsyncMesaV4Client(base_url="http://127.0.0.1:8000", api_key=api_key) as client:
    bundle = await client.get_context(session_id=session_id, query="What is the policy?")
    user_message = f"{bundle['context']}\n\nQuestion: What is the policy?"

The context returned in bundle["context"] is deterministically wrapped in

<UNTRUSTED_MEMORY_EVIDENCE>...</UNTRUSTED_MEMORY_EVIDENCE>. The prompt instructs

the model to treat everything within those tags strictly as data, never follow

instructions contained within them, cite document and revision IDs for every claim,

and decline to answer if the evidence is insufficient.