# Configuration reference

> `HermesOKFConfig` fields and defaults, resolution order (env → `~/.hermes/hermes-okf.yaml` → `~/.hermes/config.yaml`), `HERMES_OKF_*` environment variables, `memory.*` keys written by install, and hot-memory/RAG toggles.

- 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

- `src/hermes_okf/hermes_integration.py`
- `src/hermes_okf/install_plugin.py`
- `src/hermes_okf/memory_plugin.py`
- `docs/HERMES_USERS.md`
- `docs/HERMES_PLUGIN.md`

---

---
title: "Configuration reference"
description: "`HermesOKFConfig` fields and defaults, resolution order (env → `~/.hermes/hermes-okf.yaml` → `~/.hermes/config.yaml`), `HERMES_OKF_*` environment variables, `memory.*` keys written by install, and hot-memory/RAG toggles."
---

`HermesOKFConfig` is the central configuration dataclass for the Hermes-OKF memory provider. Values load from environment variables, dedicated YAML files, and Hermes' main `config.yaml`, with different entry points depending on whether you construct `HermesOKFProvider` directly or run through the Hermes plugin adapter.

## Configuration surfaces

hermes-okf reads configuration from three locations under `~/.hermes/`:

| Surface | Path | Used by |
|---------|------|---------|
| Dedicated OKF config | `~/.hermes/hermes-okf.yaml` | `HermesOKFConfig.from_hermes_config()` |
| Hermes main config | `~/.hermes/config.yaml` | Plugin install, `hermes memory setup`, and runtime |
| Environment variables | `HERMES_OKF_*` | `from_hermes_config()` (partial override set) |

<Note>
Two code paths load config differently. `HermesOKFProvider()` calls `HermesOKFConfig.from_hermes_config()`. The Hermes plugin adapter (`HermesOKFMemoryProvider.initialize()`) reads `memory.*` keys from `config.yaml` directly and does not call `from_hermes_config()`.
</Note>

```mermaid
flowchart TD
    subgraph env ["Environment"]
        E1["HERMES_OKF_BUNDLE_PATH"]
        E2["HERMES_OKF_AGENT_ID"]
        E3["HERMES_OKF_AUTO_SNAPSHOT"]
        E4["HERMES_OKF_ENABLE_RAG"]
    end

    subgraph files ["Config files"]
        F1["~/.hermes/hermes-okf.yaml\n(flat dataclass keys)"]
        F2["~/.hermes/config.yaml\nplugins.hermes_okf"]
        F3["~/.hermes/config.yaml\nmemory.*"]
    end

    subgraph loaders ["Loaders"]
        L1["from_hermes_config()"]
        L2["memory_plugin.initialize()"]
    end

    subgraph output ["Runtime"]
        C["HermesOKFConfig"]
        P["HermesOKFProvider"]
    end

    E1 & E2 & E3 & E4 --> L1
    F1 --> L1
    F2 -->|"only if bundle_path unset"| L1
    L1 --> C --> P
    F3 --> L2 --> C
```

## Resolution order (`from_hermes_config`)

`HermesOKFConfig.from_hermes_config()` merges sources in this order; later steps only fill keys not already set (with one exception noted below):

1. **Environment variables** — `HERMES_OKF_*` (see below)
2. **`~/.hermes/hermes-okf.yaml`** — flat keys matching dataclass field names
3. **`~/.hermes/config.yaml` → `plugins.hermes_okf`** — only when `bundle_path` is not already set from steps 1–2
4. **Dataclass defaults**

<Warning>
The `plugins.hermes_okf` block is skipped entirely once `bundle_path` is set by an environment variable or `hermes-okf.yaml`. Other fields from `plugins.hermes_okf` will not merge in that case.
</Warning>

```python
from hermes_okf.hermes_integration import HermesOKFConfig, HermesOKFProvider

# Auto-load from env → hermes-okf.yaml → plugins.hermes_okf → defaults
provider = HermesOKFProvider()

# Or pass an explicit config object
config = HermesOKFConfig(bundle_path="/data/okf", agent_id="my-agent")
provider = HermesOKFProvider(config)
```

## `HermesOKFConfig` fields

All fields are defined on the dataclass in `hermes_integration.py`. Any key present in `hermes-okf.yaml` or `plugins.hermes_okf` that matches a field name is accepted.

| Field | Default | Description |
|-------|---------|-------------|
| `bundle_path` | `~/.hermes/okf_memory` | Filesystem path to the OKF bundle |
| `agent_id` | `hermes` | Agent identifier written into concepts and sessions |
| `model` | `""` (empty) | LLM model string; falls back to `openai/gpt-4o` in `HermesOKFProvider` when empty |
| `auto_snapshot` | `true` | Save snapshots on session start and end |
| `snapshot_on_tool_call` | `false` | Save a snapshot after each tool invocation |
| `log_tool_calls` | `true` | Buffer and flush tool calls to the OKF archive |
| `log_decisions` | `true` | Buffer and flush strategic decisions to the OKF archive |
| `use_hot_memory` | `true` | Declared toggle for the in-process hot buffer (see hot memory section) |
| `hot_memory_max` | `50` | Maximum hot-buffer items before auto-flush |
| `enable_rag` | `false` | RAG feature flag (see RAG section) |
| `rag_model` | `openai/text-embedding-3-small` | Embedding model identifier for Chroma indexing |

