second-brain-api 0.10.0

HTTP API server for second-brain: REST endpoints for recall, remember, and ingest
Documentation
use std::path::{Path, PathBuf};
use std::sync::{Arc, RwLock};
use std::time::Duration;

use axum::Router;
use axum::extract::DefaultBodyLimit;
use tokio::net::TcpListener;
use tower_http::cors::CorsLayer;
use tower_http::trace::TraceLayer;

use second_brain_api::maintenance::DrainLoop;
use second_brain_api::{AppState, routes, watcher};
use second_brain_core::config::Config;
use second_brain_core::embedding::Embedder;
use second_brain_core::index::Indexes;
use second_brain_core::machine::MachineIdentity;
use second_brain_core::retrieval::Reranker;
use second_brain_core::sqlite_store::SqliteStore;
use second_brain_core::store::StoreAdmin;

/// The reader is what `AppState` and every recall call see; the writer is
/// private to the drain loop. Splitting them means recall never contends
/// with the drain loop for anything heavier than the brief `reload_view`
/// call the loop makes on the reader after each successful drain.
struct IndexHandles {
    reader: Arc<RwLock<Indexes>>,
    writer: Indexes,
}

fn open_index_handles(dir: &Path, store: &SqliteStore) -> anyhow::Result<IndexHandles> {
    let mut writer = Indexes::open(dir)?;
    if writer.consistent_with(store)? {
        tracing::info!("search indexes consistent at {}", dir.display());
        // `rebuild` persists as its last step, but the "already consistent"
        // branch never mutates, so a brand-new index (nothing on disk yet,
        // trivially consistent with an empty store) would otherwise leave
        // `open_readonly` below with no files to open.
        writer.persist()?;
    } else {
        tracing::info!("rebuilding search indexes at {}", dir.display());
        let n = writer.rebuild(store)?;
        tracing::info!("search indexes rebuilt: {n} memories");
    }
    let reader = Indexes::open_readonly(dir)?;
    Ok(IndexHandles {
        reader: Arc::new(RwLock::new(reader)),
        writer,
    })
}

/// A rerank pool of 1 (the old default) serializes every concurrent recall
/// behind one session; `evals/rerank-cost-curve.md` reproduced the result
/// of that under ordinary eval load: a queued request timed out at 30s.
/// `Reranker`'s intra-op thread count is already sized per-session as
/// `cores / pool_size` (see `crates/core/src/retrieval/rerank.rs`), so a
/// larger pool does not add CPU throughput the machine doesn't have — wave
/// 1's measurement found oversubscribed sessions just contend for the same
/// cores. What a larger pool buys is concurrency headroom: enough sessions
/// that an ordinary burst of overlapping recalls queues briefly instead of
/// erroring. Capping at 4 keeps that headroom without loading more model
/// copies into memory than a handful of concurrent clients would ever need.
fn rerank_pool_size() -> usize {
    match std::env::var("SECOND_BRAIN_RERANK_POOL") {
        Ok(v) => v
            .parse::<usize>()
            .unwrap_or_else(|_| {
                panic!("invalid SECOND_BRAIN_RERANK_POOL '{v}': expected a positive integer")
            })
            .max(1),
        Err(_) => {
            let cores = std::thread::available_parallelism()
                .map(|n| n.get())
                .unwrap_or(1);
            cores.clamp(1, 4)
        }
    }
}

