Feature Request: Support date-based filtering in `search()`

[dkhokhlov]

GitHub Issue Draft

Summary

Currently, search filtering in Indexer.search() and Indexer.findSimilar() supports fileType, directory, chunkType, contextLines, filterByBranch, and metadataOnly , but there is no way to filter results by file modification date or index date.

As predicate, not rerank.

Motivation

Users may want to restrict search/find_similar results to recently modified files (e.g. "only show code changed in the last week") to focus on active areas of a codebase.

Additional Context

Indexing already tracks per-file hashes (fileHashCache) for incremental re-indexing, but this is used only for change detection, not exposed as a queryable timestamp — new tracking would likely be needed to support this feature.

TZ: assumed the same between server and client. Provide override option.

[Helweg]

Thanks for the request. The core capability is already available as blameSince: it is a hard search predicate over each chunk’s last Git-blame commit timestamp, rather than a reranking preference.

For example, to restrict results to code last changed on or after 2026-08-08:

{ "blameSince": "2026-08-08" }

It is available on codebase_search and codebase_peek across MCP, Pi, and OpenCode. The integration coverage creates date-stamped commits and verifies that blameSince returns only chunks after the requested date.

We do not currently expose an upper bound (blameUntil) or date filters on find_similar. If your use case specifically needs a date range or find_similar support, please let us know and we can scope that narrower enhancement. Otherwise, this existing filter should cover “only show code changed in the last week.”

[dkhokhlov]

Thanks. blameSince is the right primitive and it's a predicate (boolean), not a rerank — that part is covered. I'll drop the per-chunk lastModified idea. (The original "blame" FR was mine.)

The remaining issue is when the predicate runs, and it's more than recall. blameSince is applied after retrieval, before fusion/rerank/community-boost: VectorStore.search(queryVector, limit) takes no filter (src/native/vector-store.ts:38), so candidates come from a fixed global over-fetch (maxResults × 4/×12, ×2 for find_similar), then matchesHardSearchFilters drops the out-of-scope ones (src/indexer/index.ts:4767). With a narrow date window two things break:

• recall: in-scope chunks below the over-fetch cutoff are never returned, so results can fall short of limit;
• ranking quality: fusion (rankHybridResults), API rerank, and community boost all run on the post-filtered set, so a selective window starves those stages and degrades the order of even the surviving in-scope chunks.

Note the branch prefilter has the same shape: searchCandidatesWithBranchPrefilter also post-filters store.search results and only adds an iterative over-fetch loop — it does not push into the vector index either. So generalizing that loop would patch recall, not the starvation.

The ask: push the date predicate into retrieval so the candidate pool is in-scope by construction — e.g. extend VectorStore.search to accept an in-scope ID set from a SQLite prefilter on blameCommittedAt (or filtered-ANN), add blameUntil for a range, and expose both on find_similar. That makes fusion/rerank/boost operate on a full in-scope pool and removes the global-cutoff recall bound. The branch loop is a cheaper recall-only fallback if retrieval-level scoping is too costly, but it does not solve the ranking-quality part.

It is tempting to ask for a temporal graph on top of this, but that is too much for now...

[Helweg]

You're right. I conflated a correct post-retrieval predicate with retrieval-level scoping. The current candidate cap means a narrow temporal scope can underfill the requested limit and starve hybrid fusion, reranking, and community ranking before those stages run.

That makes this a real retrieval-quality feature, not merely a discoverability issue. The next step should be a small design/benchmark spike to choose a filtered-ANN approach that preserves an in-scope candidate pool, rather than only generalizing the branch over-fetch loop. The scoped work should include blameUntil and find_similar, with acceptance coverage for narrow windows where enough in-scope matches exist to fill limit and where scoped ranking remains stable.

Thanks for the precise analysis.

[Helweg]

Feasibility update: the pinned native Usearch 2.23.0 dependency exposes Index::filtered_search(query, count, predicate), with the predicate applied during graph traversal. Our vector store already owns the stable Usearch-ID ↔ chunk-ID mapping, so an allowed chunk-ID set from SQLite can be translated into an in-process Usearch-key predicate without changing persisted vector data.

The design spike should therefore compare this path with the current post-filter behavior, rather than build a temporary subindex. The intended boundary is:

1. SQLite resolves the date range (blameSince/blameUntil) to allowed chunk IDs, intersected with branch scope where applicable.
2. Vector retrieval uses Usearch's traversal-time predicate over those IDs.
3. Keyword retrieval receives the same scope before hybrid fusion.
4. Fusion, external reranking, community boost, and find_similar consume that in-scope pool.

Before landing it, benchmarks should cover sparse and wide date windows, no matching chunks, unblamed chunks, branch-plus-date intersection, enough scoped chunks to fill limit, find_similar, and the latency/memory cost of the allowed-ID set. This is feasible, but it needs those quality and performance gates rather than a blind API extension.