ruvnet-kb-first
v6.5.3
RuvNet KB-First Application Builder - Build intelligent applications on expert knowledge
0/weekUpdated 1 months agoMITUnpacked: 11.7 MB
Published by rUv
npm install ruvnet-kb-firstUpdated: 2026-01-02 14:00:00 EST | Version 6.5.2
Created: 2026-01-01 15:28:53 EST
RuvNet KB-First Application Builder v6.5.2
Build Intelligent Applications on Expert Knowledge
$3
- 17,524 entries embedded directly in the npm package
- Zero infrastructure - works offline, no PostgreSQL required
- 15-30ms search latency (1,340x faster than PostgreSQL)
- Auto-update detection - knows when KB needs refresh
Text Version (for AI/accessibility)
``
RUVNET-KB-FIRST ARCHITECTURE
┌─────────────────────────────────────────────────────────────────────┐
│ │
│ User runs: npx ruvnet-kb-first │
│ │ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ KB Discovery │ │
│ │ Layer │ │
│ └──────────┬──────────┘ │
│ ┌───────────────┼───────────────┐ │
│ ▼ ▼ ▼ │
│ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ TIER 1 │ │ TIER 2 │ │ TIER 3 │ │
│ │ Full KB │ │ Starter │ │ None │ │
│ │ 230K+ │ │ 500 ent │ │ Struct │ │
│ └───────────┘ └───────────┘ └───────────┘ │
│ │
│ Fallback: Tier 1 → Tier 2 → Tier 3 (graceful degradation) │
│ │
└─────────────────────────────────────────────────────────────────────┘
`
RuvNet-KB-First is a methodology for building applications where curated expert knowledge drives intelligent decision-making. Every response is grounded in verified sources. Every decision can be traced. Every gap is detected and logged.
---
Quick Start
$3
`bash`Run dashboard (shows status, scores, recommendations)
npx ruvnet-kb-first
$3
`bashInitialize with your knowledge base
npx ruvnet-kb-first init --kb ask_ruvnet
Or run interactive setup
npx ruvnet-kb-first init
`
$3
> "Review this app using RuvNet-KB-First and recommend improvements"
---
Embedded WASM Knowledge Base (NEW in v6.5)
The npm package now includes an embedded WASM-based knowledge base with 17,524 entries. This means you can use the KB without any infrastructure:
javascript
import { loadKB, search, checkForUpdates } from 'ruvnet-kb-first/kb-data/kb-loader.js';// Load KB (once, ~400ms)
await loadKB();
// Search (15-30ms per query)
const results = await search('how to create agents', 5);
// Check if KB needs update
const status = await checkForUpdates();
if (status.needsUpdate) {
console.log('Run: npm update ruvnet-kb-first');
}
`$3
| Feature | WASM KB | PostgreSQL KB |
|---------|---------|---------------|
| Entries | 17,524 | 230,000+ |
| Setup | None | Docker required |
| Search latency | 15-30ms | ~6,700ms |
| Works offline | ✓ | ✗ |
| Auto-updates | npm update | Docker pull |
$3
When the PostgreSQL KB is updated:
bash
npm run kb:export # Re-export WASM with new data
npm test # Verify 43 tests pass
npm version patch # Bump version
npm publish # Publish to npm
`---
Three-Tier Knowledge Base System
RuvNet-KB-First uses a tiered approach to ensure it works for everyone:
Text Version (for AI/accessibility)
┌─────────────────────────────────────────────────────────────────────────────┐
│ KB DISCOVERY FLOW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ START: npx ruvnet-kb-first │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Check: Is ruvector-postgres running on port 5435? │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ├─── YES ──► TIER 1: Full KB (230K+ entries) │
│ │ • All features enabled │
│ │ • Semantic search, citations, gap detection │
│ │ • Score: KB Health + Application Scores │
│ │ │
│ └─── NO ───► Check: Does bundled starter KB exist? │
│ │ │
│ ├─── YES ──► TIER 2: Starter KB (500 entries) │
│ │ • Core patterns included │
│ │ • Limited but functional │
│ │ │
│ └─── NO ───► TIER 3: Structural Only │
│ • Directory/file scoring only │
│ • Offers setup options: │
│ [1] Set up full KB (Docker) │
│ [2] Download starter KB │
│ [3] Continue in limited mode │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
$3
| Tier | Requirements | Entries | Features |
|------|--------------|---------|----------|
| Full | Docker + ruvector-postgres | 230K+ | All features: semantic search, citations, gap detection |
| WASM (NEW) | None (npm package) | 17,524 | Embedded KB, 15-30ms search, offline capable |
| Starter | None (bundled SQLite) | 500 | Core patterns, basic semantic search |
| Structural | None | 0 | Directory scoring, phase tracking, hooks only |
v6.5 Default: The WASM KB is now the automatic fallback when PostgreSQL is unavailable.
---
What You See
When you run
:`
╔════════════════════════════════════════════════════════════════════════╗
║ RuvNet-KB-First Dashboard ║
║ Build intelligent applications on expert knowledge ║
╚════════════════════════════════════════════════════════════════════════╝ KNOWLEDGE BASE
────────────────────────────────────────────────────────────────────
● Status: CONNECTED
Schema: ask_ruvnet
Entries: 230,721
Host: localhost:5435
KB Health Score: █████████████████░░░ 85/100
APPLICATION SCORES
────────────────────────────────────────────────────────────────────
KB Coverage ████████████████████ 100/100 No code yet
Phase Progress ░░░░░░░░░░░░░░░░░░░░ 0/100 0/12 complete
Hooks ████████████████████ 100/100 All installed
KB Gaps ████████████████████ 100/100 No gaps
Documentation ░░░░░░░░░░░░░░░░░░░░ 0/100 Incomplete
Security ████████████████░░░░ 80/100 Issues found
────────────────────────────────────────────────────────────────────
OVERALL SCORE █████████████░░░░░░░ 63/100 C
RECOMMENDATIONS
────────────────────────────────────────────────────────────────────
→ Complete build phases: ruvnet-kb-first phase 0
→ Add documentation: README.md, docs/api.md, docs/architecture.md
→ Fix security issues: ruvnet-kb-first verify --phase=9
COMMANDS
────────────────────────────────────────────────────────────────────
ruvnet-kb-first score --detailed Full score breakdown
ruvnet-kb-first status --detailed Detailed project status
ruvnet-kb-first verify Run verification checks
ruvnet-kb-first phase Execute build phase
Ask Claude: "Review this app using RuvNet-KB-First and recommend improvements"
---
Distribution Model
Text Version (for AI/accessibility)
┌─────────────────────────────────────────────────────────────────────────────┐
│ DISTRIBUTION MODEL │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ CANONICAL USAGE (Always Latest): │
│ ───────────────────────────────── │
│ │
│ npx ruvnet-kb-first@latest │
│ │
│ WHY: │
│ • npx caches locally but checks for updates │
│ • @latest ensures you always get current version │
│ • No global install = no stale versions │
│ • Works identically on all machines │
│ │
│ ───────────────────────────────────────────────────────────────────────── │
│ │
│ MCP CONFIG (Auto-Updating): │
│ ─────────────────────────── │
│ │
│ { │
│ "mcpServers": { │
│ "ruvnet-kb-first": { │
│ "command": "npx", │
│ "args": ["ruvnet-kb-first@latest", "mcp"] │
│ } │
│ } │
│ } │
│ │
│ ───────────────────────────────────────────────────────────────────────── │
│ │
│ AVOID (Causes Version Sprawl): │
│ ───────────────────────────── │
│ │
│ ✗ npm install -g ruvnet-kb-first (hard to update) │
│ ✗ Version pinning in MCP config (prevents updates) │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
$3
| Approach | Problem |
|----------|---------|
|
| Creates stale versions across machines |
| npx ruvnet-kb-first | Always checks for latest, caches locally |---
CLI Commands
| Command | Description |
|---------|-------------|
|
ruvnet-kb-first | Show dashboard (status, scores, recommendations) |
| ruvnet-kb-first init | Initialize RuvNet-KB-First in project |
| ruvnet-kb-first init --kb | Initialize with existing KB |
| ruvnet-kb-first status | Show project status and phase progress |
| ruvnet-kb-first score | Calculate compliance score (0-100) |
| ruvnet-kb-first score --detailed | Show detailed score breakdown |
| ruvnet-kb-first verify | Run verification checks |
| ruvnet-kb-first phase | Run or view specific phase (0-11) |
| ruvnet-kb-first hooks | Manage KB-First enforcement hooks |---
MCP Server Integration
Add to your Claude Code
settings.json:`json
{
"mcpServers": {
"ruvnet-kb-first": {
"command": "npx",
"args": ["ruvnet-kb-first@latest", "mcp"]
}
}
}
`$3
| Tool | Description |
|------|-------------|
|
| Establish baseline score (always first) |
| kb_first_phase | Get phase guidance with baseline reminder |
| kb_first_delta | Compare scores - blocks if regression |
| kb_first_gate | Pass quality gate, proceed to next phase |---
The Score-Driven Workflow
`
┌──────────────────────────────────────────────────────────────┐
│ 1. kb_first_assess → Baseline: 47/100 (Grade: D) │
│ 2. kb_first_phase → Phase 3: KB Population tasks │
│ 3. [Do the work] → Add content, generate embeddings │
│ 4. kb_first_delta → Current: 62/100, Delta: +15 ✓ PASS │
│ 5. kb_first_gate → Gate passed, proceed to Phase 4 │
│ 6. REPEAT → New baseline: 62/100 │
└──────────────────────────────────────────────────────────────┘
Key Rule: Negative delta BLOCKS progress. No shortcuts.
---
The 12-Phase Build Process
KB-First applications are built through a rigorous 12-phase process:
Text Version (for AI/accessibility)
┌─────────────────────────────────────────────────────────────────────────────┐
│ THE 12-PHASE BUILD PROCESS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Phase 0 Phase 1 Phase 1.5 Phase 2 │
│ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
│ │ASSESS │ ────► │STORAGE│ ────► │ HOOKS │ ────► │ KB │ │
│ │ │ │ SETUP │ │ SETUP │ │ BUILD │ │
│ └───────┘ └───────┘ └───────┘ └───────┘ │
│ │
│ Phase 3 Phase 4 Phase 5 Phase 6 │
│ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
│ │PERSIST│ ────► │ VIZ │ ────► │ SDK │ ────► │SCAFF- │ │
│ │ │ │ │ │ LAYER │ │ OLD │ │
│ └───────┘ └───────┘ └───────┘ └───────┘ │
│ │
│ Phase 7 Phase 8 Phase 9 Phase 10 │
│ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
│ │ BUILD │ ────► │VERIFY │ ────► │SECURITY│ ───► │ DOCS │ │
│ │ (ENF) │ │ │ │ │ │ │ │
│ └───────┘ └───────┘ └───────┘ └───────┘ │
│ │
│ Phase 11 │
│ ┌───────┐ │
│ │DEPLOY │ │
│ │ │ │
│ └───────┘ │
│ │
│ ENFORCEMENT: NO SHORTCUTS • NO HARDCODED VALUES • ALL SOURCES TRACED │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
$3
| Phase | Name | Purpose | Quality Gate |
|-------|------|---------|--------------|
| 0 | Assessment | Score existing KB/app | User types "PROCEED" |
| 1 | Storage Setup | Start PostgreSQL + ruvector | Connection verified |
| 1.5 | Hooks Setup | RuVector hooks for KB enforcement | Hook verify passes |
| 2 | KB Creation | Build world-class knowledge base | Score ≥98/100 |
| 3 | Persistence | Store with embeddings | Semantic search works |
| 4 | Visualization | Interactive 3D tree | Navigation works |
| 5 | Integration Layer | TypeScript SDK | All functions compile |
| 6 | Scaffold | Project structure | KB enforcement in place |
| 7 | Build | Implement with KB enforcement | No hardcoded values |
| 8 | Verification | Final check | All 8 checks pass |
| 9 | Security | Security audit & hardening | 0 critical/high issues |
| 10 | Documentation | Complete docs & versioning | All docs complete |
| 11 | Deployment | Production with public access | Go-live verified |
---
User Scenarios
$3
bash
$ npx ruvnet-kb-firstKB: ask_ruvnet (230,721 entries) on localhost:5435
Tier: FULL
All features enabled.
`$3
bash
$ npx ruvnet-kb-firstNo Knowledge Base detected.
Options:
[1] Set up full KB (Docker) - recommended
[2] Download starter KB - quick start
[3] Continue in structural-only mode
Select [1/2/3]:
`$3
yaml
GitHub Actions - structural-only mode
- name: KB-First Verification
run: npx ruvnet-kb-first verify --structural-only
`---
The Five Enforcement Rules
Every RuvNet-KB-First application follows these rules:
$3
> Every response must cite KB sources or explicitly acknowledge a gap.$3
> Every KB result includes a confidence score (0.0-1.0).$3
> Log every query that cannot be answered from the KB.$3
> Every KB node must trace to a named expert source.$3
> No hardcoded domain logic. No fallback values. KB is the source of truth.---
Environment Variables
Configure KB connection via environment:
| Variable | Default | Description |
|----------|---------|-------------|
|
| localhost | Database host |
| KB_PORT | 5435 | Database port |
| KB_PASSWORD | guruKB2025 | Database password |
| KB_MODE | auto | Force mode: full, starter, structural |---
Repository Structure
`
ruvnet-kb-first/
├── bin/
│ └── kb-first.js # CLI entry point
├── src/
│ ├── commands/
│ │ ├── dashboard.js # Default dashboard view
│ │ ├── init.js # Project initialization
│ │ ├── status.js # Status display
│ │ ├── score.js # Scoring engine
│ │ ├── verify.js # Verification checks
│ │ ├── phase.js # Phase execution
│ │ └── hooks.js # Hook management
│ ├── kb-discovery.js # Three-tier KB detection
│ └── mcp-server.js # MCP server for Claude
├── phases/ # Phase-by-phase instructions
├── templates/ # Code templates
├── scripts/ # Verification scripts
├── install/ # Installation helpers
└── assets/ # SVG diagrams
---
Contributing
Contributions are welcome! Please read the Contributing Guide first.
---
License
MIT License - see LICENSE for details.
---
Build intelligence, not just retrieval.