Added syncing and fixed some issues in vtable search.

Author: marcobambini

API.md

@@ -12,6 +12,7 @@ A SQLite extension that provides semantic memory capabilities with hybrid search
   - [Configuration Functions](#configuration-functions)
   - [Memory Management Functions](#memory-management-functions)
   - [Deletion Functions](#deletion-functions)
+  - [Sync Functions](#sync-functions)
 - [Virtual Table Module](#virtual-table-module)
 - [C API](#c-api)
 - [Configuration Options](#configuration-options)
@@ -399,6 +400,56 @@ SELECT memory_cache_clear('openai', 'text-embedding-3-small');
 
 ---
 
+### Sync Functions
+
+Require [sqlite-sync](https://github.com/sqliteai/sqlite-sync) to be loaded before use.
+
+#### `memory_enable_sync([context TEXT, ...])`
+
+Enables CRDT-based synchronization for `dbmem_content` via sqlite-sync. Uses the CLS algorithm with block-level LWW on the `value` column for fine-grained conflict resolution.
+
+**Parameters:** Zero or more TEXT context names. If no arguments are given, all memory is synced. If one or more context names are provided, only rows matching those contexts are synced.
+
+**Returns:** INTEGER - 1 on success
+
+**Notes:**
+- Requires sqlite-sync to be loaded; returns an error otherwise
+- Idempotent: safe to call multiple times — each call is a full reconfiguration
+- With no arguments, any previously-set context filter is cleared (sync all)
+- With arguments, sets a row-level filter: only the specified contexts are replicated
+- Block-level LWW on `value` enables line-level conflict resolution for text content
+- All other columns use the default CLS algorithm
+
+**Example:**
+```sql
+-- Sync all memory
+SELECT memory_enable_sync();
+
+-- Sync only specific contexts
+SELECT memory_enable_sync('conversation', 'project-docs');
+```
+
+---
+
+#### `memory_disable_sync()`
+
+Removes synchronization infrastructure from `dbmem_content`, disabling all replication. The table data is preserved.
+
+**Parameters:** None
+
+**Returns:** INTEGER - 1 on success
+
+**Notes:**
+- Requires sqlite-sync to be loaded; returns an error otherwise
+- Safe to call even if sync was never enabled
+
+**Example:**
+```sql
+SELECT memory_disable_sync();
+```
+
+---
+
 ### `memory_search`
 
 A virtual table for performing hybrid semantic search.

Makefile

@@ -472,6 +472,30 @@ e2e: $(BUILD_DEPS) $(TARGET) $(BUILD_DIR)/e2e $(VECTOR_LIB)
 	@VECTOR_LIB=$(CURDIR)/$(VECTOR_LIB) $(BUILD_DIR)/e2e
 	@echo "E2E tests passed!"
 
+SYNC_LIB := $(TEST_DIR)/sync/cloudsync.$(EXT)
+
+$(BUILD_DIR)/test_sync.o: $(TEST_DIR)/sync/test_sync.c | $(BUILD_DIR)
+	@echo "Compiling test_sync.c..."
+	@$(CC) $(CFLAGS) $(TEST_DEFINES) $(DEFINES) $(INCLUDES) -c $< -o $@
+
+$(BUILD_DIR)/test_sync: $(BUILD_DIR)/test_sync.o $(TEST_C_OBJECTS) $(TEST_OBJC_OBJECTS) $(TEST_SQLITE_OBJ) $(LLAMA_LIBS) $(CURL_DEPS) | $(BUILD_DIR)
+	@echo "Linking test_sync..."
+	@$(LINKER) $(BUILD_DIR)/test_sync.o $(TEST_C_OBJECTS) $(TEST_OBJC_OBJECTS) $(TEST_SQLITE_OBJ) $(LLAMA_LIBS) \
+		$(TEST_LDFLAGS) $(FRAMEWORKS) $(TEST_LINK_EXTRAS) \
+		-o $@
+
+.PHONY: sync-test
+sync-test: $(BUILD_DEPS) $(TARGET) $(BUILD_DIR)/test_sync $(VECTOR_LIB)
+	@echo "Running sync integration test..."
+	@APIKEY=$${APIKEY} \
+	 VECTOR_LIB=$(CURDIR)/$(VECTOR_LIB) \
+	 SYNC_LIB=$(CURDIR)/$(SYNC_LIB) \
+	 SYNC_DB_ID=$${SYNC_DB_ID:-db_hqjmctyiplop4qn34lt7y74nli} \
+	 SYNC_APIKEY_A=$${SYNC_APIKEY_A:-rsn7t70bV4KccIlqBZqU0QGfYaN11v9v6LBAOoGYGv8} \
+	 SYNC_APIKEY_B=$${SYNC_APIKEY_B:-GB02PvlrhGAENj0xKHF5KAwHW4BKhSQPvxApS5g8NVM} \
+	 $(BUILD_DIR)/test_sync
+	@echo "Sync test passed!"
+
 .PHONY: remote
 remote:
 	@$(MAKE) OMIT_LOCAL_ENGINE=1 extension

README.md

@@ -164,11 +164,55 @@ Every sync operation is wrapped in a SQLite SAVEPOINT transaction. If anything f
 
 This makes all sync functions safe to call repeatedly - for example, on a cron schedule or at agent startup - with minimal overhead.
 
-## AI Agents Offline Syncing
+## Agent Memory Sync
 
-Thanks to sqlite-sync, agents can share knowledge. Each markdown file added to the database is intelligently parsed and subdivided into chunks, and a [block-based LWW CRDT algorithm](https://github.com/sqliteai/sqlite-sync?tab=readme-ov-file#block-level-lww) keeps everything in sync. All memory, or just a specific memory context, can be kept in sync between agents.
+Multiple agents can share and merge knowledge without any coordination. Each agent works independently with its own local SQLite database, syncing through a shared [SQLiteCloud](https://sqlitecloud.io/) managed database when connectivity is available.
 
-Memory syncing will be exposed in version 0.9.0.
+Enable sync on a database connection before ingesting content:
+
+```sql
+-- Load the sqlite-sync extension
+SELECT load_extension('./cloudsync');
+
+-- Enable CRDT sync (optionally scoped to a specific context)
+SELECT memory_enable_sync();               -- sync all memory
+SELECT memory_enable_sync('project-x');   -- sync only the 'project-x' context
+
+-- Connect to the shared cloud database
+SELECT cloudsync_network_init('your-managed-database-id');
+SELECT cloudsync_network_set_apikey('your-api-key');
+
+-- Ingest content normally — CRDT tracks every write
+SELECT memory_add_text('Agent A findings...', 'research');
+
+-- Push local changes and pull remote ones (call twice for full bidirectional exchange)
+SELECT cloudsync_network_sync(500, 3);
+SELECT cloudsync_network_sync(500, 3);
+
+-- Generate embeddings for any content received from other agents
+SELECT memory_reindex();
+```
+
+Each piece of text added to the database is parsed into chunks and tracked by a [block-level LWW CRDT algorithm](https://github.com/sqliteai/sqlite-sync?tab=readme-ov-file#block-level-lww), which merges line-level changes from concurrent agents without conflicts. Only the `dbmem_content` table is synced — embeddings are always generated locally after receiving new content.
+
+### Why This Matters for AI Systems
+
+The combination of local-first memory and CRDT sync enables agent architectures that are not possible with centralized databases:
+
+- **No single point of failure** — each agent has a complete, queryable copy of shared memory
+- **Offline-capable** — agents ingest and search without network access; sync catches up when connectivity returns
+- **Selective sharing** — `memory_enable_sync('context')` limits sync to a named context, so agents can keep private memory separate from shared memory
+- **Scales to many agents** — agents running on different nodes accumulate knowledge in parallel and merge into a single consistent corpus without coordination
+
+### Working Example
+
+[`test/sync/`](test/sync/) contains a full integration test that walks through the entire flow:
+
+- Agent A indexes knowledge about the James Webb Space Telescope
+- Agent B indexes knowledge about the Great Barrier Reef
+- After sync, **both agents can answer questions about both topics** — knowledge each agent never directly indexed
+
+See [`test/sync/README.md`](test/sync/README.md) for setup instructions, SQLiteCloud account configuration, and how to run the test.
 
 ## Use Cases
 

src/dbmem-search.c

@@ -382,7 +382,8 @@ static int dbmem_semantic_search (sqlite3 *db, vMemorySearchCursor *c, float *em
     static const char *sql_with_context =
         "SELECT v.distance, e.hash, e.seq FROM dbmem_vault AS e "
         "JOIN vector_full_scan('dbmem_vault', 'embedding', ?1, ?2) AS v ON e.rowid = v.rowid "
-        "WHERE INSTR(',' || ?3 || ',', ',' || e.context || ',') > 0";
+        "JOIN dbmem_content AS c ON e.hash = c.hash "
+        "WHERE INSTR(',' || ?3 || ',', ',' || c.context || ',') > 0";
     const char *sql = (context) ? sql_with_context : sql_no_context;
 
     sqlite3_stmt *vm = NULL;
@@ -452,32 +453,44 @@ static int vMemorySearchDisconnect (sqlite3_vtab *pVtab) {
     return SQLITE_OK;
 }
 
+// idxNum bitmask for vMemorySearchCursorFilter to decode argv positions:
+#define SEARCH_IDX_QUERY    0x01  // argv[0] = query text
+#define SEARCH_IDX_MAXITEMS 0x02  // next argv = max_results
+#define SEARCH_IDX_CONTEXT  0x04  // next argv = context name
+
 static int vMemorySearchBestIndex (sqlite3_vtab *tab, sqlite3_index_info *pIdxInfo) {
     UNUSED_PARAM(tab);
     pIdxInfo->estimatedCost = (double)1;
     pIdxInfo->estimatedRows = 100;
     pIdxInfo->orderByConsumed = 1;
-    pIdxInfo->idxNum = 1;
-    
+
+    // Assign consecutive argvIndex values (no gaps) and record which columns are
+    // present in idxNum so xFilter can decode argv without ambiguity.
+    int idxNum = 0;
+    int argvIndex = 1;
     const struct sqlite3_index_constraint *pConstraint = pIdxInfo->aConstraint;
-    for(int i=0; i<pIdxInfo->nConstraint; i++, pConstraint++){
-        if( pConstraint->usable == 0 ) continue;
-        if( pConstraint->op != SQLITE_INDEX_CONSTRAINT_EQ ) continue;
-        switch( pConstraint->iColumn ){
+    for (int i = 0; i < pIdxInfo->nConstraint; i++, pConstraint++) {
+        if (pConstraint->usable == 0) continue;
+        if (pConstraint->op != SQLITE_INDEX_CONSTRAINT_EQ) continue;
+        switch (pConstraint->iColumn) {
             case SEARCH_COLUMN_QUERY:
-                pIdxInfo->aConstraintUsage[i].argvIndex = 1;
+                pIdxInfo->aConstraintUsage[i].argvIndex = argvIndex++;
                 pIdxInfo->aConstraintUsage[i].omit = 1;
+                idxNum |= SEARCH_IDX_QUERY;
                 break;
             case SEARCH_COLUMN_MAXITEMS:
-                pIdxInfo->aConstraintUsage[i].argvIndex = 2;
+                pIdxInfo->aConstraintUsage[i].argvIndex = argvIndex++;
                 pIdxInfo->aConstraintUsage[i].omit = 1;
+                idxNum |= SEARCH_IDX_MAXITEMS;
                 break;
             case SEARCH_COLUMN_CONTEXT:
-                pIdxInfo->aConstraintUsage[i].argvIndex = 3;
+                pIdxInfo->aConstraintUsage[i].argvIndex = argvIndex++;
                 pIdxInfo->aConstraintUsage[i].omit = 1;
+                idxNum |= SEARCH_IDX_CONTEXT;
                 break;
         }
     }
+    pIdxInfo->idxNum = idxNum;
     return SQLITE_OK;
 }
 
@@ -559,31 +572,35 @@ static int vMemorySearchCursorFilter (sqlite3_vtab_cursor *cur, int idxNum, cons
     dbmem_context *ctx = searchTab->ctx;
     sqlite3 *db = searchTab->db;
 
-    // check and retrieve arguments
+    // Decode arguments using the idxNum bitmask set by xBestIndex.
+    // argvIndex values are consecutive so argv positions are derived from the bitmask.
     int  max_results = dbmem_context_max_results(ctx);
     bool perform_fts = dbmem_context_perform_fts(ctx);
     const char *query = NULL;
     const char *context = NULL;
-    
-    if (argc <= 0) {
+
+    if (!(idxNum & SEARCH_IDX_QUERY) || argc <= 0) {
         sqlvTab->zErrMsg = sqlite3_mprintf("The memory_search function expects at least one query argument of type TEXT");
         return SQLITE_ERROR;
     }
-    
-    if (sqlite3_value_type(argv[0]) != SQLITE_TEXT) {
-        sqlvTab->zErrMsg = sqlite3_mprintf("The first query argument of memory_search must be of type TEXT");
-        return SQLITE_ERROR;
-    }
-    query = (const char *)sqlite3_value_text(argv[0]);
-    
-    if (argc > 1) {
-        // only the next two arguments are handled
-        for (int i=1; i<argc && i<=2; ++i) {
-            if (sqlite3_value_type(argv[i]) == SQLITE_INTEGER) max_results = sqlite3_value_int(argv[i]);
-            else if (sqlite3_value_type(argv[i]) == SQLITE_TEXT) context = (const char *)sqlite3_value_text(argv[i]);
-            // ignore any other type
+
+    int argPos = 0;
+    if (idxNum & SEARCH_IDX_QUERY) {
+        if (sqlite3_value_type(argv[argPos]) != SQLITE_TEXT) {
+            sqlvTab->zErrMsg = sqlite3_mprintf("The first query argument of memory_search must be of type TEXT");
+            return SQLITE_ERROR;
         }
+        query = (const char *)sqlite3_value_text(argv[argPos++]);
+    }
+    if (idxNum & SEARCH_IDX_MAXITEMS) {
+        if (sqlite3_value_type(argv[argPos]) == SQLITE_INTEGER) max_results = sqlite3_value_int(argv[argPos]);
+        argPos++;
+    }
+    if (idxNum & SEARCH_IDX_CONTEXT) {
+        if (sqlite3_value_type(argv[argPos]) == SQLITE_TEXT) context = (const char *)sqlite3_value_text(argv[argPos]);
+        argPos++;
     }
+    (void)argPos; (void)argc; (void)idxStr;
 
     // compute fetch count (oversampling)
     int oversample = dbmem_context_search_oversample(ctx);