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.txt

See ./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.py returns 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/heartbeat

Execution Protocol

1. Dry run -- show what will be removed

python3 .agents/skills/vector-db-cleanup/scripts/cleanup.py \
  --profile knowledge --dry-run

Report: "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 --apply

3. Verify store integrity (optional)

python3 .agents/skills/vector-db-cleanup/scripts/vector_consistency_check.py \
  --profile knowledge

4. Smoke test search still works

python3 .agents/skills/vector-db-cleanup/scripts/query.py \
  "test query" --profile knowledge --limit 3

Rules

• Always dry-run first. Never apply without showing the user what will be deleted.
• Never delete from .vector_data/ directly -- always use cleanup.py.
• Never read .sqlite3 files with raw shell tools -- will corrupt context.
• Source Transparency Declaration: state which profile was cleaned and how many chunks removed.