Write a fact

POST

/v1/memory/facts

const url = 'https://example.com/v1/memory/facts';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"type":"example","scope":{"tenantId":"example","userId":"example","orgId":"example","projectId":"example","threadId":"example","sessionId":"example","participantId":"example"},"content":"example","retention":{"keepUntil":"2026-04-15T12:00:00Z","keepDays":1,"legalHold":true},"contentHash":"example","subjects":[{"kind":"participant","id":"example"}],"validFrom":"2026-04-15T12:00:00Z","validUntil":"2026-04-15T12:00:00Z","observedAt":"2026-04-15T12:00:00Z"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/memory/facts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "type": "example", "scope": { "tenantId": "example", "userId": "example", "orgId": "example", "projectId": "example", "threadId": "example", "sessionId": "example", "participantId": "example" }, "content": "example", "retention": { "keepUntil": "2026-04-15T12:00:00Z", "keepDays": 1, "legalHold": true }, "contentHash": "example", "subjects": [ { "kind": "participant", "id": "example" } ], "validFrom": "2026-04-15T12:00:00Z", "validUntil": "2026-04-15T12:00:00Z", "observedAt": "2026-04-15T12:00:00Z" }'

Persists a new fact. type selects the retrieval policy (which indexes populate). Semantic-indexed types require an embedding provider bound on the deployment; if unavailable, the route returns 400 bad-input. The caller needs write where the scope says: write on its project (an end user’s or a conversation’s fact included), write on its conversation outside a project, admin on its org for an org-wide fact, being that user for a user’s fact, and tenant admin for a tenant-wide fact. The fact records who wrote it (attributedTo).

Authorizations

bearerAuth

Parameters

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).

Request Body^required

application/json

Write a fact. type selects the retrieval-policy (which indexes populate); scope.tenantId MUST match the caller’s tenant. Optional retention overrides tenant defaults; optional contentHash is a caller-supplied idempotence hint (runtime computes its own hash regardless). subjects names whom it is about; validFrom/validUntil when it is true in the world; observedAt when it was said or seen.

object

type

required

string

>= 1 characters

scope

required

Fact scope object. tenantId is required; every optional key narrows the fact (userId, orgId, projectId, threadId, sessionId, participantId). A fact is readable by whoever has every container it names. Additional keys accepted for forward compatibility.

object

tenantId

required

string

userId

string

orgId

string

projectId

string

threadId

string

sessionId

string

participantId

An app’s end user, by the app’s own id: a fact private to that participant’s runs. Needs projectId.

string

>= 1 characters

key

additional properties

any

content

required

Free-form structured payload.

retention

object

keepUntil

string format: date-time

keepDays

integer

>= 1

legalHold

boolean

contentHash

string

subjects

Array<object>

<= 20 items

Whom a fact is about: what access and erasure requests by person find.

object

kind

required

string

Allowed values: participant user external

required

string

>= 1 characters

validFrom

string format: date-time

validUntil

string format: date-time

observedAt

string format: date-time

Responses

201

Fact written.

application/json

object

required

The fact id, kept across revisions (for a fact never superseded, also its one revision id).

string

revisionId

This revision’s own id; absent where it equals id.

string

type

required

Fact type identifier (pack-defined; a few are framework-standard).

string

scope

required

object

tenantId

required

string

userId

string

orgId

string

projectId

string

threadId

string

sessionId

string

participantId

An app’s end user, by the app’s own id: a fact private to that participant’s runs. Needs projectId.

string

>= 1 characters

key

additional properties

any

version

required

The revision number within the fact: 1, then one more per supersede or verify.

integer

>= 1

createdAt

required

string format: date-time

updatedAt

string format: date-time

content

Free-form structured payload.

contentRef

blob://<provider>/<bucket>/<key> when the payload is stored externally.

string

contentHash

string

size

integer

embeddingModel

string

retention

object

keepUntil

string format: date-time

keepDays

integer

>= 1

legalHold

boolean

source

object

kind

required

string

Allowed values: http-api blob mcp-tool external-db user-input

uri

string

freshness

required

object

ttlSeconds

integer

lastVerifiedAt

string format: date-time

etag

string

sourceVersion

string

refresh

required

object

strategy

required

string

Allowed values: on-read background manual

handler

string

priority

integer

causedByLogId

Array<string>

supersedes

The revision this one replaced.

string

trust

verified: a person with the right checked it. asserted: an app or a person wrote it. unverified: an agent remembered it during a conversation. Absent on facts from before trust was recorded: asserted.

string

Allowed values: verified asserted unverified

verifiedBy

string

verifiedAt

string format: date-time

attributedTo

Who asserted a fact, set by the server from the writer.

object

kind

required

string

Allowed values: user service agent

required

string

agentVersion

string

generatedBy

The run step that wrote a fact, for one an agent wrote.

object

runId

required

string

stepId

string

toolCallId

string

subjects

Array<object>

Whom a fact is about: what access and erasure requests by person find.

object

kind

required

string

Allowed values: participant user external

required

string

>= 1 characters

validFrom

When the fact starts being true in the world; absent: always.

string format: date-time

validUntil

When the fact stops being true in the world; absent: still true.

string format: date-time

observedAt

When it was said or seen.

string format: date-time

invalidatedAt

When this revision stopped being current; absent: it is current.

string format: date-time

invalidatedBy

user:<id> or service:<id>.

string

invalidationReason

string

Allowed values: superseded deleted erased expired

review

pending while a person must approve it: a pending fact is never retrieved.

string

Allowed values: pending

expiresAt

When this revision stops being readable: from its retention (keepUntil, or keepDays from the fact’s first write), or an agent-remembered fact’s unverified window. No read returns it after; absent: it doesn’t expire.

string format: date-time

Example

{
  "source": {
    "kind": "http-api",
    "refresh": {
      "strategy": "on-read"
    }
  },
  "trust": "verified",
  "attributedTo": {
    "kind": "user"
  },
  "subjects": [
    {
      "kind": "participant"
    }
  ],
  "invalidationReason": "superseded",
  "review": "pending"
}

400

Malformed body, or the fact type requires semantic indexing and no embedding provider is bound.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

permission-denied: the caller may not write in the fact’s scope.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Idempotency-Key was reused with a different body; or an erasure of the fact’s person (by scope or subject) or conversation is in progress (erasure-in-progress): nothing new is stored for them until it completes.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Server error (unmapped domain code or framework crash).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

Write a fact

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

409

Examplegenerated

413

Examplegenerated

500

Examplegenerated

See also

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated