Skip to main content

Change Overview - From Gateway to Pieces-First SDK

Status: implemented (2026-11-18). All code changes below have landed across the Rust workspace. This page is the one-screen summary of everything that will change in the code, the docs, and the roadmap. The reasoning lives in the pieces-first SDK design and the Phase 5 hardening design. Where this page and those documents disagree, they win and this page has a bug.

1. In One Paragraph​

Aether stops being one facade that every call must pass through and becomes a set of pieces a developer calls from their own workflow. The record store becomes the source of truth and the vector and graph stores become indexes derived from it. Three in-process components that each held their own copy of "recent writes" are deleted, the single QueryPlanner becomes a handful of public recall steps, and MemoryManager shrinks to an optional convenience built only from those public pieces. Nothing is released and no production driver exists, so there is no migration and no production impact.

2. Before and After​

TodayAfter
Entry pointMemoryManager onlyAny piece, at any of five levels; MemoryManager optional
Source of truthUnclear: KV "cache" in practice, vector metadata holds a copy of contentThe record store, explicitly
Stores requiredRecord, vector, and graph, alwaysOnly the ones in use (the facade needs a record store)
Pending writesIn-process queue, lost on crash or failed flushState in the record store, retried until indexed
Background workNone exists, though docs imply itNone unless the developer opts in
RecallOne sealed QueryPlannerPublic steps the developer can reorder and interleave
Unflushed-item scoresConstants 0.75 and 0.5The index's own metric
ScopesLabels with no identityUser(UserId), Session(SessionId), enforced
ExtensionNoneComposition: put your step between two Aether steps
TransportsTrait kept ready for HTTP, gRPC, MCPNone planned

3. What Gets Removed​

3.1 Code that exists today​

RemoveCrateWhyReplaced by
MemoryInbound traitmuninn-aether-coreExisted for server transports that are no longer planned; one implementationInherent methods on MemoryManager
PolicyRouter, PolicyDecisionmuninn-aether-cortexUnbounded in-memory key map; records a key before the item is storedRecordStore::create (atomic idempotency) and MemoryInput::validate
HotContextCachemuninn-aether-cortexThird copy of recent writes; serves expired session itemsRecordStore::pending_for and session_items
IngestionBuffermuninn-aether-cortexDrains before writing, so a failed flush or a crash loses dataIndexer over pending records
QueryPlannermuninn-aether-cortexSealed pipeline with no place for the developer's own steprecall::* steps
enrich_metadatamuninn-aether-cortexCopies content and version into vector metadataindex_metadata (no content; adds _aether_scope, _aether_tier)
Constant read-your-writes scores 0.75 / 0.5muninn-aether-cortexNot comparable with real similarity scoresDistanceMetric::score
Entity-name substring seed lookupmuninn-aether-cortexOnly sees local unflushed items; does nothing on a fresh processSeeds from caller plus entities of vector hits
cosine, eval_filter, value_matchesmuninn-aether-cortexDuplicates of the same logic in the in-memory backendDistanceMetric::score, FilterExpr::matches in muninn-aether-core
similarity, eval_filter, value_matchesmuninn-aether-adaptersSame duplication, other sideSame
RecordStore::put, put_if_absent, recent, deletemuninn-aether-core and every implementorNon-atomic idempotency, no pending state, hard delete that can orphan indexescreate, pending_for, tombstone
MemoryScope::Globalmuninn-aether-coreDocumented as "shared within a project", which is ProjectMemoryScope::Project
MemoryManager::new(kv, vector, graph)muninn-aether-sdkForces all three storesMemoryManager::builder(records) with .vector(..) and .graph(..)
Empty feature flags turbopuffer, qdrant, neo4j, chroma, pgvectormuninn-aether-adaptersAdvertise drivers that do not existEach flag returns with its driver in Phase 6
The word "gateway" in crate docs and commentsall cratesNo longer what Aether is"SDK", "piece", or the specific component name

3.2 Things planned in the docs that will not be built​

Drop from plansWhere it was describedWhy
WalStoreConnectors docThe record store is the log
WorkerPoolRust migration blueprintIndexer::run_pass, driven by the developer or by the opt-in Indexer::spawn
L1 cache on mokaConnectors docNo L1 cache at all until measured read latency asks for one
Queue capacity and backpressureRoadmap 5.2There is no in-memory queue left to bound
Circuit breaker in ResilientConnectors docNever existed; add it when an outage shows the need
config.rs and ConnectorRegistryConnectors docA config-driven registry that builds and wraps drivers is a gateway feature; developers construct the stores they use
HTTP/gRPC gateway serverRoadmap, blueprintAether is a library, not a service
MCP serverBlueprintSame

