Mindscape Plugin for Hermes Agent

Mindscape is a live cognitive graph and reasoning-visualization plugin for Hermes Agent.

It turns Hermes activity into an inspectable graph: sessions, tool calls, reasoning snapshots, decisions, memory nodes, project architecture, and semantic links become visible inside the Hermes Dashboard.

Mindscape is a reusable Hermes plugin that can be installed from GitHub and used with any Hermes setup.

---

Features

• Live cognitive graph inside the Hermes Dashboard
• Persistent graph memory
• Obsidian-style graph visualization
• Timeline view for session and event history
• Cluster/outline view for grouped concepts
• Search view for graph exploration
• Node inspector with content, tags, metadata, timestamps, and relations
• Semantic node linking
• Typed nodes:
  • manual
  • memory
  • reasoning
  • tool-call
  • decision
  • session
  • error
• Tool-call tracking through Hermes hooks
• Reasoning snapshots through Hermes hooks
• Defensive hook handling so Mindscape does not crash Hermes
• WebSocket updates for live dashboard refreshes
• Generic seed demo for screenshots and testing

---

Build (local development)

Source lives in dashboard/src/index.js. esbuild bundles it to dashboard/dist/index.js.

cd ~/projects/privat/mindscape

# One-time setup
npm install

# Build (after any src/ change)
npm run build

# Watch mode (auto-rebuild on save)
npm run watch

Never edit dashboard/dist/index.js directly — it is generated by npm run build.

Symlinked into ~/.hermes/plugins/:

ln -s ~/projects/privat/mindscape ~/.hermes/plugins/mindscape

---

Install from GitHub

Install directly from GitHub:

hermes plugins install southy404/hermes-mindscape --enable

Or with a full Git URL:

hermes plugins install https://github.com/southy404/hermes-mindscape.git --enable

Then start Hermes Dashboard:

hermes dashboard

Open the Mindscape entry in the dashboard sidebar.

If the dashboard was already open, click Rescan dashboard extensions or hard refresh the browser:

Ctrl + Shift + R

---

Install from the Dashboard

In the Hermes Dashboard, go to:

Plugins → Install from GitHub / Git URL

Use:

southy404/hermes-mindscape

Then enable:

Enable after install

Click:

Install

After installation, rescan dashboard extensions so the sidebar picks up the Mindscape manifest.

---

Repository Layout

For GitHub installation, the repository root should be the plugin root:

hermes-mindscape/
├── plugin.yaml
├── manifest.json
├── __init__.py
├── plugin_api.py
├── README.md
├── LICENSE
├── graph/
│   ├── __init__.py
│   ├── store.py
│   └── events.py
├── hooks/
│   ├── __init__.py
│   └── graph_hooks.py
└── dashboard/
    └── dist/
        ├── index.js
        └── style.css

The plugin should not require users to copy files from a local Hermes checkout manually.

---

Plugin Manifest

plugin.yaml should use the public plugin name:

name: mindscape
version: "1.0.0"
description: Live cognitive graph and reasoning visualization plugin for Hermes Agent.
author: southy404

The dashboard manifest should point to the built dashboard files:

{
  "name": "mindscape",
  "displayName": "Mindscape",
  "description": "Live cognitive graph and reasoning visualization for Hermes Agent.",
  "entry": "dashboard/dist/index.js",
  "style": "dashboard/dist/style.css"
}

Adjust the manifest only if your final bundle path differs.

---

Usage

Start Hermes:

hermes chat

Example prompts:

Create a Mindscape node for this session summary.

Use Mindscape to map the architecture of this project.

Search Mindscape for reasoning nodes related to tool calls.

Then open the dashboard:

hermes dashboard

Use the Mindscape views:

• Graph — visual node-link map
• Timeline — chronological event and thought history
• Clusters — grouped concepts and tags
• Search — query graph nodes
• Inspector — selected node details, metadata, and relations

---

Seed Demo

Mindscape includes a generic seed demo for quick testing.

Start the dashboard first, then call:

curl -X POST "http://127.0.0.1:9119/api/plugins/mindscape/seed-demo"

Force reseed:

curl -X POST "http://127.0.0.1:9119/api/plugins/mindscape/seed-demo?force=true"

The demo should use generic Hermes concepts only, for example:

• Hermes Agent
• Tool System
• Session Layer
• Memory Layer
• Dashboard UI
• Mindscape Plugin
• Reasoning Snapshot
• Decision Node
• Error Node
• Project Architecture

Avoid personal demo content in the public repository.

---

Clear Local Graph Data

Mindscape stores local runtime graph data outside the plugin folder.

To reset the graph:

rm -f ~/.hermes/mindscape/graph.json

Then restart the dashboard or reload the Mindscape tab.

Do not commit runtime graph files to the repository.

---

Hermes Agent Challenge Demo Flow

Recommended submission title:

Mindscape: A Live Cognitive Graph for Hermes Agent

Suggested demo flow:

1. Install the plugin from GitHub.
2. Enable the plugin.
3. Start Hermes Dashboard.
4. Open the Mindscape tab.
5. Run the seed demo or ask Hermes to map a project.
6. Show the live graph.
7. Click a node and show the inspector.
8. Switch to Timeline.
9. Switch to Clusters.
10. Search for a concept like reasoning, tool, or session.

Example challenge prompt:

Analyze this Hermes plugin and create a cognitive graph of its architecture, tools, hooks, API routes, storage layer, dashboard UI, and risks. Use Mindscape nodes and meaningful relations.

What this demonstrates:

Mindscape turns Hermes Agent activity into visible, persistent graph structure. Tool calls, reasoning snapshots, decisions, sessions, and project architecture become inspectable nodes and relations instead of hidden chat history.

---

Troubleshooting

hermes plugin list fails

Use the plural command:

hermes plugins list

Plugin is installed but not visible in the sidebar

Rescan dashboard extensions from the dashboard UI, or restart the dashboard:

hermes dashboard

Then hard refresh:

Ctrl + Shift + R

Plugin 'mindscape' is not installed or bundled

Check the installed plugins:

hermes plugins list | grep mindscape

If you installed from GitHub, try reinstalling:

hermes plugins install southy404/hermes-mindscape --enable --force

/api/auth/me 401 Unauthorized

This is usually the local Hermes Dashboard auth check. If the dashboard works locally, it can usually be ignored during local testing.

dashboard-plugins/example/dist/index.js 404 Not Found

This is usually unrelated to Mindscape. It means another example dashboard plugin is referenced but missing its built bundle.

Disable or remove the example plugin reference, then restart the dashboard.

Browser still shows old UI

Hard refresh:

Ctrl + Shift + R

---

Development

Run Python syntax checks:

python3 -m py_compile __init__.py plugin_api.py graph/*.py hooks/*.py

Check the dashboard bundle:

node --check dashboard/dist/index.js

Recommended .gitignore:

__pycache__/
*.pyc
.env
.DS_Store
node_modules/
.hermes/
graph.json
*.log
screenshots/raw/
*.webm
*.mp4

Do not ignore:

dashboard/dist/index.js
dashboard/dist/style.css

Hermes should be able to install and run the plugin directly from GitHub without requiring a build step.

---

Future Ideas

• Project mapping workflow
• Reasoning replay timeline
• Graph snapshots
• SQLite storage option
• Import/export graph data
• 3D graph view
• Memory confidence scoring
• Multi-agent graph support
• Export to Markdown or Obsidian