Migration

Don't migrate blind. RAGForge shadow-indexes a new embedding model, validates quality overlap against the old one on your real chunks, backs up the old index, and only then cuts over. Source: migrator.py.

Step by step

1. Load existing KB — read chunks from ~/.ragforge/knowledge_bases/<name>/vectors.json.
2. Re-embed with the new model — new_embedder.encode(texts) on every chunk.
3. Build shadow index — new InMemoryStore with the new vectors. Old store untouched.
4. Validate (if validate=True) — pick the first chunk's text as a probe, embed with both old and new model, compare top-3 results for overlap. quality_after = overlap_ratio.
5. Backup old store — copy vectors.json to vectors_backup.json.
6. Atomic cutover — save the new store over vectors.json.
7. Update metadata — write embedder_name, migrated_from, and embedder_dim to meta.json.

Python

from ragforge.migration import migrate_knowledge_base

result = migrate_knowledge_base(
    knowledge="my-kb",
    from_model="default",
    to_model="openai",
    validate=True,
)
print(result)
# {'knowledge': 'my-kb', 'from_model': 'default', 'to_model': 'openai',
#  'status': 'migrated', 'quality_before': 1.0, 'quality_after': 0.9667,
#  'num_chunks_migrated': 87}

HTTP API

curl -X POST http://localhost:8000/migrate \
  -H "Content-Type: application/json" \
  -d '{
    "knowledge":      "my-kb",
    "from_model":     "default",
    "to_model":       "openai",
    "run_validation": true
  }'

The response includes quality_before, quality_after, and num_chunks_migrated. The previous index stays on disk as vectors_backup.json so you can roll back manually if needed.