@claude-flow/cli 3.0.2 → 3.1.0-alpha.2

package/.claude/skills/reasoningbank-agentdb/SKILL.md

@@ -0,0 +1,446 @@
+---
+name: "ReasoningBank with AgentDB"
+description: "Implement ReasoningBank adaptive learning with AgentDB's 150x faster vector database. Includes trajectory tracking, verdict judgment, memory distillation, and pattern recognition. Use when building self-learning agents, optimizing decision-making, or implementing experience replay systems."
+---
+
+# ReasoningBank with AgentDB
+
+## What This Skill Does
+
+Provides ReasoningBank adaptive learning patterns using AgentDB's high-performance backend (150x-12,500x faster). Enables agents to learn from experiences, judge outcomes, distill memories, and improve decision-making over time with 100% backward compatibility.
+
+**Performance**: 150x faster pattern retrieval, 500x faster batch operations, <1ms memory access.
+
+## Prerequisites
+
+- Node.js 18+
+- AgentDB v1.0.7+ (via agentic-flow)
+- Understanding of reinforcement learning concepts (optional)
+
+---
+
+## Quick Start with CLI
+
+### Initialize ReasoningBank Database
+
+```bash
+# Initialize AgentDB for ReasoningBank
+npx agentdb@latest init ./.agentdb/reasoningbank.db --dimension 1536
+
+# Start MCP server for Claude Code integration
+npx agentdb@latest mcp
+claude mcp add agentdb npx agentdb@latest mcp
+```
+
+### Migrate from Legacy ReasoningBank
+
+```bash
+# Automatic migration with validation
+npx agentdb@latest migrate --source .swarm/memory.db
+
+# Verify migration
+npx agentdb@latest stats ./.agentdb/reasoningbank.db
+```
+
+---
+
+## Quick Start with API
+
+```typescript
+import { createAgentDBAdapter, computeEmbedding } from 'agentic-flow/reasoningbank';
+
+// Initialize ReasoningBank with AgentDB
+const rb = await createAgentDBAdapter({
+  dbPath: '.agentdb/reasoningbank.db',
+  enableLearning: true,      // Enable learning plugins
+  enableReasoning: true,      // Enable reasoning agents
+  cacheSize: 1000,            // 1000 pattern cache
+});
+
+// Store successful experience
+const query = "How to optimize database queries?";
+const embedding = await computeEmbedding(query);
+
+await rb.insertPattern({
+  id: '',
+  type: 'experience',
+  domain: 'database-optimization',
+  pattern_data: JSON.stringify({
+    embedding,
+    pattern: {
+      query,
+      approach: 'indexing + query optimization',
+      outcome: 'success',
+      metrics: { latency_reduction: 0.85 }
+    }
+  }),
+  confidence: 0.95,
+  usage_count: 1,
+  success_count: 1,
+  created_at: Date.now(),
+  last_used: Date.now(),
+});
+
+// Retrieve similar experiences with reasoning
+const result = await rb.retrieveWithReasoning(embedding, {
+  domain: 'database-optimization',
+  k: 5,
+  useMMR: true,              // Diverse results
+  synthesizeContext: true,    // Rich context synthesis
+});
+
+console.log('Memories:', result.memories);
+console.log('Context:', result.context);
+console.log('Patterns:', result.patterns);
+```
+
+---
+
+## Core ReasoningBank Concepts
+
+### 1. Trajectory Tracking
+
+Track agent execution paths and outcomes:
+
+```typescript
+// Record trajectory (sequence of actions)
+const trajectory = {
+  task: 'optimize-api-endpoint',
+  steps: [
+    { action: 'analyze-bottleneck', result: 'found N+1 query' },
+    { action: 'add-eager-loading', result: 'reduced queries' },
+    { action: 'add-caching', result: 'improved latency' }
+  ],
+  outcome: 'success',
+  metrics: { latency_before: 2500, latency_after: 150 }
+};
+
+const embedding = await computeEmbedding(JSON.stringify(trajectory));
+
+await rb.insertPattern({
+  id: '',
+  type: 'trajectory',
+  domain: 'api-optimization',
+  pattern_data: JSON.stringify({ embedding, pattern: trajectory }),
+  confidence: 0.9,
+  usage_count: 1,
+  success_count: 1,
+  created_at: Date.now(),
+  last_used: Date.now(),
+});
+```
+
+### 2. Verdict Judgment
+
+Judge whether a trajectory was successful:
+
+```typescript
+// Retrieve similar past trajectories
+const similar = await rb.retrieveWithReasoning(queryEmbedding, {
+  domain: 'api-optimization',
+  k: 10,
+});
+
+// Judge based on similarity to successful patterns
+const verdict = similar.memories.filter(m =>
+  m.pattern.outcome === 'success' &&
+  m.similarity > 0.8
+).length > 5 ? 'likely_success' : 'needs_review';
+
+console.log('Verdict:', verdict);
+console.log('Confidence:', similar.memories[0]?.similarity || 0);
+```
+
+### 3. Memory Distillation
+
+Consolidate similar experiences into patterns:
+
+```typescript
+// Get all experiences in domain
+const experiences = await rb.retrieveWithReasoning(embedding, {
+  domain: 'api-optimization',
+  k: 100,
+  optimizeMemory: true,  // Automatic consolidation
+});
+
+// Distill into high-level pattern
+const distilledPattern = {
+  domain: 'api-optimization',
+  pattern: 'For N+1 queries: add eager loading, then cache',
+  success_rate: 0.92,
+  sample_size: experiences.memories.length,
+  confidence: 0.95
+};
+
+await rb.insertPattern({
+  id: '',
+  type: 'distilled-pattern',
+  domain: 'api-optimization',
+  pattern_data: JSON.stringify({
+    embedding: await computeEmbedding(JSON.stringify(distilledPattern)),
+    pattern: distilledPattern
+  }),
+  confidence: 0.95,
+  usage_count: 0,
+  success_count: 0,
+  created_at: Date.now(),
+  last_used: Date.now(),
+});
+```
+
+---
+
+## Integration with Reasoning Agents
+
+AgentDB provides 4 reasoning modules that enhance ReasoningBank:
+
+### 1. PatternMatcher
+
+Find similar successful patterns:
+
+```typescript
+const result = await rb.retrieveWithReasoning(queryEmbedding, {
+  domain: 'problem-solving',
+  k: 10,
+  useMMR: true,  // Maximal Marginal Relevance for diversity
+});
+
+// PatternMatcher returns diverse, relevant memories
+result.memories.forEach(mem => {
+  console.log(`Pattern: ${mem.pattern.approach}`);
+  console.log(`Similarity: ${mem.similarity}`);
+  console.log(`Success Rate: ${mem.success_count / mem.usage_count}`);
+});
+```
+
+### 2. ContextSynthesizer
+
+Generate rich context from multiple memories:
+
+```typescript
+const result = await rb.retrieveWithReasoning(queryEmbedding, {
+  domain: 'code-optimization',
+  synthesizeContext: true,  // Enable context synthesis
+  k: 5,
+});
+
+// ContextSynthesizer creates coherent narrative
+console.log('Synthesized Context:', result.context);
+// "Based on 5 similar optimizations, the most effective approach
+//  involves profiling, identifying bottlenecks, and applying targeted
+//  improvements. Success rate: 87%"
+```
+
+### 3. MemoryOptimizer
+
+Automatically consolidate and prune:
+
+```typescript
+const result = await rb.retrieveWithReasoning(queryEmbedding, {
+  domain: 'testing',
+  optimizeMemory: true,  // Enable automatic optimization
+});
+
+// MemoryOptimizer consolidates similar patterns and prunes low-quality
+console.log('Optimizations:', result.optimizations);
+// { consolidated: 15, pruned: 3, improved_quality: 0.12 }
+```
+
+### 4. ExperienceCurator
+
+Filter by quality and relevance:
+
+```typescript
+const result = await rb.retrieveWithReasoning(queryEmbedding, {
+  domain: 'debugging',
+  k: 20,
+  minConfidence: 0.8,  // Only high-confidence experiences
+});
+
+// ExperienceCurator returns only quality experiences
+result.memories.forEach(mem => {
+  console.log(`Confidence: ${mem.confidence}`);
+  console.log(`Success Rate: ${mem.success_count / mem.usage_count}`);
+});
+```
+
+---
+
+## Legacy API Compatibility
+
+AgentDB maintains 100% backward compatibility with legacy ReasoningBank:
+
+```typescript
+import {
+  retrieveMemories,
+  judgeTrajectory,
+  distillMemories
+} from 'agentic-flow/reasoningbank';
+
+// Legacy API works unchanged (uses AgentDB backend automatically)
+const memories = await retrieveMemories(query, {
+  domain: 'code-generation',
+  agent: 'coder'
+});
+
+const verdict = await judgeTrajectory(trajectory, query);
+
+const newMemories = await distillMemories(
+  trajectory,
+  verdict,
+  query,
+  { domain: 'code-generation' }
+);
+```
+
+---
+
+## Performance Characteristics
+
+- **Pattern Search**: 150x faster (100µs vs 15ms)
+- **Memory Retrieval**: <1ms (with cache)
+- **Batch Insert**: 500x faster (2ms vs 1s for 100 patterns)
+- **Trajectory Judgment**: <5ms (including retrieval + analysis)
+- **Memory Distillation**: <50ms (consolidate 100 patterns)
+
+---
+
+## Advanced Patterns
+
+### Hierarchical Memory
+
+Organize memories by abstraction level:
+
+```typescript
+// Low-level: Specific implementation
+await rb.insertPattern({
+  type: 'concrete',
+  domain: 'debugging/null-pointer',
+  pattern_data: JSON.stringify({
+    embedding,
+    pattern: { bug: 'NPE in UserService.getUser()', fix: 'Add null check' }
+  }),
+  confidence: 0.9,
+  // ...
+});
+
+// Mid-level: Pattern across similar cases
+await rb.insertPattern({
+  type: 'pattern',
+  domain: 'debugging',
+  pattern_data: JSON.stringify({
+    embedding,
+    pattern: { category: 'null-pointer', approach: 'defensive-checks' }
+  }),
+  confidence: 0.85,
+  // ...
+});
+
+// High-level: General principle
+await rb.insertPattern({
+  type: 'principle',
+  domain: 'software-engineering',
+  pattern_data: JSON.stringify({
+    embedding,
+    pattern: { principle: 'fail-fast with clear errors' }
+  }),
+  confidence: 0.95,
+  // ...
+});
+```
+
+### Multi-Domain Learning
+
+Transfer learning across domains:
+
+```typescript
+// Learn from backend optimization
+const backendExperience = await rb.retrieveWithReasoning(embedding, {
+  domain: 'backend-optimization',
+  k: 10,
+});
+
+// Apply to frontend optimization
+const transferredKnowledge = backendExperience.memories.map(mem => ({
+  ...mem,
+  domain: 'frontend-optimization',
+  adapted: true,
+}));
+```
+
+---
+
+## CLI Operations
+
+### Database Management
+
+```bash
+# Export trajectories and patterns
+npx agentdb@latest export ./.agentdb/reasoningbank.db ./backup.json
+
+# Import experiences
+npx agentdb@latest import ./experiences.json
+
+# Get statistics
+npx agentdb@latest stats ./.agentdb/reasoningbank.db
+# Shows: total patterns, domains, confidence distribution
+```
+
+### Migration
+
+```bash
+# Migrate from legacy ReasoningBank
+npx agentdb@latest migrate --source .swarm/memory.db --target .agentdb/reasoningbank.db
+
+# Validate migration
+npx agentdb@latest stats .agentdb/reasoningbank.db
+```
+
+---
+
+## Troubleshooting
+
+### Issue: Migration fails
+```bash
+# Check source database exists
+ls -la .swarm/memory.db
+
+# Run with verbose logging
+DEBUG=agentdb:* npx agentdb@latest migrate --source .swarm/memory.db
+```
+
+### Issue: Low confidence scores
+```typescript
+// Enable context synthesis for better quality
+const result = await rb.retrieveWithReasoning(embedding, {
+  synthesizeContext: true,
+  useMMR: true,
+  k: 10,
+});
+```
+
+### Issue: Memory growing too large
+```typescript
+// Enable automatic optimization
+const result = await rb.retrieveWithReasoning(embedding, {
+  optimizeMemory: true,  // Consolidates similar patterns
+});
+
+// Or manually optimize
+await rb.optimize();
+```
+
+---
+
+## Learn More
+
+- **AgentDB Integration**: node_modules/agentic-flow/docs/AGENTDB_INTEGRATION.md
+- **GitHub**: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentdb
+- **MCP Integration**: `npx agentdb@latest mcp`
+- **Website**: https://agentdb.ruv.io
+
+---
+
+**Category**: Machine Learning / Reinforcement Learning
+**Difficulty**: Intermediate
+**Estimated Time**: 20-30 minutes

