Hermes Agent Setup on Linux Mint 22.3 — What Actually Worked

Date: 2026-08-09 Target: Rust + Svelte development (FicHub) with Hermes Agent v0.20.0

This doc records what ACTUALLY worked on this fresh Linux Mint install. A pasted AI guide (Qwen3.8-Max) contained many hallucinated commands (hermes tools enable rtk, standalone codegraph binaries, tree-sitter CLI setup, etc.). This file is the ground truth after verification.

1. Ground truth — what Hermes v0.20.0 actually has

• hermes runs from ~/.local/bin/hermes (a bash wrapper that execs the venv python: ~/.hermes/hermes-agent/venv/bin/python hermes).
• HERMES_HOME is the PROFILE dir: ~/.hermes/profiles/coding/ (not ~/.hermes/). Config: ~/.hermes/profiles/coding/config.yaml.
• Tools are organized as toolsets (hermes tools list), plugins (hermes plugins list), and MCP servers (hermes mcp list).
• There is NO first-party "codegraph", "tree-sitter", "rtk", "headroom", "caveman", "tokensaver", or "ponytail" tool in this build. Those names came from the hallucinated guide (except rtk-hermes, a real community pip plugin — see §5).

2. LSP (semantic diagnostics on write) — WORKED

Hermes has a built-in LSP subsystem (hermes lsp status). It runs language servers as background subprocesses and feeds diagnostics into write_file and patch results.

What was already installed

• pyright (Python), typescript-language-server (TS/JS), bash-language-server, yaml-language-server, rust-analyzer (via rustup, on PATH).

What I installed

• svelte-language-server — the auto-install (hermes lsp install svelte) FAILED (no log detail). Manual install worked:

# Install the npm package into the PROFILE lsp dir (HERMES_HOME = profile!)
mkdir -p ~/.hermes/profiles/coding/lsp/bin ~/.hermes/profiles/coding/lsp/node_modules
cd ~/.hermes/profiles/coding/lsp
npm install --prefix ~/.hermes/profiles/coding/lsp svelte-language-server
ln -sf ~/.hermes/profiles/coding/lsp/node_modules/.bin/svelteserver \
       ~/.hermes/profiles/coding/lsp/bin/svelteserver
hermes lsp status   # → svelte-language-server [installed]

Key gotcha

• hermes lsp status checks <HERMES_HOME>/lsp/bin/ where HERMES_HOME is the profile dir (~/.hermes/profiles/coding/), NOT ~/.hermes/.
• rust-analyzer is manual-only (too heavy to auto-install); rustup installs it to ~/.local/share/cargo/bin, which is on PATH.

LSP config (optional tuning)

# config.yaml
lsp:
  enabled: true
  wait_mode: document
  wait_timeout: 5.0
  install_strategy: auto
  idle_timeout: 600

3. CodeGraph — WORKED (community MCP server)

There is no first-party codegraph. The real one is @colbymchenry/codegraph (npm CLI + MCP server + SQLite + tree-sitter). It builds a pre-indexed symbol/call graph per repo. The skills-hub skill skills-sh/onsager-ai/dev-skills/codegraph documents it; the install was blocked by the scanner (community + unpinned npm), so I installed the CLI directly instead — cleaner and fully controlled.

Install + index

npm install -g @colbymchenry/codegraph      # → ~/.local/bin/codegraph
cd /personal/documents/code/rust/fichub
codegraph init .                            # indexed 299 files, 5124 nodes, 14345 edges
codegraph telemetry off
codegraph status                            # rust 137, ts 71, svelte 55, js 23, ...
codegraph query "roadmap"                   # CLI works standalone
codegraph explore "suggest"                 # blast radius + no-covering-test flags

Wire MCP into Hermes config

hermes config set mcp_servers.codegraph.command codegraph
hermes config set mcp_servers.codegraph.args '["serve","--mcp","--no-watch","--path","/personal/documents/code/rust/fichub"]'
hermes config set mcp_servers.codegraph.timeout 120
hermes config set mcp_servers.codegraph.connect_timeout 60
hermes config set mcp_servers.codegraph.enabled true

• --no-watch avoids the file-watcher (which can be heavy on NFS); reindex manually with codegraph sync after edits, or rely on the staleness banner.
• --path pins the project so the server finds .codegraph/ regardless of cwd.
• Added /.codegraph/ to the repo .gitignore.

