MESA Core · v0.9.3
Local quickstart
This guide has equivalent English and Turkish versions. The source sections behind this page are at the bottom.
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:
python3 --versionSuccess: 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.
python3 -m venv .venv
. .venv/bin/activate
python -m pip install mesa-memory==0.9.3
mesa --helpSuccess: 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:
mesa startSuccess: 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.
Add a document and search#
Open Terminal 2 in the same working directory and activate the environment:
. .venv/bin/activateCreate the UTF-8 sample document. Save its receipt in receipt.json for the next step:
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.jsonSelected receipt fields from the historical Core v0.9.0 recording are shown below. Your identifiers can differ; receipt.json contains your own complete receipt.
{
"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:
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")python wait_for_document.pySuccess: 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#
mesa search "archive"Historical Core v0.9.0 recorded CLI output (not a v0.9.3 recording):
[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:
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 statusSuccess: 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:
docker compose -f docker-compose.v4.yml exec mesa-v4 shSkip 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:
mesa mcp-configThe 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
- Advanced Operator & Production Profiles → Installation & deployment
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:
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:
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:
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:
mesa startIn another terminal, add and search documents immediately without manually exporting credentials:
mesa add notes.txt --source file://notes.txt
mesa search "notes"
mesa statusProvision 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.
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_CREATEKeep 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:
.venv/bin/python -m uvicorn mesa_memory.api.server:app --host 127.0.0.1 --port 18080Wait for readiness:
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/healthReadiness 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:
MESA_BASE_URL=http://127.0.0.1:18080 make healthThis 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:
.venv/bin/python -m examples.v4_quickstartThe 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:
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:
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.
