Skip to main content

Crates, Traits & API Reference

This reference lists the workspace crates, validated newtypes, trait contracts, orchestration methods, and error variants across Project Aether (0.1.0, Rust 1.89, edition = "2021").

Workspace crates​

Crate directoryPackage nameRole
crates/aether-coremuninn-aether-coreDomain DTOs, validated IDs, scoring, filters, AetherError, and storage traits
crates/aether-cortexmuninn-aether-cortexIndexer sync engine, PersonalizedPageRank, graph_scores, and recall functions
crates/aether-adaptersmuninn-aether-adaptersInMemoryBackend, middleware wrappers, contract suite, and 7 backend drivers
crates/aether-sdkmuninn-aether-sdkMemoryManager facade, MemoryManagerBuilder, and telemetry (otel feature)
crates/aether-vaultmuninn-aether-vaultVaultEngine, ControlPlaneServer, McpServer, KV adapters, and aether-mcp binary

Validated newtypes​

Core SDK (muninn-aether-core)​

TypeInner representationValidation rulePrimary constructor
ProjectIdStringNon-empty after trimProjectId::new(id)
MemoryIdUuid (pub Uuid)UUID v4 or caller-provided UUIDMemoryId::new(), MemoryId::from_uuid(id)
EntityIdStringNon-empty after trimEntityId::new(id)
UserIdStringNon-empty after trimUserId::new(id)
SessionIdStringNon-empty after trimSessionId::new(id)
SecretStringStringDebug and Display print [REDACTED]SecretString::new(secret)

Obsidian Vault & Team Auth (muninn-aether-vault)​

TypeFormat and constraintsPrimary constructor
VaultPathVault-relative POSIX .md path. Rejects empty, /, drive letters, NUL, .., .obsidian, .git, .trash, .aetherVaultPath::parse(raw)
SourcePointerVaultPath plus optional single-line #<anchor>SourcePointer::parse(raw), SourcePointer::new(path, anchor)
AmuIdamu_<32-hex> wrapping MemoryId derived deterministically via SHA-256 (aether:amu:v1:)AmuId::from_pointer(&pointer), AmuId::parse(raw)
CandidateIdcand_<6..32-hex> (cand_<12-hex> when generated)CandidateId::from_proposal(fact, target, tier), CandidateId::parse(raw)
ContentHash64-character lowercase hex SHA-256 digestContentHash::compute(bytes), ContentHash::parse(raw)
ScopeTagLowercase non-empty label with no whitespace or control characters (defaults to global)ScopeTag::new(raw), ScopeTag::global()
TokenBudgetPositive non-zero usize (default 1500, HOT_PROFILE_MAX_TOKENS is 2000)TokenBudget::new(tokens)
AgentIdLowercase ASCII [a-z0-9._-], 1..=128 bytesAgentId::new(raw)
KeyIdkey_<16..32-hex> (key_<16-hex> when generated)KeyId::generate(), KeyId::parse(raw)
ApiKeySecretaek_<hex> with >= 32 hex characters (aek_<64-hex> generated, non-Serialize, redacts Debug and Display)ApiKeySecret::generate(), ApiKeySecret::parse(raw)
ModelIdNon-empty trimmed string without control charactersModelId::new(raw)
KvBlockHash64-hex SHA-256 KV block identifierKvBlockHash::genesis(), paged_chained(...), cache_blend(...), parse(raw)

Core storage traits (muninn-aether-core)​

Arc<T> implements OutboundConnector, RecordStore, VectorStore, and GraphStore for any T implementing the corresponding trait.

OutboundConnector​

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<()>;
}

RecordStore: OutboundConnector​

MethodSignature summaryBehavior
create(ns, item, ttl) -> Result<CreateOutcome>Persists record and atomic idempotency_key (Created or Duplicate(MemoryReceipt))
get(ns, id) -> Result<Option<MemoryItem>>Returns live non-expired, non-tombstoned record
get_many(ns, ids) -> Result<Vec<MemoryItem>>Batch lookup dropping missing, expired, or tombstoned records
cas_update(ns, id, expected_version, new_item) -> Result<()>Atomically updates live record and returns AetherError::Conflict on version mismatch
tombstone(ns, id) -> Result<Option<MemoryItem>>Marks deleted, bumps version, hides from reads while leaving pending for index retraction
pending(limit) -> Result<Vec<PendingRecord>>Cross-project unindexed records and tombstones, oldest first
pending_for(ns, limit) -> Result<Vec<MemoryItem>>Project-scoped live unindexed records for ReadYourWrites
session_items(ns, session, limit) -> Result<Vec<MemoryItem>>Live TTL-bound items for SessionId
mark_indexed(ns, id, version) -> Result<()>Advances indexed_version or purges tombstone if version still matches

VectorStore: OutboundConnector​

MethodSignature summaryBehavior
initialize(ns, dimensions, metric) -> Result<()>Creates or validates namespace index with dimensions and DistanceMetric
describe(ns) -> Result<Option<IndexSpec>>Returns { dimensions, metric } or None if uninitialized
upsert_batch(ns, records) -> Result<()>Idempotent upsert of VectorRecord { id, vector, metadata }
delete(ns, ids) -> Result<()>Idempotent removal by MemoryId
search(ns, query_vector, top_k, filter) -> Result<Vec<VectorMatch>>Returns top k matches optionally filtered by FilterExpr

GraphStore: OutboundConnector​

