Memories | Chipp Docs

Memories

Retrieve user memory entries extracted from conversations

1 min read

# api # builder-api # rest # memories # user-memory # personalization # context

Memories are facts and preferences your app has learned about individual consumers through conversations. They power personalized responses across sessions.

ℹ️

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

List Memories

plaintext

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"