Delete a fact

DELETE

/v1/memory/facts/{factId}

curl --request DELETE \
  --url https://example.com/v1/memory/facts/example \
  --header 'Authorization: Bearer <token>'

• Same-origin — path relative to the deployment root.

Closes the current revision (invalidationReason: deleted): the fact is no longer listed, fetched or retrieved, and its history stays readable until the retention sweep removes it.

Authorizations

• bearerAuth

Parameters

Path Parameters

factId

required

string

The fact id (kept across revisions).

Query Parameters

expectVersion

integer

>= 1

Only if the current revision is still this one; otherwise 409 fact-changed with currentVersion.

Responses

200

The closed revision.

Media typeapplication/json

object

id

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

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

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

id

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

id

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

expectVersion is not a revision number.

Media typeapplication/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.

Media typeapplication/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.

Media typeapplication/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"
  }
}

404

No fact with that id the caller may see, or it was deleted.

Media typeapplication/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

fact-changed: the current revision is not expectVersion; legal-hold: the fact is under legal hold.

Media typeapplication/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"
  }
}

501

memory-operation-unsupported: this runtime’s memory can’t delete facts.

Media typeapplication/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"
  }
}