MethodSignature summaryBehavior
upsert_entities(ns, entities) -> Result<()>Idempotent upsert of Entity { id, name, entity_type }
upsert_relations(ns, source_memory_id, relations) -> Result<()>Idempotent upsert keyed by (source_memory_id, source, target, relation_type)
retract_memory_facts(ns, source_memory_id, invalidated_at) -> Result<()>Stamps invalid_at on all edges belonging to source_memory_id
neighborhood(ns, seeds, hops, per_node_limit, temporal) -> Result<Subgraph>Bounded multi-hop traversal respecting TemporalFilter { as_of, active_only }

Vault extension traits (muninn-aether-vault)​

TraitMethodsBuilt-in implementations
Embedderid(&self), dimensions(&self), embed(&self, text), device(&self)HashedNgramEmbedder (256-dim default), DenseSubwordEmbedder (384-dim default), LocalGpuEmbedder
Rerankerid(&self), top_k(&self), rerank(&self, query, candidates)CrossEncoderReranker (DEFAULT_RERANK_TOP_K = 30), NoopReranker
KvCacheAdapterid, hydrate, warm_blocks, lookup_blocks, evict_blocks, statsInMemoryKvCacheAdapter, VllmLmCacheHttpAdapter

Orchestration APIs (MemoryManager, Indexer, recall, VaultEngine)​

MemoryManager and MemoryManagerBuilder (muninn-aether-sdk)​

MemoryManager::builder(record_store) starts a builder with defaults connector_tracing = true, session_ttl = Some(3600s), timeout = Some(10s), retry = Some(RetryPolicy::default()), and background_indexing = None.

  • Builder methods. vector, graph, background_indexing, with_connector_tracing, with_session_ttl, with_timeout, with_retry, build.
  • Manager methods. remember(MemoryInput) -> Result<MemoryReceipt>, recall(RecallQuery) -> Result<RecallResult>, update(&ProjectId, MemoryId, MemoryUpdate) -> Result<MemoryReceipt>, forget(&ProjectId, MemoryId) -> Result<()>, flush() -> Result<()>, shutdown() -> Result<()>.

muninn-aether-cortex (Indexer, PersonalizedPageRank, recall)​

  • Indexer. new(record), with_vector(vector), with_graph(graph), notify(), apply(&PendingRecord) -> Result<()>, run_pass() -> Result<PassReport>, spawn(&Arc, interval) -> JoinHandle<()>.
  • PersonalizedPageRank and helpers. PersonalizedPageRank { damping: 0.85, iterations: 20 }, rank(&Subgraph, &[EntityId]), graph_scores(&Subgraph, &[(EntityId, f32)]), index_metadata(&MemoryItem).
  • recall module (RRF_K = 60.0). scope_filter, vector_search, unindexed, session, graph_search, merge, rrf, in_scopes.

VaultEngine (muninn-aether-vault)​

GroupPublic methods
Lifecycle & indexingopen(VaultConfig), vault_meta(), wait_for_reindex(), sync_vault(), handle_fs_event(&Path), status(), shutdown()
Recall & inspectionrecall(RecallRequest), recall_as(&ScopedApiKey, RecallRequest), inspect_source(&str), inspect_source_as(&ScopedApiKey, &str)
Inbox & Dreamstage_memory(StageMemoryRequest), stage_memory_as(&ScopedApiKey, StageMemoryRequest), reconcile_inbox(), pending_inbox(), pending_inbox_as(&ScopedApiKey), decide_inbox_candidate(&CandidateId, bool), run_dream_pass()
Scoped API keysissue_api_key(IssueApiKeyRequest), ensure_bootstrap_admin_key(AgentId, &ApiKeySecret), authenticate_api_key(&ApiKeySecret), list_api_keys(), revoke_api_key(&KeyId)
Team Git & KV cachegit_sync(GitSyncOptions), warm_kv_cache(WarmKvRequest), warm_kv_cache_as(&ScopedApiKey, WarmKvRequest), kv_stats(Option<&ModelId>)

Errors (AetherError and AuthError)​

AetherError (muninn-aether-core)​

VariantRetryable (is_retryable)Meaning
NotImplemented(&'static str)falseOperation not supported by the driver
InvalidInput(String)falseBoundary validation, dimension mismatch, bad path, or missing store
NotFound(String)falseTarget memory, candidate, or source pointer missing
Conflict { memory_id, expected_version, actual_version }falseOptimistic CAS version mismatch on cas_update
Transient { connector, message }trueTimeout, HTTP 429 or 503, busy lock, or transient network error
Permanent { connector, message }falseUnrecoverable backend error or wrapped AuthError (connector = "vault-auth")
Serialization(serde_json::Error)falseJSON encoding or decoding error

AuthError (muninn-aether-vault)​

AuthError maps to HTTP 401 Unauthorized or 403 Forbidden in ControlPlaneServer and converts into AetherError::Permanent { connector: "vault-auth", .. } in Rust callers.

VariantHTTP statusCondition
MissingToken401require_auth is true and Authorization: Bearer ... header is absent
InvalidToken401Malformed bearer header, invalid aek_ format, or unknown digest
RevokedToken(KeyId)401Matched key has revoked_at set
ExpiredToken(KeyId)401Matched key has expires_at <= now
InsufficientRole { required, actual }403Caller role is below required Reader, Contributor, or Admin
ScopeDenied { agent_id, requested }403Requested or target ScopeTag not permitted by key scopes