Memories

A memory is a durable statement hlix carries between cycles — a convention, a decision, a lesson from something that failed. It is what stops the second cycle on a project from rediscovering what the first one already learned, and it is the surface where you write down knowledge that has no natural home in the code.

Memories are Workspace-wide knowledge, not project data. Every agency member can read and curate them; a client collaborator cannot see them at all.

Prerequisites

• A Workspace, and a role of owner, admin or member. Every route here refuses a client.
• A scope to attach the memory to — usually a project.

What a memory carries

Field	Values
scope	org, project, cycle, task, agent
scopeId	The id of that thing — the Workspace id for org
category	convention, decision, lesson, preference, failure, heuristic
key	A short handle, up to 200 characters
value	The statement itself, up to 10,000 characters
source	auto, user, interview, review — where it came from
confidence	0 to 1
status	tentative, approved, archived

Write one

curl -sS -X POST "$HLIX_BASE_URL/v1/api/memories" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID" \
  -H 'content-type: application/json' \
  -d '{
    "scope": "project",
    "scopeId": "'"$PROJECT_ID"'",
    "category": "convention",
    "key": "error-envelope",
    "value": "API errors always carry a stable machine-readable code alongside the message.",
    "status": "approved"
  }'

Expected result: 201 and the stored memory.

PATCH /v1/api/memories/{id} changes the value, the confidence or the status — the scope and category of an existing memory are fixed. DELETE /v1/api/memories/{id} removes one, and setting status to archived is the softer option when you want the record kept.

Read and search

curl -sS "$HLIX_BASE_URL/v1/api/memories?scope=project&scopeId=$PROJECT_ID&status=approved" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"

Expected result: 200 and the matching memories.

The list endpoint filters on scope, scopeId, status, a plain q text match and a limit. For ranked semantic search, use GET /v1/api/memories/search/{scope}/{scopeId}?q=…, which takes the same status and limit and returns entries ordered by similarity rather than by recency.

Filter by status on both endpoints

status narrows the search endpoint exactly as it narrows the list, so one status filter applies whether or not you search.

Where memories come from

Most are written by hlix rather than by you.

curl -sS -X POST "$HLIX_BASE_URL/v1/api/memories/extract/$CYCLE_ID" \
  -H "x-api-key: $HLIX_API_KEY" \
  -H "X-Organization-Id: $HLIX_WORKSPACE_ID"

Expected result: 200 and {"message": "Memory extraction started"}.

Extraction runs in the background, so the response confirms it started rather than what it found; list memories again for the result. Extracted memories arrive as tentative: a reading of a finished cycle is a candidate until someone approves it.

Approved and unreviewed are treated differently

The project manager and the planner read memories before they decide anything, and each entry carries its status: an approved memory is presented as settled, while anything else is marked unreviewed. An unreviewed entry never carries the weight of a decision someone made.

Curating has a direct effect: promoting a good tentative memory to approved changes how much weight it carries, and archiving a wrong one stops it being repeated.

If a memory is missing or not being used

• {"error":"Memory is restricted to the agency"} with 403. The caller is a client collaborator. Memories are Workspace knowledge spanning every project, so there is no narrowed client view — see Roles & permissions.
• {"error":"Not found"} with 404. No memory with that id in this Workspace.
• A 400 on create. Check the enums — scope, category, source and status each accept only the values in the table above, and value is capped at 10,000 characters.
• Extraction returned immediately and nothing appeared. It is a background job; the response only confirms it started. Re-list after a moment. A cycle with nothing worth recording produces nothing.
• An agent ignored a memory you wrote. Check its status. A tentative entry is presented as unreviewed and is weighted accordingly. Promote it to approved.
• A memory is right but attached to the wrong thing. Scope is fixed after creation. Write it at the correct scope and archive the old one.
• The list is dominated by low-value entries. Archive them. Extracted memories are candidates, and pruning them is the intended workflow.

Where to go next

If you want to…	Read
Understand everything an agent knows before a turn	Context, memory & DNA
Write a standard instead of a memory	Packs & skills
See the exact request and response shapes	Memories API
Check who may read this	Roles & permissions

Next steps

Context, memory & DNAHow memory, skills and identity compose into what an agent knows.

Packs & skillsStandards you write once, rather than knowledge hlix extracts.

Memories APIThe generated contract for every filter above.

Roles & permissionsWhy client collaborators are refused here entirely.