pi-vcc

Algorithmic conversation compactor for Pi. No LLM calls — produces a brief transcript via extraction and formatting.

Inspired by VCC (View-oriented Conversation Compiler).

Why pi-vcc

| | Pi default | pi-vcc | |---|---|---| | Method | LLM-generated summary | Algorithmic extraction, no LLM | | Determinism | Non-deterministic, can hallucinate | Same input = same output, always | | Token reduction | Varies | 35-99% on real sessions (higher on longer sessions) | | Compaction latency | Waits for LLM call | 30-470ms, no API calls | | History after compaction | Gone — agent only sees summary | Fully searchable via vcc_recall | | Repeated compactions | Each rewrite risks losing more | Sections merge and accumulate | | Cost | Burns tokens on summarization call | Zero — no API calls | | Structure | Free-form prose | Brief transcript + 4 semantic sections |

Real session metrics

Measured on real session JSONLs under ~/.pi/agent/sessions (chars = rendered message text).

| Session | Messages | Before | After | Reduction | Time | |---|---|---|---|---|---| | Session A | 2,943 | 997,162 | 7,959 | 99.2% | 64ms | | Session B | 1,703 | 428,334 | 7,762 | 98.2% | 29ms | | Session C | 1,657 | 424,183 | 9,577 | 97.7% | 54ms | | Session D | 1,004 | 2,258,477 | 4,439 | 99.8% | 30ms | | Session E | 486 | 295,006 | 11,163 | 96.2% | 30ms | | Session F | 46 | 5,234 | 3,364 | 35.7% | 5ms | | Session G | 27 | 8,595 | 2,489 | 71.0% | 2ms |

Features

• No LLM — purely algorithmic, zero extra API cost
• Brief transcript — chronological conversation flow, each tool call collapsed to a one-liner with (#N) refs, text truncated to keep it compact
• 4 semantic sections — session goal, files & changes, outstanding context, user preferences
• Bounded merge — rolling sections re-capped after merge instead of growing unbounded
• Lossless recall — vcc_recall reads raw session JSONL, so old history stays searchable across compactions
• Regex search — vcc_recall supports regex patterns (hook|inject, fail.*build) and OR-ranked multi-word queries
• Fallback cut — still works when Pi core returns nothing to summarize
• Redaction — strips passwords, API keys, secrets
• /pi-vcc — manual compaction on demand

Install

pi install npm:@sting8k/pi-vcc

Or from GitHub:

pi install https://github.com/sting8k/pi-vcc

Or try without installing:

pi -e https://github.com/sting8k/pi-vcc

Usage

Once installed, pi-vcc registers a session_before_compact hook.

• When Pi triggers a compaction, pi-vcc supplies the summary.
• To trigger compaction manually, run /pi-vcc.
• To search older history after compaction, use vcc_recall.

Compacted message structure

[Session Goal]
- Fix the authentication bug in login flow
- [Scope change]
- Also update the session token refresh logic

[Files And Changes]
- Modified: src/auth/session.ts
- Created: tests/auth-refresh.test.ts

[Outstanding Context]
- lint check still failing on line 42

[User Preferences]
- Prefer Vietnamese responses
- Always run tests before committing

[user]
Fix the auth bug, users can't log in after password reset

[assistant]
Root cause is a missing token refresh after password reset...
* bash "bun test tests/auth.test.ts" (#12)
Tests: 8 passed, 4 failed — the refresh token isn't being set.
* edit "src/auth/session.ts" (#14)
Added token refresh call after password reset flow.
* bash "bun test tests/auth.test.ts" (#16)
Tests: 12 passed, 0 failed ✓

[user]
also update the session expiry logic

[assistant]
* bash "grep -n 'expiry' src/auth/session.ts" (#18)
...(truncated)

Sections:

| Section | Description | |---|---| | [Session Goal] | Initial goal + scope changes (regex-based extraction) | | [Files And Changes] | Modified/created files from tool calls (capped) | | [Outstanding Context] | Unresolved items — errors, pending questions | | [User Preferences] | Regex-extracted from user messages (always, never, prefer...) | | Brief transcript | Chronological conversation flow — rolling window of ~120 recent lines, tool calls collapsed to one-liners with (#N) refs |

Merge policy:

• Session Goal, User Preferences: concise sticky sections
• Outstanding Context: fresh-only (replaced each compaction)
• Files And Changes: unique union across compactions
• Brief transcript: rolling window, older lines drop off

Recall (Lossless History)

Pi's default compaction discards old messages permanently. After compaction, the agent only sees the summary.

vcc_recall bypasses this by reading the raw session JSONL file directly. It parses every message entry in the file, regardless of how many compactions have happened.

Search

Queries support regex and multi-word OR logic ranked by relevance:

vcc_recall({ query: "auth token" })           // OR search, ranked
vcc_recall({ query: "hook|inject" })           // regex pattern
vcc_recall({ query: "fail.*build" })           // regex pattern

Browse

Without a query, returns the last 25 entries as brief summaries:

vcc_recall()

Expand

Returns full untruncated content for specific indices found via search:

vcc_recall({ expand: [41, 42] })

Typical workflow: search → find relevant entry indices → expand those indices for full content.

Some tool results are truncated by Pi core at save time. expand returns everything in the JSONL but can't recover what Pi already cut.

Pipeline

1. Normalize — raw Pi messages → uniform blocks (user, assistant, tool_call, tool_result, thinking)
2. Filter noise — strip system messages, empty blocks
3. Build sections — extract goal, file paths, blockers, preferences
4. Brief transcript — chronological conversation flow, tool calls collapsed to one-liners, text truncated
5. Format — render into bracketed sections + transcript
6. Redact — strip passwords, API keys, secrets
7. Merge — if previous summary exists: sticky sections merge, volatile sections replace, transcript rolls

Debug

Debug logging is off by default. Enable it in ~/.pi/agent/pi-vcc-config.json:

{ "debug": true }

When enabled, each compaction writes detailed info to /tmp/pi-vcc-debug.json — message counts, cut boundary, summary preview, sections.

Related Work

• VCC — the original transcript-preserving conversation compiler
• Pi — the AI coding agent this extension is built for

License

MIT