infra-search
Manage AICP's search surfaces — KB semantic search (LocalAI Collections + nomic-embed embeddings + bge-reranker reranking via `aicp --kb search` and `aicp_kb_search_collection` MCP), source code searc
SKILL.md.claude/skills/infra-search/SKILL.md
GitHubinfra-search
Manage AICP's search surfaces. AICP exposes 3 distinct search shapes:
- Semantic search (KB) — LocalAI Collections at
localhost:8090/app/collections, embedded via nomic-embed, reranked via bge-reranker-v2-m3. Accessed viaaicp --kb searchCLI oraicp_kb_search_collectionMCP tool (Category B KEEP per audit). - Source code search — Grep + Glob (ripgrep-backed via Claude Code
tool). No code-specific index; treesitter parsing happens via
claude-mem:smart-exploreskill. - Wiki page search — second brain's
python3 -m tools.view search <query>CLI (project-internal lexical search across wiki/).
Trigger phrases (when to load this skill)
Load when the conversation matches any of:
- Direct verb: "set up search", "tune embedding search", "rerank results", "why are search results wrong", "add a new search surface"
- KB tuning: chunking strategy, top_k, threshold values, reranker on/off
- Code-aware search: when grep is too coarse and operator wants
structural/semantic — load
claude-mem:smart-exploreinstead - Multi-store search: searching across KB + wiki + code in one query
Do NOT load when:
- The concern is the KB ingestion lifecycle (load
infra-storagefor KB persistence,aicp --kb addfor the runtime workflow) - The concern is monitoring KB health (load
infra-monitoring) - The concern is Mission Control's web search UI (separate project)
Operations
Operation 1 — Tune semantic search relevance
When: KB search returns irrelevant or missing results.
Process:
- Inspect current settings in
config/default.yamlrag:section:top_k(default 5) — how many results to retrieve before rerankingchunk_size/chunk_overlap— how source text is split for embeddingthreshold— minimum cosine similarity to consider a matchrerank: true/false— apply bge-reranker re-scoringmax_context_chars— RAG context budget passed to the LLM
- Common failure modes:
- Missing relevant chunks → lower
threshold, increasetop_k, decreasechunk_size(more granular) - Off-topic results → enable rerank, raise
threshold - Truncated results → increase
max_context_chars(within KB context window)
- Missing relevant chunks → lower
- Re-run
aicp --kb search --kb-arg "<query>"after each tune - For systematic tuning, use a test query set (operator-provided) and measure precision/recall
Quality bar: NEVER tune without a baseline measurement. Tune one parameter at a time so you can attribute the effect.
Operation 2 — Add a new search surface
When: AICP needs to search a new content type (e.g., GitHub issues, external docs, log files).
Process:
- Decide indexing strategy:
- Embed into existing aicp-kb collection (preferred) —
aicp --kb add --kb-arg <path>for files - New LocalAI collection for isolated storage —
localhost:8090/app/collections/{new-collection} - External index (e.g., GitHub API direct query) — no embed, fetch on demand
- Embed into existing aicp-kb collection (preferred) —
- For embedded surfaces: add ingestion command in
aicp/cli/main.pyif not already covered by--kb add - For query: extend
aicp --kb searchwith--kb-arg2 <collection-name>if multi-collection becomes a frequent need - Document the new surface in CLAUDE.md
## Knowledge Baseor wiki
Quality bar: PREFER extending the existing collection over creating new ones — multi-collection search increases query complexity.
Operation 3 — Diagnose search quality
When: operator reports unexpected ranking.
Process:
- Reproduce:
aicp --kb search --kb-arg "<query>"(with rerank on) - Look at the top results' source paths — are they ON-TOPIC?
- If off-topic: re-embed the source (chunking may have split awkwardly)
- If missing topical content: verify ingestion (
aicp --kb listshows sources) - Check reranker score distribution — large gaps signal weak reranking
- Fall back to grep for sanity check:
Grep "<keyword>" wiki/— does the term even exist in the corpus?
Quality bar: search quality is multi-causal (chunking + embedding
- reranking + threshold). Diagnose one layer at a time.
Gotchas
Detection: agent assumes AICP uses Elasticsearch. Rule: AICP uses LocalAI Collections (chromem-backed). No Elasticsearch. Reasoning: setting expectations correctly avoids time wasted on nonexistent infrastructure.
Detection: agent recommends raising
top_kto 100 to "find more results". Rule: top_k > 20 typically degrades quality (reranker can't sort 100 items well; LLM context fills with noise). Reasoning: search is precision-first; flooding with low-quality matches dilutes the LLM's RAG context.Detection: agent disables reranker to "speed up search". Rule: reranker adds <500ms typically; the quality lift is large. Disable only with measured evidence the latency matters more. Reasoning: bge-reranker meaningfully improves precision; the cost is rarely the bottleneck for operator-driven queries.
Detection: agent embeds large binary files into KB. Rule: KB is for TEXT. Binary embedding produces nonsense vectors. Skip / convert to text first. Reasoning: nomic-embed expects text input; binary bytes embed to random-ish vectors that pollute results.
Reference exemplars
aicp/core/kb.py— KB query implementation (search + augment)aicp/core/rag.py— RAG pipeline + chunkeraicp/cli/main.py_run_kb()—--kbCLI dispatcherconfig/default.yamlrag:section — tunable parameterswiki/decisions/01_drafts/4-tier-router-with-profiles-over-hardcoded-routing.md— router that uses RAG context
Domain context
AICP's KB is the operational knowledge store: ingested via aicp --kb add, queried via aicp --kb search or --rag flag, persisted in
LocalAI Collections (per infra-storage skill). The search pipeline is
embed → similarity → rerank → LLM-context. Precision matters more than
recall for inference quality (per the autocomplete-chain lesson — better
to retrieve nothing than to retrieve wrong context).
Related skills
| Skill | When to use |
|---|---|
infra-storage |
When the concern is KB persistence (Collections directory) |
infra-monitoring |
When alerting on KB query rate / latency |
quality-performance |
When measuring KB query latency under load |
claude-mem:smart-explore |
When code-aware search is needed (treesitter, AST) |