@onigetoc/mdsearch

mdsearch - Fast full-text search for Markdown knowledge bases

Local full-text search CLI for Markdown knowledge bases, Obsidian vaults, and note collections. Powered by MiniSearch, with automatic indexing, fuzzy search, contextual snippets with line numbers, and LLM-ready output.

LLM-ready workflows

mdsearch helps AI tools and LLM workflows retrieve relevant context from Markdown knowledge bases. Search results are available in structured formats designed for AI agents, automation, and context retrieval.

For maximum token efficiency and streamlined context retrieval, we recommend using the dedicated mdsearch skill which provides automated, ready-to-use workflows for your LLM agents:

https://github.com/onigetoc/mdsearch-skill

Installation

Global installation (recommended)

npm install -g @onigetoc/mdsearch

After global install, use mdsearch directly (no npx):

mdsearch "<query>"              # search current directory
mdsearch "<query>" <folder>     # search a specific folder

Run without installation (npx)

npx @onigetoc/mdsearch "<query>" [<folder>]

Folder defaults to the current directory if omitted. The index is auto-built on first run (cache in .mdsearch/).

Examples

# SIMPLE
mdsearch "karpathy llm wiki"                               # current dir, fuzzy=0.2 (default)
mdsearch "karpathy llm wiki" notes-test                    # specific folder
mdsearch "term" --no-fuzzy                                 # exact only
mdsearch "term" --fuzzy 0.4                                # wider fuzzy

# BOOST
mdsearch "term"                                            # boost: title=3, headings=2, text=1
mdsearch "term" --boost-title 5 --boost-headings 3 --boost-text 1

# CONTEXT / LIMIT
mdsearch "term" --limit 5
mdsearch "term" --context 0                                # no snippet
mdsearch "term" --context 4

# OUTPUT FORMAT
mdsearch "term"                                            # human-readable
mdsearch "term" --json                                     # JSON with normalized scores + line
mdsearch "term" --context 4 --llm-context                  # compact for LLM prompts

# PREFIX, PHRASE & AND
mdsearch "minis" --prefix
mdsearch "karpathy llm" --phrase                           # exact phrase (sequence of terms)
mdsearch "karpathy llm" --and                              # require all terms (default: OR)

# CACHE / INDEX
mdindex ~/my-notes                                         # pre-build index
mdindex ~/my-notes --cache-dir .mycache
mdsearch "term" --reindex                                  # force rebuild
mdsearch "term" ~/my-notes --cache-dir .mycache

# VERSION / HELP / LIST
mdsearch --version
mdsearch --help
mdsearch --list                                            # list indexed files (auto-build if missing)
mdsearch --list --reindex                                  # force re-index before listing

Local dev test only

node src/search-md.mjs "<query>"          # test without installing

Options

Flag	Type	Default	Description
--no-fuzzy	boolean	false	Disable fuzzy matching (exact search only)
--prefix	boolean	false	Enable prefix search (match term prefixes)
--phrase	boolean	false	Exact phrase search (sequence of terms in order)
--and	boolean	false	Require all terms (default is OR — any term matches)
--boost-title	number	3	Weight multiplier for matches in document title
--boost-headings	number	2	Weight multiplier for matches in headings
--boost-text	number	1	Weight multiplier for matches in body text
--limit	number	10	Maximum number of results to return
--context	number	2	Lines of context before/after match (0 = snippet disabled)
--json	boolean	false	Output results as JSON
--llm-context	boolean	false	Compact LLM-friendly output format
--reindex	boolean	false	Force rebuild the search index
--cache-dir	string	.mdsearch	Custom cache directory name
--list	boolean	false	List all indexed files
--version	boolean	false	Show version number
--help	boolean	false	Show help message

Cache structure

.mdsearch/ contains:

• index.json - serialized MiniSearch index
• meta.json - folder signature (file count + max mtime), id → absolute path mapping

If the signature changes (file added/removed/modified), search-md.mjs detects it and re-indexes automatically.

Output formats

All formats include line numbers and normalized scores (0.00 - 1.00).

Mode	Example
Terminal	line 42: → matching content with highlighted match line
JSON	{ "path": "...", "line": 42, "score": 0.92, "snippet": "..." }
LLM context	Confidence: 0.92 for each result, clean body without markers