second-brain-core 0.13.3

Core library for second-brain: SQLite storage with vector and lexical indexes, BGE embeddings, and hybrid retrieval
Documentation
use anyhow::Result;
use chrono::{DateTime, Utc};
use rusqlite::{OptionalExtension, params};
use uuid::Uuid;

use super::{SqliteStore, embedding_to_blob};
use crate::cold::{content_digest, stub_digest};
use crate::schema::distillable_source;

const SUPERSEDE_HOPS: usize = 8;

/// What became of the raw memory a transcript passage was cut from.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RawMemoryState {
    /// No row and no tombstone for the id: ingest screened the chunk out,
    /// or the row has not reached this device.
    Unknown,
    /// In force, held by the row `id`: the memory itself, or the identical
    /// row maintenance collapsed it onto, which is the one to forget.
    InForce {
        id: Uuid,
    },
    Withdrawn,
}

pub(super) const ARCHIVED_RAW: &str = concat!(
    "tier = 'archived' AND superseded_by IS NULL AND retired_reason IS NULL AND ",
    distillable_source!("source")
);

/// Archived raw memories split at an age bound, each side newest first.
#[derive(Debug, Default, PartialEq, Eq)]
pub struct ArchivedRaws {
    pub recent: Vec<Uuid>,
    pub older: Vec<Uuid>,
}

impl SqliteStore {
    /// Archived raw memories split by whether their session time (their
    /// creation time when the session is unknown) is at or after `since`.
    /// These are the transcript chunks consolidation took out of recall,
    /// which the raw fallback index keeps searchable; retired and superseded
    /// rows are left out.
    pub fn archived_raws_since(&self, since: DateTime<Utc>) -> Result<ArchivedRaws> {
        let conn = self.reader();
        let mut stmt = conn.prepare(&format!(
            "SELECT id, COALESCE(session_at, created_at) >= ?1 FROM memories \
             WHERE {ARCHIVED_RAW} ORDER BY COALESCE(session_at, created_at) DESC, id"
        ))?;
        let rows = stmt.query_map(params![since.to_rfc3339()], |r| {
            Ok((r.get::<_, String>(0)?, r.get::<_, bool>(1)?))
        })?;
        let mut raws = ArchivedRaws::default();
        for row in rows {
            let (id, in_bound) = row?;
            match Uuid::parse_str(&id) {
                Ok(id) if in_bound => raws.recent.push(id),
                Ok(id) => raws.older.push(id),
                Err(_) => {}
            }
        }
        Ok(raws)
    }

    /// Whether `id` is still an archived raw the fallback may answer from.
    pub fn is_archived_raw(&self, id: Uuid) -> Result<bool> {
        let conn = self.reader();
        let hit = conn
            .prepare(&format!(
                "SELECT 1 FROM memories WHERE id = ?1 AND {ARCHIVED_RAW}"
            ))?
            .exists(params![id.to_string()])?;
        Ok(hit)
    }

    /// Whether the raw memory `id` still stands behind the transcript
    /// passage it was cut from. Forgetting, deleting or correcting it
    /// withdraws the passage; a supersede onto a byte-identical row, which is
    /// how maintenance collapses duplicates, does not, unless the row it
    /// collapsed onto is withdrawn in turn.
    pub fn raw_memory_state(&self, id: Uuid) -> Result<RawMemoryState> {
        let conn = self.reader();
        let mut current = id;
        let mut previous: Option<String> = None;
        for _ in 0..SUPERSEDE_HOPS {
            let row = conn
                .query_row(
                    "SELECT content, archived_segment IS NOT NULL, \
                     retired_reason IS NOT NULL, superseded_by \
                     FROM memories WHERE id = ?1",
                    params![current.to_string()],
                    |r| {
                        Ok((
                            r.get::<_, String>(0)?,
                            r.get::<_, bool>(1)?,
                            r.get::<_, bool>(2)?,
                            r.get::<_, Option<String>>(3)?,
                        ))
                    },
                )
                .optional()?;
            let Some((text, cold, retired, superseded_by)) = row else {
                let tombstoned = conn
                    .prepare("SELECT 1 FROM tombstones WHERE node_id = ?1")?
                    .exists(params![current.to_string()])?;
                return Ok(match (tombstoned, previous.is_some()) {
                    (true, _) | (false, true) => RawMemoryState::Withdrawn,
                    (false, false) => RawMemoryState::Unknown,
                });
            };
            let digest = match (cold, stub_digest(&text)) {
                (true, Some(digest)) => digest.to_string(),
                _ => content_digest(&text),
            };
            if retired || previous.as_ref().is_some_and(|c| *c != digest) {
                return Ok(RawMemoryState::Withdrawn);
            }
            let Some(next) = superseded_by.and_then(|s| Uuid::parse_str(&s).ok()) else {
                return Ok(RawMemoryState::InForce { id: current });
            };
            previous = Some(digest);
            current = next;
        }
        Ok(RawMemoryState::Withdrawn)
    }

    /// Restores the vector of an archived row that lost it, which happens
    /// when a redacted row arrives through sync. It is derived from the
    /// content on this device, so it is written locally: no outbox, no sync
    /// log, and `updated_at` is left alone so it cannot win a merge.
    pub fn restore_archived_embedding(&self, id: Uuid, embedding: &[f32]) -> Result<bool> {
        self.with_txn(|tx| {
            let changed = tx.execute(
                "UPDATE memories SET embedding = ?2 \
                 WHERE id = ?1 AND tier = 'archived' AND archived_segment IS NULL \
                 AND embedding IS NULL",
                params![id.to_string(), embedding_to_blob(embedding)],
            )?;
            Ok(changed > 0)
        })
    }
}