package/.claude/skills/reasoningbank-intelligence/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: "ReasoningBank Intelligence"
+description: "Implement adaptive learning with ReasoningBank for pattern recognition, strategy optimization, and continuous improvement. Use when building self-learning agents, optimizing workflows, or implementing meta-cognitive systems."
+---
+
+# ReasoningBank Intelligence
+
+## What This Skill Does
+
+Implements ReasoningBank's adaptive learning system for AI agents to learn from experience, recognize patterns, and optimize strategies over time. Enables meta-cognitive capabilities and continuous improvement.
+
+## Prerequisites
+
+- agentic-flow v1.5.11+
+- AgentDB v1.0.4+ (for persistence)
+- Node.js 18+
+
+## Quick Start
+
+```typescript
+import { ReasoningBank } from 'agentic-flow/reasoningbank';
+
+// Initialize ReasoningBank
+const rb = new ReasoningBank({
+  persist: true,
+  learningRate: 0.1,
+  adapter: 'agentdb' // Use AgentDB for storage
+});
+
+// Record task outcome
+await rb.recordExperience({
+  task: 'code_review',
+  approach: 'static_analysis_first',
+  outcome: {
+    success: true,
+    metrics: {
+      bugs_found: 5,
+      time_taken: 120,
+      false_positives: 1
+    }
+  },
+  context: {
+    language: 'typescript',
+    complexity: 'medium'
+  }
+});
+
+// Get optimal strategy
+const strategy = await rb.recommendStrategy('code_review', {
+  language: 'typescript',
+  complexity: 'high'
+});
+```
+
+## Core Features
+
+### 1. Pattern Recognition
+```typescript
+// Learn patterns from data
+await rb.learnPattern({
+  pattern: 'api_errors_increase_after_deploy',
+  triggers: ['deployment', 'traffic_spike'],
+  actions: ['rollback', 'scale_up'],
+  confidence: 0.85
+});
+
+// Match patterns
+const matches = await rb.matchPatterns(currentSituation);
+```
+
+### 2. Strategy Optimization
+```typescript
+// Compare strategies
+const comparison = await rb.compareStrategies('bug_fixing', [
+  'tdd_approach',
+  'debug_first',
+  'reproduce_then_fix'
+]);
+
+// Get best strategy
+const best = comparison.strategies[0];
+console.log(`Best: ${best.name} (score: ${best.score})`);
+```
+
+### 3. Continuous Learning
+```typescript
+// Enable auto-learning from all tasks
+await rb.enableAutoLearning({
+  threshold: 0.7,        // Only learn from high-confidence outcomes
+  updateFrequency: 100   // Update models every 100 experiences
+});
+```
+
+## Advanced Usage
+
+### Meta-Learning
+```typescript
+// Learn about learning
+await rb.metaLearn({
+  observation: 'parallel_execution_faster_for_independent_tasks',
+  confidence: 0.95,
+  applicability: {
+    task_types: ['batch_processing', 'data_transformation'],
+    conditions: ['tasks_independent', 'io_bound']
+  }
+});
+```
+
+### Transfer Learning
+```typescript
+// Apply knowledge from one domain to another
+await rb.transferKnowledge({
+  from: 'code_review_javascript',
+  to: 'code_review_typescript',
+  similarity: 0.8
+});
+```
+
+### Adaptive Agents
+```typescript
+// Create self-improving agent
+class AdaptiveAgent {
+  async execute(task: Task) {
+    // Get optimal strategy
+    const strategy = await rb.recommendStrategy(task.type, task.context);
+
+    // Execute with strategy
+    const result = await this.executeWithStrategy(task, strategy);
+
+    // Learn from outcome
+    await rb.recordExperience({
+      task: task.type,
+      approach: strategy.name,
+      outcome: result,
+      context: task.context
+    });
+
+    return result;
+  }
+}
+```
+
+## Integration with AgentDB
+
+```typescript
+// Persist ReasoningBank data
+await rb.configure({
+  storage: {
+    type: 'agentdb',
+    options: {
+      database: './reasoning-bank.db',
+      enableVectorSearch: true
+    }
+  }
+});
+
+// Query learned patterns
+const patterns = await rb.query({
+  category: 'optimization',
+  minConfidence: 0.8,
+  timeRange: { last: '30d' }
+});
+```
+
+## Performance Metrics
+
+```typescript
+// Track learning effectiveness
+const metrics = await rb.getMetrics();
+console.log(`
+  Total Experiences: ${metrics.totalExperiences}
+  Patterns Learned: ${metrics.patternsLearned}
+  Strategy Success Rate: ${metrics.strategySuccessRate}
+  Improvement Over Time: ${metrics.improvement}
+`);
+```
+
+## Best Practices
+
+1. **Record consistently**: Log all task outcomes, not just successes
+2. **Provide context**: Rich context improves pattern matching
+3. **Set thresholds**: Filter low-confidence learnings
+4. **Review periodically**: Audit learned patterns for quality
+5. **Use vector search**: Enable semantic pattern matching
+
+## Troubleshooting
+
+### Issue: Poor recommendations
+**Solution**: Ensure sufficient training data (100+ experiences per task type)
+
+### Issue: Slow pattern matching
+**Solution**: Enable vector indexing in AgentDB
+
+### Issue: Memory growing large
+**Solution**: Set TTL for old experiences or enable pruning
+
+## Learn More
+
+- ReasoningBank Guide: agentic-flow/src/reasoningbank/README.md
+- AgentDB Integration: packages/agentdb/docs/reasoningbank.md
+- Pattern Learning: docs/reasoning/patterns.md