Phase 5 Design - Consistency Hardening
Status: implemented (2026-11-18).
:::note Shape superseded This design was written when Aether was framed as a gateway with a single facade. The pieces-first SDK design now sets the overall shape, and its section 7 lists what it changes here. The record-store contract, indexer semantics, validation rules, scope rules, and ranking algorithm below remain the design of the consistency pieces. :::
This document resolves the open choices in Roadmap Phase 5 into one design a builder can plan from.
1. Intent
Aether stays model-free (decided 2026-11-16). It does not embed, chunk, extract, or call models. The audience is developers who run their own memory, RAG, or knowledge-base stack and already produce their own embeddings and entities.
The specific problem Aether solves for them:
One memory lives in several stores (a record, a vector, graph facts). Keeping those stores consistent through writes, updates, deletes, crashes, and retries is the part every team rebuilds badly. Aether makes it one call with stated guarantees.
Everything in this phase serves that sentence. A feature that does not make the multi-store guarantee stronger or easier to trust is out of scope.
2. Goals, Non-Goals, Anti-Goals
Goals
- G1. An acknowledged write is never lost, including across a process crash.
- G2. A forgotten memory never reappears and leaves no orphaned index entries.
- G3. A caller reads its own writes with scores that mean the same thing as indexed scores.
- G4. Expired and out-of-scope memories are never returned.
- G5. Bad input fails at the inbound boundary, not later inside a driver.
- G6. Every guarantee above is expressed as a contract test that any backend must pass.
Non-goals
- Embedding, chunking, extraction, summarization, consolidation, or any model call.
- New production drivers (Phase 6).
- Cross-store distributed transactions. Indexes are eventually consistent with the record store by design.
Anti-goals
- A guarantee that holds only for
InMemoryBackend. - Silent degradation: returning an empty or approximate result where an error is the honest answer.
3. Approaches Considered
A. Patch each bug in place.
Keep the in-process queue, hot cache, and KvStore-as-cache, and fix the listed defects one by one (requeue on failure, lock forget against flush, add TTL to the cache).
Smallest diff per fix.
It keeps three places that each hold "recent writes" (queue, cache, KV) and must be kept in agreement, and it cannot deliver G1 across a crash without adding a separate write-ahead log.
B. Record store as the source of truth, indexes derived (chosen). Every write, update, and delete is a versioned change to one durable record. A single indexer brings the vector and graph indexes up to the record's version. Most of the listed defects stop being possible instead of being individually guarded, and three components are deleted. Cost: the storage trait changes shape, and the record-store role needs a real database (SQLite, Postgres) for the durability claim.
C. Outbox with a separate write-ahead log.
Keep KvStore as a cache and add WalStore as the durable log.
Delivers G1, but adds a fourth storage role and a second ordering to reconcile with the KV state.
B was chosen because it is the only option where the guarantees follow from the structure. It was the proposal in roadmap section 5.1.
4. Design
4.1 Roles
| Role | Trait | Holds | Truth? |
|---|---|---|---|
| Record store | RecordStore (renamed from KvStore) | Complete MemoryItem, version, indexing state, tombstones, idempotency keys | Yes |
| Vector index | VectorStore | id, vector, filterable metadata | Derived |
| Graph index | GraphStore | Entities and provenance-tagged relations | Derived |
The vector index no longer carries content.
Recall resolves hits through the record store by MemoryId.
A hit whose record is missing, tombstoned, or expired is dropped, which is what makes G2 and G4 structural.
4.2 RecordStore contract
#[async_trait]
pub trait RecordStore: OutboundConnector {
/// Stores the item and, if present, its idempotency key in one atomic step.
async fn create(&self, ns: &ProjectId, item: &MemoryItem, ttl: Option<Duration>) -> Result<CreateOutcome>;
async fn get(&self, ns: &ProjectId, id: MemoryId) -> Result<Option<MemoryItem>>;
async fn get_many(&self, ns: &ProjectId, ids: &[MemoryId]) -> Result<Vec<MemoryItem>>;
async fn cas_update(&self, ns: &ProjectId, id: MemoryId, expected_version: Option<u64>, new_item: &MemoryItem) -> Result<()>;
/// Marks the record deleted, bumps its version, and returns it. `None` if there is no live record.
/// The record is removed by `mark_indexed`.
async fn tombstone(&self, ns: &ProjectId, id: MemoryId) -> Result<Option<MemoryItem>>;
/// Records whose indexes are behind their version, oldest first, across all projects.
async fn pending(&self, limit: usize) -> Result<Vec<PendingRecord>>;
/// Same, for one project. Used by read-your-writes.
async fn pending_for(&self, ns: &ProjectId, limit: usize) -> Result<Vec<MemoryItem>>;
/// Live items in one session scope. Used to recall working memory.
async fn session_items(&self, ns: &ProjectId, session: &SessionId, limit: usize) -> Result<Vec<MemoryItem>>;
/// No-op unless `version` is still the record's current version. Removes the record if it is a tombstone.
async fn mark_indexed(&self, ns: &ProjectId, id: MemoryId, version: u64) -> Result<()>;
}
pub enum CreateOutcome { Created, Duplicate(MemoryReceipt) }
pub struct PendingRecord { pub item: MemoryItem, pub tombstone: bool }
put, put_if_absent, recent, and delete are removed.
pending is the only method that crosses project boundaries, and it is called only by the indexer.
An idempotency key lives exactly as long as its record and is removed with it.
4.3 Write, update, forget: one pipeline
All three become "change the record, then index".
- remember: validate, then
create.Duplicatereturns the existing receipt. - update: read, apply patch,
cas_updatewithversion + 1. - forget:
tombstone. - In every case the record is now pending.
Bufferedreturns immediately.WaitFlush,update, andforgetindex that record before returning. If indexing that record fails, the waiter receives the error and the record stays pending for retry.
Indexer (replaces IngestionBuffer):
- Loop:
pending(batch), then for each record apply it to the indexes, thenmark_indexed(id, version). - Live record: upsert the vector if there is an embedding, otherwise delete any vector for that id; retract the memory's previous graph facts, then upsert current entities and relations.
- Upserting relations for a memory after its facts were retracted must leave those facts active.
This is added to the
GraphStorecontract. - Tombstone: delete the vector, retract graph facts, then
mark_indexedremoves the record. - A failed record stays pending and is retried on the next pass. One bad record does not block or drop the others.
- Woken by a notify on every write, and by an interval timer as a fallback.
- Index operations are idempotent upserts and deletes, so two replicas processing the same record is harmless.
mark_indexedignores stale versions, so a record updated mid-pass simply stays pending.
What this removes:
| Removed | Why it is no longer needed |
|---|---|
| In-process pending queue | Pending state is in the record store. Fixes data loss on failed flush and on crash. |
HotContextCache | Its only users were read-your-writes and seed lookup, both now served by pending_for. Removes the TTL leak. Reintroduce only if measured read latency calls for it. |
PolicyRouter | Idempotency moves into create; validation is MemoryInput::validate plus the dimension check. Removes the unbounded key map. |
WalStore (planned) | The record store is the log. |
| Queue capacity and backpressure (planned) | There is no in-memory queue to bound. |
4.4 Validation at the boundary
VectorStoregainsdescribe(ns) -> Result<Option<IndexSpec>>whereIndexSpec { dimensions, metric }.remember,update, andrecallcheck vector length against it and returnInvalidInputon mismatch.updatethat changescontentmust also supplyembeddingif the item has one. The gateway cannot re-embed, and a vector that no longer matches its text is worse than an error.MemoryUpdategainsentitiesandrelations.recallinVectororHybridmode withoutquery_vectorreturnsInvalidInput.Graphmode without seeds returnsInvalidInput.- Metadata keys starting with
_aether_are reserved and rejected in caller input.
4.5 Scopes, tiers, and sessions
pub enum MemoryScope { Project, User(UserId), Session(SessionId) }
Globalis removed. It was documented as "shared within a project", which isProject.RecallQuerygainsscopes: Vec<MemoryScope>, defaulting to[Project]. A typical agent turn passes[Project, User(u), Session(s)].- The gateway writes
_aether_scopeand_aether_tierinto vector metadata and ANDs a scope filter into every search. Callers cannot widen it. - Session memories are never written to the indexes.
They live only in the record store with a TTL, and
mark_indexedis called for them without index writes. At recall,session_itemsfor each requested session are scored in process. This fixes expired session memories remaining searchable in the vector store forever. MemoryTierstays a label with no behaviour, filterable through_aether_tier. The memory guide will say so.
4.6 Recall
- Validate (4.4).
- Vector search with the scope filter and caller filter,
top_k. - Resolve hits through
get_many; drop the unresolved. - If
ReadYourWrites: addpending_foritems that match scope and filter. IfEventual: skip. - Add
session_itemsfor requested sessions. - Items from steps 4 and 5 are scored against
query_vectorusing the index's metric fromdescribe. Items with no embedding are left out ofVectorandHybridranking. The constant0.75and0.5scores are deleted. HybridandGraph: seeds are the caller'sseed_entitiesplus the entities of the resolved vector hits. Fetch the neighbourhood, run PPR, and give each memory the sum of PPR scores of entities on edges it sourced (source_memory_id).Hybridfuses the vector ranking and the graph ranking with reciprocal rank fusion. Graph-only memories are resolved throughget_manylike any other hit.- The graph index carries no scope, so every resolved item is checked against the requested scopes in the gateway before it is returned.
4.7 Middleware defaults
MemoryManager::builderwraps each store asTraced<Resilient<Timeout<T>>>, withBatcherinnermost for the vector store. Each layer can be switched off on the builder.- Retry backoff gets full jitter.
- The circuit breaker is removed from the connectors doc.
4.8 Contract suite
- The suite becomes generic over a backend factory so Phase 6 drivers run it unchanged.
- New cases, one per guarantee: failed index write keeps the record pending (G1); pending records survive a rebuilt manager over the same store (G1); forget during an in-flight index pass does not resurrect (G2); failed index delete is retried and leaves no orphan (G2); unflushed and flushed copies of the same item score equally (G3); expired session item is not recalled (G4); user A cannot recall user B's memories (G4); wrong-dimension write is rejected at
remember(G5). - A fault-injecting wrapper around
InMemoryBackenddrives the failure cases.
4.9 Repository hygiene
- Rust CI:
cargo fmt --check,cargo clippy --workspace --all-targets -- -D warnings,cargo test --workspace. - Remove the Python package, its tests,
pyproject.toml, and the Python CI job. RewriteREADME.mdanddocs/development/guidelines.mdfor Rust. This deletes code and needs explicit sign-off before it is done.
5. Order of Work
Each step is a series of micro commits, test first, and leaves the workspace green.
- Rust CI, so every later step is checked.
- Rename
KvStoretoRecordStore(structural only). - Fault-injecting test backend and generic contract suite.
- New
RecordStoremethods and the indexer; delete the queue,HotContextCache, andPolicyRouter. - Forget through tombstones.
describeand boundary validation;MemoryUpdateentities and relations.- Scopes with identity; session memories record-only.
- Recall: resolve through records, real scores, seeds from hits, PPR fusion.
- Middleware defaults and jitter.
- Docs: memory guide, usage guide, connectors, architecture diagram, README.
- Python removal (after sign-off).
6. Production Impact
None on running systems: no production driver exists and nothing is published.
The public Rust API changes in breaking ways (KvStore renamed and reshaped, MemoryScope variants, MemoryUpdate fields, recall now errors where it returned empty results).
The crate is at 0.1.0 and unreleased, so no migration path is provided.
7. Design Calls
These were proposed by the author and approved with the design on 2026-11-16.
- Renaming
KvStoretoRecordStoreinstead of only redefining it in prose. - Deleting
HotContextCacheandPolicyRouterinstead of fixing them. updatewith new content and no new embedding is an error, not a silent removal from the index.recallwithout a usable query is an error, not "most recent items".- Session memories are scored in process and never indexed.
Globalscope removed.- Reciprocal rank fusion for hybrid ranking.
MemoryTierstays a label.
8. Left to the Builder
- SQL or key layout for pending state and idempotency keys inside each backend.
- Indexer batch size, interval, and how waiters are notified of a specific version.
- RRF constant and PPR parameters, kept as named defaults.
- Whether
session_itemsneeds pagination (start without).