$ cat ~/map/pi-experience.md

pi-experience

Experience-memory extension: logs raw runs to its own SQLite; the main agent merges audited history into cross-session experiences.

extensions✓ Sep 14

npm ci then pi -e ./src/index.ts to load once, or pi install /absolute/path/to/pi-experience as a local pi package; requires Node.js 24+ and pi 0.85.1

## TL;DR

An experience-memory extension that taps pi's extension events into its own SQLite and generates per-run summaries in a background forked session for user audit; the main agent merges history into nestable, cross-session experiences.

## Key points

• $Records raw runs by tapping pi's extension events into its own SQLite database (WAL, FULL sync, foreign keys, transactions); the extension does not read, parse, index, or modify pi's JSONL, does not depend on native entry IDs, and recording and recovery still hold under SessionManager.inMemory().
• $A run's summary is generated in a background forked session after the run ends; the read-only Chinese-language /experience panel lets the user audit records — R refreshes, L browses runs, S asks the agent to tidy, D shows diagnostics — with /experience runs, /experience show R01, /experience prepare, /experience debug, and /experience raw R01 for deeper inspection.
• $Experiences (E) and runs (R): an E has at most one direct parent E; combine operations reject cycles, duplicate parent relationships, and overlapping intervals; root Es merge across sessions and propagate sources and attach associations, with source time ranges inherited from members and kept unknown while any source lacks a confirmed end time.
• $Run lifecycle: agent_start opens a run and agent_settled confirms it stopped — a final assistant stop maps to completed, error or length to failed, and aborted to interrupted; missing terminal state or unfinished work flags recovery_required, and a dead writer's runs keep their UUID, numbering, and committed events without a fabricated end time.
• $Requires Node.js 24+ and pi 0.85.1, with the peer dependency locked to that version; other pi versions need event-compatibility verification first.
• $Explicit scope limits: capture starts when the extension is enabled and does not import prior pi history; pi 0.85.1's direct ! / !! bash paths emit only the pre-execution user_bash event, so only the initiation is stored; fork lineage is marked unresolved because pi extension events expose no mappable fork point; search is SQLite keyword metadata with no vector recall.

## FAQ

## References

• README ↗

Last updated: Sep 14, 2026