AgentNativeDB

🤖 Agent-Native Database — Sessions, Memory, Decisions as First-Class Citizens

A purpose-built database system designed from the ground up for AI agents.
Combines a SQL query engine, vector search (HNSW), graph store, knowledge/lineage tracking, and MCP server integration — all in a single Go binary.

---

✨ Why AgentNativeDB?

The Problem: AI agents need persistent memory, structured data, vector search, and knowledge graphs — but stitching together multiple databases is fragile and complex.

The Solution: AgentNativeDB is the agent-native database that combines everything into a single binary. Sessions, memories, and decisions are first-class data types, not afterthoughts.

🎯 Key Highlights

Feature	What It Means for You
🤖 Agent-Native Schema	Sessions, memories, decisions, and tasks are built-in table types with optimized storage
⚡ SQL Query Engine	Hand-written lexer → parser → planner → executor — SELECT/INSERT/UPDATE/DELETE, WHERE, JOIN, GROUP BY, ORDER BY, LIMIT, aggregations
🔍 Vector Search	Custom HNSW index with cosine/L2/dot-product distance — no third-party vector libraries
🕸️ Graph Store	Adjacency-list storage with BFS, K-hop, shortest-path queries — all persisted on BadgerDB
📊 Data Lineage	Track data provenance and transformation history through the knowledge layer
🔗 MCP Server	Model Context Protocol (stdio) — plug into Cursor, Claude Desktop, or any MCP-compatible client
🌐 HTTP API	RESTful endpoints for sessions, memories, decisions, and SQL queries
💻 Interactive CLI	Local SQL REPL with syntax highlighting, command history, and auto-completion
🖥️ Web UI	Svelte-based dashboard embedded into the binary — table management, data visualization, SQL editor
📦 Pure Go	Single binary, zero CGO, no external runtime dependencies — only BadgerDB (pure Go KV store)

---

🚀 Get Started in 30 Seconds

# Install (pick one)
npm install -g andb-installer # npm
pip install andb-installer # PyPI / pipx
go install github.com/startvibecoding/AgentNativeDB/cmd/andb@latest # Go# Build from source
git clone https://github.com/startvibecoding/AgentNativeDB.git
cd AgentNativeDB
make build

Supported Platforms: Linux (x86_64, arm64), macOS (x86_64, arm64), Windows (x86_64)

Run

# HTTP server (default: 0.0.0.0:8400)
./bin/andb server
# MCP server (stdio transport)
./bin/andb server -mode mcp
# Interactive SQL CLI (local)
./bin/andb cli
# HTTP client (connect to remote server)
./bin/andb client -server localhost:8400
# Version
./bin/andb version

Uninstall:

npm uninstall -g andb-installer
pip uninstall andb-installer

---

🎮 SQL Query Examples

-- Create tablesCREATETABLEagent_sessions (
id VARCHAR(64) PRIMARY KEY,
agent_id VARCHAR(64),
state VARCHAR(32),
created_at INTEGER
);
CREATETABLEagent_memories (
id VARCHAR(64) PRIMARY KEY,
session_id VARCHAR(64),
content TEXT,
importance FLOAT
);
-- Basic queriesSELECT*FROM agent_sessions WHERE state ='active';
-- AggregationSELECT agent_id, COUNT(*) as cnt FROM agent_sessions GROUP BY agent_id;
-- JOINSELECTs.agent_id, m.contentFROM agent_sessions s
JOIN agent_memories m ONs.id=m.session_idWHEREm.importance>0.7;
-- Sorting and paginationSELECT*FROM agent_memories ORDER BY importance DESCLIMIT10;
-- Full-text search (INVERTED index)CREATETABLEdocs (id VARCHAR(64) PRIMARY KEY, body TEXT);
CREATE FULLTEXT INDEX idx_docs_body ON docs(body);
SELECT*FROM docs WHERE MATCH(body) AGAINST ('agent memory');
-- Vector searchCREATETABLEembeddings (id VARCHAR(64) PRIMARY KEY, embedding FLOAT);
CREATE VECTOR INDEX idx_emb ON embeddings(embedding) WITH (dimensions=128);
SELECT*FROM vector_search(idx_emb, '[0.1, 0.2, ...]', 10);
-- Graph queries
CREATE GRAPH TABLE edges (src VARCHAR(64), dst VARCHAR(64));
SELECT*FROM graph_bfs(edges, 'node_001', 3);
SELECT*FROM graph_shortest_path(edges, 'node_001', 'node_010');

