# zbalint/saltmdb architecture

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

- Interactive diagram: https://gitdiagram.com/zbalint/saltmdb
- Repository: https://github.com/zbalint/saltmdb

## Overview

SALTMDB is a local-first, shared memory service for AI agents. Agents invoke MCP tools through thin per-agent adapters; those adapters connect by RPC to the single-owner daemon, which dispatches memory operations and owns SQLite. The domain workflow covers guarded/redacted writes and duplicate checks, asynchronous embedding, hybrid retrieval and reranking, and relation-based context expansion or consolidation. Other documented capabilities include events and governance, canonical tags, lineage, and a database viewer. The README documents several behaviors whose implementation was not sampled, so uncertain internal wiring is omitted.

Main entry points: [`src/saltmdb/db/connection.py`](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/db/connection.py) (SQLite Memory Store), [`src/saltmdb/daemon/server.py`](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/daemon/server.py) (Backend Daemon), [`src/saltmdb/domain/services/memory_service/orchestrator.py`](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/memory_service/orchestrator.py) (Memory Operations), [`src/saltmdb/daemon/dispatch.py`](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/daemon/dispatch.py) (Tool Dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Agent Interfaces"]
  node_mcp["MCP Server<br/>[server.py]"]
  node_tools["MCP Tools<br/>[tools.py]"]
  node_rpc_client["Daemon Client<br/>[client.py]"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_backend["Daemon Backend"]
  node_daemon["Backend Daemon<br/>[server.py]"]
  node_dispatch["Tool Dispatch<br/>[dispatch.py]"]
  node_coordinator["Write Coordinator"]
end

subgraph group_memory["Memory Domain"]
  node_memory["Memory Operations<br/>[orchestrator.py]"]
  node_quality["Write Quality and Duplicates<br/>[validation.py]"]
  node_relations["Relations and Lineage"]
  node_context["Context Expansion"]
  node_embedding["Embedding Jobs"]
  node_reranker["Cross-Encoder Reranker"]
end

subgraph group_state["Persistence and Search"]
  node_sqlite[("SQLite Memory Store<br/>[connection.py]")]
  node_search["Search Primitives"]
end

subgraph group_ops["Viewing and Governance"]
  node_librarian["Librarian Maintenance"]
  node_events["Event and Governance Services<br/>[event_service.py]"]
  node_viewer["Database Viewer<br/>[routes.py]"]
end

node_agents(("AI Agents"))
node_embedding_runtime["ONNX Embedding Runtime"]
node_browser(("Browser User"))

node_agents -->|"invoke MCP"| node_mcp
node_mcp -->|"register tools"| node_tools
node_tools -->|"send tool RPC"| node_rpc_client
node_rpc_client -->|"connect and call"| node_daemon
node_cli -->|"call daemon"| node_rpc_client
node_daemon -->|"dispatch tools"| node_dispatch
node_dispatch -->|"invoke operations"| node_memory
node_dispatch -->|"invoke relations"| node_relations
node_dispatch -->|"invoke event tools"| node_events
node_memory -->|"validate writes"| node_quality
node_memory -->|"build search results"| node_search
node_memory -.->|"rerank candidates"| node_reranker
node_memory -->|"expand context"| node_context
node_relations -->|"read and write"| node_sqlite
node_memory -->|"read and write"| node_sqlite
node_quality -->|"check duplicates"| node_sqlite
node_embedding -->|"persist vectors"| node_sqlite
node_embedding -->|"generate vectors"| node_embedding_runtime
node_daemon -->|"coordinate writes"| node_coordinator
node_coordinator -->|"serialize writes"| node_sqlite
node_daemon -->|"run embedding jobs"| node_embedding
node_daemon -->|"trigger maintenance"| node_librarian
node_librarian -->|"read and update"| node_sqlite
node_events -->|"append and read"| node_sqlite
node_daemon -->|"serve in process"| node_viewer
node_viewer -->|"query records"| node_sqlite
node_browser -->|"browse records"| node_viewer

click node_mcp "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/mcp/server.py"
click node_tools "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/mcp/tools.py"
click node_rpc_client "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/daemon/client.py"
click node_cli "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/cli.py"
click node_daemon "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/daemon/server.py"
click node_dispatch "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/daemon/dispatch.py"
click node_coordinator "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/daemon/db_write_coordinator.py"
click node_memory "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/memory_service/orchestrator.py"
click node_quality "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/memory_service/validation.py"
click node_relations "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/relation_service.py"
click node_context "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/context_expansion_service.py"
click node_embedding "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/embedding_service.py"
click node_reranker "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/reranker_service.py"
click node_sqlite "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/db/connection.py"
click node_search "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/memory_service/search_primitives.py"
click node_librarian "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/librarian_service.py"
click node_events "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/event_service.py"
click node_viewer "https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/viewer/routes.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_mcp,node_tools,node_rpc_client,node_cli,node_browser toneBlue
class node_daemon,node_dispatch,node_coordinator toneAmber
class node_memory,node_quality,node_relations,node_context,node_embedding,node_reranker toneMint
class node_sqlite,node_search toneRose
class node_librarian,node_events,node_viewer,node_agents,node_embedding_runtime toneIndigo
```

## Components

### Agent Interfaces

- [MCP Server](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/mcp/server.py): `src/saltmdb/mcp/server.py`
- [MCP Tools](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/mcp/tools.py): `src/saltmdb/mcp/tools.py`
- [Daemon Client](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/daemon/client.py): `src/saltmdb/daemon/client.py`
- [CLI](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/cli.py): `src/saltmdb/cli.py`

### Daemon Backend

- [Backend Daemon](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/daemon/server.py): `src/saltmdb/daemon/server.py`
- [Tool Dispatch](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/daemon/dispatch.py): `src/saltmdb/daemon/dispatch.py`
- [Write Coordinator](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/daemon/db_write_coordinator.py): `src/saltmdb/daemon/db_write_coordinator.py`

### Memory Domain

- [Memory Operations](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/memory_service/orchestrator.py): `src/saltmdb/domain/services/memory_service/orchestrator.py`
- [Write Quality and Duplicates](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/memory_service/validation.py): `src/saltmdb/domain/services/memory_service/validation.py`
- [Relations and Lineage](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/relation_service.py): `src/saltmdb/domain/services/relation_service.py`
- [Context Expansion](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/context_expansion_service.py): `src/saltmdb/domain/services/context_expansion_service.py`
- [Embedding Jobs](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/embedding_service.py): `src/saltmdb/domain/services/embedding_service.py`
- [Cross-Encoder Reranker](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/reranker_service.py): `src/saltmdb/domain/services/reranker_service.py`

### Persistence and Search

- [SQLite Memory Store](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/db/connection.py): `src/saltmdb/db/connection.py`
- [Search Primitives](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/memory_service/search_primitives.py): `src/saltmdb/domain/services/memory_service/search_primitives.py`

### Viewing and Governance

- [Librarian Maintenance](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/librarian_service.py): `src/saltmdb/domain/services/librarian_service.py`
- [Event and Governance Services](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/domain/services/event_service.py): `src/saltmdb/domain/services/event_service.py`
- [Database Viewer](https://github.com/zbalint/saltmdb/blob/master/src/saltmdb/viewer/routes.py): `src/saltmdb/viewer/routes.py`

### Other components

- **AI Agents**
- **ONNX Embedding Runtime**
- **Browser User**

## Connections

- AI Agents → MCP Server: invoke MCP
- MCP Server → MCP Tools: register tools
- MCP Tools → Daemon Client: send tool RPC
- Daemon Client → Backend Daemon: connect and call
- CLI → Daemon Client: call daemon
- Backend Daemon → Tool Dispatch: dispatch tools
- Tool Dispatch → Memory Operations: invoke operations
- Tool Dispatch → Relations and Lineage: invoke relations
- Tool Dispatch → Event and Governance Services: invoke event tools
- Memory Operations → Write Quality and Duplicates: validate writes
- Memory Operations → Search Primitives: build search results
- Memory Operations → Cross-Encoder Reranker: rerank candidates
- Memory Operations → Context Expansion: expand context
- Relations and Lineage → SQLite Memory Store: read and write
- Memory Operations → SQLite Memory Store: read and write
- Write Quality and Duplicates → SQLite Memory Store: check duplicates
- Embedding Jobs → SQLite Memory Store: persist vectors
- Embedding Jobs → ONNX Embedding Runtime: generate vectors
- Backend Daemon → Write Coordinator: coordinate writes
- Write Coordinator → SQLite Memory Store: serialize writes
- Backend Daemon → Embedding Jobs: run embedding jobs
- Backend Daemon → Librarian Maintenance: trigger maintenance
- Librarian Maintenance → SQLite Memory Store: read and update
- Event and Governance Services → SQLite Memory Store: append and read
- Backend Daemon → Database Viewer: serve in process
- Database Viewer → SQLite Memory Store: query records
- Browser User → Database Viewer: browse records