Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Hermes-LCM is a lossless context management plugin for Hermes Agent that prevents message loss during context compression. Instead of replacing old messages with flat summaries, it:
Stores all messages in SQLite before compaction
Compacts old context into a hierarchical summary DAG
Provides agent tools to drill back into compacted material
Maintains source lineage for filtered retrieval
Externalizes large payloads to prevent bloat
Key difference from built-in compression: LCM makes recall part of the active context engine with drill-down tools (lcm_grep, lcm_expand, lcm_expand_query) rather than relying on auxiliary cross-session search.
Installation
Standard Installation
Clone into Hermes plugins directory:
# General user plugin (all profiles)
git clone https://github.com/stephenschoettler/hermes-lcm \
~/.hermes/plugins/hermes-lcm
git https://github.com/stephenschoettler/hermes-lcm \
~/.hermes/profiles/myprofile/plugins/hermes-lcm
# Profile-specific install
clone
Symlink Installation
From an existing checkout:
cd hermes-lcm
./scripts/install.sh
# Profile-specific
HERMES_PROFILE=myprofile ./scripts/install.sh
Configuration
Enable in Hermes config (YAML):
plugins:enabled:-hermes-lcmcontext:engine:lcm# Keep compression enabled - LCM needs this gatecompression:enabled:true
# Check status
/lcm status
# Search
/lcm grep pattern search_raw=true# Describe summary
/lcm describe summary_id=s_abc123
# Expand
/lcm expand summary_id=s_abc123 max_raw=20
# Query
/lcm query What was discussed about the API?
# Doctor
/lcm doctor check
/lcm doctor clean_preview
Common Patterns
Initial Setup After Installation
# 1. Verify installation
hermes plugins
# 2. Send a test message to initialize session
hermes chat "Hello"# 3. Check LCM status
hermes chat "Can you run lcm_status?"# 4. Verify tools are available# Agent should have access to lcm_grep, lcm_expand, etc.
# Check current stateexport LCM_ENABLE_SLASH_COMMAND=true
hermes chat "/lcm status"# Run diagnostics
hermes chat "/lcm doctor check"# Preview cleanup
hermes chat "/lcm doctor clean_preview"# Check for orphaned summaries or raw messages# Doctor will report:# - Orphaned summaries (no parent)# - Dangling raw messages (session mismatch)# - Missing required tables
Session Isolation
# Exclude test sessions from LCMexport LCM_IGNORE_SESSION_PATTERNS="test-*,temp-*,debug-*"# Keep readonly sessions from being storedexport LCM_STATELESS_SESSION_PATTERNS="readonly-*,audit-*"# Restart Hermes
hermes restart
Large Payload Management
# Enable external storage for large outputsexport LCM_LARGE_OUTPUT_EXTERNALIZATION_ENABLED=trueexport LCM_LARGE_OUTPUT_EXTERNALIZATION_THRESHOLD_CHARS=12000
# Enable transcript GC for already-externalized contentexport LCM_LARGE_OUTPUT_TRANSCRIPT_GC_ENABLED=true# Restart Hermes
hermes restart
External payloads stored in:
~/.hermes/profiles/<profile>/lcm_externalized/
Troubleshooting
Plugin Shows as Not Found
Symptom: hermes plugins shows lcm (not found) but tools exist
Solution: If tools are available, LCM is loaded. This is a host discovery mismatch, not a plugin failure.
# Verify tools exist
hermes chat "Run lcm_status"# If tools work, plugin is functional
Status Shows Unbound After Restart
Symptom: /lcm status shows session_id: (unbound) or threshold_tokens: (uninitialized)
Solution: Send one normal message first:
hermes chat "Hello"
hermes chat "/lcm status"# Now shows live session data
Compaction Not Triggering
Check threshold calculation:
# Get current context window
hermes chat "What's your context window?"# Calculate expected trigger# trigger = context_window * LCM_CONTEXT_THRESHOLD# Example: 128K window, 0.75 threshold = 96K triggerexport LCM_CONTEXT_THRESHOLD=0.75
Verify compression is enabled:
# In Hermes configcompression:enabled:true# Must be true
Missing Regex Message Filtering
Symptom: Warning about disabled message-level regex filtering
Solution: Install regex package:
pip install regex
LCM uses regex with timeouts to prevent unbounded pattern matching. Without it, LCM_IGNORE_MESSAGE_PATTERNS is disabled.
High Token Costs
Tune threshold for your model:
# For 1M token model, don't wait until 750K# Trigger earlier to reduce costs# Trigger at 250K (25% of 1M)export LCM_CONTEXT_THRESHOLD=0.25
# Trigger at 400K (40% of 1M)export LCM_CONTEXT_THRESHOLD=0.40
Database Corruption
# Run doctor checkexport LCM_ENABLE_SLASH_COMMAND=true
hermes chat "/lcm doctor check"# Preview cleanup
hermes chat "/lcm doctor clean_preview"# Apply cleanup (if safe)export LCM_DOCTOR_CLEAN_APPLY_ENABLED=true
hermes chat "/lcm doctor clean_apply"
Update Plugin
# From plugin directorycd ~/.hermes/plugins/hermes-lcm
git pull --ff-only
# Or for symlinked installcd /path/to/hermes-lcm
./scripts/update.sh
# Restart Hermes
hermes restart
Integration Examples
Python Code Using LCM Tools
# Example: Agent helper to search and expand contextasyncdefrecover_context(topic: str, max_depth: int = 2):
"""Search LCM and expand results to recover context."""# Search for topic
grep_result = await hermes.call_tool("lcm_grep", {
"pattern": topic,
"search_raw": True,
"search_summaries": True,
"max_results": 5
})
ifnot grep_result.get("matches"):
returnf"No context found for: {topic}"# Expand first match
first_match = grep_result["matches"][0]
if"summary_id"in first_match:
expand_result = await hermes.call_tool("lcm_expand", {
"summary_id": first_match["summary_id"],
"max_raw": 10
})
return expand_result
return first_match
asyncdefquery_history(question: str, scope_summary_id: str = None):
"""Ask a question about compacted history."""
params = {"query": question, "max_raw": 50}
if scope_summary_id:
params["summary_id"] = scope_summary_id
result = await hermes.call_tool("lcm_expand_query", params)
return result.get("answer", "No answer generated")
