@plures/superlocalmemory-mcp 0.2.0

package/README.md

@@ -0,0 +1,228 @@
+# @plures/superlocalmemory-mcp
+
+MCP (Model Context Protocol) server for **superlocalmemory** — a **local-first, persistent vector memory** for AI coding assistants.
+
+It exposes a small set of MCP **tools** and **resources** so editors like VS Code (Copilot MCP), Cursor, Continue, and Claude Desktop can store and recall long-term memory during coding sessions.
+
+- Storage: local SQLite file (better-sqlite3)
+- Retrieval: semantic vector search
+- Embeddings: **Transformers.js (default, zero-config)** or OpenAI (optional)
+
+## ✨ Zero-Config Usage
+
+**No API keys required!** Just run:
+
+```bash
+npx @plures/superlocalmemory-mcp
+```
+
+The server uses **Transformers.js** to run embeddings locally in-process with the `bge-small-en-v1.5` model (384 dimensions).
+
+> **Note:** First run will download the model (~100MB) to `~/.cache/superlocalmemory/transformers`. Subsequent runs are instant and fully offline.
+
+## Install
+
+```bash
+# Run directly (recommended):
+npx @plures/superlocalmemory-mcp
+
+# Or install globally:
+npm install -g @plures/superlocalmemory-mcp
+```
+
+## Configuration
+
+All configuration is **optional**:
+
+### Environment Variables
+
+- `SUPERLOCALMEMORY_DB_PATH` (optional) — SQLite DB path (default: `~/.superlocalmemory/mcp.db`)
+- `SUPERLOCALMEMORY_DEBUG` (optional) — set to `true` for debug logs to stderr
+- `SUPERLOCALMEMORY_CACHE_DIR` (optional) — Transformers.js model cache directory (default: `~/.cache/superlocalmemory/transformers`)
+- `OPENAI_API_KEY` (optional) — use OpenAI embeddings instead of local Transformers.js
+- `OPENAI_EMBEDDING_MODEL` (optional) — OpenAI model to use (default: `text-embedding-3-small`)
+
+### Using OpenAI (Optional)
+
+If you prefer OpenAI embeddings over local Transformers.js:
+
+1. Set `OPENAI_API_KEY` in your environment
+2. The server will use OpenAI with 1536-dim embeddings
+
+## Migration / Breaking Changes
+
+> **Important:** Embedding dimensions are **not** interchangeable. Transformers.js uses **384‑dim** embeddings, while OpenAI uses **1536‑dim** embeddings by default.
+
+If you already have an existing database:
+
+- **Databases created with OpenAI embeddings must continue using `OPENAI_API_KEY`.**
+  - Do **not** switch that database to Transformers.js; the stored vectors will be incompatible.
+  - The server will detect dimension mismatches and provide a clear error message.
+- There is **no automatic migration** between 384‑dim and 1536‑dim embeddings.
+- To change providers (OpenAI ⇄ Transformers.js), you must either:
+  - Point `SUPERLOCALMEMORY_DB_PATH` to a **new database**, or
+  - Delete/recreate the existing DB and **re-index all memories**.
+## Editor setup
+
+### Zero-Config Examples
+
+These examples require **no environment variables** and work out of the box:
+
+#### VS Code (Copilot) — `mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "superlocalmemory": {
+      "command": "npx",
+      "args": ["@plures/superlocalmemory-mcp"]
+    }
+  }
+}
+```
+
+#### Cursor — `settings.json`
+
+```json
+{
+  "mcpServers": {
+    "superlocalmemory": {
+      "command": "npx",
+      "args": ["@plures/superlocalmemory-mcp"]
+    }
+  }
+}
+```
+
+#### Continue.dev — `config.json`
+
+```json
+{
+  "mcpServers": [
+    {
+      "name": "superlocalmemory",
+      "command": "npx",
+      "args": ["@plures/superlocalmemory-mcp"]
+    }
+  ]
+}
+```
+
+#### Claude Desktop — `claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "superlocalmemory": {
+      "command": "npx",
+      "args": ["@plures/superlocalmemory-mcp"]
+    }
+  }
+}
+```
+
+### With OpenAI (Optional)
+
+If you prefer OpenAI embeddings:
+
+```json
+{
+  "mcpServers": {
+    "superlocalmemory": {
+      "command": "npx",
+      "args": ["@plures/superlocalmemory-mcp"],
+      "env": {
+        "OPENAI_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### `memory_store`
+Store a memory.
+
+**Input**
+- `content` (string, required)
+- `tags` (string[], optional)
+- `category` (string, optional)
+- `source` (string, optional)
+
+### `memory_search`
+Semantic search.
+
+**Input**
+- `query` (string, required)
+- `limit` (number, optional, default 5)
+- `minScore` (number, optional, default 0.3)
+
+### `memory_forget`
+Delete by UUID `id` or by semantic `query`.
+
+**Input**
+- `id` (string, optional)
+- `query` (string, optional)
+- `threshold` (number, optional, default 0.8)
+
+### `memory_profile`
+Return the stored user profile summary (if any).
+
+### `memory_index`
+Index a directory by storing file contents as memories.
+
+**Input**
+- `directory` (string, required)
+- `maxFiles` (number, optional, default 500)
+- `maxBytesPerFile` (number, optional, default 200000)
+- `category` (string, optional, default `project-context`)
+- `tags` (string[], optional)
+
+### `memory_stats`
+Return database stats.
+
+## Resources
+
+- `memory://profile` — JSON user profile (if available)
+- `memory://recent` — markdown list of the 20 most recent memory contents
+- `memory://stats` — JSON stats
+
+## How it works
+
+This server provides local-first persistent memory with:
+
+- **Local SQLite database** stores memory rows with embeddings
+- **Embeddings**: 
+  - Default: Transformers.js (`bge-small-en-v1.5`, 384-dim) — runs in-process, zero-config
+  - Optional: OpenAI API (`text-embedding-3-small`, 1536-dim) — requires API key
+- **Vector search**: In-process cosine similarity against stored embeddings
+- **Indexing**: `memory_index` walks a directory, reads text files, and stores them for later retrieval
+
+## Privacy
+
+All memory data is stored **locally** on your machine at `SUPERLOCALMEMORY_DB_PATH` (default: `~/.superlocalmemory/mcp.db`).
+
+### Network Usage
+
+- **Transformers.js (default)**: One-time model download (~100MB) on first run, then 100% offline
+- **OpenAI (optional)**: API calls for each embedding when `OPENAI_API_KEY` is set
+
+No memory content is ever sent to external services except for embedding generation when using OpenAI.
+
+## Development
+
+```bash
+npm install
+npm run dev
+```
+
+Build:
+
+```bash
+npm run build
+```
+
+## License
+
+AGPL-3.0

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+export interface McpConfig {
+    dbPath: string;
+    openaiApiKey?: string;
+    openaiModel?: string;
+    debug: boolean;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): McpConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,OAAO,CAAC;CAChB;AASD,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,SAAS,CAO1E"}

package/dist/config.js

@@ -0,0 +1,19 @@
+import os from "node:os";
+import path from "node:path";
+function expandHome(p) {
+    if (!p)
+        return p;
+    if (p === "~")
+        return os.homedir();
+    if (p.startsWith("~/"))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+export function loadConfig(env = process.env) {
+    const dbPath = expandHome(env.SUPERLOCALMEMORY_DB_PATH ?? "~/.superlocalmemory/mcp.db");
+    const openaiApiKey = env.OPENAI_API_KEY;
+    const openaiModel = env.OPENAI_EMBEDDING_MODEL;
+    const debug = (env.SUPERLOCALMEMORY_DEBUG ?? "").toLowerCase() === "true";
+    return { dbPath, openaiApiKey, openaiModel, debug };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAS7B,SAAS,UAAU,CAAC,CAAS;IAC3B,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC;IACjB,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;IACnC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,wBAAwB,IAAI,4BAA4B,CAAC,CAAC;IACxF,MAAM,YAAY,GAAG,GAAG,CAAC,cAAc,CAAC;IACxC,MAAM,WAAW,GAAG,GAAG,CAAC,sBAAsB,CAAC;IAC/C,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;IAE1E,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;AACtD,CAAC"}

package/dist/db/memory.d.ts

@@ -0,0 +1,95 @@
+export interface MemoryEntry {
+    id: string;
+    content: string;
+    embedding: string;
+    tags: string[];
+    category?: string;
+    source: string;
+    created_at: number;
+}
+export interface StoreOptions {
+    tags?: string[];
+    category?: string;
+    source?: string;
+    dedupeThreshold?: number;
+}
+export interface StoreResult {
+    entry: MemoryEntry;
+    isDuplicate: boolean;
+    updatedId?: string;
+}
+export interface SearchResult {
+    entry: MemoryEntry;
+    score: number;
+}
+/**
+ * Local SQLite-based vector memory database.
+ * Supports storage, cosine similarity search, and CRUD operations.
+ */
+export declare class MemoryDB {
+    private db;
+    private dimension;
+    constructor(dbPath: string, dimension: number);
+    private initTables;
+    /**
+     * Validate that existing embeddings in the database match the configured dimension.
+     * This prevents dimension mismatches when switching between embedding providers.
+     */
+    private validateDimension;
+    /**
+     * Calculate cosine similarity between two vectors
+     */
+    private cosineSimilarity;
+    /**
+     * Store a memory with deduplication
+     */
+    store(content: string, embedding: number[], options?: StoreOptions): Promise<StoreResult>;
+    /**
+     * Find a similar memory above threshold (for deduplication)
+     */
+    private findSimilar;
+    /**
+     * Vector search using cosine similarity.
+     *
+     * Performance note: This implementation loads all embeddings into memory and performs
+     * brute-force cosine similarity computation. For large databases (>10,000 memories),
+     * this may have performance implications. Future optimizations could include:
+     * - Approximate nearest neighbor search (ANN)
+     * - Vector indexing (e.g., HNSW, IVF)
+     * - Limiting search scope with filters
+     */
+    vectorSearch(queryEmbedding: number[], limit?: number, minScore?: number): Promise<SearchResult[]>;
+    /**
+     * Delete a memory by ID
+     */
+    delete(id: string): void;
+    /**
+     * Delete memories matching a query above threshold
+     */
+    deleteByQuery(queryEmbedding: number[], threshold?: number): Promise<number>;
+    /**
+     * Get user profile (stub - not implemented in core)
+     */
+    getProfile(): string | null;
+    /**
+     * Get all memory content (limited)
+     */
+    getAllContent(limit?: number): string[];
+    /**
+     * Get database statistics
+     */
+    stats(): {
+        totalMemories: number;
+        captureCount: number;
+        dimension: number;
+    };
+    /**
+     * Increment capture count
+     */
+    incrementCaptureCount(): void;
+    /**
+     * Close database connection
+     */
+    close(): void;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/db/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/db/memory.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,WAAW,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,EAAE,CAAoB;IAC9B,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAQ7C,OAAO,CAAC,UAAU;IAiClB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA0BzB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAmBxB;;OAEG;IACG,KAAK,CACT,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EAAE,EACnB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC;IAwEvB;;OAEG;YACW,WAAW;IAQzB;;;;;;;;;OASG;IACG,YAAY,CAChB,cAAc,EAAE,MAAM,EAAE,EACxB,KAAK,SAAI,EACT,QAAQ,SAAM,GACb,OAAO,CAAC,YAAY,EAAE,CAAC;IAkD1B;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIxB;;OAEG;IACG,aAAa,CACjB,cAAc,EAAE,MAAM,EAAE,EACxB,SAAS,SAAM,GACd,OAAO,CAAC,MAAM,CAAC;IAYlB;;OAEG;IACH,UAAU,IAAI,MAAM,GAAG,IAAI;IAM3B;;OAEG;IACH,aAAa,CAAC,KAAK,SAAK,GAAG,MAAM,EAAE;IAQnC;;OAEG;IACH,KAAK,IAAI;QACP,aAAa,EAAE,MAAM,CAAC;QACtB,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;KACnB;IAkBD;;OAEG;IACH,qBAAqB,IAAI,IAAI;IAO7B;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/db/memory.js

@@ -0,0 +1,245 @@
+import Database from "better-sqlite3";
+import { randomUUID } from "node:crypto";
+/**
+ * Local SQLite-based vector memory database.
+ * Supports storage, cosine similarity search, and CRUD operations.
+ */
+export class MemoryDB {
+    db;
+    dimension;
+    constructor(dbPath, dimension) {
+        this.dimension = dimension;
+        this.db = new Database(dbPath);
+        this.db.pragma("journal_mode = WAL");
+        this.initTables();
+        this.validateDimension();
+    }
+    initTables() {
+        // Create memories table
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS memories (
+        id TEXT PRIMARY KEY,
+        content TEXT NOT NULL,
+        embedding TEXT NOT NULL,
+        tags TEXT,
+        category TEXT,
+        source TEXT,
+        created_at INTEGER NOT NULL
+      )
+    `);
+        // Create metadata table for stats
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS metadata (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      )
+    `);
+        // Initialize capture count if not exists
+        const stmt = this.db.prepare("SELECT value FROM metadata WHERE key = ?");
+        const row = stmt.get("capture_count");
+        if (!row) {
+            this.db.prepare("INSERT INTO metadata (key, value) VALUES (?, ?)").run("capture_count", "0");
+        }
+    }
+    /**
+     * Validate that existing embeddings in the database match the configured dimension.
+     * This prevents dimension mismatches when switching between embedding providers.
+     */
+    validateDimension() {
+        const stmt = this.db.prepare("SELECT embedding FROM memories LIMIT 1");
+        const row = stmt.get();
+        if (row) {
+            try {
+                const existingEmbedding = JSON.parse(row.embedding);
+                if (existingEmbedding.length !== this.dimension) {
+                    throw new Error(`Database dimension mismatch: Database contains ${existingEmbedding.length}-dim embeddings, ` +
+                        `but configured provider uses ${this.dimension}-dim embeddings. ` +
+                        `To fix this, either:\n` +
+                        `  1. Set OPENAI_API_KEY to use OpenAI (1536-dim) if database was created with OpenAI\n` +
+                        `  2. Use a new database path with SUPERLOCALMEMORY_DB_PATH\n` +
+                        `  3. Delete the existing database to start fresh with ${this.dimension}-dim embeddings`);
+                }
+            }
+            catch (err) {
+                if (err instanceof Error && err.message.includes("Database dimension mismatch")) {
+                    throw err;
+                }
+                // Ignore JSON parse errors for corrupted data - will be handled during search
+            }
+        }
+    }
+    /**
+     * Calculate cosine similarity between two vectors
+     */
+    cosineSimilarity(a, b) {
+        if (a.length !== b.length) {
+            throw new Error(`Vector dimension mismatch: ${a.length} vs ${b.length}`);
+        }
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dotProduct += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        const denom = Math.sqrt(normA) * Math.sqrt(normB);
+        return denom === 0 ? 0 : dotProduct / denom;
+    }
+    /**
+     * Store a memory with deduplication
+     */
+    async store(content, embedding, options = {}) {
+        const { tags = [], category, source = "", dedupeThreshold = 0.95, } = options;
+        // Check for duplicates
+        const existing = await this.findSimilar(embedding, dedupeThreshold);
+        if (existing) {
+            // Update existing entry
+            const stmt = this.db.prepare("UPDATE memories SET content = ?, embedding = ?, tags = ?, category = ?, source = ?, created_at = ? WHERE id = ?");
+            stmt.run(content, JSON.stringify(embedding), JSON.stringify(tags), category || null, source, Date.now(), existing.id);
+            return {
+                entry: {
+                    ...existing,
+                    content,
+                    embedding: JSON.stringify(embedding),
+                    tags,
+                    category,
+                    source,
+                    created_at: Date.now(),
+                },
+                isDuplicate: true,
+                updatedId: existing.id,
+            };
+        }
+        // Insert new entry
+        const id = randomUUID();
+        const created_at = Date.now();
+        const stmt = this.db.prepare("INSERT INTO memories (id, content, embedding, tags, category, source, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)");
+        stmt.run(id, content, JSON.stringify(embedding), JSON.stringify(tags), category || null, source, created_at);
+        return {
+            entry: {
+                id,
+                content,
+                embedding: JSON.stringify(embedding),
+                tags,
+                category,
+                source,
+                created_at,
+            },
+            isDuplicate: false,
+        };
+    }
+    /**
+     * Find a similar memory above threshold (for deduplication)
+     */
+    async findSimilar(embedding, threshold) {
+        const results = await this.vectorSearch(embedding, 1, threshold);
+        return results.length > 0 ? results[0].entry : null;
+    }
+    /**
+     * Vector search using cosine similarity.
+     *
+     * Performance note: This implementation loads all embeddings into memory and performs
+     * brute-force cosine similarity computation. For large databases (>10,000 memories),
+     * this may have performance implications. Future optimizations could include:
+     * - Approximate nearest neighbor search (ANN)
+     * - Vector indexing (e.g., HNSW, IVF)
+     * - Limiting search scope with filters
+     */
+    async vectorSearch(queryEmbedding, limit = 5, minScore = 0.3) {
+        const stmt = this.db.prepare("SELECT * FROM memories");
+        const rows = stmt.all();
+        const results = [];
+        for (const row of rows) {
+            let embedding;
+            try {
+                embedding = JSON.parse(row.embedding);
+            }
+            catch (err) {
+                console.warn(`Skipping memory entry with invalid embedding JSON (id=${row.id}):`, err);
+                continue;
+            }
+            const score = this.cosineSimilarity(queryEmbedding, embedding);
+            if (score >= minScore) {
+                results.push({
+                    entry: {
+                        id: row.id,
+                        content: row.content,
+                        embedding: row.embedding,
+                        tags: JSON.parse(row.tags || "[]"),
+                        category: row.category || undefined,
+                        source: row.source,
+                        created_at: row.created_at,
+                    },
+                    score,
+                });
+            }
+        }
+        // Sort by score descending
+        results.sort((a, b) => b.score - a.score);
+        // Limit results
+        return results.slice(0, limit);
+    }
+    /**
+     * Delete a memory by ID
+     */
+    delete(id) {
+        this.db.prepare("DELETE FROM memories WHERE id = ?").run(id);
+    }
+    /**
+     * Delete memories matching a query above threshold
+     */
+    async deleteByQuery(queryEmbedding, threshold = 0.8) {
+        const matches = await this.vectorSearch(queryEmbedding, 100, threshold);
+        let deleted = 0;
+        for (const match of matches) {
+            this.delete(match.entry.id);
+            deleted++;
+        }
+        return deleted;
+    }
+    /**
+     * Get user profile (stub - not implemented in core)
+     */
+    getProfile() {
+        const stmt = this.db.prepare("SELECT value FROM metadata WHERE key = ?");
+        const row = stmt.get("profile");
+        return row ? row.value : null;
+    }
+    /**
+     * Get all memory content (limited)
+     */
+    getAllContent(limit = 20) {
+        const stmt = this.db.prepare("SELECT content FROM memories ORDER BY created_at DESC LIMIT ?");
+        const rows = stmt.all(limit);
+        return rows.map((r) => r.content);
+    }
+    /**
+     * Get database statistics
+     */
+    stats() {
+        const countStmt = this.db.prepare("SELECT COUNT(*) as count FROM memories");
+        const countRow = countStmt.get();
+        const captureStmt = this.db.prepare("SELECT value FROM metadata WHERE key = ?");
+        const captureRow = captureStmt.get("capture_count");
+        return {
+            totalMemories: countRow.count,
+            captureCount: captureRow ? parseInt(captureRow.value, 10) : 0,
+            dimension: this.dimension,
+        };
+    }
+    /**
+     * Increment capture count
+     */
+    incrementCaptureCount() {
+        const stmt = this.db.prepare("UPDATE metadata SET value = CAST((CAST(value AS INTEGER) + 1) AS TEXT) WHERE key = ?");
+        stmt.run("capture_count");
+    }
+    /**
+     * Close database connection
+     */
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/db/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/db/memory.ts"],"names":[],"mappings":"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"}

package/dist/embeddings/index.d.ts

@@ -0,0 +1,16 @@
+import { TransformersEmbeddings } from "./transformers.js";
+import { OpenAIEmbeddings } from "./openai.js";
+import type { EmbeddingProvider } from "./transformers.js";
+export type { EmbeddingProvider };
+export { TransformersEmbeddings, OpenAIEmbeddings };
+export interface EmbeddingConfig {
+    openaiApiKey?: string;
+    openaiModel?: string;
+    debug?: boolean;
+}
+/**
+ * Create an embedding provider based on available configuration.
+ * Defaults to Transformers.js (zero-config), with OpenAI as optional override.
+ */
+export declare function createEmbeddings(config?: EmbeddingConfig): Promise<EmbeddingProvider>;
+//# sourceMappingURL=index.d.ts.map

package/dist/embeddings/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/embeddings/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAClC,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,GAAE,eAAoB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,CAmB5B"}

package/dist/embeddings/index.js

@@ -0,0 +1,26 @@
+import { TransformersEmbeddings } from "./transformers.js";
+import { OpenAIEmbeddings } from "./openai.js";
+export { TransformersEmbeddings, OpenAIEmbeddings };
+/**
+ * Create an embedding provider based on available configuration.
+ * Defaults to Transformers.js (zero-config), with OpenAI as optional override.
+ */
+export async function createEmbeddings(config = {}) {
+    const { openaiApiKey, openaiModel, debug = false } = config;
+    // If OpenAI key is provided, use OpenAI (fail fast on error)
+    if (openaiApiKey) {
+        if (debug) {
+            console.error("[Embeddings] Using OpenAI provider");
+        }
+        // When an explicit OpenAI API key is provided, fail fast instead of silently
+        // falling back to a different provider with incompatible dimensions.
+        // This prevents dimension mismatch errors with existing databases.
+        return new OpenAIEmbeddings(openaiApiKey, openaiModel, debug);
+    }
+    // Default: Transformers.js (zero-config)
+    if (debug) {
+        console.error("[Embeddings] Using Transformers.js provider (zero-config)");
+    }
+    return new TransformersEmbeddings(debug);
+}
+//# sourceMappingURL=index.js.map

package/dist/embeddings/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/embeddings/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAI/C,OAAO,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,CAAC;AAQpD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,SAA0B,EAAE;IAE5B,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,KAAK,GAAG,KAAK,EAAE,GAAG,MAAM,CAAC;IAE5D,6DAA6D;IAC7D,IAAI,YAAY,EAAE,CAAC;QACjB,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACtD,CAAC;QACD,6EAA6E;QAC7E,qEAAqE;QACrE,mEAAmE;QACnE,OAAO,IAAI,gBAAgB,CAAC,YAAY,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC;IAChE,CAAC;IAED,yCAAyC;IACzC,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,CAAC,KAAK,CAAC,2DAA2D,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,IAAI,sBAAsB,CAAC,KAAK,CAAC,CAAC;AAC3C,CAAC"}