$ cat ~/map/pi-memento.md

pi-memento

Nested context transactions for pi: commit, compact, squash, or revert an exploration without rewriting session history.

extensions✓ Oct 16

./bin/memento

## TL;DR

Experimental pi extension for explicit, nested transactions over the agent's own model-visible context — commit, compact, squash, or revert a stretch of exploration without ever rewriting session history.

## Key points

• $Decouples the context axis from execution: a subagent gives you a clean caller context only by spawning a new loop with a boundary decided up front, while pi-memento delivers the context effect alone inside the same agent loop — any granularity, opened anywhere, and disposed after seeing how the work went.
• $Registers three tools: transaction_begin (with optional purpose), transaction_end (disposition plus optional result and carryforward), and the read-only transaction_status; begin and end must each be the only tool call in their assistant message, and end always closes the innermost open transaction (LIFO).
• $Four dispositions: commit keeps the body inline, compact replaces it with a model-generated summary (the only disposition that calls the model), squash replaces it with an agent-written result string, and revert removes it entirely while requiring a non-empty carryforward lesson.
• $The projection is a view over canonical history, which stays append-only JSONL — a transaction never rewrites what happened, and it does not roll back the world: files written, commands run, and other side effects remain.
• $Compaction is transaction-aware: cuts land on transaction boundaries, open transactions stay entirely in the retained tail, and inconsistent boundaries or metadata make it fail closed rather than fall back to raw history.
• $Strict non-goals: no filesystem, shell, or process rollback, no VM or container snapshots, no database transactions, no distributed agent memory, and no semantic search or automatic long-term memory management.
• $Runs as a plugin via a project-local pinned pi: npm install fetches the pinned @earendil-works/pi-coding-agent, npm run build compiles the extension to dist/, and ./bin/memento launches that pinned binary — the global pi install is untouched.

## FAQ

## References

• README ↗
• pi integration contract ↗

Last updated: Aug 31, 2026