[BUG] Retrieve tool incorrectly filters out relevant results when using AWS Aurora PostgreSQL as backing vector database due to cosine distance being used

[starJammer]

Checks

• I have updated to the lastest minor and patch version of Strands
• I have checked the documentation and this is not expected behavior
• I have searched ./issues and there are no duplicates of my issue

Strands Version

1.22.0

Tools Package Version

0.2.19

Tools used

1. Retrieve

Python Version

3.12.11

Operating System

Mac OS X Tahoe 26.3.1

Installation Method

other

Steps to Reproduce

1. Configure an Amazon Bedrock Knowledge Base using AWS Aurora PostgreSQL as the vector store.
2. Ensure the vector store is configured to use the pg_vector so the cosine distance operator (<=>) is supported.
3. Initialize the retrieve tool using strands-agents=1.22.0 and strands-agents-tools=0.2.19.
4. Perform a retrieval query with a high-relevance expected match and set a score threshold (e.g., score=0.4):

results = agent.tool.retrieve(
    text="<query-with-known-exact-matches>",
    score=0.4
)

5. Observe that the exact or highly relevant matches (which have scores < 0.4 due to being distances) are filtered out, while poor matches (distances >= 0.4) are returned.

Expected Behavior

The retrieve tool should either automatically detect the scoring metric being used by the underlying vector database, or provide a parameter (e.g., score_metric="distance" | "similarity") to determine whether it should filter using <= or >=.

Actual Behavior

The tool strictly applies score >= min_score, incorrectly dropping highly relevant documents when the Bedrock Knowledge Base returns distance metrics instead of similarity metrics.

Additional Context

The retrieve tool incorrectly filters out the most relevant search results when using Amazon Bedrock Knowledge Bases backed by an Aurora PostgreSQL database using the <=> (cosine distance) operator.

When performing a semantic search in PostgreSQL using pgvector, the <=> operator returns the cosine distance (1 - cosine_similarity). For this metric, a smaller score indicates a closer match (0 is an exact match).

However, the filter_results_by_score function in retrieve.py assumes that a higher score indicates higher relevance. It uses a greater-than-or-equal-to comparison (>= min_score), which effectively drops the most relevant results (scores close to 0) and only returns the least relevant results (scores above the threshold).

Possible Solution

No response

Related Issues

No response

[kaiisfree]

Root Cause Analysis

Location: src/strands_tools/retrieve.py, function filter_results_by_score:

return [result for result in results if result.get("score", 0.0) >= min_score]

Problem: This assumes the score field from Bedrock Knowledge Base retrieve API is always a similarity metric (higher = more relevant). When the backing vector store is Aurora PostgreSQL using pgvector's <=> (cosine distance) operator, the score is a distance metric where lower = more relevant (0 = exact match, 1 = orthogonal).

The >= min_score comparison inverts the filter:

• A perfect match with distance 0.05 is dropped (0.05 >= 0.4 is false)
• A poor match with distance 0.85 is kept (0.85 >= 0.4 is true)

The TOOL_SPEC reinforces this assumption with "Relevance scoring (0.0-1.0)" and minimum: 0.0, maximum: 1.0 constraints.

This is the same bug class as mem0ai/mem0#4453 — threshold filtering inverted for distance-based vector stores because the filter assumes similarity semantics universally.

Suggested Fix

Pragmatic approach: Add a score_metric parameter ("similarity" | "distance", default "similarity") and invert the comparison when distance:

def filter_results_by_score(results, min_score, score_metric="similarity"):
    if score_metric == "distance":
        return [r for r in results if r.get("score", float('inf')) <= min_score]
    return [r for r in results if r.get("score", 0.0) >= min_score]

This is backward-compatible (default stays "similarity") and gives users immediate control. The alternative — normalizing distance to similarity at source via score = max(0.0, 1.0 - distance) — is cleaner long-term but changes score semantics for existing users.

Additional observations

1. The memory.py tool has a similar retrieve path and likely shares this issue.
2. Tests in test_retrieve.py only use similarity-style scores (0.3, 0.7, 0.9). A distance-style test case would catch this class of bug.
3. The score parameter schema constrains to [0.0, 1.0], but cosine distance ranges [0, 2] — needs relaxing for distance mode.

Happy to submit a PR with the fix if this approach looks right.