Response shape

Memex keeps the core payload shape consistent across direct REST calls, MCP tool calls, and agent wrappers.

Surface envelope

REST returns the payload directly.
MCP returns the same payload inside result.structuredContent.
Skills and plugins should return the same payload object.

Search response

Search has two response modes:

default compact mode with raw: false or omitted, which is better when you want to send the response directly to an LLM
raw mode with raw: true, which is better when you want to process the response programmatically and preserve the original search graph

Some clients expose these as named response options:

llm means the compact mode. For REST, omit raw or send "raw": false.
full means the raw machine-readable mode. For REST, send "raw": true.

For saved views, use POST /search with viewIds when you need to choose between llm and full response modes. POST /execute-view-search returns the full shape directly.

Compact search response (`raw: false`, default)

type SearchLlmReadyResponse = {
    results: SearchLlmReadyResult[]
    meta: SearchMeta
    error?: string
    errorCode?: 'INSUFFICIENT_CREDITS'
    upgradeOptions?: AvailablePlansOutput
}

type SearchLlmReadyMedia = {
    type: string
    imageDescription?: string
    transcriptChunks?: string[]
    assetUrls?: string[]
}

type SearchLlmReadyResult = {
    type: string
    url: string
    createdAt: string | null
    title?: string
    text: string
    media?: SearchLlmReadyMedia[]
    references?: Record<string, SearchLlmReadyReference>
    user_notes?: SearchLlmReadyNote[]
}

type SearchLlmReadyReference = {
    type: string
    url: string
    createdAt: string | null
    title?: string
    text: string
    media?: SearchLlmReadyMedia[]
    references?: Record<string, SearchLlmReadyReference>
}

type SearchLlmReadyNote = {
    type: 'annotation'
    url: string
    createdAt: string | null
    title?: string
    text: string
    media?: SearchLlmReadyMedia[]
    references?: Record<string, SearchLlmReadyReference>
}

Compact search results return a results array with a slim top-level contract:

top-level type, url, createdAt, title?, and text stay consistent across content types
media is opt-in per content type and only includes slim entries such as imageDescription, chunked transcriptChunks, and image assetUrls
web HTML is precompiled into markdown-like text
annotation text is precompiled with references resolved inline
annotation references resolve selector text/timestamps plus source title and summary into YAML blocks
user_notes contains annotations attached to the matched content entity when includeNotes is true
annotation-shaped compact results and user_notes can both expose a compact references object for directly referenced content
compact raw=false output omits chunk matches, extra entities, and other raw search scaffolding

Raw search response (`raw: true`)

type SearchRawResponse = {
    results: SearchResultEntity[]
    extraEntities: ContentEntity[]
    referencesByResultId: Record<string, ResultReferences>
    referencedEntities: ContentEntity[]
    referencedTags: TagEntity[]
    meta: SearchMeta
    error?: string
    errorCode?: 'INSUFFICIENT_CREDITS'
    upgradeOptions?: AvailablePlansOutput
}

type ResultReferences = {
    contentEntityIds: string[]
    tagIds: string[]
}

type SearchResultEntity = ContentEntity & {
    annotations?: SearchResultAnnotation[]
    references?: SearchResultReferencedEntity[]
}

type SearchResultAnnotation = AnnotationEntity & {
    resolvedReferences: SearchResultReferencedEntity[]
    references?: SearchResultReferencedEntity[]
}

type SearchResultReferencedEntity = ContentEntity & {
    metadata: Record<string, unknown>
    references?: SearchResultReferencedEntity[]
}

Raw mode keeps the original search payload shape and adds nested annotation references where they matter. Use it when your application code needs the richer search graph for deterministic parsing, post-processing, or custom rendering:

referencesByResultId maps content and tag relationships by entity ID
when includeNotes is true, each matched result can expose annotations
each annotation in annotations includes resolvedReferences for direct reference entities
each annotation can also include references, which returns the direct reference entities inline
if one of those direct references is itself an annotation, that nested annotation gets its own references one level deep

Memex resolves these raw annotation and chat-thread references from both:

reference_content_ids
memex-reference nodes inside annotation JSON content or chat-thread message JSON content

