use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::time::{Duration, Instant};
use axum::Json;
use axum::extract::State;
use axum::http::StatusCode;
use axum::response::IntoResponse;
use chrono::Utc;
use second_brain_core::query::{QueryEngine, QueryFilters, QueryRequest};
use second_brain_core::retrieval::{Candidates, ProjectScope, RerankScorer, Retriever, blend};
use second_brain_core::schema::Memory;
use second_brain_core::sqlite_store::{ReadDeadline, SqliteStore};
use serde::{Deserialize, Serialize};
use uuid::Uuid;
use super::project_names::refuse_unknown_project;
use super::raw_answer::{self, HotOutcome, RawPassageResponse, RawQuery};
use super::rerank_budget::{Budgeted, TimedRerank, doc_chars_for, embed_query, tunables_for};
use super::{MemoryResponse, bad_request, internal_error, parse_memory_type, to_response};
use crate::AppState;
use crate::value_metrics::{RecallEvent, RecallVerdict};
const DEFAULT_RECALL_LIMIT: usize = 10;
const MAX_RECALL_LIMIT: usize = 100;
#[derive(Deserialize)]
pub(super) struct RecallRequest {
query: String,
limit: Option<usize>,
source: Option<String>,
memory_type: Option<String>,
project: Option<String>,
current_project: Option<String>,
#[serde(default)]
all_projects: bool,
record_access: Option<bool>,
exclude_session: Option<String>,
session: Option<String>,
budget_ms: Option<u64>,
rerank_top: Option<usize>,
rerank_doc_chars: Option<usize>,
project_pass: Option<bool>,
}
#[derive(Serialize)]
struct RecallResponse {
memories: Vec<MemoryResponse>,
#[serde(skip_serializing_if = "Option::is_none")]
degraded: Option<&'static str>,
#[serde(skip_serializing_if = "Option::is_none")]
scope: Option<&'static str>,
#[serde(skip_serializing_if = "Option::is_none")]
abstain_bar: Option<f32>,
#[serde(skip_serializing_if = "Vec::is_empty")]
raw: Vec<RawPassageResponse>,
}
struct RecallOutcome {
memories: Vec<(Memory, Option<f32>, Option<f32>)>,
degraded: Option<&'static str>,
scope: Option<&'static str>,
abstain_bar: Option<f32>,
raw: Vec<RawPassageResponse>,
}
const SAME_SESSION_HEADROOM: usize = 20;
fn without_session(
mut pool: Candidates,
sqlite: &SqliteStore,
session: Option<&str>,
) -> anyhow::Result<Candidates> {
let Some(session) = session else {
return Ok(pool);
};
let ids: Vec<Uuid> = pool
.dense
.iter()
.chain(&pool.lexical)
.map(|(id, _)| *id)
.collect();
let excluded = sqlite.memories_from_session(&ids, session)?;
pool.dense.retain(|(id, _)| !excluded.contains(id));
pool.lexical.retain(|(id, _)| !excluded.contains(id));
pool.best_chunk.retain(|id, _| !excluded.contains(id));
Ok(pool)
}
fn drop_session<T>(
items: &mut Vec<T>,
id: impl Fn(&T) -> Uuid,
sqlite: &SqliteStore,
session: Option<&str>,
) -> anyhow::Result<()> {
let Some(session) = session else {
return Ok(());
};
let ids: Vec<Uuid> = items.iter().map(&id).collect();
let excluded = sqlite.memories_from_session(&ids, session)?;
items.retain(|item| !excluded.contains(&id(item)));
Ok(())
}
fn applied_bar(abstained: bool, reranked: bool) -> Option<f32> {
(abstained && reranked).then_some(blend::ABSTAIN_RERANK_BAR)
}
fn recall_event(
session: Option<String>,
shown: &[(Uuid, Option<f32>)],
raw: &[Option<Uuid>],
abstain_bar: Option<f32>,
has_reranker: bool,
shows_only_cleared: bool,
degraded: bool,
) -> RecallEvent {
if degraded {
let memory_ids = if shows_only_cleared {
Vec::new()
} else {
shown.iter().map(|(id, _)| *id).collect()
};
return RecallEvent {
session,
verdict: RecallVerdict::Unjudged,
memory_ids,
};
}
let (verdict, memory_ids) = if shown.is_empty() {
if !raw.is_empty() {
(RecallVerdict::Hit, raw.iter().flatten().copied().collect())
} else if abstain_bar.is_none() && has_reranker {
(RecallVerdict::Unjudged, Vec::new())
} else {
(RecallVerdict::Empty, Vec::new())
}
} else if let Some(bar) = abstain_bar {
let cleared: Vec<Uuid> = shown
.iter()
.filter(|(_, relevance)| relevance.is_some_and(|r| r >= bar))
.map(|(id, _)| *id)
.collect();
let verdict = if cleared.is_empty() {
RecallVerdict::LowScore
} else {
RecallVerdict::Hit
};
if shows_only_cleared {
(verdict, cleared)
} else {
(verdict, shown.iter().map(|(id, _)| *id).collect())
}
} else {
let all = shown.iter().map(|(id, _)| *id).collect();
if shows_only_cleared {
(RecallVerdict::Unjudged, Vec::new())
} else if has_reranker {
(RecallVerdict::Unjudged, all)
} else {
(RecallVerdict::Hit, all)
}
};
RecallEvent {
session,
verdict,
memory_ids,
}
}
fn scope_name(scope: ProjectScope) -> &'static str {
match scope {
ProjectScope::Project => "project",
ProjectScope::OtherProjects => "other-projects",
}
}
static RECALLS_IN_FLIGHT: AtomicUsize = AtomicUsize::new(0);
struct InFlight(&'static AtomicUsize);
impl InFlight {
fn enter(counter: &'static AtomicUsize) -> Self {
counter.fetch_add(1, Ordering::SeqCst);
InFlight(counter)
}
}
impl Drop for InFlight {
fn drop(&mut self) {
self.0.fetch_sub(1, Ordering::SeqCst);
}
}
pub(super) fn recalls_in_flight() -> usize {
RECALLS_IN_FLIGHT.load(Ordering::SeqCst)
}
pub(super) async fn recall(
State(state): State<Arc<AppState>>,
Json(req): Json<RecallRequest>,
) -> impl IntoResponse {
let deadline = req
.budget_ms
.map(|ms| Instant::now() + Duration::from_millis(ms));
let limit = req.limit.unwrap_or(DEFAULT_RECALL_LIMIT);
if !(1..=MAX_RECALL_LIMIT).contains(&limit) {
return bad_request(format!(
"limit must be between 1 and {MAX_RECALL_LIMIT}, got {limit}"
));
}
let session_named = |session: Option<&str>| {
session
.map(str::trim)
.filter(|s| !s.is_empty())
.map(str::to_string)
};
let exclude_session = session_named(req.exclude_session.as_deref());
let shows_only_cleared = req.budget_ms.is_some();
let caller_session = session_named(req.session.as_deref()).or_else(|| exclude_session.clone());
let fetch_limit = match exclude_session {
Some(_) => (limit + SAME_SESSION_HEADROOM).min(MAX_RECALL_LIMIT),
None => limit,
};
let query_text = req.query.clone();
let source_filter = req.source.clone();
let type_filter = match req.memory_type.as_deref().map(parse_memory_type) {
None => None,
Some(Ok(t)) => Some(t),
Some(Err(message)) => return bad_request(message),
};
if req.project.is_some() && req.all_projects {
return bad_request("pass project or all_projects, not both");
}
let project_filter = req.project.clone();
let current_project = req
.current_project
.clone()
.filter(|_| req.project.is_none() && !req.all_projects);
let store = state.store.clone();
let sqlite = state.sqlite.clone();
let indexes = state.indexes.clone();
let raw_index = state.raw_index.clone();
let archive = state.archive.clone();
let reranker = state.reranker.clone();
let tunables = match tunables_for(state.tunables, req.rerank_top) {
Ok(tunables) => tunables,
Err(message) => return bad_request(message),
};
let doc_chars = match doc_chars_for(req.rerank_doc_chars) {
Ok(doc_chars) => doc_chars,
Err(message) => return bad_request(message),
};
let project_pass = req.project_pass.unwrap_or(true);
let embedder = state.embedder.clone();
let gate = state.gate.clone();
let accessed = store.clone();
let record_access = req.record_access.unwrap_or(true);
let record_accesses = move |ids: &[Uuid]| {
if !record_access {
return Ok(());
}
match gate.try_enter() {
Some(_slot) => accessed.record_accesses(ids),
None => Ok(()),
}
};
let in_flight = InFlight::enter(&RECALLS_IN_FLIGHT);
let result =
tokio::task::spawn_blocking(move || -> anyhow::Result<Result<RecallOutcome, String>> {
let _in_flight = in_flight;
let _reads = deadline.map(ReadDeadline::set);
if let Some(ref project) = project_filter
&& let Some(refusal) = refuse_unknown_project(&sqlite, project)?
{
return Ok(Err(refusal));
}
let embedding = match embedder {
Some(ref emb) => match embed_query(emb, &query_text, deadline) {
Ok(embedding) => Some(embedding),
Err(e) => {
tracing::warn!(
"embedding the recall query failed, using the text fallback: {e}"
);
None
}
},
None => None,
};
if deadline.is_some()
&& let Some(ref reranker) = reranker
{
reranker.warm_in_background();
}
if let Some(embedding) = embedding {
let request = QueryRequest {
text: query_text.clone(),
embedding,
limit,
filters: QueryFilters {
source: source_filter.clone(),
memory_type: type_filter,
min_confidence: None,
entity_names: crate::link_query_entities(&query_text),
project_path: project_filter.clone(),
},
};
let budgeted = reranker.as_deref().map(|r| {
Budgeted::new(r as &dyn TimedRerank, deadline).with_doc_chars(doc_chars)
});
let scorer = budgeted.as_ref().map(|b| b as &dyn RerankScorer);
let (mut results, scope) = match indexes {
Some(ref idx) => {
let retriever = Retriever { tunables };
let generate = |request: &QueryRequest| {
let guard = match idx.read() {
Ok(g) => g,
Err(poisoned) => poisoned.into_inner(),
};
let pool = retriever.candidates(&guard, &sqlite, request)?;
without_session(pool, &sqlite, exclude_session.as_deref())
};
match current_project {
Some(ref project) => {
let answer = if project_pass {
retriever.rank_project_first(
store.as_ref(),
&request,
project,
generate,
scorer,
)?
} else {
retriever.rank_project_preferred(
store.as_ref(),
&request,
project,
generate,
scorer,
)?
};
(answer.results, Some(scope_name(answer.scope)))
}
None => {
let pool = generate(&request)?;
(
retriever.rank(store.as_ref(), &request, &pool, scorer)?,
None,
)
}
}
}
None => (Vec::new(), None),
};
let abstained = tunables.abstain && indexes.is_some();
let hot_reranked = budgeted.as_ref().is_some_and(Budgeted::reranked);
let raw = raw_answer::fallback(
raw_index.as_deref(),
scorer,
HotOutcome {
results: results.len(),
abstention_on: abstained,
narrowed: type_filter.is_some() || source_filter.is_some(),
budgeted: deadline.is_some(),
excludes_session: exclude_session.is_some(),
},
&sqlite,
RawQuery {
text: &query_text,
embedding: &request.embedding,
project: project_filter.as_deref(),
limit,
archive: archive.as_deref(),
},
);
if results.is_empty() && !abstained {
let engine = QueryEngine::new(store.as_ref());
results = engine.recall(&QueryRequest {
limit: fetch_limit,
..request.clone()
})?;
}
if !results.is_empty() || abstained {
drop_session(
&mut results,
|r| r.memory.id,
&sqlite,
exclude_session.as_deref(),
)?;
results.truncate(limit);
let ids: Vec<Uuid> = results.iter().map(|r| r.memory.id).collect();
record_accesses(&ids)?;
return Ok(Ok(RecallOutcome {
memories: results
.into_iter()
.map(|r| (r.memory, Some(r.score), Some(r.relevance)))
.collect(),
degraded: None,
scope,
abstain_bar: applied_bar(abstained, hot_reranked),
raw,
}));
}
}
let mut text_results = sqlite.scoped_text_search(
&query_text,
source_filter.as_deref(),
type_filter,
project_filter.as_deref(),
fetch_limit,
)?;
drop_session(
&mut text_results,
|m| m.id,
&sqlite,
exclude_session.as_deref(),
)?;
text_results.truncate(limit);
let ids: Vec<Uuid> = text_results.iter().map(|m| m.id).collect();
record_accesses(&ids)?;
Ok(Ok(RecallOutcome {
memories: text_results.into_iter().map(|m| (m, None, None)).collect(),
degraded: Some("text-fallback"),
scope: None,
abstain_bar: None,
raw: Vec::new(),
}))
})
.await;
let outcome = match result {
Ok(Ok(Ok(outcome))) => outcome,
Ok(Ok(Err(message))) => return bad_request(message),
Ok(Err(e)) => return internal_error(e),
Err(e) => return internal_error(e),
};
let machine_names = match state.store.get_all_machines() {
Ok(names) => names,
Err(e) => return internal_error(e),
};
let ids: Vec<_> = outcome.memories.iter().map(|(m, _, _)| m.id).collect();
let corrected = match state.sqlite.corrected_at(&ids) {
Ok(marks) => marks,
Err(e) => return internal_error(e),
};
let shown: Vec<(Uuid, Option<f32>)> = outcome
.memories
.iter()
.map(|(m, _, relevance)| (m.id, *relevance))
.collect();
let raw_shown: Vec<Option<Uuid>> = outcome.raw.iter().map(|p| p.memory_id()).collect();
state.health.recalled(
recall_event(
caller_session,
&shown,
&raw_shown,
outcome.abstain_bar,
state.reranker.is_some(),
shows_only_cleared,
outcome.degraded.is_some(),
),
Utc::now(),
);
Json(RecallResponse {
memories: outcome
.memories
.into_iter()
.map(|(m, score, relevance)| {
let at = corrected.get(&m.id).map(|t| t.to_rfc3339());
MemoryResponse {
corrected_at: at,
..to_response(m, score, relevance, &machine_names)
}
})
.collect(),
degraded: outcome.degraded,
scope: outcome.scope,
abstain_bar: outcome.abstain_bar,
raw: outcome.raw,
})
.into_response()
}
#[derive(Deserialize)]
pub(super) struct ContextRequest {
project: String,
depth: Option<u32>,
}
#[derive(Serialize)]
struct ContextResponse {
memories: Vec<ContextMemory>,
}
#[derive(Serialize)]
struct ContextMemory {
id: String,
content: String,
memory_type: String,
confidence: f32,
session_at: Option<String>,
connected: Vec<String>,
}
pub(super) async fn context(
State(state): State<Arc<AppState>>,
Json(req): Json<ContextRequest>,
) -> impl IntoResponse {
let project = req.project.clone();
let depth = req.depth.unwrap_or(2);
let store = state.store.clone();
let result = tokio::task::spawn_blocking(move || -> anyhow::Result<Vec<ContextMemory>> {
let relevant = store.memories_by_project_path(&project)?;
let mut out = Vec::new();
for memory in &relevant {
let connected: Vec<String> = store
.traverse(memory.id, depth)?
.into_iter()
.map(|(m, _)| truncate(&m.content, 100))
.collect();
out.push(ContextMemory {
id: memory.id.to_string(),
content: memory.content.clone(),
memory_type: format!("{:?}", memory.memory_type).to_lowercase(),
confidence: memory.confidence,
session_at: memory.session_at.map(|t| t.to_rfc3339()),
connected,
});
}
Ok(out)
})
.await;
match result {
Ok(Ok(memories)) => Json(ContextResponse { memories }).into_response(),
Ok(Err(e)) => (
StatusCode::INTERNAL_SERVER_ERROR,
Json(serde_json::json!({"error": e.to_string()})),
)
.into_response(),
Err(e) => (
StatusCode::INTERNAL_SERVER_ERROR,
Json(serde_json::json!({"error": e.to_string()})),
)
.into_response(),
}
}
fn truncate(s: &str, max_len: usize) -> String {
if s.len() <= max_len {
s.to_string()
} else {
let mut end = max_len.min(s.len());
while end > 0 && !s.is_char_boundary(end) {
end -= 1;
}
format!("{}...", &s[..end])
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_bar_is_reported_only_for_an_abstaining_reranked_answer() {
assert_eq!(applied_bar(true, true), Some(blend::ABSTAIN_RERANK_BAR));
assert_eq!(applied_bar(true, false), None);
assert_eq!(applied_bar(false, true), None);
assert_eq!(applied_bar(false, false), None);
}
#[test]
fn a_recall_is_classified_by_its_results_bar_and_reranker() {
let (a, b) = (Uuid::new_v4(), Uuid::new_v4());
let bar = 0.5;
let cases = vec![
(vec![], None, false, RecallVerdict::Empty, vec![]),
(vec![], Some(bar), true, RecallVerdict::Empty, vec![]),
(vec![], None, true, RecallVerdict::Unjudged, vec![]),
(
vec![(a, Some(0.7)), (b, Some(0.2))],
Some(bar),
true,
RecallVerdict::Hit,
vec![a, b],
),
(
vec![(a, Some(0.2)), (b, Some(0.5))],
Some(bar),
true,
RecallVerdict::Hit,
vec![a, b],
),
(
vec![(a, Some(0.2)), (b, None)],
Some(bar),
true,
RecallVerdict::LowScore,
vec![a, b],
),
(
vec![(a, None), (b, Some(0.1))],
None,
false,
RecallVerdict::Hit,
vec![a, b],
),
(
vec![(a, Some(0.9)), (b, None)],
None,
true,
RecallVerdict::Unjudged,
vec![a, b],
),
];
for (shown, abstain_bar, has_reranker, verdict, ids) in cases {
let event = recall_event(
Some("s1".to_string()),
&shown,
&[],
abstain_bar,
has_reranker,
false,
false,
);
assert_eq!(
event,
RecallEvent {
session: Some("s1".to_string()),
verdict,
memory_ids: ids,
},
"{shown:?} bar {abstain_bar:?} reranker {has_reranker}"
);
}
}
#[test]
fn a_deadline_answer_without_a_bar_is_unjudged_and_shows_nothing() {
let (a, b) = (Uuid::new_v4(), Uuid::new_v4());
let shown = [(a, Some(0.9)), (b, None)];
for has_reranker in [true, false] {
let event = recall_event(None, &shown, &[], None, has_reranker, true, false);
assert_eq!(event.verdict, RecallVerdict::Unjudged, "{has_reranker}");
assert_eq!(event.memory_ids, Vec::<Uuid>::new(), "{has_reranker}");
}
let event = recall_event(None, &shown, &[], Some(0.5), true, true, false);
assert_eq!(event.verdict, RecallVerdict::Hit);
assert_eq!(event.memory_ids, vec![a]);
}
#[test]
fn a_degraded_answer_is_unjudged_even_when_empty() {
let a = Uuid::new_v4();
let cases = [
(vec![], true, vec![]),
(vec![], false, vec![]),
(vec![(a, None)], true, vec![]),
(vec![(a, None)], false, vec![a]),
];
for (shown, deadline, ids) in cases {
for has_reranker in [true, false] {
let event = recall_event(None, &shown, &[], None, has_reranker, deadline, true);
assert_eq!(
(event.verdict, event.memory_ids),
(RecallVerdict::Unjudged, ids.clone()),
"{shown:?} deadline {deadline} reranker {has_reranker}"
);
}
}
}
#[test]
fn raw_passages_make_an_abstained_recall_a_hit_on_their_memories() {
let (a, b) = (Uuid::new_v4(), Uuid::new_v4());
let event = recall_event(
None,
&[],
&[Some(a), None, Some(b)],
Some(0.5),
true,
false,
false,
);
assert_eq!(
event,
RecallEvent {
session: None,
verdict: RecallVerdict::Hit,
memory_ids: vec![a, b],
}
);
let event = recall_event(
None,
&[(a, Some(0.9))],
&[Some(b)],
Some(0.5),
true,
false,
false,
);
assert_eq!(
event.memory_ids,
vec![a],
"raw only answers an empty recall"
);
}
#[test]
fn a_pool_without_a_session_keeps_only_other_sessions_candidates() {
use second_brain_core::schema::MemoryType;
use second_brain_core::store::Store;
let sqlite = SqliteStore::in_memory("m".to_string()).unwrap();
let stored = |source_id: &str| {
let memory = Memory::new(
source_id.to_string(),
MemoryType::Episodic,
"claude-code".to_string(),
source_id.to_string(),
);
sqlite.store_memory(&memory).unwrap();
memory.id
};
let own = stored("/h/.claude/projects/-a/s1.jsonl");
let other = stored("/h/.claude/projects/-a/s2.jsonl");
let mut pool = Candidates::new(vec![(own, 0.9), (other, 0.8)], vec![(own, 3.0)]);
pool.best_chunk.insert(own, (0, 0.9));
let kept = without_session(pool.clone(), &sqlite, Some("s1")).unwrap();
assert_eq!(kept.dense, vec![(other, 0.8)]);
assert!(kept.lexical.is_empty());
assert!(kept.best_chunk.is_empty());
let untouched = without_session(pool, &sqlite, None).unwrap();
assert_eq!(untouched.dense.len(), 2);
}
#[test]
fn a_recall_counts_as_in_flight_until_its_work_is_dropped() {
static COUNTER: AtomicUsize = AtomicUsize::new(0);
let first = InFlight::enter(&COUNTER);
let second = InFlight::enter(&COUNTER);
assert_eq!(COUNTER.load(Ordering::SeqCst), 2);
drop(first);
assert_eq!(COUNTER.load(Ordering::SeqCst), 1);
drop(second);
assert_eq!(COUNTER.load(Ordering::SeqCst), 0);
}
}