datacules-agentdb 0.5.0

The default embedded database for AI agents.
One file. Eight layers. Every platform. Zero servers.
Semantic Memory  ·  Vector Search  ·  Memory Graphs  ·  Full-Text Search  ·  Hybrid Queries  ·  Conversations  ·  Workflows  ·  Reasoning Traces
Rust  ·  Python  ·  Node.js  ·  Go  ·  Java  ·  C#  ·  C/C++  ·  WASM  ·  CLI

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

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

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.

CLI Install

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

Full Feature Comparison

API Overview

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

Roadmap

Full detail in ROADMAP.md.

Documentation

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.

Built and maintained by Datacules LLC