How yasou13/mesa works
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: dao.py Memory DAO · v4_router.py V4 API · loop.py Consolidation loop · ingestion_worker.py Ingestion worker
Components 23
User interfaces
- Python SDK
mesa_client/client.py - HTTP service
mesa_memory/api/server.py - MCP server
mesa_mcp/server.py - MCP V4 service
mesa_mcp/v4_service.py
API and admission
- V4 API
mesa_api/v4_router.py - Access control
mesa_memory/security/rbac.py - Runtime configuration
mesa_memory/config.py
Memory processing
- Ingestion worker
mesa_workers/ingestion_worker.py - Validation policy
mesa_memory/consolidation/policy.py - Consolidation loop
mesa_memory/consolidation/loop.py - Fact extraction
mesa_memory/extraction/service.py - Document chunking
mesa_memory/document_chunking.py - Evidence context
mesa_memory/context_builder.py - Adaptive retrieval
mesa_memory/retrieval/adaptive.py
Persistence and projections
- Memory DAO
mesa_storage/dao.py - Canonical SQLite store
mesa_storage/sqlite_engine.py - Vector projection
mesa_storage/vector_engine.py - Graph projection
mesa_storage/kuzu_provider.py - Projection worker
mesa_workers/projection_worker.py
Optional model integrations
- Embedding service
mesa_memory/embedding/service.py - LLM adapter factory
mesa_memory/adapter/factory.py
Other components
- Agent or user
- Model provider
Connections 29
- Agent or user → Python SDK: uses
README.md - Python SDK → HTTP service: calls API
README.md - Agent or user → HTTP service: submits documents
README.md - HTTP service → V4 API: routes requests
mesa_memory/api/server.py - V4 API → Access control: checks permissions
mesa_api/v4_router.py - V4 API → Memory DAO: persists mutations
mesa_api/v4_router.py - V4 API → Document chunking: uses chunking
mesa_api/v4_router.py - V4 API → Runtime configuration: reads settings
mesa_api/v4_router.py - Ingestion worker → Memory DAO: reads and updates
mesa_workers/ingestion_worker.py - Ingestion worker → Validation policy: applies policy
mesa_workers/ingestion_worker.py - Ingestion worker → Consolidation loop: delegates processing
mesa_workers/ingestion_worker.py - Consolidation loop → Fact extraction: uses extraction
mesa_memory/consolidation/loop.py - Consolidation loop → Validation policy: uses policy
mesa_memory/consolidation/loop.py - Consolidation loop → Memory DAO: persists results
mesa_memory/consolidation/loop.py - Memory DAO → Canonical SQLite store: stores canonical data
mesa_storage/dao.py - Memory DAO → Vector projection: writes projections
mesa_storage/dao.py - Memory DAO → Graph projection: writes projections
mesa_storage/dao.py - Projection worker → Memory DAO: projects data
mesa_workers/projection_worker.py - V4 API → Adaptive retrieval: routes search
mesa_api/v4_router.py - Adaptive retrieval → Memory DAO: searches memory
mesa_memory/retrieval/adaptive.py - V4 API → Evidence context: builds evidence
mesa_api/v4_router.py - Evidence context → Adaptive retrieval: retrieves evidence
mesa_memory/context_builder.py - Agent or user → MCP server: connects client
README.md - MCP server → MCP V4 service: dispatches requests
mesa_mcp/server.py - MCP V4 service → Python SDK: calls client
mesa_mcp/v4_service.py - Embedding service → Model provider: requests embeddings
mesa_memory/embedding/service.py - LLM adapter factory → Model provider: selects adapter
mesa_memory/adapter/factory.py - Consolidation loop → LLM adapter factory: optional validation models
mesa_memory/consolidation/loop.py - Memory DAO → Embedding service: optional semantic search
mesa_storage/dao.py