Install dependencies

pip install chromadb lancedb python-dotenv requests numpy pip install -e sochdb-python-sdk/

Run real embedding benchmark (requires Azure OpenAI credentials in .env)

SOCHDB_LIB_PATH=target/release python3 benchmarks/real_embedding_benchmark.py

Prerequisites

• Rust 2024 edition (1.75+)
• Clang/LLVM (for SIMD optimizations)

Installation

Choose your preferred SDK:

```bash

🐳 Docker Deployment

SochDB includes a production-ready Docker setup with gRPC server:

```bash

Pull and run from Docker Hub

docker pull sochdb/sochdb:latest docker run -d -p 50051:50051 sochdb/sochdb:latest

Or use docker-compose

cd docker docker compose up -d ```

Docker Hub: sochdb/sochdb

Features: - ✅ Production-ready image (159MB) - ✅ High availability setup with Traefik - ✅ Prometheus + Grafana monitoring - ✅ gRPC-Web support via Envoy - ✅ Comprehensive test suite included

Performance (tested on Apple M-series): - Single-threaded: ~2K ops/sec - Concurrent (10 threads): ~10.5K ops/sec - Latency p99: <2.2ms

See docker/README.md for full documentation. | Node.js/TypeScript | sochdb-nodejs-sdk | npm install @sochdb/sochdb | | Go | sochdb-go | go get github.com/sochdb/sochdb-go@latest | | Rust | This repository | cargo add sochdb |

Build conversation graph

graph.add_node("msg_1", {"role": "user", "content": "What's the weather?"}) graph.add_node("msg_2", {"role": "assistant", "content": "Let me check..."}) graph.add_node("msg_3", {"role": "tool", "content": "Sunny, 72°F"}) graph.add_node("msg_4", {"role": "assistant", "content": "It's sunny and 72°F"})

Build context with token budgeting

context = ( ContextQuery(collection) .add_vector_query(query_embedding, weight=0.7) .add_keyword_query("machine learning optimization", weight=0.3) .with_token_budget(4000) # Fit within model context window .with_min_relevance(0.5) # Filter low-quality results .with_deduplication(DeduplicationStrategy.EXACT) .execute() )

Build the index

index.build()

📊 Context Query Builder

Build LLM context with automatic token budget management.

use sochdb_query::{ContextSection, ContextSelectQuery};
use sochdb::ContextQueryBuilder;

let context = ContextQueryBuilder::new()
    .for_session("session_123")
    .with_budget(4096)  // Token budget
    
    // System prompt (highest priority)
    .literal("SYSTEM", -1, "You are a helpful assistant")
    
    // User profile from database
    .section("USER", 0)
        .get("user.profile.{name, email, preferences}")
        .done()
    
    // Recent conversation history
    .section("HISTORY", 1)
        .last(10, "messages")
        .where_eq("session_id", session_id)
        .done()
    
    // Relevant documents via vector search
    .section("DOCS", 2)
        .search("knowledge_base", "query_embedding", 5)
        .min_score(0.7)
        .done()
    
    .truncation(TruncationStrategy::PriorityDrop)
    .format(ContextFormat::Soch)
    .execute()?;

println!("Tokens used: {}/{}", context.token_count, 4096);
println!("Context:\n{}", context.context);

---

Install Python 3.12 (recommended for ChromaDB compatibility)

brew install python@3.12 python3.12 -m venv .venv312 source .venv312/bin/activate

Build SochDB release library

cargo build --release

🔧 Building from Source

Build

```bash

Build all crates

cargo build --release

📦 Quick Start

Examples

• Python Examples: sochdb-python-examples
• Node.js Examples: sochdb-nodejs-examples
• Go Examples: sochdb-golang-examples

Hello World

Python

from sochdb import Database

db = Database.open("./my_db")
db.put(b"users/alice", b"Alice Smith")
print(db.get(b"users/alice").decode())  # "Alice Smith"
db.close()

Node.js / TypeScript

import { SochDatabase } from '@sochdb/sochdb';

const db = new SochDatabase('./my_db');
await db.put('users/alice', 'Alice Smith');
console.log(await db.get('users/alice'));  // "Alice Smith"
await db.close();

Go

package main

