pi-history-tools

A pi extension package that gives the agent tools to search and fetch historical session messages, including messages that are no longer in model context after compaction.

Pi compaction summarizes older context for the model, but the original conversation remains in the JSONL session file. This package exposes that saved history through safe, bounded tools so the agent can look up exact earlier details instead of guessing.

Tools

history_search

Search historical messages in the current pi session.

Use cases:

• The user refers to an earlier detail that is not visible after compaction.
• The agent needs to recover an earlier instruction, decision, filename, or requirement.
• The agent needs to find an entry id before fetching the full message.

Key parameters:

• query — distinctive text to search for.
• role — optional filter: any, user, assistant, toolResult, bashExecution, custom, or summary.
• scope — branch by default, or all to include all entries in the session file.
• includeToolResults — false by default.
• includeBashOutput — false by default.

history_get

Fetch a full historical message by entry id, optionally with nearby context.

Key parameters:

• entryId — an id or unique prefix returned by history_search.
• before / after — include nearby searchable entries.
• scope — branch by default, or all.
• maxChars — cap returned output.

How the agent knows to use it

The extension registers prompt guidance with pi:

• Use history_search when the user refers to an earlier detail, instruction, decision, filename, or message that is not visible in the current context, especially after compaction.
• Use history_search before guessing about prior conversation details; then use history_get with the returned entry id when exact wording or surrounding context matters.
• Use history_get after history_search when exact original wording or nearby messages are needed.

Install

Install globally from GitHub:

pi install git:github.com/amknight/pi-history-tools

Or try it for one run:

pi -e git:github.com/amknight/pi-history-tools

After installing in an existing interactive session, run:

/reload

or restart pi.

Privacy and safety

The tools read the active pi session history available to the current session manager. Results are bounded and include basic redaction for common secret/token shapes, but extensions run with your local permissions and can access session content. Review the source before installing.

Search defaults are intentionally conservative:

• active branch only
• tool results excluded
• bash output excluded
• capped snippets

Development

This is a pi package with a single extension declared in package.json:

{
  "pi": {
    "extensions": ["./extensions/history.ts"]
  }
}

For local testing:

pi --no-extensions -e ./extensions/history.ts