# Overview

> Exposed surfaces (standalone CLI, Hermes plugin, Python SDK), runtime assumptions (filesystem OKF bundles, pyyaml-only core), and the shortest path from install to first memory write.

- 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

- `README.md`
- `pyproject.toml`
- `src/hermes_okf/__init__.py`
- `docs/ARCHITECTURE.md`
- `src/hermes_okf/bundle.py`

---

---
title: "Overview"
description: "Exposed surfaces (standalone CLI, Hermes plugin, Python SDK), runtime assumptions (filesystem OKF bundles, pyyaml-only core), and the shortest path from install to first memory write."
---

`hermes-okf` (v0.4.6) is a filesystem-backed memory layer for Hermes agents and standalone OKF bundles. Persistence is markdown files with YAML frontmatter on disk; the core runtime depends only on `pyyaml`. Three integration surfaces—`hermes-okf` CLI, Hermes plugin hooks, and the `hermes_okf` Python package—share `OKFBundle` as the write path into cold storage.

## Exposed surfaces

| Surface | Entry | Primary use |
|---------|-------|-------------|
| Standalone CLI | `hermes-okf` | Operate an OKF bundle without Hermes: init, validate, search, graph, snapshots |
| Hermes plugin | `hermes-okf-install`, `hermes okf`, `HermesOKFMemoryProvider` | Native Hermes memory provider with session hooks and `hermes okf` subcommands |
| Python SDK | `from hermes_okf import OKFBundle, HermesAgent, …` | Programmatic CRUD, agent lifecycle, provider wiring in custom code |

### Standalone CLI

The `hermes-okf` script maps to `hermes_okf.cli:main`. Global flags include `--version` and per-command `--path` (default `.`).

Representative subcommands:

| Command | Role |
|---------|------|
| `init` | Create a conformant bundle (`index.md`, `log.md`, seeded subdirectories) |
| `validate` | Run `OKFValidator` over the bundle |
| `list`, `show`, `search` | Inspect and query concepts |
| `log`, `log-append` | Read or append chronological entries to `log.md` |
| `graph-edges`, `graph-neighbors` | Traverse implicit link graph |
| `snapshot`, `context` | Checkpoint and build LLM context |
| `sessions`, `plans`, `tools` | List Hermes-native bundle directories |

`init` refuses non-empty directories unless `--force` is passed.

### Hermes plugin

Installation registers two pip entry points:

- `hermes.memory_providers` → `HermesOKFMemoryProvider` (implements Hermes `MemoryProvider` ABC)
- `hermes_agent.plugins` → `hermes_okf.plugin.register` (registers `hermes okf` CLI tree)

`hermes-okf-install` creates `~/.hermes/plugins/hermes-okf/` (`plugin.yaml`, wrapper files) and, when `~/.hermes/config.yaml` exists, sets `plugins.enabled`, `memory.provider: hermes-okf`, and `memory.bundle_path: ~/.hermes/okf_memory`. `hermes-okf-uninstall` removes the plugin wrapper only; the OKF bundle is preserved.

Hermes CLI commands registered via `cli_extension.py`:

```bash
hermes okf search <query> [--top-k N]
hermes okf list [--type TYPE]
hermes okf show <path> [--raw]
hermes okf snapshot [--note NOTE]
hermes okf restore
```

### Python SDK

Public exports from `hermes_okf`:

| Symbol | Responsibility |
|--------|----------------|
| `OKFBundle` | Concept CRUD, logging, graph edge extraction |
| `Concept` | Dataclass for a single `.md` concept |
| `SearchIndex` | Full-text search over bundle content |
| `GraphExtractor` | Link traversal, tag clustering, optional NetworkX export |
| `OKFValidator` | OKF conformance checks |
| `HermesMemory` | Session, decision, observation, tool-call semantics |
| `HermesAgent` | Full agent state stored in an OKF bundle |
| `HermesOKFProvider`, `get_provider()` | Universal Hermes memory provider |

Decorator-based integration (`HermesMemoryMixin` in `agent.py`) wraps decisions, tools, and observations for custom agent classes.

## Runtime assumptions

### Filesystem OKF bundles

An OKF bundle is a directory tree of `.md` files. `OKFBundle.__init__` creates the root if missing and seeds a minimal conformant layout when `index.md` is absent:

- Reserved files: `index.md` (directory index), `log.md` (chronological agent log)
- Default subdirectories: `projects/`, `decisions/`, `context/` (each with an `index.md` stub)
- Concept files: relative path as ID (e.g. `projects/my_project.md`), YAML frontmatter + markdown body
- Required OKF field: `type` in frontmatter (enforced by `OKFValidator`, not at write time)
- Auto-timestamp: `write_concept` adds `timestamp` in UTC ISO 8601 when omitted
- Implicit graph: markdown links `[label](path.md)` become directed edges

Hermes-extended bundles add `config/`, `sessions/`, `plans/`, `tools/`, and `snapshots/` as the agent runs.

<Info>
No database, vector store, or cloud service is required for core operation. Optional RAG (`pip install hermes-okf[rag]`) layers LangChain + ChromaDB on top of the same filesystem bundle without changing storage format.
</Info>

### pyyaml-only core

`pyproject.toml` declares a single runtime dependency: `pyyaml>=6.0`. Python `>=3.9` is supported. Optional extras:

| Extra | Packages | Purpose |
|-------|----------|---------|
| `[rag]` | langchain, langchain-community, langchain-chroma, langchain-openai | Vector retrieval over bundle markdown |
| `[dev]` | pytest, black, ruff, mypy, pre-commit | Development and CI |

Fuzzy search (`rapidfuzz`) and NetworkX graph export are optional runtime additions, not core dependencies.

