feat: support empty directory markers (#11)

Add explicit empty directory markers via memory_add_content('dirname/', '') for path-preserving virtual filesystem workflows. Directory marker creation now requires preserve_duplicate_paths=1, stores marker paths with a trailing slash, rejects file/directory conflicts, and keeps markers out of search indexes.

Update listing, delete, rename, materialize, directory sync cleanup, and reindex paths to handle markers consistently. Document the new behavior and add focused unit coverage for marker creation, conflicts, listing, deletion, materialization, and reindex survival.

Author: andinux

API.md

@@ -308,11 +308,16 @@ Indexes caller-provided file content without reading from the filesystem.
 - If the path was previously indexed with different content, the old entry (chunks, embeddings, FTS) is deleted and new content is reindexed
 - If the new content is already indexed under another path, the stale path is removed and the existing content entry is reused
 - Set `preserve_duplicate_paths=1` to preserve separate rows for distinct paths with identical or empty content
+- With `preserve_duplicate_paths=1`, an empty `content` value and a trailing slash in `path` creates an explicit empty directory marker, for example `memory_add_content('dirname/', '')`
+- Directory markers are stored in `dbmem_content` with a trailing slash path, are shown as directories by `memory_list_files()`, and are not indexed for search
+- Directory marker paths cannot contain non-empty content and cannot conflict with a file path of the same name
 - Available even when compiled with `DBMEM_OMIT_IO`
 
 **Example:**
 ```sql
 SELECT memory_add_content('docs/api.md', '# API\nContent already loaded by the caller.', 'documentation');
+SELECT memory_set_option('preserve_duplicate_paths', 1);
+SELECT memory_add_content('docs/drafts/', '');
 ```
 
 ---
@@ -334,6 +339,7 @@ Renames an indexed file path in memory without reprocessing content.
 - It does not rename the file on disk or change the stored `source_path` value
 - Does not change `hash`, `value`, embeddings, or FTS entries
 - Fails if `new_path` already exists because `dbmem_content.path` is unique
+- Explicit directory markers can be renamed only to another trailing-slash marker path; this renames only the marker row, not child paths
 - Fails if `old_path` matches more than one row across `path` and local `dbmem_content_source.source_path`; pass a unique logical path or exact local source path
 
 **Example:**
@@ -392,10 +398,11 @@ Writes all stored file contents from `dbmem_content` back to the filesystem.
 |-----------|------|----------|-------------|
 | `root_path` | TEXT | No | Filesystem root used to materialize relative paths |
 
-**Returns:** INTEGER - Number of files processed
+**Returns:** INTEGER - Number of files or explicit directory markers processed
 
 **Notes:**
 - Creates parent directories as needed
+- Explicit directory markers created with `memory_add_content('dirname/', '')` are materialized as directories
 - Relative paths are written under `root_path` when provided
 - Paths containing `..` segments are rejected to prevent writing outside the materialization root
 - If a file already exists with the same content, it is left unchanged and no error is returned
@@ -421,7 +428,7 @@ Returns a JSON tree with the indexed directories and files stored in `dbmem_cont
 **Notes:**
 - Rows added with `memory_add_text()` use generated paths and can appear as root-level file nodes
 - Legacy absolute paths are displayed with their common directory prefix removed when possible
-- Directory nodes are derived from indexed file paths
+- Directory nodes are derived from indexed file paths and explicit directory markers
 - Path separators are normalized to `/` in the returned JSON
 - Sibling nodes are sorted with directories first, then files; each group is alphabetical
 
@@ -488,7 +495,7 @@ SELECT memory_delete_context('meetings');
 
 #### `memory_delete_file(path TEXT)`
 
-Deletes an indexed file by its stored path.
+Deletes an indexed file or explicit directory marker by its stored path.
 
 **Parameters:**
 | Parameter | Type | Description |
@@ -500,6 +507,8 @@ Deletes an indexed file by its stored path.
 **Notes:**
 - Atomically deletes the matching `dbmem_content` entry and its rows in `dbmem_vault` and `dbmem_vault_fts`
 - Does not delete or modify the file on disk
+- When the path names an explicit directory marker, deletes only that marker row; files under the directory are not deleted
+- Directory markers can be matched with either `dirname` or `dirname/`
 - Path matching is exact; if a row has local source metadata, `dbmem_content_source.source_path` is also accepted
 - Fails if the argument matches more than one row across `path` and local `dbmem_content_source.source_path`
 

README.md

@@ -232,6 +232,15 @@ SELECT memory_set_option('preserve_duplicate_paths', 1);
 
 In this mode, `dbmem_content.hash` identifies the stored entry and is scoped by path.
 
+The same mode supports explicit empty directory markers for virtual filesystems:
+
+```sql
+SELECT memory_set_option('preserve_duplicate_paths', 1);
+SELECT memory_add_content('dirname/', '');
+```
+
+Directory markers are listed as directories, materialized as directories by `memory_materialize_files()`, and ignored by `memory_search`.
+
 `memory_add_text()`, `memory_add_file()`, and `memory_add_content()` each run inside a SQLite SAVEPOINT transaction. `memory_add_directory()` performs its cleanup pass transactionally and then processes each file in its own transaction. If one file fails, that file rolls back cleanly and previously-committed files remain valid; there are no partially-indexed rows or orphaned chunk/FTS entries for the failed file.
 
 This makes all sync functions safe to call repeatedly - for example, on a cron schedule or at agent startup - with minimal overhead.