Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'

vendor/ruvector/examples/agentic-jujutsu/README.md

@@ -0,0 +1,187 @@
+# Agentic-Jujutsu Examples
+
+This directory contains comprehensive examples demonstrating the capabilities of agentic-jujutsu, a quantum-resistant, self-learning version control system designed for AI agents.
+
+## Examples Overview
+
+### 1. Basic Usage (`basic-usage.ts`)
+Fundamental operations for getting started:
+- Repository status checks
+- Creating commits
+- Branch management
+- Viewing commit history and diffs
+
+**Run:** `npx ts-node basic-usage.ts`
+
+### 2. Learning Workflow (`learning-workflow.ts`)
+Demonstrates ReasoningBank self-learning capabilities:
+- Starting and tracking learning trajectories
+- Recording operations and outcomes
+- Getting AI-powered suggestions
+- Viewing learning statistics and discovered patterns
+
+**Run:** `npx ts-node learning-workflow.ts`
+
+### 3. Multi-Agent Coordination (`multi-agent-coordination.ts`)
+Shows how multiple AI agents work simultaneously:
+- Concurrent commits without locks (23x faster than Git)
+- Shared learning across agents
+- Collaborative code review workflows
+- Conflict-free coordination
+
+**Run:** `npx ts-node multi-agent-coordination.ts`
+
+### 4. Quantum Security (`quantum-security.ts`)
+Demonstrates quantum-resistant security features:
+- SHA3-512 quantum fingerprints (<1ms)
+- HQC-128 encryption
+- Data integrity verification
+- Secure trajectory storage
+
+**Run:** `npx ts-node quantum-security.ts`
+
+## Key Features Demonstrated
+
+### Performance Benefits
+- **23x faster** concurrent commits (350 ops/s vs Git's 15 ops/s)
+- **10x faster** context switching (<100ms vs Git's 500-1000ms)
+- **87% automatic** conflict resolution
+- **Zero** lock waiting time
+
+### Self-Learning Capabilities
+- Trajectory tracking for continuous improvement
+- Pattern discovery from successful operations
+- AI-powered suggestions with confidence scores
+- Learning statistics and improvement metrics
+
+### Quantum-Resistant Security
+- SHA3-512 fingerprints (NIST FIPS 202)
+- HQC-128 post-quantum encryption
+- <1ms verification performance
+- Future-proof against quantum computers
+
+### Multi-Agent Features
+- Lock-free concurrent operations
+- Shared learning between agents
+- Collaborative workflows
+- Cross-agent pattern recognition
+
+## Prerequisites
+
+```bash
+# Install agentic-jujutsu
+npm install agentic-jujutsu
+
+# Or run directly
+npx agentic-jujutsu
+```
+
+## Running the Examples
+
+### Individual Examples
+```bash
+# Basic usage
+npx ts-node examples/agentic-jujutsu/basic-usage.ts
+
+# Learning workflow
+npx ts-node examples/agentic-jujutsu/learning-workflow.ts
+
+# Multi-agent coordination
+npx ts-node examples/agentic-jujutsu/multi-agent-coordination.ts
+
+# Quantum security
+npx ts-node examples/agentic-jujutsu/quantum-security.ts
+```
+
+### Run All Examples
+```bash
+cd examples/agentic-jujutsu
+for file in *.ts; do
+  echo "Running $file..."
+  npx ts-node "$file"
+  echo ""
+done
+```
+
+## Testing
+
+Comprehensive test suites are available in `/tests/agentic-jujutsu/`:
+
+```bash
+# Run all tests
+./tests/agentic-jujutsu/run-all-tests.sh
+
+# Run with coverage
+./tests/agentic-jujutsu/run-all-tests.sh --coverage
+
+# Run with verbose output
+./tests/agentic-jujutsu/run-all-tests.sh --verbose
+
+# Stop on first failure
+./tests/agentic-jujutsu/run-all-tests.sh --bail
+```
+
+## Integration with Ruvector
+
+Agentic-jujutsu can be integrated with Ruvector for:
+- Versioning vector embeddings
+- Tracking AI model experiments
+- Managing agent memory evolution
+- Collaborative AI development
+
+Example integration:
+```typescript
+import { VectorDB } from 'ruvector';
+import { JjWrapper } from 'agentic-jujutsu';
+
+const db = new VectorDB();
+const jj = new JjWrapper();
+
+// Track vector database changes
+jj.startTrajectory('Update embeddings');
+await db.insert('doc1', [0.1, 0.2, 0.3]);
+await jj.newCommit('Add new embeddings');
+jj.addToTrajectory();
+jj.finalizeTrajectory(0.9, 'Embeddings updated successfully');
+```
+
+## Best Practices
+
+### 1. Trajectory Management
+- Use meaningful task descriptions
+- Record honest success scores (0.0-1.0)
+- Always finalize trajectories
+- Add detailed critiques for learning
+
+### 2. Multi-Agent Coordination
+- Let agents work concurrently (no manual locks)
+- Share learning through trajectories
+- Use suggestions for informed decisions
+- Monitor improvement rates
+
+### 3. Security
+- Enable encryption for sensitive operations
+- Verify fingerprints regularly
+- Use quantum-resistant features for long-term data
+- Keep encryption keys secure
+
+### 4. Performance
+- Batch operations when possible
+- Use async operations for I/O
+- Monitor operation statistics
+- Optimize based on learning patterns
+
+## Documentation
+
+For complete API documentation and guides:
+- **Skill Documentation**: `.claude/skills/agentic-jujutsu/SKILL.md`
+- **NPM Package**: https://npmjs.com/package/agentic-jujutsu
+- **GitHub**: https://github.com/ruvnet/agentic-flow/tree/main/packages/agentic-jujutsu
+
+## Version
+
+Examples compatible with agentic-jujutsu v2.3.2+
+
+## License
+
+MIT License - See project LICENSE file