MESA Core · v0.9.3

Yerel hızlı başlangıç

Ön koşulları kontrol edin#

Bu rehber bir yerel denemedir. Metin belgesi ekleyip kaynaklı arama sonucu alacaksınız; model hesabı gerekmez. MESA son yanıtı yazmaz. Terminal, komut yazdığınız uygulamadır; Linux’ta Terminal’i, macOS’ta Terminal uygulamasını açın.

Linux ve macOS#

Python 3.11–3.13 ve pip gerekir. Önce sürümü kontrol edin:

bash
python3 --version

Başarı ölçütü: çıktı Python 3.11, 3.12 veya 3.13 ile başlamalıdır. Python yoksa veya sürüm farklıysa resmî Python indirme sayfasını kullanın. Linux’ta venv bileşeni eksikse dağıtımınızın Python venv paketini kurun.

Windows: WSL#

Windows’un yerel PowerShell penceresinde mesa start çalışmaz. Microsoft’un WSL kurulum rehberini izleyip Linux terminali açın; aşağıdaki Linux komutlarını o terminalde uygulayın. Python sürümünü WSL içinde kontrol edin.

Docker yolu#

Python kurulumunu kullanmayacaksanız Docker kurulumunu tamamlayıp Docker ile kurulum bölümüne geçin.

v0.9.3 sürümünü kurun#

Yeni bir çalışma klasöründe bu komutları çalıştırın. Sanal ortam, MESA paketlerini diğer Python projelerinizden ayırır.

v0.9.3 paketi PyPI’da yayımlandı; komut doğrulanan bu sürümü sabitler. Kurulum ve eklere bakın.

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

Başarı ölçütü: yardım çıktısında start, add, search ve status komutları görünür. mesa: command not found hatasında doğru klasörde . .venv/bin/activate çalıştırın.

Yerel sunucuyu başlatın#

Terminal 1’de:

bash
mesa start

Başarı ölçütü: sunucu http://127.0.0.1:8000 adresinde başlar ve Application startup complete kaydı görünür. Bu pencereyi açık bırakın. Yerel depolama ~/.mesa/data, özel kimlik bilgileri ~/.mesa/credentials.json içindedir.

Modeller ve dış sağlayıcılar varsayılan olarak kapalıdır; mevcut .env ayarlarınız bu varsayılanı değiştirebilir. Bu rehber sözcük araması içindir.

Bir belge ekleyip arayın#

Terminal 2’yi aynı çalışma klasöründe açıp sanal ortamı etkinleştirin:

bash
. .venv/bin/activate

UTF-8 örnek belgeyi oluşturun. Alındıyı bir sonraki adım için receipt.json dosyasına kaydedin:

bash
printf '%s\n' 'Atlas arşivi hafta içi 09:00 saatinde açılır.' > archive-tr.txt
mesa add archive-tr.txt --source file://archive-tr.txt --json > receipt.json
cat receipt.json

Tarihsel Core v0.9.0 çalıştırmasından seçilmiş alındı alanları aşağıdadır. Kimlikler sizin çalıştırmanızda farklı olabilir; receipt.json kendi tam alındınızı içerir.

json
{
  "document_id": "doc-d206865140f38f4fcadb22c4645c222f",
  "revision_number": 1,
  "chunk_count": 1,
  "mutation_ids": [
    "a7e6110e-5e6f-55f5-88ee-0ad1fd9086ee"
  ]
}

Başarı ölçütü: alındıda document_id, chunk_count ve mutation_ids bulunur. mesa add artık başarılı dönüşten önce ACTIVE sürümü bekler. --no-wait ile alındı yalnız kabulü gösterir.

İşlemenin tamamlandığını doğrulayın#

Aşağıdaki kodu wait_for_document.py adlı dosyaya kaydedin. Yerel kimlik bilgilerini otomatik okur ve her mutasyonun son durumunu kontrol eder:

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

