Cortex

Overview

Cortex is an abstraction layer for vector databases, built natively for Effect. It provides schemas, typed collections, and composable operations for vector data. Relational databases use ORMs for structure, and Cortex provides the same structure for AI storage.

Problem

Most vector database tools work at a low level, combining SDKs, handwritten schemas, validation code, and query APIs. The result is infrastructure code that is hard to maintain. As RAG systems grow, metadata becomes inconsistent and filters break. Retrieval logic spreads across the application, and runtime parsing fails. Types become Record<string, unknown>, so the compiler no longer helps. Relational databases had the same problem before ORMs.

Approach

Cortex adds structure and safety to vector database operations, using three design decisions:

Built natively for Effect: Cortex is not an adapter. It uses Effect primitives directly, so vector operations become Effect programs. Adapters become layers, and collections become services. Effect provides typed failures, dependency injection, and structured concurrency as the foundation.
Schema-driven infrastructure: Collections have structure, and Cortex validates vectors, so operations combine cleanly. Cortex treats vector databases as structured infrastructure, not as loosely typed storage. The compiler checks assumptions before runtime, removing a class of bugs in RAG pipelines.
Adapters instead of lock-in: The vector database ecosystem changes often. Cortex uses adapters, keeping application logic independent from storage code. The application describes what it needs from vector infrastructure, not how a vendor implements it.

How It Works

import { Effect } from 'effect'
import { VectorDB, DocumentId, Vector } from '@thaletto/cortex'
 
const program = Effect.gen(function* () {
  const db = yield* VectorDB
  const id = DocumentId.make('user-1-preference')
 
  yield* db.upsert({
    id,
    content: 'User prefers TypeScript over JavaScript',
    category: 'preferences',
    tags: 'typescript',
    metadata_json: JSON.stringify({ source: 'onboarding' }),
    vector: Vector.make(new Array(384).fill(0)),
    expires_at: new Date('2026-12-31'),
  })
})

Tech Stack

Effect
TypeScript
npm

Problem

Approach

Cortex adds structure and safety to vector database operations, using three design decisions:

Built natively for Effect: Cortex is not an adapter. It uses Effect primitives directly, so vector operations become Effect programs. Adapters become layers, and collections become services. Effect provides typed failures, dependency injection, and structured concurrency as the foundation.

Schema-driven infrastructure: Collections have structure, and Cortex validates vectors, so operations combine cleanly. Cortex treats vector databases as structured infrastructure, not as loosely typed storage. The compiler checks assumptions before runtime, removing a class of bugs in RAG pipelines.

Adapters instead of lock-in: The vector database ecosystem changes often. Cortex uses adapters, keeping application logic independent from storage code. The application describes what it needs from vector infrastructure, not how a vendor implements it.

How It Works

import { Effect } from 'effect'
import { VectorDB, DocumentId, Vector } from '@thaletto/cortex'
 
const program = Effect.gen(function* () {
  const db = yield* VectorDB
  const id = DocumentId.make('user-1-preference')
 
  yield* db.upsert({
    id,
    content: 'User prefers TypeScript over JavaScript',
    category: 'preferences',
    tags: 'typescript',
    metadata_json: JSON.stringify({ source: 'onboarding' }),
    vector: Vector.make(new Array(384).fill(0)),
    expires_at: new Date('2026-12-31'),
  })
})