Skip to content

hermes.md

Latest commit

 

History

History
451 lines (338 loc) · 15.1 KB

hermes.md

File metadata and controls

451 lines (338 loc) · 15.1 KB
Raw

Hermes Plugin Integration

Uteke can be used as a complementary memory layer for Hermes Agent ecosystems.

Architecture

Uteke integrates with Hermes in two modes. Pick the one that matches how you want memory to behave.

Hermes Agent
├── Mode A: uteke-tool (manual)    → agent calls uteke(action=...) for explicit remember/recall
├── Mode C: uteke-memory (plugin)  → automatic recall via pre_llm_call hook every turn
└── ~~Mode B: memory-provider~~     → removed 2026-06-29
Mode A (uteke-tool) Mode C (uteke-memory plugin) Mode B (memory-provider)
Install uteke init --agent hermes Plugin at ~/.hermes/plugins/uteke-memory/ removed
Invocation Agent calls uteke(action="recall") Automatic (plugin hook) Automatic (provider)
Capture Agent decides what to store Manual (uteke remember via Mode A) Auto-extract on session end
Transport HTTP to uteke-serve subprocess or HTTP CLI subprocess
Daemon Requires uteke-serve No (subprocess) / optional (HTTP) No
Rooms / multi-agent Yes Yes No
Best for Explicit, on-demand memory Lightweight auto-recall Drop-in replacement

Recommended: Mode A + Mode C side by side — automatic recall via plugin hook, manual store via tool. Both read the same uteke store.

Mode A — uteke-tool (manual actions, multi-agent rooms)

Quick Setup

1. Install uteke

curl -fsSL https://raw.githubusercontent.com/codecoradev/uteke/main/install.sh | sh

2. Auto-install Hermes plugin (v0.3.0+)

uteke init --agent hermes

This generates the plugin directly to ~/.hermes/plugins/uteke-tool/ with:

  • plugin.yaml — manifest
  • tool.py — Python entry point (stdlib only, no requests dependency)
  • README.md — usage guide

3. Start the server

uteke-serve --port 8767

4. Start a new Hermes session

The plugin loads automatically.

Usage

Memory Operations

# Store a memory
uteke(action="remember", content="User prefers dark mode", tags="preference,ui")

# Semantic recall
uteke(action="recall", content="user preferences")

# Keyword search
uteke(action="search", content="dark mode")

# List memories
uteke(action="list", limit=10)

# Delete a memory
uteke(action="forget", id="abc12345")

# Stats
uteke(action="stats")

Room Operations (v0.3.0+, #395, #410)

Rooms enable multi-agent collaborative memory — multiple agents share a room and contribute memories with author attribution.

# Create a shared room
uteke(action="room_create", room_id="sprint-planning", title="Sprint Planning")

# Add a memory to a room (with author attribution)
uteke(action="room_remember", room_id="sprint-planning", content="Deploy scheduled for Friday", author="agent1")

# Add a reference document to a room
uteke(action="room_summary_document", room_id="sprint-planning", content="Architecture spec: ...", title="Arch Spec")

# Recall from a room (semantic search — query is required)
uteke(action="room_recall", room_id="sprint-planning", content="deploy deadline")

# List all rooms (cross-namespace)
uteke(action="room_list")

# Room analytics
uteke(action="room_stats", room_id="sprint-planning")
uteke(action="room_summary", room_id="sprint-planning")

# Delete a room (memories preserved)
uteke(action="room_delete", room_id="sprint-planning")

MCP Server (Alternative)

For MCP-compatible agents, use the uteke MCP server instead of the HTTP plugin:

# Register with Hermes
hermes mcp add uteke --command uteke-mcp

# Or use the HTTP transport
hermes mcp add uteke --url http://127.0.0.1:8767/mcp

The MCP server provides the same tools via JSON-RPC (protocol version 2025-06-18):

  • uteke_remember — store memory (supports type, room, author, tags)
  • uteke_recall — semantic search (supports tags filter, min_score)
  • uteke_list — list memories (supports pagination via offset)
  • uteke_forget — delete memory
  • uteke_stats — store statistics
  • uteke_room_memories — list memories in a room (#569)

MCP Client Configuration Examples

Claude Desktop (stdio transport)

Create or edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "uteke": {
      "command": "uteke-mcp"
    }
  }
}

Claude Desktop (HTTP transport)

{
  "mcpServers": {
    "uteke": {
      "url": "http://127.0.0.1:8767/mcp"
    }
  }
}

Cursor

Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "uteke": {
      "command": "uteke-mcp"
    }
  }
}

Or with HTTP transport:

