encode | Brain Docs

Signature

POST/v1/memoriesAPI keybeta

// HTTP client
brain.encode(input: http.EncodeInput): Promise<http.EncodeResult>

// wire client
client.encode(request: EncodeRequest): Promise<EncodeResponse>

Request fields

The HTTP input is loose — only text is required.

ParameterTypeRequired

textstringrequired

The text to remember.

contextnumberoptional

Context id that scopes the memory (e.g. a conversation or session). Defaults to 0.

occurred_atnumberoptional

Unix-nanos wall-clock time the remembered event occurred. Omit to let Brain stamp write time.

The wire request mirrors the protocol field-for-field. Build it by hand or with EncodeBuilder, which fills defaults and mints the requestId.

ParameterTypeRequired

textstringrequired

The text to remember.

contextIdbigintrequired

Context id that scopes the memory. Use 0n for none.

requestIdUint8Arrayrequired

16-byte idempotency key. EncodeBuilder mints one for you.

txnIdUint8Array | nullrequired

Enclosing transaction id, or null for an autocommit write.

occurredAtUnixNanosbigint | nullrequired

Wall-clock time the event occurred, or null.

actAsActAs | nulloptional

Run as an effective (namespace, agentId) on behalf of the connection principal. null runs as the connection's own identity. Requires the canActAs grant.

waitWaitModeoptional

Write-completion mode. WaitMode.Ack (the default) returns after the durable ack; WaitMode.Derived blocks until async derivation finishes and the response carries the full write-analysis trace. This is the write knob.

allowDuplicatesbooleanoptional

Opt out of content dedup. By default Brain dedupes byte-identical text on (agentId, contextId, BLAKE3(text)) and returns the existing memory (wasDeduplicated = true) without writing. Set true to force a distinct memory.

Response fields

FieldTypePresence

memory_idstringalways

The id assigned to the memory.

was_deduplicatedbooleanalways

true when identical text already existed and no new memory was written.

saliencenumberalways

Initial salience score.

kindnumberalways

Memory-kind discriminant.

created_at_unix_nanosnumberalways

Write timestamp in unix-nanos.

auto_edges_addednumberalways

Count of similarity/temporal edges auto-added at write time.

The wire response carries the HTTP fields plus write-pipeline detail.

FieldTypePresence

memoryIdbigintalways

The id assigned to the memory (numeric on the wire).

wasDeduplicatedbooleanalways

true when identical text already existed.

saliencenumberalways

Initial salience.

autoEdgesAddednumberalways

Auto-added edge count.

lsnbigintalways

Log sequence number of the durable write — usable as a SUBSCRIBE cursor.

kindMemoryKindWirealways

Memory kind.

createdAtUnixNanosbigintalways

Write timestamp.

pendingStagesStageKind[]always

Async derivation stages still pending (auto-edge, temporal-edge, extractor).

hasActiveSchemabooleanalways

Whether a user schema is active on the shard.

traceEncodeTrace

Full synchronous write-analysis trace — present only when the request set wait = WaitMode.Derived.

Also returned: agentId, contextId, edgesOutCount, embeddingModelFp.

Examples

import { BrainHttpClient } from "@brain-db/sdk";

const brain = new BrainHttpClient({ apiKey: process.env.BRAIN_API_KEY! });

const res = await brain.encode({
  text: "I prefer dark mode and live in Berlin.",
  context: 42,
});
console.log(res.memory_id, res.was_deduplicated);

import { BrainClient, EncodeBuilder } from "@brain-db/sdk";

const client = await BrainClient.connect("127.0.0.1", 9090, {
  auth: { kind: "token", token: tokenBytes },
});

const res = await client.encode(
  new EncodeBuilder("I prefer dark mode and live in Berlin.")
    .context(42n)
    .build(),
);
console.log(res.memoryId, res.pendingStages);

On the wire client, call .wait() on the builder (equivalent to WaitMode.Derived) when you need the write to be fully derived — entities, statements, and relations extracted — before the call resolves, plus the populated trace.