ollama_corpus_search

Corpus search. FLAGSHIP. Concept search over a persistent named corpus (e.g. ‘memory’, ‘canon’, ‘handbook’). Pass corpus + query; returns ranked [{id, path, score, chunk_index, preview?}] drawn from the indexed corpus. Use this as your default for semantic recall — the corpus is persistent across sessions so you don’t re-embed every call. Build or refresh a corpus with ollama_corpus_index first; see what’s available with ollama_corpus_list.

Parameters

Parameter	Type	Required	Default	Description
corpus	string	yes	—	Name of the corpus to search (e.g. ‘memory’, ‘canon’). Must have been indexed first with ollama_corpus_index.
query	string	yes	—	Concept or question to search for (max 1000 chars).
mode	"semantic" \	"lexical" \	"hybrid" \	"fact" \
top_k	integer	no	—	Return the top K chunks (default 10).
preview_chars	integer	no	—	Include this many chars of each chunk’s text in the result (default 200).
filter	object	no	—	Restrict which chunks participate in retrieval. Applied before RRF fusion so scores reflect the filtered set.
explain	boolean	no	—	When true, each top-5 hit gets a short LLM-generated ‘why matched’ explanation. Capped at 5 hits to bound cost. Fails soft — on LLM failure the hits return without why_matched and a warning is appended.

Full input schema

The JSON Schema below is generated from the same zod schema the server validates against at the wire — it cannot drift from runtime behavior.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "corpus": {
      "type": "string",
      "minLength": 1,
      "pattern": "^[a-zA-Z0-9_-]+$",
      "description": "Name of the corpus to search (e.g. 'memory', 'canon'). Must have been indexed first with ollama_corpus_index."
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1000,
      "description": "Concept or question to search for (max 1000 chars)."
    },
    "mode": {
      "description": "Ranking strategy. 'hybrid' (default) fuses dense + lexical via RRF — best for general queries. 'semantic' is dense-only. 'lexical' is BM25-only (no embed call). 'fact' is hybrid with exact-substring + short-chunk boosts for specific-fact lookups. 'title_path' searches only title/heading/path metadata (no embed call, sub-ms).",
      "type": "string",
      "enum": [
        "semantic",
        "lexical",
        "hybrid",
        "fact",
        "title_path"
      ]
    },
    "top_k": {
      "description": "Return the top K chunks (default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "preview_chars": {
      "description": "Include this many chars of each chunk's text in the result (default 200).",
      "type": "integer",
      "minimum": 0,
      "maximum": 500
    },
    "filter": {
      "description": "Restrict which chunks participate in retrieval. Applied before RRF fusion so scores reflect the filtered set.",
      "type": "object",
      "properties": {
        "path_glob": {
          "description": "Minimatch-style glob applied to chunk.path. Supports **, *, ? (no braces). Applied BEFORE ranking.",
          "type": "string",
          "minLength": 1
        },
        "since": {
          "description": "ISO timestamp. Keep only chunks whose source file mtime is ≥ this value.",
          "type": "string",
          "minLength": 1
        }
      }
    },
    "explain": {
      "description": "When true, each top-5 hit gets a short LLM-generated 'why matched' explanation. Capped at 5 hits to bound cost. Fails soft — on LLM failure the hits return without why_matched and a warning is appended.",
      "type": "boolean"
    }
  },
  "required": [
    "corpus",
    "query"
  ]
}

Envelope

Every tool returns the standard envelope — tier_used, model, tokens_in/tokens_out, elapsed_ms, backend provenance, warnings. See Envelope & tiers.

Source

Schema + handler: src/tools/corpusSearch.ts · registration: src/index.ts

---

Back to the Tool Reference.