MESA Core · v0.9.3

Kurulum ve dağıtım

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

Bu rehberin Türkçe ve İngilizce sürümleri aynı konuyu açıklar. Bu sayfayla ilgili kaynak bölümleri en altta yer alır.

Yayımlanmış paketi kurun#

Test matrisi Python 3.11–3.13’tür. Linux/macOS üzerinde doğrudan; Windows üzerinde Docker veya WSL ile çalışır. Rehberlerle aynı sürümü kurun:

bash
pip install mesa-memory==0.9.3
mesa start

CLI; yerel kataloğu, yetkileri, depolamayı ve kimlik bilgilerini hazırlar. Modeller varsayılan olarak kapalıdır; belgeler alınabilir ve BM25 ile aranabilir. İsteğe bağlı adapters ve ml ekleri seçilen model sağlayıcılarını destekler. Ayrı veritabanı sunucusu gerekmez.

Sabitlenmiş kaynak kodunu kullanın#

Geliştirme için sürümün Git nesnesini ve kilit dosyasını kullanın:

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

Yerel Docker çalıştırın#

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"

Compose komutlarını sabitlenmiş kaynak klasöründen, kendi document.txt dosyanız hazırken çalıştırın. Konteyner mesa start çalıştırır, içeride 0.0.0.0 adresine bağlanır ve yalnızca ana makinenin loopback adresinde yayımlanır. Volume, verileri ve /var/lib/mesa/credentials.json kimlik dosyasını korur. Her depolama kökünün tek bir combined yazma sahibi vardır. Hazır olma ve yerel başlangıç üretim yeterliliği sağlamaz.

Paket indeksi ve isteğe bağlı ekler#

17 Kasım 2026’da GitHub v0.9.3 etiketi ve PyPI 0.9.3 yayını doğrulandı. Wheel ve sdist mevcut ve geri çekilmemiştir. Temel kurulum ve yükseltme:

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

OpenAI ve Ollama SDK’ları temel pakete dahildir. Anthropic için [adapters]; yerel embedding ve BGE yeniden sıralama için [ml] gerekir. Seçtiğiniz sağlayıcının gerektirdiği ekleri kurun:

bash
pip install "mesa-memory[adapters]==0.9.3"
pip install "mesa-memory[ml]==0.9.3"

Yayın, Alfa / üretim NO-GO durumunu değiştirmez.

Şemalar

UML · Dağıtım şemasıTek süreç, tek depolama kökü, isteğe bağlı model sağlayıcılar
«device»Sunucu · VM veya Docker Compose servisi «execution environment»Python 3.11–3.13 · uvicorn «artifact»mesa · birleşik çalışmaAPI + işçiler + MemoryDAO {replicas = 1} «volume»MESA_STORAGE_ROOT «artifact»SQLite«artifact»LanceDB«artifact»Kùzu sahip «device»İstemci uygulama · ajan · SDK HTTP APIX-API-Key «external»Model sağlayıcıları yalnız model açıksa çıkarım · doğrulama · embedding «device»Yedek hedefi çevrimdışı İki süreci aynı depolamaköküne bağlamayın.Kabulü ölçekleyin, yazıcıyı değil.

Üç depo tek kök altındaki gömülü dosyalardır; birlikte yedeklenir ve geri yüklenir. Modeller kapalı combined çalışma belgeleri kabul eder ve BM25 araması sunar. Hukuk kuralları model istemez; açık uçlu SPO çıkarımı ayrıca açılır.

Tüm şemalar ve gerekçeleri: Mimari →

Kaynak belgedeki ilgili bölümler

Bu bölüm, kaynak belgenin bu sayfayla ilgili kısımlarını değiştirmeden gösterir. Kaynak içindeki bir bölüme giden bağlantıyı açtığınızda metin otomatik olarak görünür.

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.