Memories — AVCodex Docs

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#

code

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.*