Added cache eviction and oversampling

Author: marcobambini

API.md

@@ -465,6 +465,8 @@ AND context = 'meetings';
 | `min_score` | REAL | 0.7 | Minimum score threshold for results |
 | `update_access` | INTEGER | 1 | Update last_accessed on search |
 | `embedding_cache` | INTEGER | 1 | Cache embeddings to avoid redundant computation |
+| `cache_max_entries` | INTEGER | 0 | Max cache entries (0 = no limit). When exceeded, oldest entries are evicted |
+| `search_oversample` | INTEGER | 0 | Search oversampling multiplier (0 = no oversampling). When set, retrieves N * multiplier candidates from each index before merging down to N final results |
 
 ---
 

README.md

@@ -182,12 +182,14 @@ SELECT memory_set_option('max_results', 30);      -- Max search results
 SELECT memory_set_option('min_score', 0.75);      -- Score threshold
 SELECT memory_set_option('vector_weight', 0.6);   -- Vector vs FTS balance
 SELECT memory_set_option('text_weight', 0.4);
+SELECT memory_set_option('search_oversample', 4); -- Fetch 4x candidates before merging
 
 -- File processing
 SELECT memory_set_option('extensions', 'md,txt,rst');  -- File types to index
 
 -- Embedding cache (enabled by default)
 SELECT memory_set_option('embedding_cache', 0);        -- Disable cache
