second-brain-api 0.13.5

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

use axum::http::StatusCode;
use tower::ServiceExt;
use uuid::Uuid;

use common::{app_with_store, json_body, post_json};
use second_brain_core::schema::{Memory, MemoryType};
use second_brain_core::store::Store;

const EVIDENCE: &str = "crates/core/src/lib.rs:12";

fn stored(store: &second_brain_core::sqlite_store::SqliteStore, content: &str) -> Memory {
    let m = Memory::new(
        content.to_string(),
        MemoryType::Decision,
        "api".to_string(),
        String::new(),
    )
    .with_project_path(Some("-srv-garden".to_string()));
    store.store_memory(&m).unwrap();
    m
}

async fn correct(app: &axum::Router, body: serde_json::Value) -> (StatusCode, serde_json::Value) {
    let response = app
        .clone()
        .oneshot(post_json("/v1/correct", body))
        .await
        .unwrap();
    let status = response.status();
    (status, json_body(response).await)
}

async fn recall(app: &axum::Router, query: &str) -> Vec<serde_json::Value> {
    let response = app
        .clone()
        .oneshot(post_json("/v1/recall", serde_json::json!({"query": query})))
        .await
        .unwrap();
    assert_eq!(response.status(), StatusCode::OK);
    json_body(response).await["memories"]
        .as_array()
        .unwrap()
        .clone()
}

#[tokio::test]
async fn recall_drops_the_corrected_memory_and_marks_its_replacement_corrected() {
    let (app, store) = app_with_store();
    let old = stored(&store, "the garden daemon listens on port 7100");

    let (status, body) = correct(
        &app,
        serde_json::json!({
            "memory_id": old.id.to_string(),
            "content": "the garden daemon listens on port 7200",
            "evidence": EVIDENCE,
        }),
    )
    .await;

    assert_eq!(status, StatusCode::CREATED, "{body}");
    assert_eq!(body["corrects"], old.id.to_string());
    assert_eq!(body["replayed"], false);
    assert_eq!(body["memory_type"], "decision");
    assert_eq!(body["project_path"], "-srv-garden");
    let new_id = Uuid::parse_str(body["id"].as_str().unwrap()).unwrap();

    let found = recall(&app, "garden daemon listens").await;
    let ids: Vec<&str> = found.iter().map(|m| m["id"].as_str().unwrap()).collect();
    assert_eq!(ids, vec![new_id.to_string()]);
    assert!(found[0]["corrected_at"].is_string(), "{}", found[0]);
    assert_eq!(found[0]["project_path"], "-srv-garden");

    assert_eq!(
        store.correction_evidence(new_id).unwrap().as_deref(),
        Some(EVIDENCE)
    );
}

#[tokio::test]
async fn a_memory_that_replaced_nothing_carries_no_corrected_flag() {
    let (app, store) = app_with_store();
    stored(&store, "the orchard runs nightly backups");
    let found = recall(&app, "orchard runs nightly").await;
    assert_eq!(found.len(), 1);
    assert!(found[0].get("corrected_at").is_none(), "{}", found[0]);
}

#[tokio::test]
async fn evidence_outside_the_accepted_forms_is_a_400_naming_them() {
    let (app, store) = app_with_store();
    let old = stored(&store, "a wrong fact");
    for evidence in ["", "trust me", "src/lib.rs", "abc12"] {
        let (status, body) = correct(
            &app,
            serde_json::json!({"memory_id": old.id.to_string(), "content": "a right fact", "evidence": evidence}),
        )
        .await;
        assert_eq!(status, StatusCode::BAD_REQUEST, "{evidence:?}");
        let message = body["error"].as_str().unwrap();
        for form in ["path:line", "commit hash", "command line"] {
            assert!(message.contains(form), "{message}");
        }
    }
    assert_eq!(
        store.get_memory(old.id).unwrap().unwrap().superseded_by,
        None
    );
}

#[tokio::test]
async fn commit_and_command_evidence_are_accepted() {
    let (app, store) = app_with_store();
    for evidence in ["garden@3b14717", "$ cargo test -p garden\ntest result: ok"] {
        let old = stored(&store, "a stale fact");
        let (status, body) = correct(
            &app,
            serde_json::json!({"memory_id": old.id.to_string(), "content": "a fresh fact", "evidence": evidence}),
        )
        .await;
        assert_eq!(status, StatusCode::CREATED, "{evidence:?}: {body}");
    }
}

#[tokio::test]
async fn correcting_a_corrected_memory_is_a_409_naming_its_current_replacement() {
    let (app, store) = app_with_store();
    let old = stored(&store, "v1 of the fact");
    let (_, first) = correct(
        &app,
        serde_json::json!({"memory_id": old.id.to_string(), "content": "v2 of the fact", "evidence": "abc1234"}),
    )
    .await;

    let (status, body) = correct(
        &app,
        serde_json::json!({"memory_id": old.id.to_string(), "content": "v3 of the fact", "evidence": "abc1234"}),
    )
    .await;

    assert_eq!(status, StatusCode::CONFLICT);
    assert_eq!(body["current"], first["id"]);
    assert!(
        body["error"]
            .as_str()
            .unwrap()
            .contains(first["id"].as_str().unwrap())
    );
}

