AgentDB

3.0.0-alpha.11 verified Sat Apr 25 auth: no javascript

AgentDB v3 (3.0.0-alpha.11) is a proof-gated graph intelligence database for AI agents, requiring cryptographic proof for every state mutation. It provides native Rust performance via @ruvector/graph-transformer with 8 verified graph modules, including HNSW search, causal reasoning, and reflexion memory. The library supports episodic memory, skill libraries, and lifelong learning with explainable provenance. Released as alpha, it targets Node.js >=18.0.0 and ships TypeScript types. Key differentiators: mandatory proof verification on mutations, causal reasoning capabilities, and native Rust acceleration.

Common errors

error TypeError: agentdb_1.AgentDB is not a constructor ↓

cause Using CJS require() on an ESM-only package.

fix

Change to import { AgentDB } from 'agentdb' and ensure your project uses ES modules (set 'type': 'module' in package.json).

error Error: Proof verification failed: invalid signature ↓

cause Mutations attempted without a valid cryptographic proof.

fix

Before mutating, call graph.prove() with the appropriate parameters and pass the proof to the mutation method.

error Cannot find module 'agentdb/graph' or its corresponding type declarations. ↓

cause Subpath import not resolved; possibly due to bundler misconfiguration or missing types.

fix

If using TypeScript, ensure 'moduleResolution' is set to 'node16' or 'bundler'. For JavaScript, check that the package is correctly installed.

Warnings

breaking AgentDB v3 is a complete rewrite. APIs from v2.x are incompatible. Migrate by reviewing new proof-gated mutation patterns. ↓

fix Update all code to use the new v3 API. Refer to migration guide at https://github.com/ruvnet/agentic-flow/wiki/v3-migration.

deprecated The old v2 API symbols like Agent, MemoryGraph are no longer exported; use AgentDB and initGraph instead. ↓

fix Replace Agent with AgentDB.create() and MemoryGraph with initGraph(). Use subpath imports for specific modules.

gotcha All graph mutations (insert, update, delete) require a valid cryptographic proof. Omitting proof will throw an error. ↓

fix Always call .prove() before mutation or use the proof returned from the mutation method if available.

breaking Node.js versions below 18 are not supported. The package uses global fetch and Web Crypto API. ↓

fix Upgrade Node.js to 18 or later. If stuck on older Node, use agentdb v2.x (last v2 release is 2.3.6).

Install

npm install agentdb

yarn add agentdb

pnpm add agentdb

Imports

AgentDB
wrong
```
const AgentDB = require('agentdb')
```
correct
```
import { AgentDB } from 'agentdb'
```
AgentDB v3 is ESM-only. Use ESM imports; CJS require will fail.
initGraph
wrong
```
import { initGraph } from 'agentdb'
```
correct
```
import { initGraph } from 'agentdb/graph'
```
initGraph is exported from a subpath 'agentdb/graph', not the main package entry.
Proof
wrong
```
import { Proof } from 'agentdb'
```
correct
```
import type { Proof } from 'agentdb/types'
```
Proof is a TypeScript type only. Use type import to avoid runtime overhead.

Quickstart

Creates an AgentDB instance, initializes a memory graph with 128 dimensions, inserts a node, generates a cryptographic proof, and performs a search query.

import { AgentDB } from 'agentdb';
import { initGraph } from 'agentdb/graph';
import type { Proof } from 'agentdb/types';

async function main() {
  const db = await AgentDB.create({ path: './agentdb_data' });
  const graph = await initGraph({ type: 'memory', dimensions: 128 });
  await graph.insert({ id: '1', vector: new Float32Array(128).fill(0.5), metadata: { task: 'learn' } });
  const proof: Proof = await graph.prove({ id: '1' });
  console.log('Proof:', proof.hash);
  const results = await graph.search({ vector: new Float32Array(128).fill(0.4), k: 10 });
  console.log('Search results:', results);
  await db.close();
}
main().catch(console.error);