hermes-context-inspector

Inspect Hermes agent context management - token usage, compression events, skill pruning

Problem

Hermes agents manage context automatically but provide no visibility:

Token limits hit silently - context compressed without notification
Skills pruned unexpectedly - capabilities disappear mid-conversation
No compression history - can't debug why context was reduced
Token usage unknown - no tracking of costs or limits
Session forensics impossible - can't reconstruct what happened

Solution

hermes-context-inspector provides read-only inspection of all context management:

Inspection	Reveals
Token Usage	Per-message tokens, models, providers, compression flags
Compression Events	When, why, how much context was reduced
Skill Pruning	Which skills removed, why, context saved
Session Reconstruction	Full session timeline with all events
Health Analysis	Issues/warnings per session
Config Validation	Token limits, thresholds, auto-compress settings

Installation

pip install hermes-context-inspector

Or run directly:

python -m hermes_context_inspector summary

Quick Start

# Overall context health summary
hermes-context-inspector summary

# List recent sessions
hermes-context-inspector sessions

# Reconstruct specific session
hermes-context-inspector session abc123

# Show compression events for session
hermes-context-inspector compressions abc123

# Show skill prune events
hermes-context-inspector prunes abc123

# Analyze session health
hermes-context-inspector health abc123

# Show token usage history
hermes-context-inspector usage abc123

# Show token limit configuration
hermes-context-inspector config

# Machine-readable JSON output
hermes-context-inspector summary --json

Commands

`summary` - Overall Context Health

hermes-context-inspector summary [OPTIONS]

Options:
  --profile TEXT      Hermes profile (default: default)
  --hermes-home PATH  Override Hermes home directory
  --json              Output as JSON

`sessions` - List Recent Sessions

hermes-context-inspector sessions [OPTIONS]

Options:
  --profile TEXT      Hermes profile
  --hermes-home PATH  Override Hermes home
  --json              Output as JSON
  --limit INT         Number of sessions (default: 20)

`session` - Reconstruct Session

hermes-context-inspector session SESSION_ID [OPTIONS]

Options:
  --profile TEXT      Hermes profile
  --hermes-home PATH  Override Hermes home
  --json              Output as JSON
  --verbose, -v       Show loaded/pruned skills, models, providers

`compressions` - Compression Events

hermes-context-inspector compressions SESSION_ID [OPTIONS]

Options:
  --profile TEXT      Hermes profile
  --hermes-home PATH  Override Hermes home
  --json              Output as JSON
  --verbose, -v       Show summaries and pruned skills
  --limit INT         Number of events (default: 50)

`prunes` - Skill Prune Events

hermes-context-inspector prunes SESSION_ID [OPTIONS]

Options:
  --profile TEXT      Hermes profile
  --hermes-home PATH  Override Hermes home
  --json              Output as JSON
  --verbose, -v       Verbose output
  --limit INT         Number of events (default: 50)

`health` - Session Health Analysis

hermes-context-inspector health SESSION_ID [OPTIONS]

Options:
  --profile TEXT      Hermes profile
  --hermes-home PATH  Override Hermes home
  --json              Output as JSON

Exit codes: 0 = healthy/warning, 1 = critical/not found

`usage` - Token Usage History

hermes-context-inspector usage [SESSION_ID] [OPTIONS]

Options:
  --profile TEXT      Hermes profile
  --hermes-home PATH  Override Hermes home
  --json              Output as JSON
  --limit INT         Number of records (default: 100)

`config` - Token Limit Configuration

hermes-context-inspector config [OPTIONS]

Options:
  --profile TEXT      Hermes profile
  --hermes-home PATH  Override Hermes home
  --json              Output as JSON

Example Output

Human-readable (default)

╭──────────────────────────────────────────────────────────────────────────────╮
│                         Context Management Summary                          │
╰──────────────────────────────────────────────────────────────────────────────╯
Config:
  Max Tokens: 128000
  Context Window: 128000
  Compression Threshold: 0.85
  Auto Compress: True

Recent Sessions (5):
  Total Messages: 1,234
  Total Tokens: 2,456,789
  Avg Peak: 98,765

Compression Stats:
  Sessions w/ Compression: 3
  Total Events: 7
  Skills Pruned: 2

Health Distribution:
  Healthy: 2
  Warning: 2
  Critical: 1

╭──────────────────────── abc123... (WARNING) ────────────────────────────────╮
│ Started: 2026-08-25 22:00:00                                                 │
│ Ended: 2026-08-26 06:30:00                                                   │
│ Messages: 245                                                                │
│ Total Tokens: 892,341                                                        │
│ Peak Tokens: 118,500                                                         │
│ Avg Tokens/Msg: 3,642                                                        │
│ Compression Events: 3                                                        │
│ Skills Loaded: 8                                                             │
│ Skills Pruned: 1                                                             │
│                                                                              │
│ Loaded Skills: session-continuity, pattern-memory, code-review, ...         │
│ Pruned Skills: heavy-analysis                                                │
│ Models: nemotron-3-ultra, llama-3.1-70b                                      │
│ Providers: novita, nvidia                                                    │
╰──────────────────────────────────────────────────────────────────────────────╯