+SELECT memory_set_option('cache_max_entries', 10000);  -- Limit cache size (0 = no limit)
 SELECT memory_cache_clear();                           -- Clear cached embeddings
 ```
 

src/dbmem-search.c

@@ -584,10 +584,14 @@ static int vMemorySearchCursorFilter (sqlite3_vtab_cursor *cur, int idxNum, cons
         }
     }
 
+    // compute fetch count (oversampling)
+    int oversample = dbmem_context_search_oversample(ctx);
+    int fetch_count = (oversample > 0) ? max_results * oversample : max_results;
+
     // allocate internal cursor buffer
-    int rc = vMemorySearchCursorAllocate(c, max_results, perform_fts);
+    int rc = vMemorySearchCursorAllocate(c, fetch_count, perform_fts);
     if (rc != SQLITE_OK) return SQLITE_NOMEM;
-    
+
     // perform semantic search
     // retrieve engine
     bool is_local;
@@ -627,16 +631,16 @@ static int vMemorySearchCursorFilter (sqlite3_vtab_cursor *cur, int idxNum, cons
     }
 
     // perform search
-    rc = dbmem_semantic_search(db, c, result.embedding, (int)(result.n_embd * sizeof(float)), context, max_results);
+    rc = dbmem_semantic_search(db, c, result.embedding, (int)(result.n_embd * sizeof(float)), context, fetch_count);
     if (rc != 0) {
         sqlvTab->zErrMsg = sqlite3_mprintf("%s", sqlite3_errmsg(db));
         return SQLITE_ERROR;
     }
-    
+
     // perform fts search
     if (perform_fts) {
         // in case of FTS error ignore its contribution
-        rc = dbmem_fts_search(db, c, query, context, max_results);
+        rc = dbmem_fts_search(db, c, query, context, fetch_count);
         if (rc != SQLITE_OK) perform_fts = false;
     }
 

src/sqlite-memory.c

@@ -57,6 +57,8 @@ SQLITE_EXTENSION_INIT1
 #define DBMEM_SETTINGS_KEY_MIN_SCORE            "min_score"
 #define DBMEM_SETTINGS_KEY_UPDATE_ACCESS        "update_access"
 #define DBMEM_SETTINGS_KEY_EMBEDDING_CACHE     "embedding_cache"
+#define DBMEM_SETTINGS_KEY_CACHE_MAX_ENTRIES   "cache_max_entries"
+#define DBMEM_SETTINGS_KEY_SEARCH_OVERSAMPLE  "search_oversample"
 
 // default values from https://docs.openclaw.ai/concepts/memory
 #define DEFAULT_CHARS_PER_TOKEN                 4       // Approximate number of characters per token (GPT ≈ 4, Claude ≈ 3.5)
@@ -106,6 +108,8 @@ struct dbmem_context {
     double      min_score;                      // Minimum score threshold to filter irrelevant results
     bool        update_access;                  // Whether to update last_accessed on search
     bool        embedding_cache;                // Enable/disable embedding cache (default: true)
+    int         cache_max_entries;              // Max cache entries (0 = no limit)
+    int         search_oversample;             // Search oversampling multiplier (0 = no oversampling)
 
     // Cache
     float       *cache_buffer;                  // Reusable buffer for cache hits
@@ -254,6 +258,18 @@ static int dbmem_settings_sync (dbmem_context *ctx, const char *key, sqlite3_val
         return 0;
     }
 
+    if (strcasecmp(key, DBMEM_SETTINGS_KEY_CACHE_MAX_ENTRIES) == 0) {
+        int n = sqlite3_value_int(value);
+        if (n >= 0) ctx->cache_max_entries = n;
+        return 0;
+    }
+
+    if (strcasecmp(key, DBMEM_SETTINGS_KEY_SEARCH_OVERSAMPLE) == 0) {
+        int n = sqlite3_value_int(value);
+        if (n >= 0) ctx->search_oversample = n;
+        return 0;
+    }
+
     if (strcasecmp(key, DBMEM_SETTINGS_KEY_PROVIDER) == 0) {
         char *provider = dbmem_strdup((const char *)sqlite3_value_text(value));
         if (provider) {
@@ -644,6 +660,10 @@ bool dbmem_context_update_access (dbmem_context *ctx) {
     return ctx->update_access;
 }
 
+int dbmem_context_search_oversample (dbmem_context *ctx) {
+    return ctx->search_oversample;
+}
+
 const char *dbmem_context_errmsg (dbmem_context *ctx) {
     return ctx->error_msg;
 }
@@ -1071,6 +1091,33 @@ static bool dbmem_cache_lookup (dbmem_context *ctx, uint64_t text_hash, embeddin
     return found;
 }
 
+static void dbmem_cache_evict (dbmem_context *ctx) {
+    static const char *sql = "DELETE FROM dbmem_cache WHERE rowid IN (SELECT rowid FROM dbmem_cache ORDER BY rowid ASC LIMIT ?1);";
+
+    sqlite3_stmt *vm = NULL;
+    int rc = sqlite3_prepare_v2(ctx->db, sql, -1, &vm, NULL);
+    if (rc != SQLITE_OK) goto cleanup;
+
+    // count current entries
+    sqlite3_stmt *count_vm = NULL;
+    rc = sqlite3_prepare_v2(ctx->db, "SELECT COUNT(*) FROM dbmem_cache;", -1, &count_vm, NULL);
+    if (rc != SQLITE_OK) goto cleanup;
+
+    rc = sqlite3_step(count_vm);
+    if (rc != SQLITE_ROW) { sqlite3_finalize(count_vm); goto cleanup; }
+    int count = sqlite3_column_int(count_vm, 0);
+    sqlite3_finalize(count_vm);
+
+    int excess = count - ctx->cache_max_entries;
+    if (excess <= 0) goto cleanup;
+
+    sqlite3_bind_int(vm, 1, excess);
+    sqlite3_step(vm);
+
+cleanup:
+    if (vm) sqlite3_finalize(vm);
+}
+
 static void dbmem_cache_store (dbmem_context *ctx, uint64_t text_hash, const embedding_result_t *result) {
     static const char *sql = "INSERT OR REPLACE INTO dbmem_cache (text_hash, provider, model, embedding, dimension) VALUES (?1, ?2, ?3, ?4, ?5);";
 
@@ -1090,6 +1137,11 @@ static void dbmem_cache_store (dbmem_context *ctx, uint64_t text_hash, const emb
 
 cleanup:
     if (vm) sqlite3_finalize(vm);
+
+    // evict oldest entries if limit is set and exceeded
+    if (ctx->cache_max_entries > 0) {
+        dbmem_cache_evict(ctx);
+    }
 }
 
 // MARK: -

src/sqlite-memory.h

@@ -43,6 +43,7 @@ double dbmem_context_vector_weight (dbmem_context *ctx);
 double dbmem_context_text_weight (dbmem_context *ctx);
 double dbmem_context_min_score (dbmem_context *ctx);
 bool   dbmem_context_update_access (dbmem_context *ctx);
+int    dbmem_context_search_oversample (dbmem_context *ctx);
 const char *dbmem_context_errmsg (dbmem_context *ctx);
 
 #ifdef __cplusplus

test/unittest.c

@@ -2049,6 +2049,128 @@ TEST(sqlite_cache_setting_default) {
     sqlite3_close(db);
 }
 
+TEST(sqlite_cache_max_entries_setting) {
+    sqlite3 *db = open_test_db();
+    ASSERT(db != NULL);
+
+    // Default is 0 (no limit)
+    sqlite3_int64 result;
+    int rc = exec_get_int(db, "SELECT memory_set_option('cache_max_entries', 100);", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT_EQ(result, 1);
+
+    rc = exec_get_int(db, "SELECT memory_get_option('cache_max_entries');", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT_EQ(result, 100);
+
+    // Set back to 0 (no limit)
+    rc = exec_get_int(db, "SELECT memory_set_option('cache_max_entries', 0);", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT_EQ(result, 1);
+
+    rc = exec_get_int(db, "SELECT memory_get_option('cache_max_entries');", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT_EQ(result, 0);
+
+    sqlite3_close(db);
+}
+
+TEST(sqlite_cache_eviction) {
+    sqlite3 *db = open_test_db();
+    ASSERT(db != NULL);
+
+    // Set max entries to 3
+    sqlite3_int64 result;
+    int rc = exec_get_int(db, "SELECT memory_set_option('cache_max_entries', 3);", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+
+    // Insert 5 entries (rowids 1-5)
+    rc = sqlite3_exec(db,
+        "INSERT INTO dbmem_cache (text_hash, provider, model, embedding, dimension) VALUES "
+        "(1, 'p', 'm', X'00000000', 1), "
+        "(2, 'p', 'm', X'00000000', 1), "
+        "(3, 'p', 'm', X'00000000', 1), "
+        "(4, 'p', 'm', X'00000000', 1), "
+        "(5, 'p', 'm', X'00000000', 1);",
+        NULL, NULL, NULL);
+    ASSERT_EQ(rc, SQLITE_OK);
+
+    // Verify 5 entries before any sync triggers eviction
+    sqlite3_int64 count;
+    rc = exec_get_int(db, "SELECT COUNT(*) FROM dbmem_cache;", &count);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT_EQ(count, 5);
+
+    // Now manually call memory_cache_clear to clear all, then re-insert within limit
+    rc = exec_get_int(db, "SELECT memory_cache_clear();", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+
+    // Insert exactly 3 (at limit)
+    rc = sqlite3_exec(db,
+        "INSERT INTO dbmem_cache (text_hash, provider, model, embedding, dimension) VALUES "
+        "(10, 'p', 'm', X'00000000', 1), "
+        "(11, 'p', 'm', X'00000000', 1), "
+        "(12, 'p', 'm', X'00000000', 1);",
+        NULL, NULL, NULL);
+    ASSERT_EQ(rc, SQLITE_OK);
+
+    rc = exec_get_int(db, "SELECT COUNT(*) FROM dbmem_cache;", &count);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT_EQ(count, 3);
+
+    sqlite3_close(db);
+}
+
+TEST(sqlite_cache_no_eviction_when_unlimited) {
+    sqlite3 *db = open_test_db();
+    ASSERT(db != NULL);
+
+    // Default cache_max_entries is 0 (no limit)
+    // Insert many entries, none should be evicted
+    int rc = sqlite3_exec(db,
+        "INSERT INTO dbmem_cache (text_hash, provider, model, embedding, dimension) VALUES "
+        "(1, 'p', 'm', X'00000000', 1), "
+        "(2, 'p', 'm', X'00000000', 1), "
+        "(3, 'p', 'm', X'00000000', 1), "
+        "(4, 'p', 'm', X'00000000', 1), "
+        "(5, 'p', 'm', X'00000000', 1);",
+        NULL, NULL, NULL);
+    ASSERT_EQ(rc, SQLITE_OK);
+
+    sqlite3_int64 count;
+    rc = exec_get_int(db, "SELECT COUNT(*) FROM dbmem_cache;", &count);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT_EQ(count, 5);
+
+    sqlite3_close(db);
+}
+
+TEST(sqlite_search_oversample_setting) {
+    sqlite3 *db = open_test_db();
+    ASSERT(db != NULL);
+
+    // Default is 0 (no oversampling)
+    sqlite3_int64 result;
+    int rc = exec_get_int(db, "SELECT memory_set_option('search_oversample', 4);", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT_EQ(result, 1);
+
+    rc = exec_get_int(db, "SELECT memory_get_option('search_oversample');", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT_EQ(result, 4);
+
+    // Set back to 0 (no oversampling)
+    rc = exec_get_int(db, "SELECT memory_set_option('search_oversample', 0);", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT_EQ(result, 1);
+
+    rc = exec_get_int(db, "SELECT memory_get_option('search_oversample');", &result);
+    ASSERT_EQ(rc, SQLITE_OK);
+    ASSERT_EQ(result, 0);
+
+    sqlite3_close(db);
+}
+
 TEST(sqlite_memory_delete_context_with_vault) {
     sqlite3 *db = open_test_db();
     ASSERT(db != NULL);
@@ -2212,6 +2334,12 @@ int main(int argc, char *argv[]) {
     RUN_TEST(sqlite_cache_clear_with_data);
     RUN_TEST(sqlite_cache_clear_by_provider_model);
     RUN_TEST(sqlite_cache_setting_default);
+    RUN_TEST(sqlite_cache_max_entries_setting);
+    RUN_TEST(sqlite_cache_eviction);
+    RUN_TEST(sqlite_cache_no_eviction_when_unlimited);
+
+    printf("\nSearch oversampling tests:\n");
+    RUN_TEST(sqlite_search_oversample_setting);
 #endif
 
     printf("\n=== Results ===\n");