MESA Core · v0.9.3
MESA Core overview
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.
Source reference for this page
The sections of the upstream file that back this page, unchanged. Source section links open the appendix automatically.




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#
pip install mesa-memorySupported on Linux and macOS natively. On Windows, run via Docker or WSL.
Start the server#
mesa startStarts 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:
mesa add document.txt --source file://document.txt
mesa search "your query"Python SDK#
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:
mesa mcp-configInternal 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:
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:7bLocal 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:
MESA_GRAPH_ENABLED=falseGRAPH 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):
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 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:
Development#
uv sync --locked --python 3.11See testing for local tests and test markers.
Documentation#
- Getting Started Guide
- Configuration Reference
- API Reference
- MCP Integration Guide
- Architecture
- Documentation Index
License#
MESA is licensed under the Apache License, Version 2.0. See NOTICE for copyright information.
