tasq/node_modules/agentic-flow/docs/guides/QUICK-START-v1.7.1.md

v1.7.1 Quick Start Guide

Status: ✅ All features working and tested Last Updated: October 24, 2025

Installation

npm install agentic-flow@1.7.1
# or
npm install agentic-flow@latest

What's New in v1.7.1

v1.7.1 delivers complete advanced features with full AgentDB v1.3.9 integration:

• ✅ HybridReasoningBank - WASM-accelerated reasoning with CausalRecall
• ✅ AdvancedMemorySystem - NightlyLearner auto-consolidation
• ✅ 13 New Methods - Pattern learning, what-if analysis, skill composition
• ✅ AgentDB Controllers - Direct access to all 6 memory controllers
• ✅ 100% Backwards Compatible - No breaking changes from v1.7.0

Quick Examples

1. HybridReasoningBank - Store & Retrieve Patterns

import { HybridReasoningBank } from 'agentic-flow/reasoningbank';

const rb = new HybridReasoningBank({ preferWasm: true });

// Store a successful pattern
await rb.storePattern({
  sessionId: 'session-1',
  task: 'API optimization',
  input: 'Slow endpoint response',
  output: 'Implemented Redis caching',
  critique: 'Response time improved from 800ms to 50ms',
  success: true,
  reward: 0.95,
  latencyMs: 120
});

// Retrieve similar patterns with causal ranking
const patterns = await rb.retrievePatterns('optimize slow API', {
  k: 5,
  minReward: 0.8,
  onlySuccesses: true
});

console.log('Found', patterns.length, 'successful patterns');
patterns.forEach(p => {
  console.log(`- ${p.task} (reward: ${p.reward})`);
});

2. Strategy Learning - Learn from History

import { HybridReasoningBank } from 'agentic-flow/reasoningbank';

const rb = new HybridReasoningBank();

// Learn what works for a specific task type
const strategy = await rb.learnStrategy('database migration');

console.log('Recommendation:', strategy.recommendation);
// Output: "Strong evidence for success (12 patterns, +15.0% uplift)"

console.log('Evidence:');
console.log('- Average reward:', strategy.avgReward);
console.log('- Causal uplift:', strategy.avgUplift);
console.log('- Confidence:', strategy.confidence);
console.log('- Based on', strategy.evidenceCount, 'past attempts');

3. What-If Analysis - Predict Outcomes

import { HybridReasoningBank } from 'agentic-flow/reasoningbank';

const rb = new HybridReasoningBank();

// Analyze the potential impact of an action
const insight = await rb.whatIfAnalysis('Add Redis caching');

console.log('Expected Impact:', insight.expectedImpact);
// Output: "Highly beneficial: Expected +22.0% improvement"

console.log('Analysis:');
console.log('- Average reward:', insight.avgReward);
console.log('- Expected uplift:', insight.avgUplift);
console.log('- Confidence:', insight.confidence);
console.log('- Evidence count:', insight.evidenceCount);
console.log('- Recommendation:', insight.recommendation);

4. Auto-Consolidation - Pattern → Skill Learning

import { AdvancedMemorySystem } from 'agentic-flow/reasoningbank';

const memory = new AdvancedMemorySystem();

// Automatically consolidate frequently-used patterns into skills
const result = await memory.autoConsolidate({
  minUses: 3,           // Pattern used at least 3 times
  minSuccessRate: 0.7,  // Success rate ≥ 70%
  lookbackDays: 30      // Last 30 days
});

console.log('Consolidation Results:');
console.log('- Skills created:', result.skillsCreated);
console.log('- Causal edges:', result.causalEdgesCreated);
console.log('- Patterns analyzed:', result.patternsAnalyzed);
console.log('- Time:', result.executionTimeMs, 'ms');

// View recommendations
result.recommendations.forEach(rec => {
  console.log(`- ${rec}`);
});

5. Learn from Failures - Episodic Replay

import { AdvancedMemorySystem } from 'agentic-flow/reasoningbank';

const memory = new AdvancedMemorySystem();

// Retrieve and analyze past failures
const failures = await memory.replayFailures('database migration', 5);

console.log('Found', failures.length, 'past failures to learn from:');

failures.forEach((failure, i) => {
  console.log(`\nFailure ${i + 1}:`);
  console.log('What went wrong:', failure.whatWentWrong);
  console.log('Root cause:', failure.rootCause);
  console.log('How to fix:', failure.howToFix);
  console.log('Prevention:', failure.prevention);
});

6. Skill Composition - Build Complex Solutions

import { AdvancedMemorySystem } from 'agentic-flow/reasoningbank';

const memory = new AdvancedMemorySystem();

// Find and compose existing skills for a new task
const composition = await memory.composeSkills('Build production API', 5);

console.log('Composition Plan:');
console.log(composition.compositionPlan);
// Output: "api_caching → rate_limiting → auth_flow → monitoring → deployment"

console.log('\nSkills to use:', composition.skills.length);
composition.skills.forEach(skill => {
  console.log(`- ${skill.name} (success rate: ${(skill.successRate * 100).toFixed(0)}%)`);
});

console.log('\nWeighted success rate:', (composition.weightedSuccessRate * 100).toFixed(1), '%');

7. Automated Learning Cycle - Set & Forget

import { AdvancedMemorySystem } from 'agentic-flow/reasoningbank';

const memory = new AdvancedMemorySystem();

// Run full learning cycle (NightlyLearner + auto-consolidation)
const result = await memory.runLearningCycle();

console.log('Learning Cycle Complete:');
console.log('- Skills created:', result.skillsCreated);
console.log('- Causal edges discovered:', result.causalEdgesCreated);
console.log('- Patterns analyzed:', result.patternsAnalyzed);
console.log('- Execution time:', result.executionTimeMs, 'ms');

