All plugins

qmd-workspaces

Convert uploaded document folders to Markdown, index them in QMD, and retrieve relevant passages for Hermes Desktop with Ollama. Disclosure — reads documents you upload into Hermes' workspaces folder and sends your prompt text and extracted document passages to the configured Ollama endpoint (loopback by default, optionally reached through the Tailscale CLI); writes the shared QMD index and collection config in your user cache and config directories (~/.cache/qmd, ~/.config/qmd), loads QMD's sqlite-vec native extension, and may run qmd status and pdftotext.

lad75020Desktopv1.0.2Updated 5 days ago

About

Convert uploaded document folders to Markdown, index them in QMD, and retrieve relevant passages for Hermes Desktop with Ollama. Disclosure — reads documents you upload into Hermes' workspaces folder and sends your prompt text and extracted document passages to the configured Ollama endpoint (loopback by default, optionally reached through the Tailscale CLI); writes the shared QMD index and collection config in your user cache and config directories (~/.cache/qmd, ~/.config/qmd), loads QMD's sqlite-vec native extension, and may run qmd status and pdftotext.

QMD Workspaces for Hermes

QMD Workspaces converts uploaded documents to Markdown, indexes the Markdown with Ollama embeddings in QMD, and retrieves relevant passages for Hermes Desktop prompts. The archive contains source code only; it includes no workspaces, documents, databases, model weights, or credentials.

Maintainer: @lad75020 · License: MIT

Platform status: Linux support is beta. It has been tested and appears to work, but macOS is the only fully tested platform. Windows is not supported.

Requirements

  • Hermes Agent 0.23.0 or newer.
  • QMD 2.8.3 on the backend machine's PATH, using the same account and QMD index/configuration as Hermes. The plugin accesses QMD's SQLite schema directly; other QMD versions are not verified.
  • Node.js 22 or newer for QMD.
  • The Hermes Python environment with pypdf, python-docx, python-pptx, and ruamel.yaml. These dependencies are declared in plugin.yaml; approve them when Hermes requests dependency installation.
  • Ollama serving embeddinggemma-2 and gemma4:e4b. The default URL is http://127.0.0.1:11434 for a local Ollama server. Configure ollama_url for a different endpoint; remote HTTPS endpoints must present a certificate valid for their hostname. The plugin verifies TLS certificates.
  • macOS or Linux. Windows is not supported because the workspace operation lock uses POSIX fcntl.

The sqlite-vec extension is located relative to the qmd executable. For non-standard QMD layouts, set QMD_SQLITE_VEC_PATH in the backend environment to the trusted, platform-specific extension file.

Install

Use the Hermes Plugin Catalog once this project has a public repository and a reviewed catalog entry. To try a local checkout before publication:

export HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}"
mkdir -p "$HERMES_HOME/plugins"
test ! -e "$HERMES_HOME/plugins/qmd-workspaces" || { echo 'Plugin already exists; stop and back it up first.'; exit 1; }
cp -R /path/to/qmd-workspaces "$HERMES_HOME/plugins/"
hermes plugins enable qmd-workspaces
hermes plugins doctor "$HERMES_HOME/plugins/qmd-workspaces" --ci

Enable the Desktop half separately in Capabilities → Plugins. A native Desktop using a remote backend also needs the Desktop plugin file on the client, installed through the Desktop plugin UI or placed in its local desktop-plugins/qmd-workspaces/plugin.js location. Agent and Desktop plugin enablement are separate. Start a new chat if the new agent tools are not present.

Configure Settings → Plugins → QMD Workspaces → Agent settings (ollama_url, embed_model, search_model, top_k). Do not place non-secret settings in .env. Do not change embedding models for an existing QMD index: vector rows are keyed by content hash and the search path does not isolate models. Use a separate QMD index and config for each embedding model.

