Hermes Summarization Calendar

A standalone Hermes Web Dashboard plugin that adds a Calendar page for browsing daily session and cron activity, generating manual per-session summaries, and optionally creating a daily roll-up from saved summaries.

Summarization Calendar does not patch Hermes core. It inventories Hermes session and cron stores read-only and writes its own versioned artifacts under the active HERMES_HOME.

Current behavior

• Calendar month navigation with activity counts.
• Daily session inventory across the default Hermes profile and named profiles.
• Session title with sanitized anchor that navigates to /chat?resume=<session_id>&profile=<profile>.
• Profile-scoped session links, restored model metadata, and browser-local auto-titled session visibility filter.
• Read-only cron execution inventory.
• Manual per-session summaries; nothing runs automatically.
• Lossless transcript chunking for larger sessions.
• Optional daily roll-ups built from current saved session summaries, not raw transcripts.
• Immutable JSON and Markdown versions with fingerprints, staleness detection, durable job state, and explicit regeneration.
• Summary routing through Hermes' configured auxiliary.compression task. The plugin contains no private provider or model fallback.
• Fixed America/Chicago day boundaries.

Requirements

• Hermes Agent with the native Web Dashboard plugin SDK and backend plugin API loader.
• A Hermes build that provides agent.auxiliary_client.call_llm and a working auxiliary.compression route.
• Python 3.11 or newer in the Dashboard runtime.
• Linux for the 1.2.x release line. Artifact locking uses POSIX fcntl; the supplied lifecycle scripts also use Bash and GNU coreutils.
• Node.js 20 or newer only for development tests; users install the prebuilt frontend bundle.

The v1.2.3 release was validated on Hermes Agent v0.20.1 (2026.8.13), Python 3.11, and Node.js 23. Newer Hermes releases may change plugin contracts; see the compatibility notes in SECURITY.md and run the included validation before publishing or deploying an update.

Install

Hermes discovers dashboard plugins at:

$HERMES_HOME/plugins/summarization-calendar/dashboard/manifest.json

For this standalone Dashboard extension, dashboard/manifest.json is the canonical package manifest. A root plugin.yaml or plugin.json is not required by the Dashboard plugin contract.

HERMES_HOME defaults to ~/.hermes.

The Dashboard loader enables a user-installed standalone extension by the exact manifest name. Ensure the active Hermes config contains a YAML list entry for summarization-calendar under plugins.enabled; the directory name may be different. This is separate from the native hermes plugins enable command, which does not manage Dashboard-only packages that have no root plugin.yaml/plugin.json.

From a release archive

Set the release version, download the archive and checksum manifest from the GitHub release, and verify the exact archive before extracting it:

VERSION=1.2.3
ARCHIVE="hermes-summarization-calendar-v${VERSION}.tar.gz"
RELEASE_URL="https://github.com/Ithrial/Hermes-Summarization-Calendar/releases/download/v${VERSION}"

curl -fsSLO "${RELEASE_URL}/${ARCHIVE}"
curl -fsSLO "${RELEASE_URL}/SHA256SUMS"
grep "${ARCHIVE}$" SHA256SUMS | sha256sum -c -

Extract it anywhere, then install a production copy:

tar -xzf "${ARCHIVE}"
cd "hermes-summarization-calendar-v${VERSION}"
HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}" ./scripts/install-local.sh --copy

Use --copy for a normal release installation. The installer stages the replacement, snapshots any existing plugin, and atomically swaps the staged copy into place. If the swap fails, it attempts to restore the previous plugin. It never removes generated summaries or other data under HERMES_HOME.

--symlink is available for development installations, but is not the normal release-update mode.

From Git

Either clone directly into the Hermes plugin path:

mkdir -p "${HERMES_HOME:-$HOME/.hermes}/plugins"
git clone https://github.com/Ithrial/Hermes-Summarization-Calendar.git "${HERMES_HOME:-$HOME/.hermes}/plugins/summarization-calendar"

Or clone elsewhere and run:

./scripts/install-local.sh --copy

The Git method is useful for development or a first install. For a release update, use the checksum-verified release archive and --copy; do not run git pull inside an installed release copy because that bypasses the install backup and atomic-swap workflow.

