How zbalint/saltmdb works
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: connection.py SQLite Memory Store · server.py Backend Daemon · orchestrator.py Memory Operations · dispatch.py Tool Dispatch
Components 21
Agent Interfaces
- MCP Server
src/saltmdb/mcp/server.py - MCP Tools
src/saltmdb/mcp/tools.py - Daemon Client
src/saltmdb/daemon/client.py - CLI
src/saltmdb/cli.py
Daemon Backend
- Backend Daemon
src/saltmdb/daemon/server.py - Tool Dispatch
src/saltmdb/daemon/dispatch.py - Write Coordinator
src/saltmdb/daemon/db_write_coordinator.py
Memory Domain
- Memory Operations
src/saltmdb/domain/services/memory_service/orchestrator.py - Write Quality and Duplicates
src/saltmdb/domain/services/memory_service/validation.py - Relations and Lineage
src/saltmdb/domain/services/relation_service.py - Context Expansion
src/saltmdb/domain/services/context_expansion_service.py - Embedding Jobs
src/saltmdb/domain/services/embedding_service.py - Cross-Encoder Reranker
src/saltmdb/domain/services/reranker_service.py
Persistence and Search
- SQLite Memory Store
src/saltmdb/db/connection.py - Search Primitives
src/saltmdb/domain/services/memory_service/search_primitives.py
Viewing and Governance
- Librarian Maintenance
src/saltmdb/domain/services/librarian_service.py - Event and Governance Services
src/saltmdb/domain/services/event_service.py - Database Viewer
src/saltmdb/viewer/routes.py
Other components
- AI Agents
- ONNX Embedding Runtime
- Browser User
Connections 27
- 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