# Install Hermes plugin

> Register `hermes-okf` via `hermes-okf-install`: wrapper files in `~/.hermes/plugins/hermes-okf/`, auto-updates to `~/.hermes/config.yaml` (`plugins.enabled`, `memory.provider`, `bundle_path`), `hermes memory setup`, and uninstall semantics.

- Repository: EliaszDev/hermes-okf
- GitHub: https://github.com/EliaszDev/hermes-okf
- Human docs: https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02
- Complete Markdown: https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/llms-full.txt

## Source Files

- `src/hermes_okf/install_plugin.py`
- `docs/HERMES_PLUGIN.md`
- `docs/HERMES_USERS.md`
- `src/hermes_okf/memory_plugin.py`
- `src/hermes_okf/plugin.py`
- `pyproject.toml`

---

---
title: "Install Hermes plugin"
description: "Register `hermes-okf` via `hermes-okf-install`: wrapper files in `~/.hermes/plugins/hermes-okf/`, auto-updates to `~/.hermes/config.yaml` (`plugins.enabled`, `memory.provider`, `bundle_path`), `hermes memory setup`, and uninstall semantics."
---

`hermes-okf-install` registers the OKF memory provider with Hermes by writing a filesystem plugin wrapper under `~/.hermes/plugins/hermes-okf/` and, when `~/.hermes/config.yaml` already exists, patching `plugins.enabled`, `memory.provider`, and `memory.bundle_path`. Hermes discovers memory providers from that directory—not from the `hermes.memory_providers` setuptools entry point—so the install command is required even after `pip install hermes-okf`.

<Info>
Hermes also loads the `hermes okf` CLI tree through the separate `hermes_agent.plugins` entry point in `pyproject.toml`. That path does not replace the filesystem wrapper; both surfaces ship together after install.
</Info>

## Prerequisites

| Requirement | Detail |
|-------------|--------|
| Python | `>=3.9` (`requires-python` in package metadata) |
| Package | `pip install hermes-okf` (see [Installation](/installation)) |
| Hermes home | `~/.hermes/` directory (created by Hermes Agent setup) |
| Core dependency | `pyyaml>=6.0` (bundled with `hermes-okf`) |

Install `hermes-okf` into the same Python environment Hermes uses. If Hermes runs inside `~/.hermes/hermes-agent/venv/`, activate that venv before running the install command.

## Install procedure

<Steps>
<Step title="Install the package">

```bash
pip install hermes-okf
```

Verify the version:

```bash
python -c "import hermes_okf; print(hermes_okf.__version__)"
```

</Step>

<Step title="Register the plugin">

<CodeGroup>
```bash title="Entry-point script"
hermes-okf-install
```

```bash title="Standalone CLI subcommand"
hermes-okf install-plugin
```

```bash title="Module invocation (PATH fallback)"
python -m hermes_okf.install_plugin
```
</CodeGroup>

All three invoke the same `install_plugin()` implementation.

</Step>

<Step title="Finish activation">

If `~/.hermes/config.yaml` was updated, stdout includes:

```
Installed hermes-okf plugin to /home/you/.hermes/plugins/hermes-okf
  Updated ~/.hermes/config.yaml
  Run 'hermes memory setup' to finish activation
```

Run the setup wizard to customize memory settings, then start Hermes:

```bash
hermes memory setup
hermes
```

If config was not modified (missing `config.yaml`, or values already correct), stdout omits the update line and still prints `Run 'hermes memory setup' to activate`.

</Step>

<Step title="Verify">

On first session start, the provider initializes the OKF bundle at the configured `bundle_path` (default `~/.hermes/okf_memory`). Confirm the plugin CLI works:

```bash
hermes okf show config/agent
```

</Step>
</Steps>

## Plugin wrapper layout

`install_plugin()` creates `~/.hermes/plugins/hermes-okf/` with two files:

:::files
~/.hermes/plugins/hermes-okf/
├── plugin.yaml      # Hermes manifest (name, version, hooks)
└── __init__.py      # Imports HermesOKFMemoryProvider
:::

