Memories API

Create, retrieve, update, and delete memories. Memories are the fundamental building blocks of your agent's long-term knowledge.

Updated Oct 6, 2026

Overview

The Memories API allows you to store and manage persistent memories for your AI agents. Each memory contains content, metadata, and is automatically embedded for semantic search.

Base URL: https://api.trixdb.com/v1

Create Memory

Endpoint

POST /memories

Creates a new memory in the specified space. The content is automatically embedded for semantic search.

Body Parameters

Field	Type	Description
content	string (required)	The text content of the memory. Maximum 1 MB (1,048,576 bytes). Up to 100 tags, each up to 255 characters.
type	string	Content type. One of: `text` (default), `markdown`, `url`, `audio`, `image`.
space_id	string (UUID)	Optional. UUID of the space to store this memory in. Omit for account-level memories.
tags	string[]	Optional array of tag strings (max 100 tags; each up to 255 chars).
metadata	object	Optional key-value pairs to attach to this memory. Useful for filtering and categorization.
priority	integer	Optional priority (0-10). Higher values bias search toward this memory.
session_id	string	Associate this memory with a specific session for conversation context.
is_pinned	boolean	Pin this memory on creation to prevent decay. Default: false.
protection_level	string	Set protection level on creation. One of: `"none"`, `"soft"`, `"hard"`. Default: `"none"`.

Response (201)

Example Response

{
  "id": "<memory-uuid>",
  "content": "The user prefers dark mode and uses vim keybindings",
  "content_type": "text",
  "space_id": null,
  "tags": ["preference", "ui"],
  "metadata": { "source": "onboarding" },
  "priority": 5,
  "salience": null,
  "is_pinned": true,
  "is_deleted": false,
  "protection_level": "soft",
  "quality_score": null,
  "created_at": "2026-04-15T10:30:00Z",
  "updated_at": "2026-04-15T10:30:00Z"
}

Get Memory

Endpoint

GET /memories/:id

Fetches a single memory by its unique identifier.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the memory.

Response (200)

Example Response

