Sókrates Wiki

Migration from OpenClaw to Hermes Agent

5 min read

Migration from OpenClaw to Hermes Agent

Summary

The Sokrates project is migrating its core agentic gateway and “nervous system” from the legacy OpenClaw system to the Hermes Agent (developed by NousResearch). This transition simplifies the stack from five Docker containers to a more streamlined architecture where Hermes handles channel I/O and agentic loops, while proprietary logic remains in the Sókrates agent and Eidos systems accessed via the Model Context Protocol (MCP).

Details

Rationale and Architectural Shift

The move to Hermes Agent is driven by the need for a more robust, maintained upstream gateway that supports multiple channels (Telegram, Discord, Slack, WhatsApp) out of the box. While OpenClaw served as the initial gateway, Hermes provides a superior NixOS integration via the nix-hermes module and a sophisticated security model.

In the new architecture:

  • Hermes Agent acts as the “nervous system,” managing user interactions and the primary AIAgent core loop.
  • Sókrates agent remains the “brain,” housing proprietary IP such as Socratic dialogue and Basis consultation. It is exposed to Hermes as an MCP server.
  • Eidos remains the “memory,” providing the Neo4j knowledge graph. Since Hermes natively uses flat Markdown files for memory, the Sokrates knowledge graph is integrated as an MCP tool to bridge this gap.
  • sokrates-ctl transitions from an OpenClaw bridge to a diagnostic CLI tool for the stack.

Technical Implementation

The migration involves several key file changes within the NixOS configuration:

  1. flake.nix: The nix-openclaw input is replaced with nix-hermes. The openclawPkgs specialArg is removed, and the openclaw-gateway module is replaced by the hermes-agent module.
  2. nixos/modules/hermes.nix: This new module replaces openclaw.nix. It configures the Hermes Agent with the primary model (routed via OpenRouter), sets up secret management, and defines the mcpServers pointing to Eidos on localhost:8000. The production target model is Gemma 4 31B Dense (locally on DGX Spark), with fine-tuned variants planned.
  3. Systemd Hardening: The nix-hermes module implements strict security, including NoNewPrivileges, ProtectSystem=strict, and scoped ReadWritePaths limited to the state directory.
  4. Network Configuration: Inbound ports 3000 and 3001 (previously used by OpenClaw) are closed in networking.nix, as Hermes utilizes long-polling for channel communication.

Security Model

The Hermes integration introduces a five-layer security boundary:

  • User Authorization: DM pairing and allowlists aligned with OWASP/NIST standards.
  • Command Approval: Human-in-the-loop requirements for destructive operations.
  • MCP Credential Filtering: Explicit environment variable passing to prevent credential leakage to sub-agents.
  • SSRF Protection: Fail-closed mechanisms for RFC 1918 and cloud metadata addresses.
  • Tirith Scanning: Pre-execution scanning for homograph URLs and shell injection attempts.

Identified Gaps and Contributor Strategy

The migration identified specific areas where Sokrates will contribute back to the Hermes upstream:

  • Graph-backed Memory: Developing a Neo4j/Eidos backend for Hermes to replace or augment its flat-file memory system.
  • Multi-tenant Isolation: Adapting Hermes (originally designed for single-user use) to support the Sokrates fleet model, where one agent instance serves specific customer contexts with isolated filesystem boundaries.
  • Basis Accumulation: Creating a pipeline to transform procedural “skills” into principled “Basis” knowledge.

Hermes claw Migrate Utility

The migration from OpenClaw to Hermes is facilitated by the hermes claw migrate utility, which automates the transfer of agent configurations, identities, and operational data from the legacy OpenClaw system to the Hermes environment.

Migration Presets and Options

The migration supports two primary presets:

  • full (default): Migrates all compatible data, including API keys and messaging platform tokens.
  • user-data: Migrates identity and memory files but excludes secrets and sensitive credentials.

Key command options include:

  • --dry-run: Allows users to preview the migration actions without modifying the filesystem.
  • --overwrite: Forces the utility to overwrite existing files in the ~/.hermes directory.
  • --skill-conflict <mode>: Defines how to handle naming collisions for skills (options: skip, overwrite, rename).
  • --source <path>: Specifies a custom path if the OpenClaw data is not in the default home directory.

Data Mapping

The migration utility categorizes OpenClaw data into two groups: those that are directly imported and those that are archived for manual intervention.

Directly Imported Components:

  • Identity and Personality: SOUL.md, USER.md, and AGENTS.md.
  • Context: MEMORY.md.
  • Skills: Logic and code from up to four distinct skill sources.
  • Infrastructure: MCP servers, custom providers, and default model selections.
  • Channel Credentials: Tokens and allowlists for Telegram, Discord, Slack, WhatsApp, Signal, Matrix, and Mattermost.
  • Operational Settings: Session reset policies, approval rules, TTS configurations, browser settings, and command allowlists.

Archived for Manual Review: Certain components are considered too complex or architecturally different to migrate automatically. These are moved to an archive folder within the target directory:

  • Automation: Cron jobs, hooks, and webhooks.
  • Extensions: Plugins and skills registry configurations.
  • System Internals: Memory backend settings, logging configurations, and heartbeat/bootstrap scripts.
  • Identity Metadata: IDENTITY.md, TOOLS.md, and specific channel bindings.

Execution Examples

A typical full migration is executed with:

hermes claw migrate --preset full

To perform a safer migration of only user data while ensuring existing Hermes files are not lost unless specified:

hermes claw migrate --preset user-data --skill-conflict rename

Graph View

Backlinks