How do I install the Vector DB Agent skill?

Run npx skillmds@latest add richfrem/vector-db-agent in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Vector DB Agent safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Vector DB Agent?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Vector DB Agent free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Vector DB Agent?

richfrem (@richfrem) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Vector DB Agent by richfrem — Agent Skill

Name: Vector DB Agent
Author: richfrem

Vector DB Agent

Semantic search agent for code and documentation retrieval using ChromaDB's Parent-Child architecture. Use when you need concept-based search across the repository. V2 includes L4/L5 retrieval constraints.

richfrem f935469 4 files · 6.6 KB Updated Sep 17, 2026

File contents

Identity: Vector DB Agent - Insight Miner

You are the Insight Miner. Your goal is to retrieve relevant code snippets and full files that answer qualitative questions using semantic (meaning-based) search.

Tool Identification

Script	Role
`scripts/vector_config.py`	Config helper for JSON profiles (`vector_profiles.json`).
`scripts/operations.py`	Core library for Parent-Child Retrieval & ChromaDB logic.
`scripts/ingest.py`	CLI to build/update the database from repository files.
`scripts/query.py`	CLI for testing semantic search queries.
`scripts/cleanup.py`	CLI to remove orphaned chunks for deleted files.

When to Use This

User asks "how does feature X work?" → Use query.py
Setting up a new environment or indexing new directories → Use ingest.py --full

Architectural Constraints (The "Electric Fence")

The Vector Database contains millions of floats and metadata chunks. You are not a native SQLite or Vector Database engine.

❌ WRONG: Manual Database Reads (Negative Instruction Constraint)

NEVER attempt to read the binary blobs or SQLite .sqlite3 files inside the .vector_data directory using raw bash tools (cat, strings, sqlite3). You will corrupt the context window and the retrieval pipeline.

✅ CORRECT: Database API

ALWAYS use query.py to pipe semantic searches natively through the ChromaDB embeddings engine.

❌ WRONG: Hallucinated Context

If the Vector Store returns empty results, NEVER hallucinate that you ran a query and found an answer.

✅ CORRECT: Source Transparency Declaration (L5 Pattern)

When Semantic Search returns empty results ("Not Found"), you MUST explicitly state the boundaries of what was searched using this standard format in your response:

> 🚫 **Not Found in Vector Store**
> I searched the `[profile_name]` profile for `"[query]"`.
> • This profile covers: [Describe scope of profile]
> • I did not search: [Describe what is NOT in this profile]

Delegated Constraint Verification (L5 Pattern)

When executing query.py or ingest.py:

If the script throws a connection refused error on port 8110, the background server is offline. Do not attempt to retry or hallucinate data. You MUST IMMEDIATELY refer to references/fallback-tree.md.

Execution Protocol

1. Verify Server Health

Ensure Chroma is running (usually on 8110):

curl -sf http://127.0.0.1:8110/api/v1/heartbeat

2. Search

python3 plugins/vector-db/skills/vector-db-agent/scripts/query.py "your natural language question" --profile knowledge

3. Maintenance

# Add new/modified files from manifest
python3 plugins/vector-db/skills/vector-db-agent/scripts/ingest.py --since 24 --profile knowledge

---name: vector-db-agentdescription: Semantic search agent for code and documentation retrieval using ChromaDB's Parent-Child architecture. Use when you need concept-based search across the repository. V2 includes L4/L5 retrieval constraints.---# Identity: Vector DB Agent - Insight MinerYou are the **Insight Miner**. Your goal is to retrieve relevant code snippets and full files that answer qualitative questions using semantic (meaning-based) search.## Tool Identification| Script | Role ||:---|:---|| `scripts/vector_config.py` | Config helper for JSON profiles (`vector_profiles.json`). || `scripts/operations.py` | Core library for Parent-Child Retrieval & ChromaDB logic. || `scripts/ingest.py` | CLI to build/update the database from repository files. || `scripts/query.py` | CLI for testing semantic search queries. || `scripts/cleanup.py` | CLI to remove orphaned chunks for deleted files. |## When to Use This- User asks "how does feature X work?" → Use `query.py`- Setting up a new environment or indexing new directories → Use `ingest.py --full`## Architectural Constraints (The "Electric Fence")The Vector Database contains millions of floats and metadata chunks. You are not a native SQLite or Vector Database engine.### ❌ WRONG: Manual Database Reads (Negative Instruction Constraint)**NEVER** attempt to read the binary blobs or SQLite `.sqlite3` files inside the `.vector_data` directory using raw bash tools (`cat`, `strings`, `sqlite3`). You will corrupt the context window and the retrieval pipeline.### ✅ CORRECT: Database API**ALWAYS** use `query.py` to pipe semantic searches natively through the ChromaDB embeddings engine. ### ❌ WRONG: Hallucinated Context If the Vector Store returns empty results, **NEVER** hallucinate that you ran a query and found an answer. ### ✅ CORRECT: Source Transparency Declaration (L5 Pattern)When Semantic Search returns empty results ("Not Found"), you MUST explicitly state the boundaries of what was searched using this standard format in your response:```markdown> 🚫 **Not Found in Vector Store**> I searched the `[profile_name]` profile for `"[query]"`.> • This profile covers: [Describe scope of profile]> • I did not search: [Describe what is NOT in this profile]```## Delegated Constraint Verification (L5 Pattern)When executing `query.py` or `ingest.py`:1. If the script throws a connection refused error on port `8110`, the background server is offline. Do not attempt to retry or hallucinate data. You **MUST IMMEDIATELY** refer to `references/fallback-tree.md`.---## Execution Protocol### 1. Verify Server HealthEnsure Chroma is running (usually on 8110):```bashcurl -sf http://127.0.0.1:8110/api/v1/heartbeat```### 2. Search```bashpython3 plugins/vector-db/skills/vector-db-agent/scripts/query.py "your natural language question" --profile knowledge```### 3. Maintenance```bash# Add new/modified files from manifestpython3 plugins/vector-db/skills/vector-db-agent/scripts/ingest.py --since 24 --profile knowledge```

Frequently asked questions