Başarı ölçütü: her satırın sonunda COMMITTED görünür. Başka bir son durumda betik hata ile durur; belgeyi başarılı işlenmiş kabul etmeyin. Zaman aşımında sunucunun açık olduğunu kontrol edip aynı betiği yeniden çalıştırın. Durum API’si ayrıntıları gösterir.

mesa status, sunucunun hazır ve sağlıklı olup olmadığını gösterir; belge mutasyonlarının tamamlandığını göstermez.

İlk arama sonucunu görün#

bash
mesa search "arşivi"

Tarihsel Core v0.9.0 kaydından gerçek CLI çıktısı (v0.9.3 ile yeniden kaydedilmedi):

text
[1] score: 0.033 | doc-d206865140f38f4fcadb22c4645c222f
    Atlas arşivi hafta içi 09:00 saatinde açılır.

Başarı ölçütü: sonuçta belgenizdeki 09:00 metni ve belge kimliği görünür. Kimlik ve skor değişebilir; skor doğruluk olasılığı değildir. Kaynak ve sürüm alanlarını ana sayfadaki gerçek kayıt örneğinde görebilirsiniz.

Sonuç boşsa: önce tamamlanma betiğini çalıştırın; sonra belgedeki sözcüğü aynen arayın. Bağlantı hatasında: Terminal 1’in açık ve mesa status çıktısının sağlıklı olduğunu kontrol edin. Port kullanımda ise: başka bir MESA örneği olup olmadığını kontrol edin; bu rehber mevcut depolamayı silmenizi gerektirmez.

Docker ile kurulum#

Bu yol için Git, Docker Engine/Desktop ve Compose gerekir. Sabitlenmiş kaynak sürümünü açın:

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

Başarı ölçütü: durum çıktısı ready ve healthy gösterir. Compose, 8000 portunu yalnızca ana makinenin loopback adresinde yayımlar; volume veriyi ve kimlik bilgilerini korur.

Belge ekleme, tamamlanma kontrolü ve arama adımlarını konteyner içinde uygulayın. Kabuk açmak için:

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

Konteyner kabuğunda sanal ortam etkinleştirme adımını atlayın; örnek dosyayı oluşturup yukarıdaki mesa add ve Python tamamlanma betiğini kullanın. Komut bitince exit ile çıkın. Yerel makinedeki mesa komutu konteyner kimlik bilgilerini kendiliğinden kullanmaz. Dağıtım rehberi ayrıntıları açıklar.

Python kullanın veya MCP istemcisi bağlayın#

İlk aramanız başarılı olduktan sonra Python SDK örneklerine veya MCP rehberine geçin. MCP ayarını üretmek için:

bash
mesa mcp-config

Çıktı yerel API anahtarını içerir; paylaşmayın. MESA bağlam metnini döndürür, son yanıtı uygulamanız ve onun modeli üretir.

İsteğe bağlı modelleri ve çizgeyi açın#

Bu ilk arama için gerekli değildir. Anlamsal arama ve bilgi çıkarımı için model yapılandırmasını ve sağlayıcıları inceleyin. Dış sağlayıcılar veri aktarımı ve kullanım ücreti doğurabilir. Grafik/embedding yeniden açıldığında atlanan işler başlangıçta tamamlanabilir. Yerel başarı üretim yeterliliği sağlamaz; canlı kullanım doğrulamaları tamamlanmadı.

İleri seçenekler: modeller ve çizge

v0.9.3 bekleme davranışı#

mesa add, başarılı dönüşten önce ACTIVE belge sürümünü bekler. --no-wait yalnız kabul alındısını döndürür. Yukarıdaki alındı ve CLI çıktıları tarihsel Core v0.9.0 kaydından alınmıştır; v0.9.3 ile yeniden kaydedilmedi. Ek durum kontrolü isteğe bağlı doğrulama olarak kullanılabilir.

Kaynak ve sürüm
v0.9.3 kaynak: docs/getting-started.md
Kendi sayfasına taşınan bölümler
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.

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.