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, bail};
use chrono::Utc;
use rusqlite::{OptionalExtension, Transaction, params};
use uuid::Uuid;

use super::{SqliteStore, body_of, embedding_to_blob};
use crate::chunk;
use crate::index::EMBEDDING_DIM;
use crate::maintenance::EmbedBatchFn;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RewriteOutcome {
    Rewritten,
    Unchanged,
    NotFound,
    /// The row's content or context changed between the read and the write,
    /// so nothing was written; a later pass sees the newer text.
    Conflict,
}

#[derive(PartialEq)]
struct Texts {
    content: String,
    context: Option<String>,
    retired_reason: Option<String>,
}

struct Snapshot {
    texts: Texts,
    live: bool,
    embedded: bool,
    cold: bool,
}

impl SqliteStore {
    /// Rewrites a memory's content, context and retirement reason through
    /// `rewrite`, whatever its tier. Vectors are computed before the write
    /// transaction, so the writer lock is never held across model inference;
    /// the transaction then stores the text, the memory vector, a fresh chunk
    /// set (live rows only), an index upsert and a sync Update carrying the
    /// new row. Without `embed`, or when embedding fails, the memory vector
    /// and chunks are dropped and the repair loop's backfills restore them. A
    /// row outside the live set that had no vector gets none. A change to the
    /// reason alone keeps the vectors and chunks, which are not derived from
    /// it. A cold row is an error, since its row holds only a stub.
    pub fn rewrite_memory_content(
        &self,
        memory_id: Uuid,
        rewrite: &dyn Fn(&str) -> String,
        embed: Option<EmbedBatchFn<'_>>,
    ) -> Result<RewriteOutcome> {
        let id = memory_id.to_string();
        let Some(before) = self.rewrite_snapshot(&id)? else {
            return Ok(RewriteOutcome::NotFound);
        };
        if before.cold {
            bail!(
                "memory {memory_id} is in the cold tier; its text is sealed in a segment, not the row"
            );
        }
        let old = &before.texts;
        let new = Texts {
            content: rewrite(&old.content),
            context: old.context.as_deref().map(rewrite),
            retired_reason: old.retired_reason.as_deref().map(rewrite),
        };
        if new == *old {
            return Ok(RewriteOutcome::Unchanged);
        }
        let body_changed = new.content != old.content || new.context != old.context;
        let vectors = body_changed.then(|| {
            let body = body_of(new.context.clone(), new.content.clone());
            let embedding = match embed {
                Some(embed) if before.embedded || before.live => embed_one(embed, memory_id, &body),
                _ => None,
            };
            let chunks = match embed {
                Some(embed) if before.live => embed_chunks(embed, memory_id, &new.content),
                _ => Vec::new(),
            };
            (embedding, chunks)
        });

        self.with_txn(|tx| {
            if Self::texts_on_tx(tx, &id)?.as_ref() != Some(old) {
                return Ok(RewriteOutcome::Conflict);
            }
            tx.execute(
                "UPDATE memories SET content = ?2, context = ?3, retired_reason = ?4, \
                 updated_at = ?5 WHERE id = ?1",
                params![
                    id,
                    new.content,
                    new.context,
                    new.retired_reason,
                    Utc::now().to_rfc3339(),
                ],
            )?;
            if let Some((embedding, chunks)) = &vectors {
                tx.execute(
                    "UPDATE memories SET embedding = ?2 WHERE id = ?1",
                    params![id, embedding.as_deref().map(embedding_to_blob)],
                )?;
                Self::replace_chunk_rows(
                    tx,
                    &id,
                    &chunk::content_hash(&new.content),
                    chunks
                        .iter()
                        .enumerate()
                        .map(|(ord, (text, vector))| (ord, text.as_str(), vector.as_slice())),
                )?;
                Self::append_outbox(tx, memory_id, "upsert")?;
            }
            if let Some(memory) = Self::memory_on_tx(tx, memory_id)? {
                self.log_memory_update(tx, &memory)?;
            }
            Ok(RewriteOutcome::Rewritten)
        })
    }

    fn texts_on_tx(tx: &Transaction<'_>, id: &str) -> Result<Option<Texts>> {
        tx.query_row(
            "SELECT content, context, retired_reason FROM memories WHERE id = ?1",
            params![id],
            |r| {
                Ok(Texts {
                    content: r.get(0)?,
                    context: r.get(1)?,
                    retired_reason: r.get(2)?,
                })
            },
        )
        .optional()
        .map_err(Into::into)
    }

    fn rewrite_snapshot(&self, id: &str) -> Result<Option<Snapshot>> {
        let conn = self.reader();
        conn.query_row(
            "SELECT content, context, retired_reason, tier = 'hot' AND superseded_by IS NULL, \
             embedding IS NOT NULL, archived_segment IS NOT NULL FROM memories WHERE id = ?1",
            params![id],
            |r| {
                Ok(Snapshot {
                    texts: Texts {
                        content: r.get(0)?,
                        context: r.get(1)?,
                        retired_reason: r.get(2)?,
                    },
                    live: r.get(3)?,
                    embedded: r.get(4)?,
                    cold: r.get(5)?,
                })
            },
        )
        .optional()
        .map_err(Into::into)
    }
}

fn embed_one(embed: EmbedBatchFn<'_>, memory_id: Uuid, body: &str) -> Option<Vec<f32>> {
    match embed(&[body]) {
        Ok(mut v) if v.len() == 1 && v[0].len() == EMBEDDING_DIM => v.pop(),
        Ok(_) => {
            tracing::warn!(%memory_id, "rewrite embedding had the wrong shape");
            None
        }
        Err(e) => {
            tracing::warn!(%memory_id, "rewrite embedding failed: {e:#}");
            None
        }
    }
}

/// All of the content's chunks with their vectors, or none: a partial set
/// would read as complete to `scan_chunk_work`, which only compares hashes.
fn embed_chunks(
    embed: EmbedBatchFn<'_>,
    memory_id: Uuid,
    content: &str,
) -> Vec<(String, Vec<f32>)> {
    let texts = chunk::split(content);
    if texts.is_empty() {
        return Vec::new();
    }
    let refs: Vec<&str> = texts.iter().map(String::as_str).collect();
    match embed(&refs) {
        Ok(v) if v.len() == texts.len() && v.iter().all(|e| e.len() == EMBEDDING_DIM) => {
            texts.into_iter().zip(v).collect()
        }
        Ok(_) => {
            tracing::warn!(%memory_id, "rewrite chunk embedding had the wrong shape");
            Vec::new()
        }
        Err(e) => {
            tracing::warn!(%memory_id, "rewrite chunk embedding failed: {e:#}");
            Vec::new()
        }
    }
}