Connectors Architecture (Unified Storage Layer)
muninn-aether-adapters provides the outbound storage traits' implementations so applications can combine SQLite, Redis/Valkey, Turbopuffer, Qdrant, Chroma, pgvector, and Neo4j behind consistent async traits, resilience wrappers, and contract tests.
1. Storage Roles & Connector Traits
Aether separates the authoritative system of record from derived search indexes:
RecordStore: OutboundConnector: Authoritative durable store forMemoryItemrecords, atomic idempotency (create), batch lookup (get_many), optimistic CAS (cas_update), versioned tombstones (tombstone), indexing cursors (pending,pending_for,mark_indexed), and live TTL-backedsession_items. Backed by SQLite (WAL mode) or Redis/Valkey (single-instance/shard Lua script atomicity across pending ZSETs).VectorStore: OutboundConnector: Derived dense vector + metadata index (initialize,describe,upsert_batch,delete,search) backed by Turbopuffer, Qdrant, Chroma, or pgvector.describereportsOption<IndexSpec>(persisted across restarts onQdrant,Chroma, andpgvector, and process-cached on REST v1Turbopufferafterinitialize).GraphStore: OutboundConnector: Derived temporal knowledge graph (upsert_entities,upsert_relations,retract_memory_facts,neighborhood) backed by Neo4j Query API v2 withsource_memory_idprovenance andvalid_at/invalid_atbounds.
2. Crate & Module Structure (muninn-aether-adapters)
crates/aether-adapters/
├── Cargo.toml # Features: contract-suite, sqlite, redis, turbopuffer, qdrant, neo4j, chroma, pgvector
└── src/
├── lib.rs
├── contract.rs # Reusable backend contract suite (gated by `contract-suite`)
├── in_memory.rs # InMemoryBackend + FaultPoint injection
├── middleware.rs # Batcher, Timeout, Resilient (exponential backoff + jitter), Traced
├── kv/ # sqlite.rs, redis.rs
└── storage/ # turbopuffer.rs, qdrant.rs, neo4j.rs, chroma.rs, pgvector.rs
3. Shared Supertrait & Middleware Composition
Every driver implements OutboundConnector and composes cleanly inside generic middleware (Traced<Resilient<Timeout<Batcher<T>>>>):
#[derive(Debug, Clone)]
pub struct ConnectorCapabilities {
pub max_batch_size: usize,
pub supports_temporal: bool,
pub supports_filter_expr: bool,
}
#[async_trait::async_trait]
pub trait OutboundConnector: Send + Sync {
fn name(&self) -> &'static str;
fn capabilities(&self) -> ConnectorCapabilities;
async fn health_check(&self) -> Result<ConnectorHealth>;
async fn close(&self) -> Result<()>;
}
Error Classification & Wrapper Responsibilities
Drivers classify failures via AetherError:
AetherError::Transient { .. }: Retryable transport or rate-limit errors (HTTP 429/503, timeouts, busy locks).AetherError::Permanent { .. }/InvalidInput/Conflict/NotFound: Non-retryable errors.
When stacked (which MemoryManager::builder configures by default, with opt-out toggles):
Batcher(vector store): chunksupsert_batchcalls tocapabilities().max_batch_size.Timeout: bounds per-request tail latency (default 10s inMemoryManager).Resilient: retries onlyAetherError::is_retryable()errors with full-jitter exponential backoff (jittered).Traced: emitsconnector_optracingspans withotel.kind = "client",db.system,connector,project_id,op, andotel.status_code.
4. Contract Test Suite
Every storage implementation is verified against muninn_aether_adapters::contract::{record_store, record_store_concurrent_idempotency, vector_store, graph_store}:
- Record contract:
create, atomicidempotency_keydeduplication (concurrent + persisted state), namespace isolation,cas_updateconflict checks, TTL expiration,session_items,tombstone+ key reuse, andmark_indexed. - Vector contract: namespace isolation,
describeacross clients/restarts,upsert_batch+deleteidempotency, dimension mismatch rejection, distance metrics, andFilterExprtranslation (Eq,In,Range,And,Or). - Graph contract: entity/relation idempotent upserts, temporal
as_of/active_onlyfiltering, multi-hopneighborhoodtraversal, andretract_memory_factsprovenance isolation.