Memory Model & Consistency
Aether treats the RecordStore as the durable source of truth and keeps VectorStore and GraphStore as derived indexes synchronized via versioned indexing state and tombstones.
Storage Roles
RecordStore: Holds canonicalMemoryItemrecords, atomic idempotency keys (create), optimistic CAS versions (cas_update), pending indexing state (pending,pending_for,mark_indexed), versionedtombstonedeletes, and TTL-boundsession_items.VectorStore(optional): Holds dense vectors paired with filterable metadata (_aether_scope,_aether_tier, and caller JSON fields). Recall resolves hit bodies fromRecordStore::get_many, omitting stale or tombstoned records.GraphStore(optional): Holds entities and idempotent temporal edges (source_memory_id,valid_at,invalid_at) retracted onupdateandforget.
Memory Tiers (MemoryTier)
MemoryTier (Episodic, Semantic (default), Procedural, Profile) is stored on every MemoryItem and written to vector metadata as _aether_tier for filtering in queries.
Memory Scopes (MemoryScope)
Project(default): Shared within aProjectIdnamespace.User(UserId): Isolated to a validated user identity via_aether_scopeindex filtering andrecall::in_scopes.Session(SessionId): Stored only in theRecordStorewith TTL expiration (with_session_ttl, default 1 hour). Session items are never written to vector or graph indexes, preventing stale turns from outliving TTL.
Durability & Consistency
WriteDurability
Buffered(default): Persists the record inRecordStore, wakes any opt-in background indexer, and returnsReceiptState::Bufferedimmediately. Pending records survive process restarts and are indexed onflush()or bybackground_indexing.WaitFlush: Persists the record and runsIndexer::applybefore returningReceiptState::Persisted.
ConsistencyMode
ReadYourWrites(default): Combines indexedvector_searchhits with unindexed pending records scored using the index'sDistanceMetric::score, keeping the newestversionviarecall::merge, plus livesession_itemswhen requested.Eventual: Reads derived vector/graph indexes directly (plus explicitSessionscopes) without scanning unindexed pending records.
Updates, Tombstones, and Graph Fusion
- Updating
contenton an embedded memory requires a matching newembeddingso indexed vectors stay aligned with text. forgetrecords an immediatetombstone(hiding the memory fromget/get_manyright away) and retracts vector/graph entries; any transient index delete failure stays pending and retries cleanly on subsequent flushes.RecallMode::Hybridfuses vector and graph rankings deterministically usingrecall::rrf(Reciprocal Rank Fusion) backed byPersonalizedPageRank+graph_scores.
Vault Memory Model (muninn-aether-vault)
muninn-aether-vault compiles Obsidian Markdown notes into tracked Aether Memory Units (Amu) inside a single SQLite WAL file while reading live source sections directly from disk.
Vault Tiers (VaultTier) & Privacy Boundary
Hot(aether_tier: hotor matched by vault-root.aetherhotpath/glob rules): Packed into the static[AETHER_HOT_PROFILE]prefix block (static_prefix/hot_prefix) sorted deterministically byamu_idascending withinHOT_PROFILE_MAX_TOKENS(2000), with no volatile timestamps soprefix_hashstays stable across turns. Explicit frontmatter (private,warm,cold,hot) always overrides.aetherhot.Warm(default) (aether_tier: warm) andCold(aether_tier: cold): Ranked dynamically per query by fusing SQLite FTS5 BM25, cosine vector similarity (HashedNgramEmbedder,DenseSubwordEmbedder, orLocalGpuEmbedder), and wikilink/tagPersonalizedPageRank(graph_scores) viarecall::rrf, scaled byauthority_weight, reranked over the top30RRF entries byCrossEncoderRerankerwith a per-heading diversity cap (MAX_RECALL_HITS_PER_HEADING = 2so repeated boilerplate headings cannot crowd out distinct notes), and packed into[AETHER_RECALL_CONTEXT](dynamic_context) withinmax_tokens(default1500). Empty heading-only parent sections (headings with no body text before the next heading) are skipped at parse time while preserving hierarchy and anchor slugs.private(aether_tier: private): Exists only during parsing (RawFrontmatterTier) and cannot be constructed inVaultTier. Private notes are removed from SQLite if previously indexed, omitted fromrecalland Dream consolidation, and rejected byinspect_source.
Scopes, Kinds, Statuses, and Provenance
ScopeTag: Lowercase scope tags fromaether_scopefrontmatter (defaults toglobal).AmuKind&AmuStatus: Notes carryAmuKind(Profile,Rule,Decision,Spec(default), orFleeting(default underDaily/orJournal/)) andAmuStatus(Active(default),Superseded,Archived).SourcePointer&AmuId: Normalized vault-relative POSIX paths (Arch/DB.md#Schema, or#_preamblefor text before the first ATX heading) map deterministically via SHA-256 toAmuId(amu_<32-hex>), which converts bijectively tomuninn_aether_core::MemoryId.
Human-in-the-Loop Inbox (Aether/Inbox.md) & Compiled Mirror (Aether/Compiled/Approved.md)
VaultEngine::stage_memoryandVaultEngine::run_dream_passwrite pending- [ ] **[TIER | scope]** ...entries atomically (tempfile,sync_all,rename) toAether/Inbox.mdand record the file hash inself_write_ledgerso polling skips daemon-originated writes.- Marking an entry
[x]in Obsidian (or callingVaultEngine::decide_inbox_candidate/POST /v1/inbox/decide) compiles it into an active AMU, materializes its## cand_<id>section inAether/Compiled/Approved.mdsoaether_inspect_sourceresolves itsSourcePointer, and marks anysupersedes_amu_idtarget asSuperseded. Marking[-]rejects it.
Embedder Schema Tracking (vault_meta)
vault_metatracks(schema_version, embedder_id, embedding_dim, updated_at). Switching embedders or dimensions onVaultEngine::openre-embeds active AMUs synchronously in oneIMMEDIATEtransaction when active count<= sync_reindex_threshold(5000), or populatesamus_shadow_embeddingsasynchronously and swaps atomically above threshold while keeping FTS5 + graph recall online.
Scoped Team API Keys (agent_api_keys)
ScopedApiKeybinds aKeyId, anAgentId, anAgentRole(Reader,Contributor, orAdmin), and a non-empty list ofScopeTagvalues. Plaintext secrets (aek_<hex>) are returned once at creation and stored as domain-separated SHA-256 digests inagent_api_keys, compared in constant time.VaultEngine::recall_asintersects requested scopes with the caller's allowed scopes insideVaultStore::recall_bundlebefore top-K truncation.VaultEngine::stage_memory_asrequiresContributoror higher, stampsproposed_bywithagent.agent_id, and rejects disallowed scopes.VaultEngine::inspect_source_asblocks cross-scope reads on both vault notes andAether/Compiled/Approved.mdentries.
Git-Backed Team Sync & Monotonic Lattice (git.rs)
VaultEngine::git_syncensures.gitignoreignores.aether/, runsgit fetchandgit merge --no-commit, redacts any credential userinfo inGitSyncReportviaredact_url_userinfo, and optionally commits and pushes merged state.- Human notes containing unresolved Git conflict markers (
<<<<<<<,=======,>>>>>>>outside fenced code blocks) are skipped during re-indexing so prior valid SQLite AMUs stay active until the human resolves the conflict. - Conflicts in
Aether/Inbox.mdandAether/Compiled/Approved.mdare resolved deterministically by a join-semilattice keyed onCandidateId(Approved > Rejected > Pending) combined with local SQLite decision state.
GPU KV-Tensor Warming & Eviction (kv_cache_blocks)
kv.rspartitionsstatic_prefixinto chained PagedAttention prefix blocks (KvBlockHash::paged_chained) andWARM/COLDAMUs into CacheBlend chunks (KvBlockHash::cache_blend) acrossGpuHbm,HostDram, andNvmeSsd.InMemoryKvCacheAdaptertracks tiered capacity with LRU demotion (GpuHbm -> HostDram -> NvmeSsd), whileVllmLmCacheHttpAdapterpushes warming payloads over HTTP (LmCacheControlorOpenAiPrefill) with offline fallback.- Block metadata persists in SQLite (
kv_cache_blocks), rehydrates onVaultEngine::open, surfaces reuse hints inRecallResponse::kv_hint(and MCPstructuredContent.kv_hint), and evicts affected hashes atomically whenever AMUs are modified, removed, or superseded.