Resume Work with Session Context

This guide shows you how to pick up exactly where you left off — without re-reading files or re-explaining context to Claude.

Step 1: Understand What Session Context Stores

Every time you search, read, or edit a file during a Pyckle session, that activity gets recorded. Session context tracks which files you touched, which queries you ran, and how frequently each file appeared in your workflow. This gives Pyckle a ranked map of what matters right now — not just what exists in the codebase.

The result is a "heat map" of your session. Hot files are the ones you've been circling. Cold files are everything else. When you resume, Pyckle uses this map to surface the right files first.

Step 2: Call session_summary() to See Your Current State

Before you start any new work, run session_summary(). It returns a snapshot: files you've read or edited, queries you've run, and the hottest files by access frequency. This takes two seconds and prevents you from starting in the wrong place.

session_summary()

The output shows file paths ranked by activity, your recent search queries, and a count of edits per file. If the list looks right, you're ready to resume. If it looks stale or wrong, that's your signal to clear it first — covered in Step 5.

Step 3: Use session_continue() to Resume with Warm Files

session_continue() does two things at once: it runs a semantic search against your query and it biases results toward files already active in your session. You get relevance plus continuity. Use it instead of search_code() whenever you're picking up existing work.

session_continue("authentication middleware error handling", top_k=8)

The top_k parameter controls how many results come back. Eight is a good default for most resume scenarios — enough to reconstruct context without flooding the response. If you're deep in a single module, drop it to four.

Step 4: Register Edits to Keep Context Current

Pyckle tracks reads automatically, but edits made outside of Claude Code — in your editor, via a script, or through a patch — won't register unless you tell it. Use register_edit() to keep the heat map accurate.

register_edit("/home/kp112081/myproject/src/auth/middleware.py")

Call this immediately after any external edit. It takes a full file path and updates the session's activity record. If you batch-edited several files, call it once per file. The cost is negligible; the benefit is that your next session_continue() call will weight those files correctly.

Step 5: Clear Session State When Switching Tasks

Session context is scoped to a working thread of work. When you shift to a different feature, module, or codebase, you want a clean slate — otherwise the old heat map bleeds into your new searches and poisons the ranking. Check the current state first, then reset.

session_summary()
# Confirm you're done with current context, then clear:
session_clear()

After clearing, the first session_continue() or search_code() call starts fresh. Files accumulate heat again from zero. Think of it like closing your editor tabs before starting a different project — same discipline, different tool.