pi-semble

Hybrid (semantic + lexical + code-aware-rerank) search over your local code and the markdown doc library, backed by MinishLab/semble. Replaces code-vocab's vocab_find and pi-research-library's FTS5 kb_search.

No model server, no GPU. Semble is invoked on demand via uvx (CPU-only).

Tools

| Tool | What it does | |---|---| | repo_search(query, top_k?, snippets?) | Semantic+lexical search over THIS repo's source. Returns file:line ranked chunks. | | kb_search(query, scope?, top_k?, snippets?) | Search the doc library. scope: project | global | both (default both). Hides superseded docs; annotates [authority] + sources. | | find_related(file_path, line, top_k?) | Code semantically similar to a location — siblings / callers / tests. |

Note: the web code-example tool code_search belongs to pi-web-tools; this extension's local code tool is deliberately named repo_search to avoid the collision.

Index / model layout

Three artifacts, two of them under ~/.pi/cache (shared) and one per-project:

| Artifact | Location | Env var | |---|---|---| | Project index (code + project docs) | <repo>/.pi/semble/ (git-ignored, rebuildable) | SEMBLE_CACHE_LOCATION | | Global doc index (~/.pi/kb) | ~/.pi/cache/semble-global/ (built once, shared) | SEMBLE_CACHE_LOCATION | | Embedding model (potion-code-16M, ~64 MB) | ~/.pi/cache/hf/ (shared, download-once) | HF_HOME |

The index is built lazily: a fire-and-forget warm-up runs on session_start (git-freshness gated), and the first real query builds the cache if needed. First ever session downloads ~64 MB (the model).

First run in a new repo

The first time pi opens in a code repo, semble asks before indexing — a one-time confirm dialog ("Initialize semble?"). The answer is remembered per repo via markers under the git-ignored <repo>/.pi/semble/ cache dir:

| Decision | Marker | Effect | |---|---|---| | Yes | .enabled (or legacy .warm-signal) | Silent freshness-gated warm on every session. | | No | .opt-out | Dormant: no warm, no nudges. Search tools stay callable on demand. | | Unset | (no cache dir) | Prompt again next interactive session. |

Repos indexed before this change have a .warm-signal and are treated as already enabled, so they keep working with no prompt. To re-decide a declined repo, delete <repo>/.pi/semble/ (or its .opt-out marker). Without an interactive UI (print/RPC), an unset repo is left untouched (no prompt, no warm) unless PI_SEMBLE_AUTO_INIT=1 is set.

Behavior

• Detection: only activates as a code repo when source files are tracked at any depth (git-aware) or a manifest exists; non-code dirs index nothing.
• Guard: if the agent reaches for manual grep/find/read to discover code, it's nudged (once per session) toward repo_search/kb_search/find_related. A short system-prompt note also states the preference up front.
• Provenance: kb_search reads frontmatter of the returned hits to drop superseded docs and annotate authority/sources — semble itself is pure retrieval.
• Fail-open: every hook swallows errors; semble is an optimization, never a hard dependency.

Config

| Env | Effect | |---|---| | PI_SEMBLE_DISABLE=1 | Register nothing (kill switch). | | PI_SEMBLE_AUTO_INIT=1 | Skip the first-run prompt and index silently (restores pre-prompt behavior; useful for CI / scripted / no-UI runs). |

Requirements

• uv/uvx on PATH (semble is pulled via uvx --from "semble[mcp]" semble).
• Python ≥ 3.10 (managed by uvx).

Deferred

Warm-MCP transport (a lazily-spawned, warm semble MCP server for ~ms queries instead of the ~1.4 s per-call uvx startup) is a future internal swap behind the same engine interface — see docs/superpowers/plans/2026-06-20-semble-search-integration.md, Phase 8.

Credits

The search engine is semble by MinishLab, pulled at runtime via uvx --from "semble[mcp]" semble. This extension is a thin pi integration layer (tools, indexing lifecycle, provenance) over their package — all retrieval credit goes to MinishLab.