hermes-lcm-context-management

Hermes LCM Context Management

Skill by ara.so — Hermes Skills collection.

Overview

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

# Profile-specific install
git clone https://github.com/stephenschoettler/hermes-lcm \
  ~/.hermes/profiles/myprofile/plugins/hermes-lcm

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-lcm

context:
  engine: lcm

# Keep compression enabled - LCM needs this gate
compression:
  enabled: true

Restart Hermes after configuration changes.

Verification

hermes plugins

Expected output includes:

• Plugin list shows hermes-lcm
• Context engine shows lcm
• Tools include: lcm_grep, lcm_describe, lcm_expand, lcm_expand_query, lcm_status, lcm_doctor, lcm_load_session

Core Concepts

Message Storage

LCM stores messages in SQLite before compaction happens:

~/.hermes/profiles/<profile>/lcm.db  # Default path

Summary DAG

Old messages are compacted into hierarchical summary nodes:

Raw messages → Leaf summaries → Branch summaries → Root

Each node tracks:

• Descendant message count
• Source lineage (for filtering)
• Depth in DAG
• Token counts

Bounded Recovery

Agent can page back into compacted material without flooding active context:

• lcm_grep: Search raw messages and summaries
• lcm_describe: Get summary metadata
• lcm_expand: Retrieve child summaries or raw messages
• lcm_expand_query: Synthesize answer from DAG material

Environment Configuration

Core Settings

# Compaction trigger (fraction of context window)
export LCM_CONTEXT_THRESHOLD=0.75

# Recent messages protected from compaction
export LCM_FRESH_TAIL_COUNT=64

# Raw backlog floor before leaf compaction
export LCM_LEAF_CHUNK_TOKENS=20000

# Enable dynamic chunk-sized leaf compaction
export LCM_DYNAMIC_LEAF_CHUNK_ENABLED=false
export LCM_DYNAMIC_LEAF_CHUNK_MAX=40000

Session Management

# DAG depth retained after /new (-1 all, 0 none)
export LCM_NEW_SESSION_RETAIN_DEPTH=2

# Exclude sessions from LCM storage (glob patterns)
export LCM_IGNORE_SESSION_PATTERNS="test-*,debug-*"

# Keep sessions read-only (glob patterns)
export LCM_STATELESS_SESSION_PATTERNS="readonly-*"

# Exclude messages by content regex (comma-separated)
export LCM_IGNORE_MESSAGE_PATTERNS="^SYSTEM:,^\[INTERNAL\]"

Large Payload Handling

# Store oversized payloads externally
export LCM_LARGE_OUTPUT_EXTERNALIZATION_ENABLED=true
export LCM_LARGE_OUTPUT_EXTERNALIZATION_THRESHOLD_CHARS=12000

# Compact already-externalized tool results
export LCM_LARGE_OUTPUT_TRANSCRIPT_GC_ENABLED=false

Model Overrides

# Override summarization model
export LCM_SUMMARY_MODEL=claude-3-5-sonnet-20241022

# Override expansion synthesis model
export LCM_EXPANSION_MODEL=gpt-4-turbo
export LCM_EXPANSION_CONTEXT_TOKENS=32000

# Timeouts
export LCM_SUMMARY_TIMEOUT_MS=60000
export LCM_EXPANSION_TIMEOUT_MS=120000

Advanced

# Custom database path
export LCM_DATABASE_PATH=/custom/path/lcm.db

# Enable slash commands
export LCM_ENABLE_SLASH_COMMAND=true

# Allow destructive doctor clean operations
export LCM_DOCTOR_CLEAN_APPLY_ENABLED=false

# Critical pressure bypass (0.0 = disabled)
export LCM_CRITICAL_BUDGET_PRESSURE_RATIO=0.0

Tuning for Long Context Models

For large context windows, tune threshold to avoid excessive prompt costs:

Calculation:

compaction_trigger = effective_context_window * LCM_CONTEXT_THRESHOLD

Examples:

Context Window	Desired Trigger	Threshold	Use Case
128K	96K	0.75	Standard
200K	140K	0.70	Balanced
400K	240K	0.60	Long context
1M	250K	0.25	Cost-optimized
1M	400K	0.40	Balanced large
1M	600K	0.60	Max raw context

Example configuration for 1M token model:

# Cost-optimized: trigger at 300K tokens
export LCM_CONTEXT_THRESHOLD=0.30

# Balanced: trigger at 400K tokens
export LCM_CONTEXT_THRESHOLD=0.40

# Max context: trigger at 600K tokens
export LCM_CONTEXT_THRESHOLD=0.60

Agent Tools Usage

lcm_status

Get current LCM state:

# Agent calls this to check compression state
{
  "tool": "lcm_status",
  "params": {}
}

Returns:

• Session ID
• Threshold tokens
• Current prompt tokens
• Raw message count
• Summary DAG structure
• Storage path
• Git commit (if source checkout)

lcm_grep

Search messages and summaries:

# Search for keyword in raw messages
{
  "tool": "lcm_grep",
  "params": {
    "pattern": "database schema",
    "search_raw": true,
    "search_summaries": false,
    "max_results": 10
  }
}

# Search summaries only
{
  "tool": "lcm_grep",
  "params": {
    "pattern": "migration",
    "search_raw": false,
    "search_summaries": true,
    "max_results": 5
  }
}

# Filter by source (files/tools mentioned)
{
  "tool": "lcm_grep",
  "params": {
    "pattern": "error",
    "source_filter": "src/database.py",
    "search_raw": true
  }
}

lcm_describe

Get summary node metadata:

# Describe a specific summary node
{
  "tool": "lcm_describe",
  "params": {
    "summary_id": "s_abc123"
  }
}

Returns:

