@cartisien/extensa

Vector infrastructure layer. Res extensa — the extended thing.

High-performance vector storage with Matryoshka embeddings, binary quantization, and multi-stage retrieval.

Install

npm install @cartisien/extensa

Quick Start

import { createExtensa } from '@cartisien/extensa'

// In-memory (testing)
const extensa = createExtensa({ adapter: 'memory' })
await extensa.connect()

// Create collection
await extensa.createCollection('memories', 768, 'cosine')

// Store vectors
await extensa.store('memories', [
  { id: 'm1', vector: [0.1, 0.2, ...], payload: { text: 'Hello' } },
  { id: 'm2', vector: [0.3, 0.4, ...], payload: { text: 'World' } }
])

// Search
const results = await extensa.search('memories', queryVector, { limit: 5 })

await extensa.disconnect()

The Cartisien Trinity

Extensa sits between Cogito and Engram, providing the vector infrastructure:

Cogito (mind) → Extensa (vectors) → Engram (memory trace)

Where Descartes separated mind (res cogitans) from body (res extensa), Extensa is the extended substance — the mathematical space where meaning lives as geometry.

Features

• Matryoshka Embeddings (MRL) — Full vectors for accuracy, truncated for speed
• Binary Quantization — 32x memory reduction for large-scale retrieval
• Multi-Stage Pipeline — Oversample → Rescore → Rerank
• Query Modes — Interactive, Background, Critical (different latency/quality tradeoffs)
• Multiple Adapters — Memory (testing), Qdrant (production)
• Fusion Retrieval — Combine multiple collections with weighted ranking

API

Adapters

// Memory adapter (testing)
createExtensa({ adapter: 'memory' })

// Qdrant adapter (production)
createExtensa({
  adapter: 'qdrant',
  adapterConfig: {
    url: 'http://localhost:6333',
    apiKey: 'optional-api-key'
  }
})

Matryoshka Configuration

const extensa = createExtensa({
  matryoshka: {
    enabled: true,
    fullDimensions: 768,
    smallDimensions: 256
  }
})

Query Pipeline

// Different modes for different latency requirements
const interactive = await extensa.search('memories', vector, { 
  mode: 'interactive',  // Fast, 4x oversampling
  limit: 10 
})

const critical = await extensa.search('memories', vector, { 
  mode: 'critical',     // Thorough, 8x oversampling
  limit: 10 
})

Binary Quantization

import { BinaryQuantizer } from '@cartisien/extensa'

const quantizer = new BinaryQuantizer()
const binary = quantizer.quantize(vector)

// 32x memory reduction
console.log(quantizer.memoryRatio(768)) // ~0.031

Philosophy

Extensa implements the infrastructure layer of persistent cognition:

• Vectors are meaning — semantic similarity as geometric proximity
• Tradeoffs are explicit — Matryoshka lets you choose speed vs accuracy
• Memory is constrained — Binary quantization for scale
• Retrieval is staged — Fast coarse search, slow precise rescoring

License

MIT © Cartisien Interactive