Minor issues fixed, clarified README and raised version to 0.8.5

Author: marcobambini

API.md

@@ -13,6 +13,7 @@ A SQLite extension that provides semantic memory capabilities with hybrid search
   - [Memory Management Functions](#memory-management-functions)
   - [Deletion Functions](#deletion-functions)
 - [Virtual Table Module](#virtual-table-module)
+- [C API](#c-api)
 - [Configuration Options](#configuration-options)
 - [Timestamps](#timestamps)
 - [Examples](#examples)
@@ -407,39 +408,164 @@ A virtual table for performing hybrid semantic search.
 SELECT * FROM memory_search WHERE query = 'search text';
 ```
 
-**Columns:**
+**Hidden filter columns (used in WHERE):**
+| Column | Type | Required | Description |
+|--------|------|----------|-------------|
+| `query` | TEXT | Yes | The search query |
+| `max_entries` | INTEGER | No | Override `max_results` setting for this query only |
+| `context` | TEXT | No | Restrict results to a specific context label |
+
+**Output columns:**
 | Column | Type | Description |
 |--------|------|-------------|
-| `query` | TEXT (HIDDEN) | Search query (required in WHERE clause) |
 | `hash` | INTEGER | Content hash identifier |
+| `seq` | INTEGER | Chunk sequence number within the document (0-based) |
+| `ranking` | REAL | Combined similarity score (0.0 - 1.0) |
 | `path` | TEXT | Source file path or generated UUID for text content |
-| `context` | TEXT | Context label (NULL if not set) |
 | `snippet` | TEXT | Text snippet from the matching chunk |
-| `ranking` | REAL | Combined similarity score (0.0 - 1.0) |
 
 **Notes:**
 - Requires sqlite-vector extension loaded first
 - Performs hybrid search combining vector similarity and FTS5
 - Results are ranked by combined score
-- Limited by `max_results` setting (default: 20)
+- Limited by `max_results` setting (default: 20), overridable per-query with `max_entries`
 - Filtered by `min_score` setting (default: 0.7)
 - Updates `last_accessed` timestamp if `update_access` is enabled
 
 **Example:**
 ```sql
 -- Basic search
-SELECT * FROM memory_search WHERE query = 'database indexing strategies';
+SELECT path, snippet, ranking FROM memory_search WHERE query = 'database indexing strategies';
 
 -- Search with ranking filter
 SELECT path, snippet, ranking
 FROM memory_search
 WHERE query = 'how to optimize queries'
 AND ranking > 0.8;
 
--- Search within a specific context
-SELECT * FROM memory_search
+-- Restrict to a specific context
+SELECT path, snippet, ranking
+FROM memory_search
 WHERE query = 'meeting action items'
 AND context = 'meetings';
+
+-- Override result limit for this query only
+SELECT path, snippet, ranking
+FROM memory_search
+WHERE query = 'architecture overview'
+AND max_entries = 5;
+
+-- Get the chunk sequence number (useful for reconstructing document order)
+SELECT path, seq, snippet, ranking
+FROM memory_search
+WHERE query = 'installation steps';
+```
+
+---
+
+## C API
+
+In addition to the SQL interface, sqlite-memory exposes a C API for embedding custom providers directly from application code.
+
+### `sqlite3_memory_register_provider`
+
+```c
+int sqlite3_memory_register_provider(
+    sqlite3 *db,
+    const char *provider_name,
+    const dbmem_provider_t *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.
+
+**Parameters:**
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `db` | `sqlite3 *` | The database connection to register the provider on |
+| `provider_name` | `const char *` | Name used to activate the provider via `memory_set_model()` |
+| `provider` | `const dbmem_provider_t *` | Pointer to a struct containing the engine callbacks |
+
+**Returns:** `SQLITE_OK` on success, or a SQLite error code.
+
+**`dbmem_provider_t` struct:**
+```c
+typedef struct {
+    // Called when memory_set_model(provider_name, model) is executed.
+    // 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).
+    void *(*init)(const char *model, const char *api_key, void *xdata, char err_msg[1024]);
+
+    // Compute the embedding for the given text.
+    // Return 0 on success, non-zero on error.
+    int   (*compute)(void *engine, const char *text, int text_len, void *xdata, dbmem_embedding_result_t *result);
+
+    // Free the engine. Called on context teardown or when the model changes.
+    // May be NULL if no cleanup is needed.
+    void  (*free)(void *engine, void *xdata);
+
+    // Optional user-supplied pointer passed to all three callbacks.
+    void  *xdata;
+} dbmem_provider_t;
+```
+
+**`dbmem_embedding_result_t` struct:**
+```c
+typedef struct {
+    int    n_tokens;            // Number of tokens processed
+    int    n_tokens_truncated;  // Tokens that were truncated (0 if none)
+    int    n_embd;              // Embedding dimension
+    float *embedding;           // Embedding vector (engine-owned, valid until next call or free)
+} dbmem_embedding_result_t;
+```
+
+**Notes:**
+- Works regardless of `DBMEM_OMIT_LOCAL_ENGINE` / `DBMEM_OMIT_REMOTE_ENGINE` compile flags
+- The `embedding` buffer in `dbmem_embedding_result_t` must remain valid until the next `compute` call or `free` — it is engine-owned, not copied by the caller
+- Only one custom provider can be registered per connection at a time; registering again replaces the previous one
+- The provider struct is copied by value; the caller does not need to keep it alive after registration
+
+**Example:**
+```c
+#include "sqlite-memory.h"
+
+typedef struct { int dimension; } MyEngine;
+
+static void *my_init(const char *model, const char *api_key, void *xdata, char err_msg[1024]) {
+    MyEngine *e = malloc(sizeof(MyEngine));
+    e->dimension = 384;
+    return e;
+}
+
+static int my_compute(void *engine, const char *text, int text_len, void *xdata,
+                      dbmem_embedding_result_t *result) {
+    MyEngine *e = (MyEngine *)engine;
+    static float vec[384];
+    // ... fill vec with your embedding ...
+    result->n_embd = e->dimension;
+    result->n_tokens = text_len / 4;
+    result->n_tokens_truncated = 0;
+    result->embedding = vec;
+    return 0;
+}
+
+static void my_free(void *engine, void *xdata) {
+    free(engine);
+}
+
+// Register before using the database
+dbmem_provider_t provider = {
+    .init    = my_init,
+    .compute = my_compute,
+    .free    = my_free,
+    .xdata   = NULL,
+};
+sqlite3_memory_register_provider(db, "my-engine", &provider);
+
+// Then from SQL:
+// SELECT memory_set_model('my-engine', 'my-model-name');
+// SELECT memory_add_text('some text to embed');
 ```
 
 ---

Makefile

@@ -60,7 +60,7 @@ OUTPUT_NAME := memory
 ifeq ($(PLATFORM),macos)
     EXT := dylib
     FRAMEWORKS := -framework Security
-    LDFLAGS := -dynamiclib $(FRAMEWORKS)
+    LDFLAGS := -dynamiclib -undefined dynamic_lookup $(FRAMEWORKS)
     INCLUDES += -I/opt/homebrew/include -I/usr/local/include
     TEST_LDFLAGS := -L/opt/homebrew/lib -L/usr/local/lib -lsqlite3
     STRIP_CMD = strip -x -S $(TARGET)
@@ -196,7 +196,7 @@ ifeq ($(OMIT_LOCAL_ENGINE),0)
         else
             LLAMA_OPTIONS += '-DCMAKE_OSX_ARCHITECTURES=x86_64;arm64'
         endif
-        LDFLAGS := -dynamiclib -framework Metal -framework Foundation -framework Accelerate -framework Security
+        LDFLAGS := -dynamiclib -undefined dynamic_lookup -framework Metal -framework Foundation -framework Accelerate -framework Security
         ifeq ($(ARCH),x86_64)
             LDFLAGS += -arch x86_64
         else ifeq ($(ARCH),arm64)

README.md

@@ -1,6 +1,8 @@
 # SQLite Memory
 
-A SQLite extension that gives AI agents persistent, searchable memory. Features hybrid semantic search (vector similarity + FTS5), markdown-aware chunking, and local embedding via llama.cpp. Memory databases can be synced between agents using **offline first technology** each agent works independently and syncs when connected, making it ideal for distributed AI systems, edge deployments, and collaborative agent architectures.
+A SQLite extension that gives AI agents persistent, searchable memory, optimized for markdown content. Features hybrid semantic search (vector similarity + FTS5), markdown-aware chunking, and local embedding via llama.cpp.
+
+Agent memory databases can be synchronized between agents using **offline-first technology** via [sqlite-sync](https://github.com/sqliteai/sqlite-sync). Each agent works independently and syncs when connected, making it ideal for distributed AI systems, edge deployments, and collaborative agent architectures.
 
 ## The Future of AI Agent Memory
 
@@ -33,10 +35,10 @@ sqlite-memory bridges these concepts, allowing any SQLite-powered application to
 
 - **Hybrid Search**: Combines vector similarity (cosine distance) with FTS5 full-text search for superior retrieval
 - **Smart Chunking**: Markdown-aware parsing preserves semantic boundaries
-- **Intelligent Sync**: Content-hash change detection, unchanged files are skipped, modified files are atomically replaced, deleted files are cleaned up
-- **Transactional Safety**: Every sync operation runs inside a SAVEPOINT transaction, either fully succeeds or fully rolls back, no partially-indexed content
+- **Intelligent Sync**: Content-hash change detection skips unchanged files, atomically replaces modified ones, and cleans up deleted ones
+- **Transactional Safety**: Every sync operation runs inside a SAVEPOINT transaction - either fully succeeds or fully rolls back, no partially-indexed content
 - **Efficient Storage**: Binary embeddings with configurable dimensions
-- **Embedding Cache**: Automatically caches computed embeddings so re-indexing the same text skips redundant API calls and computation
+- **Embedding Cache**: Automatically caches computed embeddings, so re-indexing the same text skips redundant API calls and computation
 - **Flexible Embedding**: Use local models (llama.cpp) or [vectors.space](https://vectors.space) remote API
 
 ## Architecture
@@ -63,14 +65,16 @@ sqlite-memory bridges these concepts, allowing any SQLite-powered application to
 
 - SQLite
 - [sqlite-vector](https://github.com/sqliteai/sqlite-vector) extension
+- [sqlite-sync](https://github.com/sqliteai/sqlite-sync) extension (optional, only needed for agent sync)
 - **For local embeddings**: A GGUF embedding model (e.g., [nomic-embed-text](https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF))
 - **For remote embeddings**: A free API key from [vectors.space](https://vectors.space)
 
 ### Quick Start
 
 ```sql
--- Load extensions
+-- Load extensions (sync is optional)
 .load ./vector
+.load ./sync
 .load ./memory
 
 -- Configure embedding model (choose one):
@@ -79,6 +83,7 @@ sqlite-memory bridges these concepts, allowing any SQLite-powered application to
 SELECT memory_set_model('local', '/path/to/nomic-embed-text-v1.5.Q8_0.gguf');
 
 -- Option 2: Remote embedding via vectors.space (requires free API key from https://vectors.space)
+-- The provider name 'openai' selects the vectors.space OpenAI-compatible endpoint.
 -- SELECT memory_set_model('openai', 'text-embedding-3-small');
 -- SELECT memory_set_apikey('your-vectorspace-api-key');
 
@@ -91,7 +96,7 @@ 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
+-- Add an entire documentation directory
 SELECT memory_add_directory('/path/to/docs', 'project-docs');
 
 -- Search your memory semantically
@@ -149,15 +154,21 @@ memories = recall("what's the project timeline")
 
 All `memory_add_*` functions use content-hash change detection to avoid redundant work:
 
-- **`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:
+- **`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
+  2. **Scan**: Recursively processes all matching files - adding new ones, replacing modified ones, and skipping unchanged ones
 
 Every sync operation is wrapped in a SQLite SAVEPOINT transaction. If anything fails mid-sync (embedding error, disk issue, etc.), the entire operation rolls back cleanly. There is no risk of partially-indexed files or orphaned entries.
 
-This makes all sync functions safe to call repeatedly — for example, on a cron schedule or at agent startup — with minimal overhead.
+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
+
+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.
+
+Memory syncing will be exposed in version 0.9.0.
 
 ## Use Cases
 
@@ -197,8 +208,7 @@ SELECT memory_cache_clear();                           -- Clear cached embedding
 
 ```sql
 -- View all memories
-SELECT hash, path, context,
-       datetime(created_at, 'unixepoch', 'localtime') as created
+SELECT hash, path, context, datetime(created_at, 'unixepoch', 'localtime') as created
 FROM dbmem_content;
 
 -- Delete by context
@@ -219,7 +229,7 @@ For complete API documentation, including all functions and configuration option
 
 ```bash
 # Clone with submodules
-git clone --recursive https://github.com/user/sqlite-memory.git
+git clone --recursive https://github.com/sqliteai/sqlite-memory.git
 cd sqlite-memory
 
 # Build (full build with local + remote engines)
@@ -259,17 +269,17 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 ## Part of the SQLite AI Ecosystem
 
-This project is part of the **SQLite AI** ecosystem, a collection of extensions that bring modern AI capabilities to the world’s most widely deployed database. The goal is to make SQLite the default data and inference engine for Edge AI applications.
+This project is part of the **SQLite AI** ecosystem, a collection of extensions that bring modern AI capabilities to the world's most widely deployed database. The goal is to make SQLite the default data and inference engine for Edge AI applications.
 
 Other projects in the ecosystem include:
 
-- **[SQLite-AI](https://github.com/sqliteai/sqlite-ai)** — On-device inference and embedding generation directly inside SQLite.
-- **[SQLite-Memory](https://github.com/sqliteai/sqlite-memory)** — Markdown-based AI agent memory with semantic search.
-- **[SQLite-Vector](https://github.com/sqliteai/sqlite-vector)** — Ultra-efficient vector search for embeddings stored as BLOBs in standard SQLite tables.
-- **[SQLite-Sync](https://github.com/sqliteai/sqlite-sync)** — Local-first CRDT-based synchronization for seamless, conflict-free data sync and real-time collaboration across devices.
-- **[SQLite-Agent](https://github.com/sqliteai/sqlite-agent)** — Run autonomous AI agents directly from within SQLite databases.
-- **[SQLite-MCP](https://github.com/sqliteai/sqlite-mcp)** — Connect SQLite databases to MCP servers and invoke their tools.
-- **[SQLite-JS](https://github.com/sqliteai/sqlite-js)** — Create custom SQLite functions using JavaScript.
-- **[Liteparser](https://github.com/sqliteai/liteparser)** — A highly efficient and fully compliant SQLite SQL parser.
+- **[SQLite-AI](https://github.com/sqliteai/sqlite-ai)** - On-device inference and embedding generation directly inside SQLite.
+- **[SQLite-Memory](https://github.com/sqliteai/sqlite-memory)** - Markdown-based AI agent memory with semantic search.
+- **[SQLite-Vector](https://github.com/sqliteai/sqlite-vector)** - Ultra-efficient vector search for embeddings stored as BLOBs in standard SQLite tables.
+- **[SQLite-Sync](https://github.com/sqliteai/sqlite-sync)** - Local-first CRDT-based synchronization for seamless, conflict-free data sync and real-time collaboration across devices.
+- **[SQLite-Agent](https://github.com/sqliteai/sqlite-agent)** - Run autonomous AI agents directly from within SQLite databases.
+- **[SQLite-MCP](https://github.com/sqliteai/sqlite-mcp)** - Connect SQLite databases to MCP servers and invoke their tools.
+- **[SQLite-JS](https://github.com/sqliteai/sqlite-js)** - Create custom SQLite functions using JavaScript.
+- **[Liteparser](https://github.com/sqliteai/liteparser)** - A highly efficient and fully compliant SQLite SQL parser.
 
 Learn more at **[SQLite AI](https://sqlite.ai)**.

src/dbmem-http.h

@@ -16,7 +16,7 @@ extern "C" {
 
 // Synchronous HTTP POST using NSURLSession.
 // Returns 0 on success, -1 on error.
-// On success: *out_data is malloc'd response body (caller frees), *out_size is its length, *out_http_code is the status.
+// On success: *out_data is sqlite3_malloc64'd response body (caller must sqlite3_free), *out_size is its length, *out_http_code is the status.
 // On error: err_msg is filled with a description.
 int dbmem_http_post(const char *url, const char *api_key, const char *body,
                     void **out_data, size_t *out_size, long *out_http_code,

src/dbmem-http.m

@@ -7,8 +7,8 @@
 
 #import <Foundation/Foundation.h>
 #include "dbmem-http.h"
+#include "sqlite-memory.h"
 #include <string.h>
-#include <stdlib.h>
 
 int dbmem_http_post(const char *url, const char *api_key, const char *body,
                     void **out_data, size_t *out_size, long *out_http_code,
@@ -53,7 +53,7 @@ int dbmem_http_post(const char *url, const char *api_key, const char *body,
 
         *out_http_code = httpResponse.statusCode;
         *out_size = responseData.length;
-        *out_data = malloc(responseData.length + 1);
+        *out_data = sqlite3_malloc64(responseData.length + 1);
         if (!*out_data) {
             snprintf(err_msg, err_msg_size, "Failed to allocate response buffer");
             return -1;