AgentDB (Browser Demo)

This is a browser-based prototype, not the production AgentDB. The planned production AgentDB is a Rust single-binary embedded database. This demo runs a TypeScript query engine in the browser and saves its state in localStorage.

What Works

• SQL-like queries, exact vector search, HNSW, BM25, and hybrid RRF ranking

• Agent memory with store, recall, forget, importance, and decay

• 44 browser tool calls, including an append-only SHA-256 evidence ledger

• Scripted Agent Desk walkthrough: clarification pause, table search, read-role write refusal, and a receipt-backed because-line; this is not a model-driven agent. SQL remains in the developer nav

• A Node HTTP prototype at POST /mcp with server/discover, tools/list, and tools/call, version/routing headers, and signed stateless clarification

• Read/write/admin role switching for trying the demo; this is a UI control, not an authorization boundary

• Simulated operation log, JSON snapshot, checkpoint, and replay

• Snapshot export and import

Related MCP server: Apigee X AI Gateway

What Does Not Work Yet

• The HTTP implementation covers discovery, tool listing/calls, routing headers, and cross-instance clarification; other MCP methods, stdio, authorization, and full protocol conformance remain unfinished

• The evidence ledger and deterministic receipt explanations are an early browser prototype; replay returns a read-only ledger reconstruction, and policy evaluation and the full audit explanation system are not done

• No operating-system database file; state is stored in browser localStorage

• No server-side authorization or security boundary in the demo

• Embeddings use a deterministic feature hash, not a neural model

• No production-grade crash durability, concurrent writers, or scale claims

Run Locally

Requires Node.js 22 or newer.

npm install
npm run dev

Open the local development URL printed by Vite. The application works in the browser and does not require a database service.

To run the separate HTTP transport prototype, set a secret of at least 32 characters and start the seeded in-memory server:

AGENTDB_REQUEST_STATE_SECRET='replace-with-a-long-random-secret' npm run start:http

It listens on http://127.0.0.1:3000/mcp by default. The server currently seeds an in-memory demo engine at startup; it is not persistent storage or an authorization boundary.

Tests

npm test

The Node test runner executes 14 engine, evidence, agent-desk-flow, discovery-shape, header-routing, and cross-instance clarification tests across src/lib/agentdb/*.test.ts.

The source also passes npx tsc --noEmit.

Roadmap

See MASTER_PROMPT.md for the target architecture and phased roadmap. Phase 1 still targets full MCP transport coverage, policy evaluation, and the complete plain-English explanation system.