MESA — Memory Engine for Structured Agents

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.2. V4 is the current API. Production qualification remains at the release candidate stage: NO-GO until the release gates pass.

Installation

pip install mesa-memory

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

Start the server

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:

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

Python SDK

from mesa_client import Mesa

mesa = Mesa()
mesa.add(open("document.txt").read(), source="file://document.txt")
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-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).

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: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:

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):

docker compose -f docker-compose.v4.yml up --build -d

Credentials 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: Colab Quickstart

Development

uv sync --locked --python 3.11

See testing for local tests, and docs/testing.md for 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.