# yasou13/mesa architecture

> Architecture diagram of the GitHub repository yasou13/mesa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yasou13/mesa
- Repository: https://github.com/yasou13/mesa

## Overview

MESA is an LLM-independent memory engine that accepts documents, preserves document/revision/passage provenance, and returns scoped evidence through HTTP, the Python SDK, or MCP. The main workflow is admission, durable ingestion and validation, canonical storage with derived projections, then scoped retrieval and evidence delivery. Optional model-backed embedding, extraction, and graph capabilities complement lexical search. The graph uses README statements and SOURCE INDEX references for relationships; unsampled implementation details are not assumed.

Main entry points: [`mesa_storage/dao.py`](https://github.com/yasou13/mesa/blob/main/mesa_storage/dao.py) (Memory DAO), [`mesa_api/v4_router.py`](https://github.com/yasou13/mesa/blob/main/mesa_api/v4_router.py) (V4 API), [`mesa_memory/consolidation/loop.py`](https://github.com/yasou13/mesa/blob/main/mesa_memory/consolidation/loop.py) (Consolidation loop), [`mesa_workers/ingestion_worker.py`](https://github.com/yasou13/mesa/blob/main/mesa_workers/ingestion_worker.py) (Ingestion worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_sdk["Python SDK<br/>[client.py]"]
  node_http["HTTP service<br/>[server.py]"]
  node_mcp["MCP server<br/>[server.py]"]
  node_mcp_v4["MCP V4 service<br/>[v4_service.py]"]
end

subgraph group_admission["API and admission"]
  node_v4["V4 API<br/>[v4_router.py]"]
  node_auth["Access control<br/>[rbac.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_memory["Memory processing"]
  node_ingestion["Ingestion worker"]
  node_validation["Validation policy<br/>[policy.py]"]
  node_consolidation["Consolidation loop<br/>[loop.py]"]
  node_extraction["Fact extraction<br/>[service.py]"]
  node_chunking["Document chunking"]
  node_context["Evidence context<br/>[context_builder.py]"]
  node_retrieval["Adaptive retrieval<br/>[adaptive.py]"]
end

subgraph group_persistence["Persistence and projections"]
  node_dao["Memory DAO<br/>[dao.py]"]
  node_sqlite[("Canonical SQLite store<br/>[sqlite_engine.py]")]
  node_vectors[("Vector projection<br/>[vector_engine.py]")]
  node_graph[("Graph projection<br/>[kuzu_provider.py]")]
  node_projection_worker["Projection worker"]
end

subgraph group_integrations["Optional model integrations"]
  node_embedding["Embedding service<br/>[service.py]"]
  node_adapter_factory["LLM adapter factory<br/>[factory.py]"]
end

node_user(("Agent or user"))
node_provider["Model provider"]

node_user -->|"uses"| node_sdk
node_sdk -->|"calls API"| node_http
node_user -->|"submits documents"| node_http
node_http -->|"routes requests"| node_v4
node_v4 -->|"checks permissions"| node_auth
node_v4 -->|"persists mutations"| node_dao
node_v4 -->|"uses chunking"| node_chunking
node_v4 -->|"reads settings"| node_config
node_ingestion -->|"reads and updates"| node_dao
node_ingestion -->|"applies policy"| node_validation
node_ingestion -->|"delegates processing"| node_consolidation
node_consolidation -->|"uses extraction"| node_extraction
node_consolidation -->|"uses policy"| node_validation
node_consolidation -->|"persists results"| node_dao
node_dao -->|"stores canonical data"| node_sqlite
node_dao -->|"writes projections"| node_vectors
node_dao -->|"writes projections"| node_graph
node_projection_worker -->|"projects data"| node_dao
node_v4 -->|"routes search"| node_retrieval
node_retrieval -->|"searches memory"| node_dao
node_v4 -->|"builds evidence"| node_context
node_context -->|"retrieves evidence"| node_retrieval
node_user -->|"connects client"| node_mcp
node_mcp -->|"dispatches requests"| node_mcp_v4
node_mcp_v4 -->|"calls client"| node_sdk
node_embedding -.->|"requests embeddings"| node_provider
node_adapter_factory -.->|"selects adapter"| node_provider
node_consolidation -.->|"optional validation models"| node_adapter_factory
node_dao -.->|"optional semantic search"| node_embedding

click node_sdk "https://github.com/yasou13/mesa/blob/main/mesa_client/client.py"
click node_http "https://github.com/yasou13/mesa/blob/main/mesa_memory/api/server.py"
click node_mcp "https://github.com/yasou13/mesa/blob/main/mesa_mcp/server.py"
click node_mcp_v4 "https://github.com/yasou13/mesa/blob/main/mesa_mcp/v4_service.py"
click node_v4 "https://github.com/yasou13/mesa/blob/main/mesa_api/v4_router.py"
click node_auth "https://github.com/yasou13/mesa/blob/main/mesa_memory/security/rbac.py"
click node_config "https://github.com/yasou13/mesa/blob/main/mesa_memory/config.py"
click node_ingestion "https://github.com/yasou13/mesa/blob/main/mesa_workers/ingestion_worker.py"
click node_validation "https://github.com/yasou13/mesa/blob/main/mesa_memory/consolidation/policy.py"
click node_consolidation "https://github.com/yasou13/mesa/blob/main/mesa_memory/consolidation/loop.py"
click node_extraction "https://github.com/yasou13/mesa/blob/main/mesa_memory/extraction/service.py"
click node_chunking "https://github.com/yasou13/mesa/blob/main/mesa_memory/document_chunking.py"
click node_context "https://github.com/yasou13/mesa/blob/main/mesa_memory/context_builder.py"
click node_retrieval "https://github.com/yasou13/mesa/blob/main/mesa_memory/retrieval/adaptive.py"
click node_dao "https://github.com/yasou13/mesa/blob/main/mesa_storage/dao.py"
click node_sqlite "https://github.com/yasou13/mesa/blob/main/mesa_storage/sqlite_engine.py"
click node_vectors "https://github.com/yasou13/mesa/blob/main/mesa_storage/vector_engine.py"
click node_graph "https://github.com/yasou13/mesa/blob/main/mesa_storage/kuzu_provider.py"
click node_projection_worker "https://github.com/yasou13/mesa/blob/main/mesa_workers/projection_worker.py"
click node_embedding "https://github.com/yasou13/mesa/blob/main/mesa_memory/embedding/service.py"
click node_adapter_factory "https://github.com/yasou13/mesa/blob/main/mesa_memory/adapter/factory.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk,node_http,node_mcp,node_mcp_v4,node_user toneBlue
class node_v4,node_auth,node_config toneAmber
class node_ingestion,node_validation,node_consolidation,node_extraction,node_chunking,node_context,node_retrieval toneMint
class node_dao,node_sqlite,node_vectors,node_graph,node_projection_worker toneRose
class node_embedding,node_adapter_factory,node_provider toneIndigo
```

## Components

### User interfaces

- [Python SDK](https://github.com/yasou13/mesa/blob/main/mesa_client/client.py): `mesa_client/client.py`
- [HTTP service](https://github.com/yasou13/mesa/blob/main/mesa_memory/api/server.py): `mesa_memory/api/server.py`
- [MCP server](https://github.com/yasou13/mesa/blob/main/mesa_mcp/server.py): `mesa_mcp/server.py`
- [MCP V4 service](https://github.com/yasou13/mesa/blob/main/mesa_mcp/v4_service.py): `mesa_mcp/v4_service.py`

### API and admission

- [V4 API](https://github.com/yasou13/mesa/blob/main/mesa_api/v4_router.py): `mesa_api/v4_router.py`
- [Access control](https://github.com/yasou13/mesa/blob/main/mesa_memory/security/rbac.py): `mesa_memory/security/rbac.py`
- [Runtime configuration](https://github.com/yasou13/mesa/blob/main/mesa_memory/config.py): `mesa_memory/config.py`

### Memory processing

- [Ingestion worker](https://github.com/yasou13/mesa/blob/main/mesa_workers/ingestion_worker.py): `mesa_workers/ingestion_worker.py`
- [Validation policy](https://github.com/yasou13/mesa/blob/main/mesa_memory/consolidation/policy.py): `mesa_memory/consolidation/policy.py`
- [Consolidation loop](https://github.com/yasou13/mesa/blob/main/mesa_memory/consolidation/loop.py): `mesa_memory/consolidation/loop.py`
- [Fact extraction](https://github.com/yasou13/mesa/blob/main/mesa_memory/extraction/service.py): `mesa_memory/extraction/service.py`
- [Document chunking](https://github.com/yasou13/mesa/blob/main/mesa_memory/document_chunking.py): `mesa_memory/document_chunking.py`
- [Evidence context](https://github.com/yasou13/mesa/blob/main/mesa_memory/context_builder.py): `mesa_memory/context_builder.py`
- [Adaptive retrieval](https://github.com/yasou13/mesa/blob/main/mesa_memory/retrieval/adaptive.py): `mesa_memory/retrieval/adaptive.py`

### Persistence and projections

- [Memory DAO](https://github.com/yasou13/mesa/blob/main/mesa_storage/dao.py): `mesa_storage/dao.py`
- [Canonical SQLite store](https://github.com/yasou13/mesa/blob/main/mesa_storage/sqlite_engine.py): `mesa_storage/sqlite_engine.py`
- [Vector projection](https://github.com/yasou13/mesa/blob/main/mesa_storage/vector_engine.py): `mesa_storage/vector_engine.py`
- [Graph projection](https://github.com/yasou13/mesa/blob/main/mesa_storage/kuzu_provider.py): `mesa_storage/kuzu_provider.py`
- [Projection worker](https://github.com/yasou13/mesa/blob/main/mesa_workers/projection_worker.py): `mesa_workers/projection_worker.py`

### Optional model integrations

- [Embedding service](https://github.com/yasou13/mesa/blob/main/mesa_memory/embedding/service.py): `mesa_memory/embedding/service.py`
- [LLM adapter factory](https://github.com/yasou13/mesa/blob/main/mesa_memory/adapter/factory.py): `mesa_memory/adapter/factory.py`

### Other components

- **Agent or user**
- **Model provider**

## Connections

- Agent or user → Python SDK: uses (evidence: `README.md`)
- Python SDK → HTTP service: calls API (evidence: `README.md`)
- Agent or user → HTTP service: submits documents (evidence: `README.md`)
- HTTP service → V4 API: routes requests (evidence: `mesa_memory/api/server.py`)
- V4 API → Access control: checks permissions (evidence: `mesa_api/v4_router.py`)
- V4 API → Memory DAO: persists mutations (evidence: `mesa_api/v4_router.py`)
- V4 API → Document chunking: uses chunking (evidence: `mesa_api/v4_router.py`)
- V4 API → Runtime configuration: reads settings (evidence: `mesa_api/v4_router.py`)
- Ingestion worker → Memory DAO: reads and updates (evidence: `mesa_workers/ingestion_worker.py`)
- Ingestion worker → Validation policy: applies policy (evidence: `mesa_workers/ingestion_worker.py`)
- Ingestion worker → Consolidation loop: delegates processing (evidence: `mesa_workers/ingestion_worker.py`)
- Consolidation loop → Fact extraction: uses extraction (evidence: `mesa_memory/consolidation/loop.py`)
- Consolidation loop → Validation policy: uses policy (evidence: `mesa_memory/consolidation/loop.py`)
- Consolidation loop → Memory DAO: persists results (evidence: `mesa_memory/consolidation/loop.py`)
- Memory DAO → Canonical SQLite store: stores canonical data (evidence: `mesa_storage/dao.py`)
- Memory DAO → Vector projection: writes projections (evidence: `mesa_storage/dao.py`)
- Memory DAO → Graph projection: writes projections (evidence: `mesa_storage/dao.py`)
- Projection worker → Memory DAO: projects data (evidence: `mesa_workers/projection_worker.py`)
- V4 API → Adaptive retrieval: routes search (evidence: `mesa_api/v4_router.py`)
- Adaptive retrieval → Memory DAO: searches memory (evidence: `mesa_memory/retrieval/adaptive.py`)
- V4 API → Evidence context: builds evidence (evidence: `mesa_api/v4_router.py`)
- Evidence context → Adaptive retrieval: retrieves evidence (evidence: `mesa_memory/context_builder.py`)
- Agent or user → MCP server: connects client (evidence: `README.md`)
- MCP server → MCP V4 service: dispatches requests (evidence: `mesa_mcp/server.py`)
- MCP V4 service → Python SDK: calls client (evidence: `mesa_mcp/v4_service.py`)
- Embedding service → Model provider: requests embeddings (evidence: `mesa_memory/embedding/service.py`)
- LLM adapter factory → Model provider: selects adapter (evidence: `mesa_memory/adapter/factory.py`)
- Consolidation loop → LLM adapter factory: optional validation models (evidence: `mesa_memory/consolidation/loop.py`)
- Memory DAO → Embedding service: optional semantic search (evidence: `mesa_storage/dao.py`)