better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/troubleshooting-agent-quality.md

@@ -0,0 +1,145 @@
+---
+sidebar_position: 27
+title: "Troubleshooting: \"My Agent Feels Dumber\""
+description: "A diagnostic checklist for when Hermes seems less capable than before or forgets things mid-session — model switches, context pressure, wrong context detection, and the frozen memory snapshot"
+---
+
+# Troubleshooting: "My Agent Feels Dumber"
+
+Sometimes Hermes seems less sharp than it was yesterday, or forgets something you told it twenty minutes ago. This is almost never mysterious — there's usually one specific, checkable cause. Work through this checklist in order: the steps are sorted by how often each one turns out to be the answer.
+
+## 1. Check which model the session is actually using
+
+**Symptom:** Answers are shallower, code quality dropped, reasoning feels off — across the board.
+
+**Check:** Run `/model` with no arguments to show the current model, or `/status` to see the session's model, provider, and profile in one view.
+
+**What it means:** A model switch is a capability change, and it's easy to end up on a different model than you think:
+
+- A plain `/model <name>` switch is **session-only** by default (unless `model.persist_switch_by_default: true` is set), so the model you're on may not match what's in `config.yaml`.
+- Changing the main model from the dashboard's Models page applies to **new sessions only** — an already-open chat keeps running whatever model it started with.
+- If you switched to a faster model for a simple task (a pattern [Tips & Best Practices](/guides/tips#choose-the-right-model) recommends), remember to switch back for complex reasoning work.
+
+If the model is wrong, `/model <name>` fixes it for this session; add `--global` to persist the change to `config.yaml`. Note that a mid-session switch resets the prompt cache, so the next turn re-reads the conversation at full input price — on a long session it can be cheaper to start fresh on the right model.
+
+## 2. Check context usage
+
+**Symptom:** The session started strong but responses are slowing down, getting truncated, or losing track of earlier details.
+
+**Check:** Run `/usage` to see token usage and context window state, or `/context` for a visual breakdown of what's occupying the window (system prompt, tool definitions, skills, memory, conversation) versus free space.
+
+**What it means:** Extended conversations accumulate messages and tool outputs, approaching context limits. When you notice degradation in a long session:
+
+```bash
+# Compress the conversation (summarizes history, preserves key context)
+/compress
+
+# Or start a fresh session
+/new
+```
+
+`/compress` summarizes the conversation history, dramatically reducing token count while preserving key context. `/compress here [N]` keeps the most recent N exchanges verbatim and summarizes the rest, and a focus topic (`/compress focus <topic>`) narrows what a full summary preserves.
+
+:::tip
+Use `/compress` regularly during long sessions rather than waiting for problems, and `/usage` periodically to see where you stand.
+:::
+
+## 3. Verify the detected context length
+
+**Symptom:** Context problems appear surprisingly early — the first long conversation already hits limits, or compression fires far sooner than the model's advertised window should allow.
+
+**Check:** Look at the CLI startup line — it shows the detected context length (e.g., `📊 Context limit: 128000 tokens`). You can also check with `/usage` during a session.
+
+**What it means:** Hermes may have auto-detected the wrong context length for your model. Set it explicitly:
+
+```yaml
+# In ~/.hermes/config.yaml
+model:
+  default: your-model-name
+  context_length: 131072  # your model's actual context window
+```
+
+Or for custom endpoints, per-model on the provider entry:
+
+```yaml
+providers:
+  my-server:
+    api: "http://localhost:11434/v1"
+    models:
+      qwen3.5:27b:
+        context_length: 64000
+```
+
+Ollama users: if you set a custom `num_ctx`, set the matching context length in Hermes — Ollama's `/api/show` reports the model's *maximum* context, not the effective `num_ctx` you configured. On a running gateway, edits to `model.context_length` or any `compression.*` key take effect on the next message — no restart needed.
+
+See [Context Length Detection](/integrations/providers#context-length-detection) for how auto-detection works and all override options.
+
+## 4. "I told it something and it forgot" — the frozen memory snapshot
+
+**Symptom:** You asked Hermes to remember something during this session, it confirmed the save, but later in the *same* session it doesn't seem to know it.
+
+**Check:** Nothing is broken — check the timing. Memory saved mid-session is written to disk immediately, but the system prompt won't reflect it until the next session.
+
+**What it means:** This is documented, intentional behavior. Memory is injected into the system prompt as a **frozen snapshot at session start**, and that injection never changes mid-session — it preserves the LLM's prefix cache for performance. When the agent adds or removes memory entries during a session, the changes persist to disk right away but appear in the system prompt only when the next session starts. Tool responses always show the live state, so the save itself is confirmed and real.
+
+:::info
+Frozen snapshot in practice: "remember X" during a session means X is guaranteed available **next** session. Within the current session, the fact still exists in the conversation history itself — the agent forgets it only if that part of the conversation has since been compressed away (see step 7).
+:::
+
+See [Persistent Memory](/user-guide/features/memory#how-memory-appears-in-the-system-prompt) for the full mechanics.
+
+## 5. Memory is bounded and curated — not a transcript
+
+**Symptom:** Hermes doesn't recall a detail from a session last week, even though you discussed it at length.
+
+**Check:** Memory capacity and contents. The system prompt memory header shows usage (e.g., `[67% — 1,474/2,200 chars]`), and `hermes journey list` shows every saved memory entry and skill.
+
+**What it means:** Persistent memory is intentionally bounded — 2,200 chars (~800 tokens) for MEMORY.md and 1,375 chars (~500 tokens) for USER.md. It holds curated key facts, not conversation transcripts. Things worth saving are preferences, environment facts, conventions, and corrections; raw discussion detail is not stored there by design.
+
+For "did we discuss X last week?" recall, the agent has a separate mechanism: `session_search` queries all past sessions (stored in SQLite with full-text search) and can find things discussed weeks ago even when they're not in active memory. Just ask — "search our past sessions for the deploy discussion."
+
+You can also help directly: say "remember this for next time" after a productive session, or "clean up your memory" when it's near capacity so the agent consolidates entries. See [Memory & Skills tips](/guides/tips#memory--skills) and [Capacity Management](/user-guide/features/memory#capacity-management).
+
+## 6. Check that skills and tools are loaded
+
+**Symptom:** Hermes used to handle a specific workflow expertly and now approaches it naively, or says it can't do something it did before.
+
+**Check:**
+
+- `/skills` — browse installed skills (a skill the agent relied on may have been removed).
+- `/reload-skills` — re-scan `~/.hermes/skills/` for newly installed or removed skills.
+- `/tools list` — see available tools; a tool disabled earlier with `/tools disable` stays out of the agent's toolset for the session.
+- `/context all` — per-skill and per-toolset cost listing, which doubles as an inventory of what's actually loaded.
+
+**What it means:** Skills are the agent's procedural knowledge — multi-step workflows and tool-specific instructions. If a skill is missing or a toolset was trimmed (e.g., a session started with `hermes chat -t "terminal"` to reduce prompt weight), the agent genuinely has less to work with in that session. Re-enable tools with `/tools enable`, or invoke the skill explicitly by name (`/github-pr-workflow`) to confirm it loads.
+
+## 7. Compression side-effects
+
+**Symptom:** After a long session (or right after running `/compress`), Hermes remembers the broad strokes but has lost fine detail from earlier in the conversation.
+
+**Check:** Whether compression has fired — `/usage` and `/context` show compression stats and context state on messaging platforms, and manual `/compress` always reports its result.
+
+**What it means:** Compression replaces older conversation history with a summary — that's the point, and it necessarily trades detail for headroom. Know the shape of it:
+
+- Recent messages are protected: by default the last 20 messages stay uncompressed (`protect_last_n`) and the opening exchange is pinned (`protect_first_n: 3`) so the original goal stays visible.
+- Compaction is non-destructive: with the default `compression.in_place: true`, the session keeps one durable id and pre-compaction turns are soft-archived — still searchable via `session_search` and recoverable, not deleted.
+- With `in_place: false` (legacy behavior), each compaction rotates to a **new session linked to the old one** — a titled session becomes `"my project" → "my project #2" → "my project #3"`. If you resume by title, `hermes -c "my project"` automatically picks the most recent variant.
+- A focus topic narrows what a full summary preserves: `/compress focus auth-refactor` keeps that thread's detail at the expense of the rest.
+
+If a compressed-away detail matters, ask the agent to search for it (`session_search` reaches the archived turns), or re-paste the key facts into the conversation.
+
+See [Context Compression](/user-guide/configuration#context-compression) for the full settings reference and [Auto-Lineage on Compression](/user-guide/sessions#auto-lineage-on-compression) for how titled sessions chain.
+
+---
+
+## Quick reference
+
+| Symptom | First command | Likely cause |
+|---------|--------------|--------------|
+| Everything feels less capable | `/model` | Session is on a different model than you think |
+| Long session degrading | `/usage` | Context pressure — compress or start fresh |
+| Limits hit surprisingly early | CLI startup line / `/usage` | Wrong auto-detected context length |
+| Forgot what I said this session | — (by design) | Frozen memory snapshot — appears next session |
+| Forgot last week's discussion | ask it to `session_search` | Memory is bounded, curated facts only |
+| Lost a specific ability | `/skills`, `/tools list` | Skill or toolset not loaded this session |
+| Lost old detail after long session | `/usage`, `/context` | Compression summarized older history |

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/use-mcp-with-hermes.md

@@ -0,0 +1,541 @@
+---
+sidebar_position: 6
+title: "Use MCP with Hermes"
+description: "A practical guide to connecting MCP servers to Hermes Agent, filtering their tools, and using them safely in real workflows"
+---
+
+# Use MCP with Hermes
+
+This guide shows how to actually use MCP with Hermes Agent in day-to-day workflows.
+
+If the feature page explains what MCP is, this guide is about how to get value from it quickly and safely.
+
+## When should you use MCP?
+
+Use MCP when:
+- a tool already exists in MCP form and you do not want to build a native Hermes tool
+- you want Hermes to operate against a local or remote system through a clean RPC layer
+- you want fine-grained per-server exposure control
+- you want to connect Hermes to internal APIs, databases, or company systems without modifying Hermes core
+
+Do not use MCP when:
+- a built-in Hermes tool already solves the job well
+- the server exposes a huge dangerous tool surface and you are not prepared to filter it
+- you only need one very narrow integration and a native tool would be simpler and safer
+
+## Mental model
+
+Think of MCP as an adapter layer:
+
+- Hermes remains the agent
+- MCP servers contribute tools
+- Hermes discovers those tools at startup or reload time
+- the model can use them like normal tools
+- you control how much of each server is visible
+
+That last part matters. Good MCP usage is not just “connect everything.” It is “connect the right thing, with the smallest useful surface.”
+
+## Step 1: install MCP support
+
+If you installed Hermes with the standard install script, MCP support is already included (the installer runs `uv pip install -e ".[all]"`).
+
+If you installed without extras and need to add MCP separately:
+
+```bash
+cd ~/.hermes/hermes-agent
+uv pip install -e ".[mcp]"
+```
+
+For npm-based servers, make sure Node.js and `npx` are available.
+
+For many Python MCP servers, `uvx` is a nice default.
+
+## Step 2: add one server first
+
+Start with a single, safe server.
+
+Example: filesystem access to one project directory only.
+
+```yaml
+mcp_servers:
+  project_fs:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]
+```
+
+Then start Hermes:
+
+```bash
+hermes chat
+```
+
+Now ask something concrete:
+
+```text
+Inspect this project and summarize the repo layout.
+```
+
+## Step 3: verify MCP loaded
+
+You can verify MCP in a few ways:
+
+- Hermes banner/status should show MCP integration when configured
+- ask Hermes what tools it has available
+- use `/reload-mcp` after config changes
+- check logs if the server failed to connect
+
+A practical test prompt:
+
+```text
+Tell me which MCP-backed tools are available right now.
+```
+
+## Step 4: start filtering immediately
+
+Do not wait until later if the server exposes a lot of tools.
+
+### Example: whitelist only what you want
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
+    tools:
+      include: [list_issues, create_issue, search_code]
+```
+
+This is usually the best default for sensitive systems.
+
+## WSL2: bridge Hermes in WSL to Windows Chrome
+
+This is the practical setup when:
+
+- Hermes runs inside WSL2
+- the browser you want to control is your normal signed-in Chrome on Windows
+- `/browser connect` is awkward or unreliable from WSL
+
+In this setup, Hermes does **not** connect to Chrome directly. Instead:
+
+- Hermes runs in WSL
+- Hermes starts a local stdio MCP server
+- that MCP server is launched through Windows interop (`cmd.exe` or `powershell.exe`)
+- the MCP server attaches to your live Windows Chrome session
+
+Mental model:
+
+```text
+Hermes (WSL) -> MCP stdio bridge -> Windows Chrome
+```
+
+### Why this mode is useful
+
+- you keep your real Windows browser profile, cookies, and logins
+- Hermes stays in its supported Unix environment (WSL2)
+- browser control is exposed as MCP tools instead of relying on Hermes core browser transport
+
+### Recommended server
+
+Use `chrome-devtools-mcp`.
+
+If your Windows Chrome already has live remote debugging enabled from `chrome://inspect/#remote-debugging`, add it like this from WSL:
+
+```bash
+hermes mcp add chrome-devtools-win --command cmd.exe --args /c npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics
+```
+
+After saving the server:
+
+```bash
+hermes mcp test chrome-devtools-win
+```
+
+Then start a fresh Hermes session or run:
+
+```text
+/reload-mcp
+```
+
+### Typical prompt
+
+Once loaded, Hermes can use the MCP-prefixed browser tools directly. For example:
+
+```text
+调用 MCP 工具 mcp_chrome_devtools_win_list_pages，列出当前浏览器标签页。
+```
+
+### When `/browser connect` is the wrong tool
+
+If Hermes runs in WSL and Chrome runs on Windows, `/browser connect` may fail even though Chrome is open and debuggable.
+
+Common reasons:
+
+- WSL cannot reach the same host-local endpoint Chrome exposes to Windows tools
+- newer Chrome live-debugging flows are not the same as a classic `ws://localhost:9222`
+- the browser is easier to attach to from a Windows-side helper like `chrome-devtools-mcp`
+
+In those cases, keep `/browser connect` for same-environment setups and use MCP for WSL-to-Windows browser bridging.
+
+### Known pitfalls
+
+- Start Hermes from a Windows-mounted path like `/mnt/c/Users/<you>` or `/mnt/c/workspace/...` when using Windows stdio executables through MCP.
+- If you start Hermes from `/root` or `/home/...`, Windows may emit a `UNC` current-directory warning before the MCP server starts.
+- If `chrome-devtools-mcp --autoConnect` times out while enumerating pages, reduce background/frozen tabs in Chrome and retry.
+
+### Example: blacklist dangerous actions
+
+```yaml
+mcp_servers:
+  stripe:
+    url: "https://mcp.stripe.com"
+    headers:
+      Authorization: "Bearer ***"
+    tools:
+      exclude: [delete_customer, refund_payment]
+```
+
+### Example: disable utility wrappers too
+
+```yaml
+mcp_servers:
+  docs:
+    url: "https://mcp.docs.example.com"
+    tools:
+      prompts: false
+      resources: false
+```
+
+## What does filtering actually affect?
+
+There are two categories of MCP-exposed functionality in Hermes:
+
+1. Server-native MCP tools
+- filtered with:
+  - `tools.include`
+  - `tools.exclude`
+
+2. Hermes-added utility wrappers
+- filtered with:
+  - `tools.resources`
+  - `tools.prompts`
+
+### Utility wrappers you may see
+
+Resources:
+- `list_resources`
+- `read_resource`
+
+Prompts:
+- `list_prompts`
+- `get_prompt`
+
+These wrappers only appear if:
+- your config allows them, and
+- the MCP server session actually supports those capabilities
+
+So Hermes will not pretend a server has resources/prompts if it does not.
+
+## Common patterns
+
+### Pattern 1: local project assistant
+
+Use MCP for a repo-local filesystem or git server when you want Hermes to reason over a bounded workspace.
+
+```yaml
+mcp_servers:
+  fs:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]
+
+  git:
+    command: "uvx"
+    args: ["mcp-server-git", "--repository", "/home/user/project"]
+```
+
+Good prompts:
+
+```text
+Review the project structure and identify where configuration lives.
+```
+
+```text
+Check the local git state and summarize what changed recently.
+```
+
+### Pattern 2: repo-native work record with Open Scaffold
+
+Use [Open Scaffold](https://github.com/graphanov/open-scaffold) when you want Hermes to read a repository's durable AI-work record: mission, plans, evidence notes, handoff packets, and review/gate results. Hermes remains the agent; Open Scaffold remains the repo-local record.
+
+Add the server for one scaffolded repository:
+
+```bash
+hermes mcp add open_scaffold --command npx --args -y open-scaffold@latest mcp serve --repo /absolute/path/to/repo
+hermes mcp test open_scaffold
+```
+
+Then keep the exposed surface read-oriented. Choose `select` in the `hermes mcp add` prompt, or edit `config.yaml` afterward:
+
+```yaml
+mcp_servers:
+  open_scaffold:
+    command: "npx"
+    args: ["-y", "open-scaffold@latest", "mcp", "serve", "--repo", "/absolute/path/to/repo"]
+    tools:
+      include:
+        - list_plans
+        - get_plan
+        - get_mission
+        - list_evidence
+        - get_evidence
+        - get_status
+        - search_plans
+        - list_amendments
+        - get_handoff
+        - analyze_loop
+        - gate_loop
+      prompts: false
+```
+
+Good prompts:
+
+```text
+Use the Open Scaffold MCP tools to compile the current handoff packet and tell me the next legal action.
+```
+
+```text
+Inspect the active plans and evidence notes, then say whether this repo is ready for human review or needs another attempt.
+```
+
+Boundary notes:
+
+- Open Scaffold MCP is local-first and read-only by default.
+- Its write tools require the server to be started with `--allow-write`; do not enable that until you explicitly want Hermes to mutate `.osc` files.
+- Open Scaffold records and gates work; it does not authorize Hermes to merge, publish, deploy, or spawn runtimes.
+- Pin `open-scaffold@<version>` instead of `@latest` if you need reproducible tool schemas.
+
+### Pattern 3: GitHub triage assistant
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
+    tools:
+      include: [list_issues, create_issue, update_issue, search_code]
+      prompts: false
+      resources: false
+```
+
+Good prompts:
+
+```text
+List open issues about MCP, cluster them by theme, and draft a high-quality issue for the most common bug.
+```
+
+```text
+Search the repo for uses of _discover_and_register_server and explain how MCP tools are registered.
+```
+
+### Pattern 4: internal API assistant
+
+```yaml
+mcp_servers:
+  internal_api:
+    url: "https://mcp.internal.example.com"
+    headers:
+      Authorization: "Bearer ***"
+    tools:
+      include: [list_customers, get_customer, list_invoices]
+      resources: false
+      prompts: false
+```
+
+Good prompts:
+
+```text
+Look up customer ACME Corp and summarize recent invoice activity.
+```
+
+This is the sort of place where a strict whitelist is far better than an exclude list.
+
+### Pattern 4: documentation / knowledge servers
+
+Some MCP servers expose prompts or resources that are more like shared knowledge assets than direct actions.
+
+```yaml
+mcp_servers:
+  docs:
+    url: "https://mcp.docs.example.com"
+    tools:
+      prompts: true
+      resources: true
+```
+
+Good prompts:
+
+```text
+List available MCP resources from the docs server, then read the onboarding guide and summarize it.
+```
+
+```text
+List prompts exposed by the docs server and tell me which ones would help with incident response.
+```
+
+## Tutorial: end-to-end setup with filtering
+
+Here is a practical progression.
+
+### Phase 1: add GitHub MCP with a tight whitelist
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
+    tools:
+      include: [list_issues, create_issue, search_code]
+      prompts: false
+      resources: false
+```
+
+Start Hermes and ask:
+
+```text
+Search the codebase for references to MCP and summarize the main integration points.
+```
+
+### Phase 2: expand only when needed
+
+If you later need issue updates too:
+
+```yaml
+tools:
+  include: [list_issues, create_issue, update_issue, search_code]
+```
+
+Then reload:
+
+```text
+/reload-mcp
+```
+
+### Phase 3: add a second server with different policy
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
+    tools:
+      include: [list_issues, create_issue, update_issue, search_code]
+      prompts: false
+      resources: false
+
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]
+```
+
+Now Hermes can combine them:
+
+```text
+Inspect the local project files, then create a GitHub issue summarizing the bug you find.
+```
+
+That is where MCP gets powerful: multi-system workflows without changing Hermes core.
+
+## Safe usage recommendations
+
+### Prefer allowlists for dangerous systems
+
+For anything financial, customer-facing, or destructive:
+- use `tools.include`
+- start with the smallest set possible
+
+### Disable unused utilities
+
+If you do not want the model browsing server-provided resources/prompts, turn them off:
+
+```yaml
+tools:
+  resources: false
+  prompts: false
+```
+
+### Keep servers scoped narrowly
+
+Examples:
+- filesystem server rooted to one project dir, not your whole home directory
+- git server pointed at one repo
+- internal API server with read-heavy tool exposure by default
+
+### Reload after config changes
+
+```text
+/reload-mcp
+```
+
+Do this after changing:
+- include/exclude lists
+- enabled flags
+- resources/prompts toggles
+- auth headers / env
+
+## Troubleshooting by symptom
+
+### "The server connects but the tools I expected are missing"
+
+Possible causes:
+- filtered by `tools.include`
+- excluded by `tools.exclude`
+- utility wrappers disabled via `resources: false` or `prompts: false`
+- server does not actually support resources/prompts
+
+### "The server is configured but nothing loads"
+
+Check:
+- `enabled: false` was not left in config
+- command/runtime exists (`npx`, `uvx`, etc.)
+- HTTP endpoint is reachable
+- auth env or headers are correct
+
+### "Why do I see fewer tools than the MCP server advertises?"
+
+Because Hermes now respects your per-server policy and capability-aware registration. That is expected, and usually desirable.
+
+### "How do I remove an MCP server without deleting the config?"
+
+Use:
+
+```yaml
+enabled: false
+```
+
+That keeps the config around but prevents connection and registration.
+
+## Recommended first MCP setups
+
+Good first servers for most users:
+- filesystem
+- git
+- GitHub
+- fetch / documentation MCP servers
+- one narrow internal API
+
+Not-great first servers:
+- giant business systems with lots of destructive actions and no filtering
+- anything you do not understand well enough to constrain
+
+## Related docs
+
+- [MCP (Model Context Protocol)](/user-guide/features/mcp)
+- [FAQ](/reference/faq)
+- [Slash Commands](/reference/slash-commands)