feat(recall): add lightweight retrieval profile / intent hint for query shape

[Sapientropic]

Feature request

Add a lightweight request-level retrieval profile / intent hint for recall, so clients can steer retrieval toward different memory shapes without rebuilding their own scorer layer.

Problem

I ran into a real product issue with a coding-agent client that uses a shared common bank for two different kinds of memory:

1. concise cross-project workflow / default-entrypoint rules
2. reusable technical procedures and troubleshooting notes

For workflow-contract style queries (for example: "which default entrypoint is primary, and which memory / benchmark paths are auxiliary?"), the relevant concise curated rule already existed in the bank, but default recall still surfaced older technical procedures first.

The result was:

• the memory was present
• metadata was present
• but the user-facing recall still felt wrong
• clients are pushed toward local keyword heuristics or post-ranking layers

This feels adjacent to the work already done in:

• feat(reflect): make source facts in search_observations configurable #688 (search_observations configurability)
• feat: add max_observations_per_scope bank config #729 (max_observations_per_scope)
• fix: return metadata in recall responses #680 / fix(http): recall endpoint drops metadata in response #803 (metadata in recall responses)
• feat: expose document_metadata in API and control plane #798 (document_metadata in API)

Those changes all move in a good direction: make retrieval surfaces and metadata more controllable, instead of forcing clients to guess.

Why this matters

In practice, one bank can contain multiple useful retrieval shapes:

• "default operating rule / canonical guidance"
• "technical lesson / procedure"
• "observation-heavy exploratory context"

A single generic recall mode is often not enough.

When the query is asking for a stable rule or canonical workflow guidance, surfacing technical procedures first is technically defensible but product-wrong. Clients then end up adding brittle query rewriting or custom rerank logic outside Hindsight.

Local evidence

I locally fixed this by adding a very thin client-side workaround:

• detect a narrow class of workflow / contract queries
• keep the existing hybrid recall path
• prepend 1 curated/common rule ahead of raw/common procedures
• do not change technical troubleshooting queries

That immediately improved real recall behavior:

• contract / default-entrypoint queries started surfacing the concise common rule first
• technical queries still surfaced technical procedures first

But this is exactly the kind of behavior I would rather express as a Hindsight retrieval hint than as client-specific keyword heuristics.

Proposed direction

Add an optional request-level hint on recall, something in the spirit of:

• retrieval_profile
• or intent_hint
• or query_profile

Example values could be intentionally small / generic:

• default
• formal_rules
• technical_lessons

I am not proposing a new heavy scoring system.

The server could keep the current hybrid search / rerank logic and only use the hint to make small retrieval-policy adjustments, for example:

• prefer formal / curated results earlier when formal_rules
• reduce or disable observation-heavy results for that request
• keep metadata / document_metadata available so clients can still explain what was returned

Non-goals

• not asking for client-specific heuristics in Hindsight
• not asking for a large taxonomy of profiles
• not asking for a second explanation / attribution layer
• not asking to replace existing bank config knobs

Why this seems like a good fit for Hindsight

This seems consistent with the recent direction of the project:

• expose more retrieval controls instead of hardcoding one behavior
• preserve metadata so clients can make better product decisions
• avoid pushing every integration toward bespoke recall patching

Questions

1. Would a request-level retrieval_profile fit the project direction better than adding more bank-level defaults?
2. If yes, would you prefer it to only control observation/formal bias, or also light reranking behavior?
3. If not, is there already a preferred upstream way to express "for this recall, bias toward stable formal guidance rather than technical procedures"?