CLAUDE.md to Hermes Memory: A Translation Guide

If you have been using Claude Code seriously, you probably have CLAUDE.md files scattered across projects — one at the repo root, one at ~/.claude/CLAUDE.md, maybe more. They contain your tech stack, style rules, forbidden patterns, recent decisions, command aliases, everything you want Claude to know about a project before it does anything.

When you start running Hermes, the obvious question is: does all of that port over? The answer is nuanced. Some of it absolutely belongs in Hermes memory. Some of it should stay in CLAUDE.md. Some of it wants to live in skills instead. Getting this right is the difference between Hermes that feels informed and Hermes that keeps repeating mistakes you already told Claude Code about.

Key Takeaways

• CLAUDE.md is static context loaded at the start of every Claude Code session. The content does not change unless you edit the file.
• Hermes memory is dynamic — FTS5-indexed markdown files in ~/.hermes/ that the agent curates from experience.
• Port the long-lived, portable facts (tech stack, standards, conventions) to Hermes memory.
• Leave the project-specific command aliases and quick-reference tables in CLAUDE.md so Claude Code still has them.
• Turn repeated workflows into Hermes skills, not memory entries.
• Two strategies for bootstrapping: one-shot import (paste the CLAUDE.md to Hermes and ask it to memorize) vs incremental ("memorize this" as situations arise).
• Hermes memory compounds across sessions; CLAUDE.md does not. That difference drives everything.

Two Different Mental Models

CLAUDE.md is a document. You write it, Claude Code reads it every session, it behaves according to what you wrote. If you want Claude Code to learn something new, you edit the file yourself. The model is static, human-curated, session-loaded.

Hermes memory is a dynamic store. The agent decides what to write based on experience. When Hermes learns something during a task — a rule, a lesson, a preference — it writes a markdown file under ~/.hermes/memory/ (or adjacent to the relevant skill) and the FTS5 index picks it up. Next session, when you ask a question that matches, Hermes retrieves that memory and uses it. The model is dynamic, agent-curated, search-indexed.

Neither is better. They solve different problems. CLAUDE.md gives you deterministic context ("this is how I want this project approached"). Hermes memory gives you compounding knowledge ("last time we tried this, we learned X"). You want both.

What To Port, What To Leave

Here is how I split a typical CLAUDE.md when porting to Hermes.

Port to Hermes memory

Long-lived, reusable facts that apply across many sessions:

• Tech stack declarations ("we use Next.js 15, Tailwind, Supabase")
• Coding conventions ("always use TypeScript, always use Server Components by default")
• Forbidden patterns ("never use Material UI, never use force-dynamic on listing pages")
• Design system tokens ("primary color palette is orange gradient #FF6B35 to #F7931E")
• Deployment constraints ("we are on Vercel Hobby; Fluid Active CPU budget is 1.5h")
• Security rules ("never bypass RLS, never use service role on the client")

These are things the agent benefits from knowing no matter which project or which conversation. They change rarely. They compound.

Leave in CLAUDE.md

Project-local command tables and quick references:

• Slash-command aliases specific to that project
• URLs of the staging and production deployments
• Database connection details (public-safe ones)
• Quick-command tables ("/commit to commit, /ship to deploy")
• Per-project environment quirks

These are useful to Claude Code when it is operating on that specific project. They do not need to be cross-session or cross-project. Leaving them in CLAUDE.md is the simplest thing that works.

Promote to Hermes skills

Repeatable workflows that deserve their own SKILL.md:

• Your git commit workflow
• Your PR creation workflow
• Your changelog generation workflow
• Your deployment checklist

If it is a procedure Hermes should follow step-by-step, it is a skill, not a memory. See Writing Your First Hermes SKILL.md for the skill-authoring guide.

Strategy 1: One-Shot Import

The quickest way to bootstrap Hermes memory from a CLAUDE.md is to paste the relevant sections and ask Hermes to memorize them. Start Hermes:

hermes chat --provider anthropic --model claude-sonnet-4-6

Then a prompt like:

The following is my long-lived project context. Please memorize it —
write it to memory under appropriate topic files in ~/.hermes/memory/.
Use your best judgment on how to split it up.

---

[paste the portable sections of CLAUDE.md here]

Hermes will read the content, decide on a reasonable structure under ~/.hermes/memory/, and write a set of markdown files there. It might produce something like:

~/.hermes/memory/
├── projects/
│   └── aiskill-market/
│       ├── tech-stack.md
│       ├── vercel-constraints.md
│       └── design-system.md
└── conventions/
    ├── typescript.md
    └── supabase-rls.md

FTS5 indexes those files automatically. Next time Hermes is asked about design tokens or Vercel limits, it will retrieve the right file.

The downside of one-shot import: Hermes has no context for which facts matter most, so the organization might need editing. Spot-check the generated files, rename or merge as appropriate.

