# Memory

> The Memory operations of the Hub REST API (7 operations).

URL: https://docs.synap.live/docs/reference/hub-api/memory · Generated from Synap-core/backend@c31e261ab (main)

Paths are relative to `/api/hub` on a pod.

## GET /memory

Full-text search facts

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `userId` | query | string |  |  |
| `query` | query | string |  |  |
| `q` | query | string |  |  |
| `limit` | query | string |  |  |

Responses:

- `200`: Matching facts
- `400`: Bad request
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## POST /memory

Save a memory fact

Stores a user-scoped episodic fact. The embedding is optional — when omitted, a zero vector is used so agents without embedding access can still write facts. Supports `Idempotency-Key`.

Request body (`application/json`): CreateMemoryRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | string |  | Defaults to the authenticated agent's user when omitted. |
| `fact` | string | yes |  |
| `confidence` | number |  |  |
| `embedding` | array<number> |  | Optional 1536-d embedding. Falls back to a zero vector when omitted. |
| `sourceEntityId` | string |  |  |
| `sourceMessageId` | string |  |  |

Responses:

- `200`: Saved fact
- `400`: Bad request
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## POST /memory/search

Semantic search facts by embedding

Requires pgvector — disabled on shared pods.

Request body (`application/json`): MemorySearchRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | string | yes |  |
| `embedding` | array<number> | yes |  |
| `limit` | integer |  |  |

Responses:

- `200`: Matching facts
- `400`: Bad request
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## DELETE /memory/{id}

Delete a fact

Parameters:

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string | yes |  |
| `userId` | query | string | yes |  |

Responses:

- `200`: Deleted
- `400`: Bad request
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## POST /memory/turns

Store grouped chat turns

Stores user/assistant/system turns grouped by sessionId. Each turn is persisted as a tagged fact for semantic retrieval plus a summary fact.

Request body (`application/json`): MemoryTurnsRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | string |  | Defaults to the authenticated agent's user when omitted. |
| `sessionId` | string | yes | Session grouping ID. |
| `turns` | array<MemoryTurn> | yes |  |
| `summary` | string |  | Optional human-readable summary. |
| `confidence` | number |  |  |
| `embedding` | array<number> |  | Optional 1536-d embedding for the full session. Falls back to zero vector. |
| `sourceEntityId` | string |  |  |
| `sourceMessageId` | string |  |  |

Responses:

- `200`: Batch result
- `400`: Bad request
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## POST /memory/sessions

Store session metadata

Stores session metadata as a high-confidence fact for list/dedup purposes.

Request body (`application/json`): MemorySessionRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | string |  | Defaults to the authenticated agent's user when omitted. |
| `sessionId` | string | yes | Unique session ID. |
| `summary` | string | yes | Human-readable session summary. |
| `turnCount` | integer |  |  |
| `tags` | array<string> |  |  |
| `metadata` | object |  |  |
| `confidence` | number |  |  |

Responses:

- `200`: Session metadata stored
- `400`: Bad request
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error

## POST /memory/writes

Batch structured writes

Batch write of structured memory entries (remember/update/forget).

Request body (`application/json`): MemoryWritesRequest

| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | string |  | Defaults to the authenticated agent's user when omitted. |
| `entries` | array<object> | yes |  |
| `confidence` | number |  |  |

Responses:

- `200`: Batch result
- `400`: Bad request
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict — a refusal the caller can act on
- `412`: Precondition failed
- `500`: Internal error