datacules-agentdb 0.5.3

Single-file embedded database for AI agents. SQL + Vector Search + Full-Text Search + Hybrid Queries + Memory Graphs.
Documentation

Philosophy

AgentDB is the default embedded database for AI agents. It is a single file, zero configuration, cross-platform database that works consistently across desktop, mobile, edge, browser, server, CLI, and embedded devices. Every feature is built to optimize for agentic workloads — semantic memory, vector search, graph relationships, conversations, workflows, tool executions, and structured knowledge — while remaining lightweight, portable, deterministic, and developer-friendly.

AgentDB prioritizes local-first operations, high performance, reliability, language interoperability, and simple APIs so developers can drop it into any application and immediately give AI agents persistent, intelligent memory. Every new capability reinforces the philosophy of embed, open, use — minimal setup, maximum portability.

Core Principles

# Principle What it means
1 AI-native first, not AI as an add-on Every API, schema, and default is designed around agentic access patterns — not retrofitted onto a general-purpose database
2 One file, one API, every platform A single .agentdb file works identically whether you open it from Python, Rust, Node.js, Go, Java, or the CLI
3 Offline-first with optional synchronization Full capability without any network connection; sync is an opt-in layer, not a requirement
4 Deterministic and reproducible agent memory Given the same inputs, agents produce the same outputs — no hidden server state, no non-deterministic remote indexes
5 Built-in semantic primitives Vectors, graphs, memory, workflows, conversations, and reasoning traces are first-class citizens, not plugins
6 Language-agnostic Native bindings for Rust, Python, JavaScript, Go, Java, C#, C/C++, Swift, Kotlin, Ruby, and more
7 No infrastructure required No server. No daemon. No configuration. Drop in a file and start writing
8 Scales from a phone to a data center The same programming model works on a microcontroller, a laptop, and a cloud server — without code changes

What is AgentDB?

AgentDB is a single-file, embedded database purpose-built for AI agents and LLM-powered applications. It gives your agent a complete, production-ready persistence layer — relational SQL, semantic vector search, memory graphs, full-text search, conversation threading, workflow state, and reasoning traces — all in one .agentdb file, with no servers, no daemons, and no configuration.

import agentdb

db = agentdb.AgentDB.open("my_agent.agentdb")
# That's it. Your agent now has SQL + vectors + graphs + conversations + more.

AgentDB is written in Rust for performance and safety, and ships native bindings for Python, Node.js, Go, Java, C#, C/C++, plus a CLI and WASM target for the browser.

Who Is AgentDB For?

AgentDB is designed for developers who are building on top of AI models and need reliable, fast, local-first persistence — without stitching together multiple services.

You'll love AgentDB if you are:

  • Building an AI agent that needs to remember past interactions and recall them by semantic similarity
  • Developing a RAG pipeline and tired of running a separate vector database
  • Creating a conversational application that needs threaded message history with metadata
  • Running multi-step agentic workflows and need durable, resumable state
  • Shipping an edge or offline-capable AI app where network calls to external services aren't an option
  • A researcher or indie developer who wants the power of Chroma + Neo4j + a full relational database in one pip install

Quick Start

Python — 60 seconds to your first agent memory

pip install datacules-agentdb

import agentdb
import numpy as np

# Open (or create) a database
db = agentdb.AgentDB.open("my_agent.agentdb")

# Store a conversation
conv = db.conversations()
conv.create_conversation("chat_1", title="First session")
conv.add_message("chat_1", "user", "What is the capital of France?")
conv.add_message("chat_1", "assistant", "The capital of France is Paris.")

# Store and search a vector memory
col = db.collection("memories", dim=1536)
embedding = np.random.rand(1536).tolist()   # replace with your real embedding
col.upsert("mem_1", embedding, metadata={"topic": "geography", "score": 9})

results = col.search(embedding, top_k=5)
print(results)

# Query with SQL
rows = db.query_json("SELECT * FROM _adb_conversations")
print(rows)

Node.js / TypeScript

npm install @datacules/agentdb

import { AgentDB } from '@datacules/agentdb';

const db = AgentDB.open('my_agent.agentdb');

const col = db.collection('memories', 1536);
col.upsert('mem_1', queryEmbedding, { topic: 'geography' });
const results = col.search(queryEmbedding, { topK: 5 });

Rust

cargo add datacules-agentdb

use agentdb::AgentDB;

let db = AgentDB::open("my_agent.agentdb")?;
let col = db.vectors().collection("memories", 1536)?;
col.upsert(VectorEntry { id: "mem_1".into(), vector: embedding, metadata: None })?;
let results = col.search(&query, SearchOptions { top_k: 5, ..Default::default() })?;

