Encode | Brain Docs

HTTP

POST/v1/memoriesBearerstable

client.encode(
    text: str,
    context: int | None = None,
    occurred_at: int | None = None,
) -> EncodeResult

ParameterTypeRequired

textstrrequired

The memory text. Brain embeds it server-side.

contextint | Noneoptional

Context id to store the memory under. Omitted when None.

occurred_atint | Noneoptional

Event time in Unix nanoseconds — when the thing the text describes happened, distinct from ingest time. Omitted when None.

from brain_db_sdk import BrainHttpClient

client = BrainHttpClient("sk-...", base_url="https://api.arc-labs.ai")
result = client.encode("Ada moved to Berlin.", occurred_at=1710000000000000000)
print(result.memory_id, result.was_deduplicated, result.salience)

encode is idempotent on the HTTP client and is retried per the policy.

Wire

The wire client takes an EncodeRequest. Build it with EncodeBuilder, which fills the defaults and mints a fresh request_id:

token / mTLSstable

client.encode(request: EncodeRequest) -> EncodeResponse

from brain_db_sdk import BrainClient, Auth, EncodeBuilder, WaitMode

with BrainClient.connect("127.0.0.1", 9090, Auth.token(b"my-token")) as client:
    req = (
        EncodeBuilder("Ada moved to Berlin.")
        .context(0)
        .occurred_at(1710000000000000000)
        .build()
    )
    resp = client.encode(req)
    print(resp.memory_id, resp.was_deduplicated, resp.pending_stages)

EncodeBuilder knobs

OptionTypeDefault / Env

.context(context_id)int

Store under a specific context id instead of the default 0.

.occurred_at(unix_nanos)int | None

Record the event time (distinct from ingest time).

.wait(mode)WaitMode

Write-completion mode. WaitMode.ACK (default) returns as soon as the write is durable; the async derivation stages run in the background. WaitMode.DERIVED blocks until they complete and the response carries a populated trace.

.derived()shorthand

Convenience for .wait(WaitMode.DERIVED).

.allow_duplicates(allow=True)bool

Opt out of content dedup and force a distinct memory. By default Brain dedupes byte-identical text on (agent_id, context_id, BLAKE3(text)) and returns the existing memory (was_deduplicated = True) without writing.

.act_as(namespace, agent_id)str, bytes

Run the write as an effective identity on behalf of the connection principal. Requires can_act_as, else the server rejects with ActAsDenied.

The write knob is wait (a WaitMode), not trace. Writes carry wait; reads carry trace (a bool). They are never both on one op.

Dedup

Content dedup is always on for text encode: Brain fingerprints the text with BLAKE3 per (shard, agent, context) and, on a byte-identical repeat, returns the existing memory with was_deduplicated = True instead of writing a new one. Pass allow_duplicates (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.

Response shape

The HTTP EncodeResult and wire EncodeResponse share the core fields; the wire response adds lower-level write-path detail.

FieldTypePresence

memory_idstr (HTTP) / int (wire)always

The stored memory's id.

was_deduplicatedboolalways

True when an existing byte-identical memory was returned instead of a new write.

saliencefloatalways

The server-assigned salience.

kindintalways

The classified memory kind (integer discriminant).

created_at_unix_nanosintalways

Ingest time.

auto_edges_addedintalways

How many edges the write auto-derived.

pending_stageslist[int]

Wire only. The background derivation stages still to run (observable via subscribe on lsn).

traceEncodeTrace | None

Wire only. Present when WaitMode.DERIVED was requested — the full synchronous write-analysis timeline.

The wire EncodeResponse also carries lsn, agent_id, context_id, edges_out_count, embedding_model_fp, and has_active_schema.