# Troubleshooting

> Known failure modes and recovery: `hermes-okf-install` not in PATH, plugin not listed in `hermes memory setup`, stale model in `config/agent`, missing bundle, Windows filename constraints, and `plugins.enabled` YAML list shape.

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

## Source Files

- `README.md`
- `src/hermes_okf/install_plugin.py`
- `src/hermes_okf/memory_plugin.py`
- `docs/HERMES_PLUGIN.md`
- `CHANGELOG.md`
- `wiki/Troubleshooting.md`

---

---
title: "Troubleshooting"
description: "Known failure modes and recovery: `hermes-okf-install` not in PATH, plugin not listed in `hermes memory setup`, stale model in `config/agent`, missing bundle, Windows filename constraints, and `plugins.enabled` YAML list shape."
---

Hermes OKF surfaces install, discovery, config, and filesystem errors through CLI exit codes, stderr messages, and missing files under `~/.hermes/`. Most failures trace to one of six areas: PyPI script PATH, Hermes filesystem plugin discovery, `config.yaml` shape, bundle initialization, Windows-safe timestamp filenames, or stale `config/agent` metadata. Use the sections below to match a symptom to a verified recovery path.

## Symptom index

| Symptom | Likely cause | First check |
|---------|--------------|-------------|
| `hermes-okf-install: command not found` | Script not on `PATH` | `python -m hermes_okf.install_plugin` |
| `hermes memory setup` omits hermes-okf | Plugin wrapper or `plugins.enabled` shape | `ls ~/.hermes/plugins/hermes-okf/` |
| `hermes okf show config/agent` shows old model | Session not re-initialized after model change | Restart Hermes |
| `Concept not found` / empty bundle | Bundle path missing or uninitialized | `hermes-okf init ~/.hermes/okf_memory` |
| Windows `OSError` on write | Colon in legacy filenames | `pip install --upgrade hermes-okf` |
| Plugin silently ignored | `plugins.enabled` is a string, not a list | Fix YAML list shape |

<Note>
Hermes discovers plugins from `~/.hermes/plugins/` via filesystem layout (`plugin.yaml` + `__init__.py`). The `hermes.memory_providers` pip entry point exists but Hermes does not read it — `hermes-okf-install` is required.
</Note>

## `hermes-okf-install` not in PATH

PyPI registers `hermes-okf-install` as a console script in your active Python environment's `bin/` directory. If that directory is not on `PATH`, the shell reports `command not found` even though the package is installed.

<Steps>
<Step title="Confirm the package is installed">

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

Expected: a version string (for example `0.4.6`). If import fails, run `pip install hermes-okf` first.

</Step>
<Step title="Run install via module or standalone CLI">

<CodeGroup>

```bash title="Module form (always works)"
python -m hermes_okf.install_plugin
```

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

```bash title="Hermes agent venv"
~/.hermes/hermes-agent/venv/bin/python -m hermes_okf.install_plugin
```

</CodeGroup>

</Step>
<Step title="Verify install output">

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

The `Updated` line appears when `~/.hermes/config.yaml` already exists and was modified.

</Step>
</Steps>

<Tabs>
<Tab title="Virtual environment">

```bash
source /path/to/venv/bin/activate
hermes-okf-install
```

</Tab>
<Tab title="Find Python bin">

```bash
which python
# Scripts live in the sibling bin/ directory of that Python
```

</Tab>
<Tab title="uv">

```bash
uv run --python /path/to/python hermes-okf-install
```

</Tab>
</Tabs>

## Plugin not listed in `hermes memory setup`

`hermes memory setup` lists memory providers that Hermes can load. If `hermes-okf` is missing, the plugin wrapper directory or `~/.hermes/config.yaml` is misconfigured.

### Diagnosis

```bash
ls ~/.hermes/plugins/hermes-okf/
```

Expected files:

| File | Purpose |
|------|---------|
| `plugin.yaml` | Plugin metadata and hooks (`on_session_end`) |
| `__init__.py` | Exports `HermesOKFMemoryProvider` |

`hermes-okf-install` writes both files and, when `~/.hermes/config.yaml` exists, sets:

<ParamField body="memory.provider" type="string">
Must be `hermes-okf` for the OKF memory backend.
</ParamField>

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

### Recovery

<Steps>
<Step title="Re-run the installer">

```bash
hermes-okf-install
# or: python -m hermes_okf.install_plugin
```

</Step>
<Step title="Confirm config keys">

