agentdb 3.0.0-alpha.9 → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 ruv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,344 +1,323 @@
-# AgentDB v3
+<div align="center">
 
-> **Proof-gated graph intelligence for AI agents — every mutation requires cryptographic proof**
+[![npm version](https://img.shields.io/npm/v/agentdb.svg?style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/agentdb)
+[![npm downloads](https://img.shields.io/npm/dm/agentdb.svg?style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/agentdb)
+[![License](https://img.shields.io/badge/License-MIT_OR_Apache--2.0-yellow?style=for-the-badge)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
-[![npm version](https://img.shields.io/npm/v/agentdb.svg?style=flat-square)](https://www.npmjs.com/package/agentdb)
-[![npm downloads](https://img.shields.io/npm/dm/agentdb.svg?style=flat-square)](https://www.npmjs.com/package/agentdb)
-[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-green?style=flat-square)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
+[![🕸️ RuVector Engine](https://img.shields.io/badge/RuVector_Engine-Rust_+_NAPI-06b6d4?style=for-the-badge&logoColor=white&logo=rust)](https://github.com/ruvnet/ruvector)
+[![🧠 SONA Self-Learning](https://img.shields.io/badge/SONA-Self_Learning-8b5cf6?style=for-the-badge&logoColor=white)](#-self-learning-loop)
+[![🔌 MCP Compatible](https://img.shields.io/badge/MCP-41_tools-D97757?style=for-the-badge&logoColor=white&logo=anthropic)](#-mcp-integration)
+[![⭐ Star on GitHub](https://img.shields.io/github/stars/ruvnet/agentdb?style=for-the-badge&logo=github&color=gold)](https://github.com/ruvnet/agentdb)
 
-AgentDB v3 is the first memory system built specifically for autonomous AI agents with **proof-gated mutations** — every state-changing operation requires a cryptographic proof before execution. Powered by `@ruvector/graph-transformer` with 8 verified graph modules, native Rust performance via NAPI-RS, and 82-byte attestations.
+# AgentDB
 
-## What's New in v3
+**Vector memory that gets smarter every time your agent uses it.**
 
-- **Proof-Gated Mutations** — MutationGuard validates every insert, search, remove, save, and load with structural hashes and attestation tokens
-- **8 Graph-Transformer Modules** — Sublinear attention, verified training, causal attention, Granger extraction, Hamiltonian dynamics, spiking attention, game-theoretic equilibrium, product manifold distance
-- **AttestationLog** — Append-only audit trail with cryptographic proofs for compliance and debugging
-- **GuardedVectorBackend** — Drop-in wrapper that enforces proof gates on any vector backend
-- **21 Active Controllers** — All cognitive memory patterns are production-ready with proof validation
-- **Zero-Native Regression** — Package size reduced from 50.1MB to 1.4MB by removing unused binaries
-- **Browser Support** — Runs in Node.js, browsers, edge functions, and MCP tools via WASM fallback
+</div>
 
-## Quick Start
+A single-file cognitive container — vectors, indexes, learning state, and a cryptographic audit trail in one `.rvf`. Self-learning search improves up to **36% from feedback alone**, with no manual tuning. Runs in Node, the browser, edge runtimes, and offline.
 
-```bash
-# Install v3 Alpha
-npm install agentdb@v3
+<!-- ecosystem-cta:start -->
+### Explore the wider ecosystem
 
-# Or use stable v2
-npm install agentdb@latest
-```
+[![AgentDB: Give your next idea a workspace. Try ruOS.](docs/assets/ecosystem-cta.svg)](https://ruos.cognitum.one/)
 
-## Basic Usage
+Building agents that remember? Explore the wider ecosystem.
 
-```typescript
-import { AgentDB } from 'agentdb';
-
-// Initialize with proof-gated vectorBackend
-const db = new AgentDB({
-  dbPath: './agent-memory.db',
-  dimension: 384,
-  vectorBackend: 'ruvector',
-  enableProofGate: true  // Default: true in v3
-});
+**[Explore Cognitum One](https://cognitum.one/) · [Try ruOS](https://ruos.cognitum.one/)**, an agentic desktop in your browser.
+<!-- ecosystem-cta:end -->
 
-await db.initialize();
-
-// Access controllers
-const reflexion = db.getController('reflexion');
-const reasoning = db.getController('reasoning');
-const causalGraph = db.getController('causalGraph');
-
-// Check proof engine status
-const guard = db.getMutationGuard();
-console.log(guard?.getStats());
-// Output: { engineType: 'native', proofsGenerated: 42, denials: 0 }
-
-// Store episode with automatic proof generation
-await reflexion.storeEpisode({
-  sessionId: 'session-1',
-  task: 'Debug authentication bug',
-  reward: 0.95,
-  success: true,
-  critique: 'OAuth2 PKCE flow was more secure than basic flow',
-  input: 'Users cannot log in',
-  output: 'Working OAuth2 implementation'
-});
+### Why AgentDB?
 
-// Search patterns (proof-validated)
-const patterns = await reasoning.searchPatterns({
-  task: 'authentication security',
-  k: 10,
-  threshold: 0.7
-});
-```
+> Most vector databases store embeddings and call it done. AgentDB watches *which* results your agent actually used, learns from that signal, and ranks the next query better. The bandit underneath also picks the right RL algorithm, the right compression tier, and the right pattern weighting on its own — so the database itself gets sharper while you focus on the agent.
 
-## Architecture
+> The name: a database that thinks like an agent — episodic memory, skill library, causal reasoning, and a learning loop, all in one file. Built by [`rUv`](https://ruv.io) on the [`ruvector`](https://github.com/ruvnet/ruvector) Rust engine.
 
-AgentDB v3 introduces a 3-layer architecture:
+### What AgentDB Does
 
 ```
-┌─────────────────────────────────────────────────────┐
-│                  Application Layer                  │
-│  (ReasoningBank, ReflexionMemory, SkillLibrary)     │
-└─────────────────────────────────────────────────────┘
-                        ↓
-┌─────────────────────────────────────────────────────┐
-│               Proof Validation Layer                │
-│  MutationGuard → AttestationLog → GuardedBackend    │
-└─────────────────────────────────────────────────────┘
-                        ↓
-┌─────────────────────────────────────────────────────┐
-│                  Backend Layer                      │
-│     RuVector (native) → WASM → JavaScript           │
-└─────────────────────────────────────────────────────┘
+Self-Learning Vector Memory
+
+Agent ──► AgentDB (.rvf) ──► HNSW search ──► top-k results
+   │                                              │
+   ▼                                              ▼
+recordFeedback(id, reward)  ◄──  agent uses some, ignores rest
+   │
+   ▼
+Bandit re-tunes ranking / RL choice / compression  ──► next query is smarter
 ```
 
-Every mutation flows through the proof validation layer:
+> **3 lines to self-learning search:**
+> ```typescript
+> const backend = await SelfLearningRvfBackend.create({ learning: true, storagePath: "./my.rvf" });
+> const results = await backend.searchAsync(query, 10);   // search
+> backend.recordFeedback(results[0].id, 0.9);             // learn — next search is smarter
+> ```
 
-1. **Application** calls `storeEpisode()` or `searchPatterns()`
-2. **MutationGuard** generates a proof (structural hash + attestation token)
-3. **AttestationLog** records the proof attempt
-4. **GuardedBackend** validates proof before executing native operation
-5. **Result** returns to application with proof certificate
+---
 
-## Key Features
+## Quick Start
 
-### 1. Proof-Gated Mutations (ADR-060)
+There are **three ways to use AgentDB** depending on what you're building. Pick whichever matches your stack:
 
-Every state mutation requires a cryptographic proof:
+| | **npm library** | **CLI** | **MCP server** |
+|---|---|---|---|
+| **What you get** | TypeScript / JS API for any Node app | `agentdb` binary, scriptable from any shell | 41 tools callable from Claude Code, Cursor, Cline, etc. |
+| **Install** | `npm i agentdb` | `npx agentdb …` (no install) | `claude mcp add agentdb -- npx agentdb mcp start` |
+| **Best for** | Embedding the engine in your own code | Quick experiments, CI scripts, ad-hoc memory | Plugging memory + learning into an LLM agent |
 
-```typescript
-import { MutationGuard } from 'agentdb/security';
+### Path A — npm library
 
-const guard = new MutationGuard({
-  strictMode: true,
-  enableNative: true  // Prefer native proofs
-});
-
-// Insert requires proof
-const proof = guard.generateProof({
-  operation: 'insert',
-  vectorId: 'vec-123',
-  embedding: [0.1, 0.2, ...],
-  metadata: { source: 'reflexion' }
-});
-
-// Proof includes:
-// - structuralHash: SHA-256 of operation + data
-// - attestationToken: 82-byte cryptographic token
-// - timestamp: ISO8601 timestamp
-// - nonce: Random 16-byte nonce
-
-// Backend validates before execution
-if (guard.validateProof(proof)) {
-  backend.insert(proof.vectorId, proof.embedding, proof.metadata);
-}
+```bash
+npm install agentdb
 ```
 
-### 2. Eight Graph-Transformer Modules
-
-Native Rust implementations via `@ruvector/graph-transformer`:
-
-- **Sublinear Attention** — O(n log n) replacing O(n²) JavaScript fallback
-- **Verified Training** — SGD with cryptographic proof of each gradient step
-- **Causal Attention** — Temporal-decay weighted attention for CausalRecall
-- **Granger Extract** — Time-series causal discovery for memory graphs
-- **Hamiltonian Step** — Physics-informed trajectory modeling
-- **Spiking Attention** — Biological integrate-and-fire for episodic memory
-- **Game-Theoretic Attention** — Nash equilibrium for multi-agent routing
-- **Product Manifold Distance** — Curved-space similarity for reasoning patterns
-
 ```typescript
-import { GraphTransformerService } from 'agentdb';
+import { SelfLearningRvfBackend } from 'agentdb';
 
-const transformer = new GraphTransformerService({
-  enableNative: true,
-  modules: ['sublinear', 'causal', 'verified']
+const db = await SelfLearningRvfBackend.create({
+  learning: true,
+  storagePath: './memory.rvf',
 });
 
-await transformer.initialize();
-
-// Use sublinear attention (O(n log n))
-const attended = await transformer.sublinearAttention(
-  queryVector,
-  keyMatrix,
-  valueMatrix
-);
-
-// Verify training step
-const trainingProof = await transformer.verifiedTraining(
-  weights,
-  gradients,
-  learningRate
-);
+await db.insertAsync('doc1', new Float32Array(384), { text: 'Hello world' });
+const hits = await db.searchAsync(queryEmbedding, 5);
+db.recordFeedback(hits[0].id, 1.0);  // it was useful — db gets smarter
 ```
 
-### 3. Twenty-One Active Controllers
-
-All cognitive memory patterns are production-ready:
+### Path B — CLI in 10 seconds
 
-- **ReflexionMemory** — Self-critique and episodic replay
-- **SkillLibrary** — Lifelong learning with skill consolidation
-- **ReasoningBank** — Pattern learning and adaptive memory
-- **CausalMemoryGraph** — Intervention-based causality tracking
-- **CausalRecall** — Utility-based retrieval with uplift scoring
-- **ExplainableRecall** — Provenance certificates with Merkle proofs
-- **NightlyLearner** — Automated pattern discovery
-- **LearningSystem** — 9 RL algorithms (Q-Learning, DQN, PPO, MCTS, etc.)
-- **EmbeddingService** — Multi-provider embeddings (Transformers.js, OpenAI)
-- **WASMVectorSearch** — Browser-compatible vector search
-- **HNSWIndex** — HNSW graph indexing for approximate nearest neighbor
-- **AttentionService** — 5 attention mechanisms (causal, spiking, game-theoretic)
-- **And 9 more** — See [docs/CONTROLLERS.md](./docs/CONTROLLERS.md)
+```bash
+# Try it without installing
+npx agentdb init my-memory.rvf
+npx agentdb add my-memory.rvf "vector memory that learns"
+npx agentdb search my-memory.rvf "self-improving search" --top-k 5
+```
 
-## Installation
+### Path C — MCP server (Claude Code, Cursor, etc.)
 
 ```bash
-# v3 Alpha (proof-gated mutations)
-npm install agentdb@v3
+claude mcp add agentdb -- npx agentdb@latest mcp start
+```
 
-# Stable v2 (production-ready)
-npm install agentdb@latest
+That registers 41 MCP tools — `agentdb_pattern_store`, `agentdb_pattern_search`, `agentdb_hierarchical_store`, `agentdb_causal_edge`, `agentdb_skill_library`, `agentdb_reflexion`, etc. They call the same engine the npm library does, just over Claude's tool-calling surface.
 
-# With optional native addons for 150x performance
-npm install agentdb@v3 ruvector@latest
+---
 
-# For browser environments (WASM only)
-npm install agentdb@v3
-# Native addons will be skipped automatically
-```
+## What You Get
+
+| Capability | Description |
+|------------|-------------|
+| 🧠 **Self-Learning Search** | Up to **+36% search quality** from feedback alone — Thompson Sampling bandit re-tunes ranking, RL choice, and compression tier with zero manual config |
+| 🐝 **Cognitive Memory** | 6 human-inspired patterns — episodic replay (Reflexion), skill library, causal reasoning, hierarchical context, semantic clustering, working memory |
+| 🤖 **9 RL Algorithms** | Q-Learning, SARSA, DQN, PPO, Actor-Critic, Policy Gradient, Decision Transformer, MCTS, Model-Based RL — bandit picks the right one per task |
+| ⚡ **150× faster than SQLite** | RuVector Rust engine via NAPI bindings; HNSW vector search; sub-millisecond reads on 100k+ vectors |
+| 🔍 **Hybrid Search** | BM25 keyword + dense vector fused with Reciprocal Rank Fusion — exact terms *and* semantic intent in one query |
+| 🕸️ **Graph Intelligence** | Cypher queries, causal edges, GNN 8-head attention (+12.4% recall), hyperedges for n-ary relationships |
+| 💾 **Single-file Storage** | Everything (vectors, indexes, learning state, audit log) in one `.rvf` "Cognitive Container" — no servers, no API keys, no monthly bills |
+| 🎯 **Quantization** | 4-32× memory reduction with PQ8 / PQ4 / binary quantization; minimal recall loss; runs on commodity hardware |
+| 🔌 **41 MCP Tools** | First-class Claude Code / Cursor / Cline integration — pattern store, search, skill library, reflexion, causal edges, hierarchical recall, delete |
+| 🌐 **Runs Anywhere** | Node, browser (WASM), edge runtimes, fully offline — same API, same `.rvf` file |
+| 🛡️ **Enterprise Security** | JWT auth, API key rotation, Argon2id hashing, SOC2 / GDPR audit trails, cryptographic witness chain |
+| 🔗 **agentic-flow Integration** | Drop-in for [`agentic-flow`](https://github.com/ruvnet/agentic-flow) — backs ReasoningBank, MemoryController, NightlyLearner, and 30+ agents |
 
-## API Overview
+---
 
-### Core Class
+## 🧠 Self-Learning Loop
 
-```typescript
-import { AgentDB } from 'agentdb';
-
-const db = new AgentDB({
-  dbPath: './memory.db',
-  dimension: 384,
-  vectorBackend: 'ruvector',  // or 'hnswlib' | 'sqlite'
-  enableProofGate: true,
-  strictMode: true
-});
+Most retrieval systems are read-only. AgentDB closes the loop:
 
-await db.initialize();
 ```
-
-### Controller Access
-
-```typescript
-// Get controllers by name
-const reflexion = db.getController('reflexion');
-const reasoning = db.getController('reasoning');
-const skills = db.getController('skills');
-const causalGraph = db.getController('causalGraph');
-
-// Access proof engine
-const guard = db.getMutationGuard();
-const stats = guard?.getStats();
+search ──► top-k ──► agent picks the useful ones ──► recordFeedback()
+                                                            │
+                                                            ▼
+                                              Thompson Sampling bandit
+                                                            │
+                                                            ▼
+                       re-weights ranking · re-picks RL algorithm · re-tunes compression
+                                                            │
+                                                            ▼
+                                                   next search is sharper
 ```
 
-### Security Primitives
+The bandit isn't a gimmick — it's used at four decision points:
 
-```typescript
-import { MutationGuard, AttestationLog } from 'agentdb/security';
+1. **Pattern ranking** — which historical pattern matches this new query best?
+2. **RL algorithm selection** — Q-Learning for tabular tasks, PPO for continuous control, MCTS for planning, etc.
+3. **Compression tier** — full precision when accuracy matters, PQ4 when memory does.
+4. **Skill composition** — chain skill A→B→C or skill A→D→E?
 
-// Create guard
-const guard = new MutationGuard({
-  strictMode: true,
-  enableNative: true,
-  logPath: './attestations.log'
-});
+Each decision logs reward over time. Bad arms decay fast. Good arms stick.
 
-// Generate proof
-const proof = guard.generateProof({
-  operation: 'insert',
-  vectorId: 'vec-123',
-  embedding: embedding,
-  metadata: { source: 'test' }
-});
+---
 
-// Access attestation log
-const log = guard.getAttestationLog();
-const recentProofs = await log.query({ limit: 10 });
-```
+## ⚡ Performance
 
-### Backend Integration
+| Metric | AgentDB | Baseline | Source |
+|---|---|---|---|
+| Vector search (100k vectors) | **<1 ms** | ~150 ms (SQLite + cosine loop) | `benchmarks/hnsw/` |
+| HNSW query (1M vectors) | **2–5 ms** | ~100 ms (brute force) | `benchmarks/vector-search/` |
+| Bulk insert (10k vectors) | **<100 ms** | ~12 s (sql.js) | `benchmarks/database/` |
+| Memory footprint (1M × 384d) | **~96 MB (PQ8)** | ~1.5 GB (raw f32) | `benchmarks/quantization/` |
+| Self-learning quality lift | **+36%** | n/a | `benchmarks/ruvector-performance.test.ts` |
+| GNN attention recall | **+12.4%** | baseline HNSW | `benchmarks/attention-performance.ts` |
 
-```typescript
-import { GuardedVectorBackend } from 'agentdb/backends';
+Run them yourself: `npm run bench` from this repo.
 
-// Wrap any backend with proof validation
-const guardedBackend = new GuardedVectorBackend(rawBackend, guard);
+---
 
-// All operations require proof
-await guardedBackend.insert(proof);
-await guardedBackend.search(query, k, proof);
-```
+## 🔌 MCP Integration
+
+41 tools across six families, all callable from Claude Code, Cursor, Cline, or any MCP-compatible client:
+
+<details>
+<summary><strong>Pattern Store / Search (8 tools)</strong></summary>
+
+| Tool | Purpose |
+|---|---|
+| `agentdb_pattern_store` | Store a successful pattern with embedding + metadata |
+| `agentdb_pattern_search` | Semantic search for similar past patterns |
+| `agentdb_pattern_stats` | Retrieval stats, cache hits, hit-rate trends |
+| `agentdb_pattern_delete` | Remove a pattern by id |
+| `agentdb_batch_insert` | Bulk insert many patterns at once |
+| `agentdb_batch_search` | Parallel multi-query search |
+| `agentdb_export` | Dump patterns to JSON / CSV |
+| `agentdb_import` | Load patterns from JSON / CSV |
+
+</details>
+
+<details>
+<summary><strong>Hierarchical / Causal Memory (10 tools)</strong></summary>
+
+| Tool | Purpose |
+|---|---|
+| `agentdb_hierarchical_store` | Tier-aware memory store (working / short / long) |
+| `agentdb_hierarchical_recall` | Tier-filtered retrieval |
+| `agentdb_hierarchical_delete` | Remove hierarchical entry by key |
+| `agentdb_causal_edge` | Add a causal relationship between memories |
+| `agentdb_causal_edge_delete` | Remove a causal edge by id |
+| `agentdb_causal_node_delete` | Cascade-delete a node + incident edges |
+| `agentdb_edges_by_endpoints` | Bulk-delete edges by `(from, to, label)` |
+| `agentdb_causal_query` | Cypher-like graph queries |
+| `agentdb_causal_explain` | Explain why two memories are connected |
+| `agentdb_attestation_log` | Cryptographic audit trail |
+
+</details>
+
+<details>
+<summary><strong>Reflexion + Skill Library (12 tools)</strong></summary>
+
+| Tool | Purpose |
+|---|---|
+| `agentdb_reflexion_store` | Store an episode (task + outcome + critique) |
+| `agentdb_reflexion_recall` | Retrieve relevant past episodes |
+| `agentdb_reflexion_delete` | Remove an episode |
+| `agentdb_reflexion_rebuild` | Re-hydrate vector index from durable SQL |
+| `agentdb_skill_create` | Create a reusable skill from a pattern |
+| `agentdb_skill_compose` | Chain skills A→B→C with bandit-picked composition |
+| `agentdb_skill_search` | Find skills by intent embedding |
+| `agentdb_critique_summary` | Summarize lessons from past failures |
+| `agentdb_success_strategies` | Surface what worked across past episodes |
+| `agentdb_task_stats` | Per-task win-rate, latency, reward trends |
+| `agentdb_prune` | TTL + quality-based episode pruning |
+| `agentdb_warm_cache` | Pre-populate query cache for a session |
+
+</details>
+
+<details>
+<summary><strong>Learning + Routing (11 tools)</strong></summary>
+
+| Tool | Purpose |
+|---|---|
+| `agentdb_learning_route` | Route a task to the right RL algorithm |
+| `agentdb_learning_train` | Train a specific RL agent on episodes |
+| `agentdb_learning_predict` | Get an action prediction for a state |
+| `agentdb_bandit_update` | Update bandit reward for an arm |
+| `agentdb_bandit_pick` | Sample the best arm under Thompson Sampling |
+| `agentdb_consolidate` | Run NightlyLearner consolidation pipeline |
+| `agentdb_compose` | Combine memory patterns into a strategy |
+| `agentdb_synthesize` | Build a context window from related memories |
+| `agentdb_explain_recall` | Feature-attributed retrieval results |
+| `agentdb_diversity_rank` | MMR-rerank for diverse top-k |
+| `agentdb_metadata_filter` | Filtered semantic search |
+
+</details>
 
-## Performance
+---
 
-**Proof Generation:**
-- Native (NAPI-RS): ~50μs per proof
-- WASM: ~200μs per proof
-- JavaScript: ~500μs per proof
+## 🔗 Used By
 
-**Vector Operations (with RuVector):**
-- Insert: 150x faster than JavaScript
-- Search: 61μs p50 latency (96.8% recall@10)
-- Pattern search: 32.6M ops/sec with caching
+AgentDB powers the memory + learning layer in:
 
-**Package Size:**
-- v2: 50.1MB (with unused native binaries)
-- v3: 1.4MB (zero-native regression fixed)
+| Project | What it uses AgentDB for |
+|---|---|
+| [**`agentic-flow`**](https://github.com/ruvnet/agentic-flow) | ReasoningBank backend, ReflexionMemory, NightlyLearner consolidation, 30+ agent memory namespaces |
+| [**`ruflo`**](https://github.com/ruvnet/ruflo) | Plugin marketplace memory, agent federation audit log, hierarchical recall for /adr-index, swarm coordination patterns |
+| [**`@ruvector`**](https://github.com/ruvnet/ruvector) | Reference downstream for the Rust engine — every release is verified against AgentDB's test suite |
 
-## Documentation
+If you ship something on top of AgentDB, [open an issue](https://github.com/ruvnet/agentdb/issues) and we'll add you.
+
+---
 
-- **[ADR-060: Proof-Gated Mutations](./docs/adr/ADR-060-agentdb-v3-proof-gated-graph-intelligence.md)** — Architecture decision record
-- **[Controllers Guide](./docs/CONTROLLERS.md)** — All 21 controllers documented
-- **[MCP Tools Reference](./docs/MCP_TOOLS.md)** — 32 MCP tools for Claude Code
-- **[Migration Guide](./MIGRATION_v3.0.0.md)** — Upgrade from v2 to v3
-- **[Security Model](./docs/SECURITY.md)** — Proof validation and attestation
+## 🐳 Docker / Edge / Browser
 
-## MCP Integration (Claude Code)
+AgentDB compiles to four targets from one source:
 
-Zero-code integration with AI coding assistants:
+| Target | What | When |
+|---|---|---|
+| **Node native** | NAPI bindings (Linux, macOS, Windows; x64 + arm64) | Backend services, CLI, MCP server |
+| **Node WASM fallback** | sql.js + WASM engine | Restricted hosts that can't run NAPI |
+| **Browser** | Pure WASM bundle | Offline-first apps, edge functions, IDE extensions |
+| **Docker** | `docker-compose.yml` in `docker/` | Local dev, CI, prod deploy |
 
 ```bash
-# One-command setup
-claude mcp add agentdb npx agentdb@v3 mcp start
-
-# Now Claude Code can:
-# - Store reasoning patterns with proof validation
-# - Search 32.6M patterns/sec for relevant approaches
-# - Learn from successful task completions
-# - Build reusable skills with attestation logs
-```
+# Browser
+import { createBrowserDb } from 'agentdb/browser';
 
-## License
+# Docker
+docker compose -f docker/docker-compose.yml up
+```
 
-MIT OR Apache-2.0
+---
 
-See [LICENSE-MIT](LICENSE-MIT) and [LICENSE-APACHE](LICENSE-APACHE) for details.
+## Documentation
 
-## Contributing
+| Doc | When to read it |
+|---|---|
+| [**Full README** (deep)](docs/README-full.md) | Every feature, every API, every option — the complete reference (2,900+ lines) |
+| [**PUBLISHING.md**](docs/PUBLISHING.md) | npm publish flow, dist-tag policy, release verification |
+| [**ADR-071**](docs/ADR-071-agentdb-ruvector-wasm-capabilities-review.md) | WASM integration design |
+| [**ADR-072**](docs/ADR-072-ruvector-advanced-features-integration.md) | RuVector advanced-feature integration |
+| [**Examples**](examples/) | End-to-end runnable scripts — RAG chatbot, code-review agent, RL training, edge deploy |
+| [**Benchmarks**](benchmarks/) | Reproducible perf harness — HNSW, attention, quantization, RL, end-to-end |
 
-We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+---
 
-## Acknowledgments
+## Repository
 
-AgentDB v3 builds on research from:
-- **RuVector** — Native Rust vector database (150x faster)
-- **Reflexion** (Shinn et al., 2023) — Self-critique and episodic replay
-- **Causal Inference** (Pearl, Judea) — Intervention-based causality
-- **HNSW** (Malkov & Yashunin, 2018) — Approximate nearest neighbor search
-- **Graph Neural Networks** — Attention mechanisms for memory navigation
+| | |
+|---|---|
+| 📦 **npm** | [`agentdb`](https://www.npmjs.com/package/agentdb) |
+| 🌐 **Source** | https://github.com/ruvnet/agentdb |
+| 🐛 **Issues** | https://github.com/ruvnet/agentdb/issues |
+| 🎨 **Marketing site** | [`ui/`](./ui) (Vite + React + shadcn/ui) |
+| 🧬 **Engine** | [`@ruvector`](https://github.com/ruvnet/ruvector) (Rust + NAPI) |
+| 🔗 **Reference consumer** | [`agentic-flow`](https://github.com/ruvnet/agentic-flow) (uses this as a git submodule at `packages/agentdb/`) |
 
 ---
 
-**Built with ❤️ for the agentic era**
+## Support
+
+| Resource | Link |
+|---|---|
+| Documentation | [docs/README-full.md](docs/README-full.md) |
+| Issues & Bugs | [GitHub Issues](https://github.com/ruvnet/agentdb/issues) |
+| Enterprise | [ruv.io](https://ruv.io) |
+| Community | [Agentics Foundation Discord](https://discord.com/invite/dfxmpwkG2D) |
+| Engine | [`ruvector`](https://github.com/ruvnet/ruvector) |
+| Powered by | [Cognitum.one](https://cognitum.one) |
+
+## License
 
-[Documentation](./docs/) | [GitHub](https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb) | [npm](https://www.npmjs.com/package/agentdb)
+[MIT](LICENSE) OR Apache-2.0 — [RuvNet](https://github.com/ruvnet)

package/dist/schemas/frontier-schema.sql

@@ -338,6 +338,13 @@ WHERE e1.id != e2.id AND e2.id != e3.id AND e1.id != e3.id
 -- Version: 2.0.0 (Frontier Features)
 -- Features: Causal Memory Graph, Explainable Recall Certificates
 -- Compatible with: AgentDB 1.x
+--
+-- Performance Optimization:
+-- Apply composite index migration (003_composite_indexes.sql) for:
+--   - 30-50% faster causal edge queries
+--   - Optimized causal chain traversal (multi-hop reasoning)
+--   - Faster experiment analysis and A/B testing
+--   - See: db/migrations/README.md for details
 -- ============================================================================
 
 -- ============================================================================

package/dist/schemas/schema.sql

@@ -379,4 +379,11 @@ END;
 -- Schema version: 1.0.0
 -- Compatible with: SQLite 3.35+, sqlite-vec (optional), sqlite-vss (optional)
 -- WASM compatible: Yes (via SQLite-WASM + OPFS)
+--
+-- Performance Optimization:
+-- For production deployments, apply composite index migration for 30-50% query speedup:
+--   - Migration file: db/migrations/003_composite_indexes.sql
+--   - Adds 40+ composite indexes for common query patterns
+--   - Trade-off: 2x slower writes, +15-20% storage (acceptable for read-heavy workloads)
+--   - See: db/migrations/README.md for details
 -- ============================================================================