Memories

Generated from contract version 1.0.0 — the same document /v1/api/openapi.json 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
POST	/v1/api/memories	Write a memory
DELETE	/v1/api/memories/{id}	Delete a memory
GET	/v1/api/memories/{id}	Get one memory
PATCH	/v1/api/memories/{id}	Update a memory
POST	/v1/api/memories/extract/{cycleId}	Extract memories from a finished cycle
GET	/v1/api/memories/project/{projectId}	Read learned knowledge and recording availability for one project
GET	/v1/api/memories/search/{scope}/{scopeId}	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
confidence	number	no	min 0, max 1
key	string	yes	min length 1, max length 200
scope	org	project	cycle
scopeId	string	yes	min length 1
source	auto	user	interview
status	tentative	approved	archived
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
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 referenceEvery resource in the published contract, and what is deliberately not in it.

API & OpenAPIDownload the contract, generate a client, and read the compatibility policy.

TypeScript SDKAuth, retries, typed errors, uploads and streaming, already built.

CLI referenceThe same operations from a terminal, with a stable JSON envelope.