@undreren/pi-checkpoint

Pi package that adds context checkpoints and conversation restore for agents and users.

Install

pi install npm:@undreren/pi-checkpoint

Or from this repo:

node install.mjs

Tools

• checkpoint — create a conversation-only bookmark, returns #N with compaction guidance
• restore_conversation — compact context back to a checkpoint with a required summary

Commands (TUI)

• /checkpoint [label] — create a checkpoint (injects tool call + result)
• /restore_conversation — picker (current branch, newest first) then summary prompt

Behavior

• Conversation-only compaction (no filesystem restore)
• restore_conversation replaces intermediate messages with your summary; it does not mean undo
• Restore lands on checkpoint → restore_conversation tool_call → restore_conversation tool_result
• Agent restore_conversation auto-continues; user /restore_conversation waits for your next message
• Checkpoint ids are global per session (#1, #2, …); accept #3 or 3

Agent semantics

• Checkpoint creates a conversation bookmark. The filesystem is unchanged.
• Restore conversation compacts everything after that checkpoint into the summary you provide.
• The summary is authored by you (or the user via /restore_conversation) and becomes your durable memory.
• Intermediate tool outputs are removed from context after restore; trust the summary and tool_result.details.
• Restore success is reported in the session tool_result with isError: false.

Cursor bridge notes

When pi tools are replayed through a Cursor bridge:

• restore_conversation tool_result must not be duplicated on an error channel.
• tool_call.arguments.summary should remain visible after compaction.
• Compacted messages must actually leave agent context.
• Prefer the session-written restore_conversation tool_result over any minimal hook block reason.

Develop

npm install
npm test

License

MIT