Hermespace Setup Guide¶

Repo: PabloTheThinker/hermespace Version: v0.20.0 Stars: 46 License: MIT Skill: npx skills add PabloTheThinker/hermespace --skill hermespace -g -y

What It Is¶

Hermespace is a persistent, append-only world model that adds a limited working-memory desk beside Hermes Agent. It provides:

Workbench - Focused attention of ≤4 items, park stack for deferred goals, monotropic goal focus
Dual Decode - Separate channels: short human report vs dense model context (never dumps model context into chat)
Fabric - Ranks $HERMES_HOME/skills and injects MEMORY/USER excerpts relevant to current goal
Plugin - on_session_start, pre_llm_call, on_session_end hook broadcasts
Study DB - Turn history stored under ~/.hermespace (separate from Hermes session DB)
Desktop Plugin - Right-rail pane for Hermes desktop app
World Model - Append-only archive that never prunes, never decays, never caps

It does not replace Hermes tools, skills, memory, gateway, or the agent loop. It augments them.

Prerequisites¶

Python 3.10+
Hermes Agent v0.20.0+ (v0.20.0+ recommended)
Git
pip or uv for Python package management

Installation¶

Method 1: npx skills (recommended)¶

npx skills add PabloTheThinker/hermespace --skill hermespace -g -y

This places the skill at $HERMES_HOME/skills/hermespace/.

Method 2: Manual clone + install¶

git clone https://github.com/PabloTheThinker/hermespace.git
cd hermespace
./scripts/install_hermes.sh

The install script: 1. Installs the Python package (pip install -e .) 2. Symlinks hermes_plugin/ → $HERMES_HOME/plugins/hermespace 3. Symlinks skills/hermespace/ → $HERMES_HOME/skills/hermespace 4. Creates ~/.hermespace/ state directory

Verify Installation¶

cd hermespace
./scripts/smoke_test.sh    # expect 9/9

# Python import check
python3 -c "from hermespace import Workbench; print('OK')"

Configuration¶

State directory¶

Default: ~/.hermespace/

Override with environment variable:

export HERMESPACE_HOME=/custom/path
export ILO_HOME=/custom/path     # alternative name

Plugin activation¶

If installed via install_hermes.sh, the plugin is symlinked. Verify:

ls -la $HERMES_HOME/plugins/hermespace/

The plugin broadcasts on three hooks: - on_session_start - Desk initialization, fabric scan - pre_llm_call - Inject ranked skills + memory - on_session_end - Seal turn, update archive

Skill loading¶

The skill (hermespace) should be loaded when: - User says "hermespace", "pocket", "workbench", "FOA desk", "pulse", "viewport" - Multi-step job needs monotropic focus + dual channel - Ranking Hermes skills or injecting MEMORY for current goal - Desktop Hermespace missing or right-rail only - Access approve/deny, autonomy toggles, ops boot

Usage¶

Quick start - Workbench¶

from hermespace import Workbench

wb = Workbench(agent_id="hermes", session_id="main")
wb.enter()
r = wb.receive_order("Audit the deployment pipeline", goal="Find bottlenecks", say="Starting audit...", force=True)

# r["user_reply"] → what the user sees
# r["model_context"] → dense context for the model (NOT shown to user)

CLI turn interface¶

./scripts/hs turn -m "Analyze our current social posting cadence" --goal "Find gaps in our schedule" --say "On it"

World Model (persistent archive)¶

from hermespace import WorldModel

wm = WorldModel(agent_id="corpusiq-growth")
wm.enter()
wm.add_belief("Help-first content outperforms promotional", 0.85, source="six-month-data")
wm.add_landmark("Hit 5,000 monthly reach across platforms")
wm.set_trait("operations-minded")
wm.set_goal("Grow to 15% MoM", decision="A - increase Reddit presence", plan=["audit", "deploy", "measure"])
wm.evolve()  # consolidate, detect patterns
print(wm.render_markdown())

The archive lives at ~/.hermespace/worlds/corpusiq-growth_archive.jsonl - an append-only JSONL file that grows forever.

Focus of Attention (FOA)¶

The workbench enforces a bounded FOA:

Limit	Default	Meaning
FOA capacity	4	Active items in focus
Desk capacity	12	Items on desk (parked + active)
Monotropic goal	1	One active goal at a time

When the desk is full, items are parked and can be recalled.

Fabric - Skill ranking¶

The fabric scans $HERMES_HOME/skills/ and ranks them by relevance to the current goal. It injects the top matches into the model context (not the user report):

wb = Workbench()
wb.enter()
# Fabric auto-ranks on receive_order
r = wb.receive_order("Debug the gateway crash loop", goal="Fix gateway")
# The model sees ranked skills + relevant MEMORY excerpts
# The user only sees the report

Architecture Decisions¶

Dual Decode Pattern¶

This is the critical design insight: never dump model context into the chat. Hermespace provides two separate channels:

Channel	Audience	Contents
`report`	Human user	Concise summary, decision, next step
`context`	Model only	Ranked skills, memory, full plan, fabric output

This prevents the context pollution where model-internal reasoning overwhelms the conversation.

Append-Only Archive¶

The world model is an append-only JSONL - no pruning, no decay, no deletion. Every entry type (enter, leave, landmark, belief, trait, evolution, focus, epoch_transition, resolve, relationship) appends to the file.

Evolution is triggered explicitly (wm.evolve()) and handled by the library - consolidation, pattern detection, epoch checks.

Pitfalls¶

Not a replacement for Hermes memory - Hermespace's archive is a companion, not a replacement for Hermes MEMORY, Sibyl, or GBrain. Use both.
Not a second agent runtime - Hermespace provides bounded working memory, not a second LLM. It does not make API calls or run tools.
Desktop plugin requires Hermes desktop app - The right-rail pane only works with the Hermes desktop app (Electron). On headless/SSH systems, use the Python API.
Archive grows unbounded - The JSONL file never prunes. For long-running agents (months/years), disk usage may become significant. Monitor ~/.hermespace/worlds/ size periodically.
Python 3.10+ required - Some type annotations and features require Python 3.10+. On older systems, upgrade Python first.

Verification Checklist¶

[ ] pip install -e . succeeds (or npx skills add succeeds)
[ ] ./scripts/smoke_test.sh returns 9/9
[ ] python3 -c "from hermespace import Workbench" succeeds
[ ] ~/.hermespace/ directory exists
[ ] Plugin appears in $HERMES_HOME/plugins/hermespace/
[ ] Skill appears in $HERMES_HOME/skills/hermespace/
[ ] wb = Workbench(agent_id="test"); wb.enter() completes without error

Integration with CorpusIQ¶

CorpusIQ is the connector layer that lets AI assistants read the systems a business already runs on - accounting, payments, CRM, email, files and analytics - and answer with the source named. It is read-only by design: it retrieves data and never writes to, or acts in, a connected system, which is what makes it safe to point at live accounts.

This page is part of the CorpusIQ directory, the reference we maintain for the MCP server and agent-skill ecosystem. Run alongside CorpusIQ, a third-party server like this one can be combined with a company's own business data in a single answer.

See what CorpusIQ connects