{
  "mcpServers": {
    "uteke": {
      "url": "http://127.0.0.1:8767/mcp"
    }
  }
}

Hermes Native MCP Client (HTTP transport)

# Register with Hermes using HTTP transport (requires uteke-serve running)
hermes mcp add uteke --url http://127.0.0.1:8767/mcp

Or with stdio transport:

# Register with Hermes using stdio transport
hermes mcp add uteke --command uteke-mcp

Tip: HTTP transport is recommended when uteke-serve is already running — it avoids subprocess overhead and works across machines. Stdio transport is simpler for local, single-agent setups where no daemon is desired.

Available Actions

Action Description
remember Store a new memory
recall Semantic search
search Keyword search
list List memories (with namespace filter)
forget Delete memory
stats Namespace or global statistics
room_remember Store memory in a room with author attribution
room_summary_document Store a reference document in a room
room_create Create a room
room_recall Semantic search within a room (requires query)
room_list List all rooms (cross-namespace)
room_summary Room topic summary with clusters and highlights
room_stats Room statistics (memory count, participants)
room_delete Delete a room (memories preserved)
namespace_list List all namespaces
namespace_stats Statistics for a specific namespace
tags_list List all tags
tags_rename Rename a tag across all memories
tags_delete Delete a tag from all memories
consolidate Merge similar memories (with threshold)
aging Aging cleanup of old memories
import Import memories from JSON
importance Recompute importance scores
doctor Health check (alias for /health)

Valid Memory Types

When using remember, room_remember, or room_summary_document, the type parameter accepts these values:

Type Description
fact A factual statement or observation
procedure A how-to, process, or workflow
preference A user or system preference
decision A decision that was made
context Background context for a topic
note A general note
insight An insight or conclusion
reference A reference document (default for room_document)
event A time-based event

Warning: Using an invalid type (e.g., document) causes HTTP 500. Use reference instead of document.

HTTP API Notes

The uteke HTTP server (uteke-serve) uses exact path matching — query parameters are NOT part of the route. This means:

# ✅ Correct — POST with JSON body
curl -X POST http://127.0.0.1:8767/stats \
  -H 'Content-Type: application/json' \
  -d '{"namespace": "cto"}'

# ❌ Wrong — GET with query params returns 404
curl http://127.0.0.1:8767/stats?namespace=cto

All endpoints that accept parameters use POST with JSON body, not GET with query strings.

Memory-Provider for Other Agents

