Semantic Search & Code Intelligence

If you haven't already, enable semantic search during init:

knowns init
# → "Enable semantic search?" → y
# → "Select model:" → gte-small (recommended, ~50MB)

Or enable on an existing project:

knowns config set search.semantic.enabled true
knowns model download gte-small
knowns search --reindex

This is where it gets interesting. You don't need exact keywords:

$ knowns search "how do we handle authentication errors"

DOC: patterns/auth (94%)
Section: ## Error Handling
Matched by: semantic

#42 [done] (89%)
Implement JWT error middleware
Matched by: semantic, keyword

MEMORY: "Auth errors return 401 with error code" (85%)
Matched by: semantic

Notice: the query says "authentication errors" but it finds "JWT error middleware" and "Auth errors" — because it understands meaning, not just words.

Search modes

# Hybrid (semantic + keyword) — default, best for most cases
knowns search "handle auth errors"

# Keyword only — when you know the exact term
knowns search "bcrypt" --keyword

# Filter by type
knowns search "api design" --type doc
knowns search "login bug" --type task
knowns search "token rotation" --type memory

Semantic search covers docs, tasks, and memory. For code-level intelligence, you need to build the code index first:

# Build the code index (AST-based) — required before any code search
knowns code ingest

After the initial ingest, keep it fresh while you work:

knowns code watch

This indexes functions, classes, methods, interfaces, and their relationships across Go, TypeScript, JavaScript, and Python files.

Find code by what it does, not where it lives:

$ knowns code search "oauth login handler"

src/routes/auth.ts
→ loginHandler (function, line 42)
→ Calls: validateCredentials, generateToken
→ Imported by: src/app.ts

src/middleware/oauth.ts
→ oauthCallback (function, line 15)
→ Calls: exchangeCode, createSession

Inspect symbols in a scope

# All symbols in a directory
knowns code symbols --path src/auth/

# Filter by kind
knowns code symbols --kind function
knowns code symbols --kind class

$ knowns code symbols --path src/auth/

src/auth/login.ts
├── loginHandler (function)
├── validateEmail (function)
└── LoginRequest (interface)

src/auth/middleware.ts
├── authGuard (function)
└── extractToken (function)

Understand how code connects:

# What does this file import?
knowns code deps --type imports

# What calls what?
knowns code deps --type calls

# Full dependency graph
knowns code deps

$ knowns code deps --type imports

src/routes/auth.ts
→ imports: src/services/auth-service.ts
→ imports: src/middleware/validate.ts
→ imports: src/utils/jwt.ts

src/services/auth-service.ts
→ imports: src/repositories/user-repo.ts
→ imports: src/utils/bcrypt.ts

This is powerful for understanding unfamiliar codebases — trace from an endpoint down to the database layer in seconds.

When MCP is connected, your AI assistant uses these tools automatically:

You: How does our auth middleware work?

AI:  [Calls search({ action: "search", query: "auth middleware" })]
   [Calls code({ action: "search", query: "auth middleware" })]
   [Calls code({ action: "deps", type: "imports" })]

   Your auth middleware is in src/middleware/auth.ts:
   - Extracts JWT from Authorization header
   - Validates token using src/utils/jwt.ts
   - Attaches user to request context
   - Returns 401 if token is invalid or expired

   It's imported by 12 route files and depends on
   the jwt utility and user repository.

The AI combines semantic search (docs, memory) with code intelligence (symbols, deps) to give you a complete answer.