```yaml
plugins:
  enabled:
    - hermes-okf

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

</Step>
<Step title="Restart Hermes and re-run setup">

```bash
hermes memory setup
hermes
```

</Step>
</Steps>

<Warning>
Reinstalling only via `pip install hermes-okf` does not create `~/.hermes/plugins/hermes-okf/`. You must run `hermes-okf-install` (or `hermes-okf install-plugin`) after every fresh environment.
</Warning>

## Stale model in `config/agent`

The OKF `config/agent` concept stores the active model in frontmatter. As of v0.3.7, `HermesOKFMemoryProvider.initialize()` reads Hermes `config.yaml` on every session start and overwrites the concept.

Model resolution order:

1. Top-level `model` in `~/.hermes/config.yaml`
2. Fallback: `llm.model`

<Steps>
<Step title="Upgrade and restart">

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

Session start triggers `initialize()`, which calls `write_concept("config/agent", ..., model=hermes_model)`.

</Step>
<Step title="Verify the synced model">

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

The `model:` metadata field should match your Hermes config. Use `--raw` to show only the markdown body.

</Step>
</Steps>

<Info>
Changing the model in `config.yaml` while Hermes is running does not update OKF until the next session. Exit and restart Hermes after model changes.
</Info>

## Missing OKF bundle

Commands that read or write concepts require a valid bundle root containing at least `index.md` and `log.md`. `OKFBundle` auto-creates these when the root path exists but lacks `index.md`; the Hermes plugin also initializes on first session start.

### Symptoms

- `hermes okf show <path>` prints `Concept not found: <path>`
- Standalone CLI reports empty listings or validation errors
- Custom `bundle_path` points to a non-existent directory

### Recovery

<Steps>
<Step title="Initialize the default bundle path">

```bash
hermes-okf init ~/.hermes/okf_memory
```

Expected:

```
Initialised OKF bundle at /home/username/.hermes/okf_memory
```

</Step>
<Step title="Handle non-empty directories">

If the target directory already has files:

```bash
hermes-okf init ~/.hermes/okf_memory --force
```

Without `--force`, init exits with code `1` and:

```
Error: Directory '...' is not empty. Use --force to overwrite.
```

</Step>
<Step title="Point Hermes at the bundle">

Ensure `memory.bundle_path` in `~/.hermes/config.yaml` matches the initialized path, or override with:

```bash
export HERMES_OKF_BUNDLE_PATH=~/.hermes/okf_memory
```

</Step>
<Step title="Validate">

```bash
hermes-okf validate --path ~/.hermes/okf_memory
```

Expected: `Bundle is valid.`

</Step>
</Steps>

## Windows filename constraints

Windows rejects `:` in filenames. Older hermes-okf versions used ISO timestamps with colons (for example `2026-06-15T10:30:00Z`) for session and snapshot IDs. Current releases replace colons with hyphens in the time segment.

| Version behavior | Filename example |
|------------------|------------------|
| Legacy (invalid on Windows) | `2026-06-15T10:30:00Z` |
| v0.2.0+ (safe) | `2026-06-15T10-30-00Z` |

`HermesAgent._now_filename_safe()` formats timestamps as `%Y-%m-%dT%H-%M-%SZ` for session IDs, snapshot paths under `snapshots/`, and related concept filenames.

<Steps>
<Step title="Upgrade">

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

</Step>
<Step title="Use hyphenated paths in CLI commands">

```bash
hermes okf show sessions/2026-06-14T22-14-58Z
```

Not `sessions/2026-06-14T22:14:58Z`.

</Step>
</Steps>

## `plugins.enabled` YAML list shape

`install_plugin._configure_hermes_config()` ensures `plugins.enabled` is a Python list and appends `hermes-okf` if absent. If the key is a JSON-encoded string or scalar, Hermes ignores it and the plugin never activates.

### Correct shape

```yaml
plugins:
  enabled:
    - hermes-okf
```

### Incorrect shapes

<AccordionGroup>
<Accordion title="JSON string (ignored)">

```yaml
plugins:
  enabled: "[\"hermes-okf\"]"
```

Hermes expects a native YAML sequence, not a quoted string.

</Accordion>
<Accordion title="Scalar string (ignored)">

```yaml
plugins:
  enabled: hermes-okf
```

Must be a list even for a single plugin.

</Accordion>
<Accordion title="Missing key (installer adds it)">

If `plugins` or `plugins.enabled` is absent, `hermes-okf-install` creates an empty list and appends `hermes-okf`. Re-run the installer to repair a corrupted shape:

```bash
python -m hermes_okf.install_plugin
```

The installer coerces non-list values to `[]` before appending.

</Accordion>
</AccordionGroup>

## Additional CLI failures

### `hermes okf show` AttributeError on `content`

Versions before v0.3.5 referenced `concept.content` instead of `concept.body`. Upgrade:

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

### Slow memory writes

Increase the hot-memory buffer before flush:

```yaml
memory:
  hot_memory_max: 200
```

Or:

```bash
export HERMES_OKF_HOT_MEMORY_MAX=200
```

Default is `50`.

## Uninstall and clean reinstall

```bash
hermes-okf-uninstall
# or: hermes-okf uninstall-plugin
```

Removes `~/.hermes/plugins/hermes-okf/` but does not delete the OKF bundle. To fully re-register:

```bash
pip install --upgrade hermes-okf
hermes-okf-install
hermes memory setup
```

## Check version and report issues

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

If problems persist after the steps above, open an issue at [github.com/EliaszDev/hermes-okf/issues](https://github.com/EliaszDev/hermes-okf/issues) with your hermes-okf version, OS, and the output of `ls ~/.hermes/plugins/hermes-okf/`.

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
PyPI install targets, entry-point scripts, and PATH recovery when install scripts are not found.
</Card>
<Card title="Install Hermes plugin" href="/install-hermes-plugin">
Full `hermes-okf-install` flow, wrapper layout, and `hermes memory setup` activation.
</Card>
<Card title="Configuration reference" href="/configuration-reference">
`HermesOKFConfig` fields, env overrides, and `memory.*` keys written by install.
</Card>
<Card title="OKF validation reference" href="/okf-validation-reference">
`hermes-okf validate` rules and error output when bundle structure is wrong.
</Card>
</CardGroup>