#[tokio::test]
async fn an_unknown_memory_is_a_404_and_a_retired_one_a_409() {
    let (app, store) = app_with_store();
    let (status, _) = correct(
        &app,
        serde_json::json!({"memory_id": Uuid::new_v4().to_string(), "content": "x", "evidence": "abc1234"}),
    )
    .await;
    assert_eq!(status, StatusCode::NOT_FOUND);

    let retired = stored(&store, "retired fact");
    store.retire_memory(retired.id, "wrong").unwrap();
    let (status, body) = correct(
        &app,
        serde_json::json!({"memory_id": retired.id.to_string(), "content": "x", "evidence": "abc1234"}),
    )
    .await;
    assert_eq!(status, StatusCode::CONFLICT);
    assert!(body["error"].as_str().unwrap().contains("retired"));
}

#[tokio::test]
async fn a_replayed_call_with_its_client_id_writes_nothing_new() {
    let (app, store) = app_with_store();
    let old = stored(&store, "v1");
    let client_id = Uuid::new_v4();
    let body = serde_json::json!({
        "memory_id": old.id.to_string(),
        "content": "v2",
        "evidence": "abc1234",
        "id": client_id.to_string(),
    });

    let (first, _) = correct(&app, body.clone()).await;
    let (again, replay) = correct(&app, body).await;

    assert_eq!(first, StatusCode::CREATED);
    assert_eq!(again, StatusCode::CREATED);
    assert_eq!(replay["replayed"], true);
    assert_eq!(replay["id"], client_id.to_string());
}

#[tokio::test]
async fn the_replacement_and_its_evidence_are_redacted() {
    let (app, store) = app_with_store();
    let old = stored(&store, "deploy uses the old token");
    let token = ["gh", "p_"].concat() + "Qq7k3Jd9XwL2pVb8NzR4tYc6MhF1sGa5UeT0";

    let (status, body) = correct(
        &app,
        serde_json::json!({
            "memory_id": old.id.to_string(),
            "content": format!("deploy uses {token}"),
            "evidence": format!("$ env\nTOKEN={token}"),
        }),
    )
    .await;

    assert_eq!(status, StatusCode::CREATED, "{body}");
    let new_id = Uuid::parse_str(body["id"].as_str().unwrap()).unwrap();
    let new = store.get_memory(new_id).unwrap().unwrap();
    assert!(!new.content.contains(&token), "{}", new.content);
    let context = store.correction_evidence(new_id).unwrap().unwrap();
    assert!(!context.contains(&token), "{context}");
}

#[tokio::test]
async fn a_full_commit_hash_is_kept_as_evidence() {
    let (app, store) = app_with_store();
    let old = stored(&store, "a stale fact");
    let hash = "3b14717b4d6586486f180154297a391cdbfde686";
    let (status, body) = correct(
        &app,
        serde_json::json!({"memory_id": old.id.to_string(), "content": "a fresh fact", "evidence": hash}),
    )
    .await;
    assert_eq!(status, StatusCode::CREATED, "{body}");
    let new_id = Uuid::parse_str(body["id"].as_str().unwrap()).unwrap();
    assert_eq!(
        store.correction_evidence(new_id).unwrap().as_deref(),
        Some(hash)
    );
}

#[tokio::test]
async fn a_source_another_route_owns_is_refused_as_remember_refuses_it() {
    let (app, store) = app_with_store();
    let old = stored(&store, "a stale fact");
    for source in ["markdown", "agent-note", "claude-code"] {
        let (status, body) = correct(
            &app,
            serde_json::json!({"memory_id": old.id.to_string(), "content": "a fresh fact", "evidence": "abc1234", "source": source}),
        )
        .await;
        assert_eq!(status, StatusCode::BAD_REQUEST, "{source}: {body}");
        assert!(
            body["error"]
                .as_str()
                .unwrap()
                .starts_with("correct accepts only")
        );
    }
}

#[tokio::test]
async fn the_replacement_keeps_its_call_time_and_links_what_it_mentions() {
    let (app, store) = app_with_store();
    let old = stored(&store, "billing runs on postgres");
    let at = "2026-10-01T09:30:00+00:00";

    let (status, body) = correct(
        &app,
        serde_json::json!({
            "memory_id": old.id.to_string(),
            "content": "billing moved from postgres to sqlite",
            "evidence": "abc1234",
            "session_at": at,
        }),
    )
    .await;

    assert_eq!(status, StatusCode::CREATED, "{body}");
    let new_id = Uuid::parse_str(body["id"].as_str().unwrap()).unwrap();
    let new = store.get_memory(new_id).unwrap().unwrap();
    assert_eq!(new.session_at.unwrap().to_rfc3339(), at);
    let mentioned: Vec<String> = store
        .get_relations(
            new_id,
            Some(second_brain_core::schema::RelationType::Mentions),
        )
        .unwrap()
        .into_iter()
        .map(|r| store.get_entity(r.to_id).unwrap().unwrap().name)
        .collect();
    assert!(mentioned.iter().any(|n| n == "sqlite"), "{mentioned:?}");
}