import (
    "fmt"
    sochdb "github.com/sochdb/sochdb-go"
)

func main() {
    db, _ := sochdb.Open("./my_db")
    defer db.Close()
    
    db.Put([]byte("users/alice"), []byte("Alice Smith"))
    value, _ := db.Get([]byte("users/alice"))
    fmt.Println(string(value))  // "Alice Smith"
}

Rust

use sochdb::Database;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = Database::open("./my_db")?;
    
    db.put(b"users/alice", b"Alice Smith")?;
    if let Some(value) = db.get(b"users/alice")? {
        println!("{}", String::from_utf8_lossy(&value));  // "Alice Smith"
    }
    Ok(())
}

Vector Search Example

Python

```python from sochdb import VectorIndex import numpy as np

Configuration

use sochdb_index::{HNSWIndex, HNSWConfig, DistanceMetric};

// Create index with custom parameters
let config = HNSWConfig {
    m: 16,                          // Max connections per layer
    m_max: 32,                      // Max connections at layer 0
    ef_construction: 200,           // Build-time search width
    ef_search: 50,                  // Query-time search width
    metric: DistanceMetric::Cosine, // Or Euclidean, DotProduct
    ..Default::default()
};

let index = HNSWIndex::with_config(config);

Option 1: Context manager (auto-flush)

with index.batch_accumulator(estimated_size=50_000) as acc: acc.add(ids, vectors) # Zero FFI, pure numpy memcpy

Option 2: Explicit control

acc = index.batch_accumulator(50_000) acc.add(chunk1_ids, chunk1_vecs) acc.add(chunk2_ids, chunk2_vecs) inserted = acc.flush() # Single bulk FFI call → full Rayon parallelism

Option 3: Cross-process persistence

acc.save("/tmp/vectors") # Persist to disk acc2 = index.batch_accumulator() acc2.load("/tmp/vectors") # Load in another process acc2.flush() # Build HNSW ```

Optional Ordered Index

SochDB's ordered index can be disabled for write-optimized workloads:

use sochdb::ConnectionConfig;

// Default: ordered index enabled (O(log N) prefix scans)
let config = ConnectionConfig::default();

// Write-optimized: disable ordered index (~20% faster writes)
let mut config = ConnectionConfig::default();
config.enable_ordered_index = false;
// Note: scan_prefix becomes O(N) instead of O(log N + K)

---

🛠 Configuration Reference

DatabaseConfig

pub struct DatabaseConfig {
    /// Enable group commit for better throughput
    pub group_commit: bool,           // default: true
    
    /// WAL sync mode
    pub sync_mode: SyncMode,          // default: Normal
    
    /// Maximum WAL size before checkpoint
    pub max_wal_size: u64,            // default: 64MB
    
    /// Memtable size before flush
    pub memtable_size: usize,         // default: 4MB
    
    /// Block cache size
    pub block_cache_size: usize,      // default: 64MB
    
    /// Compression algorithm
    pub compression: Compression,      // default: LZ4
}

HNSWConfig

pub struct HNSWConfig {
    /// Max connections per node per layer
    pub m: usize,                     // default: 16
    
    /// Max connections at layer 0
    pub m_max: usize,                 // default: 32
    
    /// Construction-time search width
    pub ef_construction: usize,       // default: 200
    
    /// Query-time search width (adjustable)
    pub ef_search: usize,             // default: 50
    
    /// Distance metric
    pub metric: DistanceMetric,       // default: Cosine
    
    /// Level multiplier (mL = 1/ln(M))
    pub ml: f32,                      // default: calculated
}

---

SDK Repositories

Language SDKs are maintained in separate packages and repos with their own release cycles:

SDK Feature Matrix

Note: While SDKs are maintained in separate repositories, they share the same core functionality and API design. Refer to individual SDK repositories for language-specific documentation and examples.

---

High-Throughput Ingestion (Python SDK)

The Python SDK's BatchAccumulator provides 4–5× faster inserts by deferring HNSW graph construction:

