feat: lazily initialize engines from saved settings (#10)

Reuse persisted provider/model settings by creating missing local, remote, or custom engines on first embedding use instead of requiring memory_set_model on every connection.

Keep memory_set_model eager so callers can preload and validate engines explicitly, while memory_set_apikey remains connection-scoped and lazy for saved remote models.

Update API/README documentation and add regression coverage for saved local, remote, and custom provider settings.

Verification: build/unittest with TEST_SQLITE_EXTENSION passed 157 tests.

Author: andinux

API.md

@@ -136,8 +136,9 @@ Configures the embedding model to use.
 - When `provider` is `"local"`, the extension uses the built-in llama.cpp engine and verifies the model file exists
 - When `provider` is anything other than `"local"`, the extension uses the [vectors.space](https://vectors.space) remote embedding service
 - Remote embedding requires a free API key from [vectors.space](https://vectors.space) (set via `memory_set_apikey`)
-- Settings are persisted in `dbmem_settings` table
-- For local models, the embedding engine is initialized immediately
+- Provider/model settings are persisted in the `dbmem_settings` table and reused by new connections
+- Calling `memory_set_model()` initializes the embedding engine immediately, which can be used to preload and validate the engine
+- When provider/model settings are loaded by a new connection, the engine is initialized lazily on first embedding use
 - **Automatic reindex**: If a model was previously configured and the new provider/model differs, all existing content is automatically re-embedded with the new model. File-based entries are re-read from disk; text-based entries are re-embedded from stored content. Errors on individual entries are silently skipped (best-effort)
 
 **Example:**
@@ -164,7 +165,7 @@ Sets the API key for the [vectors.space](https://vectors.space) remote embedding
 **Returns:** INTEGER - 1 on success
 
 **Notes:**
-- API key is stored in memory only, not persisted to disk
+- API key is stored in memory only, not persisted to disk, and must be set per connection for remote embeddings
 - Required when using any provider other than `"local"`
 - Get a free API key by creating an account at [vectors.space](https://vectors.space)
 
@@ -623,7 +624,7 @@ Generates or refreshes local embeddings for stored content.
 **Returns:** INTEGER - Number of content rows reindexed or realigned
 
 **Notes:**
-- Requires an embedding model configured with `memory_set_model()`
+- Requires an embedding model configured with `memory_set_model()` or loaded from persisted provider/model settings
 - Processes rows in `dbmem_content` that have stored `value`
 - Skips rows whose `dbmem_content.hash` already matches `value` and whose local `dbmem_vault` entries already exist
 - After sync merges remote changes into `dbmem_content.value`, recomputes stale hashes, refreshes missing embeddings, and removes old local index rows
@@ -714,7 +715,7 @@ int sqlite3_memory_register_provider(
 );
 ```
 
-Registers a custom embedding engine for a specific database connection. Once registered, calling `memory_set_model(provider_name, model)` from SQL will use your engine instead of the built-in local or remote engines.
+Registers a custom embedding engine for a specific database connection. Once registered, calling `memory_set_model(provider_name, model)` from SQL will use your engine instead of the built-in local or remote engines. If provider/model settings were already loaded from `dbmem_settings`, the custom engine is initialized lazily on first embedding use after registration.
 
 **Parameters:**
 | Parameter | Type | Description |
@@ -728,7 +729,8 @@ Registers a custom embedding engine for a specific database connection. Once reg
 **`dbmem_provider_t` struct:**
 ```c
 typedef struct {
-    // Called when memory_set_model(provider_name, model) is executed.
+    // Called when memory_set_model(provider_name, model) is executed, or lazily
+    // on first embedding use when provider/model were loaded from settings.
     // api_key is the value set via memory_set_apikey() (may be NULL).
     // xdata is the user pointer from this struct.
     // Return an opaque engine pointer on success, or NULL on error (fill err_msg).

README.md

@@ -128,6 +128,10 @@ SELECT memory_set_model('local', '/path/to/nomic-embed-text-v1.5.Q8_0.gguf');
 -- SELECT memory_set_apikey('your-vectorspace-api-key');
 -- SELECT memory_set_model('openai', 'text-embedding-3-small');
 
+-- Provider/model settings are persisted. New connections reuse them and
+-- initialize the engine lazily on first embedding use. Remote API keys are
+-- connection-scoped, so call memory_set_apikey() on each remote connection.
+
 -- Add some knowledge
 SELECT memory_add_text('SQLite is a C-language library that implements a small, fast,
 self-contained, high-reliability, full-featured, SQL database engine. SQLite is the
@@ -182,7 +186,8 @@ conn.enable_load_extension(True)
 conn.load_extension('./vector')
 conn.load_extension('./memory')
 
-# One-time setup
+# One-time setup. Later connections reuse the saved provider/model and lazily
+# load the engine on first embedding use.
 conn.execute("SELECT memory_set_model('local', './models/nomic-embed-text-v1.5.Q8_0.gguf')")
 
 # Store conversation context

src/dbmem-search.c

@@ -656,6 +656,12 @@ static int vMemorySearchCursorFilter (sqlite3_vtab_cursor *cur, int idxNum, cons
     if (rc != SQLITE_OK) return SQLITE_NOMEM;
 
     // perform semantic search
+    rc = dbmem_context_ensure_engine(ctx);
+    if (rc != SQLITE_OK) {
+        sqlvTab->zErrMsg = sqlite3_mprintf("%s", dbmem_context_errmsg(ctx));
+        return SQLITE_ERROR;
+    }
+
     // retrieve engine
     bool is_local;
     void *engine = dbmem_context_engine(ctx, &is_local);

src/sqlite-memory.c

@@ -1067,6 +1067,56 @@ void *dbmem_context_engine (dbmem_context *ctx, bool *is_local) {
     return (ctx->is_local) ? (void *)ctx->l_engine : (void *)ctx->r_engine;
 }
 
+int dbmem_context_ensure_engine (dbmem_context *ctx) {
+    if (!ctx || !ctx->provider || !ctx->model) {
+        if (ctx) dbmem_context_set_error(ctx, "memory_set_model must be called before adding content");
+        return SQLITE_ERROR;
+    }
+
+    bool is_local_provider = (strcasecmp(ctx->provider, DBMEM_LOCAL_PROVIDER) == 0);
+    bool is_custom_provider = (ctx->custom_provider_name && ctx->custom_provider.compute &&
+                               strcasecmp(ctx->provider, ctx->custom_provider_name) == 0);
+
+    ctx->is_local = is_custom_provider ? false : is_local_provider;
+    ctx->is_custom = is_custom_provider;
+
+    if (is_custom_provider) {
+        if (ctx->custom_engine) return SQLITE_OK;
+        ctx->custom_engine = ctx->custom_provider.init(ctx->model, ctx->api_key, ctx->custom_provider.xdata, ctx->error_msg);
+        return ctx->custom_engine ? SQLITE_OK : SQLITE_ERROR;
+    }
+
+    #ifndef DBMEM_OMIT_LOCAL_ENGINE
+    if (is_local_provider) {
+        if (ctx->l_engine) return SQLITE_OK;
+        if (dbmem_file_exists(ctx->model) == false) {
+            dbmem_context_set_error(ctx, "Local model not found in the specified path");
+            return SQLITE_ERROR;
+        }
+
+        int max_context_tokens = (int)(ctx->max_tokens + ctx->overlay_tokens);
+        ctx->l_engine = dbmem_local_engine_init(ctx, ctx->model, max_context_tokens, ctx->error_msg);
+        if (!ctx->l_engine) return SQLITE_ERROR;
+        if (ctx->engine_warmup) dbmem_local_engine_warmup(ctx->l_engine);
+        return SQLITE_OK;
+    }
+    #else
+    if (is_local_provider) {
+        dbmem_context_set_error(ctx, "Local provider cannot be set because SQLite-memory was compiled without local provider support");
+        return SQLITE_ERROR;
+    }
+    #endif
+
+    #ifndef DBMEM_OMIT_REMOTE_ENGINE
+    if (ctx->r_engine) return SQLITE_OK;
+    ctx->r_engine = dbmem_remote_engine_init(ctx, ctx->provider, ctx->model, ctx->error_msg);
+    return ctx->r_engine ? SQLITE_OK : SQLITE_ERROR;
+    #else
+    dbmem_context_set_error(ctx, "Remote provider cannot be set because SQLite-memory was compiled without remote provider support");
+    return SQLITE_ERROR;
+    #endif
+}
+
 bool dbmem_context_is_custom (dbmem_context *ctx) {
     return ctx->is_custom;
 }
@@ -2565,6 +2615,8 @@ static int dbmem_process_callback (const char *text, size_t len, size_t offset,
             dbmem_context_set_error(ctx, "memory_set_model must be called before adding content");
             return SQLITE_ERROR;
         }
+        rc = dbmem_context_ensure_engine(ctx);
+        if (rc != SQLITE_OK) return rc;
 
         // compute embedding
         if (ctx->is_custom) {

src/sqlite-memory.h

@@ -45,7 +45,8 @@ typedef struct {
 } dbmem_embedding_result_t;
 
 typedef struct {
-    // Called when memory_set_model(provider, model) matches this provider.
+    // Called when memory_set_model(provider, model) matches this provider, or
+    // lazily on first embedding use when provider/model were loaded from settings.
     // api_key is the value set via memory_set_apikey() (may be NULL).
     // xdata is the user-supplied generic pointer from the struct.
     // Return opaque engine pointer, or NULL on error (fill err_msg).
@@ -67,6 +68,7 @@ typedef struct {
 SQLITE_DBMEMORY_API int sqlite3_memory_register_provider (sqlite3 *db, const char *provider_name, const dbmem_provider_t *provider);
 
 void  *dbmem_context_engine (dbmem_context *ctx, bool *is_local);
+int     dbmem_context_ensure_engine (dbmem_context *ctx);
 bool   dbmem_context_is_custom (dbmem_context *ctx);
 bool   dbmem_context_load_vector (dbmem_context *ctx);
 bool   dbmem_context_sync_available (dbmem_context *ctx);

test/unittest.c

@@ -1490,6 +1490,19 @@ static sqlite3 *open_test_db(void) {
     return db;
 }
 
+static sqlite3 *open_test_db_path(const char *path) {
+    sqlite3 *db = NULL;
+    int rc = sqlite3_open(path, &db);
+    if (rc != SQLITE_OK) return NULL;
+
+    rc = sqlite3_memory_init(db, NULL, NULL);
+    if (rc != SQLITE_OK) {
+        sqlite3_close(db);
+        return NULL;
+    }
+    return db;
+}
+
 // Helper to execute SQL and get integer result
 static int exec_get_int(sqlite3 *db, const char *sql, sqlite3_int64 *result) {
     sqlite3_stmt *stmt = NULL;
@@ -3275,10 +3288,12 @@ typedef struct {
 } dummy_engine_t;
 
 static int dummy_compute_calls = 0;
+static int dummy_init_calls = 0;
 
 static void *dummy_init(const char *model, const char *api_key, void *xdata, char err_msg[1024]) {
     UNUSED_PARAM(model);
     UNUSED_PARAM(xdata);
+    dummy_init_calls++;
     dummy_engine_t *e = (dummy_engine_t *)calloc(1, sizeof(dummy_engine_t));
     if (!e) { snprintf(err_msg, 1024, "alloc failed"); return NULL; }
     e->dimension = 4;
@@ -4069,6 +4084,128 @@ TEST(sqlite_memory_add_text_requires_model) {
     sqlite3_close(db);
 }
 
+#ifndef DBMEM_OMIT_REMOTE_ENGINE
+TEST(sqlite_saved_remote_model_initializes_lazily_after_apikey) {
+    const char *path = TEST_TMP_DIR "/dbmem_saved_remote_model.sqlite";
+    remove_test_file(path);
+
+    sqlite3 *db = open_test_db_path(path);
+    ASSERT(db != NULL);
+
+    int rc = sqlite3_exec(db,
+        "INSERT OR REPLACE INTO dbmem_settings (key, value) VALUES ('provider', 'openai');"
+        "INSERT OR REPLACE INTO dbmem_settings (key, value) VALUES ('model', 'text-embedding-3-small');",
+        NULL, NULL, NULL);
+    ASSERT_EQ(rc, SQLITE_OK);
+    sqlite3_close(db);
+
+    db = open_test_db_path(path);
+    ASSERT(db != NULL);
+
+    dbmem_context *ctx = get_test_ctx(db);
+    ASSERT(ctx != NULL);
+    rc = dbmem_context_ensure_engine(ctx);
+    ASSERT_EQ(rc, SQLITE_ERROR);
+    ASSERT(strstr(dbmem_context_errmsg(ctx), "memory_set_apikey must be called") != NULL);
+
+    sqlite3_int64 result = 0;
+    rc = exec_get_int(db, "SELECT memory_set_apikey('test-key');", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+
+    rc = dbmem_context_ensure_engine(ctx);
+    ASSERT_EQ(rc, SQLITE_OK);
+
+    bool is_local = true;
+    ASSERT(dbmem_context_engine(ctx, &is_local) != NULL);
+    ASSERT_EQ(is_local, false);
+
+    sqlite3_close(db);
+    remove_test_file(path);
+}
+#endif
+
+#ifndef DBMEM_OMIT_LOCAL_ENGINE
+TEST(sqlite_saved_local_model_initializes_lazily) {
+    const char *path = TEST_TMP_DIR "/dbmem_saved_local_model.sqlite";
+    const char *model_path = "models/embeddinggemma-300M-Q8_0.gguf";
+    remove_test_file(path);
+
+    if (access(model_path, F_OK) != 0) return;
+
+    sqlite3 *db = open_test_db_path(path);
+    ASSERT(db != NULL);
+
+    sqlite3_int64 result = 0;
+    int rc = exec_get_int(db, "SELECT memory_set_model('local', 'models/embeddinggemma-300M-Q8_0.gguf');", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+    sqlite3_close(db);
+
+    db = open_test_db_path(path);
+    ASSERT(db != NULL);
+
+    dbmem_context *ctx = get_test_ctx(db);
+    ASSERT(ctx != NULL);
+
+    bool is_local = false;
+    ASSERT(dbmem_context_engine(ctx, &is_local) == NULL);
+
+    rc = exec_get_int(db, "SELECT memory_add_text('Saved local model settings should load lazily.');", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT(result >= 1);
+
+    ASSERT(dbmem_context_engine(ctx, &is_local) != NULL);
+    ASSERT_EQ(is_local, true);
+
+    sqlite3_close(db);
+    remove_test_file(path);
+}
+#endif
+
+TEST(sqlite_saved_custom_model_initializes_lazily_after_register) {
+    const char *path = TEST_TMP_DIR "/dbmem_saved_custom_model.sqlite";
+    remove_test_file(path);
+
+    sqlite3 *db = open_test_db_path(path);
+    ASSERT(db != NULL);
+
+    dbmem_provider_t prov = { .init = dummy_init, .compute = dummy_compute, .free = dummy_free };
+    int rc = sqlite3_memory_register_provider(db, "dummy", &prov);
+    ASSERT_EQ(rc, SQLITE_OK);
+
+    sqlite3_int64 result = 0;
+    rc = exec_get_int(db, "SELECT memory_set_model('dummy', 'test-model');", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+    sqlite3_close(db);
+
+    dummy_init_calls = 0;
+    dummy_compute_calls = 0;
+
+    db = open_test_db_path(path);
+    ASSERT(db != NULL);
+
+    dbmem_context *ctx = get_test_ctx(db);
+    ASSERT(ctx != NULL);
+    bool is_local = true;
+    ASSERT(dbmem_context_engine(ctx, &is_local) == NULL);
+    ASSERT_EQ(dummy_init_calls, 0);
+
+    rc = sqlite3_memory_register_provider(db, "dummy", &prov);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT_EQ(dummy_init_calls, 0);
+
+    rc = exec_get_int(db, "SELECT memory_add_text('Saved custom provider settings should load lazily.');", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT(result >= 1);
+    ASSERT_EQ(dummy_init_calls, 1);
+    ASSERT(dummy_compute_calls >= 1);
+
+    ASSERT(dbmem_context_engine(ctx, &is_local) != NULL);
+    ASSERT_EQ(is_local, false);
+
+    sqlite3_close(db);
+    remove_test_file(path);
+}
+
 TEST(sqlite_custom_provider_add_text) {
     sqlite3 *db = open_test_db();
     ASSERT(db != NULL);
@@ -4662,6 +4799,13 @@ int main(int argc, char *argv[]) {
     RUN_TEST(sqlite_custom_provider_register);
     RUN_TEST(sqlite_custom_provider_set_model);
     RUN_TEST(sqlite_memory_add_text_requires_model);
+#ifndef DBMEM_OMIT_REMOTE_ENGINE
+    RUN_TEST(sqlite_saved_remote_model_initializes_lazily_after_apikey);
+#endif
+#ifndef DBMEM_OMIT_LOCAL_ENGINE
+    RUN_TEST(sqlite_saved_local_model_initializes_lazily);
+#endif
+    RUN_TEST(sqlite_saved_custom_model_initializes_lazily_after_register);
     RUN_TEST(sqlite_custom_provider_add_text);
     RUN_TEST(sqlite_memory_reindex_refreshes_synced_value_changes);
     RUN_TEST(sqlite_custom_provider_skips_whitespace_only_text);