{"_id":"@adamjen/pi-vcc","_rev":"2-8e04e2c5c4158b6f75947458ee77626d","name":"@adamjen/pi-vcc","dist-tags":{"latest":"0.3.17"},"versions":{"0.3.16":{"name":"@adamjen/pi-vcc","version":"0.3.16","keywords":["pi-package","pi-extension","vcc","compact","compaction"],"_id":"@adamjen/pi-vcc@0.3.16","maintainers":[{"name":"adamjen","email":"adamjentv@gmail.com"}],"homepage":"https://github.com/adamjen/pi-vcc#readme","bugs":{"url":"https://github.com/adamjen/pi-vcc/issues"},"pi":{"extensions":["./index.ts"]},"dist":{"shasum":"7679df7686e60f74ccee41a5687f27e2ccff968c","tarball":"https://registry.npmjs.org/@adamjen/pi-vcc/-/pi-vcc-0.3.16.tgz","fileCount":33,"integrity":"sha512-4E4GlRGOdo8JuGUOkZ4ufUgdknYVFqTdUdCVg4hrdEi9t2M3Lt8Jbh8XoCy5mxUTLVxnUD3BNcnaoe8ONZdc1w==","signatures":[{"sig":"MEUCIBwKLYluJrs59052OYP94rGNV/UB8KpBelePrgrSo+aCAiEA+w/5ZMfjF+aYClQqbj5UeeRSyiWOe9+2BLM0XrcXVls=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":109120},"main":"index.ts","exports":{".":"./index.ts","./src/core/normalize":"./src/core/normalize.ts","./src/core/summarize":"./src/core/summarize.ts","./src/core/filter-noise":"./src/core/filter-noise.ts","./src/core/normalize.ts":"./src/core/normalize.ts","./src/core/summarize.ts":"./src/core/summarize.ts","./src/core/build-sections":"./src/core/build-sections.ts","./src/core/filter-noise.ts":"./src/core/filter-noise.ts","./src/hooks/before-compact":"./src/hooks/before-compact.ts","./src/core/build-sections.ts":"./src/core/build-sections.ts","./src/hooks/before-compact.ts":"./src/hooks/before-compact.ts"},"gitHead":"956a405f8793e7c2ac320486ec74fc5626f67dfd","_npmUser":{"name":"adamjen","email":"adamjentv@gmail.com"},"repository":{"url":"git+https://github.com/adamjen/pi-vcc.git","type":"git"},"_npmVersion":"10.9.7","description":"Algorithmic conversation compactor for pi - transcript-preserving structured summaries, no LLM calls","directories":{},"_nodeVersion":"22.22.2","_hasShrinkwrap":false,"peerDependencies":{"typebox":">=1.1.24 <2.0.0","@earendil-works/pi-coding-agent":">=0.74.0 <1.0.0"},"_npmOperationalInternal":{"tmp":"tmp/pi-vcc_0.3.16_1780494981906_0.6553345898777281","host":"s3://npm-registry-packages-npm-production"}},"0.3.17":{"name":"@adamjen/pi-vcc","version":"0.3.17","description":"Algorithmic conversation compactor for pi - transcript-preserving structured summaries, no LLM calls","main":"index.ts","exports":{".":"./index.ts","./src/hooks/before-compact":"./src/hooks/before-compact.ts","./src/hooks/before-compact.ts":"./src/hooks/before-compact.ts","./src/core/summarize":"./src/core/summarize.ts","./src/core/summarize.ts":"./src/core/summarize.ts","./src/core/normalize":"./src/core/normalize.ts","./src/core/normalize.ts":"./src/core/normalize.ts","./src/core/filter-noise":"./src/core/filter-noise.ts","./src/core/filter-noise.ts":"./src/core/filter-noise.ts","./src/core/build-sections":"./src/core/build-sections.ts","./src/core/build-sections.ts":"./src/core/build-sections.ts"},"keywords":["pi-package","pi-extension","vcc","compact","compaction"],"repository":{"type":"git","url":"git+https://github.com/adamjen/pi-vcc.git"},"peerDependencies":{"@earendil-works/pi-coding-agent":">=0.74.0 <1.0.0","typebox":">=1.1.24 <2.0.0"},"pi":{"extensions":["./index.ts"]},"scripts":{"test":"vitest run","test:watch":"vitest","smoke":"vitest run src/__tests__/*-smoke.test.ts","test:all":"vitest run"},"devDependencies":{"vitest":"^4.1.10"},"_id":"@adamjen/pi-vcc@0.3.17","gitHead":"32e1e38a9e281ebe58c4db2f50afbc6810c5fb9d","bugs":{"url":"https://github.com/adamjen/pi-vcc/issues"},"homepage":"https://github.com/adamjen/pi-vcc#readme","_nodeVersion":"22.23.1","_npmVersion":"10.9.8","dist":{"integrity":"sha512-s+mcHjvCC+nKaD0Xfp8CWRVZurBsdVuNauVQUJWGeIPcMmPnxY0iJlH765JnWIeT9XIl7y4ipJ2VTn7AvNE8OQ==","shasum":"d45b4e1513d7ea5421963378788608954895ff3d","tarball":"https://registry.npmjs.org/@adamjen/pi-vcc/-/pi-vcc-0.3.17.tgz","fileCount":46,"unpackedSize":193232,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDXGHQMKkC6DCLIl0yxcLUB11Y9fvF/mt+p/1eeAiZ9JgIhAObzaYwQZcezJ4RXWKFMnuoDZWa5bzdetK70jbjXpfUS"}]},"_npmUser":{"name":"adamjen","email":"adamjentv@gmail.com"},"directories":{},"maintainers":[{"name":"adamjen","email":"adamjentv@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-vcc_0.3.17_1783672770065_0.1597137333176275"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-03T13:56:21.585Z","modified":"2026-07-10T08:39:30.292Z","0.3.16":"2026-06-03T13:56:22.057Z","0.3.17":"2026-07-10T08:39:30.200Z"},"bugs":{"url":"https://github.com/adamjen/pi-vcc/issues"},"homepage":"https://github.com/adamjen/pi-vcc#readme","keywords":["pi-package","pi-extension","vcc","compact","compaction"],"repository":{"type":"git","url":"git+https://github.com/adamjen/pi-vcc.git"},"description":"Algorithmic conversation compactor for pi - transcript-preserving structured summaries, no LLM calls","maintainers":[{"name":"adamjen","email":"adamjentv@gmail.com"}],"readme":"# pi-vcc\n\n[![npm](https://img.shields.io/npm/v/@adamjen/pi-vcc)](https://www.npmjs.com/package/@adamjen/pi-vcc)\n\nAlgorithmic conversation compactor for [Pi](https://github.com/badlogic/pi-mono). No LLM calls — produces a brief transcript via extraction and formatting.\n\nInspired by [VCC](https://github.com/lllyasviel/VCC) **(View-oriented Conversation Compiler)**.\n\n## Demo\n\n![pi-vcc demo](./demo.gif)\n\n## Why pi-vcc\n\n|  | Pi default | pi-vcc |\n|---|---|---|\n| **Method** | LLM-generated summary | Algorithmic extraction, no LLM |\n| **Determinism** | Non-deterministic, can hallucinate | Same input = same output, always |\n| **Token reduction** | Varies | 35-99% on real sessions (higher on longer sessions) |\n| **Compaction latency** | Waits for LLM call | 30-470ms, no API calls |\n| **History after compaction** | Gone — agent only sees summary | Active lineage searchable via `vcc_recall` (`scope:\"all\"` available) |\n| **Repeated compactions** | Each rewrite risks losing more | Sections merge and accumulate |\n| **Cost** | Burns tokens on summarization call | Zero — no API calls |\n| **Structure** | Free-form prose | Brief transcript + 4 semantic sections |\n\n### Real session metrics\n\nMeasured on real session JSONLs under `~/.pi/agent/sessions` (chars = rendered message text).\n\n| Session | Messages | Before | After | Reduction | Time |\n|---|---|---|---|---|---|\n| Session A | 2,943 | 997,162 | 7,959 | 99.2% | 64ms |\n| Session B | 1,703 | 428,334 | 7,762 | 98.2% | 29ms |\n| Session C | 1,657 | 424,183 | 9,577 | 97.7% | 54ms |\n| Session D | 1,004 | 2,258,477 | 4,439 | 99.8% | 30ms |\n| Session E | 486 | 295,006 | 11,163 | 96.2% | 30ms |\n| Session F | 46 | 5,234 | 3,364 | 35.7% | 5ms |\n| Session G | 27 | 8,595 | 2,489 | 71.0% | 2ms |\n\n## Features\n\n- **No LLM** — purely algorithmic, zero extra API cost\n- **Brief transcript** — chronological conversation flow, each tool call collapsed to a one-liner with `(#N)` refs, text truncated to keep it compact\n- **5 semantic sections** — session goal, files & changes, commits, outstanding context, user preferences\n- **Bounded merge** — rolling sections re-capped after merge instead of growing unbounded\n- **Lossless recall** — `vcc_recall` reads raw session JSONL, so active-lineage history stays searchable across compactions\n- **Scoped recall** — default search is active lineage; use `scope:\"all\"` / `scope:all` to intentionally search across all lineages\n- **Regex search** — `vcc_recall` supports regex patterns (`hook|inject`, `fail.*build`) and OR-ranked multi-word queries\n- **Result ranking** — search results ranked by term relevance, rare terms weighted higher than common ones\n- **`/pi-vcc-recall`** — slash command to search history directly, results shown as collapsible message and auto-fed to agent as context\n- **Fallback cut** — still works when Pi core returns nothing to summarize\n- **`/pi-vcc`** — manual compaction on demand\n\n## Install\n\n```bash\npi install npm:@adamjen/pi-vcc\n```\n\nOr from GitHub:\n\n```bash\npi install https://github.com/adamjen/pi-vcc\n```\n\nOr try without installing:\n\n```bash\npi -e https://github.com/adamjen/pi-vcc\n```\n\n## Usage\n\nOnce installed, pi-vcc registers a `session_before_compact` hook.\n\n- Run `/pi-vcc` to trigger pi-vcc compaction manually.\n- By default, `/compact` and auto-threshold compactions still go through pi core (LLM-based). Set `overrideDefaultCompaction: true` in the config to let pi-vcc handle all compaction paths.\n- To search older active-lineage history after compaction, use `vcc_recall`.\n- To intentionally search across all lineages, pass `scope:\"all\"` to `vcc_recall` or run `/pi-vcc-recall <query> scope:all`.\n- To search and feed results to agent yourself, run `/pi-vcc-recall <query> [page:N]`.\n  - Tip: type `/recall` and Pi will autocomplete to `/pi-vcc-recall`.\n\n### How compaction works\n\nPi splits the conversation at the **last user message**. Everything after — the **kept tail** — stays intact and untouched. pi-vcc only summarizes the older portion before that cut point.\n\n### Compacted message structure\n\n```\n[Session Goal]\n- Fix the authentication bug in login flow\n- [Scope change]\n- Also update the session token refresh logic\n\n[Files And Changes]\n- Modified: src/auth/session.ts\n- Created: tests/auth-refresh.test.ts\n\n[Commits]\n- a1b2c3d: fix(auth): refresh token after password reset\n\n[Outstanding Context]\n- lint check still failing on line 42\n\n[User Preferences]\n- Prefer Vietnamese responses\n- Always run tests before committing\n\n[user]\nFix the auth bug, users can't log in after password reset\n\n[assistant]\nRoot cause is a missing token refresh after password reset...\n* bash \"bun test tests/auth.test.ts\" (#12)\n* edit \"src/auth/session.ts\" (#14)\n* bash \"bun test tests/auth.test.ts\" (#16)\n...(28 earlier lines omitted)\n```\n\nSections appear only when relevant — a session with no git commits won't have `[Commits]`.\n\n**Sections:**\n\n| Section | Description |\n|---|---|\n| `[Session Goal]` | Initial goal + scope changes (regex-based extraction) |\n| `[Files And Changes]` | Modified/created files from tool calls (capped, paths trimmed to common root) |\n| `[Commits]` | Git commits made during the session (last 8, hash + first line) |\n| `[Outstanding Context]` | Unresolved items — errors, pending questions |\n| `[User Preferences]` | Regex-extracted from user messages (`always`, `never`, `prefer`...) |\n| Brief transcript | Chronological conversation flow — rolling window of ~120 recent lines, tool calls collapsed to one-liners with `(#N)` refs |\n\n**Merge policy:**\n- `Session Goal`, `User Preferences`: concise sticky sections\n- `Outstanding Context`: fresh-only (replaced each compaction)\n- `Files And Changes`, `Commits`: unique union across compactions\n- Brief transcript: rolling window, older lines drop off\n\n## Recall (Lossless History)\n\nPi's default compaction discards old messages permanently. After compaction, the agent only sees the summary.\n\n`vcc_recall` bypasses this by reading the raw session JSONL file directly. By default it searches only the active conversation lineage, regardless of how many compactions have happened. Use `scope:\"all\"` only when you intentionally want to include off-lineage branches.\n\n### Search\n\nQueries support **regex** and **multi-word OR logic** ranked by relevance:\n\n```\nvcc_recall({ query: \"auth token\" })                         // active-lineage OR search, ranked\nvcc_recall({ query: \"auth token\", page: 2 })                // paginated (5 results/page)\nvcc_recall({ query: \"hook|inject\" })                         // regex pattern\nvcc_recall({ query: \"fail.*build\" })                         // regex pattern\nvcc_recall({ query: \"auth token\", scope: \"all\" })           // search all lineages\n```\n\nManual slash command:\n\n```\n/pi-vcc-recall auth token scope:all\n```\n\n### Browse\n\nWithout a query, returns the last 25 entries as brief summaries:\n\n```\nvcc_recall()\nvcc_recall({ scope: \"all\" })  // browse recent entries across all lineages\n```\n\n### Expand\n\nReturns full untruncated content for specific indices found via search:\n\n```\nvcc_recall({ expand: [41, 42] })                 // active-lineage expand\nvcc_recall({ expand: [41, 42], scope: \"all\" })   // expand across all lineages\n```\n\nTypical workflow: **search → find relevant entry indices → expand those indices for full content**.\n\n> 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.\n\n## Pipeline\n\n1. **Normalize** — raw Pi messages → uniform blocks (user, assistant, tool_call, tool_result, thinking)\n2. **Filter noise** — strip system messages, empty blocks\n3. **Build sections** — extract goal, file paths, blockers, preferences\n4. **Brief transcript** — chronological conversation flow, tool calls collapsed to one-liners, text truncated\n5. **Format** — render into bracketed sections + transcript\n6. **Merge** — if previous summary exists: sticky sections merge, volatile sections replace, transcript rolls\n\n## Config\n\nConfig lives at `~/.pi/agent/pi-vcc-config.json` (auto-scaffolded on first load with safe defaults):\n\n```json\n{\n  \"overrideDefaultCompaction\": false,\n  \"debug\": false\n}\n```\n\n- **`overrideDefaultCompaction`** *(default `false`)*: when `false`, pi-vcc only runs for `/pi-vcc`; `/compact` and auto-threshold compactions fall through to pi core. Set `true` to make pi-vcc handle all compaction paths.\n- **`debug`** *(default `false`)*: when `true`, each compaction writes detailed info to `/tmp/pi-vcc-debug.json` — message counts, cut boundary, summary preview, sections.\n\n## Changes from upstream\n\n- Compact resume logic moved from core into this extension wrapper (injects a steer message after compaction so the agent continues its task)\n- Renamed from `@sting8k/pi-vcc` to `@adamjen/pi-vcc`\n\n## Related Work\n\n- [VCC](https://github.com/lllyasviel/VCC) — the original transcript-preserving conversation compiler, by HazAT / sting8k\n- [Pi](https://github.com/badlogic/pi-mono) — the AI coding agent this extension is built for\n\n## License\n\nMIT\n","readmeFilename":"README.md"}