agentleFS
TechNickAITechNickAI/hermes-skills/skills/core/recall/SKILL.md

recall

Skill0 starsChanged 3 months agoMITView on GitHub

Restore context from prior sessions, memories, and transcripts. Run /recall after /new to pick up where you left off, and also use when a bare-pronoun follow-up like "ship it", "do it", or "send that" likely points at a prior-session artifact. Designed to never dead-end — if one source has nothing, keep searching others until you have a useful picture.

152 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use addskill, apply-firmware and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ryanportfolioSkill

    addskill

    Create, import, update, or install repo or personal skills: runtime ownership, resources, discovery checks.

    Also in 6 projects that use this

  • ryanportfolioSkill

    apply-firmware

    Bring current folder (plain folder, existing repo, old or partial firmware copy) up to full Harness Firmware in place. Mirror external repo → adopt-repo.

    Also in 6 projects that use this

  • +10 more from ryanportfolio

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. 0 are common, 7 are distinctive, and 8 are very specific to this project.

  • 0

    Common

    Most of the 139 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use session_search to find prior sessions matching the topic or recent activity:

    line 49
  2. Very specific:

    If the user gave a topic hint, search for it: session_search(query="<topic hint>")

    line 51
  3. Distinctive:

    Look at multiple results, not just the top one

    line 56
  4. Very specific:

    If session_search returns matching sessions, load the transcript for the most relevant one(s).

    line 60
  5. Distinctive:

    Read the tail of a session directly:

    line 84
  6. Very specific:

    If a lookup comes back empty, check the other store before concluding anything is gone.

    line 112
  7. Distinctive:

    Check what the agent already knows that's relevant:

    line 140
  8. Very specific:

    Search cortex for the topic if available: cortex(action="search", query="...")

    line 142
  9. Very specific:

    Read the agent's MEMORY.md / memory/ files for any durable notes on this subject

    line 143
  10. Very specific:

    Check USER.md for relevant user context that bears on the topic

    line 144
  11. Distinctive:

    If sessions and memory come up empty but the user clearly remembers a conversation happening, it may predate Hermes or have been with a …

    line 148
  12. Distinctive:

    If you genuinely found nothing across all sources, say so plainly and offer to help reconstruct — don't just say "no results found." Ask: …

    line 180
  13. Distinctive:

    When was it roughly? That's still more useful than a dead end.

    line 182
  14. Very specific:

    If you're editing gateway/recall.py, keep this principle: Python = mechanical candidate gathering.

    line 202
  15. Distinctive:

    Use when sessions are gone, predate Hermes, or were with a different bot.

    line 215

“Common” is measured: kept by at least 6 in 10 of the 139 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Recall

Mission: Restore as much relevant context as possible. Never return empty-handed. If one source has nothing, try the next. Synthesize what you find into a clear briefing so the conversation can continue naturally.

When invoked

The user ran /recall (possibly with a topic hint like /recall project X status or /recall alice relationship analysis) after a /new reset or context overrun. They want to pick up where they left off. Your job is to find that thread and hand it back to them.

Implicit recall (no /recall command): A common case is a bare-pronoun follow-up right after a daily reset or /new — e.g. "ok deliver this", "ship it", "send that", "do it", "go ahead". The antecedent ("this", "that", "it") points at an artifact from the previous session that you no longer have in context. Treat these as recall triggers: go straight to step 2b (raw jsonl tail of the most recent prior session) and find the last assistant artifact — usually a draft, a ranked list, a proposed plan, or a pending-approval message. Then either confirm what they mean before acting, or surface the candidate artifact verbatim so they can say yes/no. Do not guess and execute on a deictic without verifying — the wrong "this" is worse than a clarifying question.

What to do

Work through these sources in order. Do not stop at the first miss — keep going until you have enough to give a useful briefing, or until all sources are exhausted.

1. Session search (start here)

Use session_search to find prior sessions matching the topic or recent activity:

  • If the user gave a topic hint, search for it: session_search(query="<topic hint>")
  • Also search for related terms if the first query is thin — break the phrase apart, try synonyms
  • Try a broad recency search with no query to see what was recently worked on: session_search() (no args = recent sessions)
  • Look at multiple results, not just the top one

2. Hermes session DB (if session_search has matches)

If session_search returns matching sessions, load the transcript for the most relevant one(s). Read through it and extract:

  • What was being worked on
  • Key decisions or conclusions reached
  • Open questions or blockers left unresolved
  • What the user's last message / intent was

2b. Raw transcript (when summaries are too lossy)

session_search returns summaries, not transcripts. When the previous session ended mid-task and you need exact state — the actual file paths touched, the last todo state, the precise question the assistant was waiting on, the diff that was proposed but not yet applied — the summary will be too coarse. Go to the raw transcript.

Transcripts live in a SQLite state store. Resolve it from the active Hermes home, not a hardcoded path — a named profile keeps its own store, and reading the wrong one returns an empty result that looks exactly like a missing session:

$HERMES_HOME/state.db          # active profile, when HERMES_HOME is set
~/.hermes/state.db             # root agent, when it is not

Read the tail of a session directly:

import sqlite3, os

# Resolve the store the way the running agent does, or a profile session
# will appear to be missing when it is simply in another file.
home = os.environ.get("HERMES_HOME") or os.path.expanduser("~/.hermes")
db = os.path.join(home, "state.db")

con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)   # read-only: never disturb a live session

session_id = "..."   # from session_search
rows = con.execute("""
    SELECT role, tool_name, content
    FROM messages
    WHERE session_id = ?
    ORDER BY id DESC
    LIMIT 12
""", (session_id,)).fetchall()