### `plugin.yaml`

Written with the installed package version, a description string, and one lifecycle hook:

```yaml
name: hermes-okf
version: 0.4.6
description: "OKF-based memory provider for Hermes agent — structured, persistent, agent-readable knowledge storage."
hooks:
  - on_session_end
```

The `version` field tracks `hermes_okf.__version__` at install time.

### `__init__.py`

```python
from hermes_okf.memory_plugin import HermesOKFMemoryProvider
__all__ = ["HermesOKFMemoryProvider"]
```

Hermes imports this module when loading plugins from `~/.hermes/plugins/`. The actual `MemoryProvider` implementation lives in the pip-installed `hermes_okf.memory_plugin` package; the wrapper only exposes the class for discovery.

## Config auto-updates

When `~/.hermes/config.yaml` exists and PyYAML is importable, `_configure_hermes_config()` loads the file, applies idempotent patches, and rewrites it only if something changed.

| Key | Action |
|-----|--------|
| `plugins.enabled` | Ensures a YAML list; appends `hermes-okf` if absent |
| `memory.provider` | Sets to `hermes-okf` when not already set |
| `memory.bundle_path` | Adds `~/.hermes/okf_memory` only when the key is missing |

<Warning>
`plugins.enabled` must remain a YAML list, not a JSON-encoded string. Hermes ignores string values and the plugin will not load.
</Warning>

<RequestExample>

```yaml title="Resulting ~/.hermes/config.yaml (excerpt)"
plugins:
  enabled:
    - hermes-okf

memory:
  provider: hermes-okf
  bundle_path: ~/.hermes/okf_memory
```

</RequestExample>

Config patching is skipped when:

- `~/.hermes/config.yaml` does not exist yet
- PyYAML cannot be imported (should not happen after `pip install hermes-okf`)

In those cases, create or edit `config.yaml` manually, or run `hermes memory setup` after Hermes creates the file.

### Config keys the installer does not set

`hermes-okf-install` does not write `memory.agent_id`, `auto_snapshot`, `hot_memory_max`, or other provider toggles. Those are applied later by `hermes memory setup` or manual edits. See [Configuration reference](/configuration-reference) for the full field list and resolution order.

## Why a filesystem wrapper is required

Hermes memory-provider discovery scans `~/.hermes/plugins/<name>/` for `plugin.yaml` plus a Python module exporting a `MemoryProvider` subclass. Although `pyproject.toml` registers:

```toml
[project.entry-points."hermes.memory_providers"]
hermes-okf = "hermes_okf.memory_plugin:HermesOKFMemoryProvider"
```

Hermes core does not read that entry point for provider loading. `hermes-okf-install` bridges pip installation to filesystem discovery.

```mermaid
flowchart LR
  subgraph pip["pip install"]
    PKG["hermes_okf package"]
    EP["entry points<br/>(not used for memory)"]
  end
  subgraph install["hermes-okf-install"]
    WRAP["~/.hermes/plugins/hermes-okf/"]
    CFG["~/.hermes/config.yaml"]
  end
  subgraph hermes["Hermes Agent"]
    DISC["Plugin scanner"]
    MP["MemoryProvider load"]
    CLI["hermes okf CLI"]
  end
  PKG --> WRAP
  install --> CFG
  WRAP --> DISC
  DISC --> MP
  PKG --> CLI
```

The `hermes_agent.plugins` entry point (`hermes_okf.plugin:register`) registers `hermes okf` CLI subcommands independently of the memory wrapper.

## `hermes memory setup`

After install, `hermes memory setup` lists `hermes-okf` when the wrapper directory exists and `plugins.enabled` includes the plugin name. The wizard reads `HermesOKFMemoryProvider.get_config_schema()` and prompts for:

<ParamField body="bundle_path" type="string">
Directory where the OKF memory bundle is stored. Default: `~/.hermes/okf_memory`.
</ParamField>