• Summary text
• Descendant count
• Token counts
• Depth in DAG
• Source lineage

lcm_expand

Retrieve child summaries or raw messages:

# Expand a summary to see its children
{
  "tool": "lcm_expand",
  "params": {
    "summary_id": "s_abc123",
    "max_children": 5,
    "max_raw": 10
  }
}

# Get raw messages with source filter
{
  "tool": "lcm_expand",
  "params": {
    "summary_id": "s_abc123",
    "source_filter": "config.py",
    "max_raw": 20
  }
}

lcm_expand_query

Synthesize answer from DAG material using auxiliary LLM:

# Ask a question about compacted history
{
  "tool": "lcm_expand_query",
  "params": {
    "query": "What database migrations were discussed earlier?",
    "summary_id": "s_abc123",  # optional: scope to subtree
    "max_raw": 50
  }
}

This tool:

1. Retrieves relevant raw messages and summaries
2. Calls auxiliary LLM with query + material
3. Returns synthesized answer
4. Uses LCM_EXPANSION_MODEL and LCM_EXPANSION_CONTEXT_TOKENS

lcm_load_session

Load historical session into current context:

# Load previous session
{
  "tool": "lcm_load_session",
  "params": {
    "session_id": "previous-session-abc123"
  }
}

lcm_doctor

Diagnose and repair LCM state:

# Check for issues
{
  "tool": "lcm_doctor",
  "params": {
    "action": "check"
  }
}

# Preview cleanup (dry run)
{
  "tool": "lcm_doctor",
  "params": {
    "action": "clean_preview"
  }
}

# Apply cleanup (requires LCM_DOCTOR_CLEAN_APPLY_ENABLED=true)
{
  "tool": "lcm_doctor",
  "params": {
    "action": "clean_apply"
  }
}

Slash Commands (Optional)

Enable with LCM_ENABLE_SLASH_COMMAND=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.

Recovering Lost Context

# Scenario: Agent forgot details about earlier discussion

# 1. Search for topic
{
  "tool": "lcm_grep",
  "params": {
    "pattern": "API authentication",
    "search_raw": true,
    "search_summaries": true,
    "max_results": 10
  }
}

# 2. Expand relevant summary
{
  "tool": "lcm_expand",
  "params": {
    "summary_id": "s_found_in_grep",
    "max_raw": 20
  }
}

# 3. Synthesize answer
{
  "tool": "lcm_expand_query",
  "params": {
    "query": "What authentication method did we decide to use?",
    "summary_id": "s_found_in_grep"
  }
}

Debugging Compaction Issues

# Check current state
export 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 LCM
export LCM_IGNORE_SESSION_PATTERNS="test-*,temp-*,debug-*"

# Keep readonly sessions from being stored
export LCM_STATELESS_SESSION_PATTERNS="readonly-*,audit-*"

# Restart Hermes
hermes restart

Large Payload Management

# Enable external storage for large outputs
export LCM_LARGE_OUTPUT_EXTERNALIZATION_ENABLED=true
export LCM_LARGE_OUTPUT_EXTERNALIZATION_THRESHOLD_CHARS=12000

# Enable transcript GC for already-externalized content
export 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 trigger
export LCM_CONTEXT_THRESHOLD=0.75

Verify compression is enabled:

# In Hermes config
compression:
  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 check
export 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 directory
cd ~/.hermes/plugins/hermes-lcm
git pull --ff-only

# Or for symlinked install
cd /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 context

async def recover_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
    })
    
    if not grep_result.get("matches"):
        return f"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


async def query_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")

Custom Configuration Template

#!/bin/bash
# lcm-config.sh - LCM configuration template

# Core compaction settings
export LCM_CONTEXT_THRESHOLD=0.75
export LCM_FRESH_TAIL_COUNT=64
export LCM_LEAF_CHUNK_TOKENS=20000

# Dynamic chunking (optional)
export LCM_DYNAMIC_LEAF_CHUNK_ENABLED=true
export LCM_DYNAMIC_LEAF_CHUNK_MAX=40000

# Session management
export LCM_NEW_SESSION_RETAIN_DEPTH=2
export LCM_IGNORE_SESSION_PATTERNS="test-*,temp-*"
export LCM_STATELESS_SESSION_PATTERNS="readonly-*"

# Large payload handling
export LCM_LARGE_OUTPUT_EXTERNALIZATION_ENABLED=true
export LCM_LARGE_OUTPUT_EXTERNALIZATION_THRESHOLD_CHARS=12000
export LCM_LARGE_OUTPUT_TRANSCRIPT_GC_ENABLED=false

# Model overrides (use env vars for API keys)
# export LCM_SUMMARY_MODEL=claude-3-5-sonnet-20241022
# export LCM_EXPANSION_MODEL=gpt-4-turbo

# Advanced
export LCM_ENABLE_SLASH_COMMAND=true
export LCM_DOCTOR_CLEAN_APPLY_ENABLED=false

# Start Hermes
hermes start

Best Practices

1. Start with defaults: Only tune after observing actual compaction behavior
2. Monitor token usage: Use lcm_status to track prompt size and compaction triggers
3. Tune threshold for your model: Don't use 0.75 blindly on 1M token models
4. Enable slash commands for debugging: Set LCM_ENABLE_SLASH_COMMAND=true during setup
5. Use source filters: When expanding, filter by relevant files/tools to reduce noise
6. External payloads for large outputs: Enable externalization if tool results include large JSON/media
7. Regular doctor checks: Run /lcm doctor check periodically to catch issues early
8. Session patterns for isolation: Use ignore/stateless patterns to exclude test/debug sessions

Resources

• GitHub Repository
• LCM Paper by Ehrlich & Blackman
• Hermes Agent
• Lossless CLAW (inspiration)