This means the raw references field can describe:

annotations attached directly to a matched content entity through includeNotes
annotations or other entities directly referenced inside annotation content
annotations or other entities directly referenced inside chat-thread message content

type SearchMeta = {
    offset: number
    limit: number
    returnedCount: number
    rerankApplied: boolean
    usageMicrosCharged: number
    remainingUsageBalance: {
        usageBalancePaygMicros: number
        usageBalanceSubscriptionMicros: number
        total: number
    }
}

usageMicrosCharged reports the dollar-denominated usage micros consumed by that search request. 1,000,000 micros equals $1.00. Search currently reports 0. Compact raw=false search defaults reranking on when the query is eligible for rerank. Raw raw=true search defaults reranking off unless enableRerank is explicitly set to true.

Compact example

{
    "results": [
        {
            "type": "web",
            "url": "https://example.com/article",
            "createdAt": "2026-04-09T08:31:42.786Z",
            "title": "Example article",
            "text": "# Example article\n\nBody text...",
            "user_notes": [
                {
                    "type": "annotation",
                    "url": "https://example.com/article",
                    "createdAt": "2026-04-09T08:31:42.786Z",
                    "text": "annotation:\n  blocks:\n    - kind: commentary\n      text: \"Important passage\"",
                    "references": {
                        "https://www.youtube.com/watch?v=abc123": {
                            "type": "youtube",
                            "url": "https://www.youtube.com/watch?v=abc123",
                            "createdAt": "2026-04-09T08:31:42.786Z",
                            "title": "Referenced video",
                            "text": "Video summary...",
                            "media": [
                                {
                                    "type": "video",
                                    "transcriptChunks": ["Transcript chunk 1"]
                                }
                            ]
                        }
                    }
                }
            ]
        }
    ],
    "meta": {
        "offset": 0,
        "limit": 10,
        "returnedCount": 1,
        "rerankApplied": true,
        "usageMicrosCharged": 0,
        "remainingUsageBalance": {
            "usageBalancePaygMicros": 9000000,
            "usageBalanceSubscriptionMicros": 0,
            "total": 9000000
        }
    }
}

Raw example