### Two-memory model (Hermes path)

When `HermesOKFProvider` runs with `use_hot_memory: true` (default), writes land in `HotMemoryBuffer` first and flush to the OKF cold archive on session end, buffer reaching `hot_memory_max` (default 50), or explicit `flush()`. Push kinds: `observation`, `decision`, `tool_call`. Direct SDK/CLI writes bypass the hot buffer and hit `OKFBundle.write_concept` immediately.

## Architecture

```mermaid
flowchart TB
    subgraph human["Human interface"]
        HC["hermes okf search|list|show|snapshot|restore"]
        SC["hermes-okf init|validate|search|show|…"]
        PI["hermes-okf-install / hermes-okf-uninstall"]
    end

    subgraph plugin["Hermes plugin layer"]
        MP["HermesOKFMemoryProvider"]
        PL["plugin.py / cli_extension.py"]
        INS["install_plugin.py"]
    end

    subgraph provider["Universal provider"]
        HP["HermesOKFProvider"]
        HA["HermesAgent / HermesMemoryMixin"]
        HM["HotMemoryBuffer"]
    end

    subgraph core["Core OKF layer"]
        OB["OKFBundle"]
        CV["Concept"]
        GE["GraphExtractor"]
        SI["SearchIndex"]
        OV["OKFValidator"]
    end

    subgraph persist["Persistence"]
        FS["Filesystem: markdown + YAML frontmatter"]
    end

    HC --> PL
    SC --> OB
    PI --> INS
    MP --> HP
    PL --> HP
    HP --> HA
    HP --> HM
    HA --> OB
    HM -->|"flush"| OB
    OB --> CV
    OB --> GE
    OB --> SI
    OB --> OV
    OB --> FS
```

Configuration resolves in order: `HERMES_OKF_*` environment variables → `~/.hermes/hermes-okf.yaml` → `~/.hermes/config.yaml` → defaults (`bundle_path: ~/.hermes/okf_memory`, `agent_id: hermes`).

## Shortest path to first memory write

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

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

Installs `hermes-okf`, `hermes-okf-install`, and `hermes-okf-uninstall` entry-point scripts.

</Step>
<Step title="Create a bundle">

```bash
hermes-okf init ./knowledge
```

<ResponseExample>

```text
Initialised OKF bundle at /path/to/knowledge
```

</ResponseExample>

`OKFBundle("./knowledge")` in Python performs the same seeding if the directory is new.

</Step>
<Step title="Write a concept">

<CodeGroup>

```python Python SDK
from hermes_okf import OKFBundle

bundle = OKFBundle("./knowledge")
bundle.write_concept(
    "projects/my_project",
    body="# My Project\n\nFirst memory entry.",
    type="Project",
    title="My Project",
    tags=["first-write"],
)
```

```bash CLI log append
hermes-okf log-append --path ./knowledge \
  "First decision recorded" --category Decision
```

</CodeGroup>

`write_concept` persists a `.md` file with YAML frontmatter and auto-adds `timestamp`. `log-append` appends a timestamped line to `log.md`.

</Step>
<Step title="Verify the write">

```bash
hermes-okf show --path ./knowledge projects/my_project
hermes-okf validate --path ./knowledge
```

Expected validation output: `Bundle is valid.`

</Step>
</Steps>

### Hermes plugin path (automatic writes)

For Hermes users, the install-to-write path is two commands plus a session start:

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

On first session, `HermesOKFMemoryProvider.initialize()` creates the bundle at `~/.hermes/okf_memory` (or `memory.bundle_path` from config). Memory writes from Hermes (`on_memory_write`, `on_tool_call`, `on_decision`) flow through `HermesOKFProvider` into typed OKF concepts. Inspect results with `hermes okf list` or `hermes okf show sessions/<session-id>`.

<Tip>
Run `hermes memory setup` after install to customize `bundle_path` and agent ID. The install script pre-populates `plugins.enabled` so the provider appears in the wizard.
</Tip>

## Surface selection

| Goal | Start here |
|------|------------|
| Manage a knowledge bundle without Hermes | Standalone CLI + `OKFBundle` |
| Drop-in Hermes agent memory | `hermes-okf-install` + `HermesOKFMemoryProvider` |
| Custom Python agent with decorators | `HermesMemoryMixin` or `HermesAgent` |
| Vector search over existing concepts | `[rag]` extra + `HERMES_OKF_ENABLE_RAG` |

<Warning>
If `hermes-okf-install` is not found, the script may be outside `PATH`. Run `python -m hermes_okf.install_plugin` from the same environment where `pip install` ran.
</Warning>

## Next

<CardGroup>
<Card title="Installation" href="/installation">
PyPI targets, optional extras, entry-point scripts, Python version constraints, and PATH recovery.
</Card>
<Card title="Quickstart" href="/quickstart">
End-to-end standalone flow: init, write, search, validate, and non-empty directory recovery.
</Card>
<Card title="OKF bundle model" href="/okf-bundle-model">
Filesystem layout, `Concept` fields, frontmatter rules, and Hermes-native directories.
</Card>
<Card title="Install Hermes plugin" href="/install-hermes-plugin">
`hermes-okf-install` wrapper creation, config.yaml updates, and uninstall semantics.
</Card>
<Card title="Two-memory model" href="/two-memory-model">
Hot buffer vs cold archive, flush triggers, and Hermes flat-memory mapping.
</Card>
<Card title="Python SDK reference" href="/python-sdk-reference">
Full public API: `OKFBundle`, `SearchIndex`, `GraphExtractor`, `HermesAgent`, `get_provider()`.
</Card>
</CardGroup>