Blovm - A Local File Indexing and Blossom Sync Daemon

Blovm is a local daemon built with Bun.js that indexes your local files and provides tools to upload them to Blossom servers. It uses a SQLite database for efficient full-text searching of your local and remote content.

Features

• Content-Addressable Indexing: Indexes files based on their SHA-256 hash, tracking both metadata and locations (local or remote).
• Blossom Protocol Integration: Can upload files to Blossom servers using Nostr-based authentication.
• Real-Time Updates: Monitors local directories for changes and keeps the index synchronized.
• MCP Server Interface: Exposes a powerful set of tools to search, manage, and upload your files.
• Configurable: All settings are managed via environment variables.
• Efficient Indexing: Uses streaming SHA-256 hashing and garbage collection for optimal performance.
• Data Integrity: Foreign key constraints ensure blob-location relationships remain consistent.

Configuration

Before running the server, copy the example.env file to .env and fill in the required values.

cp example.env .env

Variable	Description	Default
BLOVM_WATCH_PATH	The path to the directory Blovm should watch for files.	.
DB_FILE	The path to the SQLite database file.	blovm.sqlite
NOSTR_SK	Your Nostr private key in HEX format. Required for uploading blobs.	-
BLOSSOM_SERVER	The default Blossom server URL to upload files to.	- (optional when serverUrl provided)

Usage

To get started, you'll need to have Bun.js installed.

First, install the dependencies:

bun install

Running the Server

You can run the MCP server and the file-watching daemon with a single command:

bun mcp-server.ts

This will start the server and begin indexing files from the directory specified in BLOVM_WATCH_PATH.

Architecture Overview

Blovm uses a two-table database schema that separates content from location:

• blobs: FTS virtual table storing content metadata (SHA-256 hash, file name, description, MIME type, size)
• locations: Standard SQL table tracking where blobs can be found (local paths or remote Blossom URLs)

This design supports a many-to-many relationship where one blob can exist in multiple locations simultaneously.

For detailed technical information about the database schema and implementation, see Blossom Integration Design.

Implementation Details

File Indexing

• Files are indexed using efficient streaming-based SHA-256 hashing to minimize memory usage
• The daemon scans the watch directory recursively and maintains an up-to-date index
• File changes (creations, modifications, deletions) are detected in real-time

Garbage Collection

• When a file is removed, its location entry is deleted
• If no other locations exist for a blob, the blob metadata is automatically cleaned up
• This prevents orphaned entries from accumulating in the database

Data Integrity

• Foreign key constraints ensure all location entries reference valid blobs
• Unique indexes prevent duplicate tracking of the same file path
• Database transactions ensure atomic operations during indexing

Available Tools

Blovm exposes its functionality via an MCP server with the following tools:

blovm-status

Checks the current status of the index.

• Input: None
• Output: A summary of how many unique blobs and locations are currently indexed, along with health check and monitoring status.

list-blobs

Lists all indexed blobs, with optional filters for location.

• Input:
  • local (boolean, optional): If true, only returns blobs with at least one local location.
  • remote (boolean, optional): If true, only returns blobs with at least one remote location.
• Output: A list of matching blobs, including their metadata and all known locations.

search-blobs

Performs a full-text search against the metadata (file name, description, MIME type) of all indexed blobs.

• Input: query (string)
• Output: A list of matching blobs, including their metadata and all known local and remote locations.

upload-blob

Uploads a locally indexed blob to a Blossom server using Nostr-based authentication.

• Input:
  • sha256 (string): The SHA-256 hash of the blob to upload.
  • serverUrl (string, optional): The Blossom server to upload to. Defaults to BLOSSOM_SERVER from your .env file.
• Output: The "Blob Descriptor" JSON from the Blossom server upon successful upload, including the remote URL and upload timestamp.

Note: The blob must have a local location entry in the database for upload to succeed.

remove-file

Deletes a file from the local filesystem. The watcher will automatically detect this and remove the corresponding location from the index. If this was the last location for a blob, the blob metadata will be garbage collected.

• Input: path (string)

rename-file

Renames a file on the local filesystem. The watcher will automatically update the index, maintaining the blob-to-location association.

• Input: from (string), to (string)

bookmark_blob_url

Bookmarks a blob from a URL, creating a remote location entry in the database.

Use Case: Use this tool to save a reference to a blob that is stored on a remote Blossom server. This allows you to track and manage remote blobs that are not yet stored locally.

• Input:
  • url (string): The full URL of the blob (e.g., https://<blossom-server>/<sha256>).
  • name (string, optional): A custom name for the blob.
  • description (string, optional): A description for the blob.
  • mime_type (string, optional): The MIME type of the blob.
  • size (number, optional): The size of the blob in bytes.
• Output: A confirmation message indicating that the blob has been bookmarked.

backup_blob

Downloads a blob from its remote location and stores it locally.

Use Case: After bookmarking a remote blob, use this tool to create a local copy. Once downloaded, the blob will be indexed like any other local file, making it accessible for local operations.

• Input:
  • sha256 (string, optional): The SHA-256 hash of the blob to back up.
  • all_remotes (boolean, optional): If true, backup all remote blobs that are not yet stored locally.
• Output: A confirmation message indicating that the blob has been successfully downloaded and stored locally.

monitor_pubkey

Monitors a Nostr public key for new notes and automatically imports any associated blobs.

Use Case: Keep your local Blovm index synchronized with a Nostr user's latest shared content. This is useful for following creators or backing up your own Nostr-based data.

• Input:
  • source (string): The Nostr public key to monitor. This can be a hex pubkey, npub, or nprofile.
• Output: A confirmation message indicating that the pubkey is being monitored, along with the number of blobs found in the initial scan.