Metadata-Version: 2.4
Name: forge-hermes-plugin
Version: 0.2.61
Summary: Structured memory plugin for project management and mental health tracking in Hermes
Author: Forge
License-Expression: MIT
Project-URL: Homepage, https://github.com/albertbuchard/forge/tree/main/plugins/forge-hermes
Project-URL: Repository, https://github.com/albertbuchard/forge
Project-URL: Issues, https://github.com/albertbuchard/forge/issues
Keywords: forge,hermes,agent,plugin,productivity
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Forge Hermes Plugin

Hermes plugin for Forge.

This plugin follows the Hermes plugin guide directly:

- a Python package with a `hermes_agent.plugins` entry point for pip discovery
- a Hermes plugin manifest and registration module that expose Forge to Hermes
- bundled plugin skills that prefer native Hermes plugin-skill registration
- bundled Forge runtime assets so Hermes can start Forge safely without repo-only runtime imports

It exposes the same curated Forge contract as the OpenClaw adapter, but through Hermes' Python plugin system.
It also bundles a Psyche interview playbook pack so Hermes can explore values,
patterns, behaviors, beliefs, modes, and trigger reports with active listening before
persisting them.
It now also exposes the first-class Preferences surface, including the
summary-first workspace read, the comparison-game starter, editable concept
lists, contextual profile slices, direct signals, and exact score overrides.
It also exposes Forge's wiki memory surface plus the sleep and sports review
models, so Hermes can inspect recent nights, review workout context, enrich
health sessions with reflective links, and work with SQLite-backed wiki pages.
It also exposes a dedicated `forge_get_doctor` diagnostic tool for runtime and
config-file health checks.
It also warms a session-scoped Forge overview through Hermes' documented
`on_session_start` hook and injects that cached summary through `pre_llm_call`
on every turn, so a fresh `/new` discussion starts with current operator
context and later turns keep the same cached Forge grounding without
refetching Forge again.

Forge PM behavior Hermes should understand is:

- `Goal -> Strategy -> Project -> Strategy -> Issue -> Task -> Subtask`
- one mixed board for `project | issue | task | subtask`
- one compact hierarchy view with shared search and filters
- hierarchy-aware linking flows that can select or create goals, projects, issues, and parent work items
- shared `executionMode` + `acceptanceCriteria` support on issues and tasks
- `completionReport = { modifiedFiles[], workSummary, linkedGitRefIds[] }`
- direct commits to `main` by default

## Install

Use the published package when you want Hermes to load the released Forge plugin:

```bash
~/.hermes/hermes-agent/venv/bin/python -m ensurepip --upgrade
~/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade pip
~/.hermes/hermes-agent/venv/bin/python -m pip uninstall -y forge-hermes-plugin
~/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade forge-hermes-plugin
```

Use the local editable install when you are developing Forge from this repo:

```bash
~/.hermes/hermes-agent/venv/bin/python -m ensurepip --upgrade
~/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade pip
~/.hermes/hermes-agent/venv/bin/python -m pip uninstall -y forge-hermes-plugin
~/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade --editable ./plugins/forge-hermes
```

That installs the package into Hermes' own Python environment through `pip`, keeps the
live code pointed at this local dev folder, creates
`~/.hermes/forge/config.json` automatically on first plugin load if it is missing.
When `FORGE_DATA_ROOT` or `dataRoot` is set, that explicit value decides where
Forge stores `forge.sqlite`; use the same value for Hermes, OpenClaw, Codex, and
the browser when they should share one local runtime. If no explicit value is
set, the local default is `~/.forge`.

The Forge web app also exposes these controls in `Settings -> Data`. Users can
see the live data folder, move current data, adopt an existing Forge data
folder, create a manual backup, enable automatic backups, and choose how many
days of automatic backups Forge should keep. Automatic retention only removes
automatic backups; manual and safety backups are kept.

Use `~/.hermes/hermes-agent/venv/bin/python` so the package lands in the Python
environment Hermes actually runs and Hermes can discover Forge through the package
entry point on the next startup.

If you want to install from the local repo without editable mode:

```bash
~/.hermes/hermes-agent/venv/bin/python -m ensurepip --upgrade
~/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade pip
~/.hermes/hermes-agent/venv/bin/python -m pip uninstall -y forge-hermes-plugin
~/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade ./plugins/forge-hermes
```

## Runtime behavior

- defaults to `FORGE_ORIGIN=http://127.0.0.1` and `FORGE_PORT=4317`
- defaults `FORGE_ACTOR_LABEL` to blank and inherits the trusted local operator label when available
- defaults `FORGE_DATA_ROOT` to `~/.forge` unless the user sets `FORGE_DATA_ROOT` or `dataRoot`
- supports `FORGE_API_TOKEN` for remote or explicitly scoped access
- supports `FORGE_DATA_ROOT` when you want Forge to use a specific local data folder
- when Forge is local and not already running, the plugin calls the repo's tested Forge local-runtime bootstrap helper instead of maintaining a separate startup implementation
- the stable local web entrypoint stays `http://127.0.0.1:4317/forge/`; if the shared runtime is in dev mode it can supervise the Vite frontend behind that same URL instead of exposing `3027` directly
- when port `4317` is busy and not explicitly pinned, the shared runtime helper can move Forge to the next free localhost port and remember that preferred port
- if another Forge runtime is already serving the wrong storage root, startup fails loudly instead of attaching to the wrong database
- Forge fetches one compact operator summary per Hermes session, caches it for
  that session, reinjects that same cached summary on each turn, and clears it
  when the session is finalized or reset

