Skip to content

v2.4.0

Latest
Latest

Choose a tag to compare

View all tags
@BattermanZ BattermanZ released this 27 Jul 20:03
v2.4.0
aaf8962
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Hatchdoor v2.4.0

Important

Container deployments must update their environment and bind mounts before upgrading. The old MCP attachment-inbox ingestion system has been removed, a persistent models mount is now required, and the first v2.4.0 startup rebuilds and re-embeds the generated cache.

This is a feature-packed release that I hope you will enjoy! Tons of new things, especially if you are using the LLM Wiki pattern (see below). A bit of prep for you to do (now direct sending of attachments via the MCP) and a new reindex, but this should be the last time in a while, and it is for the best. New embeddings model for better and faster results, and smaller RAM footprint of the server (from 1.3GB to 500MB on reindex).

Enjoy!

Required upgrade actions

1. Replace the retired attachment-inbox mount

Remove the old attachment-ingestion configuration from .env and Docker Compose:

  • HOST_ATTACHMENT_STAGING_PATH
  • HATCHDOOR_MCP_ATTACHMENT_STAGING_PATH
  • HATCHDOOR_MCP_ADVERTISE_HOST_PATHS
  • The attachments-inbox bind mount

Agents must now upload files directly: use multipart POST /api/attachment by default, or the base64 import_attachment MCP tool when they cannot make an out-of-band HTTP request.

2. Add the persistent models mount

Add this to .env:

HOST_MODELS_PATH=./models

Ensure Docker Compose mounts it at /models:

${HOST_MODELS_PATH:-./models}:/models

This directory persists downloaded search models and the local EmbeddingGemma terms-acceptance receipt across container restarts and image upgrades.

Use the checked-in .env.example and docker-compose.yml as the canonical configuration examples.

3. Expect a full reindex on first startup

v2.4.0 rebuilds the disposable SQLite cache automatically. The cache schema changes from 7 to 8, FastEmbed changes from v4 to v5, and embeddings now include each note title and heading path. Hatchdoor therefore reindexes and re-embeds the vault after upgrade. Markdown source files are not changed.

The first startup may also require selecting and downloading a search model. Keep the new /models mount in place so this work is not repeated after a restart.

4. Review renamed and new environment variables

  • Rename HATCHDOOR_MCP_MAX_ATTACHMENT_BYTES to HATCHDOOR_MAX_ATTACHMENT_BYTES for the HTTP/web upload limit.

  • HATCHDOOR_MCP_MAX_BASE64_BYTES controls the decoded-size limit for base64 MCP uploads.

  • HATCHDOOR_EXCLUDE is a comma-separated, gitignore-style list of paths to leave out of indexing, for example:

    HATCHDOOR_EXCLUDE=imports/,*.bak

  • HATCHDOOR_EMBED_LAYERS=false leaves demoted layers keyword-searchable while skipping their vector embeddings.

Note

.hatchdoor-layer is not an exclusion file. It marks a folder as a named, demoted layer. Use HATCHDOOR_EXCLUDE to exclude folders or files from the index.

LLM Wiki raw-source layers

Andrej Karpathy’s LLM Wiki pattern separates immutable raw sources from the LLM-maintained wiki. Hatchdoor can keep those raw files on a separate, explicitly selectable surface:

# raw/.hatchdoor-layer
raw

The raw/ folder then stays out of the browser and default search results, while an MCP client can select it with layers: ["raw"]. Pair this with HATCHDOOR_EMBED_LAYERS=false when the raw corpus should remain available for keyword lookup without consuming vector-indexing resources.

A layer does not make files read-only; use your agent schema/instructions to preserve the raw-source immutability convention.

LLM Wiki users: follow the step-by-step raw-source layer setup before configuring your agent workflow.

Highlights

  • Vault layers and diagnostics: keep source material on named, demoted surfaces; MCP clients can select them explicitly while browser routes remain on the default surface.
  • Noise exclusions: built-in rules now omit .obsidian/, .trash/, .hatchdoor-trash/, .DS_Store, *.tmp, and *.sync-conflict-*; deployment-specific rules use HATCHDOOR_EXCLUDE.
  • First-run semantic-search setup: guided EmbeddingGemma terms acceptance, download progress, and indexing, with Nomic Embed Text v1.5 as an English-focused fallback.
  • Direct agent attachment uploads: no shared staging folder; use HTTP by default or base64 MCP upload as fallback.
  • Inline PDF previews: linked PDF vault assets now render directly in the app.
  • Improved retrieval: FastEmbed v5 and contextual embeddings include each note title and heading path.

See CHANGELOG.md and the README’s Vault Layers And Exclusions section for the complete configuration details.

Assets 2
Loading