Use

  1. Choose Upload Folder… in the prompt selector or open Workspaces. Hermes sends the selected files to the backend; the user's source folder remains unchanged.
  2. Supported text/code and Markdown files remain or become .md; DOCX, text-layer PDF, and PPTX are extracted to Markdown before indexing. Successful workspaces retain Markdown only: uploaded originals, hidden copies, and unsupported files are discarded. Conversion is staged as a batch; unreadable, empty, encrypted, scanned, or malformed documents and staging failures preserve the uploaded originals and report an error. Scanned PDFs need OCR before upload.
  3. Select the workspace below the prompt. The plugin embeds the prompt, retrieves candidates from QMD, and calls the configured Ollama semantic-search model. Retrieved text is untrusted source content, not instructions. The prompt, retrieved excerpts, and extracted documents are sent to the configured Ollama endpoint; Hermes also sends the eventual prompt to its configured inference provider.
  4. The Workspaces page shows indexed, partial, and failed uploads. Re-index folder converts and indexes a verified upload again. A trash icon on each row opens a confirmation dialog. Cancel has no effects. Confirm deletes a verified uploaded workspace and its QMD collection; an external QMD collection is removed from the index only, and its source files stay on disk. The confirmation is bound to the displayed upload generation and collection identity, so stale replacements are refused. Shared vector content used by other collections is retained.

Explicit re-indexing of older Hermes uploads is supported when QMD database/YAML metadata identifies their original plugin-created workspace and the directory passes filesystem validation. Status checks do not migrate or rewrite existing workspaces. An unregistered/nested tool input under the allowed workspace root is copied into a new managed workspace; source files are not modified. Outside-root paths, linked files, and unsafe directories are refused.

Data and external actions

The plugin reads/writes its uploaded workspace under the active Hermes home, QMD's configured SQLite database and collection YAML, and plugin selection state. If the QMD database does not exist, it may invoke qmd status once to initialize QMD's schema. If a PDF needs the optional fallback, it invokes pdftotext from PATH. When a direct connection to a remote Ollama host fails and the tailscale CLI is available, it may use tailscale status and tailscale nc; set TAILSCALE_SOCKET only when a non-default daemon socket is needed. It does not collect telemetry or read credentials from files. Local Ollama traffic uses loopback by default; remote traffic is sent to the endpoint you configure.

QMD's cache and collection configuration default to the current OS user's directories (typically ~/.cache/qmd and ~/.config/qmd, subject to XDG settings). Multiple Hermes profiles under one OS account may therefore share the same QMD index; collections are not a security boundary. Back up an existing QMD index before experimenting. QMD's own embed, vsearch, and query use its own embedding runtime and should not be run against these workspaces; re-index through the plugin instead. QMD may report vectors from Ollama as pending under its own model fingerprint.

Tests

Run from this checkout in an environment that has the Hermes source/runtime available. HERMES_AGENT_ROOT must point to that Hermes checkout; temporary files are isolated beneath QMD_TEST_SCRATCH.

export HERMES_AGENT_ROOT=/path/to/hermes-agent
export QMD_TEST_SCRATCH="${TMPDIR:-/tmp}/qmd-workspaces-tests"
mkdir -p "$QMD_TEST_SCRATCH"
export TMPDIR="$QMD_TEST_SCRATCH" PYTHONDONTWRITEBYTECODE=1
python tests/run_isolated.py
node --experimental-vm-modules --test tests/*test.mjs
python tests/run_isolated.py --doctor
python tests/run_isolated.py --validate

The isolated tests use synthetic TXT/DOCX/PPTX/PDF fixtures, real SQLite/sqlite-vec, and mocked Ollama; they do not contact an Ollama service or modify an existing QMD index. tests/run_integration.py is the opt-in live-Ollama integration suite; configure QMD_TEST_OLLAMA_URL (defaults to loopback) and run it only against a disposable QMD database.

Known limitations

  • PDF extraction uses text layers; image-only scans require OCR outside this plugin.
  • Filesystem/YAML/SQLite operations cannot form one crash-atomic transaction. A failure after DB commit can leave a manageable partial cleanup state, reported by the API; no automatic sweep removes recovery backups.
  • External programs do not honor the plugin's workspace operation locks.
  • Linux support is beta; macOS is the only fully tested platform.

README from the reviewed commit 6c356e8; it updates when the author re-pins.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section