Replication

How Basis instances stay in sync across peers using Strand replication.

What this page covers

Basis itself owns no networking. Replication happens at the Strand layer beneath it. This page explains the model: how two peers converge on the same vector corpus, what guarantees hold, and what to be careful about.

The replication model

Each Basis writes to a vector_strand. That strand is the only thing that needs to cross the network. A peer that has the strand bytes can construct a Basis on top and answer queries locally.

   Peer A                                 Peer B
   ──────                                 ──────
   Basis::add(id, vec)                    
        │                                 
        ▼                                 
   vector_strand.append(...)              
        │                                 
        │  Strand replication             
        │  (weave-dht / weave-swarm)      
        └───────────────────────────────► vector_strand.append(...)
                                                  │
                                                  ▼
                                          Basis on Peer B sees the
                                          new block on next rebuild

Reads on Peer B do not see the new vector until its Basis instance has replayed the new strand block into the HNSW graph.

Wiring it through the SDK

The WeaveNode SDK opens a Basis instance under a name and handles the strand pair internally:

use weave_sdk::prelude::*;
use uuid::Uuid;

#[tokio::main]
async fn main() -> WeaveResult<()> {
    let node = WeaveNode::builder()
        .namespace("l1fe")
        .identifier("semantic-agent")
        .storage_dir("/tmp/weave-semantic")
        .build()
        .await?;

    node.open_basis("memory").await?;

    let id = Uuid::new_v4();
    node.basis_add("memory", id, &[0.1, 0.2, 0.3, 0.4]).await?;

    // Strand replication runs in the background once the node joins the network.
    node.start_network().await?;
    node.start_auto_replication().await?;

    let neighbors = node.basis_search("memory", &[0.1, 0.2, 0.3, 0.4], 5).await?;
    println!("{} neighbors found", neighbors.len());
    Ok(())
}

Convergence guarantees

Property	Holds?	Notes
Eventual consistency on `Add` blocks	Yes	Strand is append-only, blocks are content-addressed
Total order across peers	Yes (per-writer)	A single Strand has a single writer; multiple writers require Nexus
Index identity (HNSW graph shape)	No	HNSW is randomized; two peers may build different graphs over the same vectors
Search result identity	Approximate	Two peers may return different `k`-NN orderings near ties

Search result drift across peers is bounded by the HNSW recall margin. For applications that require bitwise-identical results, store the embedding pipeline output and use Basis as a recall filter, then re-rank deterministically on the caller side.

Multi-writer corpora

Basis writes through one vector_strand. To accept inserts from multiple agents, route the writes through a Nexus that merges several upstream strands into a single materialized view; the Basis then reads from that view's strand.

Topology	Mechanism
Single writer, many readers	Plain Strand replication
Multi-writer, append-only	Nexus → materialized strand → Basis
Multi-writer with deletes	Today: split corpus by writer, query each Basis, merge on the caller

What to monitor

Replication latency — WeaveNode::peer_count and replication_addr; if peer count is zero, no progress is happening.
Strand divergence — Strand exposes head sequence; compare across peers for lag.
Memory pressure on the receiver — every Add block consumes RAM in the HNSW graph.