# Memories

Retrieve user memory entries extracted from conversations.

---

Memories are facts and preferences your AVCodex agent has learned about individual consumers (techs, programmers, dealer-program partners) through conversations. They drive personalized responses across sessions.

> **Note:** Embedding vectors are never exposed through this endpoint. Only the human-readable memory content is returned.

## List memories

```
GET /api/v1/apps/{appId}/memories
```

Returns a paginated list of memory entries. Uses offset-based pagination.

### Query parameters

| Parameter      | Type    | Default | Description                                          |
|----------------|---------|---------|------------------------------------------------------|
| `limit`        | integer | 25      | Results per page (1-100).                            |
| `offset`       | integer | 0       | Number of results to skip.                           |
| `consumer_id`  | UUID    | -       | Filter memories for a specific consumer.             |
| `memory_type`  | string  | -       | Filter by memory type.                               |
| `memory_layer` | string  | -       | Filter by memory layer: `episodic` or `fact`.        |

### Example

```bash
curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/memories?consumer_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"
```

### Response

```json
{
  "data": [
    {
      "id": "mem-001",
      "consumer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "external_user_id": null,
      "content": "Prefers concise step-by-step answers over long explanations.",
      "memory_type": "preference",
      "memory_layer": "fact",
      "confidence": 0.92,
      "source_message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2025-06-10T14:00:00Z",
      "updated_at": "2025-06-15T09:30:00Z"
    },
    {
      "id": "mem-002",
      "consumer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "external_user_id": "usr_12345",
      "content": "Works at Acme AV Integrators as a Crestron programmer.",
      "memory_type": "background",
      "memory_layer": "fact",
      "confidence": 0.85,
      "source_message_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "session_id": "660f9511-f30c-52e5-b827-557766551111",
      "created_at": "2025-06-12T10:15:00Z",
      "updated_at": "2025-06-12T10:15:00Z"
    },
    {
      "id": "mem-003",
      "consumer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "external_user_id": null,
      "content": "Asked about Q-SYS Reflect for managed services and seemed interested in dealer pricing.",
      "memory_type": "interaction",
      "memory_layer": "episodic",
      "confidence": 0.78,
      "source_message_id": null,
      "session_id": "771a0622-a41d-63f7-d938-668877662222",
      "created_at": "2025-06-14T16:45:00Z",
      "updated_at": "2025-06-14T16:45:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "total": 3,
    "limit": 25,
    "offset": 0
  }
}
```

### Response fields

| Field               | Type              | Description                                                                              |
|---------------------|-------------------|------------------------------------------------------------------------------------------|
| `id`                | string            | Unique memory identifier.                                                                |
| `consumer_id`       | UUID              | The consumer this memory belongs to.                                                     |
| `external_user_id`  | string or null    | External user identifier.                                                                |
| `content`           | string            | Human-readable memory text.                                                              |
| `memory_type`       | string            | Category of memory (for example `preference`, `background`, `interaction`).              |
| `memory_layer`      | string            | `episodic` (event-based) or `fact` (persistent knowledge).                               |
| `confidence`        | number            | Confidence score (0 to 1).                                                               |
| `source_message_id` | UUID or null      | The message that triggered the memory extraction.                                        |
| `session_id`        | UUID or null      | The session where the memory was extracted.                                              |
| `created_at`        | ISO 8601          | When the memory was first extracted.                                                     |
| `updated_at`        | ISO 8601          | When the memory was last reinforced or modified.                                         |

### Memory layers

- **`fact`** - stable information about the consumer (preferences, background, identity). Updated when new evidence confirms or contradicts existing facts.
- **`episodic`** - event-based memories tied to specific interactions. Useful for understanding what topics a consumer has explored (which manufacturers, which rooms, which projects).

### Filtering by layer

```bash
# Stable facts only
curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/memories?memory_layer=fact" \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"

# Interaction history
curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/memories?memory_layer=episodic" \
  -H "Authorization: Bearer avcodex_YOUR_API_KEY"
```

*AVCodex · Your AV expertise. Amplified by AI.*