mdvdb search

Search across indexed markdown files using semantic (vector), lexical (BM25), hybrid (RRF fusion), or edge-based search. Returns ranked results with chunk content, file metadata, and optional graph context.

Usage

mdvdb search [OPTIONS] <QUERY>

Arguments

Options

Option Details

--limit, -l

Sets the maximum number of results returned. The default is controlled by MDVDB_SEARCH_DEFAULT_LIMIT (default: 10). See Configuration.

--min-score

Filters out results below this similarity threshold. Score interpretation varies by mode:

• Semantic: cosine similarity (absolute, 0.0-1.0)
• Lexical: BM25 score normalized via saturation score / (score + k)
• Hybrid: RRF score normalized by theoretical maximum

The default is controlled by MDVDB_SEARCH_MIN_SCORE (default: 0.0). See Configuration.

--filter, -f

Metadata filter expressions in KEY=VALUE format. The CLI exposes exact equality on top-level frontmatter fields; it does not parse range, existence, OR, or arbitrary SQL predicates. Repeat the flag to apply multiple filters with AND logic.

Auto-type detection: The value is automatically parsed as:

If the frontmatter field is an array, the filter checks whether the array contains the value. For example, --filter tags=rust matches a document with tags: [rust, cli, tools].

Filters use effective frontmatter, so successfully materialized Formula, Lookup, and Rollup fields are queryable. Link-shaped relation values are syntax-normalized: for example, client=clients/acme, client=clients/acme.md, and client=[[clients/acme]] can all match client: "[[clients/acme|Acme]]". This normalization is syntactic and does not resolve the target file.

# Single filter
mdvdb search "query" --filter status=published

# Multiple filters (AND logic)
mdvdb search "query" -f status=published -f draft=false -f year=2024

--path

Restricts results to files whose path starts with the given prefix. Useful for scoping searches to a subdirectory.

# Only search within the docs/ directory
mdvdb search "authentication" --path docs/

# Only search within a specific project area
mdvdb search "error handling" --path src/api/

--hops

Sets the link-hop depth for graph-aware boosting. When enabled, results that are linked to or from other top results receive a score boost.

• Range: 1 to 3
• Requires: --boost-links must also be set
• Default: 1 (controlled by MDVDB_SEARCH_BOOST_HOPS)

# Boost results linked within 2 hops of top matches
mdvdb search "API design" --boost-links --hops 2

--expand

Controls graph context expansion depth. When set to a value greater than 0, the response includes additional chunks from files linked to the search results, providing supplementary context.

• Range: 0 to 3 (0 disables expansion)
• Default: 0 (controlled by MDVDB_SEARCH_EXPAND_GRAPH)

# Include chunks from directly linked files
mdvdb search "authentication" --expand 1

# Include chunks up to 3 hops away
mdvdb search "authentication" --expand 3

--populate

Resolves whole-value frontmatter relations on ranked result files. Each relation includes its raw value, resolved path, existence, title, and target frontmatter. Population is depth one: target frontmatter is returned as stored and is not recursively populated.

mdvdb search "paid invoices" --filter status=paid --populate --json

Only ranked results are populated. Supplementary graph_context entries are unchanged.

Conflicting Options

Certain options are mutually exclusive and cannot be used together:

Dependency Requirements

Search Modes

The search mode determines which retrieval signals are used. The default mode is hybrid (controlled by MDVDB_SEARCH_MODE).

For detailed explanations and diagrams, see Search Modes.

Time Decay

When enabled, time decay applies an exponential penalty to older files, favoring recently modified content. The formula is:

adjusted_score = score * 2^(-age_in_days / half_life_days)

• --decay / --no-decay: Override the config default (MDVDB_SEARCH_DECAY, default: false)
• --decay-half-life: Override the half-life (MDVDB_SEARCH_DECAY_HALF_LIFE, default: 90.0 days)
• --decay-exclude: Comma-separated path prefixes excluded from decay (e.g., docs/reference,docs/api)
• --decay-include: Comma-separated path prefixes where decay applies (whitelist mode)

Exclude takes precedence over include. For detailed explanations, see Time Decay.

Global Options

These options apply to all commands. See Commands Index for details.

Examples

Basic search

# Simple semantic search (uses default hybrid mode)
mdvdb search "how to authenticate users"

