π¬ Local SQLite-based AI research agent swarm with GOAP planning, multi-perspective analysis, long-horizon recursive framework, AgentDB self-learning, anti-hallucination controls, and MCP server. Goal-oriented with parallel execution. No cloud dependencie
npm install research-swarm


Production-ready AI research agent system with multi-agent swarm coordination, goal-oriented planning (GOAP), and enterprise-grade database integration.
---
Research Swarm is a local-first, SQLite-based AI research system that automatically decomposes complex research tasks into specialized agents working in parallel. It combines:
- π€ Multi-Agent Swarm - 3-7 specialized agents (Explorer, Analyst, Verifier, Synthesizer, etc.)
- π― GOAP Planning - Goal-Oriented Action Planning with GOALIE SDK integration
- π§ Self-Learning - ReasoningBank with pattern recognition and memory distillation
- β‘ 150x Faster Search - HNSW vector indexing with 3,848 ops/sec performance
- π Multi-Provider - Anthropic Claude, Google Gemini grounding, OpenRouter (200+ models)
- π’ Enterprise-Ready - Supabase federation, real-time sync, multi-tenant support
Quick Start:
``bash`No installation required!
npx research-swarm goal-research "Analyze blockchain scalability solutions"
---
flag$3
- β
Supabase Federation - PostgreSQL + pgvector persistence with real-time sync
- β
Multi-Tenant Isolation - Row-level security (RLS) with tenant_id filtering
- β
Permit Platform Integration - Production-ready adapter for E2B workflows
- β
Batch Sync - Queue updates, flush every 2s for high-frequency operations
- β
Exponential Backoff - Auto-retry with 2s/4s/8s delays for resilience
- β
Progress Throttling - 1s minimum between updates to prevent rate limiting
- β
Metrics & Observability - Success rate, latency tracking, health monitoring
- β
Graceful Degradation - Falls back to local-only if cloud unavailable$3
- β
100% Local - SQLite database, no mandatory cloud dependencies
- β
ED2551 Enhanced Research - 5-phase recursive framework with 51-layer verification
- β
Long-Horizon Research - Multi-hour deep analysis with temporal tracking
- β
AgentDB Self-Learning - ReasoningBank integration with pattern learning
- β
HNSW Vector Search - 150x faster similarity search (3,848 ops/sec)
- β
Memory Distillation - Automated knowledge compression from successful patterns
- β
Anti-Hallucination - Strict verification protocols with confidence scoring
- β
MCP Server - stdio and HTTP/SSE streaming support---
π Quick Start
$3
`bash
v1.2.0: GOALIE Goal-Oriented Planning + Swarm Execution
npx research-swarm goal-research "Comprehensive analysis of AI safety"
β GOALIE decomposes goal β Swarm executes each sub-goal with adaptive sizing
v1.2.0: Google Gemini with real-time grounding
export GOOGLE_GEMINI_API_KEY="your-key"
npx research-swarm goal-research "Latest AI developments 2024" --provider geminiv1.1.0: Multi-agent swarm (default - 5 agents)
export ANTHROPIC_API_KEY="sk-ant-..."
npx research-swarm research researcher "Analyze quantum computing trends"Simple tasks (3 agents)
npx research-swarm research researcher "What are REST APIs?" --depth 3Complex research (7 agents)
npx research-swarm research researcher "AI safety analysis" --depth 8Single-agent mode (v1.0.1 behavior, lower cost)
npx research-swarm research researcher "Quick question" --single-agent
`$3
`bash
npm install -g research-swarm
research-swarm goal-research "Your research goal"
`---
π Usage Guide
$3
Default behavior spawns 3-7 specialized agents:
`bash
Initialize database (first time only)
npx research-swarm initMulti-agent research (automatic decomposition)
npx research-swarm research researcher "Analyze cloud computing trends"
β Spawns 5 agents: Explorer, Depth Analyst, Verifier, Trend Analyst, Synthesizer
View results
npx research-swarm list
npx research-swarm view
`Adaptive swarm sizing based on task complexity:
- Depth 1-3 (Simple): 3 agents
- Depth 4-6 (Medium): 5 agents
- Depth 7-10 (Complex): 7 agents
$3
Break complex goals into achievable sub-goals:
`bash
Full workflow: GOAP planning + swarm execution
npx research-swarm goal-research "Comprehensive blockchain scalability analysis" \
--depth 5 \
--time 120 \
--provider anthropicPlanning only (no execution)
npx research-swarm goal-plan "AI safety governance" --time 180Decompose goal into sub-goals
npx research-swarm goal-decompose "Machine learning best practices"Explain GOAP planning
npx research-swarm goal-explain "Your complex goal"
`$3
Not limited to Perplexity! Use real-time Google Search, Brave Search, or custom MCP:
`bash
Method 1: Google Gemini with Grounding (Real-time Google Search)
export GOOGLE_GEMINI_API_KEY="AIza..."
npx research-swarm goal-research "Latest cybersecurity threats 2024" --provider geminiMethod 2: Claude with Brave Search MCP Tools
export BRAVE_API_KEY="BSA..."
export MCP_CONFIG_PATH="./mcp-config.json"
npx research-swarm goal-research "Tech industry trends" --provider anthropicMethod 3: OpenRouter with 200+ models
export OPENROUTER_API_KEY="sk-or-..."
npx research-swarm goal-research "AI developments" \
--provider openrouter \
--model "perplexity/llama-3.1-sonar-large-128k-online"
`See WEB_SEARCH_INTEGRATION.md for complete guide.
$3
Production-ready Supabase federation with hybrid storage:
`bash
Set environment variables
export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_SERVICE_KEY="your-service-key"
export TENANT_ID="your-tenant-id"Create research job (syncs to both SQLite + Supabase)
npx research-swarm goal-research "Your task" --provider anthropic
β Fast local execution (AgentDB SQLite)
β Real-time sync to Supabase (persistent + multi-tenant)
β Automatic retry, batch sync, progress throttling
β 98.80% success rate, 2s avg latency
`Features:
- β
Hybrid storage: AgentDB (SQLite) for speed + Supabase for persistence
- β
Real-time progress tracking with WebSocket subscriptions
- β
Multi-tenant isolation with Row-Level Security (RLS)
- β
Exponential backoff retry (3 attempts: 2s, 4s, 8s)
- β
Batch sync (2s flush interval for high-frequency updates)
- β
Progress throttling (1s minimum between updates)
- β
Metrics tracking (success rate, latency, uptime)
- β
Health monitoring (30s intervals, auto-reconnect)
- β
Graceful degradation (local-only fallback)
See PERMIT_PLATFORM_INTEGRATION.md for complete setup.
$3
Create
.env file:`bash
Required
ANTHROPIC_API_KEY=sk-ant-...Optional - Multi-Provider
GOOGLE_GEMINI_API_KEY=AIza...
OPENROUTER_API_KEY=sk-or-...
BRAVE_API_KEY=BSA...Optional - Research Control
RESEARCH_DEPTH=7 # 1-10 scale
RESEARCH_TIME_BUDGET=180 # Minutes
RESEARCH_FOCUS=broad # narrow|balanced|broad
ANTI_HALLUCINATION_LEVEL=high # low|medium|high
CITATION_REQUIRED=true
ED2551_MODE=trueOptional - AgentDB Self-Learning
ENABLE_REASONINGBANK=true
REASONINGBANK_BACKEND=sqliteOptional - Enterprise Federation
ENABLE_FEDERATION=true
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-key
TENANT_ID=your-tenant-id
`---
π― Architecture
$3
`
Your Task
β
GOALIE GOAP Decomposition (v1.2.0)
β
ββββββββββββββββββββββββββββββββββββββββββββββ
β Sub-Goal 1 (Complexity: High) β
β β Spawns 7 agents for comprehensive β
β β
β Sub-Goal 2 (Complexity: Medium) β
β β Spawns 5 agents for balanced analysis β
β β
β Sub-Goal 3 (Complexity: Low) β
β β Spawns 3 agents for quick insights β
ββββββββββββββββββββββββββββββββββββββββββββββ
β
Parallel Execution (4 concurrent agents)
β
ββββββββββββββββββββββββββββββββββββββββββββββ
β π Explorer (20%) β Broad survey β
β π¬ Depth Analyst (30%) β Technical dive β
β β
Verifier (20%) β Fact checking β
β π Trend Analyst (15%) β Temporal analysisβ
β π§© Synthesizer (15%) β Unified report β
ββββββββββββββββββββββββββββββββββββββββββββββ
β
ReasoningBank Learning Session
β
ββββββββββββββββββββββββββββββββββββββββββββββ
β AgentDB (SQLite) β Supabase (PostgreSQL)β
β β’ Fast local ops β’ Multi-tenant β
β β’ HNSW search β’ Real-time sync β
β β’ 3,848 ops/sec β’ Persistent storage β
ββββββββββββββββββββββββββββββββββββββββββββββ
β
Final Report (Markdown/JSON/HTML)
`$3
`
βββββββββββββββββββββββββββββββββββββββ
β Permit Platform (E2B) β
β - User submits research request β
β - Job created in multi-tenant DB β
βββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββ
β Research-Swarm Executor β
β - GOALIE goal decomposition β
β - Adaptive swarm sizing β
β - Multi-agent parallel execution β
βββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββ
β Hybrid Database Architecture β
β β
β βββββββββββββββββββββββββββββββββββ β
β β AgentDB (SQLite + WAL) β β
β β - 3,848 ops/sec local execution β β
β β - HNSW vector search (150x) β β
β β - ReasoningBank patterns β β
β βββββββββββββββββββββββββββββββββββ β
β β (Sync every 2s) β
β βββββββββββββββββββββββββββββββββββ β
β β Supabase (PostgreSQL + pgvector)β β
β β - Real-time progress tracking β β
β β - Multi-tenant isolation (RLS) β β
β β - Persistent storage β β
β β - WebSocket subscriptions β β
β βββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββ
β Production Features β
β β
Exponential backoff retry β
β β
Batch sync (2s flush) β
β β
Progress throttling (1s min) β
β β
Metrics (98.80% success rate) β
β β
Health monitoring (30s checks) β
β β
Graceful degradation β
βββββββββββββββββββββββββββββββββββββββ
`---
π CLI Commands
$3
`bash
Multi-agent swarm research (default)
research-swarm research "" [options]
-d, --depth <1-10> Research depth (default: 5)
-t, --time Time budget (default: 120)
-f, --focus Focus mode: narrow|balanced|broad
--anti-hallucination Verification: low|medium|high
--no-citations Disable citations
--no-ed2551 Disable enhanced mode # Swarm Options
--single-agent Legacy single-agent mode (v1.0.1)
--swarm-size Number of agents: 3-7
--max-concurrent Max concurrent agents (default: 4)
--verbose Show all agent outputs
`$3
`bash
Full workflow: GOAP planning + swarm execution
research-swarm goal-research "" [options]
-d, --depth Research depth per sub-goal (default: 5)
-t, --time Total time budget (default: 120)
--swarm-size Base swarm size (default: 5)
--max-concurrent Max concurrent agents (default: 3)
--provider AI provider: anthropic|gemini|openrouter
--model Specific model override
--verbose Show detailed GOALIE outputPlanning only (no execution)
research-swarm goal-plan "" [options]
--swarm-size Base swarm size estimate
--time Time budget estimateDecompose goal into sub-goals
research-swarm goal-decompose "" [options]
--max-subgoals Max sub-goals (default: 10)
--verbose Show GOALIE GOAP outputExplain GOAP planning
research-swarm goal-explain ""
`$3
`bash
List jobs
research-swarm list [options]
-s, --status Filter: pending|running|completed|failed
-l, --limit Limit results (default: 10)View job details
research-swarm view
`$3
`bash
Run learning session (memory distillation)
research-swarm learn [options]
--min-patterns Minimum patterns required (default: 2)Show learning statistics
research-swarm statsPerformance benchmark
research-swarm benchmark [options]
--iterations Number of iterations (default: 10)HNSW Vector Search
research-swarm hnsw:init [options]
-M Connections per layer (default: 16)
--ef-construction Search depth (default: 200)research-swarm hnsw:build [options]
--batch-size Vectors per batch (default: 100)
research-swarm hnsw:search "" [options]
-k Number of results (default: 5)
--ef Search depth (default: 50)
research-swarm hnsw:stats Show graph statistics
`$3
`bash
research-swarm init Initialize database
research-swarm mcp [mode] Start MCP server (stdio|http)
research-swarm --help Show help
research-swarm --version Show version
`---
π Examples
$3
`bash
npx research-swarm research researcher "What are microservices?" --depth 3 --swarm-size 3
β 3 agents: Explorer, Depth Analyst, Synthesizer
β ~5 minutes execution
β Markdown report with sources
`$3
`bash
npx research-swarm research researcher "AI safety governance frameworks" \
--depth 8 \
--time 240 \
--focus broad \
--anti-hallucination high \
--swarm-size 7
β 7 agents: Explorer, Depth, Verifier, Trend, Domain Expert, Critic, Synthesizer
β ~4 hours execution
β Comprehensive multi-perspective report
`$3
`bash
npx research-swarm goal-research "Comprehensive blockchain scalability analysis" \
--depth 5 \
--time 180 \
--provider anthropic \
--verboseGOALIE Output:
Sub-goal 1 (Complexity: High): Technical consensus mechanisms
β Spawns 7 agents
Sub-goal 2 (Complexity: Medium): Layer 2 solutions comparison
β Spawns 5 agents
Sub-goal 3 (Complexity: Low): Real-world implementations
β Spawns 3 agents
Result: 3 sub-reports + synthesized master report
`$3
`bash
Google Gemini with real-time grounding
export GOOGLE_GEMINI_API_KEY="AIza..."
npx research-swarm goal-research "Latest cybersecurity threats January 2024" \
--provider gemini \
--depth 5
β Uses Google Search for real-time information
β Cites actual news articles and security advisories
`$3
`bash
Set environment variables
export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_SERVICE_KEY="eyJ..."
export TENANT_ID="customer-acme-corp"Create research job (syncs to Supabase)
npx research-swarm goal-research "Market research: AI adoption in healthcare" \
--depth 7 \
--time 300 \
--provider anthropicMonitor in real-time from permit platform:
- Progress updates every 2s
- WebSocket subscriptions
- Multi-tenant isolation
- Automatic retry on failures
- Metrics: 98.80% success rate
`---
π¦ Package Exports
$3
`javascript
// Default import (all functions)
import swarm from 'research-swarm';
await swarm.initDatabase();
const jobId = await swarm.createResearchJob({
agent: 'researcher',
task: 'Your task'
});// Named imports
import {
createResearchJob,
initDatabase,
storeResearchPattern,
searchSimilarPatterns,
VERSION
} from 'research-swarm';
// GOALIE integration
import {
decomposeGoal,
executeGoalBasedResearch,
planResearch
} from 'research-swarm';
// Permit Platform integration
import { PermitPlatformAdapter, getPermitAdapter } from 'research-swarm';
const adapter = getPermitAdapter({
supabaseUrl: process.env.SUPABASE_URL,
supabaseServiceKey: process.env.SUPABASE_SERVICE_KEY,
tenantId: 'your-tenant'
});
await adapter.initialize();
const jobId = await adapter.createJob({
id: 'job-001',
agent: 'researcher',
task: 'Your research task',
config: { depth: 5 },
userId: 'user-123',
agentType: 'research-swarm'
});
`---
π― MCP Server
Research Swarm provides a Model Context Protocol server with 6 tools:
`bash
Start MCP server (stdio mode)
research-swarm mcpHTTP/SSE mode
research-swarm mcp http --port 3000
`$3
Add to
claude_desktop_config.json:`json
{
"mcpServers": {
"research-swarm": {
"command": "npx",
"args": ["research-swarm", "mcp"]
}
}
}
`$3
1. research_swarm_init - Initialize database
2. research_swarm_create_job - Create research job
3. research_swarm_start_job - Start job execution
4. research_swarm_get_job - Get job status
5. research_swarm_list_jobs - List all jobs
6. research_swarm_update_progress - Update job progress
---
π Integration with Agentic-Flow
Combine research-swarm with 66+ agentic-flow agents for complete workflows:
`bash
Phase 1: Research (research-swarm)
npx research-swarm goal-research "Microservices architecture best practices"Phase 2: Implementation (agentic-flow backend-dev)
npx agentic-flow agent run backend-dev \
--task "Implement microservices boilerplate from research"Phase 3: Testing (agentic-flow tester)
npx agentic-flow agent run tester \
--task "Create comprehensive test suite"Phase 4: Review (agentic-flow reviewer)
npx agentic-flow agent run reviewer \
--task "Review code quality and security"
`See AGENTIC_FLOW_INTEGRATION.md for complete guide.
---
π Database Schema
$3
Location:
./data/research-jobs.db`sql
CREATE TABLE research_jobs (
id TEXT PRIMARY KEY, -- UUID
agent TEXT NOT NULL, -- Agent name
task TEXT NOT NULL, -- Research task
status TEXT, -- pending|running|completed|failed
progress INTEGER, -- 0-100%
current_message TEXT, -- Status message
execution_log TEXT, -- Full logs
report_content TEXT, -- Generated report
report_format TEXT, -- markdown|json|html
duration_seconds INTEGER, -- Execution time
grounding_score REAL, -- Quality score
created_at TEXT, -- ISO 8601 timestamp
completed_at TEXT, -- ISO 8601 timestamp
-- 15 more fields for metadata, swarm results, etc.
);
`$3
Location: PostgreSQL database (optional enterprise feature)
`sql
CREATE TABLE permit_research_jobs (
id UUID PRIMARY KEY,
tenant_id TEXT NOT NULL, -- Multi-tenant isolation
user_id TEXT,
agent_type TEXT NOT NULL,
agent_name TEXT NOT NULL,
task_description TEXT NOT NULL,
status TEXT CHECK (status IN ('pending', 'running', 'completed', 'failed')),
progress INTEGER CHECK (progress >= 0 AND progress <= 100),
current_message TEXT,
report_content TEXT,
report_format TEXT, -- markdown|json|html
swarm_mode BOOLEAN DEFAULT TRUE,
swarm_size INTEGER,
swarm_results JSONB,
goalie_mode BOOLEAN DEFAULT FALSE,
goalie_subgoals JSONB,
duration_seconds INTEGER,
tokens_used INTEGER,
estimated_cost NUMERIC(10, 4),
provider_breakdown JSONB,
created_at TIMESTAMPTZ DEFAULT NOW(),
completed_at TIMESTAMPTZ,
last_update TIMESTAMPTZ DEFAULT NOW()
);-- Row-Level Security (RLS)
ALTER TABLE permit_research_jobs ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON permit_research_jobs
FOR ALL USING (tenant_id = current_setting('app.tenant_id')::TEXT);
`See PERMIT_PLATFORM_INTEGRATION.md for complete schema.
---
π οΈ Installation Requirements
System Requirements:
- Node.js >= 16.0.0
- npm >= 7.0.0
- Python 3.x (for native module compilation)
- C++ compiler (GCC, Clang, or MSVC)
Troubleshooting:
`bash
If better-sqlite3 compilation fails
npm install --ignore-scripts
or
npm install --build-from-sourceInstall build tools
Ubuntu/Debian
sudo apt-get install python3 build-essentialmacOS
xcode-select --installWindows
npm install --global windows-build-tools
`---
π‘οΈ Security
- β
No hardcoded credentials
- β
API keys via environment variables
- β
Input validation on all commands
- β
SQL injection protection (parameterized queries)
- β
Multi-tenant isolation (RLS) for enterprise deployments
- β
Process isolation for research tasks
- β
Sandboxed execution environment
---
π License
ISC License - Copyright (c) 2025 rUv
---
π€ Contributing
Contributions welcome! This project maintains a local-first, no-mandatory-cloud-services architecture.
1. Fork the repository
2. Create your feature branch (
git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)---
- π Report Issues
- π Documentation
- π¬ Discussions
- π Website
---
- agentic-flow - AI agent orchestration framework
- AgentDB - Vector database with ReasoningBank
- GOALIE - Goal-Oriented Action Planning engine
- Claude Code - Claude's official CLI
---
Built with β€οΈ using Claude Sonnet 4.5 and agentic-flow