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/db.rs or src/handlers.rs; 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.

▸ INPUT ▸ src/db.rs::store ▸ POST-WRITE Memory{}title, content, ns, tier validate_* enforce_governance check_duplicate?if threshold set resolve_agent_id embed (Candle)semantic+ tier auto_tag (LLM)smart+ tier SQLite INSERT FTS5 trigger HNSW insertif embed present contradict? fanout_or_503W-of-N peers dispatch_eventwebhook subs return Memorywith id caller9-86ms p95
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.

▸ QUERY ▸ THREE PARALLEL RETRIEVALS ▸ FUSION + RERANK ▸ RESULT query+ ns + filters context_tokensrecent conv FTS5 keyword (BM25) embed(query) → HNSW search embed(ctx_tokens) · 70/30 fusecontextual recall (v0.6.0) keyword candidates {id, score} vector candidates {id, cosine} vector + ctx blend (Embedder::fuse) db::recall_hybridunion + score blend cross-encoder rerankautonomous tier budgettokens scopevisibility TTL exttouch hits top-K ranked18ms p95 hot

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".

L2-renormalize

unit

Final query vector = unit-norm(0.7·primary + 0.3·context). Same magnitude as either input — drop-in for HNSW search.

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. Quorum threshold W of N (default 2 of 3) must ack before commit. Eventual consistency. Per-peer cursors for catchup after partition. Federation private endpoints under /api/v1/sync/*.

node-1 (leader) accepts the write SQLite + WAL node-2 ACK ✓ 240ms replica node-3 ACK ✓ 410ms replica node-4 offline · partitioned catchup pending ▼ mTLS · pinned cert W=2 of N=3 reached → COMMIT leader returns 200 to caller after 410ms (slowest of 2 acks) when node-4 returns: GET /api/v1/sync/since?cursor=... advances local state

local first

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

quorum write

Writes return 200 only after W peers ACK. Slowest ACK determines latency. Default W=2.

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 QuorumNotMetPayload includes per-peer error classification (Unreachable / IdDrift / InFlight / InvalidPolicy / LocalWriteFailed).