for role, tool, content in reversed(rows):
    print(f"=== {role}{'/' + tool if tool else ''} ===")
    print(str(content)[:3500])

Open the DB read-only (mode=ro). A live session may be writing to it.

If a lookup comes back empty, check the other store before concluding anything is gone. find $HOME/.hermes -maxdepth 3 -name state.db lists every store on the host.

Useful columns: messages.role, content, tool_name, timestamp, session_id; sessions.id, source, model, started_at, ended_at, message_count. The store also carries an FTS index, which is what session_search queries — prefer the tool over hand-rolled SQL for search, and use SQL for exact tail recovery.

When this beats session_search:

  • Compaction failed mid-session and the summary is a stub
  • A rollout / multi-step task paused mid-sequence; you need the exact "where"
  • The last assistant message was a pause-for-approval; you need the proposed diff verbatim
  • Tool outputs (which summaries drop) hold the recon data you'd otherwise re-run

Legacy per-profile JSONL. Older installs wrote ~/.hermes/profiles/<profile>/sessions/<session_id>.jsonl. Those files may still exist but are not written by current versions, so treat them as a historical archive only. Checking them first is a common way to conclude a session is "missing" when it is present in state.db — verify against the DB before reporting anything absent.

Finding a session: session_search returns session_id; query state.db with it directly. The shell sandbox sometimes resolves ~ to a fake home — expand $HOME explicitly (os.path.expanduser in Python) so reads always hit the real home directory.

3. Memory and cortex

Check what the agent already knows that's relevant:

  • Search cortex for the topic if available: cortex(action="search", query="...")
  • Read the agent's MEMORY.md / memory/ files for any durable notes on this subject
  • Check USER.md for relevant user context that bears on the topic

4. Raw Telegram history (tgcli fallback)

If sessions and memory come up empty but the user clearly remembers a conversation happening, it may predate Hermes or have been with a different bot. Use tgcli:

tgcli sync --chat <chat_id> --msgs-per-chat 200

Then query ~/.tgcli/tgcli.db:

SELECT sender_name, datetime(ts, 'unixepoch') AS when_, text
FROM messages
WHERE chat_id = '<chat_id>'
  AND (text LIKE '%<keyword>%' OR text LIKE '%<keyword2>%')
ORDER BY ts DESC
LIMIT 50;

See the tgcli section below for setup details.

5. Synthesize and brief

Once you have gathered what's available, produce a context briefing:

Recalled context — [topic]

What was being worked on:... Key decisions / conclusions:... Open threads:... What to do next:...

Inject this briefing into the session so it's visible. Then ask if the user wants to pick up from there or if they need anything clarified.

If you genuinely found nothing across all sources, say so plainly and offer to help reconstruct — don't just say "no results found." Ask: what do you remember about it? When was it roughly? That's still more useful than a dead end.

The /recall command

/recall is a gateway slash command. As of the one occasion rewrite, args are free-form — no rigid mode parsing. Python gathers a candidate pool (parent-chain sessions, FTS hits if the args contain letters, recent same-platform sessions for backfill), then one LLM call interprets the args and writes the briefing. See gateway/recall.py for the implementation.

Common invocations (the agent decides what they mean):

SyntaxWhat the agent does
/recallRecent in-thread sessions (parent chain)
/recall 3Last few in-thread sessions
/recall 7dSessions whose age fits the window
/recall <phrase>Topic search (in-thread + cross-thread via FTS)
/recall <phrase> 7dTopic + window, combined

If you're editing gateway/recall.py, keep this principle: Python = mechanical candidate gathering. LLM = judgment. Don't reintroduce regex mode parsing or a two-stage hunter+summarizer — that's the design the one occasion rewrite explicitly removed. The maintainer's framing: "way too complicated to do all the parsing in Python. Just have the LLM do the work."

After /new, if a prior session exists in the same thread, the agent automatically appends:

💡 Run /recall to restore context from your prior session.

Raw Telegram history fallback (tgcli)

Use when sessions are gone, predate Hermes, or were with a different bot.

tgcli is an MTProto user-account CLI that mirrors your Telegram history into local SQLite. It reads as you — not as a bot — so it sees everything your Telegram client sees.

Install + auth

# Requires TGCLI_APP_ID and TGCLI_APP_HASH from https://my.telegram.org/apps
tgcli login

Sync

tgcli sync --chat <chat_id_or_username> --msgs-per-chat 200

Messages land in ~/.tgcli/tgcli.db (table: messages, columns: chat_id, chat_name, msg_id, sender_id, sender_name, ts, from_me, text).

DMs vs forum supergroups

  • DMs — Telegram has no server-side topic for 1:1 DMs. The whole chat is one flat stream. tgcli works as-is; no topic filtering needed.
  • Forum supergroups — tgcli does NOT expose message_thread_id upstream. You get the whole supergroup. Filter by keyword in the SQL query, or use /recall <phrase> for Hermes-side FTS instead.

Pitfalls

  • Bot-only channels are invisible to tgcli (it authenticates as your user account)
  • Sync is on-demand — run it fresh before querying
  • ~/.tgcli/ contains a live user-account session; treat it like an SSH key

Pitfalls (general)

  • Never return "no topic matching" and stop. That's a dead end. Always fall through to the next source.
  • Topic search misses on exact phrase — if /recall database migration finds nothing, try shorter terms (/recall migration), then try session_search with individual keywords, then check memory.
  • Wrong thread scope — /recall (default) scopes to the current thread. Use a topic phrase to search across threads.
  • Very long transcripts — chunk before summarising if needed; the summary can still cover the whole transcript.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.