@cartisien/extensa

Vector infrastructure and Matryoshka embeddings for AI agents.

Part of the Cartisien Memory Suite — res extensa to Cogito's res cogitans and Engram's trace.

What is Extensa?

Extensa is the vector infrastructure layer for the Cartisien Memory Suite. While Engram handles memory storage and retrieval, Extensa manages the raw embedding pipeline:

• Matryoshka embeddings — adaptive dimensionality (768 → 512 → 256 → 128) from a single model pass
• Model management — Ollama integration, fallback chains, batch embedding
• Similarity primitives — cosine, dot product, L2 distance
• Caching — LRU cache for repeated embedding calls
• Normalization — L2 normalization, whitening

import { Extensa } from '@cartisien/extensa';

const vec = new Extensa({ ollamaUrl: 'http://localhost:11434', model: 'nomic-embed-text' });

// Embed a single string
const embedding = await vec.embed('User prefers TypeScript');
// → number[] (768 dims by default)

// Matryoshka — get multiple sizes in one pass
const { full, half, quarter } = await vec.embedMatryoshka('User prefers TypeScript');
// → { full: number[768], half: number[384], quarter: number[192] }

// Batch
const embeddings = await vec.embedBatch(['text one', 'text two', 'text three']);

// Similarity
const score = vec.cosine(embedding, otherEmbedding);

Why Matryoshka?

Standard embeddings are fixed-size. Matryoshka Representation Learning (MRL) trains models so that the first N dimensions of a large embedding are themselves a meaningful smaller embedding. This means:

• Store full 768-dim vectors for high-recall search
• Use 128-dim projections for fast candidate filtering
• Adaptive precision — trade accuracy for speed at query time

Extensa handles the dimension slicing, normalization, and storage recommendations automatically.

API (v0.2 — coming soon)

new Extensa(config)

const vec = new Extensa({
  ollamaUrl: 'http://localhost:11434',  // local Ollama
  model: 'nomic-embed-text',            // embedding model
  dimensions: 768,                       // output dimensions
  cache: true,                           // LRU cache (default: true)
  cacheSize: 1000,                       // max cached embeddings
});

embed(text): Promise<number[]>

Embed a single string. Returns L2-normalized vector.

embedBatch(texts): Promise<number[][]>

Embed multiple strings in parallel with rate limiting.

embedMatryoshka(text): Promise<MatryoshkaResult>

Return multiple dimension slices from a single embedding pass.

Similarity

vec.cosine(a, b)    // cosine similarity → [0, 1]
vec.dot(a, b)       // dot product
vec.l2(a, b)        // L2 distance

The Cartisien Memory Suite

| Package | Role | Status | |---------|------|--------| | @cartisien/engram | Persistent memory | ✅ Stable | | @cartisien/cogito | Agent lifecycle & identity | 🔧 In development | | @cartisien/extensa | Vector infrastructure | 🔧 In development |

"Res cogitans meets res extensa."

Research

This package is part of the Cartisien Memory Suite described in:

Cartisien. (2026). Engram: A Local-First Persistent Memory Architecture for Conversational AI Agents. Zenodo. https://doi.org/10.5281/zenodo.18988892

License

MIT © Cartisien