Skip to content

v2.3.0

Choose a tag to compare

View all tags
@BattermanZ BattermanZ released this 20 Jul 06:45
v2.3.0
9538df5

Important upgrade notice: cache rebuild on first start

v2.3.0 changes Hatchdoor's generated SQLite cache and embedding pipeline. A full cache rebuild is required and happens automatically on first start.

Why the rebuild is required

  • Nomic Embed Text v1.5 now uses a 1,024-token input window. Earlier Hatchdoor versions did not set the model's maximum input length, so FastEmbed silently applied its generic 512-token default. This truncated longer chunks at 512 tokens during embedding.
  • v2.3.0 explicitly configures the Nomic model for 1,024 tokens and includes the maximum token length in the persisted embedder identity. Since sequence length changes the vectors for chunks that exceed the old limit, existing vectors cannot be reused safely.
  • The cache schema also advances to version 6 to store structured note-level frontmatter metadata.

On upgrade, Hatchdoor detects the schema and/or embedder-identity change, wipes the generated SQLite cache, and rebuilds it from the Markdown vault. This is expected. The UI remains reachable and shows live indexing progress, but vault data, search, assets, writes, and MCP endpoints stay unavailable until the rebuild commits successfully. Large vaults may take some time to finish; wait for the index to complete before using the API or MCP tools.

Startup and indexing

  • The UI is available while the initial vault index is built, with token-weighted progress, note and chunk counts, elapsed time, and a measured ETA.
  • Indexing now logs regular human-readable progress heartbeats and additional performance diagnostics.
  • Embeddings are processed chunk-by-chunk rather than padded to the largest item in a batch, reducing peak memory pressure and avoiding wasted inference work.
  • Vault watching and Git sync begin only after the initial index is ready.

MCP, metadata, and search

  • YAML frontmatter is parsed into typed note metadata.
  • get_note now returns normalized tags, aliases, and frontmatter properties.
  • search_notes supports exact tag filters, hierarchical tag-prefix filters, vault-relative path prefixes, required property names, typed property equality, and explicit property projection.
  • query_notes adds metadata-only note queries for requests that do not need content retrieval.
  • Hierarchical tag matching lets topic/selfhosting match notes tagged topic/selfhosting and descendants such as topic/selfhosting/immich.
  • UI tag searches now use #tag/path syntax and return the matching tag branch.

Frontend and iOS PWA

  • Added a regression test preserving viewport-fit=cover, ensuring iOS safe-area insets remain available in the installed PWA on notched and Dynamic-Island devices.

Dependencies and quality

  • Refreshed Rust and frontend dependencies, including git2 0.21, resolving the current RustSec and npm audit findings.
  • Added indexing diagnostics and microbenchmark coverage, startup-gate coverage, metadata regression coverage, and hierarchical tag-search coverage.

Documentation and contribution workflow

  • Added and consolidated architecture decision records.
  • Refreshed contributing guidance for local setup, checks, security, licensing, and the development-branch PR workflow.

Full Changelog: v2.2.0...v2.3.0

Assets 2
Loading