{
    "results": [
        {
            "id": "page-1",
            "type": "web",
            "url": "https://example.com/article",
            "annotations": [
                {
                    "id": "note-1",
                    "type": "annotation",
                    "text": "Compiled annotation text",
                    "resolvedReferences": [
                        {
                            "id": "annotation-ref-1",
                            "type": "annotation",
                            "metadata": {}
                        }
                    ],
                    "references": [
                        {
                            "id": "annotation-ref-1",
                            "type": "annotation",
                            "metadata": {},
                            "references": [
                                {
                                    "id": "page-2",
                                    "type": "web",
                                    "metadata": {}
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ],
    "referencesByResultId": {
        "page-1": {
            "contentEntityIds": ["note-1"],
            "tagIds": []
        },
        "note-1": {
            "contentEntityIds": ["page-1", "annotation-ref-1"],
            "tagIds": []
        },
        "annotation-ref-1": {
            "contentEntityIds": ["page-2"],
            "tagIds": []
        }
    },
    "referencedEntities": [],
    "referencedTags": [],
    "meta": {
        "offset": 0,
        "limit": 10,
        "returnedCount": 1,
        "rerankApplied": false,
        "usageMicrosCharged": 0,
        "remainingUsageBalance": {
            "usageBalancePaygMicros": 10000000,
            "usageBalanceSubscriptionMicros": 0,
            "total": 10000000
        }
    }
}

Save response

save-content-entity responses include related entities:

type SaveContentEntityResponse = {
    entity: ContentEntity
    entities: ContentEntity[]
    tags?: TagEntity[]
    isNew: boolean
}

When responseMode: 'receipt' is passed, save-content-entity returns after the content processing request is queued:

type SaveContentEntityReceiptResponse = {
    ok: true
    processingRequestId: string
}

save-content-by-url responses use this shape:

type SaveContentByUrlResponse = {
    entity: ContentEntity
    tags: TagEntity[]
    isNew: boolean
}

Shared supporting shapes

type TagEntity = {
    id: string
    name: string
    created_at?: number
    updated_at?: number
}

type ContentEntityBase = {
    id: string
    type: string
    created_at: number
    updated_at: number
    user_id?: string
    external_id?: string
    url?: string
    tag_ids?: string[]
    reference_content_ids?: string[]
}

type ContentEntity =
    | WebContentEntity
    | TweetContentEntity
    | YoutubeContentEntity
    | ImageContentEntity
    | RedditContentEntity
    | OtherContentEntity

For search responses, Memex resolves url whenever it can derive a stable reference URL from the saved entity, including tweets, YouTube videos, Reddit posts, images, and other non-web items.

Content type shapes

Web

type WebContentEntity = ContentEntityBase & {
    type: 'web'
    title: string
    url: string
    normalized_url: string
    canonical_url?: string
    favicon_url?: string
    description?: string
    keywords?: string
    author?: string
    date?: string
    html?: string
    full_text?: string
}

Twitter

type TweetContentEntity = ContentEntityBase & {
    type: 'twitter'
    author_name: string
    author_handle: string
    title?: string
    text: string
    published_at?: number
    save_type?: 'like' | 'retweet' | 'bookmark'
    videos?: Array<{
        variants: Array<{
            content_type?: string
            url?: string
            bitrate?: number
        }>
        duration?: number
        preview_url?: string
    }>
    images?: string[]
    image_analysis?: Record<string, { description?: string }>
}

YouTube

type YoutubeContentEntity = ContentEntityBase & {
    type: 'youtube'
    title: string
    description: string
    thumbnail_url: string
    published_at: number
    transcript?: Record<
        string,
        Array<{
            offset: string | number
            text: string
            duration: number
        }>
    >
    summary?: Record<string, string>
}

Image

type ImageContentEntity = ContentEntityBase & {
    type: 'image'
    description: string
    original_url?: string
    is_reference?: boolean
    source_url?: string
    source_title?: string
}

type RedditContentEntity = ContentEntityBase & {
    type: 'reddit'
    title?: string
    text: string
    author_name: string
    author_handle: string
    author_favicon_url?: string
    subreddit_favicon_url?: string
    media_urls?: string[]
    videos?: Array<{
        url: string
        preview_url?: string
    }>
    permalink?: string
    subreddit_id?: string
    subreddit_name?: string
    image_analysis?: Record<string, { description?: string }>
}

Upgrade options shape

When Memex cannot charge a search request, upgradeOptions follows this shape:

type AvailablePlansOutput = {
    environment: 'production' | 'development' | 'unknown'
    isProduction: boolean
    defaultPlanId?: string
    plans: AvailablePlan[]
    recoveryHint: string
}

type AvailablePlan = {
    id: string
    tierId: 'starter' | 'unlimited' | 'lifetime'
    planName: string
    pricingMode: 'payg' | 'subscription'
    billingPeriod: 'one_time' | 'monthly' | 'yearly'
    variantId: string | number
    currency: 'USD'
    amount: number
    usageBalanceMicrosIncluded: number
    isSubscription: boolean
    productId?: number
}

Endpoint input shapes: Available endpoints
Auth and setup: Authentication
Usage-balance handling: Buy usage balance

General

API reference

Plugins

Surface envelope

Search response

Compact search response (`raw: false`, default)

Raw search response (`raw: true`)

Compact example

Raw example

Save response

Shared supporting shapes

Content type shapes

Web

Twitter

YouTube

Image

Reddit

Other content entities

Upgrade options shape

​Surface envelope

​Search response

​Compact search response (raw: false, default)

​Raw search response (raw: true)

​Compact example

​Raw example

​Save response

​Shared supporting shapes

​Content type shapes

​Web

​Twitter

​YouTube

​Image

​Reddit

​Other content entities

​Upgrade options shape

​Related docs

Surface envelope

Search response

Compact search response (`raw: false`, default)

Raw search response (`raw: true`)

Compact example

Raw example

Save response

Shared supporting shapes

Content type shapes

Web

Twitter

YouTube

Image

Reddit

Other content entities

Upgrade options shape

Related docs