# agentic-flow v1.7.1 Release Notes

**Release Date**: October 24, 2025
**Status**: Full Implementation with Advanced Features

## 🎯 Overview

Version 1.7.1 delivers the **complete implementation** of advanced ReasoningBank features that were simplified in v1.7.0. This release includes full CausalRecall integration, NightlyLearner auto-consolidation, and comprehensive causal reasoning capabilities.

## 🚀 New Features

### 1. **Full CausalRecall Integration**

HybridReasoningBank now uses utility-based reranking for intelligent pattern retrieval:

```typescript
// Utility formula: U = α·similarity + β·uplift − γ·latency
// Default weights: α=0.6, β=0.3, γ=0.1

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

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

// Store patterns with causal tracking
await rb.storePattern({
  sessionId: 'session-1',
  task: 'API optimization',
  input: 'Slow endpoint',
  output: 'Cached with Redis',
  critique: 'Significant performance improvement',
  success: true,
  reward: 0.95,
  latencyMs: 120,
  tokensUsed: 1500
});

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

// Each pattern includes:
// - similarity: Vector similarity score
// - uplift: Causal improvement measure
// - utilityScore: Combined ranking metric
```

### 2. **Causal Memory Graph**

Automatic tracking of causal relationships between actions and outcomes:

```typescript
// Causal edges are automatically recorded for successful patterns
// Tracks: p(y|do(x)) intervention-based causality

await rb.storePattern({
  sessionId: 'session-2',
  task: 'Add caching',
  success: true,
  reward: 0.92
  // ➜ Creates causal edge linking action → outcome
});
```

### 3. **Strategy Learning with Task Statistics**

Learn optimal strategies from historical patterns with statistical confidence:

```typescript
const strategy = await rb.learnStrategy('Error handling');

console.log(strategy);
// {
//   patterns: [...],  // Successful historical patterns
//   causality: {
//     action: 'Error handling',
//     avgReward: 0.88,
//     avgUplift: 0.15,      // +15% improvement trend
//     confidence: 0.82,      // High statistical confidence
//     evidenceCount: 12,     // 12 historical attempts
//     recommendation: 'DO_IT'
//   },
//   confidence: 0.85,
//   recommendation: 'Strong evidence for success (12 patterns, +15.0% uplift)'
// }
```

### 4. **Auto-Consolidation with NightlyLearner**

Automatic discovery of causal patterns and skill consolidation:

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

const memory = new AdvancedMemorySystem();

// Run automated learning cycle
const result = await memory.autoConsolidate({
  minUses: 3,
  minSuccessRate: 0.7,
  lookbackDays: 30
});

console.log(result);
// {
//   skillsCreated: 5,
//   causalEdgesCreated: 12,
//   patternsAnalyzed: 45,
//   executionTimeMs: 1250,
//   recommendations: [
//     'High-performing pattern detected: API caching (92% success rate)',
//     'Causal relationship confirmed: caching → latency reduction',
//     '5 new skills consolidated from frequent patterns'
//   ]
// }
```

### 5. **Episodic Replay - Learning from Failures**

Analyze past failures to generate actionable recommendations:

```typescript
const failures = await memory.replayFailures('database migration', 5);

failures.forEach(failure => {
  console.log('Critique:', failure.critique);
  console.log('What went wrong:', failure.whatWentWrong);
  // ['Low success rate observed', 'High latency detected']

  console.log('How to fix:', failure.howToFix);
  // ['Review similar successful patterns', 'Optimize for lower latency']

  console.log('Similar failures:', failure.similarFailures);
  // 3
});
```

### 6. **What-If Causal Analysis**

Predict outcomes before taking actions:

```typescript
const analysis = await memory.whatIfAnalysis('Enable caching');

console.log(analysis);
// {
//   action: 'Enable caching',
//   avgReward: 0.93,
//   avgUplift: 0.22,             // +22% expected improvement
//   confidence: 0.88,
//   evidenceCount: 8,
//   recommendation: 'DO_IT',
//   expectedImpact: 'Highly beneficial: Expected +22.0% improvement'
// }
```

### 7. **Skill Composition**

Automatically compose multiple learned skills for complex tasks:

```typescript
const composition = await memory.composeSkills('Build scalable API', 5);