<ParamField body="bundle_path" type="string" required={false}>
Directory where the OKF bundle is stored. Created automatically on first provider init if missing.
</ParamField>

<ParamField body="agent_id" type="string" required={false}>
Identifier stamped into session concepts, snapshots, and agent config. The Hermes plugin path defaults to `hermes-agent` when `memory.agent_id` is absent.
</ParamField>

<ParamField body="model" type="string" required={false}>
Model string passed to `HermesAgent`. The plugin adapter reads Hermes' top-level `model` or `llm.model` from `config.yaml` and writes it to the `config/agent` concept.
</ParamField>

<ParamField body="auto_snapshot" type="boolean" required={false}>
When `true`, calls `agent.snapshot()` at session start and end, and after plan completion.
</ParamField>

<ParamField body="snapshot_on_tool_call" type="boolean" required={false}>
When `true`, saves a snapshot on every `on_tool_call` hook.
</ParamField>

<ParamField body="log_tool_calls" type="boolean" required={false}>
When `true`, pushes tool invocations into the hot buffer and lazy-registers tools in the OKF registry.
</ParamField>

<ParamField body="log_decisions" type="boolean" required={false}>
When `true`, pushes decision events into the hot buffer for cold-archive flush.
</ParamField>

<ParamField body="use_hot_memory" type="boolean" required={false}>
Configuration field for the two-memory model. The provider always instantiates `HotMemoryBuffer` regardless of this value.
</ParamField>

<ParamField body="hot_memory_max" type="integer" required={false}>
Maximum items in `HotMemoryBuffer` before `_maybe_flush()` writes all buffered items to the cold OKF archive.
</ParamField>

<ParamField body="enable_rag" type="boolean" required={false}>
Feature flag stored in config. RAG retrieval is invoked explicitly via `HermesOKFProvider.rag_search()` rather than auto-routed from this flag.
</ParamField>

<ParamField body="rag_model" type="string" required={false}>
Embedding model passed to `OpenAIEmbeddings` when building or querying the Chroma index. Swap providers by changing this string and your embedding client credentials.
</ParamField>

## `~/.hermes/hermes-okf.yaml`

Place flat dataclass keys at the file root (not nested under `memory:`):

```yaml
bundle_path: ~/.hermes/okf_memory
agent_id: hermes-alpha
auto_snapshot: true
log_tool_calls: true
log_decisions: true
hot_memory_max: 100
enable_rag: false
rag_model: openai/text-embedding-3-small
```

Keys must match `HermesOKFConfig` field names exactly. Unknown keys are ignored. Parse errors fall back silently to defaults.

## `~/.hermes/config.yaml` — `memory.*` keys

When Hermes runs the plugin, `HermesOKFMemoryProvider.initialize()` reads these keys from the `memory` section:

| Key | Default (plugin path) | Description |
|-----|----------------------|-------------|
| `provider` | set by install to `hermes-okf` | Selects the memory backend |
| `bundle_path` | `~/.hermes/okf_memory` | OKF bundle directory |
| `agent_id` | `hermes-agent` | Agent identifier |
| `auto_snapshot` | `true` | Session snapshot toggle |
| `log_tool_calls` | `true` | Tool-call logging toggle |
| `hot_memory_max` | `50` | Hot-buffer capacity |

`hermes memory setup` exposes `bundle_path`, `agent_id`, and `auto_snapshot` via `get_config_schema()`. `save_config()` writes those values back under `memory.*`.

### Keys written by `hermes-okf-install`

Running `hermes-okf-install` (or `python -m hermes_okf.install_plugin`) modifies `~/.hermes/config.yaml` when the file already exists:

```yaml
plugins:
  enabled:
    - hermes-okf          # appended if missing

memory:
  provider: hermes-okf    # set if not already
  bundle_path: ~/.hermes/okf_memory  # set if key absent
```

<Info>
Install does not write `agent_id`, `auto_snapshot`, `log_tool_calls`, or `hot_memory_max`. Configure those via `hermes memory setup` or manual YAML edits.
</Info>

### `plugins.hermes_okf` block

`from_hermes_config()` can also read a `plugins.hermes_okf` map with the same flat field names as the dataclass. This block is consulted only when `bundle_path` has not been resolved from environment variables or `hermes-okf.yaml`.

## Environment variables

Only four `HERMES_OKF_*` variables are parsed by `from_hermes_config()`:

| Variable | Maps to | Accepted truthy values |
|----------|---------|------------------------|
| `HERMES_OKF_BUNDLE_PATH` | `bundle_path` | any non-empty string |
| `HERMES_OKF_AGENT_ID` | `agent_id` | any non-empty string |
| `HERMES_OKF_AUTO_SNAPSHOT` | `auto_snapshot` | `1`, `true`, `yes` (case-insensitive) |
| `HERMES_OKF_ENABLE_RAG` | `enable_rag` | `1`, `true`, `yes` (case-insensitive) |

