Development Guidelines
Engineering conventions for working on the Aether SDK Rust workspace. See AGENTS.md for repository-wide micro-commit and TDD rules.
Workspace Layout
crates/aether-core- Domain DTOs, validated newtypes (ProjectId,MemoryId,EntityId,UserId,SessionId),DistanceMetric::score,FilterExpr::matches,IndexSpec,AetherError, and storage traits (OutboundConnector,RecordStore,VectorStore,GraphStore).crates/aether-cortex- Composable sync and retrieval primitives (Indexer,PersonalizedPageRank,graph_scores,recall::{scope_filter, vector_search, unindexed, session, graph_search, merge, rrf, in_scopes}).crates/aether-adapters- Storage connectors (sqlite,redis,turbopuffer,qdrant,chroma,pgvector,neo4j), resilience middleware (Batcher,Timeout,Resilient,Traced),InMemoryBackend(in_memorymodule withFaultPoint), and reusablecontracttest suite (contract-suitefeature).crates/aether-sdk- OptionalMemoryManager/MemoryManagerBuilderfacade, runnable examples (level_1_connector..level_5_facade), and optionaltelemetry(otelfeature).crates/aether-vault- Obsidian-native vault daemon (VaultEngine), single-file SQLite WAL + FTS5 + 256-dim local vector +PersonalizedPageRankhybrid recall,Aether/Inbox.mdstaging and reconciliation, and 3-tool stdio MCP server (McpServer,aether-mcpbinary).
Core Principles
- Model-free boundary - Aether does not call LLMs, embedders, chunkers, or extractors. Callers supply text, optional vectors, entities, and relations.
- Pieces-first isolation - Write orchestration against
RecordStore,VectorStore, andGraphStoretraits. Offline tests run deterministically againstInMemoryBackendwithout external services; live database tests are#[ignore]d and opt-in. - Explicit error classification - Classify retryable transport/rate-limit faults as
AetherError::Transientand invalid input/auth/schema/version conflicts as permanent variants (Permanent,InvalidInput,NotFound,Conflict) soResilientonly retries transient faults. - Shared backend contract - Every
RecordStore,VectorStore, andGraphStoredriver must passmuninn_aether_adapters::contract::{record_store, vector_store, graph_store}enabled via thecontract-suitefeature.
Verification Gate
Every change must pass:
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace --all-features