Workspace search

A ranked, chunk-aware full-text search over your workspace's file content — the complement to exact-match grep. Use it to find where a topic, concept, or phrase is discussed when you don't know the exact substring; grep is still the tool for an exact regex or a 1–2 character pattern.

Enabling it

The search_workspace tool is off by default — it's registered only when you opt in, so the model isn't shown a tool it can't back:

# ~/.kin/settings.toml  (or a project .kin/settings.toml — it's project-safe)
search_enabled = true

or for a one-off session:

KIN_SEARCH_ENABLED=1 uv run kin

It is project-safe: a local index toggle has no network, egress, or secret surface, so unlike the containment knobs a project file may turn it on. See the search_enabled row in the settings reference for the project-ok/global-only rule this follows.

In the Outpost Dashboard, the same toggle lives in the Model & tuning card (search_enabled, next to enable_thinking) — flip it without touching settings.toml by hand. It only affects sessions started after the change; an already-open terminal needs a restart to pick it up, and the first search after enabling may take a moment while the index builds.

How it works

search_workspace builds a small SQLite FTS5 index (the trigram tokenizer, BM25 ranking) over your workspace's text files — zero new dependencies (it's a standard feature of Python's stdlib sqlite3), no network, no egress.

• Chunked. Files are split into chunks — code/text into line windows, markdown into heading-delimited sections that carry their A > B > C heading path — so a hit points at a tight line range (path:line) and a markdown hit tells you which section it came from.
• Ranked. Results come back best-first by BM25 relevance, not file order.
• Lazy + incremental. The first search builds the index (you'll see a progress note); later searches only re-index files whose mtime/content changed and drop files that were deleted. A build is bounded by a wall-clock budget, so even a huge tree returns promptly (a partial index, with a note).

The index database lives outside your workspace, under ~/.kin/index/ (keyed by the workspace path) — the same discipline session journals use. It is never written into the repo, so it can't be committed or surprise-tracked.

This index is separate from the one behind Memory's per-turn recall — a casual preference must never outrank authoritative repo content, and vice versa, so the two never share a ranking.

Arguments

Argument	Meaning
query	The search text. Must be ≥ 3 characters (the trigram floor — shorter strings have no trigram to match; use grep for those).
path	Optional path-prefix filter, relative to the workspace root (e.g. src/).
kind	Optional chunk-kind filter: markdown (heading sections) or text (code + plain text). Omit to search everything.
limit	Max results (default 10, max 50).

What's indexed (and what isn't)

The crawl reuses grep's discipline and adds a few exclusions, so the index never contains anything the model couldn't already read — and never anything sensitive:

• Excluded: secret files (.env, ~/.ssh, .mcp.json, and the rest of the read-deny list), .gitignored paths, binary files (NUL-byte heuristic), oversized files, and heavy dirs (.git, node_modules, .venv, …). Excluded files appear in neither the index nor the results.
• Trust. Because results are in-workspace content the model already reads freely, they carry the same trust as grep output — they are not wrapped in the untrusted-content framing that web fetches and out-of-workspace @-mentions get.

Relationship to grep

	grep	search_workspace
Match	Exact regex / substring	Ranked full-text (BM25, trigram)
Order	File order	Relevance, best-first
Granularity	Single line	Chunk (line range / heading section)
Min length	1 char	3 chars
Always available	Yes	Opt-in (search_enabled)

Reach for search_workspace when you're searching by meaning/topic and don't know the exact text; reach for grep when you know the exact pattern. See the Filesystem tools section for grep and the rest of the built-in read/write toolset.

Semantic search is a later tier

Today's index is lexical (FTS5). A future tier adds optional vector / embedding / rerank retrieval on top of the same index for true semantic search; it's additive and opt-in, and this page will grow when it lands.