# Memories

Retrieve user memory entries extracted from conversations

---

Memories are facts and preferences your app has learned about individual consumers through conversations. They power 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://build.chipp.ai/api/v1/apps/YOUR_APP_ID/memories?consumer_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"
```

### Response

```json
{
  "data": [
    {
      "id": "mem-001",
      "consumer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "external_user_id": null,
      "content": "Prefers concise answers over detailed 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 Corp as a product manager",
      "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 pricing tiers and seemed interested in the enterprise plan",
      "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 (e.g., `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.

### Filtering by Layer

```bash
# Get only stable facts
curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/memories?memory_layer=fact" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"

# Get interaction history
curl "https://build.chipp.ai/api/v1/apps/YOUR_APP_ID/memories?memory_layer=episodic" \
  -H "Authorization: Bearer chipp_YOUR_API_KEY"
```