SochDB Documentation

Welcome to the official SochDB documentation. SochDB is The LLM-Native Database — a high-performance embedded database designed specifically for AI applications.

Current Version: v0.4.4 (Core) | Python SDK v0.4.7 | Node.js SDK v0.5.1 | Go SDK v0.4.3

---

What is SochDB?

SochDB 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.

Comparison

Database + retrieval layer

Feature	SochDB	SQLite + vec	Postgres + pgvector	Chroma	LanceDB
Embedded	✅	✅	❌	✅	✅
Vector search	✅ HNSW	⚠️ (via extension)	✅ (HNSW / IVFFlat)	✅	✅
Full SQL (user-facing)	✅ SQL-92	✅	✅	❌	✅
Hybrid search (vector + keyword)	✅	⚠️ (DIY)	⚠️ (DIY)	⚠️ (limited)	✅
Context builder	✅	❌	❌	❌	❌
Token budgeting	✅	❌	❌	❌	❌
Graph overlay	✅	❌	❌	❌	❌
ACID transactions	✅	✅	✅	⚠️ (limited)	❌
Columnar storage	✅	❌	❌	❌	✅

Memory / agent-memory layer

Feature	SochDB	Mem0	Letta	Graphiti
Primary focus	DB + retrieval + context	Memory layer	Agent framework + memory	Temporal knowledge-graph memory
Long-term memory primitives	✅	✅	✅	✅
Token-aware context budgeting	✅	❌	❌	❌
Graph-based memory	✅	❌	❌	✅
Built-in vector store	✅	❌ (BYO)	❌ (BYO)	❌ (BYO)
Built-in agent runtime	❌	❌	✅	❌
Drop-in “memory add-on” to existing apps	✅	✅	⚠️	✅

Quick links: 📚 Documentation • Quick Start • Architecture • TOON Format • Benchmarks • RFD

---

Why SochDB?

❌ The Typical AI Agent Stack

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              YOUR APPLICATION                                    │
└───────┬─────────────────┬─────────────────┬─────────────────┬───────────────────┘
        │                 │                 │                 │
        ▼                 ▼                 ▼                 ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐ ┌───────────────────────────┐
│   Postgres    │ │   Pinecone    │ │    Redis      │ │    Custom Code            │
│   (metadata)  │ │   (vectors)   │ │  (sessions)   │ │    (context assembly)     │
│               │ │               │ │               │ │                           │
│ • User data   │ │ • Embeddings  │ │ • Chat state  │ │ • Token counting          │
│ • Settings    │ │ • Similarity  │ │ • Cache       │ │ • Truncation logic        │
│ • History     │ │   search      │ │ • Temp data   │ │ • Prompt packing          │
│               │ │               │ │               │ │ • Multi-source fusion     │
└───────────────┘ └───────────────┘ └───────────────┘ └───────────────────────────┘
        │                 │                 │                 │
        └─────────────────┴─────────────────┴─────────────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    │  😰 You manage all of this:   │
                    │  • 4 different query languages │
                    │  • 4 sets of credentials       │
                    │  • 4 failure modes             │
                    │  • No cross-system transactions│
                    │  • Weeks of glue code          │
                    └───────────────────────────────┘

✅ With SochDB

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              YOUR APPLICATION                                    │
└─────────────────────────────────────┬───────────────────────────────────────────┘
                                      │
                                      ▼
                    ┌─────────────────────────────────────┐
                    │             SochDB                   │
                    │                                      │
                    │   SQL + Vectors + Context Builder    │
                    │                                      │
                    │   • One query language               │
                    │   • One connection                   │
                    │   • ACID transactions                │
                    │   • Token budgeting built-in         │
                    │                                      │
                    └─────────────────────────────────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    │  😎 What you actually ship:       │
                    │  • Single ~700KB embedded DB      │
                    │  • Zero external dependencies     │
                    │  • Works offline                  │
                    │  • Deploys anywhere               │
                    └───────────────────────────────────┘

