Retrieve facts by intent

POST

/v1/memory/retrieve

const url = 'https://example.com/v1/memory/retrieve';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"mode":"list","query":"example","type":"example","scope":{"tenantId":"example","userId":"example","orgId":"example","projectId":"example","threadId":"example","sessionId":"example","participantId":"example"},"limit":1,"embeddingModel":"example"}'
};

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/retrieve \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "mode": "list", "query": "example", "type": "example", "scope": { "tenantId": "example", "userId": "example", "orgId": "example", "projectId": "example", "threadId": "example", "sessionId": "example", "participantId": "example" }, "limit": 1, "embeddingModel": "example" }'

Retrieval over the facts the caller may see (as for listing), current revisions only. mode: list (newest first, no query), keyword (full-text), semantic (by meaning), or both (the two searches fused by rank: reciprocal rank fusion). Searching by meaning needs embeddings on the deployment (KINDGI_MEMORY_EMBEDDINGS); without them semantic and both answer 422 semantic-unavailable.

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

Retrieval intent — mirrors RetrievalIntent from @kindgi/agents, widened for direct-HTTP use. mode: "list" returns a plain scoped list (no query), newest first. mode: "keyword" runs full-text search. mode: "semantic" searches by meaning — it needs embeddings on the deployment; without them the route answers 422 semantic-unavailable. mode: "both" runs both and fuses them by rank (reciprocal rank fusion), as semantic needing embeddings.

object

mode

required

string

Allowed values: list keyword semantic both

query

Required for keyword / semantic / both; ignored for list.

string

type

string

>= 1 characters

scope

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

limit

integer

>= 1

embeddingModel

string

Responses

200

Retrieval results.

application/json

object

results

required

Array<object>

object

fact

required

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

score

Relevance score. Keyword mode returns an implementation-defined rank (higher = better). Semantic mode returns cosine similarity in [-1, 1] (higher = better). Both: the fused rank score, Σ 1/(60 + rank) (higher = better). Absent for list mode.

number

Example

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

400

Malformed intent.

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"
  }
}

409

Idempotency-Key was reused with a different body, or resource-state conflict.

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"
  }
}

422

semantic-unavailable: semantic or both asked to search by meaning, and the deployment has no embeddings (KINDGI_MEMORY_EMBEDDINGS).

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"
  }
}

501

memory-operation-unsupported: this runtime’s memory can’t retrieve by intent.

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"
  }
}

Retrieve facts by intent

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

409

Examplegenerated

413

Examplegenerated

422

Examplegenerated

500

Examplegenerated

501

Examplegenerated

See also

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated