vector-db-search

Vector DB Search (vector-db-search)

Semantic concept-based search against ChromaDB using Parent-Child chunk retrieval for Phase 2 of the 3-phase search protocol (RLM -> Vector -> Grep).

Contents

• Critical Constraints
• Quick start
• Workflow
• Verification
• References

Critical Constraints

1. Profile Sovereignty: The --profile parameter is mandatory to ensure queries target the correct collection and embedding space.
2. API Integrity: Never read SQLite or Parquet backing files directly. Queries must execute through scripts/query.py.
3. Search Protocol Placement: Use as Phase 2 when RLM summaries return insufficient detail, before falling back to raw regex grep.

Quick start

Execute a natural-language semantic query against the default profile:

python3 scripts/query.py "how does session memory persist" --profile wiki --limit 5

Workflow

1. Identify Target Profile: Verify configured profile collections (wiki, codebase) in .agent/learning/vector_profiles.json.
2. Execute Query: Run scripts/query.py with the natural language query, specifying --profile and result limit.
3. Ingest Parent Chunks: Extract returned high-context parent chunks (up to 2,000 chars) for downstream reasoning.
4. Transparent Reporting: If no results match, report the exact profile and query string evaluated before falling back to grep.

Verification

Verify ChromaDB index responsiveness and consistency:

python3 scripts/vector_consistency_check.py --profile wiki

References

• acceptance-criteria.md — Retrieval accuracy criteria and ranking constraints.
• cheapest_models.md — Embedding model tiers and pricing guidance.
• fallback-tree.md — Fallback protocol when vector collections are unavailable or return zero hits.