SochDB Documentation

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

Current Version: v2.0.3 (Core engine) | Python SDK v0.5.9 | Node.js SDK v0.5.3 | Go SDK v0.4.5

License

SochDB ships under a split license. The core engine (the Rust workspace — the sochdb crate, server, and MCP) is AGPL-3.0-or-later, with commercial licensing available. The language SDKs (Python, Node.js, Go) are Apache-2.0.

---

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)	✅	✅
SQL (user-facing)	✅ joins, aggregates, GROUP BY	✅	✅	❌	✅
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 • Performance • 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 (+ a grep lane) with Reciprocal Rank Fusion (RRF)
• Multi-vector documents: chunk-level aggregation (max / mean / first)
• Vector search (HNSW): integrated into retrieval workflows

Where these live by language

The context builder, policy hooks, tool routing, and graph overlay are real importable modules in the Rust and Node.js SDKs. In the Python SDK they are example patterns (shipped in sochdb-python-examples, not importable SDK classes) — Python's first-class agent surface is the AgentMemory API. See Agent Memory and the per-language SDK guides.

✅ Database fundamentals

• SQL: SELECT / INSERT / UPDATE / DELETE plus DDL (CREATE/DROP TABLE, CREATE/DROP INDEX, ALTER TABLE)
  • Joins: INNER, LEFT, RIGHT, FULL, and CROSS
  • Aggregates & GROUP BY: COUNT, SUM, AVG, MIN, MAX (plus MEDIAN and STDDEV via the SQL aggregate path), with HAVING
  • EXPLAIN: textual query-plan output via the Volcano executor
  • VECTOR_SEARCH(...): vector similarity directly in SQL
  • AST-based query executor: unified Volcano operator engine 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

✅ Server (v2.0)

Run SochDB as a service with the sochdb-grpc-server binary and connect over multiple protocols.

• Authentication & RBAC: API keys (SHA-256, or HMAC-SHA256 with a pepper), JWT validation (HS256, validation-only), TLS/mTLS, and Owner / Editor / Viewer roles with per-namespace scoping
• CDC & subscriptions: WAL-derived change-data-capture stream with gRPC Subscribe / WatchKey and table/operation filtering
• Observability: Prometheus metrics endpoint (/metrics) and a health endpoint
• WebSocket gateway: JSON protocol for SQL, KV, and subscribe messages
• Postgres wire protocol: connect with psql and standard Postgres drivers (simple-query mode)
• At-rest encryption: AES-256-GCM-SIV engine for data blocks, WAL, and checkpoints (library API)
• Agent memory: episodic write/search with bi-temporal point-in-time queries and token-budgeted context

Upgrading from v0.4.x? See the v2.0 migration guide.

✅ 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 today (no built-in replication or clustering). A server node can fan out to clients over gRPC, WebSocket, and Postgres wire, and the CDC subscription stream is the building block for downstream replication, but the engine itself does not yet replicate or shard across nodes.

At-rest encryption is library-only

The AES-256-GCM-SIV encryption engine is a shipped, unit-tested library API, but it is not yet wired to a server CLI flag — sochdb-grpc-server does not construct an encryption engine on its main path. Treat it as an available API / planned wiring, not a runtime toggle. See Encryption.

Postgres wire is unauthenticated by default

The Postgres-wire endpoint supports simple-query only, has no auth (trust), and is cleartext (no TLS). Keep it loopback-only unless you accept the risk, and pass --pg-data-dir to back it with real persistent SQL. See Postgres Wire.

---

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.put(b"users/alice", br#"{"name": "Alice", "role": "admin"}"#)?;

    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';

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

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

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

db.close();

Go

go get github.com/sochdb/sochdb-go

The Go SDK is remote-first by default; the embedded engine lives in the embedded subpackage and requires the sochdb_embedded build tag (go build -tags sochdb_embedded).

package main

import (
    "fmt"

    "github.com/sochdb/sochdb-go/embedded"
)

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

    db.Put([]byte("users/alice"), []byte(`{"name": "Alice", "role": "admin"}`))

    user, _ := db.Get([]byte("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 (crate sochdb v2.0.3)
• Python SDK — Complete Python guide (v0.5.9)
• Node.js SDK — TypeScript/JavaScript guide (v0.5.3)
• Go SDK — Go client guide (v0.4.5)

Features:

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

AI Agent Safety & Memory:

• Agent Memory — Episodic write/search with bi-temporal queries
• 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

Server & Operations:

• Security — Auth, RBAC, TLS/mTLS, API keys & JWT
• Encryption — At-rest AES-256-GCM-SIV (library API)
• CDC & Subscriptions — Change-data-capture streams
• Observability — Prometheus metrics & health checks
• Migration to v2.0 — Upgrade from v0.4.x

💡 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
• WebSocket Gateway — JSON protocol for SQL/KV/subscribe
• Postgres Wire — Connect with psql and Postgres drivers
• 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
Use agent memory	Agent Memory
Secure the server (auth/RBAC)	Security
Stream changes (CDC)	CDC & Subscriptions
Scrape Prometheus metrics	Observability
Connect with psql	Postgres Wire
Upgrade from v0.4.x	Migration to v2.0
Use the Node.js API	Node.js API
Use the Go API	Go API
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