The MentisDB Agent Memory Cookbook

3.2 Vector Sidecar Management

The chain log is canonical. A vector sidecar is a derived index that can be rebuilt from the log at any time. Treat sidecars as durable caches: useful, integrity-checked, but never the source of truth.

The pattern

• Build or load a sidecar with manage_vector_sidecar.
• Let managed sidecars sync on append for the current handle.
• Use status APIs to detect stale or missing indexes.
• Rebuild from the chain log when metadata, model version, or head hash changes.

fn manage_vector_sidecar_lifecycle() -> io::Result<()> {
    let dir = tempfile::tempdir()?;
    let adapter = BinaryStorageAdapter::for_chain_key(dir.path(), "cookbook-sidecars");
    let mut chain = MentisDb::open_with_storage(Box::new(adapter))?;

    chain.upsert_agent(
        "search-agent",
        Some("Search Agent"),
        Some("memory-team"),
        Some("Maintains vector sidecars"),
        None,
    )?;
    chain.append_thought(
        "search-agent",
        ThoughtInput::new(
            ThoughtType::Decision,
            "Use local embeddings for offline semantic search during development.",
        )
        .with_concepts(["embeddings", "offline-search"]),
    )?;

    let provider = mentisdb::search::LocalTextEmbeddingProvider::new();
    let sidecar = chain
        .manage_vector_sidecar(provider)
        .map_err(|error| io::Error::other(format!("{error:?}")))?;
    assert_eq!(sidecar.entries.len(), 1);

    chain.append_thought(
        "search-agent",
        ThoughtInput::new(
            ThoughtType::Insight,
            "Managed sidecars update on append for the open handle.",
        )
        .with_concepts(["embeddings", "sidecar-sync"]),
    )?;

    let statuses = chain.managed_vector_sidecar_statuses()?;
    assert!(statuses.iter().any(|status| {
        status.provider_key == "local-text-v1" && status.sidecar_exists
    }));

    let result = chain.query_ranked(
        &RankedSearchQuery::new()
            .with_text("offline semantic search")
            .with_limit(3),
    );
    assert!(!result.hits.is_empty());
    Ok(())
}

Incremental WAL (0.10.6+)

Appends no longer rewrite the full JSON snapshot. MentisDB writes one integrity-chained record to a sibling *.json.wal (magic MDBVWAL1). Load verifies the snapshot digest, then replays the WAL. After 32 records the snapshot is compacted and the WAL is deleted. Older binaries that only read JSON treat a sidecar with a pending WAL as stale and rebuild from the chain.