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, get, json_body, post_json};
use second_brain_core::schema::{RelationType, Scope};
use second_brain_core::store::Store;

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

fn id_of(body: &serde_json::Value) -> Uuid {
    Uuid::parse_str(body["id"].as_str().unwrap()).unwrap()
}

#[tokio::test]
async fn a_duplicate_with_a_project_is_refiled_under_it() {
    let (app, store) = app_with_store();
    let first = remember(
        &app,
        serde_json::json!({"content": "deploys go through argo"}),
    )
    .await;

    let again = remember(
        &app,
        serde_json::json!({"content": "Deploys go through Argo", "project": "infrastructure"}),
    )
    .await;
    assert_eq!(again["duplicate"], true);
    assert_eq!(again["id"], first["id"]);
    assert_eq!(again["project_updated"], true);
    let stored = store.get_memory(id_of(&first)).unwrap().unwrap();
    assert_eq!(stored.project_path.as_deref(), Some("infrastructure"));

    let same = remember(
        &app,
        serde_json::json!({"content": "deploys go through argo", "project": "infrastructure"}),
    )
    .await;
    assert_eq!(same["project_updated"], false);
}

#[tokio::test]
async fn a_duplicate_without_a_project_keeps_the_stored_one() {
    let (app, store) = app_with_store();
    let first = remember(
        &app,
        serde_json::json!({"content": "the nas runs tos 6", "project": "haurka"}),
    )
    .await;
    let again = remember(&app, serde_json::json!({"content": "the nas runs tos 6"})).await;
    assert_eq!(again["duplicate"], true);
    assert_eq!(again["project_updated"], false);
    let stored = store.get_memory(id_of(&first)).unwrap().unwrap();
    assert_eq!(stored.project_path.as_deref(), Some("haurka"));
}

#[tokio::test]
async fn remember_links_extracted_and_named_entities() {
    let (app, store) = app_with_store();
    let body = remember(
        &app,
        serde_json::json!({
            "content": "billing moved from postgres to sqlite",
            "related_to": ["billing-v2"],
        }),
    )
    .await;
    let id = id_of(&body);
    assert_eq!(body["entities"], 3);

    let mentioned: Vec<String> = store
        .get_relations(id, Some(RelationType::Mentions))
        .unwrap()
        .into_iter()
        .map(|r| store.get_entity(r.to_id).unwrap().unwrap().name)
        .collect();
    for name in ["postgres", "sqlite", "billing-v2"] {
        assert!(mentioned.iter().any(|n| n == name), "{name}: {mentioned:?}");
    }

    let second = remember(
        &app,
        serde_json::json!({"content": "sqlite needs WAL mode", "related_to": ["billing-v2"]}),
    )
    .await;
    let reused = store.find_entity_by_name("billing-v2").unwrap().unwrap();
    assert!(
        store
            .get_relations(id_of(&second), Some(RelationType::Mentions))
            .unwrap()
            .iter()
            .any(|r| r.to_id == reused.id),
        "a named entity that already exists is reused, not duplicated"
    );
}

#[tokio::test]
async fn remember_only_accepts_sources_consolidation_leaves_alone() {
    let (app, store) = app_with_store();
    let cli = remember(
        &app,
        serde_json::json!({"content": "noted from the terminal", "source": "cli"}),
    )
    .await;
    assert_eq!(
        store.get_memory(id_of(&cli)).unwrap().unwrap().source,
        "cli"
    );

    let response = app
        .clone()
        .oneshot(post_json(
            "/v1/remember",
            serde_json::json!({"content": "posing as a transcript", "source": "claude-code"}),
        ))
        .await
        .unwrap();
    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
    let body = json_body(response).await;
    assert!(
        body["error"].as_str().unwrap().contains("mcp-direct"),
        "{body}"
    );
}

#[tokio::test]
async fn remember_refuses_the_source_vault_sync_owns() {
    let (app, _store) = app_with_store();
    let response = app
        .clone()
        .oneshot(post_json(
            "/v1/remember",
            serde_json::json!({"content": "posing as a vault note", "source": "markdown"}),
        ))
        .await
        .unwrap();
    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
    let body = json_body(response).await;
    let error = body["error"].as_str().unwrap();
    assert!(
        !error.contains("markdown,") && !error.ends_with("markdown)"),
        "{body}"
    );
}