```python from sochdb import VectorIndex import numpy as np

index = VectorIndex(dimension=1536, max_connections=16, ef_construction=200)

🌳 Path API

SochDB's unique path-based API provides O(|path|) resolution via the Trie-Columnar Hybrid (TCH) structure.

📚 API Reference

🔌 Plugin System

SochDB uses a plugin architecture for extensibility without dependency bloat.

Extension Types

Implementing a Plugin

use sochdb_kernel::{Extension, ExtensionInfo, ObservabilityExtension};

struct PrometheusMetrics { /* ... */ }

impl Extension for PrometheusMetrics {
    fn info(&self) -> ExtensionInfo {
        ExtensionInfo {
            name: "prometheus-metrics".into(),
            version: "1.0.0".into(),
            description: "Prometheus metrics export".into(),
            author: "Your Name".into(),
            capabilities: vec![ExtensionCapability::Observability],
        }
    }
    
    fn as_any(&self) -> &dyn std::any::Any { self }
    fn as_any_mut(&mut self) -> &mut dyn std::any::Any { self }
}

impl ObservabilityExtension for PrometheusMetrics {
    fn counter_inc(&self, name: &str, value: u64, labels: &[(&str, &str)]) {
        // Push to Prometheus
    }
    
    fn gauge_set(&self, name: &str, value: f64, labels: &[(&str, &str)]) {
        // Set gauge value
    }
    
    fn histogram_observe(&self, name: &str, value: f64, labels: &[(&str, &str)]) {
        // Record histogram
    }
    
    // ... tracing methods
}

// Register the plugin
db.plugins().register_observability(Box::new(PrometheusMetrics::new()))?;

---

Comparison

Token Comparison

┌─────────────────────────────────────────────────────────────────┐
│                      JSON (156 tokens)                          │
├─────────────────────────────────────────────────────────────────┤
│ [                                                               │
│   {"id": 1, "name": "Alice", "email": "alice@example.com"},    │
│   {"id": 2, "name": "Bob", "email": "bob@example.com"},        │
│   {"id": 3, "name": "Charlie", "email": "charlie@example.com"} │
│ ]                                                               │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                      TOON (52 tokens) — 67% reduction!          │
├─────────────────────────────────────────────────────────────────┤
│ users[3]{id,name,email}:                                        │
│ 1,Alice,alice@example.com                                       │
│ 2,Bob,bob@example.com                                           │
│ 3,Charlie,charlie@example.com                                   │
└─────────────────────────────────────────────────────────────────┘

VectorDBBench: 50K-Vector Comparison (SochDB vs ChromaDB vs LanceDB)

We benchmarked SochDB against ChromaDB and LanceDB using VectorDBBench — the industry-standard open-source benchmark from Zilliz. All databases ran on the same hardware in embedded mode. SochDB and ChromaDB use HNSW indexes; LanceDB uses IVF_PQ.

<p align="center"> <img src="docs/assets/benchmark_comparison.svg" alt="SochDB vs ChromaDB vs LanceDB benchmark comparison" width="800" /> </p>

#### Test Setup - Dataset: COHERE/OpenAI 50,000 vectors × 768–1536 dimensions - Queries: VectorDBBench standard query set (k=100) - Distance Metric: Cosine similarity - Ground Truth: VectorDBBench precomputed ground truth (brute-force) - Processes: Insert, optimize, and search in separate subprocesses (VectorDBBench default)

Configuration

Results

\* LanceDB recall is lower due to IVF_PQ (lossy compression) vs HNSW (graph-based exact search).

Key Findings

• 🏎️ SochDB search is 4.7× faster than ChromaDB (3.3 ms vs 15.4 ms average)
• 🏎️ SochDB search is 1.7× faster than LanceDB (3.3 ms vs 5.6 ms average)
• ⚡ SochDB total load is 5.6× faster than ChromaDB (13.7 s vs 76.9 s)
• ⚡ SochDB total load is 1.5× faster than LanceDB (13.7 s vs 21.0 s)
• 🎯 SochDB recall (98.99%) is within 1% of ChromaDB while being 4.7× faster
• ⚠️ LanceDB recall (65.74%) is significantly lower due to IVF_PQ lossy compression vs HNSW

How SochDB Achieves Fast Inserts: BatchAccumulator

SochDB's Python SDK includes a BatchAccumulator API that separates data accumulation from HNSW graph construction:

┌────────────────────────────────────────────────────────────────────┐
│                    BatchAccumulator Pipeline                       │
├───────────────────────┬──────────────────────────────────────────┤
│  Phase 1: Accumulate  │  Phase 2: Flush                          │
│  ──────────────────── │  ─────────────────                        │
│  • add(ids, vecs)     │  • Single insert_batch() FFI call        │
│  • Pure numpy memcpy  │  • Full Rayon parallel HNSW build        │
│  • Zero FFI calls     │  • Wave-parallel (32-node waves)         │
│  • ~0.05 s for 50K    │  • Adaptive ef (capped at 48)            │
│                       │  • ~13.7 s for 50K vectors               │
└───────────────────────┴──────────────────────────────────────────┘

```python from sochdb import VectorIndex

