How to search session history
Find prior work, decisions, messages, tool outputs, files, and artifacts across Buffaly sessions without relying on memory or manual log digging.
Who this is for
Use this workflow when you need to recover context after compaction, a worker recycle, a long pause, or a handoff between similarly named sessions.
Quick answer
Session history is the saved evidence stream for Buffaly work. It can include user messages, assistant progress, final answers, tool calls, tool results, lifecycle rows, compaction snapshots, Plan/Scratch files, task artifacts, and produced files.
What counts as session history
| Layer | What it tells you | How to use it |
|---|---|---|
| Session | Named work container and runtime metadata. | Scope reads and summaries by key/name. |
| Timeline rows | Messages, tool calls, tool outputs, lifecycle rows, and final answers. | Use for chronological evidence. |
| Plan and Scratch | Current route, task status, investigation notes, and observations. | Recover reasoning and latest known route. |
| Task artifacts | Durable markdown files with acceptance criteria and accumulated evidence. | Use for delegated or multi-turn work. |
| Compaction archives | Older summarized or archived timeline slices. | Use when active timeline is shorter than full history. |
| Created files/artifacts | Docs, patches, logs, screenshots, or generated files. | Verify final results outside the transcript. |
Source shows a dedicated SessionHistory skill for paging and summarizing timeline history, plus session tooling that can merge active session.json rows with compaction-*.json archive history.
Ask Buffaly to search prior work
Good requests include a target, scope, and evidence requirement. Buffaly should bind known session keys, file paths, artifact names, task names, and date ranges before falling back to semantic retrieval.
Search by known session key
When you know the session key, keep the request scoped and ask for bounded paging or summarization.
Reads a bounded page of session history.
Summarizes a date range.
Summarizes recent history after the latest compaction boundary.
Summarizes between two UTC timestamps.
Search by topic or semantic meaning
When you do not know the session key, combine exact and semantic approaches. Exact search is best for file paths, article names, commit hashes, error messages, prototype/action names, session keys, and artifact filenames. Semantic search is best for broad topics or remembered decisions where exact wording is unknown.
Treat semantic search as a retrieval aid. Verify important facts against session rows, files, artifacts, or commits before acting.
Search by date, artifact, file, or task
Date range
Use UTC timestamps when possible. If you only know a local date, ask Buffaly to state the assumed timezone before searching.
Artifact or task
If prior work produced a file or durable task, inspect the artifact itself instead of relying only on transcript search.
For long-running work, Plan, Scratch, and task artifacts may be more current than an old chat excerpt.
Resume work after finding context
Once Buffaly finds the relevant session or artifact, resume from evidence, not memory alone.
- Confirm the session key and target files.
- Distinguish completed work from planned work.
- Check whether files were committed and re-validate current repository state.
- Continue only if the old route is still valid.
Verify search results
Before acting on recovered history, verify that the match is the right work and that the evidence still applies.
- Session key/name matches the intended project or child session.
- Dates and timestamps match the expected time window.
- Cited files still exist at expected paths.
- Final answers are supported by tool output or committed files.
- Semantic matches are not merely conversations about the topic rather than the original work.
Troubleshooting
Cannot find the session
Try narrower anchors: exact filename, repo-relative path, commit hash, unique error text, action/tool name, UTC date range, or parent/child session key.
Timeline is missing older turns
Ask Buffaly to include compaction archive rows or summaries when reading a known session.
Artifacts are missing
Check both transcript evidence and filesystem state. A final answer may mention an artifact that moved, was deleted, or was never committed.
Several sessions match
Do not resume until Buffaly compares why each candidate matches and which has the strongest artifact, file, or commit evidence.