Update function names

Author: marcobambini

API.md

@@ -32,7 +32,7 @@ sqlite-memory enables semantic search over text content stored in SQLite. It:
 
 ## Sync Behavior
 
-All `memory_sync_*` functions use **content-hash change detection** to avoid redundant embedding computation. Each piece of content is hashed before processing — if the hash already exists in the database, the content is skipped.
+All `memory_add_*` functions use **content-hash change detection** to avoid redundant embedding computation. Each piece of content is hashed before processing — if the hash already exists in the database, the content is skipped.
 
 ### Change Detection
 
@@ -201,7 +201,7 @@ SELECT memory_get_option('provider');
 
 ### Memory Management Functions
 
-#### `memory_sync_text(content TEXT [, context TEXT])`
+#### `memory_add_text(content TEXT [, context TEXT])`
 
 Syncs text content to memory. Duplicate content (same hash) is skipped automatically.
 
@@ -223,15 +223,15 @@ Syncs text content to memory. Duplicate content (same hash) is skipped automatic
 **Example:**
 ```sql
 -- Add text without context
-SELECT memory_sync_text('SQLite is a C-language library that implements a small, fast, self-contained SQL database engine.');
+SELECT memory_add_text('SQLite is a C-language library that implements a small, fast, self-contained SQL database engine.');
 
 -- Add text with context
-SELECT memory_sync_text('Important meeting notes from 2024-01-15...', 'meetings');
+SELECT memory_add_text('Important meeting notes from 2024-01-15...', 'meetings');
 ```
 
 ---
 
-#### `memory_sync_file(path TEXT [, context TEXT])`
+#### `memory_add_file(path TEXT [, context TEXT])`
 
 Syncs a file to memory. Unchanged files are skipped; modified files are atomically replaced.
 
@@ -251,13 +251,13 @@ Syncs a file to memory. Unchanged files are skipped; modified files are atomical
 
 **Example:**
 ```sql
-SELECT memory_sync_file('/docs/readme.md');
-SELECT memory_sync_file('/docs/api.md', 'documentation');
+SELECT memory_add_file('/docs/readme.md');
+SELECT memory_add_file('/docs/api.md', 'documentation');
 ```
 
 ---
 
-#### `memory_sync_directory(path TEXT [, context TEXT])`
+#### `memory_add_directory(path TEXT [, context TEXT])`
 
 Synchronizes a directory with memory. Adds new files, reindexes modified files, and removes entries for deleted files.
 
@@ -283,13 +283,13 @@ Synchronizes a directory with memory. Adds new files, reindexes modified files,
 
 **Example:**
 ```sql
-SELECT memory_sync_directory('/path/to/docs');
+SELECT memory_add_directory('/path/to/docs');
 -- Returns: 42 (number of new files processed)
 
-SELECT memory_sync_directory('/project/notes', 'project-notes');
+SELECT memory_add_directory('/project/notes', 'project-notes');
 
 -- Safe to call again — unchanged files are skipped
-SELECT memory_sync_directory('/path/to/docs');
+SELECT memory_add_directory('/path/to/docs');
 -- Returns: 0 (nothing changed)
 ```
 
@@ -477,7 +477,7 @@ The extension tracks two timestamps for each memory:
 
 ### `created_at`
 
-- Set automatically when content is added via `memory_sync_text`, `memory_sync_file`, or `memory_sync_directory`
+- Set automatically when content is added via `memory_add_text`, `memory_add_file`, or `memory_add_directory`
 - Stored as Unix timestamp (seconds since 1970-01-01 00:00:00 UTC)
 - Never updated after initial creation
 
@@ -518,8 +518,8 @@ SELECT memory_set_option('max_tokens', 512);
 SELECT memory_set_option('min_score', 0.75);
 
 -- Add content
-SELECT memory_sync_text('SQLite is a C library that provides a lightweight disk-based database.', 'sqlite-docs');
-SELECT memory_sync_directory('/docs/sqlite', 'sqlite-docs');
+SELECT memory_add_text('SQLite is a C library that provides a lightweight disk-based database.', 'sqlite-docs');
+SELECT memory_add_directory('/docs/sqlite', 'sqlite-docs');
 
 -- Search
 SELECT path, snippet, ranking