Verification

• codegraph serve --mcp responds to initialize with tool capabilities.
• The MCP loop probe (probe_loop2.py pattern) connects and discovers codegraph_explore — the single tool. Confirmed working.
• NOTE: hermes mcp test codegraph reports "Connection closed" — a CLI probe quirk, NOT a real failure. The real MCP loop connects fine. Fresh sessions discover the tool at startup.

CodeGraph caveats (from the skill)

• It's a tree-sitter approximation, NOT compiler-grade. False negatives on method dispatch / generic call sites. grep is source of truth for completeness; codegraph accelerates orientation/traversal.
• Index lags disk by ~1s after edits.
• For exhaustive callers before a rename: use grep, not codegraph.

4. Token saving — what's real vs hallucinated

• Context compression is built-in and ON (compression.enabled: true, threshold 0.5, target_ratio 0.2). This is Hermes's real "headroom" — it summarizes older conversation to keep context within budget. Use /context to see the budget, /compress to force a pass.
• The names rtk, headroom, caveman, tokensaver, ponytail in the pasted guide are NOT Hermes tools/plugins in this build (checked source and docs). Do NOT try hermes tools enable rtk — it doesn't exist.
• rtk-hermes is a REAL community pip plugin (ogallotti/rtk-hermes, v1.2.3 on PyPI) — INSTALLED and enabled here. It rewrites terminal commands through RTK before execution to cut context tokens.

rtk-hermes install (worked)

# 1. RTK CLI (installer → ~/.local/bin)
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
rtk --version                                    # rtk 0.45.0

# 2. Plugin into the HERMES venv (venv has NO pip; use uv)
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python --upgrade rtk-hermes

# 3. Enable (use the CLI, NOT `hermes config set plugins.enabled '["rtk-rewrite"]'`
#    — that writes a quoted string, not a YAML list; the CLI writes it correctly)
hermes plugins enable rtk-rewrite                # declines built-in tool override

# Verify
hermes plugins list | grep rtk                   # enabled 1.2.3 entrypoint
rtk rewrite "git status"                          # → "rtk git status"

• Failure mode is fail-open: if RTK can't rewrite, the original command runs.
• hermes config set plugins.enabled '[...]' saves a STRING, not a list — use hermes plugins enable instead.

5. Project context & workflow for FicHub

• Hermes auto-loads project context files: .hermes.md (walks to git root), AGENTS.md / CLAUDE.md (cwd only), .cursorrules. FicHub has docs/AGENTS.md (comprehensive rules, loaded only when cwd is docs/). A root AGENTS.md quick-start was drafted but the write needs user approval (protected agent-instruction file) — pending.
• Worktrees live on /media/alvaro/code-worktrees/wt-<name>; .env is NOT in worktrees — source from the main repo (set -a && . ./.env && set +a).

6. Host tooling status on this box

Already present: Rust (rustup, rustc/cargo), Node v22.23.2 + npm 10.9.8, git 2.43, ripgrep, fdfind, batcat. Not installed yet: pnpm (use npm or corepack), justfile, pre-commit.

7. Memory — Semantic (qdrant) + Second Brain — WORKED

7a. Semantic memory: mem0 OSS + Qdrant (local)

Hermes ships real memory-provider plugins (hermes memory status): honcho, openviking, mem0, hindsight, holographic, retaindb, byterover, supermemory. mem0 OSS mode supports Qdrant local as the vector store — that's the semantic memory path, fully local.

Prereqs: ollama on this box (LLM + embedder). Installed via the official installer (curl -fsSL https://ollama.com/install.sh | sh), pulled nomic-embed-text (embedder) + llama3.1:8b (LLM).

Gotcha: hermes memory setup mem0 --mode oss --oss-llm ... FAILS — the CLI's argparse rejects the plugin flags before the plugin sees them (the README's flag examples are aspirational for this build). The plugin reads flags from sys.argv via its own parser, so invoke post_setup directly:

# setup_mem0_oss.py (run with the hermes venv python)
import sys, os
sys.path.insert(0, "/home/alvaro/.hermes/hermes-agent")
os.environ.setdefault("HERMES_HOME", "/home/alvaro/.hermes")
sys.argv = ["hermes","memory","setup","mem0","--mode","oss",
            "--oss-llm","ollama","--oss-embedder","ollama","--oss-vector","qdrant"]
