Hermes OKF Documentation

Pages

1. OverviewExposed 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.
2. InstallationPyPI 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.
3. QuickstartFirst 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.
4. OKF bundle modelFilesystem 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/`).
5. Knowledge graphImplicit directed edges from markdown links, tag clustering, directory hierarchy, BFS traversal, neighbor/backlink queries, and optional NetworkX export via `GraphExtractor`.
6. Two-memory modelHot 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.
7. Install Hermes pluginRegister `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.
8. Standalone CLI workflowsOperate 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.
9. Python agent integrationWire OKF memory into custom agent classes with `HermesMemoryMixin`, `wrap_decision`/`wrap_tool`/`wrap_observation`, `HermesAgent` session/plan/tool lifecycle, snapshots, and `with_context` recall.
10. Hermes provider integrationIntegrate 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`.
11. Enable RAGOptional 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.
12. Standalone CLI referenceAll `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.
13. Hermes CLI reference`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`.
14. Python SDK referenceExported 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()`.
15. 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.
16. OKF validation reference`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.
17. OKF bundle basicsCopy-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.
18. Full Hermes agentEnd-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`.
19. RAG pipelineComplete 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.
20. TroubleshootingKnown 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.
21. ContributingDev 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.