# Installation

> PyPI install targets, optional extras (`[rag]`, `[dev]`), entry-point scripts (`hermes-okf`, `hermes-okf-install`, `hermes-okf-uninstall`), Python version constraints, and PATH recovery when install scripts are not found.

- 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

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

---

---
title: "Installation"
description: "PyPI install targets, optional extras (`[rag]`, `[dev]`), entry-point scripts (`hermes-okf`, `hermes-okf-install`, `hermes-okf-uninstall`), Python version constraints, and PATH recovery when install scripts are not found."
---

`hermes-okf` is published on PyPI as a Hatchling-built wheel with a single runtime dependency (`pyyaml>=6.0`). Installing the package registers three console scripts and two Hermes plugin entry points; the core OKF bundle layer works without Hermes, LangChain, or any model provider.

## Requirements

| Constraint | Value |
|------------|-------|
| Python | `>=3.9` (`requires-python` in `pyproject.toml`) |
| Supported classifiers | 3.9, 3.10, 3.11, 3.12, 3.13 |
| Core runtime dependency | `pyyaml>=6.0` |
| Hermes Agent | Optional — required only for the `hermes okf` plugin CLI and `HermesOKFMemoryProvider` |
| Model provider | Not required for install — RAG embeddings are provider-selectable when `[rag]` is installed |

<Note>
The README badge shows Python 3.10+, but the package metadata declares `requires-python = ">=3.9"`. Use 3.9+ for compatibility with the published wheel.
</Note>

## PyPI install targets

<Tabs>
<Tab title="Standard">

Install the core package — OKF bundle I/O, standalone CLI, Python SDK, and Hermes provider classes:

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

</Tab>
<Tab title="With RAG">

Add LangChain + Chroma vector retrieval dependencies:

```bash
pip install hermes-okf[rag]
```

Pulls: `langchain>=0.2.0`, `langchain-community>=0.2.0`, `langchain-chroma>=0.1.0`, `langchain-openai>=0.1.0`.

</Tab>
<Tab title="Development">

Editable install from a cloned repository with lint, test, and type-check tooling:

```bash
git clone https://github.com/EliaszDev/hermes-okf.git
cd hermes-okf
pip install -e ".[dev]"
```

</Tab>
<Tab title="All extras">

Install both `[rag]` and `[dev]` in one command:

```bash
pip install hermes-okf[all]
```

Resolves to `hermes-okf[rag,dev]` per `pyproject.toml`.

</Tab>
</Tabs>

### Optional extras summary

| Extra | Packages pulled | Use when |
|-------|-----------------|----------|
| *(none)* | `pyyaml` only | Standalone CLI, SDK, filesystem OKF bundles |
| `[rag]` | LangChain, Chroma, OpenAI embeddings adapter | Vector retrieval over bundle markdown |
| `[dev]` | pytest, black, ruff, mypy, pre-commit, types-PyYAML | Contributing, CI-parity local checks |
| `[all]` | `[rag]` + `[dev]` | Full feature + dev toolchain |

<Warning>
`[rag]` adds `langchain-openai` as a convenience embedding adapter. Embedding provider selection is runtime-configurable — OKF storage itself remains provider-neutral.
</Warning>

## Console entry points

`pyproject.toml` registers three `[project.scripts]` console commands:

| Script | Target | Purpose |
|--------|--------|---------|
| `hermes-okf` | `hermes_okf.cli:main` | Standalone OKF bundle CLI (`init`, `validate`, `search`, `show`, graph, snapshot, context, …) |
| `hermes-okf-install` | `hermes_okf.install_plugin:install_plugin` | Create `~/.hermes/plugins/hermes-okf/` and auto-update `~/.hermes/config.yaml` |
| `hermes-okf-uninstall` | `hermes_okf.install_plugin:uninstall_plugin` | Remove the plugin wrapper directory (does not delete the OKF bundle) |

### Equivalent invocations

The standalone CLI also exposes plugin management as subcommands — useful when only `hermes-okf` is on PATH:

<CodeGroup>
```bash title="Console scripts"
hermes-okf-install
hermes-okf-uninstall
```

```bash title="CLI subcommands"
hermes-okf install-plugin
hermes-okf uninstall-plugin
```

```bash title="Python module"
python -m hermes_okf.install_plugin
```
</CodeGroup>

<RequestExample>
```bash
hermes-okf --version
```
</RequestExample>

<ResponseExample>
```text
hermes-okf 0.4.6
```
</ResponseExample>

## Hermes plugin entry points

The wheel also declares setuptools entry points for Hermes discovery:

| Group | Name | Target |
|-------|------|--------|
| `hermes.memory_providers` | `hermes-okf` | `hermes_okf.memory_plugin:HermesOKFMemoryProvider` |
| `hermes_agent.plugins` | `hermes-okf` | `hermes_okf.plugin` |