## Doctor And forge.json

Hermes now reaches the same doctor surface through `forge_get_doctor`.

That doctor output covers:

- backend health and watchdog status
- the resolved Forge storage root, data directory, and database path
- `forge.json` validity, sync state, parse errors, and applied override keys
- onboarding and overview reachability from the Hermes adapter

Forge also maintains a runtime settings mirror at `<FORGE_DATA_ROOT>/forge.json`.
This is not the same file as the Hermes plugin config at `~/.hermes/forge/config.json`.

The split is intentional:

- `~/.hermes/forge/config.json` configures the Hermes adapter itself
- `<FORGE_DATA_ROOT>/forge.json` configures Forge runtime settings and mirrors the effective state

Behavior:

- Forge exports `forge.json` on startup when it is missing
- valid settings in `forge.json` override persisted DB values
- after applying precedence, Forge rewrites the file as a full snapshot
- UI and API settings changes also rewrite `forge.json`, so the file, DB, and UI stay aligned

## Shared Multi-user Forge

This plugin can participate in one shared Forge system with OpenClaw, Codex,
and the browser UI, but the runtime target needs to be aligned deliberately.

If you want Hermes to share the same Forge users and records:

- use the same `FORGE_ORIGIN`
- use the same `FORGE_PORT`
- set the same explicit `FORGE_DATA_ROOT` or `dataRoot` for every adapter that should use a custom local database, or leave every adapter on the default `~/.forge`
- before changing or merging data roots, back up every candidate Forge database and verify which database the live runtime has opened
- leave `FORGE_ACTOR_LABEL` blank when Hermes should inherit the local operator automatically
- set `FORGE_ACTOR_LABEL` only when Hermes or a spawned sub-agent should act as a specific bot

Forge's ownership model is explicit:

- users are typed as `human` or `bot`
- entity writes should set `userId` intentionally
- reads can use one `userId` or several `userIds`
- cross-user links are allowed

That is what lets a Hermes bot own its own tasks or strategies while still
supporting human-owned goals and projects in the same Forge runtime. Forge now
also separates runtime bridge identity from acting user identity, so the live
session list can show one stable Hermes bridge while writes still attribute to
the effective human or bot actor.

## Preferences Workspace

Forge Preferences is a first-class domain, not a hidden recommendation layer.
Hermes can now:

- read the full workspace with `forge_get_preferences_workspace`
- start the comparison flow with `forge_start_preferences_game`
- create, update, and delete `preference_catalog`, `preference_catalog_item`,
  `preference_context`, and `preference_item` through the same batch entity
  routes as other Forge entities
- merge contextual profiles with the dedicated action route when two contexts
  should collapse into one
- enqueue Forge entities directly into a preference domain
- submit pairwise judgments and direct signals
- override inferred scores when the user wants an explicit correction

This matches the current Forge UI:

- the `/preferences` landing page leads with what Forge already knows
- the comparison flow is a modal "Start the game" experience
- Forge-native domains can auto-seed from real Forge entities
- broader taste domains can seed from editable concept libraries such as food,
  activities, places, countries, fashion, people, media, and tools

## Wiki, Sleep, And Sports

Hermes now ships the same explicit coverage for these newer Forge surfaces:

- Wiki: `forge_get_wiki_settings`, `forge_list_wiki_pages`, `forge_get_wiki_page`, `forge_search_wiki`, `forge_upsert_wiki_page`, `forge_get_wiki_health`, `forge_sync_wiki_vault`, `forge_reindex_wiki_embeddings`, `forge_ingest_wiki_source`
- Sleep: `forge_get_sleep_overview`, `forge_update_sleep_session`
- Sports: `forge_get_sports_overview`, `forge_update_workout_session`

This matters because sleep and sports are not generic notes or tasks, and wiki
pages are not normal batch entities. Hermes uses the dedicated routes so the
health surfaces, SQLite page rows, backlinks, and metadata index stay aligned.

## Environment variables

- `FORGE_ORIGIN`
- `FORGE_PORT`
- `FORGE_API_TOKEN`
- `FORGE_ACTOR_LABEL`
- `FORGE_TIMEOUT_MS`
- `FORGE_DATA_ROOT`

Managed tokens can now carry both a bootstrap budget and a default read scope.
That means Hermes may start with an already-scoped Forge view for one human, one
bot, or a bounded collaboration slice even before it passes explicit `userIds`
on a read call. Hermes can still narrow further per request, but it should not
assume every token sees the whole workspace by default.

## Bundled Skills

Forge Hermes now follows the newer Hermes plugin-skill recommendation when the
runtime supports it:

- first try `ctx.register_skill(...)` for bundled plugin skills
- fall back to the legacy `~/.hermes/skills/forge-hermes/` copy pattern only on
  older Hermes builds that do not expose `register_skill` yet

That keeps installs smooth on the current Hermes release while aligning the
plugin with the newer documentation.

## Notes

- the recommended install path is now pip-based Hermes entry-point discovery, not the old folder-plugin symlink
- edit `~/.hermes/forge/config.json` if you want to move the shared data root or pin a different local port
- bundled skills prefer native plugin registration and only copy into `~/.hermes/skills/forge-hermes/` as a compatibility fallback on older Hermes runtimes