The Problem → Solution

Challenge	Traditional Stack	SochDB
Token waste	JSON/SQL bloat in prompts	TOON format for dense output
RAG plumbing	Separate vector DB + glue code	Built-in HNSW with hybrid search
Context assembly	Custom packer per use case	One query with token budget
I/O overhead	Multiple DB round-trips	Single columnar read
Consistency	Distributed transaction headaches	Local ACID guarantees
Deployment	Manage 4 services	Single binary, embed anywhere

---

Key Features

🧠 Context Query Builder — Assemble system + user + history + retrieval under a token budget
🔍 Hybrid Search — HNSW vectors + BM25 keywords with reciprocal rank fusion
🕸️ Graph Overlay — Lightweight relationship tracking for agent memory
⚡ Embedded-First — ~700KB binary, no runtime dependencies, SQLite-style simplicity
🔒 Full ACID — MVCC + WAL + Serializable Snapshot Isolation
📊 Columnar Storage — Read only the columns you need

---

Why SochDB exists

Most "agent stacks" still glue together:

• a KV store (sessions / state)
• a vector DB (retrieval)
• a prompt packer (context budgeting, truncation)
• a relational DB (metadata)

…and then spend weeks maintaining brittle context assembly and token budgeting.

SochDB collapses that stack into one LLM‑native substrate: you store structured data + embeddings + history and ask the DB to produce a token‑efficient context payload.

---

What you can rely on today

✅ LLM + agent primitives

• TOON: compact, model-friendly output for context windows
• Graph Overlay: lightweight agent-memory graph with BFS/DFS traversal and relationship tracking
• ContextQuery builder: token budgets, deduplication, and multi-source fusion
• Policy hooks: safety controls with pre-built policy templates and audit trails
• Tool routing: multi-agent coordination with dynamic discovery and load balancing
• Hybrid retrieval: vector + BM25 keyword with Reciprocal Rank Fusion (RRF)
• Multi-vector documents: chunk-level aggregation (max / mean / first)
• Vector search (HNSW): integrated into retrieval workflows

✅ Database fundamentals

• SQL (SQL-92): SELECT / INSERT / UPDATE / DELETE / JOINs
  • AST-based query executor: unified SQL processing with dialect normalization
  • Multi-dialect compatibility: MySQL, PostgreSQL, SQLite
  • Idempotent DDL: CREATE TABLE IF NOT EXISTS, DROP TABLE IF EXISTS
• ACID transactions with MVCC
• WAL durability + group commit
• Serializable Snapshot Isolation (SSI)
• Columnar storage with projection pushdown (read only the columns you need)
• Sync-first architecture: async runtime (tokio) is optional
  • ~500KB smaller binaries for embedded use cases
  • Follows SQLite-style design for maximum compatibility

✅ Developer experience

• Rust client: sochdb
• Python & Nodejs & Golang SDK with:
  • Embedded mode (FFI) for lowest latency
  • IPC mode (Unix sockets) for multi-process / service deployments
  • Namespace isolation for multi-tenant apps
  • Typed error taxonomy with remediation hints
• Bulk vector operations for high-throughput ingestion

Known limits

• Single-node only (no replication / clustering yet)

---

SochDB in one picture

Problem	Typical approach	SochDB approach
Token waste	JSON/SQL payload bloat	TOON: dense, table-like output
RAG plumbing	External vector DB + glue	Built-in HNSW + quantization
Context assembly	multiple reads + custom packer	One context query with a budget
I/O amplification	row store reads all columns	columnar + projection pushdown

---

Quick Install

Rust

cargo add sochdb

use sochdb::Database;

