Hermes Agent

Data Model — v0.14.0 — Nous Research

The data structures at the heart of Hermes Agent — the database schema that persists sessions and messages, the message format that flows between the agent and LLM providers, the tool registry that powers 40+ capabilities, the skill file format, the layered configuration system, and the pluggable memory provider interface.

Core Entity Map

Where each entity lives. Sessions and messages persist in SQLite, tools and config rebuild from code and YAML at startup, skills and plugins live on the filesystem, and credentials rotate through a managed JSON store.

SQLite Schema

All state lives in ~/.hermes/state.db — a SQLite database with WAL mode for concurrent reads. Schema version 11. FTS5 for full-text search across message content, tool names, and tool-call arguments, with a trigram index for CJK/substring queries.

CREATE VIRTUAL TABLE messages_fts USING fts5(content);

-- Auto-sync triggers (v11 — indexes content + tool_name + tool_calls)
AFTER INSERT ON messages →
    INSERT INTO messages_fts(rowid, content) VALUES (
        new.id,
        COALESCE(new.content, '') || ' ' ||
        COALESCE(new.tool_name, '') || ' ' ||
        COALESCE(new.tool_calls, '')
    );

AFTER DELETE ON messages →
    DELETE FROM messages_fts WHERE rowid = old.id;

AFTER UPDATE ON messages →
    DELETE old entry, INSERT new entry (same concat as INSERT).

Message Format

Messages follow the OpenAI chat completions format. This is the lingua franca — regardless of whether the backend is Anthropic, OpenAI, or a custom endpoint, messages are normalized to this shape.

{
  "role": "user",
  "content": "Search for recent papers on GRPO"
}

{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "web_search",
        "arguments": "{\"query\": \"GRPO ...\"}"
      }
    }
  ]
}

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "tool_name": "web_search",
  "content": "{\"data\": {\"web\": [...]}}"
}

{
  "role": "system",
  "content": "You are a CLI AI Agent..."
}
// Frozen at session start.
// Never modified mid-conversation
// (preserves Anthropic prompt cache).

Tool Registry & Toolsets

Tools self-register at import time into a singleton registry. Toolsets group related tools and compose into platform-level bundles. See C4 Architecture § Tools for the high-level view.

{
  "name": "read_file",
  "description": "Read a text file with line numbers...",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "Path to the file to read"
      },
      "offset": {
        "type": "integer",
        "default": 1,
        "minimum": 1
      },
      "limit": {
        "type": "integer",
        "default": 500,
        "maximum": 2000
      }
    },
    "required": ["path"]
  }
}

Skill File Structure

Skills are Hermes's procedural memory — reusable markdown instructions with optional supporting files. They are injected as user messages (not system prompt) to preserve prompt cache efficiency.

---
name: visual-explainer                    # Required: kebab-case slug
description: Generate rich HTML docs...   # Required: when to use
version: 1.0.0                           # Required: semver
author: Hermes Agent                     # Required
license: MIT                             # Required
dependencies: []                         # Optional: pip/system deps
prerequisites:                           # Optional
  env_vars: [LINEAR_API_KEY]             #   Required env vars
  commands: [curl]                       #   Required CLI tools
metadata:
  hermes:
    tags: [architecture, diagrams]       # Searchable tags
    related_skills: [excalidraw]         # Cross-references
---

# Skill Title

## When to Use
...

## Workflow
...

## Pitfalls
...

Config Hierarchy

Configuration resolves through four layers. Lower layers provide defaults; higher layers override. ${VAR} references in YAML values are expanded from environment variables.

Plugin System

Hermes uses a plugin architecture for extensibility. Five plugin categories exist: memory providers, context engines, general-purpose plugins, dashboard plugins, and platform plugins. The PluginManager discovers and loads plugins from four sources in precedence order.

Memory Provider Interface

Memory is pluggable. The built-in provider (file-based, always active) handles memory and user targets. At most one external provider (Honcho, etc.) can be added. The MemoryManager fans out calls to all active providers. See C4 Architecture § State for the provider list and runtime behaviour.