Load the backend

The frontend can be rediscovered by the Dashboard, but Python API routes are mounted only when the Dashboard process starts. Stop and relaunch hermes dashboard after installation or upgrade. If you manage the Dashboard with systemd, Docker, or another supervisor, restart the Dashboard process through that supervisor using its actual configured unit or service name.

Do not restart the Hermes messaging gateway for a Dashboard-only plugin change.

Then open the Dashboard and select Calendar. The plugin health route is:

GET /api/plugins/summarization-calendar/health

Configure summarization

Daily inventory works without generating summaries. Manual summary and roll-up jobs use the active Hermes profile's standard compression-task configuration:

auxiliary.compression.provider
auxiliary.compression.model
auxiliary.compression.base_url
auxiliary.compression.timeout
auxiliary.compression.reasoning_effort

Configure that route with Hermes itself. Summarization Calendar never writes global model configuration and does not silently substitute a plugin-owned backend.

When a summary is requested, the selected day's transcript slice is sent to the configured compression model. Review SECURITY.md before using a remote provider.

Data and privacy boundaries

Runtime code:

$HERMES_HOME/plugins/summarization-calendar/

Generated data follows the active HERMES_HOME at runtime (or the explicit LEDGER_ROOT override used by tests and controlled deployments):

$HERMES_HOME/summarization-calendar/
  session-versions/
  rollup-versions/
  running/
  .locks/

Source stores are opened read-only. Generated summaries are separate from plugin code and are preserved by default across install, upgrade, rollback, and uninstall.

Upgrading from v1.1.0 and earlier? Existing generated data under $HERMES_HOME/daily-ledger/ is followed in place — nothing is copied or moved, and recaps remain readable. A pre-rename plugins/daily-ledger install is automatically backed up and removed by install-local.sh (restore it with rollback-local.sh). Run ./scripts/status-local.sh to see which store the plugin is currently using.

The release archive never contains your Hermes configuration, credentials, sessions, cron database, logs, or generated Summarization Calendar artifacts.

Status, upgrade, rollback, and uninstall

Show installation and artifact counts:

./scripts/status-local.sh

Upgrade from a new checkout or extracted release:

./scripts/install-local.sh --copy

A pre-existing installation is snapshotted under:

$HERMES_HOME/backups/summarization-calendar-install/

Each snapshot has a generated backup ID and contains the previous plugin plus a manifest. The snapshot is created before the replacement is swapped into place, so it is the rollback handle for that update. Generated summaries remain under $HERMES_HOME/summarization-calendar and are not part of the plugin swap.

List rollback IDs:

./scripts/rollback-local.sh

Restore one:

./scripts/rollback-local.sh <backup-id>

Uninstall code while preserving summaries:

./scripts/uninstall-local.sh

Removing generated data is intentionally separate and destructive:

./scripts/uninstall-local.sh --remove-data

Restart the Dashboard after upgrade, rollback, or uninstall so its Python router set matches the installed code.

Development

The frontend is a prebuilt plain-JavaScript IIFE at dashboard/dist/index.js. It uses React and components supplied by window.__HERMES_PLUGIN_SDK__; React is not bundled.

Install development dependencies in a Python 3.11 environment:

python -m pip install -r requirements-dev.txt
./scripts/run-tests.sh

The test runner executes backend tests with outbound non-loopback sockets blocked, frontend Node tests, Python compilation, JavaScript syntax validation, Bash syntax validation, release validation, and diff checks.

Build release archives from a clean committed tree:

./scripts/build-release.sh --ref v1.2.3

See CONTRIBUTING.md and docs/RELEASE.md.

Known 1.2.x limits

• Day boundaries are fixed to America/Chicago.
• Daily roll-ups summarize saved session summaries rather than re-ingesting all raw transcripts.
• The runtime and lifecycle scripts are POSIX/Linux-oriented.
• Summary quality and runtime depend on the user's configured compression model.
• Dashboard backend plugin routes inherit Hermes' local-dashboard trust model; do not expose an untrusted Dashboard publicly.

License

MIT. See LICENSE.