from hermes_cli.config import load_config
from plugins.memory.mem0._setup import post_setup
post_setup(os.environ["HERMES_HOME"], load_config())

Result: mem0.json with ollama llama3.1:8b + nomic-embed-text (768-d) + qdrant local at ~/.hermes/mem0_qdrant. The plugin auto-installs ollama and qdrant-client pip deps into the Hermes venv.

7b. Second brain: Karpathy-style LLM Wiki (chosen over Obsidian MCP)

The user wants the Karpathy LLM Wiki pattern (interlinked markdown KB that the LLM reads/writes, Obsidian-readable) — e.g. the llm-wiki pattern at ronancodes.github.io/llm-wiki — NOT just an Obsidian MCP bridge. The external RonanCodes/llm-wiki repo is private (404), so the wiki is implemented via the built-in llm-wiki skill (same pattern: SCHEMA / index / log, entities / concepts / comparisons / queries, wikilinks, frontmatter, ingest / query / lint). The wiki dir works as an Obsidian vault out of the box.

# Wiki lives at ~/wiki (WIKI_PATH=/home/alvaro/wiki in profile .env)
~/wiki/
├── SCHEMA.md        # domain conventions + tag taxonomy
├── index.md         # content catalog
├── log.md           # append-only action log
├── raw/             # immutable sources (articles/, papers/, transcripts/)
├── entities/        # fichub.md, ...
├── concepts/        # hermes-agent-setup-linux-mint.md, ...
├── comparisons/
└── queries/

Agent workflow (llm-wiki skill): orient (read SCHEMA+index+log) → ingest sources into raw/ → synthesize/update wiki pages with [[wikilinks]] → update index+log. Lint finds orphans, broken links, contradictions.

ALSO installed (complementary): open-second-brain native Hermes memory provider — markdown Brain/ layer injected into the system prompt + brain_* tools. Both are plain-markdown, git-versionable, human-readable.

7c. Provider layering (only one ACTIVE)

Hermes allows ONE active external memory provider (memory.provider). Current setup:

• Active: open-second-brain — markdown brain, active.md injection, brain_* tools. Vault at /home/alvaro/documents/second-brain.
• mem0/qdrant still configured (mem0.json present) — its tools (mem0_search) remain usable for semantic queries; it just isn't the auto-injecting provider.
• llm-wiki (~/wiki) is a skill-driven KB, independent of the provider system — usable regardless of which provider is active.

8. High-value additions (installed after ecosystem review)

From browsing relatedrepos.com for the installed tools (mem0, codegraph, open-second-brain, rtk) + the ecosystem catalog (/personal/documents/hermes-agent/hermes-ecosystem-tools.md), these were the top additions — all installed and verified.

8a. hermes-lcm — Lossless Context Management (Hermes plugin)

DAG-based context engine that never loses a message. Persists messages in a plugin-local SQLite store with FTS metadata; keeps the live prompt bounded while preserving raw messages for drill-down.

git clone https://github.com/stephenschoettler/hermes-lcm.git ~/code/hermes-lcm
cd ~/code/hermes-lcm && HERMES_PROFILE=coding ./scripts/install.sh
# GOTCHA: HERMES_HOME is already ~/.hermes/profiles/coding on this box, so
# the script double-appends → installs to profiles/coding/profiles/coding/.
# Move it manually:
mv ~/.hermes/profiles/coding/profiles/coding/plugins/hermes-lcm ~/.hermes/profiles/coding/plugins/
mv ~/.hermes/profiles/coding/profiles/coding/skills/hermes-lcm ~/.hermes/profiles/coding/skills/
hermes plugins enable hermes-lcm          # decline tool-override prompt
hermes config set context.engine lcm     # README activation requires this

Verified: plugin enabled (0.21.0-rc2), skill discoverable, context.engine: lcm in config.

8b. headroom — pre-LLM output compression (MCP server)

Compress tool outputs, logs, files, RAG chunks BEFORE they reach the LLM. 20% fewer tokens for coding agents, 60–95% for JSON. Local-first, reversible.

