| name | hermes-compress |
| description | Compress conversation context — summarize the current session, extract key decisions and facts, then compact history to free up context window. |
| version | 1.0.0 |
| author | hermes-CCC (ported from Hermes Agent by NousResearch) |
| license | MIT |
| metadata | {"hermes":{"tags":["Context","Compression","Memory","Session"],"related_skills":["hermes-memory","hermes-search"]}} |
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:
| Bucket | What goes here |
|---|
decisions | Choices the user or Claude made ("we decided to use Postgres", "REST over gRPC") |
artifacts_created | Files written, code blocks produced, configs generated (include file paths) |
problems_solved | Bugs fixed, errors resolved, blockers cleared |
facts_learned | New information ingested from user, tools, or research |
open_issues | Unresolved questions, TODOs, known bugs not yet fixed |
next_steps | Explicit or implied follow-up actions |
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:
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:
- Compression report — one paragraph: how many messages reviewed, how many tokens estimated saved, what was written to memory.
- Session-state block — the YAML block above.
- 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.