#[tokio::test]
async fn remember_refuses_the_source_notes_own() {
    let (app, _store) = app_with_store();
    let response = app
        .clone()
        .oneshot(post_json(
            "/v1/remember",
            serde_json::json!({"content": "posing as a note", "source": "agent-note"}),
        ))
        .await
        .unwrap();
    assert_eq!(response.status(), StatusCode::BAD_REQUEST);
    let body = json_body(response).await;
    let error = body["error"].as_str().unwrap();
    let listed = error.split(['(', ')']).nth(1).unwrap();
    assert!(!listed.split(", ").any(|s| s == "agent-note"), "{body}");
}

async fn remember_status(app: &axum::Router, body: serde_json::Value) -> StatusCode {
    app.clone()
        .oneshot(post_json("/v1/remember", body))
        .await
        .unwrap()
        .status()
}

#[tokio::test]
async fn a_client_id_and_session_date_are_kept() {
    let (app, store) = app_with_store();
    let id = Uuid::new_v4();
    let reply = remember(
        &app,
        serde_json::json!({
            "content": "queued while the daemon was down",
            "id": id.to_string(),
            "session_at": "2026-10-30T08:15:00Z",
        }),
    )
    .await;
    assert_eq!(id_of(&reply), id);
    assert_eq!(reply["duplicate"], false);
    let stored = store.get_memory(id).unwrap().unwrap();
    assert_eq!(
        stored.session_at.unwrap().to_rfc3339(),
        "2026-10-30T08:15:00+00:00"
    );
}

#[tokio::test]
async fn the_same_remember_sent_twice_gives_one_row() {
    let (app, store) = app_with_store();
    let body = serde_json::json!({
        "content": "replayed note",
        "id": Uuid::new_v4().to_string(),
    });
    let first = remember(&app, body.clone()).await;
    let again = remember(&app, body).await;
    assert_eq!(again["id"], first["id"]);
    assert_eq!(again["duplicate"], true);
    assert_eq!(store.memory_count().unwrap(), 1);
}

#[tokio::test]
async fn a_known_id_wins_over_the_content_check_and_writes_nothing() {
    let (app, store) = app_with_store();
    let id = Uuid::new_v4();
    remember(
        &app,
        serde_json::json!({"content": "original text", "id": id.to_string()}),
    )
    .await;
    let other = remember(&app, serde_json::json!({"content": "other text"})).await;
    let again = remember(
        &app,
        serde_json::json!({"content": "other text", "id": id.to_string(), "related_to": ["argo"]}),
    )
    .await;
    assert_eq!(id_of(&again), id);
    assert_eq!(again["duplicate"], true);
    assert_eq!(again["entities"], 0);
    assert_ne!(again["id"], other["id"]);
    assert_eq!(
        store.get_memory(id).unwrap().unwrap().content,
        "original text"
    );
    assert_eq!(store.memory_count().unwrap(), 2);
}

#[tokio::test]
async fn a_new_id_with_known_content_lands_as_the_existing_row() {
    let (app, _store) = app_with_store();
    let first = remember(&app, serde_json::json!({"content": "same words"})).await;
    let again = remember(
        &app,
        serde_json::json!({"content": "same words", "id": Uuid::new_v4().to_string()}),
    )
    .await;
    assert_eq!(again["id"], first["id"]);
    assert_eq!(again["duplicate"], true);
}

#[tokio::test]
async fn a_remember_for_a_retired_id_returns_it_and_leaves_it_retired() {
    let (app, store) = app_with_store();
    let id = Uuid::new_v4();
    let body = serde_json::json!({"content": "retired before replay", "id": id.to_string()});
    remember(&app, body.clone()).await;
    store.retire_memory(id, "wrong").unwrap();
    let again = remember(&app, body).await;
    assert_eq!(id_of(&again), id);
    assert_eq!(again["duplicate"], true);
    assert_eq!(
        store.get_memory(id).unwrap().unwrap().tier,
        second_brain_core::schema::Tier::Archived
    );
}