Python bindings are deferred, not dropped.

3.3 Repository contents​

These are removed in the last step of the work and need explicit owner sign-off first.

RemoveWhy
src/muninn_aether_sdk/ (Python package)Retired implementation; the product is the Rust workspace
tests/ (Python tests)Tests for the retired package
pyproject.tomlPackaging for the retired package
examples/quickstart.pyPython example for the retired API
Python job in .github/workflows/ci.ymlNothing left for it to test
Python content of README.mdDocuments an API that no longer exists
Python content of docs/development/guidelines.md (about 1,800 lines)Python style guide for the retired package

3.4 Documentation​

RemoveWhy
docs/architecture/rust-migration.mdA migration blueprint for a gateway. Its contracts section is replaced by the two design docs and by rustdoc; its phase list is already replaced by the roadmap
"L1 / L2 / L3" vocabularyDescribes a cache hierarchy that no longer exists; the terms become record store, vector index, graph index
"Gateway" positioning on every pageReplaced by "memory SDK"
Roadmap sections 5.1 to 5.6 as a problem listOnce fixed, they collapse into the completed-milestones list

4. What Changes​

ChangeFromTo
Storage trait nameKvStoreRecordStore
Storage trait roleL2 cache and working memoryDurable source of truth for every MemoryItem
VectorStoreHolds vector plus a copy of contentHolds vector plus filterable metadata only; gains describe
GraphStore::upsert_relationsAppends a new edge every callIdempotent per (memory, source, target, relation type)
MemoryScopeCopy enum of four labelsProject, User(UserId), Session(SessionId)
MemoryUpdateContent, embedding, metadataAlso entities and relations
RecallQueryNo scope, silently returns nothing useful without a vectorHas scopes; invalid queries return InvalidInput
forgetHard delete in three stores, in an order that can orphanTombstone, then the same indexing pipeline as a write
update with new content and no new embeddingKeeps the stale vectorInvalidInput
Session memoryWritten to vector and graph stores, where it outlives its TTLRecord store only, scored at recall time
Buffered writeSits in memory until someone flushesDurable immediately, visible to recall, indexed on flush() or by the opt-in loop
Hybrid recallVector hits; graph result returned but unusedVector and graph rankings fused with reciprocal rank fusion
MemoryManager builder defaultsTraced onlyTraced, Resilient, Timeout, each switchable
Retry backoffExponential, no jitterExponential with full jitter
Traced span op nameskv_*record_*
Cortex spansaether.cortex.enqueue, aether.cortex.flushaether.cortex.index_pass, aether.cortex.index_record
Module muninn_aether_adapters::memory_testNamed and described as test-onlymuninn_aether_adapters::in_memory, the zero-infrastructure backend
Contract testsOne test file tied to InMemoryBackendPublic muninn_aether_adapters::contract module any driver runs
muninn-aether-cortex/src/lib.rsOne 570-line fileWiring only; indexer.rs, recall.rs, ppr.rs
CIPython onlyRust fmt, clippy, test

5. What Gets Added​

AddCratePurpose
RecordStore::create, get_many, tombstone, pending, pending_for, session_items, mark_indexedmuninn-aether-coreVersioned records with indexing state
CreateOutcome, PendingRecordmuninn-aether-coreResults of the above
IndexSpec, VectorStore::describe, IndexSpec::checkmuninn-aether-coreDimension and metric known at the boundary
UserId, SessionIdmuninn-aether-coreIdentity for scopes
DistanceMetric::score, FilterExpr::matchesmuninn-aether-coreOne implementation of scoring and filtering
RecallQuery::validatemuninn-aether-coreReject unusable queries early
Indexer (apply, run_pass, spawn)muninn-aether-cortexThe sync engine
index_metadata, scope_filtermuninn-aether-cortexWhat goes into the index and how scope is filtered there
Candidate, recall::vector_search, unindexed, session, graph_search, merge, rrf, in_scopesmuninn-aether-cortexRecall as composable steps
graph_scoresmuninn-aether-cortexTurn PageRank over entities into scores for memories
jitteredmuninn-aether-adaptersRetry jitter
FaultPoint, InMemoryBackend::fail_next, has_vectormuninn-aether-adaptersFailure-path tests without a real database
contract module behind feature contract-suitemuninn-aether-adaptersSame guarantees tested on every backend
Builder options .vector, .graph, .background_indexing, .with_timeout, .with_retrymuninn-aether-sdkOptional stores, opt-in background work, switchable middleware
One runnable example per levelmuninn-aether-sdk/examplesShow each level of use on its own

