MESA Core · v0.9.3

MESA Core overview

v0.9.3 source: README.md

This guide has equivalent English and Turkish versions. The source sections behind this page are at the bottom.

What Core owns#

MESA Core stores durable, scoped memory with source evidence. SQLite owns canonical records; LanceDB and Kùzu provide derived search projections. Applications use the evidence to write answers.

Start locally#

Follow the local quickstart using the verified PyPI package mesa-memory==0.9.3. Run mesa start, then mesa add and mesa search. BM25 needs no model. OpenAI/Ollama are in the base package; Anthropic needs [adapters] and local ML/reranking needs [ml].

Release baseline#

These guides follow tag v0.9.3, commit 531209bc45805b478264f6dfa8a9e40a94e345cb. The changelog dates this release 16 November 2026; tag and PyPI publication were verified on 17 November. Bulk ingestion and legal parsing are faster in the reported local measurements. The default embedding identity is BGE-M3, 1024 dimensions; models remain off by default. Alpha / production NO-GO remains. See release notes and limits.

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.

![MESA CI](https://github.com/Yasou13/MESA/actions/workflows/ci.yml?query=branch%3Amain)

![Release](https://github.com/Yasou13/MESA/releases/latest)

![License: Apache 2.0](https://github.com/Yasou13/MESA/blob/main/LICENSE)

![Python: 3.11+](https://github.com/Yasou13/MESA/blob/main/pyproject.toml)

MESA is an LLM-independent, source-linked memory engine for AI applications. It stores documents with exact provenance (document, revision, passage) and returns verifiable, scoped evidence over HTTP, Python SDK, and MCP. MESA returns evidence; it never writes the final answer or hallucinates sources.

Package version: 0.9.3. V4 is the current API. Production qualification remains at the release candidate stage: NO-GO until the release gates pass.

Installation#

bash
pip install mesa-memory

Supported on Linux and macOS natively. On Windows, run via Docker or WSL.

Start the server#

bash
mesa start

Starts the local server on http://127.0.0.1:8000, initializes storage at ~/.mesa/data, and creates credentials at ~/.mesa/credentials.json (mode 0600).

Add and search documents#

In another terminal, add and search documents immediately:

bash
mesa add document.txt --source file://document.txt
mesa search "your query"

Python SDK#

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.

Connect MCP clients#

Generate a ready-to-paste configuration block for Claude Desktop or any MCP client:

bash
mesa mcp-config

Internal models (optional)#

Models stay off by default. Documents are stored and found through BM25 lexical search without any model running. FactExtractionService owns canonical V4 extraction when explicitly enabled (MESA_EXTRACTION_ENABLED=true).

Before setting MESA_MODEL_ENABLED=true, pull or download the configured embedding model (for example ollama pull bge-m3 for Ollama). To enable semantic vector search with local Ollama, add to ~/.mesa/.env:

bash
MESA_MODEL_ENABLED=true
MESA_EMBEDDING_MODEL=ollama:bge-m3
# To also enable open-ended fact extraction (defaults to false):
# MESA_EXTRACTION_ENABLED=true
# MESA_LLM_MODEL=ollama:qwen2.5:7b

Local openai_compatible servers (such as vLLM started with --port 8001, at MESA_LLM_BASE_URL=http://127.0.0.1:8001/v1; MESA itself uses port 8000) are also allowed with MESA_EXTERNAL_PROVIDER_ENABLED=false on a local endpoint (localhost, 127.0.0.1, ::1, host.docker.internal) and require no API key (D31). For cloud model providers (OpenAI, Anthropic), set MESA_EXTERNAL_PROVIDER_ENABLED=true and provide the required API keys.

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.

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 variables are required; models and external providers default off. If you set MESA_API_KEY and MESA_PRINCIPAL_ID for existing HTTP clients, the server accepts that key too, and the mesa commands inside the container use it first; add -e MESA_API_KEY= after exec to use the local credentials instead. The image includes adapters; build with --build-arg MESA_EXTRAS=ml,adapters to add local sentence-transformers. Ollama defaults to http://host.docker.internal:11434 (the Docker host).

Google Colab#

Run MESA with GPU-accelerated Ollama in Colab:

Colab Quickstart

Development#

bash
uv sync --locked --python 3.11

See testing for local tests and test markers.

Documentation#

License#

MESA is licensed under the Apache License, Version 2.0. See NOTICE for copyright information.