<RequestExample>

```bash
export HERMES_OKF_BUNDLE_PATH=/data/my_okf
export HERMES_OKF_AGENT_ID=deploy-bot
export HERMES_OKF_AUTO_SNAPSHOT=false
export HERMES_OKF_ENABLE_RAG=true
```

</RequestExample>

<Warning>
`HERMES_OKF_HOT_MEMORY_MAX` is not read by `from_hermes_config()`. Set `hot_memory_max` in `memory.*` (plugin path) or `hermes-okf.yaml` instead.
</Warning>

Environment variables take highest precedence in `from_hermes_config()` and are not re-read by the plugin adapter's `initialize()` method.

## Hot memory configuration

The hot layer is `HotMemoryBuffer`, an in-process list that batches fast writes before flushing to the cold OKF archive.

**Flush triggers:**

- Session end (`on_session_end`)
- Plan completion (`on_plan_complete`)
- Buffer reaches `hot_memory_max` items (`_maybe_flush`)
- Explicit flush via `snapshot()`, `restore()`, or `_flush_hot()`

**Buffered item kinds:**

| `_kind` value | Cold-archive target |
|---------------|---------------------|
| `observation` | `record_observation()` |
| `decision` | `record_decision()` |
| `tool_call` | `record_tool_call()` |

Hermes `memory` writes (`target="memory"`) push observations into the hot buffer. `target="user"` writes bypass the buffer and go directly to a `UserProfile` concept.

<Tabs>
<Tab title="YAML (Hermes plugin)">

```yaml
memory:
  provider: hermes-okf
  hot_memory_max: 200
```

</Tab>
<Tab title="hermes-okf.yaml">

```yaml
hot_memory_max: 200
log_tool_calls: true
log_decisions: true
```

</Tab>
<Tab title="Python SDK">

```python
from hermes_okf.hermes_integration import HermesOKFConfig, HermesOKFProvider

config = HermesOKFConfig(
    bundle_path="/tmp/okf",
    hot_memory_max=200,
    log_tool_calls=True,
    log_decisions=True,
)
provider = HermesOKFProvider(config)
```

</Tab>
</Tabs>

## RAG configuration

RAG is optional and requires the `[rag]` extra (`pip install hermes-okf[rag]`). Vector storage persists under `{bundle_path}/.chroma`.

| Control | Purpose |
|---------|---------|
| `enable_rag` / `HERMES_OKF_ENABLE_RAG` | Stored feature flag; does not auto-enable retrieval in provider hooks |
| `rag_model` | Embedding model for `OpenAIEmbeddings` in `rag_search()` and `_build_rag_index()` |
| `HermesOKFProvider.rag_search()` | Explicit semantic search entry point |

```python
provider = HermesOKFProvider(
    HermesOKFConfig(
        bundle_path="~/.hermes/okf_memory",
        enable_rag=True,
        rag_model="openai/text-embedding-3-small",
    )
)
results = provider.rag_search("deployment decisions", top_k=5)
```

Embedding provider selection is configuration-driven: change `rag_model` and swap the LangChain embedding client to use any provider your credentials support. OKF markdown storage is unchanged.

## Model sync from Hermes

When the plugin initializes, it reads the Hermes model from `config.yaml`:

```yaml
model: anthropic/claude-sonnet-4   # top-level
# or
llm:
  model: anthropic/claude-sonnet-4
```

The resolved model is assigned to `config.model` and written to the `config/agent` OKF concept so the bundle reflects the live Hermes configuration.

## Quick reference: which file wins?

| Scenario | Primary source |
|----------|---------------|
| Standalone `HermesOKFProvider()` | env → `hermes-okf.yaml` → `plugins.hermes_okf` → defaults |
| Hermes Agent session (plugin) | `config.yaml` `memory.*` at `initialize()` |
| After `hermes-okf-install` | `memory.provider`, `memory.bundle_path`, `plugins.enabled` |
| After `hermes memory setup` | `memory.bundle_path`, `memory.agent_id`, `memory.auto_snapshot` |
| Override bundle path at runtime | `HERMES_OKF_BUNDLE_PATH` (highest in `from_hermes_config`) |

## Related pages

<CardGroup>
<Card title="Install Hermes plugin" href="/install-hermes-plugin">
How `hermes-okf-install` writes `plugins.enabled` and `memory.*` keys.
</Card>
<Card title="Two-memory model" href="/two-memory-model">
Hot buffer kinds, flush triggers, and Hermes-to-OKF mapping.
</Card>
<Card title="Enable RAG" href="/enable-rag">
Optional vector retrieval setup with Chroma and LangChain.
</Card>
<Card title="Hermes provider integration" href="/hermes-provider-integration">
`HermesOKFProvider` hooks, `prefetch`, and model sync behavior.
</Card>
<Card title="Troubleshooting" href="/troubleshooting">
Recovery for stale config, missing bundle paths, and `plugins.enabled` shape errors.
</Card>
</CardGroup>