---
name: kindx
description: Search markdown knowledge bases, notes, and documentation using KINDX. Use when users ask to search notes, find documents, or look up information.
license: MIT
compatibility: Requires kindx CLI or MCP server. Install via `npm install -g @ambicuity/kindx`.
metadata:
  author: riteshrana
  version: "2.1.0"
allowed-tools: Bash(kindx:*), mcp__kindx__*
---

# KINDX - Knowledge INDexer

Local search engine for markdown content.

> **Auto-invocation:** As of v2.1.0 kindx tells every MCP-aware agent to call `query` automatically before answering questions that could be informed by your notes. Set `KINDX_AUTO_INVOKE=off` in the server's environment to disable.

## Status

!`kindx status 2>/dev/null || echo "Not installed: npm install -g @ambicuity/kindx"`

## MCP: `query`

```json
{
  "searches": [
    { "type": "lex", "query": "CAP theorem consistency" },
    { "type": "vec", "query": "tradeoff between consistency and availability" }
  ],
  "collections": ["docs"],
  "limit": 10
}
```

### Query Types

| Type | Method | Input |
|------|--------|-------|
| `lex` | BM25 | Keywords — exact terms, names, code |
| `vec` | Vector | Question — natural language |
| `hyde` | Vector | Answer — hypothetical result (50-100 words) |

### Writing Good Queries

**lex (keyword)**
- 2-5 terms, no filler words
- Exact phrase: `"connection pool"` (quoted)
- Exclude terms: `performance -sports` (minus prefix)
- Code identifiers work: `handleError async`

**vec (semantic)**
- Full natural language question
- Be specific: `"how does the rate limiter handle burst traffic"`
- Include context: `"in the payment service, how are refunds processed"`

**hyde (hypothetical document)**
- Write 50-100 words of what the *answer* looks like
- Use the vocabulary you expect in the result

**expand (auto-expand)**
- Use a single-line query (implicit) or `expand: question` on its own line
- Lets the local LLM generate lex/vec/hyde variations
- Do not mix `expand:` with other typed lines — it's either a standalone expand query or a full query document

### Combining Types

| Goal | Approach |
|------|----------|
| Know exact terms | `lex` only |
| Don't know vocabulary | Use a single-line query (implicit `expand:`) or `vec` |
| Best recall | `lex` + `vec` |
| Complex topic | `lex` + `vec` + `hyde` |

First query gets 2x weight in fusion — put your best guess first.

### Lex Query Syntax

| Syntax | Meaning | Example |
|--------|---------|---------|
| `term` | Prefix match | `perf` matches "performance" |
| `"phrase"` | Exact phrase | `"rate limiter"` |
| `-term` | Exclude | `performance -sports` |

Note: `-term` only works in lex queries, not vec/hyde.

### Collection Filtering

```json
{ "collections": ["docs"] }              // Single
{ "collections": ["docs", "notes"] }     // Multiple (OR)
```

Omit to search all collections.

## Other MCP Tools

| Tool | Use |
|------|-----|
| `get` | Retrieve doc by path or `#docid` |
| `multi_get` | Retrieve multiple by glob/list |
| `status` | Collections and health |

## CLI

```bash
kindx query "question"              # Auto-expand + rerank
kindx query $'lex: X\nvec: Y'       # Structured
kindx query $'expand: question'     # Explicit expand
kindx search "keywords"             # BM25 only (no LLM)
kindx get "#abc123"                 # By docid
kindx multi-get "journals/2026-*.md" -l 40  # Batch pull snippets by glob
kindx multi-get notes/foo.md,notes/bar.md   # Comma-separated list, preserves order
```

## HTTP API

```bash
curl -X POST http://localhost:8181/query \
  -H "Content-Type: application/json" \
  -d '{"searches": [{"type": "lex", "query": "test"}]}'
```

## Setup

```bash
npm install -g @ambicuity/kindx
kindx collection add ~/notes --name notes
kindx embed
```