REST API: Memories

Create, search, update, and delete memories via the REST API.

Updated Oct 6, 2026

Overview

The Memories API is the core of Trix. Use it to store, search, update, and manage memories. Memories can contain text, markdown, code, URLs, audio, and more.

Create Memory

Store any content type: text, markdown, URLs, audio files, code, JSON, and more. Content type is auto-detected or can be specified explicitly.

POST /v1/memories

Endpoint

POST /v1/memories

Request Body Fields

Parameter	Type	Required	Description
`content`	`string`	Yes	Memory content (text, URL, base64 audio, etc.)
`type`	`string`	No	text, markdown, code, json, html, url, audio, note
`tags`	`string[]`	No	Tags for categorization (max 100)
`metadata`	`object`	No	Custom key-value metadata
`priority`	`number`	No (default: 0)	Priority level (0-100)
`space_id`	`string`	No	Space to store memory in
`expires_at`	`string`	No	ISO 8601 expiration timestamp
`salience`	`number`	No (default: 1.0)	Memory importance 0-1
`is_private`	`boolean`	No (default: false)	Creator-only access
`clusters`	`string[]`	No	Cluster IDs to add memory to
`idempotency_key`	`string`	No	For duplicate detection

Processing Options

Parameter	Type	Description
`options.split`	`string`	none, paragraph, sentence, chunk, heading
`options.chunk_size`	`number`	Chunk size in tokens (100-10000, default 1000)
`options.chunk_overlap`	`number`	Overlap between chunks (0-500, default 100)
`options.embed`	`boolean`	Generate embeddings (default true)
`options.async`	`boolean`	Async embedding (default true)
`options.transcribe`	`boolean`	Transcribe audio (default true)

const memory = await fetch('https://api.trixdb.com/v1/memories', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: 'User prefers dark mode and compact layouts',
    type: 'text',
    tags: ['preferences', 'ui'],
    metadata: { source: 'settings_page', version: '2.0' },
    priority: 7,
    salience: 0.9
  })
}).then(r => r.json());

Response (201 Created)

