328 lines
9.5 KiB
Markdown
328 lines
9.5 KiB
Markdown
# 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
|