second-brain-api 0.11.0

HTTP API server for second-brain: REST endpoints for recall, remember, and ingest
Documentation
mod common;

use std::path::Path;
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::time::{Duration, SystemTime};

use axum::http::StatusCode;
use serde_json::{Value, json};
use tower::ServiceExt;
use uuid::Uuid;

use second_brain_api::AppState;
use second_brain_api::write_queue::{Entry, WriteQueue, entry_names};
use second_brain_core::schema::Tier;
use second_brain_core::store::Store;

const TOKEN: &str = "queue-test-token";

fn queue_dir() -> tempfile::TempDir {
    tempfile::tempdir().unwrap()
}

fn entry_name(age: Duration) -> String {
    let at = SystemTime::now() - age;
    let nanos = at
        .duration_since(SystemTime::UNIX_EPOCH)
        .unwrap()
        .as_nanos();
    format!("{nanos:019}-{}.json", Uuid::new_v4())
}

/// Entries are named by call time; each one queued here is a millisecond
/// newer than the last so the order is the order written.
fn enqueue(dir: &Path, entries: &[Entry]) {
    let n = entries.len() as u32;
    for (i, entry) in entries.iter().enumerate() {
        let age = Duration::from_millis(u64::from(n - i as u32));
        std::fs::write(
            dir.join(entry_name(age)),
            serde_json::to_vec(entry).unwrap(),
        )
        .unwrap();
    }
}

fn remember(id: Uuid, content: &str) -> Entry {
    Entry {
        tool: "remember".to_string(),
        method: "POST".to_string(),
        path: "/v1/remember".to_string(),
        query: None,
        body: Some(json!({
            "content": content,
            "id": id.to_string(),
            "session_at": "2026-10-30T08:15:00Z",
            "source": "mcp-direct",
        })),
    }
}

fn forget(id: &str, hard: bool) -> Entry {
    Entry {
        tool: "forget".to_string(),
        method: "DELETE".to_string(),
        path: format!("/v1/memory/{id}"),
        query: Some(format!("hard={hard}&reason=wrong")),
        body: None,
    }
}

fn queue(dir: &Path, state: &Arc<AppState>, token: &str) -> WriteQueue {
    WriteQueue::new(
        dir.to_path_buf(),
        second_brain_api::app(state.clone(), TOKEN.to_string()),
        token.to_string(),
        state.health.clone(),
        state.gate.clone(),
    )
}

async fn health(state: &Arc<AppState>) -> Value {
    let response = second_brain_api::app(state.clone(), TOKEN.to_string())
        .oneshot(common::get("/health"))
        .await
        .unwrap();
    assert_eq!(response.status(), StatusCode::OK);
    common::json_body(response).await
}

