@fgv/ts-agent-memory-sqlite-vec 5.1.0-42

package/lib/test/unit/sqliteVecVectorIndex.test.js

@@ -0,0 +1,237 @@
+"use strict";
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("@fgv/ts-utils-jest");
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const index_1 = require("../../index");
+function target(scope, id) {
+    return { scope: scope, id: id };
+}
+function vec(...values) {
+    return Float32Array.from(values);
+}
+describe('SqliteVecVectorIndex', () => {
+    let db;
+    beforeEach(() => {
+        db = new better_sqlite3_1.default(':memory:');
+    });
+    afterEach(() => {
+        db.close();
+    });
+    async function makeIndex() {
+        return (await index_1.SqliteVecVectorIndex.create({ database: db })).orThrow();
+    }
+    describe('create', () => {
+        test('succeeds over a fresh database with an empty index', async () => {
+            expect(await index_1.SqliteVecVectorIndex.create({ database: db })).toSucceedAndSatisfy((index) => {
+                expect(index.size).toBe(0);
+            });
+        });
+        test('rejects a table name that is not a simple identifier', async () => {
+            expect(await index_1.SqliteVecVectorIndex.create({ database: db, tableName: 'bad name; DROP TABLE x' })).toFailWith(/not a simple SQL identifier/i);
+        });
+        test('fails loudly when the sqlite-vec extension cannot load (closed database)', async () => {
+            const closed = new better_sqlite3_1.default(':memory:');
+            closed.close();
+            expect(await index_1.SqliteVecVectorIndex.create({ database: closed })).toFailWith(/failed to initialize/i);
+        });
+        test('recovers no dimension from a pre-existing non-vec0 table of the same name', async () => {
+            // A plain table that happens to share the index's name has no `float[<n>]`
+            // in its DDL, so no dimension is recovered — the index opens as if empty.
+            db.exec('CREATE TABLE memory_vectors (foo TEXT)');
+            expect(await index_1.SqliteVecVectorIndex.create({ database: db })).toSucceedAndSatisfy((index) => {
+                expect(index.size).toBe(0);
+            });
+        });
+    });
+    describe('add', () => {
+        test('adds a vector and returns the canonical scoped key, growing size', async () => {
+            const index = await makeIndex();
+            expect(await index.add(target('knowledge', 'doc-a'), vec(1, 0, 0))).toSucceedWith('knowledge\0doc-a');
+            expect(index.size).toBe(1);
+        });
+        test('rejects an empty vector', async () => {
+            const index = await makeIndex();
+            expect(await index.add(target('knowledge', 'doc-a'), vec())).toFailWith(/cannot add 'knowledge\0doc-a': empty vector/i);
+        });
+        test('rejects a vector whose dimension does not match the established dimension', async () => {
+            const index = await makeIndex();
+            (await index.add(target('knowledge', 'doc-a'), vec(1, 0, 0))).orThrow();
+            expect(await index.add(target('knowledge', 'doc-b'), vec(1, 0))).toFailWith(/dimension 2 does not match index dimension 3/i);
+        });
+        test('replacing an existing target keeps size stable and the new vector wins the query', async () => {
+            const index = await makeIndex();
+            (await index.add(target('knowledge', 'doc-a'), vec(1, 0, 0))).orThrow();
+            (await index.add(target('knowledge', 'doc-a'), vec(0, 0, 1))).orThrow();
+            expect(index.size).toBe(1);
+            expect(await index.query(vec(0, 0, 1), 1)).toSucceedAndSatisfy((hits) => {
+                expect(hits[0].target).toEqual(target('knowledge', 'doc-a'));
+                expect(hits[0].score).toBeCloseTo(1, 5);
+            });
+        });
+        test('two records that share a stem across scopes are distinct entries', async () => {
+            const index = await makeIndex();
+            (await index.add(target('conversations/a', 'turn-3'), vec(1, 0, 0))).orThrow();
+            (await index.add(target('conversations/b', 'turn-3'), vec(0, 1, 0))).orThrow();
+            expect(index.size).toBe(2);
+        });
+    });
+    describe('query', () => {
+        async function seeded() {
+            const index = await makeIndex();
+            (await index.add(target('knowledge', 'x'), vec(1, 0, 0))).orThrow();
+            (await index.add(target('knowledge', 'y'), vec(0, 1, 0))).orThrow();
+            (await index.add(target('knowledge', 'z'), vec(0.9, 0.1, 0))).orThrow();
+            return index;
+        }
+        test('returns hits in descending cosine-similarity score with round-tripped scoped targets', async () => {
+            const index = await seeded();
+            expect(await index.query(vec(1, 0, 0), 3)).toSucceedAndSatisfy((hits) => {
+                expect(hits.map((h) => h.target.id)).toEqual(['x', 'z', 'y']);
+                expect(hits[0].target.scope).toBe('knowledge');
+                expect(hits[0].score).toBeCloseTo(1, 5); // identical
+                expect(hits[2].score).toBeCloseTo(0, 5); // orthogonal
+                // scores are sorted descending
+                expect(hits[0].score).toBeGreaterThan(hits[1].score);
+                expect(hits[1].score).toBeGreaterThan(hits[2].score);
+            });
+        });
+        test('honors topK', async () => {
+            const index = await seeded();
+            expect(await index.query(vec(1, 0, 0), 2)).toSucceedAndSatisfy((hits) => {
+                expect(hits).toHaveLength(2);
+                expect(hits.map((h) => h.target.id)).toEqual(['x', 'z']);
+            });
+        });
+        test('returns empty for topK <= 0', async () => {
+            const index = await seeded();
+            expect(await index.query(vec(1, 0, 0), 0)).toSucceedWith([]);
+            expect(await index.query(vec(1, 0, 0), -5)).toSucceedWith([]);
+        });
+        test('returns empty before any add (no established dimension)', async () => {
+            const index = await makeIndex();
+            expect(await index.query(vec(1, 0, 0), 5)).toSucceedWith([]);
+        });
+        test('rejects a query vector of the wrong dimension', async () => {
+            const index = await seeded();
+            expect(await index.query(vec(1, 0), 3)).toFailWith(/query dimension 2 does not match index dimension 3/i);
+        });
+    });
+    describe('remove', () => {
+        test('removes an entry and shrinks size, returning the target', async () => {
+            const index = await makeIndex();
+            (await index.add(target('knowledge', 'doc-a'), vec(1, 0, 0))).orThrow();
+            (await index.add(target('knowledge', 'doc-b'), vec(0, 1, 0))).orThrow();
+            expect(await index.remove(target('knowledge', 'doc-a'))).toSucceedWith(target('knowledge', 'doc-a'));
+            expect(index.size).toBe(1);
+            expect(await index.query(vec(1, 0, 0), 5)).toSucceedAndSatisfy((hits) => {
+                expect(hits.map((h) => h.target.id)).toEqual(['doc-b']);
+            });
+        });
+        test('is idempotent — removing a missing target succeeds', async () => {
+            const index = await makeIndex();
+            (await index.add(target('knowledge', 'doc-a'), vec(1, 0, 0))).orThrow();
+            expect(await index.remove(target('knowledge', 'missing'))).toSucceedWith(target('knowledge', 'missing'));
+            expect(index.size).toBe(1);
+        });
+        test('succeeds before any add (no table yet)', async () => {
+            const index = await makeIndex();
+            expect(await index.remove(target('knowledge', 'doc-a'))).toSucceedWith(target('knowledge', 'doc-a'));
+            expect(index.size).toBe(0);
+        });
+    });
+    describe('custom table name', () => {
+        test('two indexes on distinct tables in one database are independent', async () => {
+            const a = (await index_1.SqliteVecVectorIndex.create({ database: db, tableName: 'idx_a' })).orThrow();
+            const b = (await index_1.SqliteVecVectorIndex.create({ database: db, tableName: 'idx_b' })).orThrow();
+            (await a.add(target('s', 'one'), vec(1, 0))).orThrow();
+            expect(a.size).toBe(1);
+            expect(b.size).toBe(0);
+        });
+    });
+    describe('persistence across reopen (the durability guarantee)', () => {
+        let dir;
+        let dbPath;
+        beforeEach(() => {
+            dir = fs.mkdtempSync(path.join(os.tmpdir(), 'svtest-'));
+            dbPath = path.join(dir, 'vectors.db');
+        });
+        afterEach(() => {
+            fs.rmSync(dir, { recursive: true, force: true });
+        });
+        test('vectors written to a file survive a close + reopen with no re-embed, and the dimension is recovered', async () => {
+            // First session: write three embeddings, then close the connection entirely.
+            const first = new better_sqlite3_1.default(dbPath);
+            const writeIndex = (await index_1.SqliteVecVectorIndex.create({ database: first })).orThrow();
+            (await writeIndex.add(target('knowledge', 'x'), vec(1, 0, 0))).orThrow();
+            (await writeIndex.add(target('knowledge', 'y'), vec(0, 1, 0))).orThrow();
+            (await writeIndex.add(target('conversations/c', 'turn-1'), vec(0.9, 0.1, 0))).orThrow();
+            first.close();
+            // Second session: a brand-new connection + index over the same file. No add
+            // calls (no re-embedding) — the vectors and the established dimension come
+            // straight off disk.
+            const second = new better_sqlite3_1.default(dbPath);
+            const reopened = (await index_1.SqliteVecVectorIndex.create({ database: second })).orThrow();
+            try {
+                expect(reopened.size).toBe(3);
+                expect(await reopened.query(vec(1, 0, 0), 3)).toSucceedAndSatisfy((hits) => {
+                    expect(hits.map((h) => h.target.id)).toEqual(['x', 'turn-1', 'y']);
+                    expect(hits[0].score).toBeCloseTo(1, 5);
+                    // the cross-scope target round-trips its full (scope, id)
+                    expect(hits[1].target).toEqual(target('conversations/c', 'turn-1'));
+                });
+                // The recovered dimension is enforced on a post-reopen add.
+                expect(await reopened.add(target('knowledge', 'w'), vec(1, 0))).toFailWith(/dimension 2 does not match index dimension 3/i);
+                // A matching-dimension add still works and persists incrementally.
+                (await reopened.add(target('knowledge', 'w'), vec(0, 0, 1))).orThrow();
+                expect(reopened.size).toBe(4);
+            }
+            finally {
+                second.close();
+            }
+        });
+    });
+});
+//# sourceMappingURL=sqliteVecVectorIndex.test.js.map