Eight Capabilities in One File

AgentDB bundles eight storage and query primitives that typically require separate services — all in a single embedded file your application owns and controls.

1 — Relational SQL

Full SQL with joins, CTEs, transactions, and indexes. Store any structured data alongside your agent's memory — sessions, users, logs, events — and query it all with standard SQL.

2 — Vector Search

Semantic similarity search using a pure-Rust HNSW index. Search hundreds of thousands of embeddings in milliseconds with support for cosine, euclidean, and dot-product similarity, plus MongoDB-style metadata filtering.

Sub-50 ms ANN on 100,000 vectors at 1,536 dimensions (OpenAI text-embedding-3-small size)

3 — Memory Graph

Model relationships between concepts, entities, and sessions as a typed, weighted graph. Traverse connections with depth-limited queries — ideal for knowledge graphs, agent memory networks, and relationship-aware retrieval.

Graph traversal < 5 ms on 10,000 nodes at depth 2

4 — Full-Text Search

BM25-ranked full-text search with Porter stemming and snippet extraction. Index any content your agent sees and retrieve it by keyword in milliseconds — no Elasticsearch required.

5 — Hybrid Queries

Blend graph traversal and vector similarity in a single query with a tunable alpha parameter. Get results that are both contextually connected and semantically relevant.

6 — Conversation Threading

First-class message threading for any interaction your agent has. Store multi-turn conversations with roles, content, and per-message metadata. Retrieve full history in chronological order.

7 — Workflow Persistence

Durable, resumable state for multi-step agent tasks. Track workflow runs and individual steps — with status, inputs, outputs, and errors — so your agent can survive restarts and resume exactly where it left off.

8 — Reasoning Traces

Tree-structured logs for chain-of-thought, tool calls, and decision sequences. Every step of your agent's reasoning can be persisted, queried, and replayed — invaluable for debugging, auditing, and evaluation.

Performance

Benchmarks run on GitHub Actions (ubuntu-latest, 4 vCPU, 16 GB RAM, Rust stable, release profile).

Operation Scale Latency
Vector search (ANN, cosine) 100k vectors, 1,536 dims ~47 ms
Vector search (ANN, cosine) 10k vectors, 1,536 dims ~8.7 ms
Graph traversal (depth 2) 10k nodes, 50k edges ~0.5 ms
Graph traversal (depth 5) 100k nodes, 500k edges ~19 ms
Full-text search (BM25) 100k documents ~1.2 ms
SQL INSERT (WAL mode) single row ~0.09 ms
Vector upsert single entry ~0.2 ms
Batch upsert 1,000 vectors ~28 ms

Full benchmark details in BENCHMARKS.md.

Multi-Language Support

AgentDB ships a native library for every major language in the AI stack. There is no language-level performance penalty — every SDK wraps the same Rust core.

Language Install Docs
Python pip install datacules-agentdb CPython 3.9+, PyPy, Linux / macOS / Windows
Node.js npm install @datacules/agentdb TypeScript types included
Rust cargo add datacules-agentdb Full API on docs.rs
Go import "github.com/hvrcharon1/agentdb/go" See go/README.md
Java Maven — see java/README.md JNI wrapper
C# / .NET NuGet — see dotnet/README.md P/Invoke wrapper
C / C++ Build libagentdb.so / .dylib / .dll Flat C API included
WASM wasm-pack build --target web In-memory databases today; OPFS persistence coming
CLI See install options below Interactive shell + all operations

CLI Install

Platform Command
Any (Cargo) cargo install datacules-agentdb
macOS / Linux (Homebrew) brew install hvrcharon1/tap/agentdb
Windows (Scoop) scoop bucket add agentdb https://github.com/hvrcharon1/scoop-bucket && scoop install agentdb
Windows (Chocolatey) choco install agentdb
Windows (WinGet) winget install Datacules.AgentDB
Linux (Snap) snap install agentdb
Nix nix run github:hvrcharon1/agentdb
Shell curl -fsSL https://raw.githubusercontent.com/hvrcharon1/agentdb/main/install.sh | sh
PowerShell irm https://raw.githubusercontent.com/hvrcharon1/agentdb/main/install.ps1 | iex 
# Common CLI operations
agentdb shell      my_agent.agentdb          # interactive SQL REPL
agentdb stats      my_agent.agentdb          # database summary
agentdb inspect    my_agent.agentdb          # full report: stats + collections + graph
agentdb sql        my_agent.agentdb "SELECT * FROM sessions LIMIT 10"
agentdb search     my_agent.agentdb memories 0.9 0.1 0.0 --top-k 5
agentdb collections my_agent.agentdb         # list vector collections
agentdb reindex    my_agent.agentdb          # rebuild all HNSW indexes

