encode | Brain Docs

Encode a memory

use brain_db_sdk::BrainHttpClient;
use brain_db_sdk::http::EncodeInput;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = BrainHttpClient::localhost("my-api-key");

    let out = client
        .encode(&EncodeInput {
            text: "Ada prefers dark mode and lives in Berlin.".to_string(),
            ..Default::default()
        })
        .await?;

    println!("memory {} (deduped: {})", out.memory_id, out.was_deduplicated);
    println!("salience {}, {} auto-edges", out.salience, out.auto_edges_added);
    Ok(())
}

use std::net::SocketAddr;
use brain_db_sdk::{Auth, BrainClient, EncodeBuilder};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let addr: SocketAddr = "127.0.0.1:9090".parse()?;
    let client = BrainClient::connect(addr, Auth::Token(b"my-token".to_vec())).await?;

    // The builder fills defaults and mints a request_id.
    let req = EncodeBuilder::new("Ada prefers dark mode and lives in Berlin.").build();
    let resp = client.encode(&req).await?;

    println!("memory {} (deduped: {})", resp.memory_id, resp.was_deduplicated);
    println!("salience {}, {} auto-edges", resp.salience, resp.auto_edges_added);
    Ok(())
}

Request fields

EncodeInput (all optional fields skip when None, so ..Default::default() is valid):

ParameterTypeRequired

textStringoptional

The memory text. Brain embeds it server-side.

contextOption<u64>optional

The context (namespace) the memory belongs to. Omit for the default context 0.

occurred_atOption<u64>optional

Event time in unix nanoseconds. Omit to let the server stamp ingest time.

Build the request with EncodeBuilder — it exposes just the knobs you tune and mints a fresh request_id:

use brain_db_sdk::EncodeBuilder;
use brain_db_sdk::wire::types::WaitMode;

let req = EncodeBuilder::new("Ada was promoted to staff engineer.")
    .context(42)                       // context id (default 0)
    .occurred_at(1_700_000_000_000_000_000) // event time, unix nanos
    .allow_duplicates(false)           // keep content dedup on (the default)
    .wait(WaitMode::Ack)               // return after the durable ack (default)
    .build();

ParameterTypeRequired

contextu64optional

Context id the memory belongs to. Defaults to 0.

occurred_atu64optional

Event time in unix nanoseconds. Unset means the server stamps ingest time.

allow_duplicatesbooloptional

Opt out of content dedup. Default false — see the dedup note below.

waitWaitModeoptional

Write-completion mode. Ack (default) returns after the durable WAL ack; Derived blocks until async derivation finishes and returns a populated trace.

The builder produces a wire EncodeRequest; you can also construct that struct directly if you need to set txn_id (to enroll the write in a transaction) or act_as.

The response

EncodeResult:

pub struct EncodeResult {
    pub memory_id: String,          // string over HTTP
    pub was_deduplicated: bool,
    pub salience: f32,
    pub kind: u8,
    pub created_at_unix_nanos: u64,
    pub auto_edges_added: u32,
}

EncodeResponse carries the HTTP fields plus wire-only detail (memory_id is numeric here):

pub struct EncodeResponse {
    pub memory_id: u128,            // numeric on the wire
    pub was_deduplicated: bool,
    pub salience: f32,
    pub auto_edges_added: u32,
    pub lsn: u64,
    pub agent_id: [u8; 16],
    pub context_id: u64,
    pub kind: MemoryKindWire,
    pub created_at_unix_nanos: u64,
    pub edges_out_count: u32,
    pub embedding_model_fp: [u8; 16],
    pub pending_stages: Vec<StageKind>,
    pub has_active_schema: bool,
    pub trace: Option<EncodeTrace>, // populated only with WaitMode::Derived
}

Content dedup is always on. Brain fingerprints text with BLAKE3 per (agent, context), so re-encoding byte-identical text returns the existing memory with was_deduplicated = true and writes nothing new. Set allow_duplicates(true) (wire) when the same text is a genuinely distinct observation that must coexist — for example the same fact re-stated at a different occurred_at.

On the wire, EncodeBuilder::new(text).wait_derived() is shorthand for .wait(WaitMode::Derived) — it blocks until async derivation completes and returns the full write trace (the extracted entities, statements, and relations) on EncodeResponse::trace.

Encode a memory

Request fields

The response

On this page