NoteDiscovery

TL;DR

This release focuses on making NoteDiscovery faster on large vaults: switching notes, searching, and mutations are all dramatically faster, even past 10,000 notes (why would you want so many in a single vault though? 😋 but I guess there are tons of use cases out there). There's also a handful of polish around logging, startup, and configurable storage paths. It's not perfect, but I think it's WAY better than before so as always, please open an issue if you hit anything unexpected, bug reports and feedback are hugely appreciated.

Faster

• In-memory note index: A unified, thread-safe index keeps every note's links, backlinks, tags, and search tokens hot in process memory. Endpoints that used to scan the filesystem on every request (/api/backlinks, /api/graph, /api/tags, /api/search, /api/stats) now read straight from the index. On a 15k-note vault: switching a note went from ~4s to under 100ms; /api/graph from 4s+ to under 200ms; /api/stats from a slow walk to under 50ms. The index updates incrementally on every save/delete/move/rename, so there's no staleness while you work.

• Background warmup on startup: A daemon thread pre-builds the index as soon as the server boots, so the first /api/notes request usually hits a warm index. Every (re)build is logged with timing and size, so if an external file change forces a rebuild later you see it too:

  INFO:     Vault index rebuilt in 1.07s (5234 notes)
  

• Optimistic UI for every mutation: Create, delete, rename, and move (notes, folders, media, drawings) update the sidebar tree locally instead of triggering a full vault refetch. Previously each mutation could freeze the UI for 2-4s on big vaults. If the server call fails, the tree resyncs quietly in the background.

UX

• Skeleton sidebar while loading: No more misleading "Add your first note" empty state during a cold load. You get an animated shimmer skeleton until the tree is ready.

• Delayed loading overlay: If /api/notes takes longer than 800ms, a soft overlay covers the tree and editor. Settings, theme, and search stay clickable underneath. Most loads finish under the threshold and the overlay never shows.

• Loading your notes… in all 11 locales. Hungarian was refined to Jegyzetek betöltése after @Adv3n10 feedback. 😋

Internals

• Unified logging: Every startup and runtime message now goes through Python's logging at the right level. Output is uniform with uvicorn's own INFO: / WARNING: / ERROR: / CRITICAL: prefix and filterable from the shell:

  python run.py 2>&1 | findstr "WARNING ERROR CRITICAL"
  

• /api/index/stats: New observability endpoint. Returns counts of indexed notes / folders / links / tags, search index status, and last build duration. Documented in documentation/API.md.

• run.py banner: Slimmed to a single line so the script no longer claims the server is "running" before uvicorn has actually bound to the port. The framework's own INFO: Application startup complete. is now the source of truth for readiness:

  📝 NoteDiscovery → http://localhost:8000  (Ctrl+C to stop)
  

• Configurable storage paths via env vars: NOTES_DIR and PLUGINS_DIR now override config.yaml, matching the precedence pattern already used by PORT, HOST, and authentication settings (env var > config.yaml > default). The resolved paths and their source are logged at startup, so it's obvious where the server is reading from:

  INFO:     Notes directory: /vault (from NOTES_DIR env var)
  INFO:     Plugins directory: ./plugins (from config.yaml)
  

  Full reference in documentation/ENVIRONMENT_VARIABLES.md.

• note_stats plugin rewrite: Dropped unused stats_history, format_stats, get_stats, get_total_stats. Per-save output is now a single line through the unified logger instead of multi-line print() with emojis:

  INFO:     note_stats 20260630.md | 456 words | 29 sentences | ~2m read | 36 lines | 10 lists
  

  No API change for the plugin itself.

• Media uploads and moves invalidate the scan cache: Brings them in line with note mutations so /api/notes and /api/stats reflect new or moved media on the very next request instead of waiting up to 1s for the cache TTL to expire.

Known limits

• Graph view scales with what your browser can render. Below ~1500 notes it's snappy. From there up, the in-browser vis-network force-directed layout is the dominant cost regardless of how fast /api/graph returns. If this becomes an issue I could consider using a different engine but let's be serious, a graph of 10k notes is just way too much IMHO... 🤪

No breaking API changes. /api/notes, /api/search, /api/tags, /api/backlinks, /api/graph return the same shape as before, just much faster.

I hope you guys like this one! 🙏🙏🙏

Docker Images

This release is available as a Docker image:

docker pull ghcr.io/gamosoft/NoteDiscovery:0.28.0

Full Changelog: https://github.com/gamosoft/NoteDiscovery/compare/v0.27.3...v0.28.0