mesa-memory 0.9.0__tar.gz

mesa_memory-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MESA Core Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mesa_memory-0.9.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include mesa_storage/alembic.ini
+recursive-include mesa_storage/alembic *
+include mesa_memory/adapter/data/cl100k_base.tiktoken
+global-exclude *.py[cod]
+global-exclude __pycache__
+prune mesa_storage/alembic/__pycache__
+prune mesa_storage/alembic/versions/__pycache__

mesa_memory-0.9.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: mesa-memory
+Version: 0.9.0
+Summary: Enterprise AI agent memory engine
+Author: MESA Core Team
+License: MIT License
+        
+        Copyright (c) 2026 MESA Core Team
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+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
+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: 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"
+Requires-Dist: openai>=2.36.0; extra == "adapters"
+Requires-Dist: ollama>=0.6.1; 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: MIT](https://img.shields.io/github/license/Yasou13/MESA)](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.0**. 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[adapters]"
+```
+
+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 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:
+
+```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 models are enabled.
+
+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
+```
+
+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 [docs/testing.md](https://github.com/Yasou13/MESA/blob/main/docs/testing.md) for 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
+
+[MIT](https://github.com/Yasou13/MESA/blob/main/LICENSE).

mesa_memory-0.9.0/README.md

@@ -0,0 +1,123 @@
+# 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: MIT](https://img.shields.io/github/license/Yasou13/MESA)](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.0**. 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[adapters]"
+```
+
+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 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:
+
+```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 models are enabled.
+
+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
+```
+
+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 [docs/testing.md](https://github.com/Yasou13/MESA/blob/main/docs/testing.md) for 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
+
+[MIT](https://github.com/Yasou13/MESA/blob/main/LICENSE).

mesa_memory-0.9.0/mesa_api/__init__.py

@@ -0,0 +1,9 @@
+"""Versioned MESA HTTP contracts.
+
+``mesa_api.v4_router`` exposes the breaking full-cognitive catalog, immutable
+session, mutation, provenance, search, replay and rollback contract.
+"""
+
+from .v4_router import create_v4_router
+
+__all__ = ["create_v4_router"]

mesa_memory-0.9.0/mesa_api/admission.py

@@ -0,0 +1,23 @@
+"""Shared API admission policy for storage-root mutations."""
+
+from fastapi import HTTPException
+
+from mesa_storage.dao import MemoryDAO
+
+
+async def require_mutation_admission(
+    dao: MemoryDAO, *, require_projection_consumer: bool = False
+) -> None:
+    """Fail closed while a durable projection rebuild owns the storage root."""
+    if require_projection_consumer and dao.canonical_v4_writes_enabled is False:
+        raise HTTPException(
+            status_code=503,
+            detail="canonical_processing_unavailable",
+            headers={"Retry-After": "5"},
+        )
+    if await dao.rebuild_admission.is_pending():
+        raise HTTPException(
+            status_code=503,
+            detail="maintenance_pending",
+            headers={"Retry-After": "5"},
+        )

mesa_memory-0.9.0/mesa_api/identifier_validation.py

@@ -0,0 +1,67 @@
+"""Shared public identifier constraints for versioned API boundaries."""
+
+from __future__ import annotations
+
+import re
+from typing import Annotated
+
+from pydantic import AfterValidator, Field
+
+_RESERVED_SENTINELS = frozenset({"__unset__", "__system__", ""})
+_ALLOWED_IDENTIFIER_PATTERN = re.compile(r"^[a-zA-Z0-9._-]+$")
+_CONTROL_CHAR_PATTERN = re.compile(r"[\x00-\x1f\x7f]")
+
+
+def validate_public_identifier(
+    value: str,
+    field_name: str = "identifier",
+    *,
+    max_length: int = 128,
+    restricted_charset: bool = True,
+) -> str:
+    """Validate one caller-controlled public identifier.
+
+    The 128-character form covers tenant, workspace, dataset, agent, session,
+    mutation, and operation identifiers.  Source-owned document, revision, and
+    chunk identifiers retain their established 256-character boundary.
+    """
+    if _CONTROL_CHAR_PATTERN.search(value):
+        raise ValueError(
+            f"{field_name} contains illegal control characters. "
+            "Only printable ASCII characters are allowed."
+        )
+
+    stripped = value.strip()
+    if stripped in _RESERVED_SENTINELS:
+        raise ValueError(f"{field_name} cannot be empty or a reserved value")
+    if len(stripped) > max_length:
+        raise ValueError(f"{field_name} must be between 1 and {max_length} characters")
+    if restricted_charset and not _ALLOWED_IDENTIFIER_PATTERN.fullmatch(stripped):
+        raise ValueError(
+            f"{field_name} may contain only alphanumeric characters, hyphens, "
+            "underscores, or dots"
+        )
+    return stripped
+
+
+def _validate_standard_identifier(value: str) -> str:
+    return validate_public_identifier(value)
+
+
+def _validate_source_identifier(value: str) -> str:
+    # Document/revision/chunk aliases historically permit external naming
+    # punctuation.  Preserve that compatibility while enforcing the shared
+    # control-character, sentinel, and size boundaries.
+    return validate_public_identifier(value, max_length=256, restricted_charset=False)
+
+
+PublicIdentifier = Annotated[
+    str,
+    Field(min_length=1, max_length=128),
+    AfterValidator(_validate_standard_identifier),
+]
+SourceIdentifier = Annotated[
+    str,
+    Field(min_length=1, max_length=256),
+    AfterValidator(_validate_source_identifier),
+]