No description
  • TypeScript 69%
  • Nix 27.1%
  • JavaScript 3.9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-17 20:39:57 -05:00
.github Run CI tests with coverage reporting 2026-10-13 21:35:04 -04:00
docs feat: HTTP bearer-token auth and Home Manager environmentFile option 2026-07-15 23:31:42 -04:00
modules/home-manager feat: HTTP bearer-token auth and Home Manager environmentFile option 2026-07-15 23:31:42 -04:00
nix fix: mcp.url default missing required /mcp path 2026-09-26 23:15:29 -04:00
pkgs chore: refresh npm dependency hash 2026-10-13 23:42:15 +00:00
skills/hermes-social-digest-pipeline feat: HTTP bearer-token auth and Home Manager environmentFile option 2026-07-15 23:31:42 -04:00
src Extend reply_to_id/root_id capture to Mastodon and Bluesky 2026-10-14 18:05:19 -04:00
.gitignore Harden and document social digest pipeline 2026-06-24 18:12:47 -04:00
.pre-commit-config.yaml CI Setup 2026-06-24 20:58:52 -04:00
AGENTS.md Add Hermes social digest pipeline 2026-06-24 08:43:43 -04:00
flake.lock chore: update Nix dependencies 2026-11-16 10:09:08 -05:00
flake.nix Add nixosModules.default for the collector/catchup timers 2026-09-26 21:02:17 -04:00
package-lock.json chore(deps): update npm non-breaking updates 2026-10-13 23:41:50 +00:00
package.json Run CI tests with coverage reporting 2026-10-13 21:35:04 -04:00
README.md feat: HTTP bearer-token auth and Home Manager environmentFile option 2026-07-15 23:31:42 -04:00
tsconfig.json Add Hermes social digest pipeline 2026-06-24 08:43:43 -04:00

HermesSocialDigestPipeline

HermesSocialDigestPipeline is an end-user tool for building a daily social-feed digest with Hermes Agent. It collects compact candidate items from the read-only social-reader MCP, stores them locally on the Hermes host, and emits bounded JSON context that a scheduled Hermes job can turn into a human-readable digest.

The social-reader MCP is treated as a black box. It can stay on another host later; this pipeline does not require scripts, shared files, SSH access, or Hermes Agent on the MCP host.

Who this is for

Use this repo if you want Hermes to:

  • collect social-feed candidates throughout the day without handing the LLM a full raw timeline;
  • preserve cursor safety by saving candidates before advancing MCP cursors;
  • run from a Nix-managed package or Home Manager module;
  • keep digest state on the Hermes Agent host under a private local state directory.

What you get

Two CLI commands are installed by the package:

hermes-social-digest-collect
hermes-social-digest-compile-context

The flake also exposes app shortcuts:

nix run .#collect -- --dry-run --verbose
nix run .#compile-context -- --since-hours 24 --max-candidates 250

For complete end-user documentation, see:

docs/index.html

Open it in a browser, or serve the repo directory with any static file server.

Quick start: local stdio MCP

This is the current local-development path. It runs the social-reader MCP from the HermesSocialSummerizer checkout over stdio.

nix run .#collect -- --dry-run --verbose

A successful dry run prints a JSON summary and does not write state or call mark_seen.

To run a real collection:

nix run .#collect -- --verbose

Then compile the cached candidates for the digest LLM prompt:

nix run .#compile-context -- --since-hours 24 --max-candidates 250

Runtime state

Default state directory:

~/.local/state/HermesSocialSummerizer/social-digest/

Override it with:

export SOCIAL_DIGEST_STATE_DIR=/path/to/social-digest-state

State directories are private (0700) and state files are private (0600) because cached candidates contain personal social-feed content.

Normal collector runs prune state files older than 30 days by default. Use:

hermes-social-digest-collect --prune-days 0

to disable pruning, or:

hermes-social-digest-collect --prune-days 14

to choose a different retention window.

MCP connection options

Local stdio mode

export SOCIAL_READER_MCP_TRANSPORT=stdio
export SOCIAL_READER_MCP_COMMAND=/path/to/HermesSocialSummerizer/node_modules/.bin/tsx
export SOCIAL_READER_MCP_ARGS=/path/to/HermesSocialSummerizer/src/server.ts

If an argument contains whitespace, use JSON instead:

export SOCIAL_READER_MCP_ARGS_JSON='["/path/with spaces/server.ts"]'

HTTP mode for a future LAN MCP

Prefer HTTPS, a localhost tunnel, WireGuard, or an authenticated reverse proxy:

export SOCIAL_READER_MCP_TRANSPORT=http
export SOCIAL_READER_MCP_URL=https://social-reader.lan/mcp
export SOCIAL_READER_MCP_HTTP_TOKEN=<token>

Non-local http:// MCP URLs are blocked unless explicitly allowed:

export SOCIAL_READER_MCP_ALLOW_INSECURE_HTTP=true

When SOCIAL_READER_MCP_HTTP_TOKEN is set, the collector sends it as an HTTP bearer token. Even though the MCP is read-only toward social platforms, it can expose private feed data and mark_seen, so do not publish it unauthenticated on an untrusted network.

Home Manager installation

Import the module from the flake and enable it:

{
  inputs.hermes-social-digest-pipeline.url = "path:/path/to/HermesSocialDigestPipeline";

  outputs = { self, nixpkgs, home-manager, hermes-social-digest-pipeline, ... }: {
    homeConfigurations.example = home-manager.lib.homeManagerConfiguration {
      pkgs = nixpkgs.legacyPackages.x86_64-linux;
      modules = [
        hermes-social-digest-pipeline.homeManagerModules.default
        {
          programs.hermesSocialDigestPipeline = {
            enable = true;
            timers.enable = true;
          };
        }
      ];
    };
  };
}

Useful options:

programs.hermesSocialDigestPipeline = {
  enable = true;
  stateDir = "/home/YOUR_USER/.local/state/HermesSocialSummerizer/social-digest";
  environmentFile = "/home/YOUR_USER/.config/hermes-social-digest.env"; # optional, keep secrets outside the Nix store

  mcp.transport = "stdio";
  mcp.command = "/path/to/HermesSocialSummerizer/node_modules/.bin/tsx";
  mcp.args = [ "/path/to/HermesSocialSummerizer/src/server.ts" ];

  # Use this instead of mcp.args if an argument contains spaces.
  mcp.argsJson = null;

  timers.enable = true;
  timers.collectSchedules = [ "10:00" "14:00" "18:00" "22:00" ];
  timers.catchupSchedule = "02:00";
};

The module can also link the bundled Hermes skill into:

~/.hermes/skills/hermes-social-digest-pipeline
  1. Run collector jobs at 10:00, 14:00, 18:00, and 22:00.
  2. Run the smart catch-up collector at 02:00 with --if-previous-hit-limit.
  3. At digest time, run hermes-social-digest-compile-context and feed the JSON output into the Hermes LLM digest prompt.
  4. The collector persists candidates before calling mark_seen, so failed cursor advancement causes duplicates rather than data loss.

Development and verification

Assume the host has only Nix. Enter the dev shell before using Node/npm directly:

nix develop
npm install
npm run typecheck
npm test
npm run build
nix flake check

After any package-lock.json change, update npmDepsHash values in pkgs/hermes-social-digest-pipeline.nix and pkgs/npm-check.nix:

nix run nixpkgs#prefetch-npm-deps package-lock.json