# 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

```bash
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

```bash
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.

```bash
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](/security/roles-and-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](/concepts/context-memory/) |
| Write a standard instead of a memory | [Packs & skills](/configure/packs-and-skills/) |
| See the exact request and response shapes | [Memories API](/api/reference/memories/) |
| Check who may read this | [Roles & permissions](/security/roles-and-permissions/) |

## Next steps

[Context, memory & DNA](/concepts/context-memory/)
  [Packs & skills](/configure/packs-and-skills/)
  [Memories API](/api/reference/memories/)
  [Roles & permissions](/security/roles-and-permissions/)