{
  "id": "mem_abc123xyz",
  "content": "User prefers dark mode and compact layouts",
  "content_type": "text",
  "tags": ["preferences", "ui"],
  "metadata": { "source": "settings_page", "version": "2.0" },
  "priority": 7,
  "salience": 0.9,
  "is_private": false,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Search Memories

The list endpoint doubles as a powerful search endpoint when the q parameter is provided. It supports semantic search, full-text search, and hybrid search.

Endpoint

GET /v1/memories?q=user+preferences&mode=hybrid

Query Parameters

Parameter	Type	Description
`q`	`string`	Search query (enables search mode)
`mode`	`string`	hybrid (default), semantic, fulltext
`threshold`	`number`	Relevance threshold 0-1 (default 0.3)
`type`	`string`	Filter by content type
`tags`	`string`	Comma-separated tags filter
`space_id`	`string`	Filter by space
`cluster`	`string`	Filter by cluster
`created_after`	`string`	ISO 8601 date filter
`created_before`	`string`	ISO 8601 date filter
`include`	`string`	Include: clusters, relationships, brain_state
`min_salience`	`number`	Minimum salience filter 0-1
`limit`	`number`	Max results (default 20, max 100)
`offset`	`number`	Pagination offset
`cursor`	`string`	Cursor for cursor-based pagination
`sort`	`string`	created_at, updated_at, accessed_at, priority, salience
`order`	`string`	asc or desc (default desc)

Search Modes

Mode	Description	Best For
`semantic`	Vector similarity search using embeddings	Conceptual queries, finding related content
`fulltext`	Traditional keyword search with BM25	Exact matches, known keywords
`hybrid`	Combines semantic and fulltext with RRF	General purpose (recommended)

const params = new URLSearchParams({
  q: 'user preferences',
  mode: 'hybrid',
  threshold: '0.5',
  limit: '10'
});

const results = await fetch(`https://api.trixdb.com/v1/memories?${params}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(r => r.json());

Response (200 OK)

{
  "data": [
    {
      "id": "mem_abc123xyz",
      "content": "User prefers dark mode and compact layouts",
      "content_type": "text",
      "score": 0.92,
      "tags": ["preferences", "ui"],
      "salience": 0.9,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": false,
    "total": 1
  }
}

Get Memory

Endpoint

GET /v1/memories/:id

curl -X GET "https://api.trixdb.com/v1/memories/mem_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use include parameter to get related data:

curl -X GET "https://api.trixdb.com/v1/memories/mem_abc123xyz?include=relationships,clusters" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Memory

Endpoint

PATCH /v1/memories/:id

curl -X PATCH "https://api.trixdb.com/v1/memories/mem_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated: User prefers dark mode with high contrast",
    "tags": ["preferences", "accessibility"],
    "priority": 9
  }'

Updating content will trigger re-embedding. Use options.embed: false if you only want to update metadata.

Delete Memory

Endpoint

DELETE /v1/memories/:id

curl -X DELETE "https://api.trixdb.com/v1/memories/mem_abc123xyz" \
  -H "Authorization: Bearer YOUR_API_KEY"

Bulk Operations

Bulk Create

Endpoint

POST /v1/memories/bulk

curl -X POST "https://api.trixdb.com/v1/memories/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memories": [
      {"content": "User completed onboarding", "tags": ["onboarding"]},
      {"content": "User selected premium plan", "tags": ["billing"]},
      {"content": "User invited team members", "tags": ["team"]}
    ]
  }'

Bulk Update

Endpoint

PATCH /v1/memories/bulk

curl -X PATCH "https://api.trixdb.com/v1/memories/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {"id": "mem_abc123", "priority": 10},
      {"id": "mem_def456", "tags": ["important"]}
    ]
  }'

Bulk Delete

Endpoint

DELETE /v1/memories/bulk

curl -X DELETE "https://api.trixdb.com/v1/memories/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["mem_abc123", "mem_def456", "mem_ghi789"]}'

Audio & Video Memories

Store and transcribe audio and video files with advanced features including speaker diarization, entity detection, content safety, auto chapters, and summarization.

Supported audio formats: mp3, mp4, m4a, wav, webm, ogg, flac, aac
Supported video formats: mp4, webm, mov, avi, mkv, flv, mpeg

File Size Limits: Audio files are limited to 100MB. Video files are limited to 200MB. For larger files, consider using external storage and providing a URL instead.

Rate Limits: Transcription requests are limited to 10 per hour per API key. This applies to both audio and video transcription endpoints.

Upload Audio/Video

curl -X POST "https://api.trixdb.com/v1/memories" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "data:audio/mp3;base64,//uQxAAAAAANIAAAAAE...",
    "type": "audio",
    "metadata": {"meeting": "standup_2024_01_15"},
    "options": {"transcribe": true}
  }'

Stream Audio/Video

Endpoint

GET /v1/memories/:id/stream

Supports HTTP Range requests for efficient streaming and seeking. The server responds with HTTP 206 Partial Content when a Range header is provided.

# Stream full audio
curl -X GET "https://api.trixdb.com/v1/memories/mem_audio123/stream" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Stream with Range request (bytes 0-999999)
curl -X GET "https://api.trixdb.com/v1/memories/mem_audio123/stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Range: bytes=0-999999"

Get Transcript

Endpoint

GET /v1/memories/:id/transcript

curl -X GET "https://api.trixdb.com/v1/memories/mem_audio123/transcript" \
  -H "Authorization: Bearer YOUR_API_KEY"

Transcribe with Advanced Options

Endpoint

POST /v1/memories/:id/transcribe

Request Body

Parameter	Type	Description
`language`	`string`	Language code (e.g., 'en', 'es')
`prompt`	`string`	Context to improve transcription accuracy
`provider`	`string`	'assemblyai' or 'openai' (default: account preference)
`enableSpeakerDiarization`	`boolean`	Enable speaker identification and labeling
`enableEntityDetection`	`boolean`	Enable entity detection in transcript
`enableContentSafety`	`boolean`	Enable content safety labeling
`enableAutoChapters`	`boolean`	Enable automatic chapter generation
`enableAutoSummarization`	`boolean`	Enable automatic summarization
`speakersExpected`	`number`	Expected number of speakers (hint for diarization)

Example: Basic Transcription

curl -X POST "https://api.trixdb.com/v1/memories/mem_audio123/transcribe" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en"
  }'

Example: Advanced Transcription with Speaker Diarization

curl -X POST "https://api.trixdb.com/v1/memories/mem_audio123/transcribe" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "assemblyai",
    "enableSpeakerDiarization": true,
    "speakersExpected": 2,
    "enableEntityDetection": true,
    "enableAutoChapters": true,
    "enableAutoSummarization": true,
    "language": "en",
    "prompt": "This is a meeting between two executives discussing Q1 results"
  }'

Provider Features & Limits

Feature	AssemblyAI	OpenAI Whisper
Max File Size	5GB	25MB
Speaker Diarization	Yes	No
Entity Detection	Yes	No
Content Safety	Yes	No
Auto Chapters	Yes	No
Auto Summarization	Yes	No
Word-level Timestamps	Yes	Yes

Stream specific time ranges from audio files without downloading the entire file. This is ideal for playing back specific segments, creating highlights, or building audio players with precise seeking.

Endpoint

GET /v1/audio/:id/clip

Query Parameters

Parameter	Type	Required	Description
`start`	`number`	Yes	Start time in seconds (e.g., 30.5)
`end`	`number`	Yes	End time in seconds (e.g., 120.0)
`context`	`number`	No (default 0)	Additional seconds of context before/after
`format`	`string`	No (default mp3)	Output format: mp3, wav, ogg, m4a, webm

Maximum Duration: Clips are limited to 3600 seconds (1 hour). Requests exceeding this limit will return a 400 Bad Request error.

const clipUrl = new URL('https://api.trixdb.com/v1/audio/aud_abc123/clip');
clipUrl.searchParams.set('start', '60');
clipUrl.searchParams.set('end', '90');
clipUrl.searchParams.set('format', 'mp3');

const response = await fetch(clipUrl, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const blob = await response.blob();
const audioUrl = URL.createObjectURL(blob);
const audio = new Audio(audioUrl);
audio.play();

Get Clip Metadata

Endpoint

GET /v1/audio/:id/clip/info

curl -X GET "https://api.trixdb.com/v1/audio/aud_abc123/clip/info?start=60&end=90" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

{
  "id": "aud_abc123",
  "start": 60,
  "end": 90,
  "duration": 30,
  "source_duration": 3600,
  "byte_size": 480000,
  "byte_range": "1920000-2400000",
  "format": "mp3",
  "sample_rate": 44100,
  "channels": 2,
  "bitrate": 128000,
  "clip_url": "/v1/audio/aud_abc123/clip?start=60&end=90&format=mp3"
}

Audio Transcript Search

Search within audio transcripts to find specific content. Returns matches with timestamps and direct links to stream the relevant audio clips.

Endpoint

GET /v1/audio/search

Query Parameters

Parameter	Type	Required	Description
`q`	`string`	Yes	Search query (supports semantic and keyword search)
`limit`	`number`	No (default 20)	Maximum results to return (max: 100)
`threshold`	`number`	No (default 0.3)	Minimum relevance score 0-1
`space_id`	`string`	No	Filter results to a specific space

const params = new URLSearchParams({
  q: 'quarterly revenue', limit: '10', threshold: '0.5'
});

const results = await fetch(`https://api.trixdb.com/v1/audio/search?${params}`, {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}).then(r => r.json());

results.matches.forEach(match => {
  console.log(`Found at ${match.start_time}s: ${match.text}`);
  console.log(`Play clip: ${match.clip_url}`);
});

Unified Search

Search across both memories and audio transcripts in a single request. Returns mixed results with facets showing the distribution across content types.

Endpoint

POST /v1/search/unified

Request Body

Parameter	Type	Required	Description
`query`	`string`	Yes	Search query
`include_types`	`string[]`	No	Types to include: ["memories", "audio"]
`limit`	`number`	No (default 20)	Maximum results per type (max: 100)
`threshold`	`number`	No (default 0.3)	Minimum relevance score 0-1
`space_id`	`string`	No	Filter results to a specific space
`mode`	`string`	No (default hybrid)	Search mode: hybrid, semantic, fulltext

const results = await fetch('https://api.trixdb.com/v1/search/unified', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'product launch strategy',
    include_types: ['memories', 'audio'],
    limit: 10,
    threshold: 0.5
  })
}).then(r => r.json());