6. What Stays​

  • The four crates and their names.
  • MemoryManager and its four operations: remember, recall, update, forget, plus flush and shutdown.
  • ProjectId tenant isolation at every store boundary.
  • FilterExpr and TemporalFilter.
  • Graph provenance through source_memory_id and temporal edges.
  • PersonalizedPageRank (its output is finally used).
  • The Traced, Resilient, Timeout, Batcher decorators.
  • The tracing span model and the otel preset.
  • Optimistic concurrency on update.
  • The model-free rule: no embedding, chunking, extraction, or model calls.

7. Per-Crate Summary​

CrateRemovedChangedAdded
muninn-aether-coreMemoryInbound, four RecordStore methods, MemoryScope::GlobalKvStore to RecordStore, MemoryScope, MemoryUpdate, RecallQueryVersioned record methods, IndexSpec, scope ids, score, matches, validators
muninn-aether-cortexPolicyRouter, HotContextCache, IngestionBuffer, QueryPlanner, duplicated helpersSplit into modulesIndexer, recall steps, graph_scores, index_metadata, scope_filter
muninn-aether-adaptersDuplicated helpers, empty feature flagsmemory_test to in_memory, idempotent relation upserts, middleware follows new traitFault injection, contract module, jittered
muninn-aether-sdkMemoryManager::new, impl MemoryInboundFacade rebuilt from public pieces, middleware defaultsBuilder options, per-level examples

8. Documentation After the Change​

PageAction
docs/index.mdKeep; update links
docs/architecture/index.mdRewrite around the five levels
docs/architecture/sdk-design.mdKeep; mark implemented
docs/architecture/hardening-design.mdKeep; mark implemented
docs/architecture/change-overview.md (this page)Delete once the work is done; it describes a transition
docs/architecture/connectors.mdRewrite: RecordStore role, no registry, no circuit breaker, contract module
docs/architecture/rust-migration.mdDelete
docs/guides/usage.mdRewrite: one section and one runnable example per level
docs/guides/memory.mdRewrite: roles, scopes with ids, session memory, durability
docs/guides/observability.mdUpdate span names
docs/development/guidelines.mdReplace with short Rust conventions
docs/about/roadmap.mdMove Phase 5 to completed
README.mdRewrite for the Rust SDK

9. Order of Work​

  1. Rust CI and a clean lint baseline.
  2. Shared scoring and filter functions in muninn-aether-core.
  3. Rename KvStore to RecordStore.
  4. Reusable contract suite and fault injection.
  5. Versioned record operations.
  6. Idempotent relation upserts.
  7. Indexer.
  8. Recall steps and validation as public pieces.
  9. Scopes with identity; session memory record-only.
  10. Rebuild MemoryManager from the pieces; delete MemoryInbound, QueryPlanner, PolicyRouter, HotContextCache, IngestionBuffer, and the old RecordStore methods.
  11. Middleware defaults and jitter.
  12. Rename memory_test to in_memory; remove empty feature flags; remove "gateway" wording from crate docs.
  13. Documentation, including deleting rust-migration.md.
  14. Python removal (after sign-off).

Steps 1 to 7 match tasks 1 to 7 of the earlier gateway-hardening plan. Steps 8 to 13 replace its tasks 8 to 13, which were written for the gateway shape and have not been revised yet.

10. Production Impact​

None. Nothing is published, no production driver exists, and no data is stored anywhere outside tests. Every public Rust API listed in sections 3 and 4 changes in a breaking way, with no deprecation period, because there are no users to migrate.

11. Decisions Still Waiting on the Owner​

  1. Approval of the pieces-first SDK design as a whole.
  2. Sign-off to delete the Python package (section 3.3).
  3. Three removals introduced on this page and not yet in an approved design: the empty driver feature flags, the planned config.rs / ConnectorRegistry, and docs/architecture/rust-migration.md.