Schemas

Cortex uses Effect Schema for all its data structures, providing runtime validation and type safety.

Core Types

A branded string used to uniquely identify documents in the database.

import { DocumentId } from "@thaletto/cortex"

const id = DocumentId.make("user-123")

A branded Array<number> representing the embedding vector. The length must match the dimension configured in your adapter.

import { Vector } from "@thaletto/cortex"

const vector = Vector.make([0.1, 0.2, ...])

The internal representation of a document stored in the database.

The input structure for upsert and upsertMany operations.

Field	Type	Description
`id`	`DocumentId`	Unique identifier
`content`	`string`	The text content to store
`category`	`string`	Category for filtering
`tags`	`string`	Single string (converted to array internally)
`metadata_json`	`string`	JSON string for extra data
`vector`	`Vector`	The embedding vector
`expires_at`	`Date`	When this record should expire

Returned by the search method.

interface SearchResult {
  readonly document: CollectionSchema
  readonly score: number // 0 to 1 (similarity)
}

Used to filter documents during search, list, or delete operations.

Field	Type	Description
`category`	`string` (optional)	Match documents in this category
`tags`	`string[]` (optional)	Match if any of these tags are present
`activeAt`	`Date` (optional)	Only include docs expiring after this date

Used to paginate results in the list method.

interface Pagination {
  readonly limit: number
  readonly offset: number
}

All errors in Cortex are TaggedError classes.

Generic storage or adapter error.

Thrown when an operation expects a document to exist (e.g., getById, delete).

Thrown when a provided vector's length does not match the configured dimension.