feat: Add LLM improvements and feedback signal API

[csfet9]

Summary

This PR adds several high-value improvements to the Hindsight memory system:

1. Feedback Signal API

• New API endpoint for tracking fact usefulness (POST /feedback)
• Allows agents to signal which retrieved facts were helpful or not
• Enables future improvements to retrieval ranking based on feedback
• Includes database migration, tests, and documentation

2. Gemini 3 Flash Preview Optimizations

• Added support for Gemini 3 Flash Preview model
• Optimized configuration for better performance with this model

3. Empty LLM Response Handling

• Added retry logic when LLM returns empty responses
• Logs finish_reason for debugging
• Exponential backoff between retries
• Prevents failures from transient empty responses

Test plan

• Run existing test suite: cd hindsight-api && uv run pytest tests/
• Test feedback signal API endpoint manually
• Verify Gemini provider works with new optimizations
• Test empty response handling by simulating empty LLM responses

🤖 Generated with Claude Code

[nicoloboschi]

Hey @csfet9 thanks for this big addition!

I've a more general question about this:
isn't the helpfulness related to the recall query and other parameters?

for example, if I ask the bank about "Alice" I might say that Bob facts weren't helpful but if I ask about Bob, that fact is indeed helpful (maybe)

So I think we're missing something that connects the helpfulness to the actual query

[csfet9]

Hey @nicoloboschi, great feedback! You're absolutely right - the helpfulness signal should be tied to the query context.

I've implemented a query-context aware scoring system:

Changes

1. New query_fact_usefulness table - stores usefulness scores per (query_embedding, fact) pair instead of just per fact
2. query field is now required in SignalItem - ensures every signal is tied to the query that triggered the recall
3. Semantic matching for similar queries - uses cosine similarity (threshold 0.85) so "Who is the CEO?" and "Who is the chief executive?" share the same score context
4. Hybrid scoring in recall - when boost_by_usefulness=true:
   - First looks for query-specific scores (similar queries)
   - Falls back to global scores for unseen query patterns
   - Falls back to 0.5 (neutral) for facts without any signals

Example

Fact: "Bob works at TechCorp"

Query "Who works at TechCorp?" → marked helpful → score = 0.65
Query "What's the weather?" → marked not_helpful → score = 0.40

Recall with "Tell me about TechCorp employees" → uses 0.65 (similar to first query)
Recall with "What's today's forecast?" → uses 0.40 (similar to second query)

This way, the same fact can have different usefulness scores depending on the query context.

Currently testing locally - will push once verified.

Want me to adjust anything?

[nicoloboschi]

Hey @nicoloboschi, great feedback! You're absolutely right - the helpfulness signal should be tied to the query context.

I've implemented a query-context aware scoring system:

Changes

1. New query_fact_usefulness table - stores usefulness scores per (query_embedding, fact) pair instead of just per fact
2. query field is now required in SignalItem - ensures every signal is tied to the query that triggered the recall
3. Semantic matching for similar queries - uses cosine similarity (threshold 0.85) so "Who is the CEO?" and "Who is the chief executive?" share the same score context
4. Hybrid scoring in recall - when boost_by_usefulness=true:
   • First looks for query-specific scores (similar queries)
   • Falls back to global scores for unseen query patterns
   • Falls back to 0.5 (neutral) for facts without any signals

Example

Fact: "Bob works at TechCorp"

Query "Who works at TechCorp?" → marked helpful → score = 0.65 Query "What's the weather?" → marked not_helpful → score = 0.40

Recall with "Tell me about TechCorp employees" → uses 0.65 (similar to first query) Recall with "What's today's forecast?" → uses 0.40 (similar to second query)

This way, the same fact can have different usefulness scores depending on the query context.

Currently testing locally - will push once verified.

Want me to adjust anything?

thanks, that looks better!

can you share your use case for this feature and what is the pattern you're building? it looks like you want some human-in-the-loop mechanism and I'd love to hear more about how you intend to use hindsight there

[csfet9]

Thanks, Here's the use case:

I'm building an automatic feedback loop for Claude Code where the system learns from Claude's actual behavior.

How it works

1. Detection - After recall, analyze Claude's response to detect which facts were actually used (semantic similarity, explicit references like "based on context", behavioral signals like file access)
2. Signal - Send used/ignored verdicts back to Hindsight via /signal
3. Learn - Use boost_by_usefulness in future recalls to prioritize facts that worked before

Why query-context matters

A fact like "Bob is a senior engineer" might be helpful for "Who can help with code?" but irrelevant for "What's the deadline?". Without query-context, one "helpful" signal would boost it for ALL queries. The semantic matching ensures similar queries share scores while different query types stay separate.

The human-in-the-loop is mostly implicit - Claude's usage patterns provide the signal automatically, no manual thumbs up/down needed.

[csfet9]

Updates pushed:

Query-Context Aware Scoring (addresses your feedback)

• Made query field required in SignalItem
• New query_fact_usefulness table stores scores per (query_embedding, fact) pair
• Semantic matching (cosine similarity ≥ 0.85) groups similar queries
• Hybrid scoring: query-specific → global fallback → 0.5 neutral
• Updated all docs and examples with required query field
• Added tests for context-aware scoring

Review comment fixes
Gemini 3 thinking level now uses reasoning_effort parameter instead of separate env var
Query field already in examples (part of context-aware scoring commit)

Ready for re-review!