MESA Core · v0.9.3

Google Colab quickstart

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.

Colab notebook in v0.9.3#

The current release includes examples/colab_quickstart.ipynb for GPU-backed Ollama experimentation in Google Colab. Open the version-pinned notebook and review its setup and downloads before running it.

Choose local or notebook operation#

For a first run without model downloads, use the local quickstart: mesa start, mesa add and BM25 search. Colab’s temporary storage, GPU availability and notebook model setup are separate from local persistence and production qualification. A notebook result is not a production certificate.

Verified sources
Source reference for this page

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

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