# Limit to 5 results with minimum score
mdvdb search "error handling" --limit 5 --min-score 0.3

Search with filters

# Filter by frontmatter field
mdvdb search "deployment" --filter status=published

# Multiple filters (AND logic)
mdvdb search "API endpoints" -f category=backend -f draft=false

# Filter with numeric value
mdvdb search "release notes" --filter year=2024

# Filter a computed field and populate relation context
mdvdb search "large paid invoices" -f status=paid -f total=240 --populate --json

Search modes

# Semantic only (meaning-based, no keyword matching)
mdvdb search "things that are similar to authentication" --semantic

# Lexical only (exact keyword matching, no API call)
mdvdb search "AuthenticationError" --lexical

# Explicit mode flag
mdvdb search "user management" --mode=hybrid

# Edge search (find relationships between documents)
mdvdb search "references to auth module" --edge-search

Path-scoped search

# Only search within docs/
mdvdb search "configuration" --path docs/

# Search within a specific directory
mdvdb search "error types" --path src/

Link boosting and graph expansion

# Boost results that are linked to/from top matches
mdvdb search "architecture" --boost-links

# Multi-hop link boosting (2 hops)
mdvdb search "architecture" --boost-links --hops 2

# Include context from linked files
mdvdb search "authentication" --expand 1

# Combine boosting and expansion
mdvdb search "API design" --boost-links --hops 2 --expand 2

Time decay

# Favor recently modified files
mdvdb search "release notes" --decay

# Custom half-life (30 days)
mdvdb search "release notes" --decay --decay-half-life 30

# Exclude reference docs from decay
mdvdb search "best practices" --decay --decay-exclude docs/reference,docs/api

# Apply decay only to blog posts
mdvdb search "updates" --decay --decay-include blog/

JSON output

# JSON output for programmatic consumption
mdvdb search "authentication" --json

# JSON with timing information (requires -v)
mdvdb search "authentication" --json -v

# Pipe to jq for processing
mdvdb search "error handling" --json | jq '.results[].file.path'

JSON Output

When --json is used, the output is a SearchOutput object. This example includes fields emitted by --populate:

{
  "results": [
    {
      "score": 0.87,
      "chunk": {
        "chunk_id": "docs/auth.md#2",
        "heading_hierarchy": ["Authentication", "OAuth2 Flow"],
        "content": "The OAuth2 flow begins with...",
        "start_line": 15,
        "end_line": 42
      },
      "file": {
        "path": "docs/auth.md",
        "frontmatter": {
          "title": "Authentication Guide",
          "tags": ["auth", "security"],
          "owner": "[[people/alex]]",
          "priority": 3
        },
        "computed_fields": {"priority": 3},
        "computed_field_errors": {},
        "file_size": 4096,
        "path_components": ["docs", "auth.md"],
        "modified_at": 1710000000,
        "relations": {
          "owner": [
            {
              "raw": "[[people/alex]]",
              "path": "people/alex.md",
              "exists": true,
              "title": "Alex",
              "frontmatter": {"title": "Alex"}
            }
          ]
        }
      }
    }
  ],
  "query": "authentication",
  "total_results": 1,
  "mode": "hybrid"
}

SearchOutput Fields

SearchResult Fields

SearchTimings Fields

Included when -v (verbose) flag is used:

GraphContextItem Fields

Included when --expand is set to a value greater than 0:

EdgeSearchResult Fields

Included when using --edge-search or --mode=edge:

Configuration

The following shell overrides affect search behavior. Equivalent values can be set in project .markdownvdb/config.yaml or user ~/.mdvdb/config.yaml. See Configuration for the complete YAML keys and resolution order.

Related Commands

• mdvdb ingest — Index files before searching
• mdvdb status — Check index health and counts
• mdvdb links — Explore the link graph for a file
• mdvdb edges — View semantic edges between documents
• mdvdb collection — Query frontmatter rows with the same equality-filter semantics
• mdvdb get — Inspect one result and its reverse relations
• mdvdb config — View resolved search configuration

See Also

• Search Modes — Detailed explanation of hybrid, semantic, lexical, and edge search
• Time Decay — How time-based scoring works
• Link Graph — Link boosting and graph expansion explained
• JSON Output Reference — Complete JSON schema reference
• Configuration — All environment variables and config options