#[tokio::test]
async fn a_remember_for_a_tombstoned_id_writes_nothing() {
    let (app, store) = app_with_store();
    let id = Uuid::new_v4();
    let body = serde_json::json!({"content": "hard forgotten", "id": id.to_string()});
    remember(&app, body.clone()).await;
    assert!(store.remove_memory(id).unwrap());
    let again = remember(&app, body).await;
    assert_eq!(id_of(&again), id);
    assert_eq!(again["duplicate"], true);
    assert!(store.get_memory(id).unwrap().is_none());
    assert_eq!(store.memory_count().unwrap(), 0);
}

#[tokio::test]
async fn a_malformed_id_or_session_date_is_refused() {
    let (app, _store) = app_with_store();
    for body in [
        serde_json::json!({"content": "x", "id": "not-a-uuid"}),
        serde_json::json!({"content": "x", "session_at": "yesterday"}),
    ] {
        assert_eq!(remember_status(&app, body).await, StatusCode::BAD_REQUEST);
    }
}

#[tokio::test]
async fn remembering_a_vault_notes_text_stores_its_own_row() {
    let (app, store) = app_with_store();
    let mut note = second_brain_core::schema::Memory::new(
        "Deploy\n\nruns at noon".to_string(),
        second_brain_core::schema::MemoryType::Semantic,
        "markdown".to_string(),
        "/vault/Deploy.md".to_string(),
    );
    note.machine_id = "smoke".to_string();
    store.store_memory(&note).unwrap();

    let reply = remember(
        &app,
        serde_json::json!({"content": "Deploy\n\nruns at noon"}),
    )
    .await;

    assert_eq!(reply["duplicate"], false);
    assert_ne!(id_of(&reply), note.id);
    assert_eq!(
        store.get_memory(id_of(&reply)).unwrap().unwrap().source,
        "api"
    );
}

#[tokio::test]
async fn remember_records_the_author_and_the_scope_asked_for() {
    let (app, store) = app_with_store();
    let private = remember(&app, serde_json::json!({"content": "kept to myself"})).await;
    let shared = remember(
        &app,
        serde_json::json!({"content": "the whole team should know", "scope": "shared"}),
    )
    .await;

    let author = format!("device:{}", store.machine_id());
    let stored = store.get_memory(id_of(&shared)).unwrap().unwrap();
    assert_eq!(stored.scope, Scope::Shared);
    assert_eq!(stored.author.as_deref(), Some(author.as_str()));
    assert_eq!(
        store.get_memory(id_of(&private)).unwrap().unwrap().scope,
        Scope::Private
    );

    let response = app
        .clone()
        .oneshot(get(&format!("/v1/memory/{}", id_of(&shared))))
        .await
        .unwrap();
    assert_eq!(response.status(), StatusCode::OK);
    let body = json_body(response).await;
    assert_eq!(body["scope"], "shared");
    assert_eq!(body["author"], author.as_str());
}

#[tokio::test]
async fn remember_refuses_an_unknown_scope() {
    let (app, store) = app_with_store();
    let status = remember_status(
        &app,
        serde_json::json!({"content": "for my eyes", "scope": "team"}),
    )
    .await;
    assert_eq!(status, StatusCode::BAD_REQUEST);
    assert_eq!(store.memory_count().unwrap(), 0);
}

#[tokio::test]
async fn a_duplicate_asked_into_another_scope_moves_there() {
    let (app, store) = app_with_store();
    let first = remember(&app, serde_json::json!({"content": "builds run nightly"})).await;

    let unscoped = remember(&app, serde_json::json!({"content": "builds run nightly"})).await;
    assert_eq!(unscoped["scope_updated"], false);
    let shared = remember(
        &app,
        serde_json::json!({"content": "builds run nightly", "scope": "shared"}),
    )
    .await;
    assert_eq!(shared["duplicate"], true);
    assert_eq!(shared["scope_updated"], true);
    assert_eq!(
        store.get_memory(id_of(&first)).unwrap().unwrap().scope,
        Scope::Shared
    );
    let again = remember(&app, serde_json::json!({"content": "builds run nightly"})).await;
    assert_eq!(again["scope_updated"], false);
    assert_eq!(
        store.get_memory(id_of(&first)).unwrap().unwrap().scope,
        Scope::Shared
    );
}