{"_id":"@cartisien/extensa","_rev":"4-687f5f1b1aac234c8c7ec403389f51a0","name":"@cartisien/extensa","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@cartisien/extensa","version":"0.1.0","keywords":["vector","embeddings","matryoshka","quantization","qdrant","retrieval","ai","extensa","cartisien","res-extensa"],"author":{"name":"Cartisien Interactive"},"license":"MIT","_id":"@cartisien/extensa@0.1.0","maintainers":[{"name":"mrwitters","email":"cartisien@cartisien.com"}],"homepage":"https://cartisien.com/products/extensa","bugs":{"url":"https://github.com/cartisien/extensa/issues"},"dist":{"shasum":"0332fae9cc5537842e8172551ed64549b285d766","tarball":"https://registry.npmjs.org/@cartisien/extensa/-/extensa-0.1.0.tgz","fileCount":6,"integrity":"sha512-vBHG9uq4MfCkYqZy6JDVf5zetglDGzXOZEMJEixNI7JyoCTaSP3tPE4OEzzer0syhT8+gS7k980JP2D7XGLuGA==","signatures":[{"sig":"MEQCIB4zsrDgjtKwR7GDRKaduJ8tAppLwNo6cAi/sK3Co9mqAiBhWt+yWXK0LoxeuhEh/nhwT0kQSDInRcHx+Yx5b5ZA5A==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":64384},"main":"./dist/index.js","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"gitHead":"36126702c52c79abd274b029ad942edd3ca84233","scripts":{"dev":"tsup src/index.ts --format cjs,esm --dts --watch","test":"vitest run","build":"tsup src/index.ts --format cjs,esm --dts","typecheck":"tsc --noEmit","test:watch":"vitest","prepublishOnly":"npm run build"},"_npmUser":{"name":"mrwitters","email":"cartisien@cartisien.com"},"repository":{"url":"git+https://github.com/cartisien/extensa.git","type":"git"},"_npmVersion":"11.8.0","description":"Vector infrastructure layer. Res extensa — the extended thing. Matryoshka embeddings, binary quantization, and high-performance retrieval.","directories":{},"_nodeVersion":"25.5.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.6.0","typescript":"^5.4.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/extensa_0.1.0_1772242033407_0.8939422961078425","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@cartisien/extensa","version":"0.1.1","keywords":["ai","agents","memory","vector","qdrant","embeddings","cartisien"],"author":{"url":"https://cartisien.com","name":"Jeff Witters","email":"jeff@cartisien.com"},"license":"MIT","_id":"@cartisien/extensa@0.1.1","maintainers":[{"name":"mrwitters","email":"cartisien@cartisien.com"}],"homepage":"https://cartisien.com","bugs":{"url":"https://github.com/cartisien/sdk/issues"},"dist":{"shasum":"105fea987e4fb552989ca8abb78cb415dfed6cee","tarball":"https://registry.npmjs.org/@cartisien/extensa/-/extensa-0.1.1.tgz","fileCount":38,"integrity":"sha512-cKdxbunn6uVfKa+0bZfTSSEi450cPTQ1mfNhPjqjqX7H8SrdxrXqJlOoC+HT01tev4lqjJLTlzTBh/ElB4cQ9Q==","signatures":[{"sig":"MEUCIBNtui2ZF3MEv3hE6zGMDBxDtCWaH6anrnXofpeoWfjHAiEAy5Mk2gKYRSRj3teZy3lHG3WK1FDEmkGuru/HP0LYYoc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":76716},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"c1927908d77bb559ecc5380afb5d4018aa14e759","scripts":{"test":"vitest run","build":"tsc","check":"tsc --noEmit"},"_npmUser":{"name":"mrwitters","email":"cartisien@cartisien.com"},"repository":{"url":"git+https://github.com/Cartisien/extensa.git","type":"git"},"_npmVersion":"10.8.2","description":"Persistent vector infrastructure for AI agents — part of the Cartisien platform","directories":{},"_nodeVersion":"20.20.0","dependencies":{},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0"},"_npmOperationalInternal":{"tmp":"tmp/extensa_0.1.1_1773150078347_0.3878824746811729","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@cartisien/extensa","version":"0.1.2","keywords":["ai","embeddings","vector","matryoshka","local-first","ollama","semantic-search"],"author":{"name":"Cartisien"},"license":"MIT","_id":"@cartisien/extensa@0.1.2","maintainers":[{"name":"mrwitters","email":"cartisien@cartisien.com"}],"homepage":"https://github.com/Cartisien/extensa#readme","bugs":{"url":"https://github.com/Cartisien/extensa/issues"},"dist":{"shasum":"17f53edb865674606e4502552949bd38d4f3b15a","tarball":"https://registry.npmjs.org/@cartisien/extensa/-/extensa-0.1.2.tgz","fileCount":6,"integrity":"sha512-SltbqmYdc9WqgxjXr5rElTBnDxgnSRMWn150XIv6c0rlTw64NeFR/1/hWbEUqq5hf5UQ669r9i3zRZeyLmtApg==","signatures":[{"sig":"MEUCIA6BHadqFSS+sjf2vWWwxvHW1baAdBAIuO1b0B2Lb6VuAiEA4uZQfi9l5gohlQJqXtvwSSVDi9yz7dtd0xhA3UXkBjA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":9278},"main":"dist/index.js","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"scripts":{"build":"tsc","prepublishOnly":"npm run build"},"_npmUser":{"name":"mrwitters","email":"cartisien@cartisien.com"},"repository":{"url":"git+https://github.com/Cartisien/extensa.git","type":"git"},"_npmVersion":"11.8.0","description":"Vector infrastructure and Matryoshka embeddings for AI agents.","directories":{},"_nodeVersion":"25.5.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.9.3","@types/node":"^20.19.37"},"_npmOperationalInternal":{"tmp":"tmp/extensa_0.1.2_1773345066792_0.3950208440959493","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@cartisien/extensa","version":"0.2.0","description":"Vector infrastructure and Matryoshka embeddings for AI agents.","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","prepublishOnly":"npm run build"},"keywords":["ai","embeddings","vector","matryoshka","local-first","ollama","semantic-search"],"author":{"name":"Cartisien"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/Cartisien/extensa.git"},"devDependencies":{"@types/node":"^20.19.37","typescript":"^5.9.3"},"engines":{"node":">=18.0.0"},"gitHead":"eeafc542425ba5a47ed625be98781f8b1dd1b389","_id":"@cartisien/extensa@0.2.0","bugs":{"url":"https://github.com/Cartisien/extensa/issues"},"homepage":"https://github.com/Cartisien/extensa#readme","_nodeVersion":"25.5.0","_npmVersion":"11.8.0","dist":{"integrity":"sha512-z6c2TMgSUgE3QWPKo5f9vgeocWqx2Omf8L3wQOdx3K11wtqkxqQOUDQ3jAk+BcF9rBLGRt8fSSvjkQGcgWjs9g==","shasum":"67ea511bf88610e76071707173baf56b37b07dd7","tarball":"https://registry.npmjs.org/@cartisien/extensa/-/extensa-0.2.0.tgz","fileCount":21,"unpackedSize":22574,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDVUsjduXIUXZmcS1/0Nsx9Lxu9K6g7QH3Je9GA2yDXVAiEAoJE0pliZmzOVX0qs3gPWi6gC3i3SeHN98OxCKx/iuCY="}]},"_npmUser":{"name":"mrwitters","email":"cartisien@cartisien.com"},"directories":{},"maintainers":[{"name":"mrwitters","email":"cartisien@cartisien.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/extensa_0.2.0_1773345418595_0.6135949275154637"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-28T01:27:13.309Z","modified":"2026-03-12T19:56:58.876Z","0.1.0":"2026-02-28T01:27:13.551Z","0.1.1":"2026-03-10T13:41:18.513Z","0.1.2":"2026-03-12T19:51:06.935Z","0.2.0":"2026-03-12T19:56:58.750Z"},"bugs":{"url":"https://github.com/Cartisien/extensa/issues"},"author":{"name":"Cartisien"},"license":"MIT","homepage":"https://github.com/Cartisien/extensa#readme","keywords":["ai","embeddings","vector","matryoshka","local-first","ollama","semantic-search"],"repository":{"type":"git","url":"git+https://github.com/Cartisien/extensa.git"},"description":"Vector infrastructure and Matryoshka embeddings for AI agents.","maintainers":[{"name":"mrwitters","email":"cartisien@cartisien.com"}],"readme":"# @cartisien/extensa\n\n> **Vector infrastructure and Matryoshka embeddings for AI agents.**\n\nPart of the [Cartisien Memory Suite](https://github.com/Cartisien) — *res extensa* to Cogito's *res cogitans* and Engram's trace.\n\n[![npm](https://img.shields.io/npm/v/@cartisien/extensa)](https://www.npmjs.com/package/@cartisien/extensa)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n---\n\n## What is Extensa?\n\nExtensa is the vector infrastructure layer for the Cartisien Memory Suite. While [Engram](https://github.com/Cartisien/engram) handles memory storage and retrieval, Extensa manages the raw embedding pipeline:\n\n- **Matryoshka embeddings** — adaptive dimensionality (768 → 512 → 256 → 128) from a single model pass\n- **Model management** — Ollama integration, fallback chains, batch embedding\n- **Similarity primitives** — cosine, dot product, L2 distance\n- **Caching** — LRU cache for repeated embedding calls\n- **Normalization** — L2 normalization, whitening\n\n```typescript\nimport { Extensa } from '@cartisien/extensa';\n\nconst vec = new Extensa({ ollamaUrl: 'http://localhost:11434', model: 'nomic-embed-text' });\n\n// Embed a single string\nconst embedding = await vec.embed('User prefers TypeScript');\n// → number[] (768 dims by default)\n\n// Matryoshka — get multiple sizes in one pass\nconst { full, half, quarter } = await vec.embedMatryoshka('User prefers TypeScript');\n// → { full: number[768], half: number[384], quarter: number[192] }\n\n// Batch\nconst embeddings = await vec.embedBatch(['text one', 'text two', 'text three']);\n\n// Similarity\nconst score = vec.cosine(embedding, otherEmbedding);\n```\n\n---\n\n## Why Matryoshka?\n\nStandard 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:\n\n- Store full 768-dim vectors for high-recall search\n- Use 128-dim projections for fast candidate filtering\n- Adaptive precision — trade accuracy for speed at query time\n\nExtensa handles the dimension slicing, normalization, and storage recommendations automatically.\n\n---\n\n## API (v0.2 — coming soon)\n\n### `new Extensa(config)`\n\n```typescript\nconst vec = new Extensa({\n  ollamaUrl: 'http://localhost:11434',  // local Ollama\n  model: 'nomic-embed-text',            // embedding model\n  dimensions: 768,                       // output dimensions\n  cache: true,                           // LRU cache (default: true)\n  cacheSize: 1000,                       // max cached embeddings\n});\n```\n\n### `embed(text): Promise<number[]>`\nEmbed a single string. Returns L2-normalized vector.\n\n### `embedBatch(texts): Promise<number[][]>`\nEmbed multiple strings in parallel with rate limiting.\n\n### `embedMatryoshka(text): Promise<MatryoshkaResult>`\nReturn multiple dimension slices from a single embedding pass.\n\n### Similarity\n\n```typescript\nvec.cosine(a, b)    // cosine similarity → [0, 1]\nvec.dot(a, b)       // dot product\nvec.l2(a, b)        // L2 distance\n```\n\n---\n\n## The Cartisien Memory Suite\n\n| Package | Role | Status |\n|---------|------|--------|\n| [`@cartisien/engram`](https://github.com/Cartisien/engram) | Persistent memory | ✅ Stable |\n| [`@cartisien/cogito`](https://github.com/Cartisien/cogito) | Agent lifecycle & identity | 🔧 In development |\n| [`@cartisien/extensa`](https://github.com/Cartisien/extensa) | Vector infrastructure | 🔧 In development |\n\n*\"Res cogitans meets res extensa.\"*\n\n---\n\n## Research\n\nThis package is part of the Cartisien Memory Suite described in:\n\n> Cartisien. (2026). *Engram: A Local-First Persistent Memory Architecture for Conversational AI Agents*. Zenodo. https://doi.org/10.5281/zenodo.18988892\n\n---\n\n## License\n\nMIT © [Cartisien](https://cartisien.com)\n","readmeFilename":"README.md"}