Metadata-Version: 2.4
Name: mesa-memory
Version: 0.9.3
Summary: Enterprise AI agent memory engine
Author: MESA Core Team
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Yasou13/MESA
Project-URL: Repository, https://github.com/Yasou13/MESA
Project-URL: Documentation, https://github.com/Yasou13/MESA/tree/main/docs
Project-URL: Changelog, https://github.com/Yasou13/MESA/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Yasou13/MESA/issues
Keywords: ai,memory,agents,knowledge-graph,llm,cognitive
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: aiosqlite>=0.22.0
Requires-Dist: anyio>=4.0.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: mcp<2.0.0,>=1.30.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: uvicorn>=0.29.0
Requires-Dist: fastapi>=0.139.0
Requires-Dist: starlette>=1.3.1
Requires-Dist: slowapi>=0.1.9
Requires-Dist: prometheus_client>=0.20.0
Requires-Dist: openai>=2.36.0
Requires-Dist: ollama>=0.6.1
Requires-Dist: pydantic>=2.13.0
Requires-Dist: pydantic-settings>=2.14.0
Requires-Dist: lancedb>=0.30.0
Requires-Dist: pyarrow>=24.0.0
Requires-Dist: kuzu>=0.0.11
Requires-Dist: numpy>=2.2.0
Requires-Dist: tenacity>=9.0.0
Requires-Dist: psutil>=7.0.0
Requires-Dist: structlog>=24.0.0
Requires-Dist: python-dotenv>=1.2.0
Requires-Dist: tiktoken>=0.12.0
Requires-Dist: alembic>=1.13.0
Requires-Dist: sqlalchemy>=2.0.51
Requires-Dist: typing_extensions>=4.16.0
Provides-Extra: adapters
Requires-Dist: anthropic>=0.100.0; extra == "adapters"
Provides-Extra: ml
Requires-Dist: torch>=2.11.0; extra == "ml"
Requires-Dist: transformers>=5.8.0; extra == "ml"
Requires-Dist: tokenizers>=0.22.0; extra == "ml"
Requires-Dist: safetensors>=0.7.0; extra == "ml"
Requires-Dist: huggingface_hub>=1.14.0; extra == "ml"
Requires-Dist: sentence-transformers>=3.0.0; extra == "ml"
Provides-Extra: loadtest
Requires-Dist: aiohttp>=3.14.3; extra == "loadtest"
Requires-Dist: locust>=2.29.0; extra == "loadtest"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: cyclonedx-bom>=5.1.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: datasets>=2.14.0; extra == "dev"
Requires-Dist: PyYAML>=6.0.0; extra == "dev"
Dynamic: license-file

# MESA — Memory Engine for Structured Agents

[![MESA CI](https://github.com/Yasou13/MESA/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Yasou13/MESA/actions/workflows/ci.yml?query=branch%3Amain)
[![Release](https://img.shields.io/github/v/release/Yasou13/MESA)](https://github.com/Yasou13/MESA/releases/latest)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)](https://github.com/Yasou13/MESA/blob/main/LICENSE)
[![Python: 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](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](https://github.com/Yasou13/MESA/blob/main/docs/release.md) 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](https://github.com/Yasou13/MESA/blob/main/examples/colab_quickstart.ipynb)

## Development

```bash
uv sync --locked --python 3.11
```

See [testing](https://github.com/Yasou13/MESA/blob/main/docs/testing.md) for local tests and test markers.

## Documentation

- [Getting Started Guide](https://github.com/Yasou13/MESA/blob/main/docs/getting-started.md)
- [Configuration Reference](https://github.com/Yasou13/MESA/blob/main/docs/configuration.md)
- [API Reference](https://github.com/Yasou13/MESA/blob/main/docs/api-reference.md)
- [MCP Integration Guide](https://github.com/Yasou13/MESA/blob/main/README_MCP.md)
- [Architecture](https://github.com/Yasou13/MESA/blob/main/ARCHITECTURE.md)
- [Documentation Index](https://github.com/Yasou13/MESA/blob/main/docs/README.md)

## License

MESA is licensed under the [Apache License, Version 2.0](https://github.com/Yasou13/MESA/blob/main/LICENSE). See [NOTICE](https://github.com/Yasou13/MESA/blob/main/NOTICE) for copyright information.
