---
title: "KB-RAG Reindex Runbook"
description: "Operational runbook for manual and emergency reindexing of the claude-home knowledge base on manticore."
type: runbook
domain: development
tags: [kb-rag, qdrant, manticore, operations]
---

# KB-RAG Reindex Runbook

## When to Use
- Search returns stale or missing results after a push
- After bulk file additions or directory restructuring
- After recovering from container crash or volume issue

## Incremental Reindex (normal)

Only re-embeds files whose content hash changed. Fast (~1-5 seconds).

```bash
ssh manticore "docker exec md-kb-rag-kb-rag-1 md-kb-rag index"
```

## Full Reindex (nuclear option)

Clears the state DB and re-embeds everything. Slow (~2-3 minutes for 150+ files).

```bash
ssh manticore "docker exec md-kb-rag-kb-rag-1 md-kb-rag index --full"
```

## Verify

```bash
# Check health
ssh manticore "docker exec md-kb-rag-kb-rag-1 md-kb-rag health"

# Check indexed file count and Qdrant point count
ssh manticore "docker exec md-kb-rag-kb-rag-1 md-kb-rag status"

# Check for validation errors in recent logs
ssh manticore "docker logs md-kb-rag-kb-rag-1 --tail 30 2>&1 | grep WARN"
```

## Escalation
- If Qdrant won't start: check disk space on manticore (`df -h`)
- If embeddings OOM: check GPU memory (`ssh manticore "nvidia-smi"`)
- Full stack restart: `ssh manticore "cd ~/docker/md-kb-rag && docker compose down && docker compose up -d"`