{"id":39745829,"url":"https://github.com/sochdb/sochdb","last_synced_at":"2026-06-13T23:05:10.029Z","repository":{"id":331999276,"uuid":"1126115972","full_name":"sochdb/sochdb","owner":"sochdb","description":"SochDB is a high-performance embedded, ACID-compliant vector database purpose-built for AI agents and memory","archived":false,"fork":false,"pushed_at":"2026-06-13T16:30:55.000Z","size":79204,"stargazers_count":31,"open_issues_count":1,"forks_count":5,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-13T18:24:03.459Z","etag":null,"topics":["ai-agents","ai-agents-mcp","ai-agents-memory","database","embeddings","knowledge","knowledge-graph","knowledge-graph-embeddings","knowledge-graphs-embeddings","llm","llm-databases","llms","toon","vector-database","vector-database-python","vector-databases"],"latest_commit_sha":null,"homepage":"https://sochdb.dev","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sochdb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-01T06:26:46.000Z","updated_at":"2026-06-13T16:30:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"bb416e6b-1252-4727-9250-0823908ffb36","html_url":"https://github.com/sochdb/sochdb","commit_stats":null,"previous_names":["toondb/toondb","sochdb/sochdb"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/sochdb/sochdb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sochdb%2Fsochdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sochdb%2Fsochdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sochdb%2Fsochdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sochdb%2Fsochdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sochdb","download_url":"https://codeload.github.com/sochdb/sochdb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sochdb%2Fsochdb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34301880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-agents-mcp","ai-agents-memory","database","embeddings","knowledge","knowledge-graph","knowledge-graph-embeddings","knowledge-graphs-embeddings","llm","llm-databases","llms","toon","vector-database","vector-database-python","vector-databases"],"created_at":"2026-01-18T11:20:42.518Z","updated_at":"2026-06-13T23:05:10.001Z","avatar_url":"https://github.com/sochdb.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/sochdb/sochdb/raw/main/sochdbicon.png\" alt=\"SochDB icon\" width=\"150\" height=\"150\" /\u003e\n    \u003cbr\u003e\n\u003c/h1\u003e\n\n## What is SochDB?\n\nSochDB is a **single database** that replaces your vector DB + relational DB + prompt packer stack. Store structured data, embeddings, and conversation history together—then ask SochDB to assemble token-optimized context for your LLM.\n\n## Comparison\n\n### Database + retrieval layer\n\n| Feature | SochDB | SQLite + vec | Postgres + pgvector | Chroma | LanceDB |\n|---------|--------|--------|----------------------|--------|---------|\n| Embedded | ✅ | ✅ | ❌ | ✅ | ✅ |\n| Vector search | ✅ HNSW | ⚠️ (via extension) | ✅ (HNSW / IVFFlat) | ✅ | ✅ |\n| Full SQL (user-facing) | ✅ SQL-92 | ✅ | ✅ | ❌ | ✅ |\n| Hybrid search (vector + keyword) | ✅ | ⚠️ (DIY) | ⚠️ (DIY) | ⚠️ (limited) | ✅ |\n| Context builder | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Token budgeting | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Graph overlay | ✅ | ❌ | ❌ | ❌ | ❌ |\n| ACID transactions | ✅ | ✅ | ✅ | ⚠️ (limited) | ❌ |\n| Columnar storage | ✅ | ❌ | ❌ | ❌ | ✅ |\n\n\n### Memory / agent-memory layer\n\n| Feature | SochDB | Mem0 | Letta | Graphiti |\n|--------|--------|------|-------|----------|\n| Primary focus | DB + retrieval + context | Memory layer | Agent framework + memory | Temporal knowledge-graph memory |\n| Long-term memory primitives | ✅ | ✅ | ✅ | ✅ |\n| Token-aware context budgeting | ✅ | ❌ | ❌ | ❌ |\n| Graph-based memory | ✅ | ❌ | ❌ | ✅ |\n| Built-in vector store | ✅ | ❌ (BYO) | ❌ (BYO) | ❌ (BYO) |\n| Built-in agent runtime | ❌ | ❌ | ✅ | ❌ |\n| Drop-in “memory add-on” to existing apps | ✅ | ✅ | ⚠️ | ✅ |\n\n\n**Quick links:** [📚 Documentation](https://sochdb.dev) • [Quick Start](#-quick-start) • [Architecture](#-architecture) • [TOON Format](#-toon-format) • [Benchmarks](#-benchmarks) • [RFD](docs/rfds/RFD-001-ai-native-database.md)\n\n---\n\n## Why SochDB?\n\n### ❌ The Typical AI Agent Stack\n\n```\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│                              YOUR APPLICATION                                    │\n└───────┬─────────────────┬─────────────────┬─────────────────┬───────────────────┘\n        │                 │                 │                 │\n        ▼                 ▼                 ▼                 ▼\n┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────────────────┐\n│   Postgres    │ │   Pinecone    │ │    Redis      │ │    Custom Code            │\n│   (metadata)  │ │   (vectors)   │ │  (sessions)   │ │    (context assembly)     │\n│               │ │               │ │               │ │                           │\n│ • User data   │ │ • Embeddings  │ │ • Chat state  │ │ • Token counting          │\n│ • Settings    │ │ • Similarity  │ │ • Cache       │ │ • Truncation logic        │\n│ • History     │ │   search      │ │ • Temp data   │ │ • Prompt packing          │\n│               │ │               │ │               │ │ • Multi-source fusion     │\n└───────────────┘ └───────────────┘ └───────────────┘ └───────────────────────────┘\n        │                 │                 │                 │\n        └─────────────────┴─────────────────┴─────────────────┘\n                                    │\n                    ┌───────────────┴───────────────┐\n                    │  😰 You manage all of this:   │\n                    │  • 4 different query languages │\n                    │  • 4 sets of credentials       │\n                    │  • 4 failure modes             │\n                    │  • No cross-system transactions│\n                    │  • Weeks of glue code          │\n                    └───────────────────────────────┘\n```\n\n### ✅ With SochDB\n\n```\n┌─────────────────────────────────────────────────────────────────────────────────┐\n│                              YOUR APPLICATION                                    │\n└─────────────────────────────────────┬───────────────────────────────────────────┘\n                                      │\n                                      ▼\n                    ┌─────────────────────────────────────┐\n                    │             SochDB                   │\n                    │                                      │\n                    │   SQL + Vectors + Context Builder    │\n                    │                                      │\n                    │   • One query language               │\n                    │   • One connection                   │\n                    │   • ACID transactions                │\n                    │   • Token budgeting built-in         │\n                    │                                      │\n                    └─────────────────────────────────────┘\n                                      │\n                    ┌─────────────────┴─────────────────┐\n                    │  😎 What you actually ship:       │\n                    │  • Single ~700KB embedded DB      │\n                    │  • Zero external dependencies     │\n                    │  • Works offline                  │\n                    │  • Deploys anywhere               │\n                    └───────────────────────────────────┘\n```\n\n### The Problem → Solution\n\n| Challenge | Traditional Stack | SochDB |\n|-----------|------------------|--------|\n| **Token waste** | JSON/SQL bloat in prompts | TOON format for dense output |\n| **RAG plumbing** | Separate vector DB + glue code | Built-in HNSW with hybrid search |\n| **Context assembly** | Custom packer per use case | One query with token budget |\n| **I/O overhead** | Multiple DB round-trips | Single columnar read |\n| **Consistency** | Distributed transaction headaches | Local ACID guarantees |\n| **Deployment** | Manage 4 services | Single binary, embed anywhere |\n\n---\n\n## Key Features\n\n🧠 **Context Query Builder** — Assemble system + user + history + retrieval under a token budget  \n🔍 **Hybrid Search** — HNSW vectors + BM25 keywords with reciprocal rank fusion  \n🕸️ **Graph Overlay** — Lightweight relationship tracking for agent memory  \n⚡ **Embedded-First** — ~700KB binary, no runtime dependencies, SQLite-style simplicity  \n🔒 **Full ACID** — MVCC + WAL + Serializable Snapshot Isolation  \n📊 **Columnar Storage** — Read only the columns you need  \n\n---\n\n## What you can rely on today\n\n### ✅ LLM + agent primitives\n\n- **TOON**: compact, model-friendly output for context windows\n- **Graph Overlay**: lightweight agent-memory graph with BFS/DFS traversal and relationship tracking\n- **ContextQuery builder**: token budgets, deduplication, and multi-source fusion\n- **Policy hooks**: safety controls with pre-built policy templates and audit trails\n- **Tool routing**: multi-agent coordination with dynamic discovery and load balancing\n- **Hybrid retrieval**: vector + BM25 keyword with Reciprocal Rank Fusion (RRF)\n- **Multi-vector documents**: chunk-level aggregation (max / mean / first)\n- **Vector search (HNSW)**: integrated into retrieval workflows\n\n### ✅ Database fundamentals\n\n- **SQL (SQL-92)**: SELECT / INSERT / UPDATE / DELETE / JOINs\n  - **AST-based query executor**: unified SQL processing with dialect normalization\n  - **Multi-dialect compatibility**: MySQL, PostgreSQL, SQLite\n  - **Idempotent DDL**: `CREATE TABLE IF NOT EXISTS`, `DROP TABLE IF EXISTS`\n- **ACID transactions** with **MVCC**\n- **WAL durability** + **group commit**\n- **Serializable Snapshot Isolation (SSI)**\n- **Columnar storage** with projection pushdown (read only the columns you need)\n- **Sync-first architecture**: async runtime (tokio) is optional\n  - ~500KB smaller binaries for embedded use cases\n  - Follows SQLite-style design for maximum compatibility\n\n### ✅ Developer experience\n\n- **Rust client**: `sochdb`\n- **Python \u0026 Nodejs \u0026 Golang SDK** with:\n  - **Embedded mode (FFI)** for lowest latency\n  - **IPC mode (Unix sockets)** for multi-process / service deployments\n  - **Namespace isolation** for multi-tenant apps\n  - **Typed error taxonomy** with remediation hints\n- **Bulk vector operations** for high-throughput ingestion\n  - **BatchAccumulator**: deferred graph construction — 4–5× faster inserts via zero-FFI numpy accumulation + single bulk Rayon-parallel HNSW build\n\n### Known limits\n\n- **Single-node only** (no replication / clustering yet)\n---\n\n## 📦 Quick Start\n\n### Installation\n\nChoose your preferred SDK:\n\n```bash\n# Rust - add to Cargo.toml\nsochdb = \"2.0.4\"\n```\n\n### SDK Repositories\n\nLanguage SDKs are maintained in separate packages and repos with their own release cycles:\n\n| Language | Repository | Installation |\n|----------|------------|-------------|\n| **Rust** | This repository | `cargo add sochdb` |\n| **Python** | [sochdb-python-sdk](https://github.com/sochdb/sochdb-python-sdk) | `pip install sochdb` |\n| **Node.js/TypeScript** | [sochdb-nodejs-sdk](https://github.com/sochdb/sochdb-nodejs-sdk) | `npm install @sochdb/sochdb` |\n| **Go** | [sochdb-go](https://github.com/sochdb/sochdb-go) | `go get github.com/sochdb/sochdb-go@latest` |\n\n### 🐳 Docker Deployment\n\nSochDB includes a production-ready Docker setup with gRPC server:\n\n```bash\n# Pull and run from Docker Hub\ndocker pull sushanth53/sochdb:latest\ndocker run -d -p 50051:50051 sushanth53/sochdb:latest\n\n# Or use docker-compose\ncd docker\ndocker compose up -d\n```\n\n**Docker Hub:** [`sushanth53/sochdb`](https://hub.docker.com/r/sushanth53/sochdb)\n\n**Features:**\n- ✅ Production-ready image (159MB)\n- ✅ High availability setup with Traefik\n- ✅ Prometheus + Grafana monitoring\n- ✅ gRPC-Web support via Envoy\n- ✅ Comprehensive test suite included\n\n**Performance (tested on Apple M-series):**\n- Single-threaded: ~2K ops/sec\n- Concurrent (10 threads): ~10.5K ops/sec  \n- Latency p99: \u003c2.2ms\n\nSee [docker/README.md](docker/README.md) for full documentation.\n| **Node.js/TypeScript** | [sochdb-nodejs-sdk](https://github.com/sochdb/sochdb-nodejs-sdk) | `npm install @sochdb/sochdb` |\n| **Go** | [sochdb-go](https://github.com/sochdb/sochdb-go) | `go get github.com/sochdb/sochdb-go@latest` |\n| **Rust** | This repository | `cargo add sochdb` |\n\n### Examples\n\n- **Python Examples**: [sochdb-python-examples](https://github.com/sochdb/sochdb-python-examples)\n- **Node.js Examples**: [sochdb-nodejs-examples](https://github.com/sochdb/sochdb-nodejs-examples)\n- **Go Examples**: [sochdb-golang-examples](https://github.com/sochdb/sochdb-golang-examples)\n\n### Benchmarks\n\nFor performance comparisons and benchmarks, see [sochdb-benchmarks](https://github.com/sochdb/sochdb-benchmarks).\n\n#### Vector Search — VectorDBBench (OpenAI 50K × 1536D, Apple M1 Ultra)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/benchmark_comparison.svg\" alt=\"SochDB vs ChromaDB vs LanceDB benchmark comparison\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n| Metric | SochDB | ChromaDB | LanceDB (IVF_PQ) |\n|--------|--------|----------|---------|\n| Recall@100 | 0.9899 | 0.9966 | 0.6574 * |\n| Avg Latency | **3.3 ms** | 15.4 ms | 5.6 ms |\n| P95 Latency | **4.2 ms** | 18.4 ms | 5.9 ms |\n| P99 Latency | **5.9 ms** | 22.3 ms | 12.2 ms |\n| Insert (50K vecs) | **0.1 s** | 76.9 s | 0.4 s |\n| Total Load | **13.7 s** | 76.9 s | 21.0 s |\n\n\u003e SochDB/ChromaDB HNSW config: m=16, ef_construction=200, ef_search=500. LanceDB uses IVF_PQ index.\n\u003e * LanceDB recall is lower due to IVF_PQ (lossy compression) vs HNSW (graph-based).\n\u003e Insert uses the Python SDK's `BatchAccumulator` for deferred graph construction\n\u003e (zero FFI during accumulation, single bulk `insert_batch()` with Rayon parallelism).\n\u003e See [full benchmark details](#-benchmarks) for methodology and analysis.\n\n#### Memory Agent — MemoryAgentBench (Ruler QA1 197K, Azure OpenAI gpt-4.1-mini)\n\n##### Head-to-Head: SochDB vs RAG Competitors\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/head_to_head_benchmark.svg\" alt=\"SochDB vs RAG competitors head-to-head benchmark\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n| Rank | System | EM% | F1% | Correct | Build | Query | Queries | Type |\n|:---:|--------|:---:|:---:|:---:|:---:|:---:|:---:|------|\n| 🥇 | **SochDB V2** | **60.0** | **61.7** | **12/20** | 1.9s | **2.1s** | 20/20 | Multi-Perspective RRF |\n| 🥈 | SochDB + HyDE | 30.0 | 42.6 | 6/20 | 3.3s | 37.0s | 20/20 | Embedded Vector DB |\n| 🥉 | GraphRAG | 25.0 | 40.6 | 5/20 | 16.2s | 11.9s | 20/20 | Knowledge Graph |\n| 3 | SochDB + Rerank | 25.0 | 40.2 | 5/20 | 3.2s | 27.9s | 20/20 | Embedded Vector DB |\n| 5 | SochDB + Advanced | 25.0 | 37.8 | 5/20 | 3.3s | 14.0s | 20/20 | Embedded Vector DB |\n| 6 | SochDB Hybrid | 20.0 | 23.4 | 4/20 | **0.01s** | 0.8s | 20/20 | Embedded Vector DB |\n| 7 | Self-RAG | 15.0 | 18.6 | 3/20 | 12.9s | 0.9s | 20/20 | Self-Reflection RAG |\n| 8 | BM25 | 10.0 | 31.4 | 2/20 | 0.06s | 27.4s | 20/20 | Lexical Search |\n| 9 | Embedding RAG | 5.0 | 18.9 | 1/20 | 0.3s | 37.8s | 20/20 | FAISS + Embedding |\n| 10 | Mem0 | 5.0 | 18.5 | 1/20 | 51.7s | 1.0s | 20/20 | Memory-as-a-Service |\n\n\u003e **SochDB V2 is #1** — 60% EM, 2× the previous best (30%), 2.4× better than GraphRAG (25%). V2 solved 4 queries that NO other system could answer.\n\u003e **V2 innovations**: Multi-Perspective RRF (3 embedding angles fused) + Few-Shot Precision Extraction (7 calibrated examples).\n\u003e **GraphRAG** at 25% EM is limited by ContextualCompressionRetriever bottleneck (~848 tokens vs SochDB's ~80K).\n\u003e **Self-RAG** results impacted by Azure content filter rejecting self-reflection prompts.\n\u003e All systems use the same LLM (gpt-4.1-mini), dataset (Ruler QA1 197K), and evaluation framework ([MemoryAgentBench](https://arxiv.org/abs/2507.05257), UCSD).\n\n##### SochDB Modes Detail\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/memory_agent_benchmark.svg\" alt=\"SochDB search modes detail benchmark\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n| Metric | SochDB + HyDE | SochDB + Rerank | SochDB (baseline) | Mem0 |\n|--------|:---:|:---:|:---:|:---:|\n| Exact Match | **30.0%** | 25.0% | 20.0% | 5.0% |\n| F1 Score | **42.6%** | 40.2% | 30.3% | 18.5% |\n| Substring Match | 45.0% | **50.0%** | 20.0% | 30.0% |\n| ROUGE-L F1 | **44.0%** | 42.9% | 29.5% | 17.9% |\n| Memory Build | 3.3 s | 3.2 s | **0.01 s** | 51.7 s |\n| Query Time | 37.0 s | 27.9 s | **6.6 s** | 1.0 s |\n| **Best For** | 🎯 Max Accuracy | 🏆 **Recommended** | ⚡ Max Speed | — |\n\n\u003e **🏆 Recommended**: Use **Rerank** for best overall balance (highest substring match 50%, strong F1 40.2%, 27% faster than HyDE).\n\u003e Use **HyDE** when exact match matters most. Use **baseline** when latency is critical.\n\u003e See [full benchmark details](#-benchmarks) for developer configuration guide, substring match analysis, and learnings.\n\n### Hello World\n\n#### Python\n\n```python\nfrom sochdb import Database\n\ndb = Database.open(\"./my_db\")\ndb.put(b\"users/alice\", b\"Alice Smith\")\nprint(db.get(b\"users/alice\").decode())  # \"Alice Smith\"\ndb.close()\n```\n\n#### Node.js / TypeScript\n\n```typescript\nimport { SochDatabase } from '@sochdb/sochdb';\n\nconst db = new SochDatabase('./my_db');\nawait db.put('users/alice', 'Alice Smith');\nconsole.log(await db.get('users/alice'));  // \"Alice Smith\"\nawait db.close();\n```\n\n#### Go\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    sochdb \"github.com/sochdb/sochdb-go\"\n)\n\nfunc main() {\n    db, _ := sochdb.Open(\"./my_db\")\n    defer db.Close()\n    \n    db.Put([]byte(\"users/alice\"), []byte(\"Alice Smith\"))\n    value, _ := db.Get([]byte(\"users/alice\"))\n    fmt.Println(string(value))  // \"Alice Smith\"\n}\n```\n\n#### Rust\n\n```rust\nuse sochdb::Database;\n\nfn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let db = Database::open(\"./my_db\")?;\n    \n    db.put(b\"users/alice\", b\"Alice Smith\")?;\n    if let Some(value) = db.get(b\"users/alice\")? {\n        println!(\"{}\", String::from_utf8_lossy(\u0026value));  // \"Alice Smith\"\n    }\n    Ok(())\n}\n```\n\n### 🕸️ Graph Overlay for Agent Memory (v0.3.3)\n\nBuild lightweight graph structures on top of SochDB's KV storage for agent memory:\n\n#### Python\n\n```python\nfrom sochdb import Database, GraphOverlay\n\ndb = Database.open(\"./my_db\")\ngraph = GraphOverlay(db, namespace=\"agent_memory\")\n\n# Build conversation graph\ngraph.add_node(\"msg_1\", {\"role\": \"user\", \"content\": \"What's the weather?\"})\ngraph.add_node(\"msg_2\", {\"role\": \"assistant\", \"content\": \"Let me check...\"})\ngraph.add_node(\"msg_3\", {\"role\": \"tool\", \"content\": \"Sunny, 72°F\"})\ngraph.add_node(\"msg_4\", {\"role\": \"assistant\", \"content\": \"It's sunny and 72°F\"})\n\n# Link causal relationships\ngraph.add_edge(\"msg_1\", \"msg_2\", {\"type\": \"triggers\"})\ngraph.add_edge(\"msg_2\", \"msg_3\", {\"type\": \"invokes_tool\"})\ngraph.add_edge(\"msg_3\", \"msg_4\", {\"type\": \"provides_context\"})\n\n# Traverse conversation history (BFS)\npath = graph.bfs(\"msg_1\", \"msg_4\")\nprint(f\"Conversation flow: {' → '.join(path)}\")\n\n# Get all tool invocations (neighbors by edge type)\ntools = graph.get_neighbors(\"msg_2\", edge_filter={\"type\": \"invokes_tool\"})\nprint(f\"Tools used: {tools}\")\n\ndb.close()\n```\n\n#### Go\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    sochdb \"github.com/sochdb/sochdb-go\"\n)\n\nfunc main() {\n    db, _ := sochdb.Open(\"./my_db\")\n    defer db.Close()\n    \n    graph := sochdb.NewGraphOverlay(db, \"agent_memory\")\n    \n    // Build agent action graph\n    graph.AddNode(\"action_1\", map[string]interface{}{\n        \"type\": \"search\", \"query\": \"best restaurants\",\n    })\n    graph.AddNode(\"action_2\", map[string]interface{}{\n        \"type\": \"filter\", \"criteria\": \"italian\",\n    })\n    \n    graph.AddEdge(\"action_1\", \"action_2\", map[string]interface{}{\n        \"relationship\": \"feeds_into\",\n    })\n    \n    // Find dependencies (DFS)\n    deps := graph.DFS(\"action_1\", 10)\n    fmt.Printf(\"Action dependencies: %v\\n\", deps)\n}\n```\n\n#### Node.js/TypeScript\n\n```typescript\nimport { Database, GraphOverlay } from '@sochdb/sochdb';\n\nconst db = await Database.open('./my_db');\nconst graph = new GraphOverlay(db, 'agent_memory');\n\n// Track entity relationships\nawait graph.addNode('entity_alice', { type: 'person', name: 'Alice' });\nawait graph.addNode('entity_acme', { type: 'company', name: 'Acme Corp' });\nawait graph.addNode('entity_project', { type: 'project', name: 'AI Initiative' });\n\nawait graph.addEdge('entity_alice', 'entity_acme', { relationship: 'works_at' });\nawait graph.addEdge('entity_alice', 'entity_project', { relationship: 'leads' });\n\n// Find all entities Alice is connected to\nconst connections = await graph.getNeighbors('entity_alice');\nconsole.log(`Alice is connected to: ${connections.length} entities`);\n\nawait db.close();\n```\n\n**Use Cases:**\n- Agent conversation history with causal chains\n- Entity relationship tracking across sessions\n- Action dependency graphs for planning\n- Knowledge graph construction\n\n### Namespace Isolation (v0.3.0)\n\n#### Python\n\n```python\nfrom sochdb import Database, CollectionConfig, DistanceMetric\n\ndb = Database.open(\"./my_db\")\n\n# Create namespace for tenant isolation\nwith db.use_namespace(\"tenant_acme\") as ns:\n    # Create vector collection with frozen config\n    collection = ns.create_collection(\n        CollectionConfig(\n            name=\"documents\",\n            dimension=384,\n            metric=DistanceMetric.COSINE,\n            enable_hybrid_search=True,  # Enable keyword search\n            content_field=\"text\"\n        )\n    )\n    \n    # Insert multi-vector document (e.g., chunked document)\n    collection.insert_multi(\n        id=\"doc_123\",\n        vectors=[chunk_embedding_1, chunk_embedding_2, chunk_embedding_3],\n        metadata={\"title\": \"SochDB Guide\", \"author\": \"Alice\"},\n        chunk_texts=[\"Intro text\", \"Body text\", \"Conclusion\"],\n        aggregate=\"max\"  # Use max score across chunks\n    )\n    \n    # Hybrid search: vector + keyword with RRF fusion\n    results = collection.hybrid_search(\n        vector=query_embedding,\n        text_query=\"database performance\",\n        k=10,\n        alpha=0.7  # 70% vector, 30% keyword\n    )\n\ndb.close()\n```\n\n### ContextQuery for LLM Retrieval (v0.3.0)\n\n#### Python\n\n```python\nfrom sochdb import Database, ContextQuery, DeduplicationStrategy\n\ndb = Database.open(\"./my_db\")\nns = db.namespace(\"tenant_acme\")\ncollection = ns.collection(\"documents\")\n\n# Build context with token budgeting\ncontext = (\n    ContextQuery(collection)\n    .add_vector_query(query_embedding, weight=0.7)\n    .add_keyword_query(\"machine learning optimization\", weight=0.3)\n    .with_token_budget(4000)  # Fit within model context window\n    .with_min_relevance(0.5)  # Filter low-quality results\n    .with_deduplication(DeduplicationStrategy.EXACT)\n    .execute()\n)\n\n# Use in LLM prompt\nprompt = f\"\"\"Context:\n{context.as_markdown()}\n\nQuestion: {user_question}\n\"\"\"\n\nprint(f\"Retrieved {len(context)} chunks using {context.total_tokens} tokens\")\ndb.close()\n```\n\n### Vector Search Example\n\n#### Python\n\n```python\nfrom sochdb import VectorIndex\nimport numpy as np\n\n# Create HNSW index\nindex = VectorIndex(\n    path=\"./vectors\",\n    dimension=384,\n    metric=\"cosine\"\n)\n\n# Add vectors\nembeddings = np.random.randn(1000, 384).astype(np.float32)\nfor i, embedding in enumerate(embeddings):\n    index.add(str(i), embedding.tolist())\n\n# Build the index\nindex.build()\n\n# Search\nquery = np.random.randn(384).astype(np.float32)\nresults = index.search(query.tolist(), k=10)\nprint(results)  # [{'id': '1', 'distance': 0.23}, ...]\n```\n\n#### Node.js / TypeScript\n\n```typescript\nimport { VectorIndex } from '@sochdb/sochdb';\n\n// Instantiate VectorIndex with path and config\nconst index = new VectorIndex('./vectors', {\n  dimension: 384,\n  metric: 'cosine'\n});\n\n// Add vectors and build index\nawait index.add('doc1', embedding1);\nawait index.add('doc2', embedding2);\nawait index.build();\n\n// Search\nconst results = await index.search(queryEmbedding, 10);\nconsole.log(results);  // [{ id: 'doc1', distance: 0.23 }, ...]\n```\n\n### SDK Feature Matrix\n\n| Feature | Python | Node.js | Go | Rust |\n|---------|--------|---------|-----|------|\n| Basic KV | ✅ | ✅ | ✅ | ✅ |\n| Transactions | ✅ | ✅ | ✅ | ✅ |\n| SQL Operations | ✅ | ✅ | ✅ | ✅ |\n| Vector Search | ✅ | ✅ | ✅ | ✅ |\n| Path API | ✅ | ✅ | ✅ | ✅ |\n| Prefix Scanning | ✅ | ✅ | ✅ | ✅ |\n| Query Builder | ✅ | ✅ | ✅ | ✅ |\n\n\u003e **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.\n\n---\n\n## 🏗 Architecture\n\n```text\nApp / Agent Runtime\n   │\n   ├─ sochdb-client (Rust / Python)\n   │\n   ├─ sochdb-query   (planner + TOON encoder + context builder)\n   └─ sochdb-kernel  (MVCC + WAL + catalog)\n        ├─ sochdb-storage (columnar LSCS + mmap)\n        └─ sochdb-index   (B-Tree + HNSW)\n```\n\n### Crate Overview\n\n| Crate | Description | Key Components |\n|-------|-------------|----------------|\n| `sochdb-core` | Core types and TOON format | `SochValue`, `SochSchema`, `SochTable`, codec |\n| `sochdb-kernel` | Database kernel | WAL, MVCC, transactions, catalog |\n| `sochdb-storage` | Storage engine | LSCS columnar, mmap, block checksums |\n| `sochdb-index` | Index structures | B-Tree, HNSW vector index |\n| `sochdb-query` | Query execution | Cost optimizer, context builder, SOCH-QL |\n| `sochdb-client` | Client SDK | `SochConnection`, `PathQuery`, `BatchWriter` |\n| `sochdb-plugin-logging` | Logging plugin | Structured logging, tracing |\n\n---\n\n## 📄 TOON Format\n\nTOON (Tabular Object-Oriented Notation) is SochDB's compact serialization format designed specifically for LLM context windows—a token-optimized format that dramatically reduces token consumption.\n\n### Format Specification\n\n```ebnf\ndocument     ::= table_header newline row*\ntable_header ::= name \"[\" count \"]\" \"{\" fields \"}\" \":\"\nname         ::= identifier\ncount        ::= integer\nfields       ::= field (\",\" field)*\nfield        ::= identifier\nrow          ::= value (\",\" value)* newline\nvalue        ::= null | bool | number | string | array | ref\n```\n\n### Token Comparison\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                      JSON (156 tokens)                          │\n├─────────────────────────────────────────────────────────────────┤\n│ [                                                               │\n│   {\"id\": 1, \"name\": \"Alice\", \"email\": \"alice@example.com\"},    │\n│   {\"id\": 2, \"name\": \"Bob\", \"email\": \"bob@example.com\"},        │\n│   {\"id\": 3, \"name\": \"Charlie\", \"email\": \"charlie@example.com\"} │\n│ ]                                                               │\n└─────────────────────────────────────────────────────────────────┘\n\n┌─────────────────────────────────────────────────────────────────┐\n│                      TOON (52 tokens) — 67% reduction!          │\n├─────────────────────────────────────────────────────────────────┤\n│ users[3]{id,name,email}:                                        │\n│ 1,Alice,alice@example.com                                       │\n│ 2,Bob,bob@example.com                                           │\n│ 3,Charlie,charlie@example.com                                   │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### TOON Value Types\n\n| Type | TOON Syntax | Example |\n|------|-------------|---------|\n| Null | `∅` | `∅` |\n| Boolean | `T` / `F` | `T` |\n| Integer | number | `42`, `-17` |\n| Float | decimal | `3.14159` |\n| String | text or `\"quoted\"` | `Alice`, `\"hello, world\"` |\n| Array | `[items]` | `[1,2,3]` |\n| Reference | `ref(table,id)` | `ref(users,42)` |\n| Binary | `b64:data` | `b64:SGVsbG8=` |\n\n---\n\n## 🔍 Vector Search\n\nSochDB includes an HNSW (Hierarchical Navigable Small World) index for similarity search.\n\n### Configuration\n\n```rust\nuse sochdb_index::{HNSWIndex, HNSWConfig, DistanceMetric};\n\n// Create index with custom parameters\nlet config = HNSWConfig {\n    m: 16,                          // Max connections per layer\n    m_max: 32,                      // Max connections at layer 0\n    ef_construction: 200,           // Build-time search width\n    ef_search: 50,                  // Query-time search width\n    metric: DistanceMetric::Cosine, // Or Euclidean, DotProduct\n    ..Default::default()\n};\n\nlet index = HNSWIndex::with_config(config);\n```\n\n### Vector Operations\n\n```rust\nuse sochdb::{SochConnection, VectorCollection, SearchResult};\n\nlet conn = SochConnection::open(\"./vectors\")?;\n\n// Insert vectors\nlet embedding: Vec\u003cf32\u003e = get_embedding(\"Hello world\");\nconn.vector_insert(\"documents\", 1, \u0026embedding, Some(metadata))?;\n\n// Search similar vectors\nlet query_embedding = get_embedding(\"Hi there\");\nlet results: Vec\u003cSearchResult\u003e = conn.vector_search(\"documents\", \u0026query_embedding, 10)?;\n\nfor result in results {\n    println!(\"ID: {}, Distance: {:.4}\", result.id, result.distance);\n}\n```\n\n### Distance Metrics\n\n| Metric | Use Case | Formula |\n|--------|----------|---------|\n| `Cosine` | Text embeddings, normalized vectors | `1 - (a·b)/(‖a‖‖b‖)` |\n| `Euclidean` | Spatial data, unnormalized | `√Σ(aᵢ-bᵢ)²` |\n| `DotProduct` | When vectors are pre-normalized | `-a·b` |\n\n### High-Throughput Ingestion (Python SDK)\n\nThe Python SDK's `BatchAccumulator` provides **4–5× faster inserts** by deferring HNSW graph construction:\n\n```python\nfrom sochdb import VectorIndex\nimport numpy as np\n\nindex = VectorIndex(dimension=1536, max_connections=16, ef_construction=200)\n\n# Option 1: Context manager (auto-flush)\nwith index.batch_accumulator(estimated_size=50_000) as acc:\n    acc.add(ids, vectors)   # Zero FFI, pure numpy memcpy\n# HNSW graph built in one shot on exit\n\n# Option 2: Explicit control\nacc = index.batch_accumulator(50_000)\nacc.add(chunk1_ids, chunk1_vecs)\nacc.add(chunk2_ids, chunk2_vecs)\ninserted = acc.flush()  # Single bulk FFI call → full Rayon parallelism\n\n# Option 3: Cross-process persistence\nacc.save(\"/tmp/vectors\")     # Persist to disk\nacc2 = index.batch_accumulator()\nacc2.load(\"/tmp/vectors\")    # Load in another process\nacc2.flush()                 # Build HNSW\n```\n\n### Vector Quantization\n\nSochDB supports optional quantization to reduce memory usage with minimal recall loss:\n\n| Precision | Memory | Search Latency | Use Case |\n|-----------|--------|----------------|----------|\n| `F32` | 100% (baseline) | Baseline | Maximum precision |\n| `F16` | 50% | ~Same | General embeddings |\n| `BF16` | 50% | ~Same | ML model compatibility |\n\n\u003e **Tip**: F16 typically provides 50% memory reduction with \u003c1% recall degradation for most embedding models.\n\n---\n\n## 🔐 Transactions\n\nSochDB provides **ACID transactions** with MVCC (Multi-Version Concurrency Control) and WAL durability.\n\n### ACID Guarantees\n\n| Property | Implementation |\n|----------|----------------|\n| **Atomicity** | Buffered writes with all-or-nothing commit |\n| **Consistency** | Schema validation before commit |\n| **Isolation** | MVCC snapshots with read/write set tracking |\n| **Durability** | WAL with fsync, group commit support |\n\n### Transaction Modes\n\n```rust\nuse sochdb::{SochConnection, ClientTransaction, IsolationLevel};\n\n// Auto-commit (implicit transaction per operation)\nconn.put(\"users/1/name\", b\"Alice\")?;\n\n// Explicit transaction with isolation level\nlet txn = conn.begin_with_isolation(IsolationLevel::Serializable)?;\nconn.put_in_txn(txn, \"users/1/name\", b\"Alice\")?;\nconn.put_in_txn(txn, \"users/1/email\", b\"alice@example.com\")?;\nconn.commit(txn)?;  // SSI validation happens here\n\n// Rollback on error\nlet txn = conn.begin()?;\nif let Err(e) = do_something(\u0026conn, txn) {\n    conn.rollback(txn)?;\n    return Err(e);\n}\nconn.commit(txn)?;\n```\n\n### Isolation Levels\n\n| Level | Description | Status |\n|-------|-------------|--------|\n| `ReadCommitted` | Sees committed data at statement start | ✅ Implemented |\n| `SnapshotIsolation` | Reads see consistent point-in-time view | ✅ Implemented |\n| `Serializable` | SSI with rw-antidependency cycle detection | ✅ Implemented |\n\n### WAL Sync Modes\n\n```rust\nuse sochdb_kernel::SyncMode;\n\nlet config = DatabaseConfig {\n    sync_mode: SyncMode::Normal,  // Group commit (recommended)\n    // sync_mode: SyncMode::Full, // Fsync every commit (safest)\n    // sync_mode: SyncMode::Off,  // Periodic fsync (fastest)\n    ..Default::default()\n};\n```\n\n### Durability Presets\n\nSochDB provides pre-configured durability settings for common use cases:\n\n| Preset | Sync Mode | Group Commit | Best For |\n|--------|-----------|--------------|----------|\n| `throughput_optimized()` | Normal | Large batches | High-volume ingestion |\n| `latency_optimized()` | Full | Small batches | Real-time applications |\n| `max_durability()` | Full | Disabled | Financial/critical data |\n\n```rust\nuse sochdb::ConnectionConfig;\n\n// High-throughput batch processing\nlet config = ConnectionConfig::throughput_optimized();\n\n// Low-latency real-time access\nlet config = ConnectionConfig::latency_optimized();\n\n// Maximum durability (fsync every commit, no batching)\nlet config = ConnectionConfig::max_durability();\n```\n\n---\n\n## 🌳 Path API\n\nSochDB's unique path-based API provides **O(|path|)** resolution via the Trie-Columnar Hybrid (TCH) structure.\n\n### Path Format\n\n```\ncollection/document_id/field\ntable/row_id/column\n```\n\n### Operations\n\n```rust\nuse sochdb::{SochConnection, PathQuery};\n\nlet conn = SochConnection::open(\"./data\")?;\n\n// Put a value at a path\nconn.put(\"users/1/name\", b\"Alice\")?;\nconn.put(\"users/1/profile/avatar\", avatar_bytes)?;\n\n// Get a value\nlet name = conn.get(\"users/1/name\")?;\n\n// Delete at path\nconn.delete(\"users/1/profile/avatar\")?;\n\n// Scan by prefix (returns all matching key-value pairs)\nlet user_data = conn.scan(\"users/1/\")?;\nfor (key, value) in user_data {\n    println!(\"{}: {:?}\", key, value);\n}\n\n// Query using PathQuery builder\nlet results = PathQuery::from_path(\u0026conn, \"users\")\n    .select(\u0026[\"id\", \"name\", \"email\"])\n    .where_eq(\"status\", \"active\")\n    .order_by(\"created_at\", Order::Desc)\n    .limit(10)\n    .execute()?;\n```\n\n### Path Resolution\n\n```\nPath: \"users/1/name\"\n      \n      TCH Resolution (O(3) = O(|path|))\n      ┌─────────────────────────────────┐\n      │  users  →  1  →  name           │\n      │    ↓       ↓       ↓            │\n      │  Table   Row   Column           │\n      │  Lookup  Index  Access          │\n      └─────────────────────────────────┘\n      \nvs    B-Tree (O(log N))\n      ┌─────────────────────────────────┐\n      │  Binary search through          │\n      │  potentially millions of keys   │\n      └─────────────────────────────────┘\n```\n\n### Optional Ordered Index\n\nSochDB's ordered index can be disabled for write-optimized workloads:\n\n```rust\nuse sochdb::ConnectionConfig;\n\n// Default: ordered index enabled (O(log N) prefix scans)\nlet config = ConnectionConfig::default();\n\n// Write-optimized: disable ordered index (~20% faster writes)\nlet mut config = ConnectionConfig::default();\nconfig.enable_ordered_index = false;\n// Note: scan_prefix becomes O(N) instead of O(log N + K)\n```\n\n| Mode | Write Speed | Prefix Scan | Use Case |\n|------|-------------|-------------|----------|\n| Ordered index **on** | Baseline | O(log N + K) | Read-heavy, prefix queries |\n| Ordered index **off** | ~20% faster | O(N) | Write-heavy, point lookups |\n\n---\n\n## 📊 Context Query Builder\n\nBuild LLM context with automatic token budget management.\n\n```rust\nuse sochdb_query::{ContextSection, ContextSelectQuery};\nuse sochdb::ContextQueryBuilder;\n\nlet context = ContextQueryBuilder::new()\n    .for_session(\"session_123\")\n    .with_budget(4096)  // Token budget\n    \n    // System prompt (highest priority)\n    .literal(\"SYSTEM\", -1, \"You are a helpful assistant\")\n    \n    // User profile from database\n    .section(\"USER\", 0)\n        .get(\"user.profile.{name, email, preferences}\")\n        .done()\n    \n    // Recent conversation history\n    .section(\"HISTORY\", 1)\n        .last(10, \"messages\")\n        .where_eq(\"session_id\", session_id)\n        .done()\n    \n    // Relevant documents via vector search\n    .section(\"DOCS\", 2)\n        .search(\"knowledge_base\", \"query_embedding\", 5)\n        .min_score(0.7)\n        .done()\n    \n    .truncation(TruncationStrategy::PriorityDrop)\n    .format(ContextFormat::Soch)\n    .execute()?;\n\nprintln!(\"Tokens used: {}/{}\", context.token_count, 4096);\nprintln!(\"Context:\\n{}\", context.context);\n```\n\n---\n\n## 🔌 Plugin System\n\nSochDB uses a plugin architecture for extensibility without dependency bloat.\n\n### Extension Types\n\n| Extension | Purpose | Example |\n|-----------|---------|---------|\n| `StorageExtension` | Alternative backends | RocksDB, LSCS |\n| `IndexExtension` | Custom indexes | Learned index, full-text |\n| `ObservabilityExtension` | Metrics/tracing | Prometheus, DataDog |\n| `CompressionExtension` | Compression algos | LZ4, Zstd |\n\n### Implementing a Plugin\n\n```rust\nuse sochdb_kernel::{Extension, ExtensionInfo, ObservabilityExtension};\n\nstruct PrometheusMetrics { /* ... */ }\n\nimpl Extension for PrometheusMetrics {\n    fn info(\u0026self) -\u003e ExtensionInfo {\n        ExtensionInfo {\n            name: \"prometheus-metrics\".into(),\n            version: \"1.0.0\".into(),\n            description: \"Prometheus metrics export\".into(),\n            author: \"Your Name\".into(),\n            capabilities: vec![ExtensionCapability::Observability],\n        }\n    }\n    \n    fn as_any(\u0026self) -\u003e \u0026dyn std::any::Any { self }\n    fn as_any_mut(\u0026mut self) -\u003e \u0026mut dyn std::any::Any { self }\n}\n\nimpl ObservabilityExtension for PrometheusMetrics {\n    fn counter_inc(\u0026self, name: \u0026str, value: u64, labels: \u0026[(\u0026str, \u0026str)]) {\n        // Push to Prometheus\n    }\n    \n    fn gauge_set(\u0026self, name: \u0026str, value: f64, labels: \u0026[(\u0026str, \u0026str)]) {\n        // Set gauge value\n    }\n    \n    fn histogram_observe(\u0026self, name: \u0026str, value: f64, labels: \u0026[(\u0026str, \u0026str)]) {\n        // Record histogram\n    }\n    \n    // ... tracing methods\n}\n\n// Register the plugin\ndb.plugins().register_observability(Box::new(PrometheusMetrics::new()))?;\n```\n\n---\n\n## 🧮 Batch Operations\n\nHigh-throughput batch operations with group commit optimization.\n\n```rust\nuse sochdb::{SochConnection, BatchWriter, GroupCommitConfig};\n\nlet conn = SochConnection::open(\"./data\")?;\n\n// Batch insert with auto-commit\nlet result = conn.batch()\n    .max_batch_size(1000)\n    .auto_commit(true)\n    .insert(\"events\", vec![(\"id\", id1), (\"data\", data1)])\n    .insert(\"events\", vec![(\"id\", id2), (\"data\", data2)])\n    // ... more inserts\n    .execute()?;\n\nprintln!(\"Executed: {}, Failed: {}, Duration: {}ms\", \n    result.ops_executed, result.ops_failed, result.duration_ms);\n\n// Bulk insert for large datasets\nlet rows: Vec\u003cVec\u003c(\u0026str, SochValue)\u003e\u003e = generate_rows(10_000);\nlet result = conn.bulk_insert(\"events\", rows)?;\n```\n\n### Group Commit Formula\n\nSochDB calculates optimal batch size using:\n\n```\nN* = √(2 × L_fsync × λ / C_wait)\n\nWhere:\n- L_fsync = fsync latency (~5ms typical)\n- λ = arrival rate (ops/sec)\n- C_wait = cost per unit wait time\n```\n\n---\n\n## 📈 Benchmarks\n\n\u003e **Version**: 0.5.3 | **Benchmark Date**: February 2026 | **Hardware**: Apple M1 Ultra (ARM64)\n\u003e **Vector Search**: [VectorDBBench](https://github.com/zilliztech/VectorDBBench) (Zilliz) | **Memory Agent**: [MemoryAgentBench](https://arxiv.org/abs/2507.05257) (UCSD)\n\n### VectorDBBench: 50K-Vector Comparison (SochDB vs ChromaDB vs LanceDB)\n\nWe benchmarked SochDB against ChromaDB and LanceDB using **[VectorDBBench](https://github.com/zilliztech/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.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/benchmark_comparison.svg\" alt=\"SochDB vs ChromaDB vs LanceDB benchmark comparison\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n#### Test Setup\n- **Dataset**: COHERE/OpenAI 50,000 vectors × 768–1536 dimensions\n- **Queries**: VectorDBBench standard query set (k=100)\n- **Distance Metric**: Cosine similarity\n- **Ground Truth**: VectorDBBench precomputed ground truth (brute-force)\n- **Processes**: Insert, optimize, and search in separate subprocesses (VectorDBBench default)\n\n#### Configuration\n\n| Parameter | SochDB | ChromaDB | LanceDB |\n|-----------|--------|----------|----------|\n| Index Type | HNSW | HNSW | IVF_PQ |\n| M | 16 | 16 | — |\n| ef_construction | 200 | 200 | — |\n| ef_search | 500 | 500 | — |\n| Version | 0.5.3 (SDK) | 0.4.22 | 0.19.0 |\n\n#### Results\n\n| Metric | SochDB | ChromaDB | LanceDB (IVF_PQ) |\n|--------|--------|----------|----------|\n| **Recall@100** | 0.9899 | 0.9966 | 0.6574 * |\n| **Avg Latency** | **3.3 ms** ✅ | 15.4 ms | 5.6 ms |\n| **P95 Latency** | **4.2 ms** ✅ | 18.4 ms | 5.9 ms |\n| **P99 Latency** | **5.9 ms** ✅ | 22.3 ms | 12.2 ms |\n| **Insert (50K vecs)** | **0.1 s** ✅ | 76.9 s | 0.4 s |\n| **Total Load** | **13.7 s** ✅ | 76.9 s | 21.0 s |\n\n\u003e \\* LanceDB recall is lower due to IVF_PQ (lossy compression) vs HNSW (graph-based exact search).\n\n#### Key Findings\n\n- 🏎️ **SochDB search is 4.7× faster than ChromaDB** (3.3 ms vs 15.4 ms average)\n- 🏎️ **SochDB search is 1.7× faster than LanceDB** (3.3 ms vs 5.6 ms average)\n- ⚡ **SochDB total load is 5.6× faster than ChromaDB** (13.7 s vs 76.9 s)\n- ⚡ **SochDB total load is 1.5× faster than LanceDB** (13.7 s vs 21.0 s)\n- 🎯 **SochDB recall (98.99%)** is within 1% of ChromaDB while being 4.7× faster\n- ⚠️ **LanceDB recall (65.74%)** is significantly lower due to IVF_PQ lossy compression vs HNSW\n\n#### How SochDB Achieves Fast Inserts: `BatchAccumulator`\n\nSochDB's Python SDK includes a **`BatchAccumulator`** API that separates data accumulation from HNSW graph construction:\n\n```\n┌────────────────────────────────────────────────────────────────────┐\n│                    BatchAccumulator Pipeline                       │\n├───────────────────────┬──────────────────────────────────────────┤\n│  Phase 1: Accumulate  │  Phase 2: Flush                          │\n│  ──────────────────── │  ─────────────────                        │\n│  • add(ids, vecs)     │  • Single insert_batch() FFI call        │\n│  • Pure numpy memcpy  │  • Full Rayon parallel HNSW build        │\n│  • Zero FFI calls     │  • Wave-parallel (32-node waves)         │\n│  • ~0.05 s for 50K    │  • Adaptive ef (capped at 48)            │\n│                       │  • ~13.7 s for 50K vectors               │\n└───────────────────────┴──────────────────────────────────────────┘\n```\n\n```python\nfrom sochdb import VectorIndex\n\nindex = VectorIndex(dimension=1536, max_connections=16, ef_construction=200)\n\n# Deferred insert: zero FFI, pure numpy memcpy\nwith index.batch_accumulator(estimated_size=50_000) as acc:\n    for batch_ids, batch_vecs in data_loader:\n        acc.add(batch_ids, batch_vecs)       # ~0.05s total\n    # flush() called automatically → single bulk HNSW build (~13.7s)\n```\n\n#### End-to-End RAG Bottleneck Analysis\n\n| Component | Time | % of Total |\n|-----------|------|------------|\n| **Embedding API (Azure OpenAI)** | 59.5s | **99.7%** |\n| SochDB Insert (1K vectors) | 0.133s | 0.2% |\n| SochDB Search (100 queries) | 0.046s | 0.1% |\n\n\u003e 🎯 **The embedding API is 333× slower than SochDB operations.** In production RAG systems, the database is never the bottleneck — your LLM API calls are.\n\n---\n\n### MemoryAgentBench: Head-to-Head RAG Comparison\n\n\u003e **Version**: 2.0.0 | **Benchmark Date**: February 2026 | **LLM**: Azure OpenAI gpt-4.1-mini | **Framework**: [MemoryAgentBench](https://arxiv.org/abs/2507.05257) (UCSD)\n\nWe 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).\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/head_to_head_benchmark.svg\" alt=\"SochDB vs RAG competitors head-to-head benchmark\" width=\"800\" /\u003e\n\u003c/p\u003e\n\n#### Head-to-Head Results (gpt-4.1-mini, Ruler QA1 197K, 20 queries)\n\n| Rank | System | EM % | F1 % | Correct | Build (s) | Query (s) | Queries | Type |\n|:---:|:---|:---:|:---:|:---:|:---:|:---:|:---:|:---|\n| 🥇 | **SochDB V2** | **60.0** | **61.7** | **12/20** | 1.9 | **2.1** | ✅ 20/20 | Multi-Perspective RRF |\n| 🥈 | SochDB + HyDE | 30.0 | 42.6 | 6/20 | 3.3 | 37.0 | ✅ 20/20 | Embedded HNSW |\n| 🥉 | GraphRAG | 25.0 | 40.6 | 5/20 | 16.2 | 11.9 | ✅ 20/20 | Knowledge Graph + NER |\n| 3 | SochDB + Rerank | 25.0 | 40.2 | 5/20 | 3.2 | 27.9 | ✅ 20/20 | Embedded HNSW |\n| 5 | SochDB + Advanced | 25.0 | 37.8 | 5/20 | 3.3 | 14.0 | ✅ 20/20 | Embedded HNSW |\n| 6 | SochDB Hybrid | 20.0 | 23.4 | 4/20 | **0.01** | 0.8 | ✅ 20/20 | Embedded HNSW |\n| 7 | Self-RAG | 15.0 | 18.6 | 3/20 | 12.9 | 0.9 | ✅ 20/20 | Adaptive Retrieval |\n| 8 | BM25 | 10.0 | 31.4 | 2/20 | 0.06 | 27.4 | ✅ 20/20 | Lexical Search |\n| 9 | Embedding RAG | 5.0 | 18.9 | 1/20 | 0.3 | 37.8 | ✅ 20/20 | FAISS + Embedding |\n| 10 | Mem0 | 5.0 | 18.5 | 1/20 | 51.7 | 1.0 | ✅ 20/20 | Memory-as-a-Service |\n| — | RAPTOR | — | — | — | — | — | 0/20 | Tree Summarization |\n\n\u003e All systems completed 20/20 queries except RAPTOR.\n\u003e **SochDB V2** solved 4 queries that NO other system could: Q2 (Denmark, Iceland and Norway), Q7 (Catholic), Q11 (King Charles III), Q12 (Epte).\n\u003e **Self-RAG** results impacted by Azure content filter rejecting self-reflection prompts (~50% of queries blocked).\n\n#### Key Findings — Head-to-Head\n\n- 🏆 **SochDB V2 dominates at 60% EM** — 2× the previous best (30%), 2.4× better than GraphRAG (25%)\n- 🏆 **V2 solves 4 previously-impossible queries** via Multi-Perspective RRF (3 embedding angles) + Few-Shot Precision Extraction\n- 🏆 **SochDB is the only embedded system** — zero external dependencies (no LangChain, spaCy, FAISS, or network services)\n- 🏆 **V2 query time is 18× faster** than HyDE v1 (2.1s vs 37.0s) and 6× faster than GraphRAG (11.9s)\n- 📊 **GraphRAG is limited by ContextualCompressionRetriever** — reduces context to ~848 tokens (vs SochDB's ~80K)\n- ⚡ **SochDB Hybrid is 40× faster than any competitor** (0.8s query) while still competitive at 20% EM\n- 🧩 **BM25 has surprisingly high substring match (70%)** but low exact match (10%) — retrieves relevant docs but can't extract precise answers\n- 📉 **Embedding RAG and Mem0 tied at 5% EM** — basic vector similarity alone is insufficient for long-context QA\n\n#### Test Setup\n- **Dataset**: Ruler QA1 197K (197,000-token context, 100 QA pairs, key-value retrieval)\n- **Embeddings**: Azure OpenAI text-embedding-3-small (1536D)\n- **LLM**: gpt-4.1-mini (all systems use the same LLM for fair comparison)\n- **Competitors tested**: GraphRAG, Self-RAG, BM25, Embedding RAG (FAISS), Mem0, RAPTOR\n- **Task**: Accurate Retrieval — memorize long conversations, then answer factual queries\n- **Queries**: 20 per system (max_test_queries_ablation=20)\n- **Metrics**: Exact match, F1, substring match, ROUGE-L (standard MemoryAgentBench metrics)\n\n#### SochDB Configuration Comparison\n\n| Configuration | EM % | F1 % | Sub-EM % | ROUGE-L | Build (s) | Query (s) | Best For |\n|:---|:---:|:---:|:---:|:---:|:---:|:---:|:---|\n| **SochDB + HyDE** | **30.0** | **42.6** | 45.0 | **44.0** | 3.29 | 37.0 | 🎯 Max Accuracy |\n| **SochDB + Rerank** | 25.0 | 40.2 | **50.0** | 42.9 | 3.24 | 27.9 | 🏆 **Recommended** |\n| **SochDB + Advanced** | 25.0 | 37.8 | 35.0 | 37.5 | 3.25 | 14.0 | ⚠️ Don't stack |\n| **SochDB (gpt-4.1)** | 20.0 | 30.3 | 20.0 | 29.5 | **0.01** | **6.6** | ⚡ Max Speed |\n| **Mem0** | 5.0 | 18.5 | 30.0 | 17.9 | 51.7 | 1.0 | — |\n\n#### 📘 Developer Configuration Guide\n\n\u003e **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.\n\n| Your Priority | Recommended Config | Why |\n|:---|:---|:---|\n| **Best overall balance** | SochDB + Rerank | Highest substring match (50%), strong F1 (40.2%), 27% faster than HyDE |\n| **Maximum exact accuracy** | SochDB + HyDE | Best EM (30%) and F1 (42.6%) — HyDE bridges question↔document vocabulary gap |\n| **Lowest latency / real-time** | SochDB baseline | 0.01s build, 6.6s query — no extra LLM calls during retrieval |\n| **Fuzzy/partial matching** | SochDB + Rerank | 50% substring match — cross-encoder reranker surfaces relevant context even on partial matches |\n\n**Key decision factors**:\n\n1. **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.\n\n2. **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.\n\n3. **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.\n\n#### Understanding Substring Match (Sub-EM)\n\n**What it measures**: Does the gold answer appear *anywhere* inside the prediction, or vice versa?\n\nSubstring match is not a pure accuracy metric — it **correlates with answer verbosity**. Here's why different configs score differently:\n\n| Config | EM % | Sub-EM % | Gap | Explanation |\n|:---|:---:|:---:|:---:|:---|\n| **SochDB (baseline)** | 20 | 20 | 0 | Short precise answers (~4 tokens). When wrong, no overlap at all. |\n| **SochDB + HyDE** | 30 | 45 | +15 | Slightly longer answers. Wrong predictions still contain gold keywords. |\n| **SochDB + Rerank** | 25 | 50 | +25 | Reranker surfaces better context → predictions contain gold as substring. |\n| **Mem0** | 5 | 30 | +25 | Very verbose answers (~13 tokens). Gold words appear by chance in long text. |\n\n**Example**: Gold answer is \"Catholic\"\n- Baseline predicts \"Orthodox\" → Sub-EM ❌ (short, no overlap)\n- Rerank predicts \"Catholic orthodoxy\" → Sub-EM ✅ (gold is a substring)\n- Mem0 predicts \"The predominant religion was Catholic Christianity\" → Sub-EM ✅ (verbose, gold appears)\n\n\u003e ⚠️ **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.\n\n#### Key Findings\n\n- 🏆 **SochDB + HyDE achieves 6× higher exact match than Mem0** (30.0% vs 5.0%)\n- 🏆 **SochDB + Rerank is the recommended config** — best substring match (50%) with strong F1 (40.2%) and 27% faster than HyDE\n- ⚡ **SochDB builds memory 5,170× faster than Mem0** (0.01s vs 51.7s)\n- 🧠 **Retrieval strategy \u003e model size**: gpt-4.1 = gpt-4.1-mini at same retrieval (both 20% EM), but HyDE on mini → 30% EM\n- ⚠️ **Don't stack all features**: Advanced (HyDE+Hybrid+Rerank) scores *worse* than using HyDE or Rerank independently\n- 📊 **Substring match tracks answer verbosity**, not pure accuracy — use EM and F1 for quality decisions\n\n#### Multi-Dataset Results (SochDB, 100 queries)\n\n| Dataset | Context | EM % | F1 % | Sub-EM % |\n|---------|---------|:---:|:---:|:---:|\n| Ruler QA1 197K | 197K tokens | 13.0 | 27.0 | 38.0 |\n| Ruler QA2 421K | 421K tokens | **31.0** | **42.7** | **49.0** |\n| LongMemEval | 400K tokens | 3.3 | 9.7 | 4.0 |\n\n\u003e 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.\n\n#### Why SochDB is Different\n\n1. **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.\n\n2. **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.\n\n3. **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).\n\n4. **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.\n\n5. **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.\n\n---\n\n### Recall Benchmarks (Search Quality)\n\nSochDB's HNSW index achieves **\u003e98% recall@10** with sub-millisecond latency using real Azure OpenAI embeddings.\n\n#### Test Methodology\n- Ground truth computed via brute-force cosine similarity\n- Recall@k = (# correct results in top-k) / k\n- Tested across multiple HNSW configurations\n\n#### Results by HNSW Configuration\n\n| Configuration | Search (ms) | R@1 | R@5 | R@10 | R@20 | R@50 |\n|---------------|-------------|-----|-----|------|------|------|\n| **M=8, ef_c=50** | **0.42** | 0.990 | **0.994** | **0.991** | 0.994 | 0.991 |\n| M=16, ef_c=100 | 0.47 | 0.980 | 0.986 | 0.982 | 0.984 | 0.986 |\n| M=16, ef_c=200 | 0.44 | 0.970 | 0.984 | 0.988 | 0.990 | 0.986 |\n| M=32, ef_c=200 | 0.47 | 0.980 | 0.982 | 0.981 | 0.984 | 0.985 |\n| M=32, ef_c=400 | 0.52 | 0.990 | 0.986 | 0.983 | 0.979 | 0.981 |\n\n**Key Insights**:\n- All configurations achieve **\u003e98% recall@10** with real embeddings\n- **Best recall**: 99.1% @ 0.42ms (M=8, ef_c=50)\n- **Recommended for RAG**: M=16, ef_c=100 (balanced speed + quality)\n- Smaller `M` values work well for text embeddings due to natural clustering\n\n#### Recommended HNSW Settings\n\n| Use Case | M | ef_construction | Expected Recall@10 | Latency |\n|----------|---|-----------------|-------------------|---------|\n| **Real-time RAG** | 8 | 50 | ~99% | \u003c0.5ms |\n| **Balanced** | 16 | 100 | ~98% | \u003c0.5ms |\n| **Maximum Quality** | 16 | 200 | ~99% | \u003c0.5ms |\n| **Large-scale (10M+)** | 32 | 200 | ~97% | \u003c1ms |\n\n---\n\n### Token Efficiency (TOON vs JSON)\n\n| Dataset | JSON Tokens | TOON Tokens | Reduction |\n|---------|-------------|-------------|-----------|\n| Users (100 rows, 5 cols) | 2,340 | 782 | **66.6%** |\n| Events (1000 rows, 3 cols) | 18,200 | 7,650 | **58.0%** |\n| Products (500 rows, 8 cols) | 15,600 | 5,980 | **61.7%** |\n\n---\n\n### I/O Reduction (Columnar Storage)\n\n| Query | Row Store | SochDB Columnar | Reduction |\n|-------|-----------|-----------------|-----------| \n| SELECT 2 of 10 cols | 100% | 20% | **80%** |\n| SELECT 1 of 20 cols | 100% | 5% | **95%** |\n\n---\n\n### KV Performance (vs SQLite)\n\n\u003e **Methodology**: SochDB vs SQLite under similar durability settings (`WAL` mode, `synchronous=NORMAL`). Results on Apple M-series hardware, 100k records.\n\n| Database | Mode | Insert Rate | Notes |\n|----------|------|-------------|-------|\n| **SQLite** | File (WAL) | ~1.16M ops/sec | Industry standard |\n| **SochDB** | Embedded (WAL) | ~760k ops/sec | Group commit disabled |\n| **SochDB** | put_raw | ~1.30M ops/sec | Direct storage layer |\n| **SochDB** | insert_row_slice | ~1.29M ops/sec | Zero-allocation API |\n\n---\n\n### Running Benchmarks Yourself\n\n```bash\n# Install Python 3.12 (recommended for ChromaDB compatibility)\nbrew install python@3.12\npython3.12 -m venv .venv312\nsource .venv312/bin/activate\n\n# Install dependencies\npip install chromadb lancedb python-dotenv requests numpy\npip install -e sochdb-python-sdk/\n\n# Build SochDB release library\ncargo build --release\n\n# Run real embedding benchmark (requires Azure OpenAI credentials in .env)\nSOCHDB_LIB_PATH=target/release python3 benchmarks/real_embedding_benchmark.py\n\n# Run recall benchmark\nSOCHDB_LIB_PATH=target/release python3 benchmarks/recall_benchmark.py\n\n# Run Rust benchmarks (SochDB vs SQLite)\ncargo run -p benchmarks --release\n```\n\n\u003e **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.\n\n---\n\n## 🛠 Configuration Reference\n\n### DatabaseConfig\n\n```rust\npub struct DatabaseConfig {\n    /// Enable group commit for better throughput\n    pub group_commit: bool,           // default: true\n    \n    /// WAL sync mode\n    pub sync_mode: SyncMode,          // default: Normal\n    \n    /// Maximum WAL size before checkpoint\n    pub max_wal_size: u64,            // default: 64MB\n    \n    /// Memtable size before flush\n    pub memtable_size: usize,         // default: 4MB\n    \n    /// Block cache size\n    pub block_cache_size: usize,      // default: 64MB\n    \n    /// Compression algorithm\n    pub compression: Compression,      // default: LZ4\n}\n```\n\n### HNSWConfig\n\n```rust\npub struct HNSWConfig {\n    /// Max connections per node per layer\n    pub m: usize,                     // default: 16\n    \n    /// Max connections at layer 0\n    pub m_max: usize,                 // default: 32\n    \n    /// Construction-time search width\n    pub ef_construction: usize,       // default: 200\n    \n    /// Query-time search width (adjustable)\n    pub ef_search: usize,             // default: 50\n    \n    /// Distance metric\n    pub metric: DistanceMetric,       // default: Cosine\n    \n    /// Level multiplier (mL = 1/ln(M))\n    pub ml: f32,                      // default: calculated\n}\n```\n\n---\n\n## 📚 API Reference\n\n### SochConnection\n\n| Method | Description | Returns |\n|--------|-------------|---------|\n| `open(path)` | Open/create database | `Result\u003cSochConnection\u003e` |\n| `create_table(schema)` | Create a new table | `Result\u003cCreateResult\u003e` |\n| `drop_table(name)` | Drop a table | `Result\u003cDropResult\u003e` |\n| `batch()` | Start a batch writer | `BatchWriter` |\n| `put(path, value)` | Put value at path | `Result\u003c()\u003e` |\n| `get(path)` | Get value at path | `Result\u003cOption\u003cVec\u003cu8\u003e\u003e\u003e` |\n| `delete(path)` | Delete at path | `Result\u003c()\u003e` |\n| `scan(prefix)` | Scan path prefix | `Result\u003cVec\u003c(String, Vec\u003cu8\u003e)\u003e\u003e` |\n| `begin()` | Begin transaction | `Result\u003cTxnHandle\u003e` |\n| `commit(txn)` | Commit transaction | `Result\u003c()\u003e` |\n| `rollback(txn)` | Rollback transaction | `Result\u003c()\u003e` |\n| `vector_insert(...)` | Insert vector | `Result\u003c()\u003e` |\n| `vector_search(...)` | Search similar vectors | `Result\u003cVec\u003cSearchResult\u003e\u003e` |\n| `fsync()` | Force sync to disk | `Result\u003c()\u003e` |\n| `checkpoint()` | Create checkpoint | `Result\u003cu64\u003e` |\n| `stats()` | Get statistics | `ClientStats` |\n\n### PathQuery\n\n| Method | Description | Returns |\n|--------|-------------|---------|\n| `from_path(conn, path)` | Create query from path | `PathQuery` |\n| `select(cols)` | Select columns | `Self` |\n| `project(cols)` | Alias for select | `Self` |\n| `where_eq(field, val)` | Equality filter | `Self` |\n| `where_gt(field, val)` | Greater than filter | `Self` |\n| `where_like(field, pat)` | Pattern match | `Self` |\n| `order_by(field, dir)` | Sort results | `Self` |\n| `limit(n)` | Limit results | `Self` |\n| `offset(n)` | Skip results | `Self` |\n| `execute()` | Execute query | `Result\u003cQueryResult\u003e` |\n| `execute_toon()` | Execute and return TOON | `Result\u003cString\u003e` |\n\n### SochValue\n\n| Variant | Rust Type | Description |\n|---------|-----------|-------------|\n| `Null` | — | Null value |\n| `Bool(bool)` | `bool` | Boolean |\n| `Int(i64)` | `i64` | Signed integer |\n| `UInt(u64)` | `u64` | Unsigned integer |\n| `Float(f64)` | `f64` | 64-bit float |\n| `Text(String)` | `String` | UTF-8 string |\n| `Binary(Vec\u003cu8\u003e)` | `Vec\u003cu8\u003e` | Binary data |\n| `Array(Vec\u003cSochValue\u003e)` | `Vec\u003cSochValue\u003e` | Array of values |\n| `Object(HashMap\u003cString, SochValue\u003e)` | `HashMap` | Key-value object |\n| `Ref { table, id }` | — | Foreign key reference |\n\n### SochType\n\n| Type | Description |\n|------|-------------|\n| `Int` | 64-bit signed integer |\n| `UInt` | 64-bit unsigned integer |\n| `Float` | 64-bit float |\n| `Text` | UTF-8 string |\n| `Bool` | Boolean |\n| `Bytes` | Binary data |\n| `Vector(dim)` | Float vector with dimension |\n| `Array(inner)` | Array of inner type |\n| `Optional(inner)` | Nullable type |\n| `Ref(table)` | Foreign key to table |\n\n---\n\n## 🔧 Building from Source\n\n### Prerequisites\n\n- Rust 2024 edition (1.75+)\n- Clang/LLVM (for SIMD optimizations)\n\n### Build\n\n```bash\n# Clone the repository\ngit clone https://github.com/sochdb/sochdb.git\ncd sochdb\n\n# Build all crates\ncargo build --release\n\n# Run tests\ncargo test --all\n\n# Run benchmarks\ncargo bench\n```\n\n### Feature Flags\n\n| Feature | Crate | Description |\n|---------|-------|-------------|\n| `simd` | sochdb-client | SIMD optimizations for column access |\n| `embedded` | sochdb-client | Use kernel directly (no IPC) |\n| `full` | sochdb-kernel | All kernel features |\n\n---\n\n## ⚠️ Before heavy production use\n\n* **Single node** (no replication / clustering)\n* **WAL growth**: call `checkpoint()` periodically for long-running services (auto-trigger config available via `CheckpointConfig`)\n* **Group commit**: tune per workload (disable for strictly sequential writes)\n\n---\n\n## 🚧 Roadmap (high level)\n\n* Cost-based optimizer: **production-ready** — full cost model, cardinality estimation (HLL + histograms), join order DP, token-budget planning, plan caching\n* Adaptive group commit: **implemented** — Little's Law-based batch sizing with EMA arrival-rate tracking\n* WAL compaction / auto-truncation: **partially implemented** — manual `checkpoint()` + `truncate_wal()` works end-to-end; automatic background compaction planned\n* Agent flow metadata schema: planned\n* Agent runtime library: planned\n\n---\n\n## 🤖 Vision: SochDB as an Agentic Framework Foundation\n\nSochDB is designed to be the **brain, memory, and registry** for AI agents—not by embedding a programming language, but by storing agent metadata that external runtimes interpret.\n\n### The Architecture\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                     Your Application                         │\n├─────────────────────────────────────────────────────────────┤\n│                                                              │\n│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │\n│  │ Agent Runtime│    │    SochDB    │    │     LLM      │   │\n│  │  (executor)  │◄──►│  (metadata)  │    │   (worker)   │   │\n│  └──────┬───────┘    └──────────────┘    └──────▲───────┘   │\n│         │                                        │           │\n│         │  1. Load flow from DB                  │           │\n│         │  2. Build prompt from node config      │           │\n│         │  3. Call LLM ─────────────────────────►│           │\n│         │  4. Parse result, update state         │           │\n│         │  5. Choose next edge, repeat           │           │\n│                                                              │\n└─────────────────────────────────────────────────────────────┘\n```\n\n### What SochDB Stores\n\n| Table | Purpose |\n|-------|---------|\n| `agent_flows` | Flow definitions: name, entry node, version |\n| `agent_nodes` | Nodes: LLM steps, tool calls, decisions, loops, reflections |\n| `agent_edges` | Edges with conditions for routing |\n| `agent_sessions` | Runtime state per user/conversation |\n| `agent_reflections` | Feedback and learning data |\n\n### Node Types\n\nFlows are graphs where each node has a `kind`:\n\n- **`llm_step`** — Call the LLM with a prompt template\n- **`tool_call`** — Execute a tool (API, function, DB query)\n- **`decision`** — Branch based on previous output\n- **`loop_start` / `loop_end`** — Iteration with exit conditions\n- **`reflection`** — Ask LLM to evaluate and improve\n- **`subflow`** — Invoke another flow\n\n### Example: Support Agent Flow\n\n```\n┌─────────────┐     ┌─────────────┐     ┌─────────────┐\n│  Classify   │────►│  Retrieve   │────►│   Answer    │\n│   Intent    │     │   Context   │     │             │\n└─────────────┘     └─────────────┘     └──────┬──────┘\n                                               │\n                    ┌─────────────┐            │\n                    │   Reflect   │◄───────────┘\n                    │  (optional) │\n                    └─────────────┘\n```\n\nThe LLM only sees **one node at a time**:\n\n```text\nflow: support_assistant\nnode: classify_intent\ngoal: classify the user's message\ninput:\n  user_message: \"I can't access my account\"\ncontext:\n  last_episodes: [...]\nallowed_outputs: [\"billing\", \"bug\", \"feature\", \"other\"]\n```\n\nThis keeps prompts small and stable. The runtime handles control flow.\n\n### Why This Approach\n\n| Benefit | Description |\n|---------|-------------|\n| **Separation of concerns** | SochDB = data, Runtime = execution, LLM = reasoning |\n| **Language-agnostic** | Rust, Python, TypeScript runtimes share the same flows |\n| **Debuggable** | Every step, state change, and decision is in the DB |\n| **Learnable** | Reflection nodes + stored feedback enable continuous improvement |\n| **No prompt injection risk** | LLM never sees \"execute this code\"—just structured tasks |\n\n### Built-in Patterns (Planned)\n\nTemplates for common agentic patterns:\n\n- **Reflection loop** — Execute, evaluate, retry if needed\n- **Tree-of-thought** — Parallel exploration with best-path selection\n- **Self-correction** — Validate output, fix errors automatically\n- **Tool-first-then-answer** — Gather data before responding\n\nThese ship as rows in `agent_flows` / `agent_nodes` that you can clone and customize.\n\n---\n\n## ☁️ Cloud Roadmap\n\n\u003e **Local-first success unlocks the cloud.**\n\nSochDB is currently a **local-first, embedded database** — and it's working great! Based on the success of this MVP, I'm exploring a cloud offering:\n\n| Phase | Status | Description |\n|-------|--------|-------------|\n| **Local MVP** | ✅ Live | Embedded + IPC modes, full ACID, vector search |\n| **Cloud (SochDB Cloud)** | 🚧 On the way | Hosted, managed SochDB with sync |\n\n**Your feedback shapes the cloud roadmap.** If you're interested in a hosted solution, let us know what you need!\n\n---\n\n## 💬 A Note from the Creator\n\n\u003e **This is an MVP — and your support makes it better.**\n\nSochDB started as an experiment: *what if databases were designed for LLMs from day one?* The result is what you see here — a working, tested, and (I hope) useful database.\n\nBut here's the thing: **software gets better with users.** Every bug report, feature request, and \"hey, this broke\" message helps SochDB become more robust. You might find rough edges. You might encounter surprises. That's expected — and fixable!\n\n**What I need from you:**\n- 🐛 **Report bugs** — even small ones\n- 💡 **Request features** — what's missing for your use case?\n- ⭐ **Star the repo** — it helps others discover SochDB\n- 📣 **Share your experience** — blog posts, tweets, anything\n\nYour usage and feedback don't just help me — they help everyone building with SochDB. Let's make this great together.\n\n\u003e **Note:** SochDB is a **single-person project** built over weekends and spare time. I'm the sole developer, architect, and maintainer. This means you might find rough edges, incomplete features, or areas that need polish. The good news? Your contributions can make a real impact. More hands on this project means more advanced features, better stability, and faster progress. Every PR, issue report, and suggestion directly shapes what SochDB becomes.\n\n*— Sushanth*\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n```bash\n# Install development dependencies\ncargo install cargo-watch cargo-criterion\n\n# Run in watch mode\ncargo watch -x \"test --all\"\n\n# Run specific benchmark\ncargo criterion --bench vector_search\n```\n\n---\n\n## 📄 License\n\n**SochDB (sochdb)**  \nCopyright (C) 2026 Sushanth Reddy Vanagala\n\nThis project is licensed under the **GNU Affero General Public License v3.0 or later** (AGPL-3.0-or-later).  \nSee the [LICENSE](LICENSE) file for the full text.\n\n**What this means:**\n- ✅ You can use, modify, and distribute SochDB freely\n- ✅ You must share your modifications under AGPL-3.0\n- ✅ If you run SochDB as a network service, you must share your source code\n- 📖 Full license text: https://www.gnu.org/licenses/agpl-3.0.html\n\nFor commercial licensing options or questions, contact: sushanth@sochdb.dev\n\n---\n\n## 🙏 Acknowledgments\n\n- HNSW algorithm: [Malkov \u0026 Yashunin, 2018](https://arxiv.org/abs/1603.09320)\n- MVCC implementation inspired by PostgreSQL and SQLite\n- Columnar storage design influenced by Apache Arrow\n- Vamana (DiskANN): Subramanya et al., \"DiskANN: Fast Accurate Billion-point Nearest Neighbor Search on a Single Node\", NeurIPS 2019\n- CoreNN: https://github.com/wilsonzlin/CoreNN\n- HNSW: Malkov \u0026 Yashunin, \"Efficient and robust approximate nearest neighbor search using Hierarchical Navigable Small World graphs\", IEEE TPAMI 2018\n- PGM-Index: Ferragina \u0026 Vinciguerra, \"The PGM-index: a fully-dynamic compressed learned index with provable worst-case bounds\", VLDB 2020\n- ARIES: Mohan et al., \"ARIES: A Transaction Recovery Method Supporting Fine-Granularity Locking and Partial Rollbacks Using Write-Ahead Logging\", ACM TODS 1992\n- SSI: Cahill et al., \"Serializable Isolation for Snapshot Databases\", ACM SIGMOD 2008\n- LSM-Tree: O'Neil et al., \"The Log-Structured Merge-Tree (LSM-Tree)\", Acta Informatica 1996\n- Soch https://github.com/toon-format/toon\n\n---\n\n**Built with ❤️ for the AI era**\n\n[GitHub](https://github.com/sochdb/sochdb) • [Documentation](https://sochdb.dev)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsochdb%2Fsochdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsochdb%2Fsochdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsochdb%2Fsochdb/lists"}