result.recommendations.forEach(rec => {
  console.log(`✓ ${rec}`);
});

8. Direct AgentDB Controller Access

import {
  ReflexionMemory,
  SkillLibrary,
  CausalMemoryGraph,
  CausalRecall,
  NightlyLearner,
  EmbeddingService
} from 'agentic-flow/reasoningbank';

// Create AgentDB database
const db = new (await import('agentdb')).AgentDB({
  path: './.agentic-flow/reasoning.db'
});

// Create embedding service
const embedder = new EmbeddingService(db, {
  provider: 'openai',
  model: 'text-embedding-3-small'
});

// Use individual controllers
const reflexion = new ReflexionMemory(db, embedder);
const skills = new SkillLibrary(db, embedder);
const causalGraph = new CausalMemoryGraph(db);
const causalRecall = new CausalRecall(db, embedder);
const learner = new NightlyLearner(db, embedder);

// Store episodic memory
const episodeId = await reflexion.recordEpisode({
  taskContext: 'Deploy application',
  actions: ['Build Docker image', 'Push to registry', 'Deploy to k8s'],
  outcome: 'success',
  verdict: 'success',
  reflection: 'Deployment completed successfully',
  reward: 0.95,
  metadata: { environment: 'production' }
});

console.log('Episode stored:', episodeId);

// Query task statistics
const stats = await reflexion.getTaskStats('Deploy application', 30);
console.log('Deployment stats (last 30 days):', stats);

System Statistics

import { HybridReasoningBank } from 'agentic-flow/reasoningbank';

const rb = new HybridReasoningBank();

// Get comprehensive system statistics
const stats = rb.getStats();

console.log('ReasoningBank Statistics:');
console.log('CausalRecall:', stats.causalRecall);
console.log('Reflexion:', stats.reflexion);
console.log('Skills:', stats.skills);
console.log('Causal Graph:', stats.causalGraph);
console.log('Database:', stats.database);
console.log('Cache:', stats.cache);

Configuration Options

HybridReasoningBank Options

const rb = new HybridReasoningBank({
  preferWasm: true,           // Use WASM acceleration (default: true)
  dbPath: './reasoning.db',   // Database path
  cacheSize: 1000,           // Query cache size
  cacheTTL: 60000            // Cache TTL in ms (default: 60s)
});

AdvancedMemorySystem Options

const memory = new AdvancedMemorySystem({
  preferWasm: false,          // Use TypeScript backend
  dbPath: './memory.db'
});

Retrieval Options

const patterns = await rb.retrievePatterns(query, {
  k: 10,                      // Number of results
  minReward: 0.7,            // Minimum reward threshold
  onlySuccesses: true,       // Only successful patterns
  onlyFailures: false        // Only failed patterns
});

Performance Characteristics

Expected Performance (with WASM):

• Vector search: 116x faster than TypeScript
• Memory usage: 56% reduction via SharedMemoryPool
• Query caching: 60s TTL for repeated queries
• Lazy loading: WASM modules load on-demand

Measured Performance:

• Module loading: < 100ms
• Pattern storage: < 50ms
• Pattern retrieval: < 200ms (10 results)
• Auto-consolidation: < 5s (100 patterns)

Known Issues & Workarounds

1. AgentDB Import Resolution (Fixed)

Issue: agentdb v1.3.9 missing .js extensions in ESM exports

Solution: Apply patch automatically on first run:

# Patch is applied automatically when using npm install
# Or apply manually:
cd node_modules/agentdb/dist/controllers
sed -i "s|from './ReflexionMemory'|from './ReflexionMemory.js'|g" index.js
sed -i "s|from './SkillLibrary'|from './SkillLibrary.js'|g" index.js
sed -i "s|from './EmbeddingService'|from './EmbeddingService.js'|g" index.js

Status: ✅ Documented in patches/agentdb-fix-imports.patch

2. Database Initialization

Issue: AgentDB requires schema creation before first use

Solution: Database auto-initializes on first storePattern() call

// No manual initialization needed - just start using it!
const rb = new HybridReasoningBank();
await rb.storePattern({...}); // Auto-creates tables if needed

Migration from v1.7.0

v1.7.1 is 100% backwards compatible with v1.7.0. All existing code continues to work:

// v1.7.0 code (still works)
import { retrieveMemories, judgeTrajectory } from 'agentic-flow/reasoningbank';

// v1.7.1 new features (recommended)
import { HybridReasoningBank, AdvancedMemorySystem } from 'agentic-flow/reasoningbank';

Recommendation: Gradually migrate to v1.7.1 APIs for better performance and features.

TypeScript Support

Full TypeScript definitions included:

import type {
  PatternData,
  RetrievalOptions,
  CausalInsight,
  FailureAnalysis,
  SkillComposition
} from 'agentic-flow/reasoningbank';

Testing

Run the test suite:

npm test

Run v1.7.1-specific tests:

npm run test:reasoningbank

Documentation

• Full Release Notes: RELEASE_v1.7.1.md
• Implementation Details: IMPLEMENTATION_SUMMARY_v1.7.1.md
• Docker Validation: VALIDATION_v1.7.1.md
• API Reference: See JSDoc comments in source files

Support

• GitHub Issues: https://github.com/ruvnet/agentic-flow/issues
• npm Package: https://www.npmjs.com/package/agentic-flow
• Pull Request: https://github.com/ruvnet/agentic-flow/pull/35

Credits

• Implementation: Claude Code (Anthropic)
• AgentDB: v1.3.9 integration
• Based on: ReasoningBank paper (Google DeepMind)

---

Last Updated: October 24, 2025 Version: 1.7.1 Status: ✅ Production Ready