---
slug: "undreren-pi-checkpoint"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/undreren/pi-checkpoint@main/README.md"
repo: "https://github.com/undreren/pi-checkpoint"
source_file: "README.md"
branch: "main"
---
# @undreren/pi-checkpoint

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

## Install

```bash
pi install npm:@undreren/pi-checkpoint
```

Or from this repo:

```bash
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

```bash
npm install
npm test
```

## License

MIT