<Info>
Hermes discovers plugins from the filesystem at `~/.hermes/plugins/`, not from `importlib.metadata` entry points. Running `hermes-okf-install` (or `hermes-okf install-plugin`) is required to create the wrapper directory even though entry points are declared in the wheel.
</Info>

## Register the Hermes plugin

After `pip install hermes-okf`, register the plugin wrapper so `hermes memory setup` and `hermes okf` subcommands can find it.

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

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

</Step>
<Step title="Register the plugin wrapper">

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

Creates `~/.hermes/plugins/hermes-okf/plugin.yaml` and `__init__.py`. If `~/.hermes/config.yaml` already exists, the installer appends `hermes-okf` to `plugins.enabled`, sets `memory.provider`, and adds `memory.bundle_path` (`~/.hermes/okf_memory`).

</Step>
<Step title="Verify registration">

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

Expected plugin directory contents: `__init__.py`, `plugin.yaml`.

</Step>
<Step title="Activate in Hermes">

```bash
hermes memory setup   # optional — customize bundle path and agent ID
hermes                # plugin activates on first session start
```

</Step>
</Steps>

<RequestExample>
```bash
hermes-okf-install
```
</RequestExample>

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

If `~/.hermes/config.yaml` does not exist yet, the installer skips config mutation and prints `Run 'hermes memory setup' to activate` instead.

## Uninstall

```bash
hermes-okf-uninstall
```

Removes `~/.hermes/plugins/hermes-okf/` only. Your OKF bundle at `~/.hermes/okf_memory` (or a custom `memory.bundle_path`) is preserved.

## PATH recovery

Console scripts land in the active Python environment's `bin/` directory. If the shell reports `hermes-okf-install: command not found`, the package is likely installed but that directory is not on `PATH`.

<AccordionGroup>
<Accordion title="Run via Python module (most portable)">

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

Works from any environment where `hermes_okf` is importable, regardless of script PATH.

</Accordion>
<Accordion title="Activate the virtual environment">

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

</Accordion>
<Accordion title="Call the venv Python directly">

```bash
/path/to/venv/bin/python -m hermes_okf.install_plugin
```

Common when Hermes ships its own venv (e.g. `~/.hermes/hermes-agent/venv/bin/python`).

</Accordion>
<Accordion title="Use uv">

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

</Accordion>
<Accordion title="Use CLI subcommand instead">

If `hermes-okf` is on PATH but `hermes-okf-install` is not:

```bash
hermes-okf install-plugin
hermes-okf uninstall-plugin
```

</Accordion>
</AccordionGroup>

<Tip>
Run `which python` (or `python -c "import sys; print(sys.executable)"`) to locate the interpreter, then derive the `bin/` directory for script paths.
</Tip>

## Post-install paths

:::files
~/.hermes/
├── config.yaml              # updated by hermes-okf-install (if present)
├── plugins/
│   └── hermes-okf/
│       ├── __init__.py      # imports HermesOKFMemoryProvider
│       └── plugin.yaml      # name, version, hooks
└── okf_memory/              # default bundle_path (created on first session)
:::

## Verify installation

| Check | Command | Expected signal |
|-------|---------|-----------------|
| Package import | `python -c "import hermes_okf; print(hermes_okf.__version__)"` | `0.4.6` (or installed version) |
| Standalone CLI | `hermes-okf --version` | `hermes-okf <version>` |
| Plugin wrapper | `ls ~/.hermes/plugins/hermes-okf/` | `__init__.py`, `plugin.yaml` |
| Config wiring | `grep -A3 'plugins:' ~/.hermes/config.yaml` | `hermes-okf` in `plugins.enabled` list |
| Core-only smoke test | `hermes-okf init /tmp/okf-test && hermes-okf validate --path /tmp/okf-test` | `Initialised OKF bundle…` then `Bundle is valid.` |

## Upgrade

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

Re-run `hermes-okf-install` after upgrading to refresh `plugin.yaml` version and ensure config keys remain current.

## Related pages

<CardGroup>
<Card title="Quickstart" href="/quickstart">
First successful invocation: init a bundle, write a concept, search it, and validate conformance.
</Card>
<Card title="Install Hermes plugin" href="/install-hermes-plugin">
Deep dive on `hermes-okf-install`: wrapper files, config.yaml mutations, and `hermes memory setup`.
</Card>
<Card title="Enable RAG" href="/enable-rag">
Optional vector retrieval after `pip install hermes-okf[rag]`.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
PATH issues, plugin discovery failures, and config shape errors.
</Card>
<Card title="Contributing" href="/contributing">
Dev setup with `pip install -e ".[dev]"`, pytest, and pre-commit hooks.
</Card>
</CardGroup>