Where data flows.

Three end-to-end animated diagrams: write path (memory_store), read path (memory_recall with hybrid fusion), and federation (W-of-N quorum sync). Every box is a real function in src/storage/ or src/handlers/; every arrow is a real call.

Write Path · memory_store

How a memory becomes durable.

Validation → embedding → SQLite insert → HNSW index update → federation fanout. The full path takes ~9-86ms p95 depending on whether embedding is requested.

The dashed boxes are tier-gated. The keyword tier skips embed + auto_tag + HNSW; it stores into SQLite + FTS5 only. The semantic tier turns on embed + HNSW. The smart tier adds auto_tag. The autonomous tier additionally turns on the curator daemon for background work.

Read Path · memory_recall

Hybrid recall: FTS5 + HNSW + reranker, fused.

memory_recall combines three retrieval modalities and reconciles them into one ranked result set. Each modality has different strengths; the fusion model produces something none of them could alone. p95 hot-path: 18ms.

The 70/30 contextual fusion (v0.6.0 feature)

When the caller passes context_tokens=[...], the recall biases the query embedding toward recent conversation:

primary embedding

70%

embed(query) — what the caller explicitly asked. Anchors the recall.

context embedding

30%

embed(context_tokens.join(" ")) — recent conversation tokens. Biases toward "what the agent is currently thinking about".

weighted sum

raw

Final query vector = 0.7·primary + 0.3·context, deliberately un-normalized — cosine similarity divides out magnitudes downstream, so only direction matters (Embedder::fuse).

Why fusion beats either alone. Pure keyword (FTS5) misses paraphrase. Pure vector (HNSW) drifts on rare terms. Pure rerank is too slow for hot path. The hybrid path uses each where it wins: BM25 for exact terms, vector for semantic neighbors, reranker only on the candidate union (top ~20 → top K). The 70/30 contextual blend is the v0.6.0 addition that makes recall feel "in-flow" with the agent's current task.

Federation · W-of-N Quorum

Multi-machine sync without a coordinator.

Each node accepts writes locally and fans out to peers via mTLS. The local commit lands first; the quorum (default W=2, counting the local commit) is met once W−1 peers ack within the deadline. Eventual consistency. Per-peer cursors for catchup after partition. Federation private endpoints under /api/v1/sync/*.

local first

Reads always serve from local SQLite. Zero network call. Sub-50ms regardless of peer state.

quorum write

Local commit lands first; the write returns 200 once W is met — the local commit plus W−1 peer ACKs within the deadline. Default W=2 (majority).

catchup loop

Detached peer catches up on rejoin via per-peer cursor. Convergent within one catchup_interval (default 30s).

What if quorum can't be reached? The leader returns 503 with structured peer status: which peers responded, which timed out, when the deadline hit. No silent partial writes. Caller can retry or escalate to the operator. The failure payload includes error classification (QuorumFailureReason: Unreachable / Timeout / IdDrift / InFlight; QuorumError: InvalidPolicy / LocalWriteFailed).