<ParamField body="agent_id" type="string">
Identifier for this agent's memory namespace. Default: `hermes-agent`.
</ParamField>

<ParamField body="auto_snapshot" type="boolean">
Whether to auto-save snapshots on session end. Default: `true`.
</ParamField>

Submitted values are written by `save_config()` into `memory.*` keys in `~/.hermes/config.yaml`, with `memory.provider` forced to `hermes-okf`. At session start, `initialize()` reads those keys (plus the top-level or `llm.model` field for model sync) and constructs `HermesOKFProvider`.

## Activation behavior

On first Hermes session after install:

1. Hermes loads `HermesOKFMemoryProvider` from the wrapper.
2. `initialize(session_id)` reads `memory.*` from `config.yaml`.
3. `on_session_start()` creates session and config concepts in the OKF bundle.
4. The default bundle path `~/.hermes/okf_memory/` receives `index.md`, `log.md`, and Hermes-native subdirectories (`config/`, `sessions/`, `plans/`, `tools/`, `snapshots/`).

Hot Hermes memory (`MEMORY.md`, `USER.md`) and the cold OKF archive coexist; see [Two-memory model](/two-memory-model).

## Uninstall semantics

<CodeGroup>
```bash title="Entry-point script"
hermes-okf-uninstall
```

```bash title="Standalone CLI subcommand"
hermes-okf uninstall-plugin
```
</CodeGroup>

`uninstall_plugin()` removes `~/.hermes/plugins/hermes-okf/` with `shutil.rmtree` when the directory exists.

| Artifact | Uninstall behavior |
|----------|-------------------|
| `~/.hermes/plugins/hermes-okf/` | **Removed** |
| OKF bundle at `memory.bundle_path` | **Preserved** |
| `~/.hermes/config.yaml` entries | **Not reverted** — `plugins.enabled`, `memory.provider`, and `bundle_path` remain until edited manually |
| pip package `hermes-okf` | **Not removed** — run `pip uninstall hermes-okf` separately |

<ResponseExample>

```text title="Success stdout"
Removed hermes-okf plugin from /home/you/.hermes/plugins/hermes-okf
```

```text title="Already absent"
hermes-okf plugin not installed
```

</ResponseExample>

After uninstall, Hermes no longer discovers the provider on startup. To fully deactivate, set `memory.provider` to another value or remove `hermes-okf` from `plugins.enabled`.

## Failure modes

<AccordionGroup>
<Accordion title="hermes-okf-install: command not found">

The script lands in your environment's `bin/`. Use `python -m hermes_okf.install_plugin`, activate the venv, or call the venv Python directly (e.g. `~/.hermes/hermes-agent/venv/bin/python -m hermes_okf.install_plugin`).

</Accordion>

<Accordion title="hermes memory setup does not list hermes-okf">

Confirm the wrapper exists (`ls ~/.hermes/plugins/hermes-okf/` shows `__init__.py` and `plugin.yaml`), re-run `hermes-okf-install`, verify `plugins.enabled` is a YAML list containing `hermes-okf`, and restart Hermes.

</Accordion>

<Accordion title="Config was not auto-updated">

`install_plugin()` only patches an existing `~/.hermes/config.yaml`. Create the file via Hermes setup first, then re-run install, or add the `plugins` and `memory` blocks manually.

</Accordion>
</AccordionGroup>

See [Troubleshooting](/troubleshooting) for PATH recovery, stale model sync, and Windows filename constraints.

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
PyPI install targets, optional extras, entry-point scripts, and Python version constraints.
</Card>
<Card title="Configuration reference" href="/configuration-reference">
`HermesOKFConfig` fields, env overrides, and `memory.*` keys written by install and setup.
</Card>
<Card title="Hermes provider integration" href="/hermes-provider-integration">
Session hooks, `prefetch`/`sync_turn`, and exposed memory tool schemas after activation.
</Card>
<Card title="Hermes CLI reference" href="/hermes-cli-reference">
`hermes okf` subcommands registered through the general plugin entry point.
</Card>
</CardGroup>