index = VectorIndex(dimension=1536, max_connections=16, ef_construction=200)

MemoryAgentBench: Head-to-Head RAG Comparison

Version: 2.0.0 | Benchmark Date: February 2026 | LLM: Azure OpenAI gpt-4.1-mini | Framework: MemoryAgentBench (UCSD)

We evaluated SochDB head-to-head against 7 RAG competitors using MemoryAgentBench — an academic benchmark from UCSD that tests how well memory systems help LLMs retrieve facts from multi-turn conversations over long contexts (up to 197K+ tokens).

<p align="center"> <img src="docs/assets/head_to_head_benchmark.svg" alt="SochDB vs RAG competitors head-to-head benchmark" width="800" /> </p>

Head-to-Head Results (gpt-4.1-mini, Ruler QA1 197K, 20 queries)

All systems completed 20/20 queries except RAPTOR. SochDB V2 solved 4 queries that NO other system could: Q2 (Denmark, Iceland and Norway), Q7 (Catholic), Q11 (King Charles III), Q12 (Epte). Self-RAG results impacted by Azure content filter rejecting self-reflection prompts (~50% of queries blocked).

Key Findings — Head-to-Head

• 🏆 SochDB V2 dominates at 60% EM — 2× the previous best (30%), 2.4× better than GraphRAG (25%)
• 🏆 V2 solves 4 previously-impossible queries via Multi-Perspective RRF (3 embedding angles) + Few-Shot Precision Extraction
• 🏆 SochDB is the only embedded system — zero external dependencies (no LangChain, spaCy, FAISS, or network services)
• 🏆 V2 query time is 18× faster than HyDE v1 (2.1s vs 37.0s) and 6× faster than GraphRAG (11.9s)
• 📊 GraphRAG is limited by ContextualCompressionRetriever — reduces context to ~848 tokens (vs SochDB's ~80K)
• ⚡ SochDB Hybrid is 40× faster than any competitor (0.8s query) while still competitive at 20% EM
• 🧩 BM25 has surprisingly high substring match (70%) but low exact match (10%) — retrieves relevant docs but can't extract precise answers
• 📉 Embedding RAG and Mem0 tied at 5% EM — basic vector similarity alone is insufficient for long-context QA

#### Test Setup - Dataset: Ruler QA1 197K (197,000-token context, 100 QA pairs, key-value retrieval) - Embeddings: Azure OpenAI text-embedding-3-small (1536D) - LLM: gpt-4.1-mini (all systems use the same LLM for fair comparison) - Competitors tested: GraphRAG, Self-RAG, BM25, Embedding RAG (FAISS), Mem0, RAPTOR - Task: Accurate Retrieval — memorize long conversations, then answer factual queries - Queries: 20 per system (max_test_queries_ablation=20) - Metrics: Exact match, F1, substring match, ROUGE-L (standard MemoryAgentBench metrics)

SochDB Configuration Comparison

📘 Developer Configuration Guide

TL;DR: Use Rerank for most use cases. Use HyDE when exact match is critical. Use baseline for real-time. Never stack all features together — it's slower and less accurate.

Key decision factors:

1. Retrieval strategy matters more than model size. Upgrading from gpt-4.1-mini → gpt-4.1 (full) gave identical 20% EM. But adding HyDE to gpt-4.1-mini boosted EM to 30% (+50% improvement). Invest in retrieval, not bigger LLMs.

1. Don't stack features. The Advanced config (HyDE + Hybrid + Rerank combined) scored worse than HyDE or Rerank alone (25% EM, 35% Sub-EM). Each feature adds its own noise — pick the one that matches your use case.

1. Rerank is the best all-rounder. It's 27% faster than HyDE (27.9s vs 37.0s query time), has the highest substring match (50%), near-equivalent F1 (40.2% vs 42.6%), and only 5pp behind HyDE on exact match.

Understanding Substring Match (Sub-EM)

What it measures: Does the gold answer appear anywhere inside the prediction, or vice versa?

Substring match is not a pure accuracy metric — it correlates with answer verbosity. Here's why different configs score differently:

Example: Gold answer is "Catholic" - Baseline predicts "Orthodox" → Sub-EM ❌ (short, no overlap) - Rerank predicts "Catholic orthodoxy" → Sub-EM ✅ (gold is a substring) - Mem0 predicts "The predominant religion was Catholic Christianity" → Sub-EM ✅ (verbose, gold appears)

⚠️ For developers: High Sub-EM with low EM (like Mem0: 5% EM / 30% Sub-EM) means the system is vaguely right but imprecise. High EM with proportional Sub-EM (like HyDE: 30% EM / 45% Sub-EM) means the system gives useful answers. Rerank's 50% Sub-EM with 25% EM is the sweet spot — it frequently gets the right entity even if not the exact formatting.

Key Findings

• 🏆 SochDB + HyDE achieves 6× higher exact match than Mem0 (30.0% vs 5.0%)
• 🏆 SochDB + Rerank is the recommended config — best substring match (50%) with strong F1 (40.2%) and 27% faster than HyDE
• ⚡ SochDB builds memory 5,170× faster than Mem0 (0.01s vs 51.7s)
• 🧠 Retrieval strategy > model size: gpt-4.1 = gpt-4.1-mini at same retrieval (both 20% EM), but HyDE on mini → 30% EM
• ⚠️ Don't stack all features: Advanced (HyDE+Hybrid+Rerank) scores worse than using HyDE or Rerank independently
• 📊 Substring match tracks answer verbosity, not pure accuracy — use EM and F1 for quality decisions

Multi-Dataset Results (SochDB, 100 queries)

Note: Multi-dataset runs used gpt-4o-mini/gpt-4.1-mini with k=100. QA2 achieved higher accuracy than QA1 due to more distinctive key-value patterns.

Why SochDB is Different

1. No External Dependencies: SochDB is the only system in this benchmark that requires zero Python packages for its core operation. GraphRAG needs LangChain + spaCy + FAISS + NER. Self-RAG needs custom retrieval chains. Even BM25 needs a ranking library. SochDB runs as an embedded Rust library via FFI.

1. Reliable Under Pressure: SochDB completed 100% of queries (20/20) on every configuration. GraphRAG failed 50% due to API rate limits during NER extraction. RAPTOR couldn't even start. Self-RAG was blocked by content filters.

1. Memory Build Speed: SochDB stores embeddings directly in its HNSW index — no LLM calls during memorization. GraphRAG needs LLM NER calls per document chunk (10× slower). Mem0 processes each memory through an extraction pipeline (5,170× slower).

1. Retrieval Quality: SochDB's HyDE generates a synthetic answer before searching, bridging the question-document gap. This single technique (zero external dependencies) achieves 75% of GraphRAG's accuracy with 10× faster build and 100% completion rate.

1. Honest Assessment: GraphRAG's knowledge graph approach is genuinely more accurate on the queries it completes. For applications where reliability and deployment simplicity matter more than peak accuracy, SochDB is the better choice. For research workloads with high API quotas, GraphRAG is worth considering.

---

Token Efficiency (TOON vs JSON)

---

KV Performance (vs SQLite)

Methodology: SochDB vs SQLite under similar durability settings (WAL mode, synchronous=NORMAL). Results on Apple M-series hardware, 100k records.

---

Run Rust benchmarks (SochDB vs SQLite)

cargo run -p benchmarks --release ```

Note: Performance varies by workload. SochDB excels in LLM context assembly scenarios (token-efficient output, vector search, context budget management). SQLite remains the gold standard for general-purpose relational workloads.

---