# Hermes OKF Documentation

> Reference for the OKF-based filesystem memory system for Hermes agents: standalone CLI, Hermes plugin integration, Python SDK APIs, bundle schema, configuration, and operational workflows.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/llms-full.txt)
- [Complete Markdown alias](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02.md)
- [Human interactive docs](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02)
- [GitHub repository](https://github.com/EliaszDev/hermes-okf)

## Repository

- Repository: EliaszDev/hermes-okf

- Generated: 2026-06-15T19:29:41.862Z
- Updated: 2026-06-15T20:29:43.803Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 21

## Pages

- [Overview](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/01-overview.md): 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.
- [Installation](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/02-installation.md): 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.
- [Quickstart](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/03-quickstart.md): First successful invocation: `pip install hermes-okf`, `hermes-okf init`, write a concept, search it, and verify with `hermes-okf validate` — expected stdout signals and recovery when the bundle path is non-empty.
- [OKF bundle model](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/04-okf-bundle-model.md): Filesystem bundle layout (`index.md`, `log.md`, concept `.md` files), `Concept` dataclass fields, required `type` frontmatter, auto-timestamp behavior, reserved directories, and Hermes-native layout (`config/`, `sessions/`, `plans/`, `tools/`, `snapshots/`).
- [Knowledge graph](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/05-knowledge-graph.md): Implicit directed edges from markdown links, tag clustering, directory hierarchy, BFS traversal, neighbor/backlink queries, and optional NetworkX export via `GraphExtractor`.
- [Two-memory model](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/06-two-memory-model.md): Hot in-process buffer (`HotMemoryBuffer`) vs cold OKF archive: push kinds (`observation`, `decision`, `tool_call`), flush triggers (session end, buffer max, explicit flush), and how Hermes flat memory writes map to typed OKF concepts.
- [Install Hermes plugin](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/07-install-hermes-plugin.md): 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.
- [Standalone CLI workflows](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/08-standalone-cli-workflows.md): Operate an OKF bundle without Hermes: init, validate, list/show concepts, full-text search, log append, graph inspection, snapshot, context build, and session/plan/tool listing with `--path` placement rules.
- [Python agent integration](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/09-python-agent-integration.md): Wire OKF memory into custom agent classes with `HermesMemoryMixin`, `wrap_decision`/`wrap_tool`/`wrap_observation`, `HermesAgent` session/plan/tool lifecycle, snapshots, and `with_context` recall.
- [Hermes provider integration](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/10-hermes-provider-integration.md): Integrate via `HermesOKFProvider` and `HermesOKFMemoryProvider`: session hooks, memory/tool/decision/plan callbacks, `prefetch`/`sync_turn`, exposed tool schemas (`search_memory`, `snapshot_memory`), and model sync from Hermes `config.yaml`.
- [Enable RAG](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/11-enable-rag.md): Optional vector retrieval over OKF bundles: `pip install hermes-okf[rag]`, LangChain `DirectoryLoader` + `MarkdownHeaderTextSplitter`, Chroma persistence, `HERMES_OKF_ENABLE_RAG` config flag, and provider-neutral embedding model selection.
- [Standalone CLI reference](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/12-standalone-cli-reference.md): All `hermes-okf` subcommands, global flags (`--version`, `--path`), per-command arguments (`--force`, `--json`, `--top-k`, `--note`, `--agent-id`, `--category`), exit codes, and stdout/error message shapes.
- [Hermes CLI reference](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/13-hermes-cli-reference.md): `hermes okf` subcommands registered via `cli_extension.py` and `plugin.py`: `search`, `list --type`, `show --raw`, `snapshot --note`, `restore`, default `top_k`, and dispatch through `HermesOKFProvider`.
- [Python SDK reference](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/14-python-sdk-reference.md): Exported public API from `hermes_okf`: `OKFBundle` CRUD/log/graph methods, `Concept` fields, `SearchIndex` query methods, `GraphExtractor` traversal, `HermesMemory` recall APIs, `HermesAgent` plan/snapshot/tool methods, and `get_provider()`.
- [Configuration reference](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/15-configuration-reference.md): `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.
- [OKF validation reference](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/16-okf-validation-reference.md): `OKFValidator` rules: reserved files (`index.md`, `log.md`), frontmatter presence and YAML shape, required `type` field, `validate_file`/`quick_check` helpers, and `hermes-okf validate` error output format.
- [OKF bundle basics](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/17-okf-bundle-basics.md): Copy-paste recipe from `examples/basic_usage.py`: create bundle, write a `Project` concept, read by ID, search by tag, append a `Decision` log entry, and print graph edges with expected field values.
- [Full Hermes agent](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/18-full-hermes-agent.md): End-to-end agent state in an OKF bundle: register tools with JSON schemas, create/complete/archive plans, record decisions, save snapshots, resume sessions — from `examples/full_agent.py` and `examples/hermes_integration.py`.
- [RAG pipeline](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/19-rag-pipeline.md): Complete vector retrieval workflow from `examples/rag_integration.py`: load all bundle markdown, split on headers, embed into Chroma, query with `retriever.invoke`, and swap embedding providers without changing OKF storage.
- [Troubleshooting](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/20-troubleshooting.md): 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.
- [Contributing](https://www.grok-wiki.com/public/docs/eliaszdev-hermes-okf-b71befaafe02/pages/21-contributing.md): Dev setup (`pip install -e ".[dev]"`), test/lint/type-check commands, pre-commit hooks, branch naming, coverage expectations, CI workflow gates, and documentation update requirements for user-facing changes.

## Source Files

- `.github/workflows/ci.yml`
- `.pre-commit-config.yaml`
- `CHANGELOG.md`
- `CONTRIBUTING.md`
- `docs/ARCHITECTURE.md`
- `docs/HERMES_INTEGRATION.md`
- `docs/HERMES_PLUGIN.md`
- `docs/HERMES_USERS.md`
- `examples/basic_usage.py`
- `examples/full_agent.py`
- `examples/hermes_integration.py`
- `examples/rag_integration.py`
- `pyproject.toml`
- `README.md`
- `src/hermes_okf/__init__.py`
- `src/hermes_okf/agent.py`
- `src/hermes_okf/bundle.py`
- `src/hermes_okf/cli_extension.py`
- `src/hermes_okf/cli.py`
- `src/hermes_okf/concept.py`
- `src/hermes_okf/graph.py`
- `src/hermes_okf/hermes_integration.py`
- `src/hermes_okf/hermes.py`
- `src/hermes_okf/install_plugin.py`
- `src/hermes_okf/memory_plugin.py`
- `src/hermes_okf/memory.py`
- `src/hermes_okf/plugin.py`
- `src/hermes_okf/search.py`
- `src/hermes_okf/validators.py`
- `tests/__init__.py`
- `tests/test_agent.py`
- `tests/test_bundle.py`
- `tests/test_graph.py`
- `tests/test_hermes_integration.py`
- `tests/test_hermes.py`
- `tests/test_memory.py`
- `tests/test_search.py`
- `tests/test_validators.py`
- `wiki/Troubleshooting.md`