Metadata only

Some companies cannot let tool arguments, results or the documents an agent wrote leave their own infrastructure: the text of a lawsuit, a quote with health data, a contract. The pointer mode serves that without losing what the record gives: the SDK writes each value to your bucket, with your credentials, and sends Niadra only the pointer and the digest. Niadra keeps the turn’s frame (what was read, called, claimed and decided, with the pins) and never a value; replay and claim verification read the values back inside your company, by digest.

The three modes

Mode	What leaves your company	What Niadra keeps	Replay
`stored`	The values, encrypted; the text leaves go through the events’ masking rules and, with `pii_model`, through the personal data model	The whole record	Yes
`pointer`	The pointer (`s3://...`) and the SHA-256 of each value	The frame, the pointers and the digests	Yes, inside your company
`hash_only`	Only the SHA-256	The frame and the digests	No; statistics and structural assertions

The mode is space configuration, in the recording document (the integration role): a default mode and, optionally, one per source. A source may always keep less than the space allows, never more: a turn sent in a mode that keeps more is refused with content_mode_refused, and the SDK sends it again with digests only. Changing the mode to one that keeps more also needs the security role. A bronze record, from OpenTelemetry, is hash_only by default.

Turning on `pointer` mode in the SDK

The SDK picks the mode in this order: content_mode of the turn options, when you fix it; pointer as soon as a store is configured; the mode the space’s recording names for the source; stored. The upload runs on the sender, in the background, never on the agent’s path.

from niadra import Niadra

niadra = Niadra()
niadra.turns.store(s3_bucket="s3://acme-agent-turns/prod")  # boto3, with your credentials from the environment
# or any callable put(key, data) -> pointer
niadra.turns.store(put=lambda key, data: my_store.write(key, data))

import { Niadra } from "@niadra/sdk";
import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";

const niadra = new Niadra();
const s3 = new S3Client({});
niadra.turns.store(async (key, data) => {
  await s3.send(new PutObjectCommand({ Bucket: "acme-agent-turns", Key: `prod/${key}`, Body: data, ContentType: "application/json" }));
  return `s3://acme-agent-turns/prod/${key}`;
});

Each value goes to <turn_id>/<blob>.json, as canonical JSON (RFC 8785), and the pointer returned enters the record next to the digest. A record whose blobs could not all be written leaves as hash_only, partial, instead of waiting. The digest is the SHA-256 of the value’s canonical JSON, so the same value has the same digest in any producer; before computing it, the SDK may apply the normalizers the space’s recording declares, to drop an order id or a timestamp that changes on every call, so a call’s args_hash matches across replays.

What Niadra still sees

The frame: the turn, the agent, the kind, the times, the build and the pins, what was read by version, the calls with their name, args_hash, latency and state, the typed state observations with their provenance (the values of observed fields are part of the frame, because they are your objects’ state, not content), the interactions, the claim verdicts, the coordination decisions and effects, the ids of the conversation’s events and the flags. What Niadra does not see: the arguments, the results, the text of the reads, the documents written. A pointer or hash_only record is taken even with Niadra’s storage unavailable, because the frame is all of it; deduplication by turn_id happens once the storage is back.

Replay inside your company

In a replay, the case carries the record with the pointers and the digests, and the runner reads each pointer with the SDK’s content resolver, with your credentials, and checks the digest before using it: a value that cannot be read or does not match is an infrastructure error, never a failing assertion.

import boto3

s3 = boto3.client("s3")

def fetch(pointer: str) -> bytes:
    bucket, key = pointer.removeprefix("s3://").split("/", 1)
    return s3.get_object(Bucket=bucket, Key=key)["Body"].read()

niadra.content.register(fetch)  # the Replayer reads pointers through it

import { GetObjectCommand } from "@aws-sdk/client-s3";

niadra.content.register(async (pointer) => {
  const [bucket, key] = pointer.replace("s3://", "").split(/\/(.+)/);
  const object = await s3.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
  return await object.Body!.transformToString();
});

The pack of the time is the blob of the record’s pack read, read the same way. The case also carries the conversation’s history masked, so the runner has everything it needs without any recorded value passing through Niadra on the way back.

Third-party content by pointer

The same holds for the content fields of declared types: with content.mode: pointer, a court’s text or a document stays in your storage, and a state read carries only the content marker (mode, sha256, pointer, scan). niadra.content.fill(context) fills the state view with the texts, checking each digest, and the text enters the prompt inside the <niadra-data> envelope, like any third-party content. Content by pointer stays pending when the type requires a scan (scan: required), because Niadra cannot read it: the scan, in that case, is yours, or the type uses scan: rules over what arrives in clear.

Counterfactual and anchors

The tool counterfactual runs the recorded calls live inside your company and reports positions and overlaps only, so it works the same in any mode. The claim contract’s text anchor compares the quote with the document the runner has in hand, put back by pointer.

What stays with Niadra in each mode

	`stored`	`pointer`	`hash_only`
Turn frame, pins, flags	yes	yes	yes
Tool arguments and results	encrypted and masked	pointer and digest	digest
Text of the context read	encrypted	pointer and digest	digest
Typed state observations	yes	yes	yes
Claim verdicts, decisions, effects, interactions	yes	yes	yes
The day’s index for your audit chain	yes	yes	yes
Retention	the tier’s; erasing a person erases their turns by the conversation’s prefix	the tier’s at Niadra; in your bucket, yours	the tier’s

Next steps

Turn records

the content modes and the SDK’s queue.

Replay in your CI

the runner that reads the pointers back.

The resolver worker

the content resolver and the state one.

Privacy

where each copy lives and for how long.

Agents

By sector

Integrations

Operations

The three modes

Turning on `pointer` mode in the SDK

What Niadra still sees

Replay inside your company

Third-party content by pointer

Counterfactual and anchors

What stays with Niadra in each mode

Next steps

Turn records

Replay in your CI

The resolver worker

Privacy

​The three modes

​Turning on pointer mode in the SDK

​What Niadra still sees

​Replay inside your company

​Third-party content by pointer

​Counterfactual and anchors

​What stays with Niadra in each mode

​Next steps

Turn records

Replay in your CI

The resolver worker

Privacy

The three modes

Turning on `pointer` mode in the SDK

What Niadra still sees

Replay inside your company

Third-party content by pointer

Counterfactual and anchors

What stays with Niadra in each mode

Next steps