Strategy 2: Incremental Memorize-On-Mention

A more organic approach: don't pre-load anything. Instead, when a relevant fact comes up during a real task, tell Hermes to memorize it.

> We are on Vercel Hobby plan. Fluid Active CPU budget is 1.5h.
> Never use force-dynamic on listing pages — use revalidate = 3600 instead.
> Please memorize this for future sessions.

Hermes writes a file, future sessions pick it up. Over weeks of use, your memory store converges on exactly the facts you actually reference, with no bloat from rules you never hit.

This is slower but produces cleaner memory. I recommend it for teams that already have CLAUDE.md files working well in Claude Code — the incremental approach lets you keep the CLAUDE.md intact as the source of truth for Claude Code while Hermes builds its own parallel memory organically.

A Worked Port Example

Here is a snippet from a real CLAUDE.md:

## Vercel Usage Rules (CRITICAL — shared account)

**This project shares Vercel Hobby plan limits with 3 other projects.
Exceeding limits pauses ALL projects.**

### NEVER do these

1. NEVER use `export const dynamic = 'force-dynamic'` on listing/public pages.
   Use `export const revalidate = 3600` (ISR) instead.
2. NEVER create API routes without `Cache-Control` headers if the response is cacheable.
3. NEVER set `maxDuration` above 10 in `vercel.json` on Hobby plan.

### Hobby Plan Limits

| Resource | Limit | Budget target |
|---|---|---|
| Fluid Active CPU | 4h total | <1.5h |
| Edge Requests | 1M total | <400K |
| Function Invocations | 1M total | <300K |

This is a great candidate for Hermes memory. It is long-lived, it compounds across sessions, it applies to any task touching Vercel. The ported memory file at ~/.hermes/memory/projects/aiskill-market/vercel-constraints.md might look like:

# Vercel Constraints — aiskill-market

## Shared Hobby Plan

This project shares a Vercel Hobby plan with 3 other projects.
Exceeding account limits pauses ALL projects.

## Forbidden Patterns

- `export const dynamic = 'force-dynamic'` on listing/public pages
  — use `export const revalidate = 3600` instead.
- API routes without `Cache-Control` headers (when response is cacheable).
- `maxDuration > 10` in `vercel.json` on Hobby plan (silently capped anyway).

## Budget Targets

- Fluid Active CPU: <1.5h (account limit 4h)
- Edge Requests: <400K (account limit 1M)
- Function Invocations: <300K (account limit 1M)

## Context

Incident 2026-04-17: entire account paused. aiskill-market was 79.3% of CPU
usage. Root cause: `force-dynamic` on 4 listing pages. Fixed by switching to ISR.

Same facts, different phrasing. Hermes memory wants concise, tagged, searchable. CLAUDE.md wanted instructive and didactic. The port is a rewrite, not a copy-paste, but the information content is identical.

Now the project CLAUDE.md can shrink — drop the Vercel section and replace it with a note that the agent should check Hermes memory under projects/aiskill-market/vercel-constraints. Or keep it in CLAUDE.md for Claude Code's session use, and duplicate the critical rules into Hermes memory. Duplication is fine; both runtimes are reading their own stores.

What Happens On Session Start

When Hermes starts a conversation it does not load all of memory — that would be expensive and unnecessary. It indexes memory at startup and retrieves entries on demand via FTS5 search when a query or task phrase matches. See Hermes Memory Deep Dive: FTS5 Markdown Recall for the indexing mechanics.

Claude Code loads your CLAUDE.md in full at the start of every session. That is its whole thing — guaranteed context you can count on. The tradeoff: CLAUDE.md context is always there, burning tokens on information that might not be relevant. Hermes memory is retrieved only when needed, saving tokens but relying on search quality.

Both work. They are different mechanisms for different workloads.

Practical Recommendation

If you have an existing CLAUDE.md and want to start with Hermes tomorrow:

1. Leave CLAUDE.md alone for now. Claude Code still uses it.
2. Pick the top 5-10 long-lived facts from CLAUDE.md and run Strategy 1 (one-shot import) for those.
3. Switch to Strategy 2 (incremental) for everything else. Let Hermes memory grow naturally.
4. Every few weeks, audit ~/.hermes/memory/ and consolidate duplicates.
5. When you notice a workflow repeating in Hermes, promote it to a skill.

The goal is not to replicate CLAUDE.md in Hermes. The goal is to let each runtime build the memory shape that fits its usage pattern. Claude Code stays deterministic and session-scoped. Hermes grows knowledge that compounds. You work across both without losing signal either way.

Sources

• Hermes Agent repo on GitHub
• Hermes Agent docs
• Hermes Memory Deep Dive: FTS5 Markdown Recall
• Cross-Session Memory: The "Claude Forgets" Problem
• Writing Your First Hermes SKILL.md
• Anthropic Claude Code documentation