Hermes + OKF: a knowledge folder your agent reads before it answers

The Stack

Tested Against

Prerequisites

• Hermes Agent installed
• A provider/API key to actually run the agent

Steps

1. 1

   Write the bundle, point Hermes at it in SOUL.md, and validate

   Make a knowledge/ folder with one OKF note per thing you keep re-explaining (each with a non-empty type) and an index.md listing them. Then add a one-line house rule to SOUL.md (Hermes' slot-1 system-prompt file in ~/.hermes/) telling it to read knowledge/index.md first and follow the links. CI checks the bundle conforms and that SOUL.md references the index.

   mkdir -p knowledge/notes
   cat > knowledge/index.md <<'MD'
   # Projects
   * [Recipe app](notes/recipe-app.md) - Solo weekend project, no accounts.
   
   # Preferences
   * [Writing voice](notes/writing-voice.md) - How I like copy written.
   MD
   cat > knowledge/notes/recipe-app.md <<'MD'
   ---
   type: Project
   title: Side project, the recipe app
   description: What it is and the decisions I keep forgetting.
   tags: [personal, project]
   timestamp: 2026-06-01T00:00:00Z
   ---
   
   # What it is
   A simple app for saving and scaling recipes. Use the [writing voice](/notes/writing-voice.md) for any copy.
   MD
   cat > knowledge/notes/writing-voice.md <<'MD'
   ---
   type: Preference
   title: Writing voice
   description: Plain, warm, no jargon.
   ---
   
   # Voice
   Short sentences. Friendly. No hype.
   MD
   cat > SOUL.md <<'MD'
   # House rules
   Before answering anything about my projects or preferences, read
   knowledge/index.md first and follow the links to the relevant notes.
   Treat those notes as the source of truth for my context.
   MD
   ruby -ryaml -e '
   require "date"
   RESERVED = ["index.md", "log.md"]
   concepts = 0; errors = []
   Dir.glob("knowledge/**/*.md").sort.each do |path|
     next if RESERVED.include?(File.basename(path))
     lines = File.read(path).lines
     unless lines.first && lines.first.strip == "---"
       errors << (path + ": no frontmatter"); next
     end
     rest = lines[1..]
     idx = rest.index { |l| l.strip == "---" }
     unless idx; errors << (path + ": unterminated frontmatter"); next; end
     fm = (begin; YAML.safe_load(rest[0...idx].join, permitted_classes: [Date, Time]); rescue; nil; end)
     unless fm.is_a?(Hash) && !fm["type"].to_s.empty?
       errors << (path + ": missing or empty type"); next
     end
     concepts += 1
   end
   abort "NONCONFORMANT bundle: " + errors.join("; ") unless errors.empty?
   soul = File.exist?("SOUL.md") ? File.read("SOUL.md") : ""
   abort "BAD: SOUL.md is missing" if soul.empty?
   abort "BAD: SOUL.md does not point Hermes at knowledge/index.md" unless soul.include?("knowledge/index.md")
   puts "Hermes+OKF wired OK: knowledge bundle conforms (" + concepts.to_s + " concepts) and SOUL.md reads knowledge/index.md first"
   '

2. 2

   Let Hermes use it (the model step, not checked by CI)

   Start Hermes with a provider key and ask it something about your project. With the SOUL.md rule in place it reads the bundle first. The same one-line-house-rule trick works in coding assistants: drop the folder in your project and tell the tool to consult it. Whether the answer is right depends on the notes, so CI never claims it.