fn main() -> anyhow::Result<()> {
    let db = Database::open("./my_app_db")?;

    db.with_transaction(|txn| {
        txn.put(b"users/alice", br#"{"name": "Alice", "role": "admin"}"#)?;
        Ok(())
    })?;

    if let Some(user) = db.get(b"users/alice")? {
        println!("{}", String::from_utf8_lossy(&user));
    }

    Ok(())
}

Python

pip install sochdb

from sochdb import Database

db = Database.open("./my_app_db")

with db.transaction() as txn:
    txn.put(b"users/alice", b'{"name": "Alice", "role": "admin"}')

user = db.get(b"users/alice")
print(user.decode())  # {"name": "Alice", "role": "admin"}

db.close()

Node.js

npm install @sochdb/sochdb

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

const db = Database.open('./my_app_db');

await db.withTransaction(async (txn) => {
  await txn.put('users/alice', '{"name": "Alice", "role": "admin"}');
});

const user = await db.get('users/alice');
console.log(user?.toString());

await db.close();

Go

go get github.com/sochdb/sochdb-go@v0.4.3

package main

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

func main() {
    db, _ := sochdb.Open("./my_app_db")
    defer db.Close()

    db.WithTransaction(func(txn *sochdb.Transaction) error {
        return txn.Put("users/alice", []byte(`{"name": "Alice", "role": "admin"}`))
    })

    user, _ := db.Get("users/alice")
    fmt.Println(string(user))
}

→ Full Quick Start Guide

---

Documentation Sections

🚀 Getting Started

Step-by-step guides to get you up and running quickly.

• Quick Start — 5-minute intro
• Installation — All platforms
• First App — Build something real

📖 Guides

Task-oriented guides for specific use cases.

Language SDKs:

• Rust SDK — Native Rust guide
• Python SDK — Complete Python guide (v0.4.7)
• Node.js SDK — TypeScript/JavaScript guide (v0.5.1)
• Go SDK — Go client guide (v0.4.3)

Features:

• SQL Guide — Working with SQL queries
• Vector Search — HNSW indexing
• Bulk Operations — Batch processing
• Deployment — Production setup

AI Agent Safety & Memory:

• Policy & Safety Hooks — Pre/post operation validation
• Multi-Agent Tool Routing — Route tools across agents
• Graph Overlay — Lightweight graph for agent memory
• Context Query — Token-aware retrieval for LLMs

💡 Concepts

Deep dives into SochDB's architecture and design.

• Architecture — System design
• TOON Format — Token-optimized format
• Performance — Optimization guide

📋 API Reference

Complete technical specifications.

• SQL API — SQL query reference
• Rust API — Crate documentation
• Python API — Full Python API docs
• Node.js API — TypeScript/JavaScript API
• Go API — Go package documentation

🛠️ Server Reference

Deep technical documentation for SochDB servers and tools.

• IPC Server — Wire protocol & architecture
• gRPC Server — Vector search service
• Bulk Operations — High-performance tools

🍳 Cookbook

Recipes for common tasks.

• Vector Indexing — Embedding workflows
• MCP Integration — Claude integration
• Logging — Observability setup

---

Quick Links

I want to...	Go to...
Get started in 5 minutes	Quick Start
Use Namespace & Collections	Python SDK
Use Priority Queues	Python SDK
Use Memory System	Node.js SDK
Use SQL queries	SQL Guide
Use the Rust SDK	Rust Guide
Use the Python SDK	Python Guide
Use the Node.js SDK	Node.js Guide
Use the Go SDK	Go Guide
Add vector search	Vector Search
Integrate with Claude (MCP)	MCP Integration
Enforce agent safety policies	Policy Hooks
Route tools across agents	Tool Routing
Model agent memory relationships	Graph Overlay
Build token-aware context	Context Query
Understand the architecture	Architecture
See the SQL API reference	SQL API

---

External Links

• sochdb.dev — Main website
• GitHub — Source code
• Python SDK — Python SDK repo
• Node.js SDK — Node.js SDK repo
• Go SDK — Go SDK repo
• Discussions — Community Q&A