The --memory-provider pattern also works for non-Hermes agents (#575, #577):

# pi (pi.dev)
uteke init --agent pi --memory-provider

# Claude Code
uteke init --agent claude --memory-provider

# Cursor
uteke init --agent cursor --memory-provider

This installs uteke as the agent's default memory provider — relevant memories are recalled and injected automatically every turn. No daemon needed; talks to the uteke binary directly via subprocess.

Note: For Hermes, use Mode A (uteke-tool) or Mode C (uteke-memory plugin) instead — the Hermes memory-provider plugin has been removed (see Mode B).

Mode B — memory-provider (deprecated)

DEPRECATED for Hermes (removed 2026-06-29). Use Mode A + Mode C instead.

The --memory-provider pattern remains supported for pi, Claude Code, and Cursor. See Memory-Provider for Other Agents. The template source lives at extensions/hermes-memory-provider/.

Historical reference: Mode B made uteke Hermes's long-term memory backend via uteke init --agent hermes --memory-provider + memory.provider: uteke config. Automatic recall every turn, auto-extract facts on session end. No daemon needed.

Configuration (uteke-tool)

Environment Variable Default Description
UTEKE_SERVER_URL http://127.0.0.1:8767 uteke server URL

(For memory-provider configuration, see the reference table under Mode B.)

How It Works (uteke-tool)

  • Remember: POST to /remember — content is embedded (EmbeddingGemma Q4, 768d) and stored in SQLite + HNSW vector index. Supports type param (see Valid Memory Types)
  • Recall: POST to /recall — semantic search via hybrid RRF (vector + FTS5), returns ranked results
  • Room Remember: POST to /room/remember — stores memory and links to room in a single call. Requires room_id (not room). Use type="reference" for documents (not document — causes 500)
  • Rooms: Cross-namespace collaboration spaces — rooms span namespaces, enabling multi-agent coordination
  • MCP: JSON-RPC over stdio or HTTP — standard MCP protocol for AI agent integration

The memory-provider plugin (Mode B) skips the HTTP layer entirely and shells out to the uteke binary: recall --json for prefetch, import --extract for session-end distillation.

Mode C — uteke-memory plugin (pre_llm_call hook, automatic recall)

Mode C is the recommended auto-recall integration: a Hermes Python plugin that registers a pre_llm_call hook. Every turn, before the LLM call, it runs uteke recall on the user message and injects the results into the user message — no shell hook, no daemon, no memory-provider config.

Why a Plugin Instead of a Shell Hook?

Aspect Old shell hook Plugin (pre_llm_call)
Registration hooks.pre_llm_call in config.yaml ctx.register_hook("pre_llm_call", cb)
Runs in Subprocess (separate process) Gateway process (in-process)
Env vars ❌ Does NOT bridge HERMES_SESSION_* ✅ Full gateway process env
Contextvar access ❌ No access to contextvars ✅ Full access (thread_id, platform, etc.)
Blocking Yes (subprocess.run) Yes, but faster (no process spawn)
Agent name detection Hacky (cwd in payload) Reliable (HERMES_HOME, ctx.profile_name)
Performance Process spawn per turn In-process function call

The plugin approach replaces both the old Mode B (MemoryProvider, removed) and the Mode C shell hook. It runs inside the gateway process, has full access to contextvars, avoids subprocess spawn overhead, and is the standard Hermes plugin pattern.

Quick Setup

1. Install uteke

curl -fsSL https://raw.githubusercontent.com/codecoradev/uteke/main/install.sh | sh

2. Install the plugin

The plugin files live at extensions/hermes-memory-provider/ in the uteke repo. Copy them to your Hermes plugins directory:

# Copy from uteke repo
cp -r extensions/hermes-memory-provider ~/.hermes/plugins/uteke-memory/
# Remove .tmpl extension
cd ~/.hermes/plugins/uteke-memory/
for f in *.tmpl; do mv "$f" "${f%.tmpl}"; done

Or generate from uteke init:

uteke init --agent hermes

3. Enable in Hermes config

In ~/.hermes/profiles/<profile>/config.yaml (or global config.yaml):

plugins:
  enabled:
    - uteke-memory

No hooks: config needed. No memory.provider config needed. Just enable the plugin.

4. Verify

hermes plugins list
# Should show: uteke-memory ... enabled

# Start a new session — recall should work automatically
hermes chat

Plugin Config

Config via ~/.hermes/uteke.json (preferred) or environment variables:

Variable Default Description
UTEKE_BIN (search PATH) Path to uteke binary
UTEKE_HOME (inherit) HOME dir for uteke store (~/.codecora/uteke)
UTEKE_NAMESPACE (agent profile name) Memory namespace
UTEKE_SERVER_URL (empty = subprocess) uteke-serve HTTP URL
UTEKE_TOKEN (empty) Auth token for uteke-serve
UTEKE_RECALL_LIMIT 5 Memories to recall per turn
UTEKE_RECALL_MIN_SCORE 0.40 Min score to include
UTEKE_RECALL_TIMEOUT 15 Max seconds per recall call

Example ~/.hermes/uteke.json:

{
  "server_url": "http://uteke:8767",
  "token": "your-bearer-token",
  "recall_limit": 5,
  "recall_min_score": 0.40
}

How It Works

  1. On plugin load (register(ctx)), the recall manager initializes: loads config, resolves transport (subprocess vs HTTP), finds uteke binary.
  2. On every turn, Hermes calls _pre_llm_call(**kwargs) in-process.
  3. The hook truncates the user message to 500 chars, runs uteke recall, filters results by min_score, and formats them as <recalled-memories> XML.
  4. Hermes injects the returned {"context": "..."} into the user message before sending to the LLM. This preserves the system prompt cache prefix.
  5. A circuit breaker pauses recall after 5 consecutive failures for 120 seconds.

Mode Comparison Summary

Mode A Mode C Mode B
What Manual tool Plugin hook (recall only) Full memory provider
Recall Agent calls uteke(action="recall") Automatic (via plugin hook) Automatic
Extraction Manual uteke(action="remember") Manual (combine with Mode A) Automatic (session end)
Daemon uteke-serve required No (subprocess) / optional (HTTP) No
Replaces Hermes memory No No Yes
Best for On-demand memory, multi-agent rooms Lightweight auto-recall Drop-in replacement

Recommended: Mode A + Mode C — automatic recall via plugin, manual store via tool. Keeps Hermes's built-in memory while adding uteke recall.

Requirements

  • uteke v0.3.0+ (includes uteke-mcp binary)
  • Mode A (uteke-tool): uteke-serve running (daemon mode)
  • Mode C (plugin hook): uteke binary on PATH, no daemon
  • Python 3.7+ (stdlib only — no pip install needed)