MESA Core · v0.9.3
Kurulum ve dağıtım
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:
pip install mesa-memory==0.9.3
mesa startCLI; 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:
git clone --branch v0.9.3 --depth 1 https://github.com/Yasou13/MESA.git
cd MESA
uv sync --locked --python 3.11
uv pip checkYerel Docker çalıştırın#
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:
pip install mesa-memory==0.9.3
pip install --upgrade mesa-memory==0.9.3OpenAI 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:
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
Üç 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:
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:
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:
uv sync --locked --python 3.11
uv pip checkpyproject.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.
| Extra | When needed |
|---|---|
dev | Local checks and development |
adapters | Provider SDK integrations |
ml | Local transformer/embedding dependencies |
loadtest | Explicit load-test work |
mcp | Compatibility extra; MCP itself is already a core dependency |
For a provider setup that needs both SDKs and local models:
uv sync --locked --python 3.11 --extra adapters --extra ml
uv pip checkInstall only the extras needed by the selected runtime. Model downloads,
credentials and operational provider endpoints are separate prerequisites.
Choose topology and storage#
| Use | Profile / Compose file | Storage rule |
|---|---|---|
| Canonical V4 | combined / docker-compose.v4.yml | One process owns API, consumers and stores |
| Local model-disabled startup | combined, models/providers false | V4 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:
- Select a new or compatible V4 storage root and provision credentials/ACL using
- 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.
- Select validation mode. Mode 0 has no LLM validator but still needs canonical
extraction and embeddings; mode 2 requires distinct A/B validator identities.
- 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):
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_entrypointThe 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:
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 psFor V3 lexical compatibility:
docker compose config --quiet
docker compose up --build -dCompose 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.