console.log(composition);
// {
//   availableSkills: [
//     { name: 'api_caching', successRate: 0.95, uses: 12 },
//     { name: 'rate_limiting', successRate: 0.88, uses: 8 },
//     { name: 'auth_flow', successRate: 0.92, uses: 10 }
//   ],
//   compositionPlan: 'api_caching → rate_limiting → auth_flow',
//   expectedSuccessRate: 0.91
// }
```

## 📊 Performance Improvements

- **116x faster** vector search with WASM acceleration (vs TypeScript fallback)
- **56% memory reduction** with SharedMemoryPool singleton pattern
- **Intelligent caching** with 60-second TTL for frequent queries
- **Lazy WASM loading** with graceful fallback to TypeScript

## 🔧 Technical Implementation

### API Alignment

All implementations now use **agentdb v1.3.9 API** correctly:

- ✅ `ReflexionMemory.getTaskStats()` for strategy learning
- ✅ `CausalRecall.recall()` with utility-based reranking
- ✅ `CausalMemoryGraph.addCausalEdge()` for causal tracking
- ✅ `NightlyLearner.run()` for automated discovery
- ✅ Direct imports from `agentdb/controllers/*` (with patch)

### Breaking Changes from v1.7.0

**None** - v1.7.1 is fully backwards compatible with v1.7.0. All simplified implementations have been replaced with full versions while maintaining the same API surface.

### Module Structure

```
src/reasoningbank/
├── HybridBackend.ts          # Full CausalRecall integration
├── AdvancedMemory.ts         # NightlyLearner + high-level ops
├── backend-selector.ts        # Automatic backend selection
├── agentdb-adapter.ts         # AgentDB integration layer
└── index.ts                   # Public exports
```

## 🐛 Known Issues & Workarounds

### AgentDB Import Resolution

**Issue**: agentdb v1.3.9 has missing `.js` extensions in `controllers/index.js`

**Workaround**: Apply patch automatically during `npm install`:

```bash
# Post-install patch applied via patches/agentdb-fix-imports.patch
# Adds .js extensions to:
# - export { ReflexionMemory } from './ReflexionMemory.js';
# - export { SkillLibrary } from './SkillLibrary.js';
# - export { EmbeddingService } from './EmbeddingService.js';
```

**Status**: Reported to agentdb maintainers. Patch is non-invasive and safe.

## 📚 Migration Guide

### From v1.7.0 to v1.7.1

**No code changes required!** v1.7.1 replaces simplified implementations with full versions while maintaining the exact same API.

### Example: Strategy Learning

```typescript
// v1.7.0 (simplified)
const strategy = await rb.learnStrategy('task');
// { patterns: [...], causality: {...}, confidence: 0.6, recommendation: '...' }

// v1.7.1 (full implementation)
const strategy = await rb.learnStrategy('task');
// Same API! But now includes:
// - Real causal analysis from ReflexionMemory.getTaskStats()
// - Improvement trends and confidence scores
// - Evidence-based recommendations
```

### Example: Auto-Consolidation

```typescript
// v1.7.0 (basic consolidation)
const result = await rb.autoConsolidate(3, 0.7, 30);
// { skillsCreated: X }

// v1.7.1 (with NightlyLearner)
const result = await memory.autoConsolidate({ minUses: 3, minSuccessRate: 0.7 });
// {
//   skillsCreated: X,
//   causalEdgesCreated: Y,        // NEW: Causal discovery
//   patternsAnalyzed: Z,           // NEW: Pattern analysis
//   executionTimeMs: T,
//   recommendations: [...]         // NEW: Actionable insights
// }
```

## 🧪 Testing

Comprehensive test suite added in `tests/reasoningbank/`:

- `integration.test.ts` - 20 integration tests covering all features
- `hybrid-backend.test.ts` - Unit tests for HybridReasoningBank (vitest-ready)
- `advanced-memory.test.ts` - Unit tests for AdvancedMemorySystem (vitest-ready)

```bash
# Run tests
npm test

# Run specific test suite
npx vitest run tests/reasoningbank/integration.test.ts
```

## 📖 Documentation

- [HybridBackend API](./src/reasoningbank/HybridBackend.ts) - Full source with JSDoc
- [AdvancedMemory API](./src/reasoningbank/AdvancedMemory.ts) - Full source with JSDoc
- [TESTING.md](./TESTING.md) - Test results and validation
- [CHANGELOG.md](./CHANGELOG.md) - Detailed version history

## 🔮 Future Enhancements (v1.8.0)

- **WASM SIMD Optimization**: Full Rust implementation with SIMD acceleration
- **Distributed Causal Discovery**: Multi-node causal inference
- **Explainable Recall**: Provenance certificates with Merkle proofs
- **Streaming Patterns**: Real-time pattern updates and notifications
- **Cross-Session Learning**: Persistent learning across multiple sessions

## 🙏 Credits

- **AgentDB v1.3.9**: Frontier memory systems integration
- **ReasoningBank**: Self-learning AI with experience replay
- **agentic-flow community**: Testing and feedback

## 📦 Installation

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

# Post-install: agentdb patch applied automatically
```

## 🔗 Resources

- **GitHub**: https://github.com/ruvnet/agentic-flow
- **npm**: https://www.npmjs.com/package/agentic-flow
- **AgentDB**: https://www.npmjs.com/package/agentdb
- **Issues**: https://github.com/ruvnet/agentic-flow/issues

---

**Status**: ✅ Production Ready
**Compatibility**: Node.js 18+, TypeScript 5+
**License**: MIT