#[tokio::test]
async fn queued_writes_replay_in_order_and_leave_the_queue_empty() {
    let dir = queue_dir();
    let state = common::state();
    let (kept, retired) = (Uuid::new_v4(), Uuid::new_v4());
    enqueue(
        dir.path(),
        &[
            remember(kept, "the build runs on the ssd"),
            remember(retired, "the build runs on sda"),
            forget(&retired.to_string(), false),
        ],
    );
    std::fs::write(dir.path().join("projects.json"), r#"{"projects":[]}"#).unwrap();
    let stale = dir
        .path()
        .join(format!("{}.tmp", entry_name(Duration::ZERO)));
    let fresh = dir.path().join("projects.json.1.tmp");
    std::fs::write(&stale, "{").unwrap();
    std::fs::write(&fresh, "{").unwrap();
    std::fs::File::options()
        .write(true)
        .open(&stale)
        .unwrap()
        .set_modified(SystemTime::now() - Duration::from_secs(2 * 60 * 60))
        .unwrap();

    let pass = queue(dir.path(), &state, TOKEN).tick().await.unwrap();
    assert_eq!((pass.sent, pass.rejected, pass.stopped), (3, 0, None));
    assert!(entry_names(dir.path()).unwrap().is_empty());
    assert!(!stale.exists());
    assert!(fresh.exists());
    assert!(dir.path().join("projects.json").exists());

    let landed = state.sqlite.get_memory(kept).unwrap().unwrap();
    assert_eq!(landed.tier, Tier::Hot);
    assert_eq!(
        landed.session_at.unwrap().to_rfc3339(),
        "2026-10-30T08:15:00+00:00"
    );
    let gone = state.sqlite.get_memory(retired).unwrap().unwrap();
    assert_eq!(gone.tier, Tier::Archived);
    assert_eq!(state.sqlite.memory_count().unwrap(), 2);
    assert_eq!(health(&state).await["queue"]["depth"], 0);
}

#[tokio::test]
async fn the_same_remember_queued_twice_lands_one_row() {
    let dir = queue_dir();
    let state = common::state();
    let id = Uuid::new_v4();
    enqueue(
        dir.path(),
        &[remember(id, "sent twice"), remember(id, "sent twice")],
    );
    queue(dir.path(), &state, TOKEN).tick().await.unwrap();
    assert_eq!(state.sqlite.memory_count().unwrap(), 1);
    assert!(state.sqlite.get_memory(id).unwrap().is_some());
}

#[tokio::test]
async fn a_queued_remember_is_redacted_when_it_replays() {
    let dir = queue_dir();
    let state = common::state();
    let id = Uuid::new_v4();
    let token = ["gh", "p_"].concat() + &"Qq7xZ2".repeat(6);
    enqueue(
        dir.path(),
        &[remember(id, &format!("the deploy bot pushes with {token}"))],
    );
    queue(dir.path(), &state, TOKEN).tick().await.unwrap();
    let stored = state.sqlite.get_memory(id).unwrap().unwrap();
    assert_eq!(
        stored.content,
        "the deploy bot pushes with [REDACTED:github_token]"
    );
}

#[tokio::test]
async fn a_remember_that_dedups_points_later_entries_at_the_stored_row() {
    let dir = queue_dir();
    let state = common::state();
    let existing = Uuid::new_v4();
    let stored = second_brain_core::schema::Memory {
        id: existing,
        ..second_brain_core::schema::Memory::new(
            "Retries need a jittered backoff".to_string(),
            second_brain_core::schema::MemoryType::Semantic,
            "mcp-direct".to_string(),
            String::new(),
        )
    };
    state.sqlite.store_memory(&stored).unwrap();
    let client = Uuid::new_v4();
    enqueue(
        dir.path(),
        &[
            remember(client, "retries need a jittered backoff"),
            forget(&client.to_string(), false),
        ],
    );
    let pass = queue(dir.path(), &state, TOKEN).tick().await.unwrap();
    assert_eq!((pass.sent, pass.rejected), (2, 0));
    assert!(state.sqlite.get_memory(client).unwrap().is_none());
    assert_eq!(
        state.sqlite.get_memory(existing).unwrap().unwrap().tier,
        Tier::Archived
    );
}

#[tokio::test]
async fn a_refused_token_keeps_every_entry() {
    let dir = queue_dir();
    let state = common::state();
    enqueue(
        dir.path(),
        &[
            remember(Uuid::new_v4(), "first"),
            remember(Uuid::new_v4(), "second"),
        ],
    );
    let pass = queue(dir.path(), &state, "stale-token")
        .tick()
        .await
        .unwrap();
    assert_eq!(pass.sent, 0);
    assert!(pass.stopped.unwrap().contains("401"));
    assert_eq!(entry_names(dir.path()).unwrap().len(), 2);
    assert_eq!(state.sqlite.memory_count().unwrap(), 0);
}

#[tokio::test]
async fn a_rejected_write_is_dropped_and_health_names_only_tool_status_and_time() {
    let dir = queue_dir();
    let state = common::state();
    let unknown = Uuid::new_v4().to_string();
    let after = Uuid::new_v4();
    enqueue(
        dir.path(),
        &[
            forget(&unknown, false),
            remember(after, "after the rejection"),
        ],
    );
    let pass = queue(dir.path(), &state, TOKEN).tick().await.unwrap();
    assert_eq!((pass.sent, pass.rejected), (1, 1));
    assert!(entry_names(dir.path()).unwrap().is_empty());
    assert!(state.sqlite.get_memory(after).unwrap().is_some());

    let body = health(&state).await;
    let rejected = &body["queue"]["last_rejected"];
    assert_eq!(rejected["tool"], "forget");
    assert_eq!(rejected["status"], 404);
    assert!(rejected["at"].is_string(), "{body}");
    assert!(!body.to_string().contains(&unknown), "{body}");
    assert!(!body.to_string().contains("no memory with id"), "{body}");
}

#[tokio::test]
async fn a_hard_forget_of_a_missing_row_counts_as_done() {
    let dir = queue_dir();
    let state = common::state();
    enqueue(dir.path(), &[forget(&Uuid::new_v4().to_string(), true)]);
    let pass = queue(dir.path(), &state, TOKEN).tick().await.unwrap();
    assert_eq!((pass.sent, pass.rejected), (1, 0));
    assert!(health(&state).await["queue"]["last_rejected"].is_null());
}

#[tokio::test]
async fn racing_replayers_send_each_entry_at_most_once() {
    let dir = queue_dir();
    let state = common::state();
    let entries: Vec<Entry> = (0..20)
        .map(|i| remember(Uuid::new_v4(), &format!("note {i}")))
        .collect();
    enqueue(dir.path(), &entries);

    let sent = Arc::new(AtomicUsize::new(0));
    let counted = |sent: Arc<AtomicUsize>| {
        second_brain_api::app(state.clone(), TOKEN.to_string()).layer(axum::middleware::from_fn(
            move |req, next: axum::middleware::Next| {
                let sent = sent.clone();
                async move {
                    sent.fetch_add(1, Ordering::SeqCst);
                    tokio::task::yield_now().await;
                    next.run(req).await
                }
            },
        ))
    };
    let replayer = |sent| {
        WriteQueue::new(
            dir.path().to_path_buf(),
            counted(sent),
            TOKEN.to_string(),
            state.health.clone(),
            state.gate.clone(),
        )
    };
    let (a, b) = (replayer(sent.clone()), replayer(sent.clone()));
    let (pa, pb) = tokio::join!(a.tick(), b.tick());
    let first = pa.or(pb).expect("one replayer took the lock");
    assert_eq!(first.sent, 20);
    let (pa, pb) = tokio::join!(a.tick(), b.tick());
    for pass in [pa, pb].into_iter().flatten() {
        assert_eq!(pass.sent, 0);
    }
    assert_eq!(sent.load(Ordering::SeqCst), 20);
    assert_eq!(state.sqlite.memory_count().unwrap(), 20);
}

#[tokio::test]
async fn health_reports_depth_and_degrades_on_a_stuck_queue() {
    let dir = queue_dir();
    let state = common::state();
    std::fs::write(
        dir.path().join(entry_name(Duration::from_secs(11 * 60))),
        serde_json::to_vec(&remember(Uuid::new_v4(), "stuck")).unwrap(),
    )
    .unwrap();
    enqueue(dir.path(), &[remember(Uuid::new_v4(), "behind it")]);
    queue(dir.path(), &state, "stale-token")
        .tick()
        .await
        .unwrap();

    let body = health(&state).await;
    assert_eq!(body["queue"]["depth"], 2);
    assert!(body["queue"]["oldest_age_secs"].as_i64().unwrap() >= 660);
    assert_eq!(body["state"], "degraded");
    assert!(
        body["reason"]
            .as_str()
            .unwrap()
            .contains("write queue not draining"),
        "{body}"
    );
}

#[tokio::test]
async fn a_forget_queued_while_its_remember_replays_reaches_the_stored_row() {
    let dir = queue_dir();
    let state = common::state();
    let existing = Uuid::new_v4();
    let stored = second_brain_core::schema::Memory {
        id: existing,
        ..second_brain_core::schema::Memory::new(
            "the cache lives on the ssd".to_string(),
            second_brain_core::schema::MemoryType::Semantic,
            "mcp-direct".to_string(),
            String::new(),
        )
    };
    state.sqlite.store_memory(&stored).unwrap();
    let client = Uuid::new_v4();
    enqueue(
        dir.path(),
        &[remember(client, "The cache lives on the SSD")],
    );

    let queue_path = dir.path().to_path_buf();
    let app =
        second_brain_api::app(state.clone(), TOKEN.to_string()).layer(axum::middleware::from_fn(
            move |req: axum::extract::Request, next: axum::middleware::Next| {
                if req.uri().path() == "/v1/remember" {
                    enqueue(&queue_path, &[forget(&client.to_string(), false)]);
                }
                next.run(req)
            },
        ));
    let replayer = WriteQueue::new(
        dir.path().to_path_buf(),
        app,
        TOKEN.to_string(),
        state.health.clone(),
        state.gate.clone(),
    );
    let first = replayer.tick().await.unwrap();
    assert_eq!(first.sent, 1);
    assert_eq!(entry_names(dir.path()).unwrap().len(), 1);
    let second = queue(dir.path(), &state, TOKEN).tick().await.unwrap();
    assert_eq!((second.sent, second.rejected), (1, 0));
    assert_eq!(
        state.sqlite.get_memory(existing).unwrap().unwrap().tier,
        Tier::Archived
    );
    assert!(health(&state).await["queue"]["last_rejected"].is_null());
}