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

```bash
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

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

### Retrieval Options

```typescript
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:

```bash
# 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

```typescript
// 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:

```typescript
// 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:

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

## Testing

Run the test suite:

```bash
npm test
```

Run v1.7.1-specific tests:

```bash
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](https://arxiv.org/html/2509.25140v1) (Google DeepMind)

---

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