hermes-search

name	hermes-search
description	Search across past conversation sessions, memory files, and project history to recall what was discussed, decided, or built in previous sessions.
version	1.0.0
author	hermes-CCC (ported from Hermes Agent by NousResearch)
license	MIT
metadata	{"hermes":{"tags":["Search","Memory","Sessions","History","Recall"],"related_skills":["hermes-memory","hermes-compress","hermes-insights"]}}

hermes-search

Search across past conversation sessions, memory files, and project files to recall what was discussed, decided, or built. This skill is the cross-session retrieval complement to hermes-compress, which writes the memory, and hermes-memory, which indexes it.

Invocation

/hermes-search "<query>"
/hermes-search --memory "<query>"
/hermes-search --project "<query>"
/hermes-search --recent <N>

---

Subcommands

/hermes-search "<query>" — Search All Memory

Searches all available memory sources in order:

1. ~/.claude/projects/*/memory/*.md — all project memory files
2. ~/.claude/history.jsonl — conversation history log (if accessible)
3. Project files under the current working directory
4. MEMORY.md index

Returns a unified result list sorted by relevance.

How Claude executes this:

# Memory files
grep -r --include="*.md" -l "<query>" ~/.claude/projects/*/memory/

# Within matched files, extract surrounding context
grep -n -A 3 -B 3 "<query>" <matched-file>

# Project files (from cwd)
grep -r --include="*.md" --include="*.py" --include="*.ts" \
     --include="*.json" -l "<query>" .

# history.jsonl (if present)
grep "<query>" ~/.claude/history.jsonl | head -20

---

/hermes-search --memory "<query>" — Memory Files Only

Restricts search to ~/.claude/projects/*/memory/*.md. Faster and more focused. Use this when you know the information was captured in a previous session via hermes-compress or hermes-memory.

How Claude executes this:

grep -r --include="*.md" -n -A 3 -B 3 "<query>" \
     ~/.claude/projects/*/memory/

Returns: file path, line number, and 3 lines of surrounding context per match.

---

/hermes-search --project "<query>" — Project Files Only

Restricts search to the current working directory. Useful for recalling where a piece of code or config lives.

How Claude executes this:

grep -r --include="*.md" --include="*.py" --include="*.ts" \
     --include="*.js" --include="*.json" --include="*.yaml" \
     -n -l "<query>" .

Claude then reads the top 3 matched files and extracts the relevant sections.

---

/hermes-search --recent <N> — Recent N Sessions Summary

Lists and summarizes the most recent N session memory files.

How Claude executes this:

ls -t ~/.claude/projects/*/memory/session_*.md | head -<N>

Claude reads each file and produces a one-line summary per session: [date] [project] — <top decision or artifact from that session>

---

Output Format

All subcommands return results in the following structure:

## Search Results: "<query>"
Source: --memory | --project | all
Query time: <timestamp>

### Match 1
- Source: ~/.claude/projects/ontology/memory/session_20260321_1430.md (line 47)
- Relevance: high
- Snippet:
  > decisions:
  >   - "Use Neo4j as primary graph store for ontology nodes"  ← MATCH
  >   - "REST API over gRPC for external integrations"

### Match 2
- Source: ./AlexAI/api/routes.py (line 12)
- Relevance: medium
- Snippet:
  > # Neo4j connection pool config  ← MATCH
  > driver = GraphDatabase.driver(uri, auth=(user, pw), max_connection_pool_size=20)

---
Total matches: 2 | Searched: 14 files

Relevance scoring (heuristic):

• High: exact phrase match in a decisions or facts_learned block
• Medium: keyword match in a session file body or code comment
• Low: keyword match in a filename or metadata field

---

What Gets Searched

Source	Path pattern	Format
Session summaries	~/.claude/projects/*/memory/session_*.md	YAML/Markdown
Memory index	~/.claude/projects/*/memory/MEMORY.md	Markdown
Honcho profiles	~/.claude/projects/*/memory/user_honcho_profile.md	YAML/Markdown
Project source files	./**/*.{md,py,ts,js,json,yaml}	Any
History log	~/.claude/history.jsonl	JSONL (if accessible)

---

Handling Missing Sources

• If ~/.claude/history.jsonl does not exist or is not readable, Claude skips it and notes: "history.jsonl not accessible — searching memory files only."
• If no memory files exist, Claude reports: "No memory files found. Run /hermes-compress after a session to start building memory."
• If project files return too many matches (>50), Claude limits output to the top 10 by file modification date (most recent first).

---

Relationship to Hermes FTS5 Session Search

This skill is the Claude Code equivalent of Hermes Agent's full-text search over its SQLite session store (using SQLite FTS5). In Hermes, /search <query> performs a ranked FTS5 query over all session message content. In hermes-CCC, the equivalent is grep-based search over the Markdown memory files written by hermes-compress. The result schema (source, relevance, snippet) mirrors the Hermes search output contract.

For projects that generate large volumes of session memory, consider building a local SQLite FTS5 index over the memory files using the hermes-memory skill's index-build subcommand.

---

Notes

• Search is case-insensitive by default. Add --case-sensitive flag to override.
• Queries containing spaces should be quoted: /hermes-search "Neo4j connection pool".
• /hermes-search does not modify any files. It is always read-only.
• Results are printed to the conversation; they are not automatically written to memory. If a search result is important, follow up with /hermes-memory add to pin it.