/hermes-compress

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:

# 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 ap