---

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│ API Layer │
│ HTTP REST │ MCP Server │ CLI │ Web UI │
├─────────────────────────────────────────────────┤
│ Agent Runtime │
│ Session │ Memory │ Decision │ Coordinator │ Audit│
├─────────────────────────────────────────────────┤
│ Unified Query Layer │
│ SQL Engine │ Graph Query │ Vector Search │
├─────────────────────────────────────────────────┤
│ Storage Engine │
│ BadgerDB │ HNSW Index │ Graph Store │
└─────────────────────────────────────────────────┘

Project Structure

AgentNativeDB/
├── cmd/andb/ # Single entry point (server, cli, client, version)
├── api/
│ ├── http/ # RESTful HTTP API
│ └── mcp/ # MCP Server (stdio transport)
├── config/ # Configuration management
├── internal/
│ ├── storage/ # Storage engine abstraction + LRU cache
│ ├── storage/badger/ # BadgerDB implementation
│ ├── model/ # Core data types (Session, Memory, Decision, Entity)
│ ├── agent/ # Agent runtime (session, memory, decision, RAG, audit)
│ ├── query/sql/ # SQL engine (lexer → parser → planner → executor)
│ ├── query/sql/index/ # Secondary indexes (Hash, BTree, Inverted/FullText)
│ ├── query/graph/ # Graph query surface
│ ├── query/vector/ # Vector query surface
│ ├── vector/ # HNSW vector index
│ ├── graph/ # Graph store (adjacency list, BFS, K-hop)
│ ├── knowledge/ # Data lineage tracking
│ └── util/ # UUID v7 generation
├── sdk/ # Go SDK
├── ui/ # Svelte + Vite Web UI (embedded into binary)
├── docs/ # Design document
└── examples/ # Example scripts

---

📚 API Reference

HTTP Endpoints

Method	Path	Description
POST	/api/v1/sessions	Create session
GET	/api/v1/sessions/{id}	Get session
PATCH	/api/v1/sessions/{id}	Update session
DELETE	/api/v1/sessions/{id}	Delete session
GET	/api/v1/sessions	List sessions
POST	/api/v1/memories	Store memory
GET	/api/v1/memories?session_id=	List memories
POST	/api/v1/decisions	Record decision
GET	/api/v1/decisions?session_id=	List decisions
GET	/api/v1/decisions/{id}/tree	Decision tree
POST	/api/v1/query	SQL query
GET	/health	Health check

MCP Tools

Tool	Description
query_sql	Execute SQL query
create_session	Create agent session
store_memory	Store agent memory
recall_memories	Retrieve agent memories
record_decision	Record agent decision

---

🛠️ Built-in Commands

Command	Description
./bin/andb server	Start HTTP API server (default: 0.0.0.0:8400)
./bin/andb server -mode mcp	Start MCP server (stdio transport)
./bin/andb cli	Interactive SQL REPL (local database)
./bin/andb client -server host:port	HTTP client (connect to remote)
./bin/andb version	Show version

---

🔧 Configuration

Settings File

Location	Platform	Scope
config.json	All	Project-level configuration

{
"server": {
"host": "0.0.0.0",
"port": 8400
},
"storage": {
"data_dir": "./data"
}
}

Command-Line Flags

./bin/andb server # Default: 0.0.0.0:8400
./bin/andb server -host 127.0.0.1 # Bind to localhost
./bin/andb server -port 9000 # Custom port
./bin/andb cli # Default data dir
./bin/andb cli -data /path/to/data # Custom data dir
./bin/andb client -server host:port # Connect to remote

---

🛠️ Development

# Build the Web UI (Vite) then the binary
make build
# Build only the Go binary (no UI rebuild)
go build -o bin/andb ./cmd/andb
# Run server
make run
# Run tests
make test# Run tests with race detector
make race
# Benchmarks
make bench
# Lint / format / vet
make lint
# Full check (fmt + vet + test)
make check
# Clean build artifacts
make clean

---

📊 Tech Stack

Component	Choice	Rationale
Language	Go 1.23+	Single binary, no runtime deps, cross-compile
KV Store	BadgerDB	Pure Go, no CGO, built-in LSM-tree, WAL, MVCC
Vector Index	Custom HNSW	Supports cosine/L2/dot distance, zero external deps
Graph Store	Custom adjacency list	Persisted on BadgerDB
SQL Engine	Custom recursive descent	Supports full SQL subset
Web UI	Svelte + Vite	Embedded into binary at build time
Protocol	MCP (stdio)	Standard agent-tool integration protocol

---

🤝 Contributing

We welcome contributions! See AGENTS.md for project conventions.

git clone https://github.com/startvibecoding/AgentNativeDB.git
cd AgentNativeDB
make build
make test

---

📄 License

MIT — see LICENSE for details.

---

Ready to build agent-native data infrastructure? ⭐ Star this repo and get started!