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(())
}