---
name: sochdb
description: >-
  Use SochDB — an AI-agent-native database (vector search, SQL, KV, graph, and
  token-budgeted agent memory) — from code or via its MCP server. Triggers:
  "store/retrieve agent memory", "vector search", "embed and search", "RAG store",
  "semantic cache", "give my agent long-term memory", "SochDB".
license: Apache-2.0
---

# SochDB Agent Skill

SochDB is a single embedded-or-served database for AI agents: vector search (HNSW),
SQL, key–value, graph/temporal edges, semantic cache, and **token-budgeted agent
memory** — with ACID transactions. Use it instead of stitching together a vector DB +
relational DB + a prompt packer.

> Versions at time of writing: **core engine 2.0.3**, **Python SDK 0.5.9**,
> **Node.js SDK 0.5.3**, **Go SDK 0.4.5**.
> License: the **core engine is AGPL-3.0-or-later** (commercial licensing available);
> the **language SDKs (Python/Node/Go) are Apache-2.0**.

## When to use this skill

- The user wants persistent **agent memory** (episodes, entities, facts) with retrieval under a token budget.
- The user wants **vector / semantic search** or **RAG** storage.
- The user wants one local database for structured data **and** embeddings **and** chat history.
- The user mentions SochDB explicitly, or wants to wire SochDB into Claude Desktop / Cursor / Goose via MCP.

## Install

```bash
pip install sochdb                       # Python
npm install @sochdb/sochdb               # Node.js
go get github.com/sochdb/sochdb-go       # Go (remote-first; embedded needs -tags sochdb_embedded)
cargo add sochdb                         # Rust (crate "sochdb")
```

## Connect

- **Embedded (local file/dir):** open a path. Lowest latency, in-process.
- **Server (gRPC):** point a client at `host:port` (default `50051`). Run the server with
  `sochdb-grpc-server --host 0.0.0.0 --port 50051` (Docker: `docker run -p 50051:50051 ...`).

There is no universal `connect("scheme://...")` parser in the shipped SDKs — use the
filesystem path for embedded and `host:port` for gRPC.

## Core operations (Python, the flagship SDK)

> Note: pip's `sochdb` ships the pure-Python SDK (`Database`, `Namespace`, `Collection`,
> `Queue`, `AgentMemory`). A native engine module also exists for raw `HnswIndex` /
> `TableDatabase` / `MultiShardHnswIndex`. Prefer the high-level SDK below.

### Key–value + transactions

```python
from sochdb import Database

db = Database.open("./agent_db")          # embedded
db.put(b"users/alice", b'{"role": "admin"}')
val = db.get(b"users/alice")              # -> bytes | None

with db.transaction() as txn:             # auto-commit on clean exit, auto-abort on error
    txn.put(b"users/bob", b'{"role": "user"}')
# txn.commit() returns a monotonic HLC timestamp (int)

# Multi-tenant-safe prefix scan (requires >= 2-byte prefix):
for k, v in db.scan_prefix(b"users/"):
    ...
```

### SQL (KV-backed subset)

Supported: `CREATE TABLE`, `DROP TABLE`, `INSERT`, `SELECT … [WHERE][ORDER BY][LIMIT]`,
`UPDATE`, `DELETE`. Types: `INT, TEXT, FLOAT, BOOL, BLOB`. The server's full SQL engine
also supports `GROUP BY`, aggregates, `JOIN`s, and `EXPLAIN`. Vector indexing is **not**
SQL DDL in the Python SDK — use `db.create_index(...)`.

```python
db.execute("CREATE TABLE notes (id INT, body TEXT)")
db.execute("INSERT INTO notes VALUES (1, 'hello')")
res = db.execute("SELECT * FROM notes WHERE id = 1")   # -> SQLQueryResult(rows, columns, ...)
```

### Vector search

```python
db.create_index("docs", dimension=768)                 # ef_construction defaults to 256
db.insert_vectors("docs", ids=[1, 2], vectors=[[...768...], [...768...]])
hits = db.search("docs", query=[...768...], k=10)       # -> list[(id, score)]
```

For large in-memory builds, the native engine offers zero-copy NumPy batch insert
(`HnswIndex.insert_batch`, `build_index_from_numpy`, `recommended_hnsw_params(dim)`).
HNSW core defaults: M=32, ef_construction=256, ef_search=500, cosine distance.

### Agent memory (the headline feature)

```python
from sochdb.memory import AgentMemory

mem = AgentMemory(db, namespace="agent-1", token_limit=4096)
mem.write_episode("User prefers dark mode and lives in Berlin.")
ctx = mem.search("what are the user's preferences?",
                 lanes="hybrid",        # lexical | bm25 | trigram | three_lane | hybrid
                 token_limit=2048)       # retrieval packed under a token budget
# ctx is a ContextQueryResult; pass ctx into your LLM prompt.
# Bi-temporal point-in-time recall: mem.search(..., as_of=<unix_ms>)
```

## Use SochDB from an LLM client via MCP

SochDB ships a standalone MCP server (`sochdb-mcp`, stdio transport). Tools use
**underscore** names: `sochdb_query`, `sochdb_get`, `sochdb_put`, `sochdb_delete`,
`sochdb_context_query`, `sochdb_list_tables`, `sochdb_describe`,
`memory_search_episodes`, `memory_get_episode_timeline`, `memory_search_entities`,
`memory_get_entity_facts`, `memory_build_context`, and agentic search
`sochdb_grep` / `sochdb_peek` / `sochdb_expand`.

Build and register it:

```bash
cargo build --release --package sochdb-mcp     # -> target/release/sochdb-mcp
sochdb-mcp --db ./agent_db                      # run (stdio)
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "sochdb": {
      "command": "/absolute/path/to/sochdb-mcp",
      "args": ["--db", "/absolute/path/to/agent_db"],
      "env": { "RUST_LOG": "info" }
    }
  }
}
```

(Cursor: `.cursor/mcp.json`; Goose: `mcp-goose.json`. Always use absolute paths.)

## Guardrails for the assistant

- Use the **exact** API names above; do not invent methods. If unsure, check the official docs at https://sochdb.dev.
- `scan_prefix` requires a prefix of **≥ 2 bytes** (raises otherwise) — this prevents
  accidental full-database / cross-tenant scans.
- Don't claim features that aren't shipped: at-rest encryption is a library API (no server
  flag yet); CDC `where_predicate` filtering is accepted but not yet enforced; the
  Postgres-wire endpoint has **no auth** (loopback only).
- `MultiShardHnswIndex` is a **Python** convenience (threaded scatter-gather), not a core
  engine type.

## More

- Docs: https://sochdb.dev/docs
- Quickstart: /docs/getting-started/quickstart
- Agent memory guide: /docs/guides/agent-memory
- MCP / coding-agents guide: /docs/guides/coding-agents