md-search

Semantic search for markdown files. Creates a portable, git-committable vector index using any OpenAI-compatible embedding API.

Why? Find relevant content in documentation, notes, or knowledge bases without exact keyword matching. Results work for both humans (readable output) and AI agents (JSON/JSONL).

Installation

Requires Bun runtime.

# Run directly (no install)
bunx md-search search "your query"

# Install globally
bun add -g md-search

Quick Start

# Set your API key (or use .md-search.local.yaml)
export OPENAI_API_KEY=sk-proj-...

# Index and search - no config file needed
md-search index ./docs
md-search search "how to configure logging"

Project-based setup with config file:

Create .md-search.yaml:

api:
  base_url: http://localhost:11434/v1  # Ollama, or any OpenAI-compatible API
  model: nomic-embed-text
  dimensions: 768
sources:
  docs: ./docs

For API keys, create .md-search.local.yaml (gitignored):

api:
  api_key: sk-...

See CONFIGURATION.md for complete configuration reference including environment variables, credential precedence, and provider-specific setup.

Usage

Index:

md-search index              # Index all sources
md-search index ./docs       # Index specific directory
md-search index --force      # Re-index everything

Search:

md-search search "how to configure logging"
md-search search -k 5 "authentication flow"    # Top 5 results
md-search search -l 10 "database queries"      # -l/--limit alias for -k
md-search search -o json "api endpoints"       # JSON for agents
md-search search --rerank "complex question"   # LLM-based reranking

Output Formats

Text (default):

docs:guides/auth.md:45-62 0.847 # Authentication
Preview of matching content...

JSON: Full result objects for programmatic use (-o json)

JSONL: One result per line for piping (-o jsonl)

Advanced Configuration

Reranking (improves result quality with LLM):

# .md-search.local.yaml
reranker:
  base_url: https://api.openai.com/v1
  model: gpt-4o-mini
  api_key: sk-...

Ignore Patterns (exclude files from indexing):

# .md-search.yaml
ignore_patterns:
  - "_*"      # Drafts (default)
  - ".*"      # Hidden files (default)
  - "archive/*"

Azure OpenAI:

# .md-search.yaml
api:
  provider: azure
  base_url: https://my-resource.openai.azure.com/openai
  deployment: text-embedding-ada-002
  api_version: "2024-02-01"

Migrating from 0.1.x

Version 0.2.0 renames CLI flags for consistency:

| Old Flag | New Flag | Commands | |----------|----------|----------| | -f, --format | -o, --output | search, links, debug, status | | -F, --filter | -f, --filter | search |

The -f flag on the index command (for --force) is unchanged.