adaptive-context-memory 1.0.0

package/README.md

@@ -0,0 +1,104 @@
+# context-memory-ts 🧠
+
+High-performance, standalone, zero-binary long-term adaptive memory system for AI agents and LLM applications in TypeScript & Node.js.
+
+Ported and optimized from the Python `contextmemory` package.
+
+---
+
+## ✨ Features
+
+- ⚡ **Zero Binary Vector Search:** Flat cosine similarity search in pure TypeScript. No C++ compilation or heavy FAISS binaries needed.
+- 🗄️ **High Performance Local Database:** Fast SQLite persistence via `better-sqlite3`.
+- 🧠 **Dual Memory Engine:** Automatically classifies information into:
+  - **Semantic Facts:** Long-term durable user knowledge (profile, skills, preferences).
+  - **Episodic Bubbles:** Time-sensitive events, tasks, and deadlines with importance scoring.
+- 🔄 **Smart Contradiction Resolution:** LLM agent dynamically decides whether to `ADD`, `UPDATE`, `REPLACE`, `DELETE`, or `NOOP` incoming facts.
+- 🎯 **MMR (Maximum Marginal Relevance) Search:** Re-ranks query results for optimal relevance and diversity.
+- 🚀 **Batch & Cached Embeddings:** Built-in LRU cache and single-call batch embedding to minimize API latency and cost.
+- 🔁 **Resilient Auto-Retry:** Exponential backoff retry wrapper handles rate limits (429) and transient errors automatically.
+- 🤖 **Multi-Provider Support:** Plug-and-play support for **OpenAI** and **OpenRouter**.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install context-memory-ts
+```
+
+*Or install from local tarball bundle:*
+```bash
+npm install /path/to/context-memory-ts-1.0.0.tgz
+```
+
+---
+
+## 🚀 Quick Start
+
+```typescript
+import { configure, createTables, getDb, ContextMemory } from 'context-memory-ts';
+
+// 1. Configure provider and model
+configure({
+  openrouterApiKey: process.env.OPENROUTER_API_KEY, // or openaiApiKey
+  llmProvider: 'openrouter',
+  llmModel: 'openai/gpt-4o-mini',
+});
+
+// 2. Initialize database schema
+createTables();
+
+// 3. Instantiate memory manager
+const db = getDb();
+const memory = new ContextMemory(db);
+
+const CONVERSATION_ID = 1;
+
+// 4. Extract and store memories from chat turns
+await memory.add([
+  { role: 'user', content: "My name is Prince and I'm a TypeScript developer." },
+  { role: 'assistant', content: "Nice to meet you, Prince!" }
+], CONVERSATION_ID);
+
+// 5. Semantic MMR Search
+const searchResult = await memory.search("what is the user's primary programming language?", CONVERSATION_ID);
+console.log(searchResult.results);
+```
+
+---
+
+## 🛠️ API Reference
+
+### `configure(options: ContextMemoryConfig)`
+Configures the global LLM provider, API keys, and embedding models.
+
+### `createTables()`
+Initializes SQLite database tables and index migrations.
+
+### `memory.add(messages, conversationId)`
+Extracts semantic facts and episodic bubbles from recent conversation turns, resolves contradictions, and saves to database & vector store.
+
+### `memory.search(query, conversationId, options)`
+Performs MMR-ranked semantic search. Options include:
+- `limit?: number` (default 10)
+- `mmrLambda?: number` (default 0.6; 0.0 = max diversity, 1.0 = max similarity)
+- `category?: string` (filter by category: `'profile' | 'skill' | 'preference' | ...`)
+
+### `memory.getAll(conversationId, category?)`
+Lists all active memories for a conversation.
+
+### `memory.getStats(conversationId)`
+Returns total count, breakdown by type/category, and embedding cache hit rates.
+
+### `memory.consolidate(conversationId)`
+Scans for near-duplicate semantic facts and merges them into clean, concise facts via LLM.
+
+### `memory.purgeOldBubbles(conversationId, olderThanDays)`
+Soft-deletes episodic bubbles older than $N$ days (default 30 days).
+
+---
+
+## 📄 License
+
+MIT

package/dist/core/llmClient.d.ts

@@ -0,0 +1,14 @@
+/**
+ * LLM & Embedding client factory — TypeScript port of Python openai_client.py
+ *
+ * Uses lazy initialization so clients are created only on first use.
+ * Supports OpenAI and OpenRouter (OpenAI-compatible interface).
+ */
+import OpenAI from "openai";
+/** Get (or lazily create) the LLM client */
+export declare function getLlmClient(): OpenAI;
+/** Get (or lazily create) the embedding client */
+export declare function getEmbeddingClient(): OpenAI;
+/** Reset clients (useful for testing or after reconfigure) */
+export declare function resetClients(): void;
+//# sourceMappingURL=llmClient.d.ts.map

package/dist/core/llmClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmClient.d.ts","sourceRoot":"","sources":["../../src/core/llmClient.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,MAAM,MAAM,QAAQ,CAAC;AAM5B,4CAA4C;AAC5C,wBAAgB,YAAY,IAAI,MAAM,CAmBrC;AAED,kDAAkD;AAClD,wBAAgB,kBAAkB,IAAI,MAAM,CAsB3C;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,IAAI,IAAI,CAGnC"}

package/dist/core/llmClient.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * LLM & Embedding client factory — TypeScript port of Python openai_client.py
+ *
+ * Uses lazy initialization so clients are created only on first use.
+ * Supports OpenAI and OpenRouter (OpenAI-compatible interface).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLlmClient = getLlmClient;
+exports.getEmbeddingClient = getEmbeddingClient;
+exports.resetClients = resetClients;
+const openai_1 = __importDefault(require("openai"));
+const settings_js_1 = require("./settings.js");
+let _llmClient = null;
+let _embeddingClient = null;
+/** Get (or lazily create) the LLM client */
+function getLlmClient() {
+    if (!_llmClient) {
+        const s = (0, settings_js_1.getSettings)();
+        s.validate();
+        if (s.llmProvider === "openrouter") {
+            _llmClient = new openai_1.default({
+                apiKey: s.openrouterApiKey,
+                baseURL: "https://openrouter.ai/api/v1",
+                defaultHeaders: {
+                    "HTTP-Referer": "https://github.com/contextmemory",
+                    "X-Title": "ContextMemory",
+                },
+            });
+        }
+        else {
+            _llmClient = new openai_1.default({ apiKey: s.openaiApiKey });
+        }
+    }
+    return _llmClient;
+}
+/** Get (or lazily create) the embedding client */
+function getEmbeddingClient() {
+    if (!_embeddingClient) {
+        const s = (0, settings_js_1.getSettings)();
+        if (s.llmProvider === "openrouter" && s.openrouterApiKey) {
+            _embeddingClient = new openai_1.default({
+                apiKey: s.openrouterApiKey,
+                baseURL: "https://openrouter.ai/api/v1",
+                defaultHeaders: {
+                    "HTTP-Referer": "https://github.com/contextmemory",
+                    "X-Title": "ContextMemory",
+                },
+            });
+        }
+        else if (s.openaiApiKey) {
+            _embeddingClient = new openai_1.default({ apiKey: s.openaiApiKey });
+        }
+        else {
+            throw new Error("API key required for embeddings. Set OPENAI_API_KEY or OPENROUTER_API_KEY.");
+        }
+    }
+    return _embeddingClient;
+}
+/** Reset clients (useful for testing or after reconfigure) */
+function resetClients() {
+    _llmClient = null;
+    _embeddingClient = null;
+}
+//# sourceMappingURL=llmClient.js.map

package/dist/core/llmClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmClient.js","sourceRoot":"","sources":["../../src/core/llmClient.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;AASH,oCAmBC;AAGD,gDAsBC;AAGD,oCAGC;AAzDD,oDAA4B;AAC5B,+CAA4C;AAE5C,IAAI,UAAU,GAAkB,IAAI,CAAC;AACrC,IAAI,gBAAgB,GAAkB,IAAI,CAAC;AAE3C,4CAA4C;AAC5C,SAAgB,YAAY;IAC1B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,CAAC,GAAG,IAAA,yBAAW,GAAE,CAAC;QACxB,CAAC,CAAC,QAAQ,EAAE,CAAC;QAEb,IAAI,CAAC,CAAC,WAAW,KAAK,YAAY,EAAE,CAAC;YACnC,UAAU,GAAG,IAAI,gBAAM,CAAC;gBACtB,MAAM,EAAE,CAAC,CAAC,gBAAiB;gBAC3B,OAAO,EAAE,8BAA8B;gBACvC,cAAc,EAAE;oBACd,cAAc,EAAE,kCAAkC;oBAClD,SAAS,EAAE,eAAe;iBAC3B;aACF,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,UAAU,GAAG,IAAI,gBAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,YAAa,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,kDAAkD;AAClD,SAAgB,kBAAkB;IAChC,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,MAAM,CAAC,GAAG,IAAA,yBAAW,GAAE,CAAC;QAExB,IAAI,CAAC,CAAC,WAAW,KAAK,YAAY,IAAI,CAAC,CAAC,gBAAgB,EAAE,CAAC;YACzD,gBAAgB,GAAG,IAAI,gBAAM,CAAC;gBAC5B,MAAM,EAAE,CAAC,CAAC,gBAAgB;gBAC1B,OAAO,EAAE,8BAA8B;gBACvC,cAAc,EAAE;oBACd,cAAc,EAAE,kCAAkC;oBAClD,SAAS,EAAE,eAAe;iBAC3B;aACF,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,CAAC,CAAC,YAAY,EAAE,CAAC;YAC1B,gBAAgB,GAAG,IAAI,gBAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;QAC5D,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CACb,4EAA4E,CAC7E,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED,8DAA8D;AAC9D,SAAgB,YAAY;IAC1B,UAAU,GAAG,IAAI,CAAC;IAClB,gBAAgB,GAAG,IAAI,CAAC;AAC1B,CAAC"}

package/dist/core/retry.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Retry utility with exponential backoff.
+ *
+ * Wraps any async function and retries on transient errors (rate limits, 5xx).
+ * Default: 3 attempts, 500ms initial delay, 2x backoff, jitter.
+ */
+export interface RetryOptions {
+    attempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    factor?: number;
+    jitter?: boolean;
+}
+/**
+ * Retry `fn` up to `attempts` times with exponential backoff.
+ *
+ * @example
+ *   const result = await withRetry(() => openai.chat.completions.create(...));
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/core/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/core/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AA2BD;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,CAAC,CAAC,CA+BZ"}

package/dist/core/retry.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * Retry utility with exponential backoff.
+ *
+ * Wraps any async function and retries on transient errors (rate limits, 5xx).
+ * Default: 3 attempts, 500ms initial delay, 2x backoff, jitter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+/** Error codes that should NOT be retried (bad request, auth failure, etc.) */
+const FATAL_CODES = new Set([400, 401, 403, 404, 422]);
+function isRetryable(err) {
+    if (err instanceof Error) {
+        const msg = err.message.toLowerCase();
+        // Rate limit or server error
+        if (msg.includes("rate limit") || msg.includes("429"))
+            return true;
+        if (msg.includes("5") && msg.includes("0"))
+            return true; // 500, 503 etc.
+        if (msg.includes("timeout") || msg.includes("econnreset"))
+            return true;
+    }
+    // Check status codes on OpenAI-style errors
+    const e = err;
+    const code = e.status ?? e.statusCode;
+    if (code != null) {
+        if (FATAL_CODES.has(code))
+            return false;
+        if (code === 429 || code >= 500)
+            return true;
+    }
+    return false;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Retry `fn` up to `attempts` times with exponential backoff.
+ *
+ * @example
+ *   const result = await withRetry(() => openai.chat.completions.create(...));
+ */
+async function withRetry(fn, opts = {}) {
+    const attempts = opts.attempts ?? 3;
+    const initialDelay = opts.initialDelayMs ?? 500;
+    const maxDelay = opts.maxDelayMs ?? 10_000;
+    const factor = opts.factor ?? 2;
+    const jitter = opts.jitter ?? true;
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt === attempts || !isRetryable(err)) {
+                throw err;
+            }
+            let delay = Math.min(initialDelay * Math.pow(factor, attempt - 1), maxDelay);
+            if (jitter)
+                delay *= 0.8 + Math.random() * 0.4; // ±20% jitter
+            console.warn(`[ContextMemory] API error (attempt ${attempt}/${attempts}), retrying in ${Math.round(delay)}ms...`, err instanceof Error ? err.message : err);
+            await sleep(delay);
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=retry.js.map

package/dist/core/retry.js.map

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

package/dist/core/settings.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ContextMemory Settings — TypeScript port of Python settings.py
+ *
+ * Supports two config methods:
+ *  1. Programmatic: configure({ openaiApiKey: "..." })
+ *  2. Environment variables: OPENAI_API_KEY, OPENROUTER_API_KEY, DATABASE_URL, ...
+ */
+export type LLMProvider = "openai" | "openrouter";
+export interface ContextMemoryConfig {
+    openaiApiKey?: string;
+    openrouterApiKey?: string;
+    databaseUrl?: string;
+    llmProvider?: LLMProvider;
+    llmModel?: string;
+    embeddingModel?: string;
+    debug?: boolean;
+}
+export declare class ContextMemorySettings {
+    openaiApiKey?: string;
+    openrouterApiKey?: string;
+    databaseUrl?: string;
+    llmProvider: LLMProvider;
+    llmModel: string;
+    embeddingModel: string;
+    debug: boolean;
+    constructor(cfg?: ContextMemoryConfig);
+    /** Return DB path — defaults to ~/.contextmemory/memory.db (SQLite) */
+    getDatabaseUrl(): string;
+    /** Get the correct API key for the active provider */
+    getApiKey(): string;
+    /** Base URL for the LLM provider */
+    getBaseUrl(): string | undefined;
+    validate(): void;
+}
+/**
+ * Configure ContextMemory programmatically.
+ * Call this once at app startup before using any Memory instances.
+ */
+export declare function configure(cfg: ContextMemoryConfig): void;
+/**
+ * Get current settings. Auto-loads from env vars if configure() not called.
+ */
+export declare function getSettings(): ContextMemorySettings;
+/** Reset settings (useful for testing) */
+export declare function resetSettings(): void;
+//# sourceMappingURL=settings.d.ts.map

package/dist/core/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/core/settings.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;AAElD,MAAM,WAAW,mBAAmB;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,qBAAqB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC;gBAEH,GAAG,GAAE,mBAAwB;IAUzC,uEAAuE;IACvE,cAAc,IAAI,MAAM;IAOxB,sDAAsD;IACtD,SAAS,IAAI,MAAM;IAenB,oCAAoC;IACpC,UAAU,IAAI,MAAM,GAAG,SAAS;IAMhC,QAAQ,IAAI,IAAI;CAGjB;AAsBD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,CAExD;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,qBAAqB,CAGnD;AAED,0CAA0C;AAC1C,wBAAgB,aAAa,IAAI,IAAI,CAEpC"}

package/dist/core/settings.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * ContextMemory Settings — TypeScript port of Python settings.py
+ *
+ * Supports two config methods:
+ *  1. Programmatic: configure({ openaiApiKey: "..." })
+ *  2. Environment variables: OPENAI_API_KEY, OPENROUTER_API_KEY, DATABASE_URL, ...
+ */
+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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextMemorySettings = void 0;
+exports.configure = configure;
+exports.getSettings = getSettings;
+exports.resetSettings = resetSettings;
+const dotenv = __importStar(require("dotenv"));
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+dotenv.config();
+class ContextMemorySettings {
+    openaiApiKey;
+    openrouterApiKey;
+    databaseUrl;
+    llmProvider;
+    llmModel;
+    embeddingModel;
+    debug;
+    constructor(cfg = {}) {
+        this.openaiApiKey = cfg.openaiApiKey;
+        this.openrouterApiKey = cfg.openrouterApiKey;
+        this.databaseUrl = cfg.databaseUrl;
+        this.llmProvider = cfg.llmProvider ?? "openai";
+        this.llmModel = cfg.llmModel ?? "gpt-4o-mini";
+        this.embeddingModel = cfg.embeddingModel ?? "text-embedding-3-small";
+        this.debug = cfg.debug ?? false;
+    }
+    /** Return DB path — defaults to ~/.contextmemory/memory.db (SQLite) */
+    getDatabaseUrl() {
+        if (this.databaseUrl)
+            return this.databaseUrl;
+        const dir = path.join(os.homedir(), ".contextmemory");
+        fs.mkdirSync(dir, { recursive: true });
+        return path.join(dir, "memory.db");
+    }
+    /** Get the correct API key for the active provider */
+    getApiKey() {
+        if (this.llmProvider === "openrouter") {
+            if (!this.openrouterApiKey)
+                throw new Error("OpenRouter API key is required. Call configure({ openrouterApiKey: '...' }) or set OPENROUTER_API_KEY.");
+            return this.openrouterApiKey;
+        }
+        if (!this.openaiApiKey)
+            throw new Error("OpenAI API key is required. Call configure({ openaiApiKey: '...' }) or set OPENAI_API_KEY.");
+        return this.openaiApiKey;
+    }
+    /** Base URL for the LLM provider */
+    getBaseUrl() {
+        return this.llmProvider === "openrouter"
+            ? "https://openrouter.ai/api/v1"
+            : undefined;
+    }
+    validate() {
+        this.getApiKey(); // throws if missing
+    }
+}
+exports.ContextMemorySettings = ContextMemorySettings;
+// ─── Global singleton ──────────────────────────────────────────────────────
+let _settings = null;
+/** Load settings from environment variables */
+function fromEnv() {
+    const provider = process.env.LLM_PROVIDER === "openrouter" ? "openrouter" : "openai";
+    return new ContextMemorySettings({
+        openaiApiKey: process.env.OPENAI_API_KEY,
+        openrouterApiKey: process.env.OPENROUTER_API_KEY,
+        databaseUrl: process.env.DATABASE_URL,
+        llmProvider: provider,
+        llmModel: process.env.LLM_MODEL ?? "gpt-4o-mini",
+        embeddingModel: process.env.EMBEDDING_MODEL ?? "text-embedding-3-small",
+        debug: ["true", "1", "yes"].includes((process.env.DEBUG ?? "").toLowerCase()),
+    });
+}
+/**
+ * Configure ContextMemory programmatically.
+ * Call this once at app startup before using any Memory instances.
+ */
+function configure(cfg) {
+    _settings = new ContextMemorySettings(cfg);
+}
+/**
+ * Get current settings. Auto-loads from env vars if configure() not called.
+ */
+function getSettings() {
+    if (!_settings)
+        _settings = fromEnv();
+    return _settings;
+}
+/** Reset settings (useful for testing) */
+function resetSettings() {
+    _settings = null;
+}
+//# sourceMappingURL=settings.js.map

package/dist/core/settings.js.map

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

package/dist/db/database.d.ts

@@ -0,0 +1,50 @@
+/**
+ * SQLite Database — TypeScript port using better-sqlite3 + Drizzle ORM schema.
+ *
+ * Tables:
+ *   conversations         — one row per conversation
+ *   messages              — chat turns (user / assistant)
+ *   conversation_summary  — rolling LLM-generated summary
+ *   memories              — semantic & episodic memory facts
+ */
+import Database from "better-sqlite3";
+export declare function getDb(): Database.Database;
+/** Close and reset the DB connection (useful for testing) */
+export declare function resetDb(): void;
+export declare function createTables(): void;
+export interface ConversationRow {
+    id: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface MessageRow {
+    id: number;
+    conversation_id: number;
+    sender: "user" | "assistant";
+    message_text: string;
+    timestamp: string;
+}
+export interface SummaryRow {
+    id: number;
+    conversation_id: number;
+    summary_text: string | null;
+    updated_at: string;
+}
+export interface MemoryRow {
+    id: number;
+    conversation_id: number;
+    memory_text: string;
+    category: string | null;
+    embedding: string | null;
+    memory_metadata: string | null;
+    is_episodic: number;
+    occurred_at: string | null;
+    session_id: number | null;
+    importance: number;
+    is_active: number;
+    created_at: string;
+    updated_at: string;
+}
+export declare function parseEmbedding(row: MemoryRow): number[] | null;
+export declare function parseMeta(row: MemoryRow): Record<string, unknown>;
+//# sourceMappingURL=database.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAStC,wBAAgB,KAAK,IAAI,QAAQ,CAAC,QAAQ,CAYzC;AAED,6DAA6D;AAC7D,wBAAgB,OAAO,IAAI,IAAI,CAK9B;AAGD,wBAAgB,YAAY,IAAI,IAAI,CAuDnC;AAGD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAGD,wBAAgB,cAAc,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,EAAE,GAAG,IAAI,CAG9D;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGjE"}