console.log(`Found ${results.facets.memories} memories`);
console.log(`Found ${results.facets.audio} audio matches`);

Video Metadata

Retrieve detailed metadata about video files including resolution, frame rate, codec information, duration, and audio track details.

Endpoint

GET /v1/memories/:id/video/metadata

curl -X GET "https://api.trixdb.com/v1/memories/mem_video123/video/metadata" \
  -H "Authorization: Bearer YOUR_API_KEY"

AI Video Interpretation

Use AI to analyze and interpret video content. Extract scene descriptions, detect objects, identify text via OCR, and generate comprehensive summaries.

Endpoint

POST /v1/memories/:id/video/interpret

Request Body

Parameter	Type	Description
`frames_to_analyze`	`number`	Number of frames to analyze (max: 100, default 10)
`include_ocr`	`boolean`	Extract text from frames via OCR (default false)
`frame_selection`	`string`	Frame selection strategy: uniform, keyframes, scene_change (default uniform)
`start_time`	`number`	Start time in seconds for analysis range
`end_time`	`number`	End time in seconds for analysis range

curl -X POST "https://api.trixdb.com/v1/memories/mem_video123/video/interpret" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "frames_to_analyze": 20,
    "include_ocr": true,
    "frame_selection": "scene_change"
  }'

Processing Time: Video interpretation is an asynchronous operation. For longer videos, consider using the job status endpoint to poll for completion, or configure webhooks for notification.

Reinforce Memory

Boost a memory's salience when it proves useful:

Endpoint

POST /v1/memories/:id/reinforce

curl -X POST "https://api.trixdb.com/v1/memories/mem_abc123/reinforce" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"boost": 0.1, "accessed": true}'