{
  "id": "mem_7x9kQ2mN8pL3",
  "content": "The user prefers dark mode and uses vim keybindings",
  "space_id": "default",
  "metadata": {
    "type": "preference",
    "source": "onboarding"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

List Memories

Endpoint

GET /memories

Returns a paginated list of memories. Supports filtering by space, session, and metadata.

Query Parameters

Field	Type	Description
space_id	string	Filter by space ID. Omit to list memories from all spaces.
session_id	string	Filter by session ID to get conversation-specific memories.
pinned	boolean	Filter by pinned status. Set to `true` to only return pinned memories, `false` for unpinned.
protected	boolean	Filter by protection status. Set to `true` to only return protected memories (soft or hard protection).
min_quality	number	Minimum quality score (0-1). Only return memories with quality score at or above this threshold.
include_deleted	boolean	Include soft-deleted memories in results. Default: false.
limit	integer	Maximum number of memories to return. Default: 20, Max: 100.
cursor	string	Pagination cursor from a previous response.

Response (200)

Example Response

{
  "data": [
    {
      "id": "mem_7x9kQ2mN8pL3",
      "content": "The user prefers dark mode and uses vim keybindings",
      "space_id": "default",
      "is_pinned": true,
      "is_deleted": false,
      "protection_level": "soft",
      "quality_score": 0.92,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6Im1lbV84eTBsUjNuTzlxTTQifQ"
}

Update Memory

Endpoint

PATCH /memories/:id

Updates an existing memory. Only the fields you provide will be updated. Changing content triggers re-embedding.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the memory to update.

Body Parameters

Field	Type	Description
content	string	New content for the memory. Will trigger re-embedding.
metadata	object	Updated metadata. Merges with existing metadata.

Response (200)

Example Response

{
  "id": "mem_7x9kQ2mN8pL3",
  "content": "The user prefers dark mode and uses vim keybindings",
  "space_id": "default",
  "metadata": {
    "type": "preference",
    "source": "onboarding",
    "verified": true
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T14:22:00Z"
}

Delete Memory

Endpoint

DELETE /memories/:id

Deletes a memory. Use soft=true for soft delete (can be restored), or omit for permanent deletion.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the memory to delete.

Query Parameters

Field	Type	Description
soft	boolean	Set to `true` for soft delete (memory can be restored). Default: false (permanent delete).

Response

For soft delete (200), returns the memory object with is_deleted=true. For permanent delete (204), returns no content.

Warning: Permanent deletion cannot be undone. Use soft delete (soft=true) if you may need to restore the memory later. Soft-deleted memories can be restored using the POST /memories/:id/restore endpoint.

Restore Memory

Endpoint

POST /memories/:id/restore

Restores a memory that was soft-deleted. The memory will be fully accessible again.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the soft-deleted memory to restore.

Response (200)

Example Response

{
  "id": "mem_7x9kQ2mN8pL3",
  "content": "The user prefers dark mode and uses vim keybindings",
  "space_id": "default",
  "is_pinned": false,
  "is_deleted": false,
  "protection_level": "none",
  "deleted_at": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T17:00:00Z"
}

Pin Memory

Endpoint

POST /memories/:id/pin

Pins a memory to prevent it from decaying over time. Pinned memories are always retained regardless of age or access frequency.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the memory to pin.

Response (200)

Example Response

{
  "id": "mem_7x9kQ2mN8pL3",
  "content": "The user prefers dark mode and uses vim keybindings",
  "space_id": "default",
  "is_pinned": true,
  "is_deleted": false,
  "protection_level": "none",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:30:00Z"
}

Tip: Use pinning for critical memories that should never be forgotten, such as core user preferences, important facts, or key decisions. Pinned memories do not count toward decay limits but do count toward storage quotas.

Unpin Memory

Endpoint

POST /memories/:id/unpin

Unpins a memory to allow normal decay behavior. The memory will be subject to standard retention policies.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the memory to unpin.

Response (200)

Returns the updated memory object with is_pinned=false.

Set Protection Level

Endpoint

PATCH /memories/:id/protection

Sets the protection level for a memory. Protection controls how the memory can be modified or deleted.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the memory.

Body Parameters

Field	Type	Description
protection_level	string (required)	The protection level to set. One of: `"none"` (no protection), `"soft"` (requires confirmation for modifications), `"hard"` (prevents all modifications and deletion).

Response (200)

Returns the updated memory object with the new protection level.

Protection Levels:

none — Default. Memory can be updated or deleted without restrictions.
soft — Memory modifications require explicit confirmation. Useful for important but occasionally updatable memories.
hard — Memory is locked and cannot be modified or deleted. Use for immutable records.

Get Memory Topics

Endpoint

GET /memories/:id/topics

Retrieves LLM-extracted topics for a memory. Topics are semantic tags that describe what the memory is about.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the memory.

Query Parameters

Field	Type	Description
refresh	boolean	Force re-extraction of topics using the LLM. Default: false.
min_relevance	number	Minimum relevance score (0-1) for topics to include. Default: 0.5.
categories	string	Comma-separated list of topic categories to include. Options: `concept`, `entity`, `action`, `attribute`.

Response (200)

Example Response

{
  "memory_id": "mem_7x9kQ2mN8pL3",
  "topics": [
    { "name": "dark mode", "relevance": 0.95, "category": "attribute" },
    { "name": "vim keybindings", "relevance": 0.92, "category": "concept" },
    { "name": "user preferences", "relevance": 0.88, "category": "concept" }
  ],
  "extracted_at": "2024-01-15T10:31:00Z",
  "model": "default"
}

Enrich Memory

Endpoint

POST /memories/:id/enrich

Enriches a memory with LLM-generated metadata such as topics, summaries, entities, and quality scores.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the memory to enrich.

Body Parameters

Field	Type	Description
operations	string[] (required)	Array of enrichment operations. Options: `"topics"`, `"summary"`, `"entities"`, `"quality"`.

Response (200)

Example Response

{
  "memory_id": "mem_7x9kQ2mN8pL3",
  "enrichments": {
    "topics": {
      "success": true,
      "data": [
        { "name": "dark mode", "relevance": 0.95, "category": "attribute" }
      ]
    },
    "summary": {
      "success": true,
      "data": "User prefers dark mode interface and vim-style keyboard shortcuts."
    },
    "entities": {
      "success": true,
      "data": [
        { "name": "vim", "type": "software", "confidence": 0.98 }
      ]
    },
    "quality": {
      "success": true,
      "data": {
        "score": 0.85,
        "factors": {
          "specificity": 0.9,
          "clarity": 0.85,
          "actionability": 0.8
        }
      }
    }
  },
  "processed_at": "2024-01-20T16:00:00Z",
  "model": "default"
}

Tip: Enrichment operations are processed asynchronously. For large batches, consider using the webhook notification system to receive completion callbacks.

Get Quality Score

Endpoint

GET /memories/:id/quality

Retrieves the quality score for a memory. Quality scores indicate how useful and well-formed a memory is.

Path Parameters

Field	Type	Description
id	string (required)	The unique identifier of the memory.

Query Parameters

Field	Type	Description
recalculate	boolean	Force recalculation of the quality score. Default: false.

Response (200)

Example Response

{
  "memory_id": "mem_7x9kQ2mN8pL3",
  "quality_score": 0.85,
  "factors": {
    "specificity": 0.9,
    "clarity": 0.85,
    "actionability": 0.8,
    "uniqueness": 0.85
  },
  "calculated_at": "2024-01-20T16:00:00Z"
}

Quality Factors:

specificity — How specific and detailed the memory is
clarity — How clearly the information is expressed
actionability — How useful the memory is for decision-making
uniqueness — How distinct the memory is from others

Memory Object

The memory object contains the following fields:

Field	Type	Description
id	string	Unique identifier for the memory. Prefixed with `mem_`.
content	string	The text content of the memory.
space_id	string	The ID of the space containing this memory.
session_id	string \| null	The session ID if this memory is associated with a conversation.
metadata	object	Custom key-value pairs attached to this memory.
is_pinned	boolean	Whether the memory is pinned. Pinned memories do not decay over time.
is_deleted	boolean	Whether the memory has been soft-deleted. Soft-deleted memories can be restored.
protection_level	string	Protection level: `none`, `soft`, or `hard`.
quality_score	number \| null	Quality score from 0 to 1, or null if not yet calculated.
deleted_at	string \| null	ISO 8601 timestamp of when the memory was soft-deleted, or null if not deleted.
created_at	string	ISO 8601 timestamp of when the memory was created.
updated_at	string	ISO 8601 timestamp of when the memory was last updated.

Errors

The Memories API uses standard HTTP status codes:

Status	Description
`400`	Bad Request — Invalid parameters or missing required fields
`401`	Unauthorized — Invalid or missing API key
`404`	Not Found — Memory doesn't exist
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error — Something went wrong on our end