HyNotes

HyNotes is a private web interface for searching and editing notes attached to files in a running Hydrus Network client.

Hydrus remains the source of truth. HyNotes keeps a local SQLite FTS5 index so that note names and note text can be searched quickly. Thumbnails, originals, metadata, and note changes pass through the Hydrus Client API.

Features

• Full-text search across note names and note text.
• Hydrus tag and system-predicate filtering.
• Responsive image gallery and file inspector.
• Add, edit, and delete Hydrus notes.
• Local SQLite FTS5 index with automatic and manual synchronization.
• Request cancellation so older searches and metadata requests cannot replace newer UI state.
• Confirmed writes: the UI reports success only after Hydrus accepts a change.

Requirements

• Python 3.9 or newer.
• A running Hydrus client.
• A Hydrus Client API service with permission to:
  • search files;
  • read files and thumbnails;
  • read file notes;
  • add and delete file notes.

Install

git clone https://github.com/vnmdev/HyNotes.git
cd HyNotes
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env

Edit .env:

HYDRUS_API_URL=http://127.0.0.1:45870
HYDRUS_ACCESS_KEY=your_client_api_access_key
HOST=0.0.0.0
PORT=5051
HYNOTES_DB_PATH=hynotes.db
SYNC_INTERVAL_MINUTES=15

HYDRUS_API_URL is the URL reachable from the machine running HyNotes. It does not have to be reachable from the browser because HyNotes proxies Hydrus requests.

Run

source venv/bin/activate
python app.py

Open http://127.0.0.1:5051 on the same machine. If the machine is reachable over a LAN or Tailnet, use its private hostname or address with port 5051.

The process performs one index sync at startup and repeats it at the configured interval. The Sync button starts an additional background pass when no sync is already running.

The built-in Flask server is suitable for personal testing on a trusted private network. Use a production WSGI server if this becomes a long-running, multi-user service.

Use

1. Enter one or more comma-separated Hydrus tags or predicates.
2. Keep Notes only enabled to search indexed note text.
3. Select a card to open the inspector.
4. Select Edit on a note, or select New note.
5. Save with the button or with Command+Enter on macOS and Ctrl+Enter on other platforms.

An existing note name is locked while editing. This prevents an accidental rename from creating a second note. To create a differently named note, select New note.

The inspector uses a thumbnail for its embedded preview. Select Open original when the full file is needed. This avoids automatically transferring large originals on mobile connections.

Data flow and save behavior

Browser
  |
  v
HyNotes Flask API
  |                \
  | note writes     \ indexed search
  v                   v
Hydrus Client API    SQLite FTS5

For a note change, HyNotes writes to Hydrus first. It updates SQLite only after Hydrus confirms the request. If Hydrus is unavailable or rejects the request, HyNotes returns an error and leaves the local index unchanged.

The SQLite database is a rebuildable search index. It is not a backup of the Hydrus database or media files.

Tests

source venv/bin/activate
python -m unittest discover -v
node --check static/app.js

The Python test suite uses a temporary database and mocked Hydrus requests. It also checks that failed Hydrus writes do not leak into the local index.

Security

HyNotes does not currently provide user accounts or application-level authentication. Do not expose it directly to the public internet.

Recommended deployment:

• bind it only on a trusted LAN or Tailnet;
• keep the Hydrus Client API key in .env;
• restrict the Hydrus API key to the permissions HyNotes needs;
• do not use Tailscale Funnel or router port forwarding;
• protect the host with normal operating-system access controls.

The .env file and local database files are excluded from Git.

Troubleshooting

HyNotes server error after browsing

Current releases close every proxied Hydrus response and every SQLite connection deterministically. Earlier builds could eventually exhaust the host's open-file limit while loading galleries. The symptoms were:

• Too many open files;
• sqlite3.OperationalError: unable to open database file;
• a red HyNotes server error status.

Restart HyNotes after updating. The SQLite index does not need to be deleted.

Change history

See CHANGELOG.md for the reliability and interface changes made to the original prototype.

Project layout

app.py              Flask routes and background sync state
hydrus_client.py    Hydrus Client API wrapper
indexer.py          SQLite/FTS index and confirmed note mutations
templates/          HTML application shell
static/             Browser JavaScript and CSS
tests/              Unit and route tests