╭──────────────────── token_limit - 118,500 → 95,200 tokens (80.3%) ─────────╮
│ Time: 2026-08-26 02:15:00                                                    │
│ Session: abc123...                                                           │
│ Messages: 180 → 145                                                          │
│ Tokens Saved: 23,300                                                         │
│                                                                              │
│ Summary: Compressed due to token limit (85% threshold). Preserved recent    │
│          context and tool outputs.                                           │
│                                                                              │
│ Pruned Skills: heavy-analysis                                                │
╰──────────────────────────────────────────────────────────────────────────────╯

JSON Output

{
  "config": {
    "max_tokens": 128000,
    "context_window": 128000,
    "compression_threshold": 0.85,
    "auto_compress": true,
    "summarize_threshold": 0.7,
    "skill_memory_limit_kb": 512
  },
  "recent_sessions": {
    "count": 5,
    "total_messages": 1234,
    "total_tokens": 2456789,
    "avg_peak_tokens": 98765.4
  },
  "compression_stats": {
    "sessions_with_compression": 3,
    "total_compression_events": 7,
    "total_skills_pruned": 2
  },
  "health_distribution": {
    "healthy": 2,
    "warning": 2,
    "critical": 1
  }
}

As a Library

from hermes_context_inspector import ContextInspector, inspect_context

# One-off summary
summary = inspect_context(hermes_home="/custom/.hermes", profile="production")
print(f"Critical sessions: {summary['health_distribution']['critical']}")

# Reusable inspector
inspector = ContextInspector(profile="staging")

# Reconstruct session
ctx = inspector.reconstruct_session("abc123")
if ctx:
    print(f"Peak tokens: {ctx.peak_tokens:,}")
    print(f"Compressions: {ctx.compression_events}")
    print(f"Skills pruned: {ctx.skills_pruned}")

# Get compression events
for event in inspector.get_compression_events("abc123"):
    print(f"{event.reason.value}: {event.tokens_before:,} → {event.tokens_after:,}")

# Get skill prune events
for event in inspector.get_skill_prune_events("abc123"):
    print(f"{event.skill_name}: {event.reason.value} ({event.context_before_kb:.1f} KB → {event.context_after_kb:.1f} KB)")

# Health analysis
health = inspector.analyze_session_health("abc123")
if health["status"] == "critical":
    for issue in health["issues"]:
        print(f"ISSUE: {issue}")

# Token usage
for usage in inspector.get_token_usage("abc123"):
    print(f"{usage.timestamp}: {usage.total_tokens:,} tokens ({usage.model}@{usage.provider})")

Compression Reasons

Reason	Description
`token_limit`	Context exceeded token threshold (configurable)
`auto_summarize`	Automatic summarization triggered
`skill_pruned`	Skills removed to free context space
`manual`	User-initiated compression
`unknown`	Reason not recorded

Skill Prune Reasons

Reason	Description
`context_limit`	Pruned to stay within token budget
`unused`	Skill not used in recent messages
`error`	Skill caused errors
`manual`	User explicitly removed
`unknown`	Reason not recorded

Data Sources

The inspector reads from (read-only):

sessions.db - Session metadata, token usage, compression events
memory.db - Skill memory, prune events
config.yaml - Token limits, compression thresholds
logs/ - Additional context (if available)

CI/CD Integration

# .github/workflows/check-context.yml
name: Check Context Health
on:
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours
  push:
    branches: [main]

jobs:
  context-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install hermes-context-inspector
      - run: hermes-context-inspector summary --json > context-health.json
        env:
          HERMES_HOME: ${{ github.workspace }}/.hermes
      - uses: actions/upload-artifact@v4
        with:
          name: context-health
          path: context-health.json
      # Alert if critical sessions
      - run: |
          python -c "
          import json, sys
          with open('context-health.json') as f:
              data = json.load(f)
          critical = data['health_distribution']['critical']
          if critical > 0:
              print(f'ALERT: {critical} critical sessions!')
              sys.exit(1)
          "

Why This Exists

Hermes automatically compresses context and prunes skills to stay within token limits, but this happens invisibly. When a skill disappears or context is lost, there's no way to know why. This tool makes the invisible visible.

License

MIT License - see LICENSE

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
examples		examples
src/hermes_context_inspector		src/hermes_context_inspector
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Navigation Menu

Repository files navigation

hermes-context-inspector

Problem

Solution

Installation

Quick Start

Commands

`summary` - Overall Context Health

`sessions` - List Recent Sessions

`session` - Reconstruct Session

`compressions` - Compression Events

`prunes` - Skill Prune Events

`health` - Session Health Analysis

`usage` - Token Usage History

`config` - Token Limit Configuration

Example Output

Human-readable (default)

JSON Output

As a Library

Compression Reasons

Skill Prune Reasons

Data Sources

CI/CD Integration

Why This Exists

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

hermes-context-inspector

Problem

Solution

Installation

Quick Start

Commands

summary - Overall Context Health

sessions - List Recent Sessions

session - Reconstruct Session

compressions - Compression Events

prunes - Skill Prune Events

health - Session Health Analysis

usage - Token Usage History

config - Token Limit Configuration

Example Output

Human-readable (default)

JSON Output

As a Library

Compression Reasons

Skill Prune Reasons

Data Sources

CI/CD Integration

Why This Exists

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`summary` - Overall Context Health

`sessions` - List Recent Sessions

`session` - Reconstruct Session

`compressions` - Compression Events

`prunes` - Skill Prune Events

`health` - Session Health Analysis

`usage` - Token Usage History

`config` - Token Limit Configuration