hermes-compress

hermes-compress

Compress the current conversation context by extracting what matters, writing a structured summary to memory, and producing a compact session-state block that can replace the full history in future context windows.

Invocation

/hermes-compress

No arguments required. Claude will process the full conversation history visible in the current context window.

---

What This Skill Does

When invoked, Claude executes the following steps in order:

Step 1 — Review All Messages

Claude reads every message in the current conversation from the beginning: user turns, assistant turns, tool calls, and tool results. Nothing is skipped. The goal is to produce a lossless inventory of everything meaningful that occurred.

Step 2 — Extract Structured Content

Claude identifies and categorizes content into six buckets:

Step 3 — Write to Memory

Claude writes the structured summary to the project memory file at:

~/.claude/projects/<project-slug>/memory/session_<YYYYMMDD_HHMM>.md

If the file already exists (e.g., from a previous compress run in the same day), Claude appends rather than overwrites, with a --- separator and a new timestamp header.

Claude also updates MEMORY.md to add an index entry pointing to the new session file.

Step 3a - Handle Memory Write Failures

• Create the memory directory before writing if it does not already exist.
• Write the session file first and update MEMORY.md second so a partial failure does not lose the summary.
• If appending fails because an existing session file is malformed, leave the old file untouched and write a new timestamped file instead.
• If the memory index update fails, report that the session file was written and that index repair is still needed.
• If the environment is read-only or permission-restricted, skip file writes, tell the user exactly what could not be persisted, and still emit the session-state block.
• If the conversation is too large to process in one pass, summarize in chunks and merge the six buckets before writing.
• Never drop explicit user requirements, file paths, commands, or unresolved blockers during fallback processing.

Step 4 — Identify What Can Be Dropped

Claude classifies each segment of the conversation as:

• Retain — essential for ongoing work (active code, current decisions, open issues)
• Compress — can be replaced by the summary (resolved discussions, background context)
• Drop — safe to discard (pleasantries, duplicate messages, superseded ideas)

This classification is not surfaced to the user by default but informs the session-state block.

Step 5 — Produce the Session-State Block

Claude outputs a compact YAML block that contains everything needed to resume the session from scratch:

# hermes-compress session state
# Generated: 2026-04-07T14:32:00Z
# Original message count: 47
# Compressed to: ~800 tokens

session:
  project: ontology-workspace
  date: 2026-04-07
  duration_approx: 90min

decisions:
  - "Use Neo4j as primary graph store for ontology nodes"
  - "REST API over gRPC for external integrations"
  - "Deploy to Vercel, not Railway"

artifacts_created:
  - path: "AlexAI/api/routes.py"
    description: "FastAPI router with /query and /ingest endpoints"
  - path: "CLAUDE.md"
    description: "Updated with hermes-compress active persona note"

problems_solved:
  - "Fixed OpenCrab surrogate encoding error by normalizing Korean queries to English"
  - "Resolved Neo4j connection timeout by bumping pool size to 20"

facts_learned:
  - "opencrab_flex.py fallback_cypher field contains a ready-made Cypher query"
  - "Honcho profile stored at ~/.claude/projects/*/memory/user_honcho_profile.md"

open_issues:
  - "hermes-search --recent N subcommand not yet tested against real history file"
  - "MEMORY.md index needs backfill for sessions before 2026-03-01"

next_steps:
  - "Run /hermes-search 'Neo4j connection' to verify memory is searchable"
  - "Commit routes.py and push to main branch"
  - "Set up Vercel project link with vercel link --repo"

This block is output at the end of the /hermes-compress response so the user can copy it into a new conversation window to resume without carrying the full history.

---

Output Format

The full /hermes-compress response is structured as:

1. Compression report — one paragraph: how many messages reviewed, how many tokens estimated saved, what was written to memory.
2. Session-state block — the YAML block above.
3. Resume instruction — one line: "Paste the session-state block at the top of your next conversation to resume."

---

Integration with hermes-memory

If the hermes-memory skill is active, /hermes-compress will:

• Automatically sync the session file to the hermes-memory index.
• Tag the session with topics extracted from the decisions and facts_learned fields.
• Make the session searchable via /hermes-search.

---

Automatic Invocation

Claude should suggest /hermes-compress proactively when:

• The conversation exceeds approximately 80% of the available context window.
• The user has been working for more than 60 minutes on a complex task.
• A major milestone has been reached (e.g., all planned files written, a bug resolved).

Claude will display: "Context window is getting full. Run /hermes-compress to summarize and free space."

---

Relationship to Hermes /compress Command

This skill is the Claude Code equivalent of the /compress command in Hermes Agent (NousResearch). Hermes /compress triggers a session summarization pass within its SQLite-backed session store. In hermes-CCC, the equivalent is writing structured Markdown to the project memory directory, since Claude Code does not have a persistent database backend by default. The output schema (decisions, artifacts, open_issues, next_steps) mirrors the Hermes compress output contract.

---

Notes

• Claude does not discard any part of the actual conversation history. Compression is about writing a compact representation to memory, not editing or deleting messages.
• The session-state YAML is designed to be pasted at the start of a new conversation as a system-level context seed.
• For very long sessions (500+ messages), Claude will process in passes: first pass extracts decisions and artifacts, second pass extracts facts and open issues.