Skip to content
Browse documentation
cli

Context and tool discovery

Help your agent find relevant context while you control tool access. Add local embeddings for optional semantic search.

What this gives you

  • Context on demand. Let your agent find selected docs and skills, then read the pages it needs instead of pasting everything into the conversation.
  • Control over tool access. Choose which tools are available and how many attempts a session allows. Search cannot grant extra access.
  • Optional local retrieval. Add meaning-based search without a separate embedding API. Your existing coding agent still handles the conversation.

This is context retrieval, not automatic memory or conversation compaction. Embeddings change how results are ranked; Smoothie's separate permission checks control tool calls.

You control tool access

Start with read-only context. To allow actions, review and grant local tools or connect external MCP tools. Smoothie checks the permission, current contract, inputs, availability, and remaining allowance before dispatch.

Limits count attempts per session, not global spending. They do not restrict your agent's independent shell/file access. Never automatically retry an uncertain call: it may already have changed something.

Start without a model

Keyword search works without embeddings. Configure your agent to launch this read-only Framework-context connection:

bash
smoothie mcp serve --project /absolute/my-product --framework --exposure search

Replace the project path and follow Connect a coding agent. The agent launches the process; running it in a separate terminal does not connect it. For your own Markdown sources, see Context and search.

When to add local embeddings

Keyword (bm25, default)Match names and terms you already know. No model needed.
SemanticSearch metadata by meaning when your task uses different wording.
HybridCombine keyword matches with semantic ranking.

All three search selected metadata, not arbitrary code or full document bodies. Embeddings do not guarantee better recall or lower token use. Ranking runs locally; retrieved text and tool results can still reach your agent's model provider.

Set up local embeddings

Semantic/hybrid search needs a CPU-backend executable and the exact bge-small-en-v1.5-q8_0-v2 asset. No public model download URL is advertised yet. Without that compatible asset, keep using keyword search; arbitrary GGUF files and engine-free builds will not work.

With a compatible file, preview the import, apply it with --run, then inspect it:

bash
smoothie embedding setup --from /absolute/input/model.gguf --directory /absolute/models --format json
smoothie embedding setup --from /absolute/input/model.gguf --directory /absolute/models --run --format json
smoothie embedding status --directory /absolute/models --format json

Smoothie verifies the bytes; it does not download or convert weights. status is read-only. semanticSearchEnabled: false is expected: retaining a model does not enable search or prove backend readiness.

Add the search flags to your agent's launch arguments. This example includes an already approved connection named github; omit --approved github for context only:

bash
smoothie mcp serve --project /absolute/my-product --framework --approved github \
  --exposure search --method hybrid --model-directory /absolute/models

Use the storage root for --model-directory, not the GGUF file. Do not mix --approved with manual registry/grant flags or --max-tool-calls. mcp host-config does not accept --method or --model-directory; review the launch arguments yourself.

mcp serve has no --run flag: startup opts into inference after MCP initialization. The model/index belong to that connection. To remove retained assets, embedding remove plans first and requires --run to apply.

If something is missing

  • No results? Check selected sources, tool approvals, and diagnostics. No match does not prove the capability is absent.
  • Search still preparing? Wait for indexing. Changed sources can require a refresh; this never renews permission.
  • Model unavailable or preparation failed? Check the backend/assets and fix the cause before an intentional restart. There is no silent fallback to BM25.

The protocol reference explains readiness and result checks. For calls with uncertain effects, follow handling failed calls.