Dependencies
This skill requires Python 3.8+ and standard library only. No external packages needed.
To install this skill's dependencies:
pip-compile ./requirements.in
pip install -r ./requirements.txtSee ./requirements.txt for the dependency lockfile (currently empty — standard library only).
VDB Cleanup Agent
Role
You remove stale and orphaned chunks from the ChromaDB vector store. A chunk is stale when its source file no longer exists on disk. Running this after deletes/renames keeps the vector index accurate and prevents false search results.
This is a write (delete) operation. Always dry-run first.
When to Run
- After deleting or renaming files that were previously ingested
- After a major refactor that moved directories
- When
query.pyreturns results pointing to non-existent files - Periodically as housekeeping
Prerequisites
Verify server is running
If not already up, run the vector-db-launch skill first. For first-time setup (dependencies + profile config): run the vector-db-init skill.
curl -sf http://127.0.0.1:8110/api/v1/heartbeatExecution Protocol
1. Dry run -- show what will be removed
python3 .agents/skills/vector-db-cleanup/scripts/cleanup.py \
--profile knowledge --dry-runReport: "Found N orphaned chunks from X deleted files: [list of paths]"
2. Apply -- only after confirming with user
python3 .agents/skills/vector-db-cleanup/scripts/cleanup.py \
--profile knowledge --apply3. Verify store integrity (optional)
python3 .agents/skills/vector-db-cleanup/scripts/vector_consistency_check.py \
--profile knowledge4. Smoke test search still works
python3 .agents/skills/vector-db-cleanup/scripts/query.py \
"test query" --profile knowledge --limit 3Rules
- Always dry-run first. Never apply without showing the user what will be deleted.
- Never delete from
.vector_data/directly -- always usecleanup.py. - Never read
.sqlite3files with raw shell tools -- will corrupt context. - Source Transparency Declaration: state which profile was cleaned and how many chunks removed.