second-brain-core 0.13.0

Core library for second-brain: SQLite storage with vector and lexical indexes, BGE embeddings, and hybrid retrieval
Documentation
use std::collections::HashSet;

use anyhow::Result;
use chrono::Utc;
use uuid::Uuid;

use crate::schema::{AGENT_NOTE_SOURCE, EXPLICIT_SOURCES, Memory, RelationType};
use crate::store::Store;

pub const MIN_SIMILARITY: f32 = 0.59;
/// Floor for a scope that generation scanned whole; see
/// `RetrievalTunables::exhausted_cosine_gate`.
pub const EXHAUSTED_MIN_SIMILARITY: f32 = 0.56;
pub const PROJECT_AFFINITY_BOOST: f32 = 1.15;
/// With `RetrievalTunables::abstain`, the cross-encoder score some result
/// must reach for a reranked query to be answered at all. Cosine has no such
/// bar: no cosine separates an absent answer from a weak present one
/// (evals/exhausted-floor.md). Calibrated in evals/results/abstain_calibration.json.
pub const ABSTAIN_RERANK_BAR: f32 = 0.52;

#[derive(Debug, Clone, Copy)]
pub struct BlendWeights {
    pub primary: f32,
    pub graph: f32,
    pub recency: f32,
}

impl Default for BlendWeights {
    fn default() -> Self {
        Self {
            primary: 0.5,
            graph: 0.3,
            recency: 0.2,
        }
    }
}

pub fn blend(primary: f32, graph: f32, recency: f32, weights: BlendWeights) -> f32 {
    (primary * weights.primary) + (graph * weights.graph) + (recency * weights.recency)
}

pub fn apply_project_affinity(score: f32, memory: &Memory, project_path: Option<&str>) -> f32 {
    match project_path {
        Some(qp) if memory.project_path.as_deref() == Some(qp) => score * PROJECT_AFFINITY_BOOST,
        _ => score,
    }
}

/// Order of a source under `RetrievalTunables::source_order`, lowest first:
/// agent notes, then distillates and remembered notes, then raw memories
/// mined from transcripts.
pub fn source_rank(source: &str) -> u8 {
    if source == AGENT_NOTE_SOURCE {
        0
    } else if source == "consolidation" || EXPLICIT_SOURCES.contains(&source) {
        1
    } else {
        2
    }
}

pub fn compute_recency(memory: &Memory) -> f32 {
    let hours_since_access = Utc::now()
        .signed_duration_since(memory.last_accessed)
        .num_hours() as f32;

    let decay = (-hours_since_access / (24.0 * 30.0)).exp();
    let access_boost = (memory.access_count as f32).ln_1p() / 10.0;

    (decay + access_boost).min(1.0)
}

/// Resolve the entity names referenced by a query to their stored entity
/// ids. Names come from gazetteer extraction over the query text, so they
/// match stored entity names exactly; unknown names resolve to nothing.
pub fn resolve_query_entities<S: Store + ?Sized>(store: &S, names: &[String]) -> HashSet<Uuid> {
    let mut ids = HashSet::new();
    for name in names {
        if let Ok(Some(entity)) = store.find_entity_by_name(name) {
            ids.insert(entity.id);
        }
    }
    ids
}

pub fn compute_graph_relevance<S: Store + ?Sized>(
    store: &S,
    memory: &Memory,
    query_entity_ids: &HashSet<Uuid>,
) -> Result<f32> {
    let scored_types = [
        (RelationType::Reinforces, 0.3_f32),
        (RelationType::RelatesTo, 0.2),
        (RelationType::DistilledFrom, 0.15),
        (RelationType::Mentions, 0.1),
        (RelationType::DerivedFrom, 0.05),
        (RelationType::Contradicts, -0.1),
        (RelationType::Supersedes, -0.2),
    ];

    // Structural score is a query-independent prior: how reinforced and
    // non-superseded a memory is. Mention overlap with the query is
    // collected in the same pass so the Mentions edges are only fetched once.
    let mut structural = 0.0_f32;
    let mut mention_hits = 0usize;
    for (rt, boost) in &scored_types {
        if let Ok(rels) = store.get_relations(memory.id, Some(*rt)) {
            for rel in &rels {
                let b = if *rt == RelationType::RelatesTo {
                    boost * rel.strength
                } else {
                    *boost
                };
                structural += b;
                if *rt == RelationType::Mentions && query_entity_ids.contains(&rel.to_id) {
                    mention_hits += 1;
                }
            }
        }
    }
    let structural = structural.clamp(0.0, 1.0);

    if query_entity_ids.is_empty() {
        return Ok(structural);
    }

    // Query-conditioned proximity: the fraction of the query's entities this
    // memory directly mentions. A memory topically adjacent to what the
    // query is about should outrank a generically well-connected but
    // off-topic one, so proximity dominates the structural prior.
    let proximity = (mention_hits as f32 / query_entity_ids.len() as f32).min(1.0);
    Ok((0.7 * proximity + 0.3 * structural).clamp(0.0, 1.0))
}