Docker

docker build -t agentdb .
docker run -v $(pwd):/data agentdb stats my_agent.agentdb
docker run -it -v $(pwd):/data agentdb shell my_agent.agentdb

Why AgentDB?

Modern AI agents have storage needs that today require five or more separate tools — each with its own server, configuration, and network dependency. AgentDB collapses all of them into one embedded file.

What your agent needs Typical solution The problem
Structured storage for sessions, logs, events Relational database No vector search, no graph
Semantic memory retrieval ChromaDB, Qdrant, Pinecone Separate service, network required
Relationship and knowledge graph Neo4j, custom solution Heavy, not embeddable, not offline
Keyword search over stored text Elasticsearch, Typesense Yet another service to operate
Combined graph + semantic retrieval Custom code Fragile, high latency, no standard
All of the above AgentDB One file. Zero servers.

Full Feature Comparison

Feature AgentDB ChromaDB Qdrant Neo4j
Embedded (no server) ✅ ❌ ❌ ❌
Single file ✅ ❌ ❌ ❌
Zero-configuration ✅ ❌ ❌ ❌
ACID transactions + WAL ✅ ❌ ❌ ✅
Relational SQL ✅ ❌ ❌ ❌
Vector / ANN search ✅ ✅ ✅ ❌
Metadata filtering ✅ ⚠️ ✅ ❌
Full-text search (BM25) ✅ ❌ ❌ ❌
Memory graph ✅ ❌ ❌ ✅
Hybrid graph + vector query ✅ ❌ ❌ ❌
Conversation threading ✅ ❌ ❌ ❌
Workflow persistence ✅ ❌ ❌ ❌
Reasoning traces ✅ ❌ ❌ ❌
Python ✅ ✅ ✅ ✅
Node.js ✅ ✅ ✅ ✅
Go ✅ ❌ ✅ ✅
Java ✅ ❌ ✅ ✅
C# / .NET ✅ ❌ ✅ ✅
C FFI ✅ ❌ ❌ ❌
WASM / browser ✅ ❌ ❌ ❌
Works offline / on edge ✅ ❌ ❌ ❌
Free / open source ✅ ✅ ⚠️ ⚠️

API Overview

A brief map of what's available. Full API documentation lives on docs.rs.

What you want to do API entry point
Open / create a database AgentDB::open(path)
Run SQL db.execute(), db.query_json(), db.transaction()
Store & search vectors db.vectors().collection("name", dim)
Add / traverse graph nodes db.memory()
Index & search text db.fts()
Graph + vector blended search db.hybrid_query(...)
Manage conversations db.conversations()
Persist workflow state db.workflows()
Log reasoning traces db.traces()
Get database stats db.stats()

Roadmap

Milestone Status
v0.1.0 — Core (SQL + Vectors + Graphs) ✅ Released
v0.2.0 — Query Power (FTS + Hybrid + Filters) ✅ Released
v0.3.0 — Universal Availability (C FFI, CLI, Python, Node.js, WASM) ✅ Released
v0.4.0 — AI-Native (Conversations, Workflows, Traces + Go/Java/.NET SDKs) ✅ Released
v0.4.5 — Dep upgrades (rusqlite 0.40, pyo3 0.29, bincode 2, thiserror 2), MSRV 1.85 ✅ Released
v0.5.0 — API completeness: 9 new FFI ops, full SDK parity (Go/Node/Java/.NET), hybrid filter, fail_workflow, 9-field DbStats ✅ Released
v0.6.0 — WASM Persistence (OPFS) + Ruby SDK 🔜 Next
v1.0.0 — Ecosystem (LangChain, LlamaIndex, MCP server, AgentDB Sync) + Production Release Planned
v1.0.0 — Production Release Planned

Full detail in ROADMAP.md.

Documentation

Resource Link
Full API reference docs.rs/datacules-agentdb
Architecture deep-dive ARCHITECTURE.md
Changelog CHANGELOG.md
Migration guide MIGRATION.md
Performance benchmarks BENCHMARKS.md
Security policy SECURITY.md

Contributing

AgentDB welcomes contributions. Whether you're fixing a bug, adding a language binding, or improving documentation — we'd love your help.

See CONTRIBUTING.md for the full development setup, PR process, and coding standards.

Quick summary:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feat/your-feature
  3. Write tests for your changes
  4. Run cargo test and cargo clippy — both must pass
  5. Open a pull request with a clear description

To report a security vulnerability, follow the process in SECURITY.md.

License

AgentDB is released under the Unlicense — effectively public domain.
You are free to use, copy, modify, distribute, and sublicense without restriction.
See LICENSE and NOTICE for the full terms.