Squashed 'vendor/ruvector/' content from commit b64c2172
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
This commit is contained in:
ruv
581
docs/hooks/MIGRATION.md
Normal file
581
docs/hooks/MIGRATION.md
Normal file
@@ -0,0 +1,581 @@
|
||||
# RuVector Hooks Migration Guide
|
||||
|
||||
Guide for migrating to RuVector's portable hooks system from legacy setups or other tools.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Overview](#overview)
|
||||
2. [Migration Paths](#migration-paths)
|
||||
3. [From Legacy Intelligence](#from-legacy-intelligence)
|
||||
4. [From Claude-Flow](#from-claude-flow)
|
||||
5. [From Manual Setup](#from-manual-setup)
|
||||
6. [Data Preservation](#data-preservation)
|
||||
7. [Verification](#verification)
|
||||
8. [Rollback](#rollback)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
### Why Migrate?
|
||||
|
||||
The new RuVector hooks system provides:
|
||||
|
||||
| Feature | Legacy | New System |
|
||||
|---------|--------|------------|
|
||||
| Portability | Hardcoded paths | Dynamic resolution |
|
||||
| CLI Management | Manual JSON editing | Full CLI support |
|
||||
| Cross-platform | Linux/macOS only | Linux, macOS, Windows |
|
||||
| Global Patterns | Not available | Supported |
|
||||
| Binary Updates | Hooks break | Survive reinstalls |
|
||||
|
||||
### Migration Safety
|
||||
|
||||
All migrations include:
|
||||
- **Automatic backup** of existing data
|
||||
- **Validation** of migrated data
|
||||
- **Atomic operations** with rollback capability
|
||||
- **Zero data loss** guarantee
|
||||
|
||||
---
|
||||
|
||||
## Migration Paths
|
||||
|
||||
### Quick Reference
|
||||
|
||||
| Source | Command | Time |
|
||||
|--------|---------|------|
|
||||
| Legacy `.claude/intelligence/` | `hooks migrate --from .claude/intelligence` | <5s |
|
||||
| Claude-flow `memory.db` | `hooks migrate --from ~/.swarm/memory.db` | <10s |
|
||||
| Exported JSON | `hooks import --input patterns.json` | <2s |
|
||||
| Fresh start | `hooks init` | <1s |
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Before migrating:
|
||||
|
||||
```bash
|
||||
# 1. Backup existing data
|
||||
cp -r .claude/intelligence .claude/intelligence.backup
|
||||
cp -r ~/.swarm ~/.swarm.backup
|
||||
|
||||
# 2. Install latest RuVector CLI
|
||||
npm install -g @ruvector/cli@latest
|
||||
|
||||
# 3. Verify installation
|
||||
npx ruvector --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## From Legacy Intelligence
|
||||
|
||||
Migrate from the repository-specific `.claude/intelligence/` system.
|
||||
|
||||
### Current Legacy Structure
|
||||
|
||||
```
|
||||
.claude/
|
||||
├── intelligence/
|
||||
│ ├── data/
|
||||
│ │ ├── memory.json # Vector memories
|
||||
│ │ ├── trajectories.json # Learning history
|
||||
│ │ ├── patterns.json # Q-learning patterns
|
||||
│ │ └── feedback.json # User feedback
|
||||
│ ├── index.js # Intelligence layer
|
||||
│ └── cli.js # CLI commands
|
||||
└── settings.json # Hardcoded hooks
|
||||
```
|
||||
|
||||
### Migration Steps
|
||||
|
||||
#### Step 1: Initialize New System
|
||||
|
||||
```bash
|
||||
npx ruvector hooks init
|
||||
```
|
||||
|
||||
This creates:
|
||||
```
|
||||
.ruvector/
|
||||
├── config.toml
|
||||
├── intelligence/
|
||||
│ └── (empty, ready for migration)
|
||||
└── .gitignore
|
||||
```
|
||||
|
||||
#### Step 2: Migrate Data
|
||||
|
||||
```bash
|
||||
# Migrate with validation
|
||||
npx ruvector hooks migrate \
|
||||
--from .claude/intelligence \
|
||||
--validate
|
||||
|
||||
# Expected output:
|
||||
# Migrating from JSON files...
|
||||
# ✓ Imported 1,247 trajectories
|
||||
# ✓ Imported 89 Q-learning patterns
|
||||
# ✓ Converted 543 memories to vectors
|
||||
# ✓ Validation passed (100% integrity)
|
||||
# ⏱ Completed in 3.2s
|
||||
```
|
||||
|
||||
#### Step 3: Install New Hooks
|
||||
|
||||
```bash
|
||||
# Install portable hooks
|
||||
npx ruvector hooks install --force
|
||||
|
||||
# This replaces hardcoded paths with dynamic resolution
|
||||
```
|
||||
|
||||
#### Step 4: Verify Migration
|
||||
|
||||
```bash
|
||||
# Check statistics
|
||||
npx ruvector hooks stats --verbose
|
||||
|
||||
# Should show migrated data:
|
||||
# Patterns: 89
|
||||
# Memories: 543
|
||||
# Trajectories: 1,247
|
||||
```
|
||||
|
||||
#### Step 5: Clean Up (Optional)
|
||||
|
||||
After confirming migration success:
|
||||
|
||||
```bash
|
||||
# Remove legacy intelligence directory
|
||||
rm -rf .claude/intelligence
|
||||
|
||||
# Keep backup for safety
|
||||
# rm -rf .claude/intelligence.backup # Only if confident
|
||||
```
|
||||
|
||||
### Legacy Settings.json Update
|
||||
|
||||
**Before (hardcoded):**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [{
|
||||
"matcher": "Bash",
|
||||
"hooks": [{
|
||||
"command": "/bin/bash -c 'cd /workspaces/ruvector/.claude/intelligence && node cli.js pre-command'"
|
||||
}]
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**After (portable):**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [{
|
||||
"matcher": "Bash",
|
||||
"hooks": [{
|
||||
"command": "/bin/bash -c 'RUVECTOR=$(which ruvector || echo npx ruvector); $RUVECTOR hooks pre-command \"$CMD\"'"
|
||||
}]
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## From Claude-Flow
|
||||
|
||||
Migrate from Claude-Flow's SQLite memory database.
|
||||
|
||||
### Claude-Flow Structure
|
||||
|
||||
```
|
||||
~/.swarm/
|
||||
├── memory.db # SQLite database
|
||||
├── config.json # Configuration
|
||||
└── sessions/ # Session data
|
||||
```
|
||||
|
||||
### Migration Steps
|
||||
|
||||
#### Step 1: Locate Memory Database
|
||||
|
||||
```bash
|
||||
# Default location
|
||||
ls ~/.swarm/memory.db
|
||||
|
||||
# Custom location (check config)
|
||||
cat ~/.swarm/config.json | jq '.memoryPath'
|
||||
```
|
||||
|
||||
#### Step 2: Initialize RuVector
|
||||
|
||||
```bash
|
||||
cd your-project
|
||||
npx ruvector hooks init
|
||||
```
|
||||
|
||||
#### Step 3: Migrate SQLite Data
|
||||
|
||||
```bash
|
||||
# Migrate from SQLite
|
||||
npx ruvector hooks migrate \
|
||||
--from ~/.swarm/memory.db \
|
||||
--format sqlite \
|
||||
--validate
|
||||
|
||||
# Output:
|
||||
# Migrating from SQLite database...
|
||||
# ✓ Extracted 2,500 trajectories
|
||||
# ✓ Converted 150 Q-learning patterns
|
||||
# ✓ Migrated 1,200 memories to vectors
|
||||
# ✓ Validation passed
|
||||
```
|
||||
|
||||
**Note:** SQLite migration requires the `sqlite-migration` feature (v1.1+). For MVP, use JSON export:
|
||||
|
||||
```bash
|
||||
# Alternative: Export from claude-flow first
|
||||
npx claude-flow memory export --output memory-export.json
|
||||
|
||||
# Then import
|
||||
npx ruvector hooks import --input memory-export.json
|
||||
```
|
||||
|
||||
#### Step 4: Merge with Existing Data
|
||||
|
||||
If you have both legacy and claude-flow data:
|
||||
|
||||
```bash
|
||||
# Merge with existing patterns
|
||||
npx ruvector hooks migrate \
|
||||
--from ~/.swarm/memory.db \
|
||||
--merge \
|
||||
--strategy average
|
||||
```
|
||||
|
||||
#### Step 5: Install Hooks
|
||||
|
||||
```bash
|
||||
npx ruvector hooks install
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## From Manual Setup
|
||||
|
||||
Migrate from manually configured hooks.
|
||||
|
||||
### Current Manual Setup
|
||||
|
||||
**`.claude/settings.json` (manual):**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [{
|
||||
"matcher": "Write|Edit",
|
||||
"hooks": [{
|
||||
"type": "command",
|
||||
"command": "echo 'Pre-edit hook'"
|
||||
}]
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Migration Steps
|
||||
|
||||
#### Step 1: Backup Existing Settings
|
||||
|
||||
```bash
|
||||
cp .claude/settings.json .claude/settings.json.manual-backup
|
||||
```
|
||||
|
||||
#### Step 2: Initialize RuVector
|
||||
|
||||
```bash
|
||||
npx ruvector hooks init
|
||||
```
|
||||
|
||||
#### Step 3: Install with Merge
|
||||
|
||||
```bash
|
||||
# Merge RuVector hooks with existing
|
||||
npx ruvector hooks install --merge
|
||||
|
||||
# This preserves your custom hooks and adds RuVector hooks
|
||||
```
|
||||
|
||||
#### Step 4: Review Merged Settings
|
||||
|
||||
```bash
|
||||
# View the merged settings
|
||||
cat .claude/settings.json
|
||||
|
||||
# Verify your custom hooks are preserved
|
||||
```
|
||||
|
||||
### Preserving Custom Hooks
|
||||
|
||||
If you have custom hooks to preserve:
|
||||
|
||||
**Before install:**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [{
|
||||
"matcher": "CustomTool",
|
||||
"hooks": [{
|
||||
"command": "my-custom-hook.sh"
|
||||
}]
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**After install (merged):**
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [
|
||||
{
|
||||
"matcher": "Bash",
|
||||
"hooks": [{
|
||||
"command": "npx ruvector hooks pre-command"
|
||||
}]
|
||||
},
|
||||
{
|
||||
"matcher": "CustomTool",
|
||||
"hooks": [{
|
||||
"command": "my-custom-hook.sh"
|
||||
}]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Preservation
|
||||
|
||||
### What Gets Migrated
|
||||
|
||||
| Data Type | Source | Destination |
|
||||
|-----------|--------|-------------|
|
||||
| Q-learning patterns | `patterns.json` | `.ruvector/intelligence/patterns.json` |
|
||||
| Trajectories | `trajectories.json` | `.ruvector/intelligence/trajectories.json` |
|
||||
| Vector memories | `memory.json` | `.ruvector/intelligence/memory.rvdb` |
|
||||
| Feedback data | `feedback.json` | `.ruvector/intelligence/feedback.json` |
|
||||
| Configuration | settings.json | `.ruvector/config.toml` |
|
||||
|
||||
### Data Integrity Checks
|
||||
|
||||
The migration process includes:
|
||||
|
||||
1. **Checksum validation**: Verify data wasn't corrupted
|
||||
2. **Count verification**: Ensure all records migrated
|
||||
3. **Q-value preservation**: Maintain learned values
|
||||
4. **Vector accuracy**: Preserve embedding precision
|
||||
|
||||
### Backup Locations
|
||||
|
||||
Automatic backups are created:
|
||||
|
||||
```
|
||||
.ruvector/
|
||||
├── intelligence/
|
||||
│ └── backup-YYYYMMDD-HHMMSS/
|
||||
│ ├── patterns.json
|
||||
│ ├── trajectories.json
|
||||
│ └── memory.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
### Verify Migration Success
|
||||
|
||||
```bash
|
||||
# 1. Check statistics
|
||||
npx ruvector hooks stats --verbose
|
||||
|
||||
# 2. Compare counts
|
||||
echo "Legacy patterns: $(jq '.patterns | length' .claude/intelligence.backup/data/patterns.json 2>/dev/null || echo 0)"
|
||||
echo "Migrated patterns: $(npx ruvector hooks stats --json | jq '.patterns')"
|
||||
|
||||
# 3. Test hook execution
|
||||
npx ruvector hooks pre-edit --file test.ts
|
||||
npx ruvector hooks post-edit --file test.ts --success true
|
||||
|
||||
# 4. Verify session hooks
|
||||
npx ruvector hooks session-start --session-id "migration-test"
|
||||
npx ruvector hooks session-end --session-id "migration-test"
|
||||
```
|
||||
|
||||
### Expected Verification Output
|
||||
|
||||
```bash
|
||||
$ npx ruvector hooks stats --verbose
|
||||
|
||||
RuVector Intelligence Statistics
|
||||
================================
|
||||
|
||||
Data Migration Status: SUCCESS
|
||||
|
||||
Learning Data:
|
||||
Trajectories: 1,247 (migrated: 1,247)
|
||||
Patterns: 89 (migrated: 89)
|
||||
Memories: 543 vectors (migrated: 543)
|
||||
Integrity: 100%
|
||||
|
||||
Configuration:
|
||||
Hooks installed: Yes
|
||||
Portable paths: Yes
|
||||
Intelligence enabled: Yes
|
||||
```
|
||||
|
||||
### Test in Claude Code
|
||||
|
||||
1. Open Claude Code in your project
|
||||
2. Verify session start message appears
|
||||
3. Make an edit to a file
|
||||
4. Confirm agent assignment message
|
||||
5. Check post-edit formatting
|
||||
|
||||
---
|
||||
|
||||
## Rollback
|
||||
|
||||
### Automatic Rollback
|
||||
|
||||
If migration fails, automatic rollback occurs:
|
||||
|
||||
```bash
|
||||
$ npx ruvector hooks migrate --from .claude/intelligence
|
||||
|
||||
Migrating from JSON files...
|
||||
✓ Imported 1,247 trajectories
|
||||
✗ Error during pattern migration: Invalid Q-value format
|
||||
⟲ Rolling back migration...
|
||||
✓ Restored from backup
|
||||
Migration failed, original data preserved
|
||||
```
|
||||
|
||||
### Manual Rollback
|
||||
|
||||
To manually rollback:
|
||||
|
||||
#### Step 1: Restore Backup
|
||||
|
||||
```bash
|
||||
# Restore intelligence data
|
||||
rm -rf .ruvector/intelligence
|
||||
cp -r .ruvector/intelligence/backup-YYYYMMDD-HHMMSS/* .ruvector/intelligence/
|
||||
|
||||
# Or restore legacy location
|
||||
rm -rf .ruvector
|
||||
mv .claude/intelligence.backup .claude/intelligence
|
||||
```
|
||||
|
||||
#### Step 2: Restore Settings
|
||||
|
||||
```bash
|
||||
# Restore Claude settings
|
||||
cp .claude/settings.json.backup .claude/settings.json
|
||||
```
|
||||
|
||||
#### Step 3: Verify Restoration
|
||||
|
||||
```bash
|
||||
# For legacy
|
||||
node .claude/intelligence/cli.js stats
|
||||
|
||||
# For new system
|
||||
npx ruvector hooks stats
|
||||
```
|
||||
|
||||
### Complete Reset
|
||||
|
||||
To completely reset and start fresh:
|
||||
|
||||
```bash
|
||||
# Remove all RuVector data
|
||||
rm -rf .ruvector
|
||||
|
||||
# Remove from Claude settings
|
||||
# Edit .claude/settings.json to remove hooks section
|
||||
|
||||
# Reinitialize
|
||||
npx ruvector hooks init
|
||||
npx ruvector hooks install
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration FAQ
|
||||
|
||||
### Q: Will I lose my learned patterns?
|
||||
|
||||
**A:** No. All migrations include automatic backup and validation. Q-values, trajectories, and memories are preserved with 100% integrity.
|
||||
|
||||
### Q: Can I migrate incrementally?
|
||||
|
||||
**A:** Yes. Use the `--merge` flag to add new data without replacing existing:
|
||||
|
||||
```bash
|
||||
npx ruvector hooks migrate --from new-data.json --merge
|
||||
```
|
||||
|
||||
### Q: What about Windows compatibility?
|
||||
|
||||
**A:** The new system uses conditional shell detection:
|
||||
|
||||
```bash
|
||||
# Windows
|
||||
cmd /c 'npx ruvector hooks ...'
|
||||
|
||||
# Linux/macOS
|
||||
/bin/bash -c 'npx ruvector hooks ...'
|
||||
```
|
||||
|
||||
### Q: How do I migrate a team project?
|
||||
|
||||
**A:** Export and share patterns:
|
||||
|
||||
```bash
|
||||
# Team member 1: Export
|
||||
npx ruvector hooks export --output team-patterns.json
|
||||
|
||||
# Team member 2: Import and merge
|
||||
npx ruvector hooks import --input team-patterns.json --merge
|
||||
```
|
||||
|
||||
### Q: Is the migration reversible?
|
||||
|
||||
**A:** Yes. Backups are automatically created and manual rollback is always possible.
|
||||
|
||||
---
|
||||
|
||||
## Post-Migration Checklist
|
||||
|
||||
- [ ] `npx ruvector hooks stats` shows expected counts
|
||||
- [ ] Session hooks trigger on Claude Code start
|
||||
- [ ] Pre-edit hooks assign agents correctly
|
||||
- [ ] Post-edit hooks format code
|
||||
- [ ] No hardcoded paths in `.claude/settings.json`
|
||||
- [ ] Backup data stored safely
|
||||
- [ ] Team notified of migration (if applicable)
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [User Guide](USER_GUIDE.md) - Getting started
|
||||
- [CLI Reference](CLI_REFERENCE.md) - Command documentation
|
||||
- [Architecture](ARCHITECTURE.md) - Technical details
|
||||
- [Troubleshooting](TROUBLESHOOTING.md) - Common issues
|
||||
Reference in New Issue
Block a user