# Retrieve facts by intent

POST

/v1/memory/retrieve

```sh
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](https://docs.kindgi.com/v0.1.9/reference/api.md#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 Bodyrequired

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

**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

**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

```json
{
  "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

##### Examplegenerated

```json
{
  "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

##### Examplegenerated

```json
{
  "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

##### Examplegenerated

```json
{
  "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

##### Examplegenerated

```json
{
  "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

##### Examplegenerated

```json
{
  "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

##### Examplegenerated

```json
{
  "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

##### Examplegenerated

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

## See also

- [Memory reference](https://docs.kindgi.com/v0.1.9/guides/agents/memory-reference.md)
- [Error code `memory-operation-unsupported`](https://docs.kindgi.com/v0.1.9/reference/errors.md#memory-operation-unsupported)
- [Error code `request-too-large`](https://docs.kindgi.com/v0.1.9/reference/errors.md#request-too-large)
- [Error code `semantic-unavailable`](https://docs.kindgi.com/v0.1.9/reference/errors.md#semantic-unavailable)
- [Every error code](https://docs.kindgi.com/v0.1.9/reference/errors.md)