@@ -547,9 +547,9 @@ SELECT memory_clear();
 
 ```sql
 -- Add memories with different contexts
-SELECT memory_sync_text('Meeting notes...', 'meetings');
-SELECT memory_sync_text('API documentation...', 'api-docs');
-SELECT memory_sync_text('Tutorial content...', 'tutorials');
+SELECT memory_add_text('Meeting notes...', 'meetings');
+SELECT memory_add_text('API documentation...', 'api-docs');
+SELECT memory_add_text('Tutorial content...', 'tutorials');
 
 -- Search within a context
 SELECT * FROM memory_search
@@ -619,6 +619,6 @@ Errors can be caught using standard SQLite error handling mechanisms.
 
 ```sql
 -- Example error handling in application code
-SELECT memory_sync_text(123);  -- Error: expects TEXT parameter
+SELECT memory_add_text(123);  -- Error: expects TEXT parameter
 SELECT memory_delete('abc');  -- Error: expects INTEGER parameter
 ```

README.md

@@ -83,16 +83,16 @@ SELECT memory_set_model('local', '/path/to/nomic-embed-text-v1.5.Q8_0.gguf');
 -- SELECT memory_set_apikey('your-vectorspace-api-key');
 
 -- Add some knowledge
-SELECT memory_sync_text('SQLite is a C-language library that implements a small, fast,
+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
 most used database engine in the world.', 'sqlite-docs');
 
-SELECT memory_sync_text('Vector databases store data as high-dimensional vectors,
+SELECT memory_add_text('Vector databases store data as high-dimensional vectors,
 enabling similarity search. They are essential for semantic search, recommendation
 systems, and AI applications.', 'concepts');
 
 -- Sync an entire documentation directory
-SELECT memory_sync_directory('/path/to/docs', 'project-docs');
+SELECT memory_add_directory('/path/to/docs', 'project-docs');
 
 -- Search your memory semantically
 SELECT path, snippet, ranking
@@ -124,7 +124,7 @@ conn.execute("SELECT memory_set_model('local', './models/nomic-embed-text-v1.5.Q
 
 # Store conversation context
 def remember(content, context="conversation"):
-    conn.execute("SELECT memory_sync_text(?, ?)", (content, context))
+    conn.execute("SELECT memory_add_text(?, ?)", (content, context))
     conn.commit()
 
 # Retrieve relevant memories
@@ -147,11 +147,11 @@ memories = recall("what's the project timeline")
 
 ## Intelligent Sync
 
-All `memory_sync_*` functions use content-hash change detection to avoid redundant work:
+All `memory_add_*` functions use content-hash change detection to avoid redundant work:
 
-- **`memory_sync_text`** — Computes a hash of the content. If the same content was already indexed, it is skipped entirely. No duplicate embeddings are ever created.
-- **`memory_sync_file`** — Reads the file and hashes its content. If the file was previously indexed with different content, the old entry (chunks, embeddings, FTS) is atomically replaced. Unchanged files are skipped.
-- **`memory_sync_directory`** — Performs a full two-phase sync:
+- **`memory_add_text`** — Computes a hash of the content. If the same content was already indexed, it is skipped entirely. No duplicate embeddings are ever created.
+- **`memory_add_file`** — Reads the file and hashes its content. If the file was previously indexed with different content, the old entry (chunks, embeddings, FTS) is atomically replaced. Unchanged files are skipped.
+- **`memory_add_directory`** — Performs a full two-phase sync:
   1. **Cleanup**: Removes database entries for files that no longer exist on disk
   2. **Scan**: Recursively processes all matching files — adding new ones, replacing modified ones, and skipping unchanged ones
 
@@ -240,7 +240,7 @@ make test
 
 - **Local Engine**: Built-in llama.cpp for on-device embeddings (requires GGUF model)
 - **Remote Engine**: [vectors.space](https://vectors.space) API for cloud embeddings (requires free API key)
-- **File I/O**: `memory_sync_file` and `memory_sync_directory` functions
+- **File I/O**: `memory_add_file` and `memory_add_directory` functions
 
 You can also combine options manually:
 

src/sqlite-memory.c

@@ -56,19 +56,19 @@ SQLITE_EXTENSION_INIT1
 #define DBMEM_SETTINGS_KEY_TEXT_WEIGHT          "text_weight"
 #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"
+#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)
-#define DEFAULT_MAX_TOKENS                      400
-#define DEFAULT_OVERLAY_TOKENS                  80
-#define DEFAULT_MAX_SNIPPET_CHARS               700
-#define DEFAULT_MAX_RESULTS                     20
-#define DEFAULT_VECTOR_WEIGHT                   0.5
-#define DEFAULT_TEXT_WEIGHT                     0.5
-#define DEFAULT_MIN_SCORE                       0.7
+#define DEFAULT_MAX_TOKENS                      400     // Maximum tokens per chunk
+#define DEFAULT_OVERLAY_TOKENS                  80      // Token overlap between consecutive chunks
+#define DEFAULT_MAX_SNIPPET_CHARS               700     // Maximum characters for search result snippets
+#define DEFAULT_MAX_RESULTS                     20      // Maximum number of search results
+#define DEFAULT_VECTOR_WEIGHT                   0.6     // Semantic similarity weight in hybrid search scoring
+#define DEFAULT_TEXT_WEIGHT                     0.4     // Full-text match weight in hybrid search scoring
+#define DEFAULT_MIN_SCORE                       0.7     // Minimum score threshold to filter irrelevant results
 
 struct dbmem_context {
     // Database and engine
@@ -1367,10 +1367,10 @@ static int dbmem_scan_callback (const char *path, void *data) {
     return rc;
 }
 
-static void dbmem_sync_text (sqlite3_context *context, int argc, sqlite3_value **argv) {
+static void dbmem_add_text (sqlite3_context *context, int argc, sqlite3_value **argv) {
     // sanity check type
     if (sqlite3_value_type(argv[0]) != SQLITE_TEXT) {
-        sqlite3_result_error(context, "The function memory_sync_text expects a parameter of type TEXT", SQLITE_ERROR);
+        sqlite3_result_error(context, "The function memory_add_text expects a parameter of type TEXT", SQLITE_ERROR);
         return;
     }
 
@@ -1392,10 +1392,10 @@ static void dbmem_sync_text (sqlite3_context *context, int argc, sqlite3_value *
 }
 
 #ifndef DBMEM_OMIT_IO
-static void dbmem_sync_file (sqlite3_context *context, int argc, sqlite3_value **argv) {
+static void dbmem_add_file (sqlite3_context *context, int argc, sqlite3_value **argv) {
     // sanity check type
     if (sqlite3_value_type(argv[0]) != SQLITE_TEXT) {
-        sqlite3_result_error(context, "The function memory_sync_file expects the first parameter to be of type TEXT", SQLITE_ERROR);
+        sqlite3_result_error(context, "The function memory_add_file expects the first parameter to be of type TEXT", SQLITE_ERROR);
         return;
     }
 
@@ -1439,10 +1439,10 @@ static void dbmem_database_delete_missing_files (sqlite3 *db, const char *dir_pa
     sqlite3_free_table(table);
 }
 
-static void dbmem_sync_directory (sqlite3_context *context, int argc, sqlite3_value **argv) {
+static void dbmem_add_directory (sqlite3_context *context, int argc, sqlite3_value **argv) {
     // sanity check type
     if (sqlite3_value_type(argv[0]) != SQLITE_TEXT) {
-        sqlite3_result_error(context, "The function memory_sync_directory expects the first parameter to be of type TEXT", SQLITE_ERROR);
+        sqlite3_result_error(context, "The function memory_add_directory expects the first parameter to be of type TEXT", SQLITE_ERROR);
         return;
     }
 
@@ -1511,23 +1511,23 @@ SQLITE_DBMEMORY_API int sqlite3_memory_init (sqlite3 *db, char **pzErrMsg, const
     if (rc != SQLITE_OK) return rc;
 
     #ifndef DBMEM_OMIT_IO
-    rc = sqlite3_create_function_v2(db, "memory_sync_file", 1, SQLITE_UTF8, ctx, dbmem_sync_file, NULL, NULL, NULL);
+    rc = sqlite3_create_function_v2(db, "memory_add_file", 1, SQLITE_UTF8, ctx, dbmem_add_file, NULL, NULL, NULL);
     if (rc != SQLITE_OK) return rc;
-    
-    rc = sqlite3_create_function_v2(db, "memory_sync_file", 2, SQLITE_UTF8, ctx, dbmem_sync_file, NULL, NULL, NULL);
+
+    rc = sqlite3_create_function_v2(db, "memory_add_file", 2, SQLITE_UTF8, ctx, dbmem_add_file, NULL, NULL, NULL);
     if (rc != SQLITE_OK) return rc;
-    
-    rc = sqlite3_create_function_v2(db, "memory_sync_directory", 1, SQLITE_UTF8, ctx, dbmem_sync_directory, NULL, NULL, NULL);
+
+    rc = sqlite3_create_function_v2(db, "memory_add_directory", 1, SQLITE_UTF8, ctx, dbmem_add_directory, NULL, NULL, NULL);
     if (rc != SQLITE_OK) return rc;
 
-    rc = sqlite3_create_function_v2(db, "memory_sync_directory", 2, SQLITE_UTF8, ctx, dbmem_sync_directory, NULL, NULL, NULL);
+    rc = sqlite3_create_function_v2(db, "memory_add_directory", 2, SQLITE_UTF8, ctx, dbmem_add_directory, NULL, NULL, NULL);
     if (rc != SQLITE_OK) return rc;
     #endif
 
-    rc = sqlite3_create_function_v2(db, "memory_sync_text", 1, SQLITE_UTF8, ctx, dbmem_sync_text, NULL, NULL, NULL);
+    rc = sqlite3_create_function_v2(db, "memory_add_text", 1, SQLITE_UTF8, ctx, dbmem_add_text, NULL, NULL, NULL);
     if (rc != SQLITE_OK) return rc;
 
-    rc = sqlite3_create_function_v2(db, "memory_sync_text", 2, SQLITE_UTF8, ctx, dbmem_sync_text, NULL, NULL, NULL);
+    rc = sqlite3_create_function_v2(db, "memory_add_text", 2, SQLITE_UTF8, ctx, dbmem_add_text, NULL, NULL, NULL);
     if (rc != SQLITE_OK) return rc;
 
     rc = sqlite3_create_function_v2(db, "memory_delete", 1, SQLITE_UTF8, ctx, dbmem_delete, NULL, NULL, NULL);

src/sqlite-memory.h

@@ -26,7 +26,7 @@
 extern "C" {
 #endif
 
-#define SQLITE_DBMEMORY_VERSION "0.5.5"
+#define SQLITE_DBMEMORY_VERSION "0.6.0"
 
 // public API
 SQLITE_DBMEMORY_API int sqlite3_memory_init (sqlite3 *db, char **pzErrMsg, const sqlite3_api_routines *pApi);

test/unittest.c

@@ -1790,7 +1790,7 @@ static int insert_fake_content(sqlite3 *db, sqlite3_int64 hash, const char *path
 }
 
 TEST(sqlite_sync_directory_removes_deleted) {
-    // Test that memory_sync_directory removes entries for files no longer on disk
+    // Test that memory_add_directory removes entries for files no longer on disk
     sqlite3 *db = open_test_db();
     ASSERT(db != NULL);
 
@@ -1828,7 +1828,7 @@ TEST(sqlite_sync_directory_removes_deleted) {
 
     // Sync — should remove the entry for gone.md, skip keep.md (hash match)
     sqlite3_int64 result;
-    rc = exec_get_int(db, "SELECT memory_sync_directory('/tmp/dbmem_test_sync_del');", &result);
+    rc = exec_get_int(db, "SELECT memory_add_directory('/tmp/dbmem_test_sync_del');", &result);
     ASSERT_EQ(rc, SQLITE_OK);
 
     // Only keep.md entry should remain
@@ -1880,7 +1880,7 @@ TEST(sqlite_sync_directory_removes_all_deleted) {
 
     // Sync — all files gone, all entries should be removed
     sqlite3_int64 result;
-    rc = exec_get_int(db, "SELECT memory_sync_directory('/tmp/dbmem_test_sync_allgone');", &result);
+    rc = exec_get_int(db, "SELECT memory_add_directory('/tmp/dbmem_test_sync_allgone');", &result);
     ASSERT_EQ(rc, SQLITE_OK);
 
     rc = exec_get_int(db, "SELECT COUNT(*) FROM dbmem_content;", &count);
@@ -1917,7 +1917,7 @@ TEST(sqlite_sync_directory_skips_unchanged) {
 
     // Sync — file exists with matching hash, should be skipped
     sqlite3_int64 result;
-    rc = exec_get_int(db, "SELECT memory_sync_directory('/tmp/dbmem_test_sync_skip', 'notes');", &result);
+    rc = exec_get_int(db, "SELECT memory_add_directory('/tmp/dbmem_test_sync_skip', 'notes');", &result);
     ASSERT_EQ(rc, SQLITE_OK);
 
     // Entry still exists unchanged (no duplication)