uv tool install --python 3.13 "headroom-ai[all]"    # → ~/.local/bin/headroom
hermes config set mcp_servers.headroom.command headroom
hermes config set mcp_servers.headroom.args '["mcp","serve"]'
hermes config set mcp_servers.headroom.timeout 120
hermes config set mcp_servers.headroom.connect_timeout 60
hermes config set mcp_servers.headroom.enabled true

Verified: 3 tools (headroom_compress, headroom_retrieve, headroom_stats).

8c. claude-mem — persistent cross-session context (MCP server)

Captures everything the agent does, compresses with AI, injects relevant context across sessions. 90k★. Installs as a Claude Code plugin by default; wired into Hermes via its MCP server directly.

export PATH="$HOME/.bun/bin:$PATH"     # needs Bun (installed for o2b)
npx -y claude-mem install --no-auto-start   # installs plugin + worker
npx -y claude-mem start                # worker on http://127.0.0.1:37700/
# Wire the MCP server into Hermes (path found in plugin cache):
hermes config set mcp_servers.claude-mem.command node
hermes config set mcp_servers.claude-mem.args '["/home/alvaro/.claude/plugins/cache/thedotmack/claude-mem/13.14.0/scripts/mcp-server.cjs"]'
hermes config set mcp_servers.claude-mem.timeout 120
hermes config set mcp_servers.claude-mem.connect_timeout 60
hermes config set mcp_servers.claude-mem.enabled true

Verified: 14 tools (search, timeline, get_observations, session_start_context, smart_search, smart_unfold, corpus tools, …).

8d. NOT installed (and why)

• hermes-tool-slimmer — its installer patches core Hermes source (conversation_loop.py + plugins.py) and the patch produced INVALID Python (try/finally/else) on this build, breaking the source. Reverted fully (git diff clean). Skip — Hermes's native progressive tool loader already handles large catalogs.
• Superpowers (obra) — a Claude Code-harness skills framework; its own AGENTS.md says copying skills into another harness = "dead weight" and requires its bootstrap + hooks. Not compatible with Hermes's skill system without a real harness integration. Skip; Hermes has 100+ skills already.

9. Verification checklist

hermes lsp status                 # rust-analyzer, svelte, typescript, pyright all [installed]
hermes mcp list                   # codegraph, headroom, claude-mem all ✓ enabled
codegraph status                  # in repo: index up to date
hermes plugins list               # hermes-lcm, open-second-brain, rtk-rewrite enabled
hermes doctor                     # general health

10. Session learnings / pitfalls

1. hermes lsp install svelte failed silently; manual npm install into the PROFILE lsp dir + symlink into lsp/bin/ worked.
2. HERMES_HOME = profile dir for LSP/MCP paths. ~/.hermes/lsp is NOT scanned — don't install there.
3. hermes mcp test can report false "Connection closed" for stdio servers that actually connect fine via the real MCP loop. Trust hermes mcp list
   • a fresh-session tool discovery instead.
4. hermes config set is the only way the agent can write config.yaml (direct file writes are blocked for security). Nested keys work: hermes config set mcp_servers.codegraph.command codegraph.
5. The MCP stdio env is filtered (_build_safe_env): PATH/HOME/USER/LANG/ TERM/SHELL/TMPDIR + XDG_* pass; everything else is dropped. If a server needs a custom env var, add it via mcp_servers.<name>.env.
6. Watchdog wrapper (mcp_stdio_watchdog.py) relays stdio transparently; a pipeline test that pipes echo | watchdog --ppid $$ is misleading ($$ is not the watchdog's parent in a pipeline) — test with a stable parent.
7. Never edit config.yaml directly as the agent — use hermes config set.
8. hermes-tool-slimmer's installer patches core Hermes source and can break it. It inserted a select_tool_schemas hook into conversation_loop.py with invalid try/finally/else syntax — the next Hermes session would have crashed with SyntaxError. If a plugin's installer modifies ~/.hermes/hermes-agent/, verify with venv/bin/python -m py_compile + git diff afterward, and revert with patch (not git checkout — that's blocked on the live source).
9. Probes of MULTIPLE MCP servers on one loop sequentially can show false "parked" failures (retry/parking interaction between shutdowns). Probe each server in a fresh process to confirm it works — each of codegraph, headroom, claude-mem connects fine individually.