pi-mega-compact 0.4.14 → 0.4.15

package/dist/extensions/dashboard-server.js

@@ -69,6 +69,15 @@ function dashboardHtml(tierName) {
   .card.safe h2 { color: #3fb950; }
   .safe-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; line-height: 1.5; }
   .value.ok { color: #3fb950; }
+  .label {
+    cursor: help;
+    border-bottom: 1px dotted #484f58;
+  }
+  .card.legend { grid-column: 1 / -1; }
+  .legend-list { margin: 0; padding-left: 18px; color: #c9d1d9; }
+  .legend-list li { margin-bottom: 8px; line-height: 1.5; }
+  .legend-list b { color: #f0f6fc; }
+  .legend-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; font-style: italic; }
   .card h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .5px; color: #8b949e; margin-bottom: 12px; font-weight: 600; }
   .meter-track { background: #21262d; border-radius: 4px; height: 20px; overflow: hidden; margin: 8px 0; }
   .meter-fill { height: 100%; border-radius: 4px; transition: width .6s ease; min-width: 2px; }
@@ -126,15 +135,15 @@ function dashboardHtml(tierName) {
   <div class="card">
     <h2>Vector Store</h2>
     <div class="stat-grid">
-      <span class="label">Checkpoints</span><span class="value" id="st-count">0</span>
-      <span class="label">Tokens Stored</span><span class="value" id="st-tokens">0</span>
-      <span class="label">Original Tokens</span><span class="value" id="st-orig">0</span>
-      <span class="label">Tokens Saved</span><span class="value" id="st-saved">0</span>
-      <span class="label">Injected</span><span class="value" id="st-injected">0</span>
-      <span class="label">Dedup Rate</span><span class="value" id="st-dedup">0%</span>
-      <span class="label">Storage Dedup</span><span class="value" id="st-sdedup">0%</span>
-      <span class="label">Collapsed</span><span class="value" id="st-collapsed">0</span>
-      <span class="label">Last ID</span><span class="value" id="st-lastid">—</span>
+      <span class="label" title="A saved summary of a chunk of your conversation that was compacted to free up space.">Checkpoints</span><span class="value" id="st-count">0</span>
+      <span class="label" title="How much conversation we are currently holding as compact summaries (the 'memory' this extension keeps). Smaller is better.">Tokens Stored</span><span class="value" id="st-tokens">0</span>
+      <span class="label" title="Total size of the original conversation text before it was compacted.">Original Tokens</span><span class="value" id="st-orig">0</span>
+      <span class="label" title="How much conversation space we have freed up for you (original size minus the compact summary we kept).">Tokens Saved</span><span class="value" id="st-saved">0</span>
+      <span class="label" title="How many times old context was automatically brought back into the conversation because it was relevant to what you were doing.">Injected</span><span class="value" id="st-injected">0</span>
+      <span class="label" title="Of the times we recalled old context, how often it was actually on-topic.">Recall Relevance</span><span class="value" id="st-dedup">0%</span>
+      <span class="label" title="How often new content matched something we already had, so we skipped storing a duplicate copy. Higher = less wasted space.">Storage Dedup</span><span class="value" id="st-sdedup">0%</span>
+      <span class="label" title="How many duplicate chunks we collapsed into one instead of storing separately.">Collapsed</span><span class="value" id="st-collapsed">0</span>
+      <span class="label" title="The ID of the most recent saved checkpoint.">Last ID</span><span class="value" id="st-lastid">—</span>
     </div>
   </div>
   <div class="card">
@@ -177,6 +186,18 @@ function dashboardHtml(tierName) {
       <span class="label">Status</span><span class="value" id="cr-status">idle</span>
     </div>
   </div>
+  <div class="card legend">
+    <h2>What these numbers mean</h2>
+    <ul class="legend-list">
+      <li><b>Tokens saved</b> — conversation space this extension has freed up for you (it compacted old text into short summaries).</li>
+      <li><b>Tokens stored</b> — how much "memory" (compact summaries) the extension is currently holding for this repo.</li>
+      <li><b>Injected</b> — times old context was automatically pasted back in because it was relevant to your current task.</li>
+      <li><b>Recall relevance</b> — of those, how often the recalled context was actually on-topic.</li>
+      <li><b>Storage dedup</b> — how often new content matched something already saved, so a duplicate copy was skipped (saves space).</li>
+      <li><b>Data safety</b> — every compacted region is kept verbatim (compressed). Nothing is permanently deleted; you can restore any of it.</li>
+    </ul>
+    <p class="legend-note">Hover any label above for a quick explanation.</p>
+  </div>
 </div>
 
 <div class="events">

package/dist/extensions/mega-compact.js

@@ -260,8 +260,8 @@ export default function (pi) {
             // Phase 3 — pulsing status glyph while a compaction is in flight.
             const pulse = pulsing ? `${C.cyan}${PULSE[Math.floor(Date.now() / 250) % PULSE.length]}${C.reset} ` : "";
             const lines = [
-                ` ${C.amber}⚡ ${config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} chkpt${agentStr}${turnStr}`,
-                `   ${triggerLabel} │ ${C.magenta}dedup: ${dedupStr}${C.reset} │ ${C.gray}used:${C.reset} ${usedStr} │ ${C.gray}saved:${C.reset} ${savedStr}`,
+                ` ${C.amber}⚡ ${config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} saved${agentStr}${turnStr}`,
+                `   ${triggerLabel} │ ${C.magenta}repeat-skipped: ${dedupStr}${C.reset} │ ${C.gray}memory held:${C.reset} ${usedStr} │ ${C.gray}space freed:${C.reset} ${savedStr}`,
             ];
             // Phase 3 — compact progress bar: session tokens saved toward the rolling goal.
             if (rt.tokensSaved > 0) {
@@ -289,11 +289,16 @@ export default function (pi) {
             // Phase 3 — recall/activity ticker (most-recent first), fresh only.
             if (fresh) {
                 for (let i = ticker.length - 1; i >= 0; i--) {
-                    if (lines.length >= 10)
-                        break; // MAX_WIDGET_LINES guard
+                    if (lines.length >= 9)
+                        break; // leave room for the hint line (MAX 10)
                     lines.push(`   ${i === ticker.length - 1 ? "" : C.dim}${ticker[i].text}${C.reset}`);
                 }
             }
+            // Plain-language hint so first-time users understand the widget. Always
+            // last, dimmed. "/mega-help explains these terms."
+            if (lines.length < 10) {
+                lines.push(`   ${C.dim}auto-compresses old context to free space · nothing deleted · /mega-help${C.reset}`);
+            }
             ctx.ui.setWidget(WIDGET_KEY, lines, { placement: "aboveEditor" });
         }
     }
@@ -844,6 +849,20 @@ export default function (pi) {
                 `${original.slice(0, 1500)}${original.length > 1500 ? "\n…(truncated)" : ""}`);
         },
     });
+    pi.registerCommand("mega-help", {
+        description: "Plain-language glossary of what mega-compact's stats mean.",
+        handler: async (_args, ctx) => {
+            ctx.ui.notify(`[mega-compact] glossary — what the numbers mean:\n` +
+                `• token — a chunk of text (~4 chars). Context window = how much text fits in memory at once.\n` +
+                `• space freed — how much conversation we've compressed away to make room (the win).\n` +
+                `• memory held — how much compact summary we're currently keeping as your 'notes'.\n` +
+                `• saved checkpoint — a compact summary of an old conversation chunk we stored.\n` +
+                `• repeat-skipped — how often new text matched something we already had, so we didn't store a duplicate.\n` +
+                `• injected — times we pasted an old saved note back into the chat because it was relevant.\n` +
+                `• recall relevance — of those, how often the note was actually on-topic.\n` +
+                `• data safety — every compressed region is kept verbatim; nothing is permanently deleted. /mega-restore brings any of it back.`);
+        },
+    });
     pi.registerCommand("mega-tier", {
         description: "Show or change the compaction tier at runtime. Usage: /mega-tier [low|medium|high|ultra|mega]",
         handler: async (args, ctx) => {

package/extensions/dashboard-server.ts

@@ -133,6 +133,15 @@ function dashboardHtml(tierName: string): string {
   .card.safe h2 { color: #3fb950; }
   .safe-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; line-height: 1.5; }
   .value.ok { color: #3fb950; }
+  .label {
+    cursor: help;
+    border-bottom: 1px dotted #484f58;
+  }
+  .card.legend { grid-column: 1 / -1; }
+  .legend-list { margin: 0; padding-left: 18px; color: #c9d1d9; }
+  .legend-list li { margin-bottom: 8px; line-height: 1.5; }
+  .legend-list b { color: #f0f6fc; }
+  .legend-note { font-size: 12px; color: #8b949e; margin: 12px 0 0; font-style: italic; }
   .card h2 { font-size: 12px; text-transform: uppercase; letter-spacing: .5px; color: #8b949e; margin-bottom: 12px; font-weight: 600; }
   .meter-track { background: #21262d; border-radius: 4px; height: 20px; overflow: hidden; margin: 8px 0; }
   .meter-fill { height: 100%; border-radius: 4px; transition: width .6s ease; min-width: 2px; }
@@ -190,15 +199,15 @@ function dashboardHtml(tierName: string): string {
   <div class="card">
     <h2>Vector Store</h2>
     <div class="stat-grid">
-      <span class="label">Checkpoints</span><span class="value" id="st-count">0</span>
-      <span class="label">Tokens Stored</span><span class="value" id="st-tokens">0</span>
-      <span class="label">Original Tokens</span><span class="value" id="st-orig">0</span>
-      <span class="label">Tokens Saved</span><span class="value" id="st-saved">0</span>
-      <span class="label">Injected</span><span class="value" id="st-injected">0</span>
-      <span class="label">Dedup Rate</span><span class="value" id="st-dedup">0%</span>
-      <span class="label">Storage Dedup</span><span class="value" id="st-sdedup">0%</span>
-      <span class="label">Collapsed</span><span class="value" id="st-collapsed">0</span>
-      <span class="label">Last ID</span><span class="value" id="st-lastid">—</span>
+      <span class="label" title="A saved summary of a chunk of your conversation that was compacted to free up space.">Checkpoints</span><span class="value" id="st-count">0</span>
+      <span class="label" title="How much conversation we are currently holding as compact summaries (the 'memory' this extension keeps). Smaller is better.">Tokens Stored</span><span class="value" id="st-tokens">0</span>
+      <span class="label" title="Total size of the original conversation text before it was compacted.">Original Tokens</span><span class="value" id="st-orig">0</span>
+      <span class="label" title="How much conversation space we have freed up for you (original size minus the compact summary we kept).">Tokens Saved</span><span class="value" id="st-saved">0</span>
+      <span class="label" title="How many times old context was automatically brought back into the conversation because it was relevant to what you were doing.">Injected</span><span class="value" id="st-injected">0</span>
+      <span class="label" title="Of the times we recalled old context, how often it was actually on-topic.">Recall Relevance</span><span class="value" id="st-dedup">0%</span>
+      <span class="label" title="How often new content matched something we already had, so we skipped storing a duplicate copy. Higher = less wasted space.">Storage Dedup</span><span class="value" id="st-sdedup">0%</span>
+      <span class="label" title="How many duplicate chunks we collapsed into one instead of storing separately.">Collapsed</span><span class="value" id="st-collapsed">0</span>
+      <span class="label" title="The ID of the most recent saved checkpoint.">Last ID</span><span class="value" id="st-lastid">—</span>
     </div>
   </div>
   <div class="card">
@@ -241,6 +250,18 @@ function dashboardHtml(tierName: string): string {
       <span class="label">Status</span><span class="value" id="cr-status">idle</span>
     </div>
   </div>
+  <div class="card legend">
+    <h2>What these numbers mean</h2>
+    <ul class="legend-list">
+      <li><b>Tokens saved</b> — conversation space this extension has freed up for you (it compacted old text into short summaries).</li>
+      <li><b>Tokens stored</b> — how much "memory" (compact summaries) the extension is currently holding for this repo.</li>
+      <li><b>Injected</b> — times old context was automatically pasted back in because it was relevant to your current task.</li>
+      <li><b>Recall relevance</b> — of those, how often the recalled context was actually on-topic.</li>
+      <li><b>Storage dedup</b> — how often new content matched something already saved, so a duplicate copy was skipped (saves space).</li>
+      <li><b>Data safety</b> — every compacted region is kept verbatim (compressed). Nothing is permanently deleted; you can restore any of it.</li>
+    </ul>
+    <p class="legend-note">Hover any label above for a quick explanation.</p>
+  </div>
 </div>
 
 <div class="events">

package/extensions/mega-compact.ts

@@ -363,8 +363,8 @@ export default function (pi: ExtensionAPI) {
       // Phase 3 — pulsing status glyph while a compaction is in flight.
       const pulse = pulsing ? `${C.cyan}${PULSE[Math.floor(Date.now() / 250) % PULSE.length]}${C.reset} ` : "";
       const lines = [
-        ` ${C.amber}⚡ ${config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} chkpt${agentStr}${turnStr}`,
-        `   ${triggerLabel} │ ${C.magenta}dedup: ${dedupStr}${C.reset} │ ${C.gray}used:${C.reset} ${usedStr} │ ${C.gray}saved:${C.reset} ${savedStr}`,
+        ` ${C.amber}⚡ ${config.tier}${C.reset} │ ${tokStr}/${maxStr} tokens (${C.bold}${pctStr}${C.reset}) │ ${st.checkpointCount} saved${agentStr}${turnStr}`,
+        `   ${triggerLabel} │ ${C.magenta}repeat-skipped: ${dedupStr}${C.reset} │ ${C.gray}memory held:${C.reset} ${usedStr} │ ${C.gray}space freed:${C.reset} ${savedStr}`,
       ];
       // Phase 3 — compact progress bar: session tokens saved toward the rolling goal.
       if (rt.tokensSaved > 0) {
@@ -389,10 +389,15 @@ export default function (pi: ExtensionAPI) {
       // Phase 3 — recall/activity ticker (most-recent first), fresh only.
       if (fresh) {
         for (let i = ticker.length - 1; i >= 0; i--) {
-          if (lines.length >= 10) break; // MAX_WIDGET_LINES guard
+          if (lines.length >= 9) break; // leave room for the hint line (MAX 10)
           lines.push(`   ${i === ticker.length - 1 ? "" : C.dim}${ticker[i].text}${C.reset}`);
         }
       }
+      // Plain-language hint so first-time users understand the widget. Always
+      // last, dimmed. "/mega-help explains these terms."
+      if (lines.length < 10) {
+        lines.push(`   ${C.dim}auto-compresses old context to free space · nothing deleted · /mega-help${C.reset}`);
+      }
       ctx.ui.setWidget(WIDGET_KEY, lines, { placement: "aboveEditor" });
     }
   }
@@ -994,6 +999,23 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
+  pi.registerCommand("mega-help", {
+    description: "Plain-language glossary of what mega-compact's stats mean.",
+    handler: async (_args: string, ctx: ExtensionContext) => {
+      ctx.ui.notify(
+        `[mega-compact] glossary — what the numbers mean:\n` +
+        `• token — a chunk of text (~4 chars). Context window = how much text fits in memory at once.\n` +
+        `• space freed — how much conversation we've compressed away to make room (the win).\n` +
+        `• memory held — how much compact summary we're currently keeping as your 'notes'.\n` +
+        `• saved checkpoint — a compact summary of an old conversation chunk we stored.\n` +
+        `• repeat-skipped — how often new text matched something we already had, so we didn't store a duplicate.\n` +
+        `• injected — times we pasted an old saved note back into the chat because it was relevant.\n` +
+        `• recall relevance — of those, how often the note was actually on-topic.\n` +
+        `• data safety — every compressed region is kept verbatim; nothing is permanently deleted. /mega-restore brings any of it back.`,
+      );
+    },
+  });
+
   pi.registerCommand("mega-tier", {
     description: "Show or change the compaction tier at runtime. Usage: /mega-tier [low|medium|high|ultra|mega]",
     handler: async (args: string, ctx: ExtensionContext) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.4.14",
+  "version": "0.4.15",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-2-Clause",