Search Boost

Rank source code above tests, mocks and docs by multiplying search scores with path-based factors.

Structural boosting multiplies each search score by factors based on the file path. By default it pushes tests, mocks, generated code and docs down, and gives a small bonus to paths containing /src/, /lib/ or /app/.

Boost is enabled by default and configured under search.boost in .grepai/config.yaml. To demote a directory, append a rule to the existing list:

search:
  boost:
    enabled: true
    penalties:
      # ...existing default rules...
      - pattern: "/examples/"
        factor: 0.5

Changes apply to the next grepai search. No re-indexing is needed.

How It Works

After the similarity search (and hybrid fusion, if enabled), grepai multiplies each result’s score by every rule that matches its path, then re-sorts the results:

• Penalties (factor < 1.0) lower the score.
• Bonuses (factor > 1.0) raise the score.
• Cumulative: when several patterns match, their factors are multiplied together.

Example: pkg/user/handler_test.go matches _test. (×0.5). services/api/tests/auth_test.py matches /tests/ (×0.5) and _test. (×0.5), so its final factor is 0.25.

Boost only reorders the candidates the store returned (2x --limit, or 4x with search.dedup enabled). It does not bring in files that were not among them.

Pattern Matching

Patterns are plain, case-sensitive substring matches on the file path. No globs or regular expressions.

Patterns are matched against the path relative to the project root, written with forward slashes and a leading / (for example /src/auth/handler.go, on every OS). So a pattern that starts with / matches a directory name at any depth, including the top level:

• /tests/ matches tests/auth.py and services/api/tests/auth.py, but not contests/auth.py.
• /src/ matches src/app.ts and packages/web/src/app.ts.
• _test. matches auth_test.go and user_test.py.
• .spec. matches auth.spec.ts and user.spec.js.

Note: in earlier versions, paths were matched without the leading / (and with backslashes on Windows), so patterns like /src/ or /tests/ never matched a top-level directory, and never matched on Windows.

Default Configuration

grepai init writes these rules to .grepai/config.yaml:

search:
  boost:
    enabled: true
    penalties:
      # Test files (multi-language)
      - pattern: "/tests/"
        factor: 0.5
      - pattern: "/test/"
        factor: 0.5
      - pattern: "__tests__"
        factor: 0.5
      - pattern: "_test."
        factor: 0.5
      - pattern: ".test."
        factor: 0.5
      - pattern: ".spec."
        factor: 0.5
      - pattern: "test_"
        factor: 0.5
      # Mocks
      - pattern: "/mocks/"
        factor: 0.4
      - pattern: "/mock/"
        factor: 0.4
      - pattern: ".mock."
        factor: 0.4
      # Fixtures & test data
      - pattern: "/fixtures/"
        factor: 0.4
      - pattern: "/testdata/"
        factor: 0.4
      # Generated code
      - pattern: "/generated/"
        factor: 0.4
      - pattern: ".generated."
        factor: 0.4
      - pattern: ".gen."
        factor: 0.4
      # Documentation
      - pattern: ".md"
        factor: 0.6
      - pattern: "/docs/"
        factor: 0.6
    bonuses:
      # Entry points (multi-language)
      - pattern: "/src/"
        factor: 1.1
      - pattern: "/lib/"
        factor: 1.1
      - pattern: "/app/"
        factor: 1.1

Note: grepai reads boost rules from the config file only. If the search.boost block is missing, boost is off. Copy the block above to restore the defaults.

Default Rules Summary

Because matching is by substring, some defaults are broad: .md also matches .mdx, and test_ also matches names like contest_results.go.

Customization

Add custom patterns

Your penalties and bonuses lists replace the defaults, so keep the default rules you still want and append yours:

search:
  boost:
    enabled: true
    penalties:
      # ...default rules you want to keep...
      - pattern: "/examples/"
        factor: 0.5
      - pattern: "/third_party/"
        factor: 0.3
    bonuses:
      - pattern: "/core/"
        factor: 1.2

Disable boosting

search:
  boost:
    enabled: false

Workspace searches

grepai search --workspace (and the MCP workspace search) always applies the built-in default rules. It ignores the search.boost block of each project.