#[tokio::main]
async fn main() {
    tracing_subscriber::fmt()
        .with_env_filter(
            tracing_subscriber::EnvFilter::from_default_env()
                .add_directive("second_brain=info".parse().unwrap())
                .add_directive("tower_http=debug".parse().unwrap()),
        )
        .init();

    let db_path = std::env::var("SECOND_BRAIN_DB")
        .map(PathBuf::from)
        .unwrap_or_else(|_| {
            let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
            PathBuf::from(home).join(".second-brain").join("brain.db")
        });

    if let Some(parent) = db_path.parent() {
        std::fs::create_dir_all(parent).ok();
    }

    let config_dir = MachineIdentity::config_dir().expect("cannot determine home directory");
    let machine = MachineIdentity::load_or_create(&config_dir)
        .expect("failed to load or create machine identity");

    tracing::info!("machine identity: {} ({})", machine.name, machine.id);

    let sqlite = match SqliteStore::open(&db_path, machine.id.clone()) {
        Ok(s) => Arc::new(s),
        Err(e) => {
            tracing::error!("failed to open database at {}: {e}", db_path.display());
            std::process::exit(1);
        }
    };
    let store: Arc<dyn StoreAdmin> = sqlite.clone();
    store
        .register_machine(&machine)
        .expect("failed to register machine identity");

    tracing::info!("database opened at {}", db_path.display());

    let config = match Config::load_default() {
        Ok(c) => c,
        Err(e) => {
            tracing::warn!("config.toml unusable, running with defaults: {e:#}");
            Config::default()
        }
    };

    let embedder = match Embedder::new() {
        Ok(e) => {
            tracing::info!("embedding model loaded");
            Some(Arc::new(e))
        }
        Err(e) => {
            tracing::warn!("embedding model unavailable: {e}");
            None
        }
    };

    let index_dir = db_path.with_extension("indexes");
    let index_handles = match open_index_handles(&index_dir, &sqlite) {
        Ok(h) => Some(h),
        Err(e) => {
            tracing::warn!(
                "search indexes unavailable at {}: {e}; recall falls back to the legacy engine",
                index_dir.display()
            );
            None
        }
    };
    let indexes = index_handles.as_ref().map(|h| h.reader.clone());

    let rerank_model = std::env::var("SECOND_BRAIN_RERANK_MODEL")
        .unwrap_or_else(|_| "jina-reranker-v1-turbo".to_string());
    let reranker = if indexes.is_none() || rerank_model == "off" {
        None
    } else {
        let pool_size = rerank_pool_size();
        match Reranker::with_sessions(&rerank_model, pool_size) {
            Ok(r) => {
                tracing::info!("rerank model {rerank_model} loaded ({pool_size} sessions)");
                Some(Arc::new(r))
            }
            Err(e) => {
                tracing::warn!("rerank model {rerank_model} unavailable: {e:#}");
                None
            }
        }
    };

    let maintenance = Arc::new(RwLock::new(None));
    let near_duplicates = Arc::new(RwLock::new(None));
    let mut repair_tx = None;
    if let Some(IndexHandles { reader, writer }) = index_handles {
        let (tx, requests) = std::sync::mpsc::channel();
        repair_tx = Some(tx);
        DrainLoop {
            store: sqlite.clone(),
            reader,
            writer,
            embedder: embedder.clone(),
            summary: maintenance.clone(),
            near_duplicates: near_duplicates.clone(),
            near_duplicate_threshold: config.distill.near_duplicate_threshold,
            config: config.maintenance.clone(),
            requests,
        }
        .spawn();
    }

    watcher::spawn(store.clone(), embedder.clone(), machine.id.clone());

    if let Some(emb) = embedder.clone() {
        tokio::spawn(async move {
            let mut interval = tokio::time::interval(Duration::from_secs(60));
            loop {
                interval.tick().await;
                emb.drop_if_idle(300);
            }
        });
    }

    if let Some(r) = reranker.clone() {
        tokio::spawn(async move {
            let mut interval = tokio::time::interval(Duration::from_secs(60));
            loop {
                interval.tick().await;
                r.drop_if_idle(300);
            }
        });
    }

    let state = Arc::new(AppState {
        store,
        sqlite,
        indexes,
        reranker,
        // Gates and fuse_top come from [retrieval] in config.toml. The
        // 2026-09 sweep on the distilled corpus (evals/fuse-top-distilled.md)
        // moved the fuse_top default from 10 to 20.
        tunables: config.retrieval.tunables(),
        embedder,
        machine,
        maintenance,
        repair_tx,
        near_duplicate_threshold: config.distill.near_duplicate_threshold,
        near_duplicates,
    });

    let app = Router::new()
        .merge(routes::router())
        .layer(DefaultBodyLimit::max(64 * 1024 * 1024))
        .layer(CorsLayer::permissive())
        .layer(TraceLayer::new_for_http())
        .with_state(state);

    let bind = std::env::var("SECOND_BRAIN_BIND").unwrap_or_else(|_| "127.0.0.1:7200".to_string());
    let listener = TcpListener::bind(&bind).await.unwrap();
    tracing::info!("listening on {bind}");

    axum::serve(listener, app).await.unwrap();
}