Hermes Search

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

Copy code
/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:

bashCopy code
# 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:

bashCopy code
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:

bashCopy code
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:

bashCopy code
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:

Copy code
## 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

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.