MESA Core · v0.9.3

Google Colab hızlı başlangıç

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.

v0.9.3 Colab not defteri#

Güncel sürüm, Google Colab üzerinde GPU destekli Ollama denemeleri için examples/colab_quickstart.ipynb içerir. Sürüme sabitlenmiş not defterini açın; çalıştırmadan önce kurulum ve indirmeleri inceleyin.

Yerel çalışma veya not defteri seçin#

Model indirmeden ilk deneme için yerel hızlı başlangıcı kullanın: mesa start, mesa add ve BM25 araması. Colab’ın geçici depolaması, GPU kullanılabilirliği ve model kurulumu, yerel kalıcılık ve üretim yeterliliğinden ayrıdır. Not defterindeki sonuç üretim sertifikası değildir.

Dayanak kaynaklar
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.

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