package/lib/test/unit/sqliteVecVectorIndex.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqliteVecVectorIndex.test.js","sourceRoot":"","sources":["../../../src/test/unit/sqliteVecVectorIndex.test.ts"],"names":[],"mappings":"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","sourcesContent":["/*\n * Copyright (c) 2026 Erik Fortune\n * SPDX-License-Identifier: MIT\n */\n\nimport '@fgv/ts-utils-jest';\n\nimport BetterSqlite3 from 'better-sqlite3';\nimport * as fs from 'fs';\nimport * as os from 'os';\nimport * as path from 'path';\nimport { IEdgeTarget, IVectorQueryHit, MemoryId, MemoryScopeKey } from '@fgv/ts-agent-memory';\nimport { SqliteVecVectorIndex } from '../../index';\n\nfunction target(scope: string, id: string): IEdgeTarget {\n  return { scope: scope as unknown as MemoryScopeKey, id: id as unknown as MemoryId };\n}\nfunction vec(...values: number[]): Float32Array {\n  return Float32Array.from(values);\n}\n\ndescribe('SqliteVecVectorIndex', () => {\n  let db: BetterSqlite3.Database;\n\n  beforeEach(() => {\n    db = new BetterSqlite3(':memory:');\n  });\n  afterEach(() => {\n    db.close();\n  });\n\n  async function makeIndex(): Promise<SqliteVecVectorIndex> {\n    return (await SqliteVecVectorIndex.create({ database: db })).orThrow();\n  }\n\n  describe('create', () => {\n    test('succeeds over a fresh database with an empty index', async () => {\n      expect(await SqliteVecVectorIndex.create({ database: db })).toSucceedAndSatisfy(\n        (index: SqliteVecVectorIndex) => {\n          expect(index.size).toBe(0);\n        }\n      );\n    });\n\n    test('rejects a table name that is not a simple identifier', async () => {\n      expect(\n        await SqliteVecVectorIndex.create({ database: db, tableName: 'bad name; DROP TABLE x' })\n      ).toFailWith(/not a simple SQL identifier/i);\n    });\n\n    test('fails loudly when the sqlite-vec extension cannot load (closed database)', async () => {\n      const closed = new BetterSqlite3(':memory:');\n      closed.close();\n      expect(await SqliteVecVectorIndex.create({ database: closed })).toFailWith(/failed to initialize/i);\n    });\n\n    test('recovers no dimension from a pre-existing non-vec0 table of the same name', async () => {\n      // A plain table that happens to share the index's name has no `float[<n>]`\n      // in its DDL, so no dimension is recovered — the index opens as if empty.\n      db.exec('CREATE TABLE memory_vectors (foo TEXT)');\n      expect(await SqliteVecVectorIndex.create({ database: db })).toSucceedAndSatisfy(\n        (index: SqliteVecVectorIndex) => {\n          expect(index.size).toBe(0);\n        }\n      );\n    });\n  });\n\n  describe('add', () => {\n    test('adds a vector and returns the canonical scoped key, growing size', async () => {\n      const index = await makeIndex();\n      expect(await index.add(target('knowledge', 'doc-a'), vec(1, 0, 0))).toSucceedWith('knowledge\\0doc-a');\n      expect(index.size).toBe(1);\n    });\n\n    test('rejects an empty vector', async () => {\n      const index = await makeIndex();\n      expect(await index.add(target('knowledge', 'doc-a'), vec())).toFailWith(\n        /cannot add 'knowledge\\0doc-a': empty vector/i\n      );\n    });\n\n    test('rejects a vector whose dimension does not match the established dimension', async () => {\n      const index = await makeIndex();\n      (await index.add(target('knowledge', 'doc-a'), vec(1, 0, 0))).orThrow();\n      expect(await index.add(target('knowledge', 'doc-b'), vec(1, 0))).toFailWith(\n        /dimension 2 does not match index dimension 3/i\n      );\n    });\n\n    test('replacing an existing target keeps size stable and the new vector wins the query', async () => {\n      const index = await makeIndex();\n      (await index.add(target('knowledge', 'doc-a'), vec(1, 0, 0))).orThrow();\n      (await index.add(target('knowledge', 'doc-a'), vec(0, 0, 1))).orThrow();\n      expect(index.size).toBe(1);\n      expect(await index.query(vec(0, 0, 1), 1)).toSucceedAndSatisfy(\n        (hits: ReadonlyArray<IVectorQueryHit>) => {\n          expect(hits[0].target).toEqual(target('knowledge', 'doc-a'));\n          expect(hits[0].score).toBeCloseTo(1, 5);\n        }\n      );\n    });\n\n    test('two records that share a stem across scopes are distinct entries', async () => {\n      const index = await makeIndex();\n      (await index.add(target('conversations/a', 'turn-3'), vec(1, 0, 0))).orThrow();\n      (await index.add(target('conversations/b', 'turn-3'), vec(0, 1, 0))).orThrow();\n      expect(index.size).toBe(2);\n    });\n  });\n\n  describe('query', () => {\n    async function seeded(): Promise<SqliteVecVectorIndex> {\n      const index = await makeIndex();\n      (await index.add(target('knowledge', 'x'), vec(1, 0, 0))).orThrow();\n      (await index.add(target('knowledge', 'y'), vec(0, 1, 0))).orThrow();\n      (await index.add(target('knowledge', 'z'), vec(0.9, 0.1, 0))).orThrow();\n      return index;\n    }\n\n    test('returns hits in descending cosine-similarity score with round-tripped scoped targets', async () => {\n      const index = await seeded();\n      expect(await index.query(vec(1, 0, 0), 3)).toSucceedAndSatisfy(\n        (hits: ReadonlyArray<IVectorQueryHit>) => {\n          expect(hits.map((h) => h.target.id)).toEqual(['x', 'z', 'y']);\n          expect(hits[0].target.scope).toBe('knowledge');\n          expect(hits[0].score).toBeCloseTo(1, 5); // identical\n          expect(hits[2].score).toBeCloseTo(0, 5); // orthogonal\n          // scores are sorted descending\n          expect(hits[0].score).toBeGreaterThan(hits[1].score);\n          expect(hits[1].score).toBeGreaterThan(hits[2].score);\n        }\n      );\n    });\n\n    test('honors topK', async () => {\n      const index = await seeded();\n      expect(await index.query(vec(1, 0, 0), 2)).toSucceedAndSatisfy(\n        (hits: ReadonlyArray<IVectorQueryHit>) => {\n          expect(hits).toHaveLength(2);\n          expect(hits.map((h) => h.target.id)).toEqual(['x', 'z']);\n        }\n      );\n    });\n\n    test('returns empty for topK <= 0', async () => {\n      const index = await seeded();\n      expect(await index.query(vec(1, 0, 0), 0)).toSucceedWith([]);\n      expect(await index.query(vec(1, 0, 0), -5)).toSucceedWith([]);\n    });\n\n    test('returns empty before any add (no established dimension)', async () => {\n      const index = await makeIndex();\n      expect(await index.query(vec(1, 0, 0), 5)).toSucceedWith([]);\n    });\n\n    test('rejects a query vector of the wrong dimension', async () => {\n      const index = await seeded();\n      expect(await index.query(vec(1, 0), 3)).toFailWith(\n        /query dimension 2 does not match index dimension 3/i\n      );\n    });\n  });\n\n  describe('remove', () => {\n    test('removes an entry and shrinks size, returning the target', async () => {\n      const index = await makeIndex();\n      (await index.add(target('knowledge', 'doc-a'), vec(1, 0, 0))).orThrow();\n      (await index.add(target('knowledge', 'doc-b'), vec(0, 1, 0))).orThrow();\n      expect(await index.remove(target('knowledge', 'doc-a'))).toSucceedWith(target('knowledge', 'doc-a'));\n      expect(index.size).toBe(1);\n      expect(await index.query(vec(1, 0, 0), 5)).toSucceedAndSatisfy(\n        (hits: ReadonlyArray<IVectorQueryHit>) => {\n          expect(hits.map((h) => h.target.id)).toEqual(['doc-b']);\n        }\n      );\n    });\n\n    test('is idempotent — removing a missing target succeeds', async () => {\n      const index = await makeIndex();\n      (await index.add(target('knowledge', 'doc-a'), vec(1, 0, 0))).orThrow();\n      expect(await index.remove(target('knowledge', 'missing'))).toSucceedWith(\n        target('knowledge', 'missing')\n      );\n      expect(index.size).toBe(1);\n    });\n\n    test('succeeds before any add (no table yet)', async () => {\n      const index = await makeIndex();\n      expect(await index.remove(target('knowledge', 'doc-a'))).toSucceedWith(target('knowledge', 'doc-a'));\n      expect(index.size).toBe(0);\n    });\n  });\n\n  describe('custom table name', () => {\n    test('two indexes on distinct tables in one database are independent', async () => {\n      const a = (await SqliteVecVectorIndex.create({ database: db, tableName: 'idx_a' })).orThrow();\n      const b = (await SqliteVecVectorIndex.create({ database: db, tableName: 'idx_b' })).orThrow();\n      (await a.add(target('s', 'one'), vec(1, 0))).orThrow();\n      expect(a.size).toBe(1);\n      expect(b.size).toBe(0);\n    });\n  });\n\n  describe('persistence across reopen (the durability guarantee)', () => {\n    let dir: string;\n    let dbPath: string;\n\n    beforeEach(() => {\n      dir = fs.mkdtempSync(path.join(os.tmpdir(), 'svtest-'));\n      dbPath = path.join(dir, 'vectors.db');\n    });\n    afterEach(() => {\n      fs.rmSync(dir, { recursive: true, force: true });\n    });\n\n    test('vectors written to a file survive a close + reopen with no re-embed, and the dimension is recovered', async () => {\n      // First session: write three embeddings, then close the connection entirely.\n      const first = new BetterSqlite3(dbPath);\n      const writeIndex = (await SqliteVecVectorIndex.create({ database: first })).orThrow();\n      (await writeIndex.add(target('knowledge', 'x'), vec(1, 0, 0))).orThrow();\n      (await writeIndex.add(target('knowledge', 'y'), vec(0, 1, 0))).orThrow();\n      (await writeIndex.add(target('conversations/c', 'turn-1'), vec(0.9, 0.1, 0))).orThrow();\n      first.close();\n\n      // Second session: a brand-new connection + index over the same file. No add\n      // calls (no re-embedding) — the vectors and the established dimension come\n      // straight off disk.\n      const second = new BetterSqlite3(dbPath);\n      const reopened = (await SqliteVecVectorIndex.create({ database: second })).orThrow();\n      try {\n        expect(reopened.size).toBe(3);\n        expect(await reopened.query(vec(1, 0, 0), 3)).toSucceedAndSatisfy(\n          (hits: ReadonlyArray<IVectorQueryHit>) => {\n            expect(hits.map((h) => h.target.id)).toEqual(['x', 'turn-1', 'y']);\n            expect(hits[0].score).toBeCloseTo(1, 5);\n            // the cross-scope target round-trips its full (scope, id)\n            expect(hits[1].target).toEqual(target('conversations/c', 'turn-1'));\n          }\n        );\n        // The recovered dimension is enforced on a post-reopen add.\n        expect(await reopened.add(target('knowledge', 'w'), vec(1, 0))).toFailWith(\n          /dimension 2 does not match index dimension 3/i\n        );\n        // A matching-dimension add still works and persists incrementally.\n        (await reopened.add(target('knowledge', 'w'), vec(0, 0, 1))).orThrow();\n        expect(reopened.size).toBe(4);\n      } finally {\n        second.close();\n      }\n    });\n  });\n});\n"]}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@fgv/ts-agent-memory-sqlite-vec",
+  "version": "5.1.0-42",
+  "description": "Result-integration boundary providing a persistent, sqlite-vec-backed IVectorIndex for @fgv/ts-agent-memory (survives restarts — no re-embed on open)",
+  "main": "lib/index.js",
+  "types": "dist/ts-agent-memory-sqlite-vec.d.ts",
+  "exports": {
+    ".": {
+      "node": {
+        "import": "./lib/index.js",
+        "require": "./lib/index.js"
+      },
+      "default": {
+        "import": "./lib/index.js",
+        "require": "./lib/index.js"
+      },
+      "types": "./dist/ts-agent-memory-sqlite-vec.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "heft build --clean",
+    "clean": "heft clean",
+    "test": "heft test --clean",
+    "test-handles": "jest --runInBand --detectOpenHandles",
+    "clean-jest": "jest --clear-cache",
+    "update-snapshot": "jest --updateSnapshot",
+    "coverage": "jest --coverage",
+    "lint": "eslint src --ext .ts",
+    "fixlint": "eslint src --ext .ts --fix"
+  },
+  "keywords": [
+    "typescript",
+    "sqlite-vec",
+    "vector-index",
+    "embeddings",
+    "agent-memory",
+    "result"
+  ],
+  "author": "Erik Fortune",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ErikFortune/fgv/issues"
+  },
+  "homepage": "https://github.com/ErikFortune/fgv/tree/main/libraries/ts-agent-memory-sqlite-vec#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ErikFortune/fgv.git"
+  },
+  "sideEffects": false,
+  "dependencies": {},
+  "devDependencies": {
+    "@fgv/heft-dual-rig": "workspace:*",
+    "@fgv/ts-utils": "workspace:*",
+    "@fgv/ts-agent-memory": "workspace:*",
+    "@fgv/ts-utils-jest": "workspace:*",
+    "better-sqlite3": "^12.0.0",
+    "sqlite-vec": "^0.1.9",
+    "@types/better-sqlite3": "^7.6.11",
+    "@microsoft/api-extractor": "^7.55.2",
+    "@rushstack/eslint-config": "4.6.4",
+    "@rushstack/heft": "1.2.7",
+    "@rushstack/heft-jest-plugin": "1.2.6",
+    "@rushstack/heft-node-rig": "2.11.27",
+    "@types/heft-jest": "1.0.6",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.14.9",
+    "@typescript-eslint/eslint-plugin": "^8.52.0",
+    "@typescript-eslint/parser": "^8.52.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-n": "^17.23.1",
+    "eslint-plugin-node": "^11.1.0",
+    "eslint-plugin-promise": "^7.2.1",
+    "eslint-plugin-tsdoc": "~0.5.2",
+    "jest": "^29.7.0",
+    "rimraf": "^6.1.2",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "@fgv/ts-utils": "workspace:*",
+    "@fgv/ts-agent-memory": "workspace:*",
+    "better-sqlite3": "^12.0.0",
+    "sqlite-vec": "^0.1.9"
+  }
+}

package/rush-logs/ts-agent-memory-sqlite-vec.build.cache.log

@@ -0,0 +1,3 @@
+Caching build output folders: dist, lib, temp, .rush/temp/operation/build
+Successfully set cache entry.
+Cache key: 689b960e7e1a3b63bd68fbb91474d5c28d567861

package/rush-logs/ts-agent-memory-sqlite-vec.build.log

@@ -0,0 +1,9 @@
+Invoking: heft build --clean 
+ ---- build started ---- 
+[build:typescript] The TypeScript compiler version 5.9.3 is newer than the latest version that was tested with Heft (5.8); it may not work correctly.
+[build:typescript] Using TypeScript version 5.9.3
+[build:lint] Using ESLint version 9.39.5
+[build:api-extractor] Using API Extractor version 7.58.9
+[build:api-extractor] Analysis will use the bundled TypeScript version 5.9.3
+ ---- build finished (1.357s) ---- 
+-------------------- Finished (1.36s) --------------------

package/src/index.ts

@@ -0,0 +1,6 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './packlets/sqlite-vec-index';

package/src/packlets/sqlite-vec-index/index.ts

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './model';
+export * from './sqliteVecVectorIndex';
+export * from './sqliteVecFragmentIndex';

package/src/packlets/sqlite-vec-index/model.ts

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ * SPDX-License-Identifier: MIT
+ */
+
+import type BetterSqlite3 from 'better-sqlite3';
+
+/**
+ * Parameters for {@link SqliteVecVectorIndex.create}.
+ * @public
+ */
+export interface ISqliteVecVectorIndexCreateParams {
+  /**
+   * A `better-sqlite3` `Database` the consumer owns (bring-your-own, mirroring
+   * the boundary-package convention). The consumer opens it (`new Database(path)`
+   * for a persistent file, or `new Database(':memory:')` for an ephemeral index)
+   * and owns its lifecycle — this index never closes it. `create` loads the
+   * `sqlite-vec` extension onto the connection and, if the vector table already
+   * exists (a reopened persistent file), recovers its established dimension so no
+   * re-embedding is required on open.
+   */
+  readonly database: BetterSqlite3.Database;
+
+  /**
+   * Name of the `vec0` virtual table that holds the embeddings. Must be a simple
+   * SQL identifier (`[A-Za-z_][A-Za-z0-9_]*`). Defaults to `'memory_vectors'`.
+   * Supply a distinct name to hold more than one independent index in a single
+   * database file.
+   */
+  readonly tableName?: string;
+}
+
+/**
+ * Parameters for {@link SqliteVecFragmentIndex.create}.
+ * @public
+ */
+export interface ISqliteVecFragmentIndexCreateParams {
+  /**
+   * A `better-sqlite3` `Database` the consumer owns (bring-your-own, mirroring
+   * {@link ISqliteVecVectorIndexCreateParams.database}). The consumer opens it and
+   * owns its lifecycle — this index never closes it. `create` loads the
+   * `sqlite-vec` extension onto the connection and, if the fragment table already
+   * exists (a reopened persistent file), recovers its established dimension so no
+   * re-embedding is required on open.
+   */
+  readonly database: BetterSqlite3.Database;
+
+  /**
+   * Name of the `vec0` virtual table that holds the fragment embeddings. Must be a
+   * simple SQL identifier (`[A-Za-z_][A-Za-z0-9_]*`). Defaults to
+   * `'memory_fragments'`. Supply a distinct name (distinct from any record-level
+   * {@link SqliteVecVectorIndex} table) to hold more than one independent index in
+   * a single database file.
+   */
+  readonly tableName?: string;
+}