# Memories

Generated from contract version `1.0.0` — the same document [`/v1/api/openapi.json`](/api/openapi/) serves.

## Prerequisites

- An API key in `x-api-key`, or a browser session cookie
- `X-Organization-Id` naming the workspace to act in, unless the session already has an active one
- The base URL for your deployment, `https://server.hlix.ai` by default

## Operations

| Method | Path | Operation |
| --- | --- | --- |
| `GET` | `/v1/api/memories` | [List the workspace's memories](#list-the-workspaces-memories) |
| `POST` | `/v1/api/memories` | [Write a memory](#write-a-memory) |
| `DELETE` | `/v1/api/memories/{id}` | [Delete a memory](#delete-a-memory) |
| `GET` | `/v1/api/memories/{id}` | [Get one memory](#get-one-memory) |
| `PATCH` | `/v1/api/memories/{id}` | [Update a memory](#update-a-memory) |
| `POST` | `/v1/api/memories/extract/{cycleId}` | [Extract memories from a finished cycle](#extract-memories-from-a-finished-cycle) |
| `GET` | `/v1/api/memories/project/{projectId}` | [Read learned knowledge and recording availability for one project](#read-learned-knowledge-and-recording-availability-for-one-project) |
| `GET` | `/v1/api/memories/search/{scope}/{scopeId}` | [Search one scope by meaning](#search-one-scope-by-meaning) |

## List the workspace's memories

`GET /v1/api/memories` · operation ID `listMemories`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `scope` | query | no | string | `org` \| `project` \| `cycle` \| `task` \| `agent`. |
| `scopeId` | query | no | string | The scoped entity's id. |
| `status` | query | no | string | `tentative` \| `approved` \| `archived`. |
| `q` | query | no | string | Substring filter. This is a plain narrowing, NOT the semantic search — that is `/memories/search/{scope}/{scopeId}`, and only it returns `score`. |
| `limit` | query | no | string | Page size, clamped to 1–500. A non-integer is ignored and the store's own default applies. |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | Memory[] | The matching memories. No `score` — nothing was ranked. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.) |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Write a memory

`POST /v1/api/memories` · operation ID `createMemory`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `CreateMemory` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `category` | `convention` | `decision` | `lesson` | `preference` | `failure` | `heuristic` | **yes** |  |
| `confidence` | number | no | min 0, max 1 |
| `key` | string | **yes** | min length 1, max length 200 |
| `scope` | `org` | `project` | `cycle` | `task` | `agent` | **yes** |  |
| `scopeId` | string | **yes** | min length 1 |
| `source` | `auto` | `user` | `interview` | `review` | no |  |
| `status` | `tentative` | `approved` | `archived` | no |  |
| `supersededReason` | string | no | max length 2000 |
| `supersedesId` | string | no |  |
| `value` | string | **yes** | min length 1, max length 10000 |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `201` | Memory | The stored memory, read back from the store. |
| `400` | ValidationError \| ApiError | The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`). |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.) |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |
| `409` | ApiError | The supersession target is not a current memory in the same scope. |

## Delete a memory

`DELETE /v1/api/memories/{id}` · operation ID `deleteMemory`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | **yes** | string |  |
| `scope` | query | no | string | `org` \| `project` \| `cycle` \| `task` \| `agent`. |
| `scopeId` | query | no | string | The scoped entity's id. |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | MessageAck | The memory is gone. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.) |
| `404` | ApiError | No memory with that id in this workspace — under the named scope, or under any of them when none was named. |

## Get one memory

`GET /v1/api/memories/{id}` · operation ID `getMemory`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | **yes** | string |  |
| `scope` | query | no | string | `org` \| `project` \| `cycle` \| `task` \| `agent`. |
| `scopeId` | query | no | string | The scoped entity's id. |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | Memory | The memory. Without `scope` and `scopeId` every namespace is scanned, which is slower but always finds it. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.) |
| `404` | ApiError | No memory with that id in this workspace — under the named scope, or under any of them when none was named. |

## Update a memory

`PATCH /v1/api/memories/{id}` · operation ID `updateMemory`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `id` | path | **yes** | string |  |
| `scope` | query | no | string | `org` \| `project` \| `cycle` \| `task` \| `agent`. |
| `scopeId` | query | no | string | The scoped entity's id. |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Request body** — `application/json`, `UpdateMemory` (required)

| Property | Type | Required | Notes |
| --- | --- | --- | --- |
| `confidence` | number | no | min 0, max 1 |
| `status` | `tentative` | `approved` | `archived` | no |  |
| `supersededById` | string,null | no |  |
| `supersededReason` | string | null | no |  |
| `value` | string | no | min length 1, max length 10000 |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | Memory | The updated memory. `category`, `key` and `source` are immutable — they are carried over from the stored row. |
| `400` | ValidationError \| ApiError | The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`). |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.) |
| `404` | ApiError | No memory with that id in this workspace — under the named scope, or under any of them when none was named. |
| `409` | ApiError | The supersession target is not a current memory in the same scope. |

## Extract memories from a finished cycle

`POST /v1/api/memories/extract/{cycleId}` · operation ID `extractCycleMemories`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `cycleId` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | MessageAck | Extraction finished. Read the project knowledge disposition to distinguish saved, skipped and rejected scope results. Failed classifier, embedding or storage writes return an error. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.) |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## Read learned knowledge and recording availability for one project

`GET /v1/api/memories/project/{projectId}` · operation ID `getProjectKnowledge`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `projectId` | path | **yes** | string |  |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | ProjectKnowledge | Only this project's actual project, cycle and task scopes. |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.) |
| `404` | ApiError | No memory with that id in this workspace — under the named scope, or under any of them when none was named. |

## Search one scope by meaning

`GET /v1/api/memories/search/{scope}/{scopeId}` · operation ID `searchMemories`

**Parameters**

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `scope` | path | **yes** | string |  |
| `scopeId` | path | **yes** | string |  |
| `q` | query | no | string | The text to rank against. Omitted, the scope's memories come back unranked. |
| `status` | query | no | string | `tentative` \| `approved` \| `archived`. |
| `limit` | query | no | string | Page size, clamped to 1–500. |
| `X-Organization-Id` | header | no | string | The workspace (organization) to act in. Omitted, the session's active organization is used. |

**Responses**

| Status | Body | Description |
| --- | --- | --- |
| `200` | Memory[] | Memories ranked by similarity, each carrying `score` (cosine similarity, 1 − distance). |
| `400` | ApiError | The request named no active organization. |
| `401` | ApiError | No valid session or API key. |
| `403` | ApiError | The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.) |
| `404` | ApiError | The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist. |

## If a request fails

These apply to every operation on this page.

- `400` — the body failed schema validation, or the request named no active organization. A `ValidationError` body carries the failing fields; an `ApiError` body carries only `error`.
- `401` — no valid session or API key.
- `403` — authenticated, but not a member of the named organization, or a client collaborator without the required access.
- `404` — no such resource **in this workspace**. Absent and not-visible are deliberately the same answer; do not infer cross-tenant existence from it.
- `409` — the expected revision or state is stale, or another operation currently owns the transition.
- `500` — the operation failed server-side. Retry only where an idempotency key makes that safe.

## Next steps

[API reference](/api/reference/)
  [API & OpenAPI](/api/openapi/)
  [TypeScript SDK](/sdk/typescript/)
  [CLI reference](/reference/cli/)