@pi-unipi/compactor 0.1.7 → 0.2.1

package/src/commands/index.ts

@@ -3,6 +3,14 @@
  *
  * Commands perform real work by calling tool implementations directly.
  * Dependencies (sessionDB, contentStore, sessionId) are injected at registration time.
+ *
+ * New command names (v0.2.0):
+ *   /unipi:session-recall (was /unipi:compact-recall)
+ *   /unipi:content-index (was /unipi:compact-index)
+ *   /unipi:content-search (was /unipi:compact-search)
+ *   /unipi:content-purge (was /unipi:compact-purge)
+ *
+ * Old names kept as deprecated aliases for backward compatibility.
  */
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
@@ -13,20 +21,25 @@ import { compactTool } from "../tools/compact.js";
 import { vccRecall } from "../tools/vcc-recall.js";
 import { ctxStats } from "../tools/ctx-stats.js";
 import { ctxDoctor } from "../tools/ctx-doctor.js";
-import { ctxIndex } from "../tools/ctx-index.js";
 import { ctxSearch } from "../tools/ctx-search.js";
 import { ContentStore } from "../store/index.js";
 import type { SessionDB } from "../session/db.js";
-import type { NormalizedBlock } from "../types.js";
+import type { NormalizedBlock, RuntimeCounters } from "../types.js";
 
 export interface CommandDeps {
   sessionDB: SessionDB | null;
   contentStore: ContentStore | null;
   getSessionId: () => string;
   getBlocks: () => NormalizedBlock[];
+  getCounters?: () => RuntimeCounters;
+}
+
+function deprecationLog(oldName: string, newName: string): void {
+  console.error(`[compactor] DEPRECATED: Command "${oldName}" used — use "${newName}" instead.`);
 }
 
 export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
+  // ── /unipi:compact ──────────────────────────────────
   pi.registerCommand("unipi:compact", {
     description: "Trigger manual compaction with stats",
     handler: async (_args: string, ctx: any) => {
@@ -39,31 +52,42 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
     },
   });
 
-  pi.registerCommand("unipi:compact-recall", {
+  // ── /unipi:session-recall (new) ─────────────────────
+  const sessionRecallHandler = async (args: string, ctx: any) => {
+    const query = args.trim();
+    if (!query) {
+      ctx.ui.notify("Usage: /unipi:session-recall <query>", "warning");
+      return;
+    }
+    const blocks = deps?.getBlocks() ?? [];
+    if (blocks.length === 0) {
+      ctx.ui.notify("No session history available for search.", "warning");
+      return;
+    }
+    const result = vccRecall(blocks, { query, limit: 10 });
+    if (result.hits.length === 0) {
+      ctx.ui.notify(`No results for "${query}".`, "info");
+      return;
+    }
+    const lines = result.hits.map(
+      (h, i) => `[${i + 1}] score=${h.score.toFixed(2)} kind=${h.kind}\n${h.text.slice(0, 200)}`,
+    );
+    ctx.ui.notify(`Found ${result.total} results:\n${lines.join("\n\n")}`, "info");
+  };
+  pi.registerCommand("unipi:session-recall", {
     description: "Search session history (BM25 or regex)",
+    handler: sessionRecallHandler,
+  });
+  // Deprecated alias
+  pi.registerCommand("unipi:compact-recall", {
+    description: "(DEPRECATED) Search session history — use /unipi:session-recall instead",
     handler: async (args: string, ctx: any) => {
-      const query = args.trim();
-      if (!query) {
-        ctx.ui.notify("Usage: /unipi:compact-recall <query>", "warning");
-        return;
-      }
-      const blocks = deps?.getBlocks() ?? [];
-      if (blocks.length === 0) {
-        ctx.ui.notify("No session history available for search.", "warning");
-        return;
-      }
-      const result = vccRecall(blocks, { query, limit: 10 });
-      if (result.hits.length === 0) {
-        ctx.ui.notify(`No results for "${query}".`, "info");
-        return;
-      }
-      const lines = result.hits.map(
-        (h, i) => `[${i + 1}] score=${h.score.toFixed(2)} kind=${h.kind}\n${h.text.slice(0, 200)}`,
-      );
-      ctx.ui.notify(`Found ${result.total} results:\n${lines.join("\n\n")}`, "info");
+      deprecationLog("/unipi:compact-recall", "/unipi:session-recall");
+      return sessionRecallHandler(args, ctx);
     },
   });
 
+  // ── /unipi:compact-stats ─────────────────────────────
   pi.registerCommand("unipi:compact-stats", {
     description: "Show context savings dashboard",
     handler: async (_args: string, ctx: any) => {
@@ -72,7 +96,7 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
         return;
       }
       try {
-        const stats = await ctxStats(deps.sessionDB, deps.contentStore, deps.getSessionId());
+        const stats = await ctxStats(deps.sessionDB, deps.contentStore, deps.getSessionId(), deps.getCounters?.());
         const lines = [
           "📊 Compactor Stats",
           `Session events: ${stats.sessionEvents}`,
@@ -89,6 +113,7 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
     },
   });
 
+  // ── /unipi:compact-doctor ────────────────────────────
   pi.registerCommand("unipi:compact-doctor", {
     description: "Run diagnostics checklist",
     handler: async (_args: string, ctx: any) => {
@@ -111,12 +136,14 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
     },
   });
 
+  // ── /unipi:compact-settings ──────────────────────────
   pi.registerCommand("unipi:compact-settings", {
     description: "Open TUI settings overlay",
     handler: async (_args: string, ctx: any) => {
       try {
+        const cwd = (ctx as any).cwd ?? process.cwd();
         const { renderSettingsOverlay } = await import("../tui/settings-overlay.js");
-        const result = await ctx.ui.custom(renderSettingsOverlay());
+        const result = await ctx.ui.custom(renderSettingsOverlay(cwd));
         if (result) {
           ctx.ui.notify("Settings saved.", "info");
         } else {
@@ -128,12 +155,13 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
     },
   });
 
+  // ── /unipi:compact-preset ────────────────────────────
   pi.registerCommand("unipi:compact-preset", {
-    description: "Apply quick preset (opencode/balanced/verbose/minimal)",
+    description: "Apply quick preset (precise/balanced/thorough/lean)",
     handler: async (args: string, ctx: any) => {
       const presetName = parsePreset(args.trim());
       if (!presetName) {
-        ctx.ui.notify("Unknown preset. Use: opencode, balanced, verbose, minimal", "error");
+        ctx.ui.notify("Unknown preset. Use: precise, balanced, thorough, lean", "error");
         return;
       }
       const config = applyPreset(presetName);
@@ -146,103 +174,152 @@ export function registerCommands(pi: ExtensionAPI, deps?: CommandDeps): void {
     },
   });
 
-  pi.registerCommand("unipi:compact-index", {
-    description: "Index current project files into FTS5",
-    handler: async (_args: string, ctx: any) => {
-      if (!deps?.contentStore) {
-        ctx.ui.notify("Content store not initialized. Enable fts5Index in config.", "warning");
-        return;
-      }
-      try {
-        const cwd = (ctx as any).cwd ?? process.cwd();
-        const { readdirSync, readFileSync, statSync } = await import("node:fs");
-        const { join, relative, extname } = await import("node:path");
-
-        const indexable = [".md", ".txt", ".ts", ".js", ".json", ".py", ".sh"];
-        const files: string[] = [];
-
-        const walk = (dir: string, depth = 0) => {
-          if (depth > 3) return;
-          try {
-            for (const entry of readdirSync(dir, { withFileTypes: true })) {
-              if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
-              const full = join(dir, entry.name);
-              if (entry.isDirectory()) {
-                walk(full, depth + 1);
-              } else if (indexable.includes(extname(entry.name))) {
-                files.push(full);
-              }
+  // ── /unipi:content-index (new) / /unipi:compact-index (deprecated) ──
+  const contentIndexHandler = async (_args: string, ctx: any) => {
+    if (!deps?.contentStore) {
+      ctx.ui.notify("Content store not initialized. Enable fts5Index in config.", "warning");
+      return;
+    }
+    try {
+      const cwd = (ctx as any).cwd ?? process.cwd();
+      const { readdirSync, readFileSync, statSync } = await import("node:fs");
+      const { join, relative, extname } = await import("node:path");
+
+      const indexable = [".md", ".txt", ".ts", ".js", ".json", ".py", ".sh"];
+      const files: string[] = [];
+
+      const walk = (dir: string, depth = 0) => {
+        if (depth > 3) return;
+        try {
+          for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory()) {
+              walk(full, depth + 1);
+            } else if (indexable.includes(extname(entry.name))) {
+              files.push(full);
             }
-          } catch {
-            // skip unreadable dirs
-          }
-        };
-
-        walk(cwd);
-        let totalChunks = 0;
-        for (const file of files.slice(0, 100)) {
-          try {
-            const content = readFileSync(file, "utf-8");
-            if (content.length < 50) continue;
-            const ext = extname(file);
-            const ct = ext === ".md" ? "markdown" : ext === ".json" ? "json" : "plain";
-            const result = await deps.contentStore.index(relative(cwd, file), content, {
-              contentType: ct,
-              source: file,
-            });
-            totalChunks += result.totalChunks;
-          } catch {
-            // skip unreadable files
           }
+        } catch {
+          // skip unreadable dirs
+        }
+      };
+
+      walk(cwd);
+      let totalChunks = 0;
+      for (const file of files.slice(0, 100)) {
+        try {
+          const content = readFileSync(file, "utf-8");
+          if (content.length < 50) continue;
+          const ext = extname(file);
+          const ct = ext === ".md" ? "markdown" : ext === ".json" ? "json" : "plain";
+          const result = await deps.contentStore!.index(relative(cwd, file), content, {
+            contentType: ct,
+            source: file,
+          });
+          totalChunks += result.totalChunks;
+        } catch {
+          // skip unreadable files
         }
-        ctx.ui.notify(`Indexed ${Math.min(files.length, 100)} files (${totalChunks} chunks).`, "info");
-      } catch (err) {
-        ctx.ui.notify(`Index error: ${err}`, "error");
       }
+      ctx.ui.notify(`Indexed ${Math.min(files.length, 100)} files (${totalChunks} chunks).`, "info");
+    } catch (err) {
+      ctx.ui.notify(`Index error: ${err}`, "error");
+    }
+  };
+  pi.registerCommand("unipi:content-index", {
+    description: "Index current project files into FTS5",
+    handler: contentIndexHandler,
+  });
+  pi.registerCommand("unipi:compact-index", {
+    description: "(DEPRECATED) Index project files — use /unipi:content-index instead",
+    handler: async (args: string, ctx: any) => {
+      deprecationLog("/unipi:compact-index", "/unipi:content-index");
+      return contentIndexHandler(args, ctx);
     },
   });
 
-  pi.registerCommand("unipi:compact-search", {
-    description: "Search indexed content",
-    handler: async (args: string, ctx: any) => {
-      const query = args.trim();
-      if (!query) {
-        ctx.ui.notify("Usage: /unipi:compact-search <query>", "warning");
-        return;
-      }
-      if (!deps?.contentStore) {
-        ctx.ui.notify("Content store not initialized.", "warning");
+  // ── /unipi:content-search (new) / /unipi:compact-search (deprecated) ──
+  const contentSearchHandler = async (args: string, ctx: any) => {
+    const query = args.trim();
+    if (!query) {
+      ctx.ui.notify("Usage: /unipi:content-search <query>", "warning");
+      return;
+    }
+    if (!deps?.contentStore) {
+      ctx.ui.notify("Content store not initialized.", "warning");
+      return;
+    }
+    try {
+      const results = await ctxSearch(deps.contentStore!, { query, limit: 10 });
+      if (results.length === 0) {
+        ctx.ui.notify(`No results for "${query}".`, "info");
         return;
       }
-      try {
-        const results = await ctxSearch({ query, limit: 10 });
-        if (results.length === 0) {
-          ctx.ui.notify(`No results for "${query}".`, "info");
-          return;
-        }
-        const lines = results.map(
-          (r, i) => `[${i + 1}] ${r.title} (rank: ${r.rank.toFixed(3)})\n${r.content.slice(0, 200)}`,
-        );
-        ctx.ui.notify(`Found ${results.length} results:\n${lines.join("\n\n")}`, "info");
-      } catch (err) {
-        ctx.ui.notify(`Search error: ${err}`, "error");
-      }
+      const lines = results.map(
+        (r, i) => `[${i + 1}] ${r.title} (rank: ${r.rank.toFixed(3)})\n${r.content.slice(0, 200)}`,
+      );
+      ctx.ui.notify(`Found ${results.length} results:\n${lines.join("\n\n")}`, "info");
+    } catch (err) {
+      ctx.ui.notify(`Search error: ${err}`, "error");
+    }
+  };
+  pi.registerCommand("unipi:content-search", {
+    description: "Search indexed content",
+    handler: contentSearchHandler,
+  });
+  pi.registerCommand("unipi:compact-search", {
+    description: "(DEPRECATED) Search indexed content — use /unipi:content-search instead",
+    handler: async (args: string, ctx: any) => {
+      deprecationLog("/unipi:compact-search", "/unipi:content-search");
+      return contentSearchHandler(args, ctx);
     },
   });
 
-  pi.registerCommand("unipi:compact-purge", {
+  // ── /unipi:content-purge (new) / /unipi:compact-purge (deprecated) ──
+  const contentPurgeHandler = async (_args: string, ctx: any) => {
+    if (!deps?.contentStore) {
+      ctx.ui.notify("Content store not initialized.", "warning");
+      return;
+    }
+    try {
+      await deps.contentStore!.purge();
+      ctx.ui.notify("All indexed content purged.", "info");
+    } catch (err) {
+      ctx.ui.notify(`Purge error: ${err}`, "error");
+    }
+  };
+  pi.registerCommand("unipi:content-purge", {
     description: "Wipe all indexed content from FTS5",
+    handler: contentPurgeHandler,
+  });
+  pi.registerCommand("unipi:compact-purge", {
+    description: "(DEPRECATED) Wipe indexed content — use /unipi:content-purge instead",
+    handler: async (args: string, ctx: any) => {
+      deprecationLog("/unipi:compact-purge", "/unipi:content-purge");
+      return contentPurgeHandler(args, ctx);
+    },
+  });
+
+  // ── /unipi:compact-help ──────────────────────────────
+  pi.registerCommand("unipi:compact-help", {
+    description: "Show detailed compactor documentation (tier-2 skill)",
     handler: async (_args: string, ctx: any) => {
-      if (!deps?.contentStore) {
-        ctx.ui.notify("Content store not initialized.", "warning");
-        return;
-      }
-      try {
-        await deps.contentStore.purge();
-        ctx.ui.notify("All indexed content purged.", "info");
-      } catch (err) {
-        ctx.ui.notify(`Purge error: ${err}`, "error");
-      }
+      // Load tier-2 skill content — delegates to skill loading system
+      ctx.ui.notify(
+        "🗜️ Compactor Help — Use your compactor-detail skill for full documentation.\n" +
+        "Quick commands:\n" +
+        "  /unipi:compact — trigger compaction\n" +
+        "  /unipi:session-recall <query> — search session history\n" +
+        "  /unipi:content-index — index project files\n" +
+        "  /unipi:content-search <query> — search indexed content\n" +
+        "  /unipi:content-purge — wipe indexed content\n" +
+        "  /unipi:compact-stats — view stats\n" +
+        "  /unipi:compact-doctor — run diagnostics\n" +
+        "  /unipi:compact-settings — TUI settings\n" +
+        "  /unipi:compact-preset <name> — apply preset",
+        "info",
+      );
     },
   });
 }

package/src/compaction/filter-noise.ts

@@ -17,9 +17,10 @@ const NOISE_STRINGS = [
 
 const XML_WRAPPER_RE = /<(system-reminder|ide_opened_file|command-message|context-window-usage)[^>]*>[\s\S]*?<\/\1>/g;
 
-const isNoiseUserBlock = (text: string): boolean => {
+const isNoiseUserBlock = (text: string, extraPatterns: string[] = []): boolean => {
   const trimmed = text.trim();
   if (NOISE_STRINGS.some((s) => trimmed.includes(s))) return true;
+  if (extraPatterns.length > 0 && extraPatterns.some((p) => trimmed.includes(p))) return true;
   const stripped = trimmed.replace(XML_WRAPPER_RE, "").trim();
   return stripped.length === 0;
 };
@@ -27,14 +28,14 @@ const isNoiseUserBlock = (text: string): boolean => {
 const cleanUserText = (text: string): string =>
   text.replace(XML_WRAPPER_RE, "").trim();
 
-export const filterNoise = (blocks: NormalizedBlock[]): NormalizedBlock[] => {
+export const filterNoise = (blocks: NormalizedBlock[], extraPatterns?: string[]): NormalizedBlock[] => {
   const out: NormalizedBlock[] = [];
   for (const b of blocks) {
     if (b.kind === "thinking") continue;
     if (b.kind === "tool_call" && NOISE_TOOLS.has(b.name)) continue;
     if (b.kind === "tool_result" && NOISE_TOOLS.has(b.name)) continue;
     if (b.kind === "user") {
-      if (isNoiseUserBlock(b.text)) continue;
+      if (isNoiseUserBlock(b.text, extraPatterns)) continue;
       const cleaned = cleanUserText(b.text);
       if (!cleaned) continue;
       out.push({ kind: "user", text: cleaned });

package/src/compaction/hooks.ts

@@ -8,6 +8,7 @@ import { compile } from "./summarize.js";
 import { loadConfig } from "../config/manager.js";
 import { buildOwnCut } from "./cut.js";
 import type { CompactionStats } from "../types.js";
+import type { SessionDB } from "../session/db.js";
 
 export const COMPACTOR_INSTRUCTION = "__compactor__";
 
@@ -50,7 +51,10 @@ const REASON_MESSAGES: Record<import("./cut.js").OwnCutCancelReason, string> = {
   no_user_message: "compactor: Cannot compact — no user message found",
 };
 
-export function registerCompactionHooks(pi: ExtensionAPI): void {
+export function registerCompactionHooks(
+  pi: ExtensionAPI,
+  deps?: { getSessionDB?: () => SessionDB | null; getSessionId?: () => string },
+): void {
   pi.on("session_before_compact", (event, ctx) => {
     const { preparation, branchEntries, customInstructions } = event;
     const config = loadConfig();
@@ -96,6 +100,23 @@ export function registerCompactionHooks(pi: ExtensionAPI): void {
       keptTokensEst: Math.round(keptChars / 4),
     };
 
+    // Persist cumulative compaction stats
+    const sessionDB = deps?.getSessionDB?.();
+    if (sessionDB && deps?.getSessionId) {
+      try {
+        const sessionId = deps.getSessionId();
+        const charsBefore = agentMessages.reduce((sum: number, msg: any) => {
+          const c = msg.message?.content;
+          if (typeof c === "string") return sum + c.length;
+          if (Array.isArray(c)) return sum + c.reduce((s: number, p: any) => s + (p.text?.length ?? 0), 0);
+          return sum;
+        }, 0);
+        sessionDB.addCompactionStats(sessionId, charsBefore, keptChars, agentMessages.length);
+      } catch {
+        // non-fatal
+      }
+    }
+
     dbg(config.debug, "compile", { messageCount: messages.length, hasPrevSummary: !!preparation.previousSummary });
     const summary = compile({
       messages,

package/src/compaction/search-entries.ts

@@ -1,8 +1,11 @@
 /**
  * BM25-lite search over normalized message blocks
+ *
+ * Includes module-level index cache for fast repeated queries.
  */
 
 import type { NormalizedBlock } from "../types.js";
+import { createHash } from "node:crypto";
 
 interface SearchDoc {
   id: number;
@@ -63,6 +66,23 @@ export interface SearchHit {
   kind: string;
 }
 
+// Module-level index cache
+let cachedIndexHash = "";
+let cachedDocs: SearchDoc[] = [];
+let cachedIndex: Map<string, number[]> | null = null;
+let cachedDocCount = 0;
+let cachedAvgDocLen = 0;
+let cachedDocLens: Map<number, number> = new Map();
+
+export function invalidateSearchCache(): void {
+  cachedIndexHash = "";
+  cachedDocs = [];
+  cachedIndex = null;
+  cachedDocCount = 0;
+  cachedAvgDocLen = 0;
+  cachedDocLens = new Map();
+}
+
 export function searchEntries(
   blocks: NormalizedBlock[],
   query: string,
@@ -74,10 +94,37 @@ export function searchEntries(
     kind: b.kind,
   }));
 
-  const index = buildIndex(docs);
-  const docCount = docs.length;
-  const docLens = new Map(docs.map((d) => [d.id, tokenize(d.text).length]));
-  const avgDocLen = docCount > 0 ? [...docLens.values()].reduce((a, b) => a + b, 0) / docCount : 1;
+  // Compute content hash to detect blocks change
+  const hashSource = docs.length > 0
+    ? `${docs.length}:${docs[0].text.slice(0, 80)}:${docs[docs.length - 1].text.slice(-80)}`
+    : "empty";
+  const currentHash = createHash("sha256").update(hashSource).digest("hex");
+
+  // Use cached index if blocks haven't changed
+  let index: Map<string, number[]>;
+  let docCount: number;
+  let avgDocLen: number;
+  let docLens: Map<number, number>;
+
+  if (currentHash === cachedIndexHash && cachedIndex) {
+    index = cachedIndex;
+    docCount = cachedDocCount;
+    avgDocLen = cachedAvgDocLen;
+    docLens = cachedDocLens;
+  } else {
+    index = buildIndex(docs);
+    docCount = docs.length;
+    docLens = new Map(docs.map((d) => [d.id, tokenize(d.text).length]));
+    avgDocLen = docCount > 0 ? [...docLens.values()].reduce((a, b) => a + b, 0) / docCount : 1;
+
+    // Update cache
+    cachedIndexHash = currentHash;
+    cachedDocs = docs;
+    cachedIndex = index;
+    cachedDocCount = docCount;
+    cachedAvgDocLen = avgDocLen;
+    cachedDocLens = docLens;
+  }
 
   const queryTokens = tokenize(query);
   if (queryTokens.length === 0) return [];

package/src/config/manager.ts

@@ -10,6 +10,11 @@ import { DEFAULT_COMPACTOR_CONFIG } from "./schema.js";
 
 export const COMPACTOR_CONFIG_PATH = join(homedir(), ".unipi", "config", "compactor", "config.json");
 
+/** Return the per-project config path for a given project directory. */
+export function projectConfigPath(cwd: string): string {
+  return join(cwd, ".unipi", "config", "compactor.json");
+}
+
 const readJson = (path: string): Record<string, unknown> | null => {
   try {
     return JSON.parse(readFileSync(path, "utf-8"));
@@ -18,23 +23,66 @@ const readJson = (path: string): Record<string, unknown> | null => {
   }
 };
 
+/** Deep merge project overrides into global config. */
+function deepMerge<T extends Record<string, any>>(base: T, override: Partial<T>): T {
+  const result = { ...base };
+  for (const key of Object.keys(override) as (keyof T)[]) {
+    const baseVal = result[key];
+    const overrideVal = override[key];
+    if (
+      overrideVal !== undefined &&
+      typeof overrideVal === "object" &&
+      !Array.isArray(overrideVal) &&
+      overrideVal !== null &&
+      typeof baseVal === "object" &&
+      !Array.isArray(baseVal) &&
+      baseVal !== null
+    ) {
+      (result as any)[key] = deepMerge(baseVal as any, overrideVal as any);
+    } else if (overrideVal !== undefined) {
+      (result as any)[key] = overrideVal;
+    }
+  }
+  return result;
+}
+
 /**
  * Load compactor config from disk with defaults fallback.
+ * Supports per-project overrides at <cwd>/.unipi/config/compactor.json.
  */
-export function loadConfig(): CompactorConfig {
+export function loadConfig(cwd?: string): CompactorConfig {
   const parsed = readJson(COMPACTOR_CONFIG_PATH);
-  if (!parsed || typeof parsed !== "object") return structuredClone(DEFAULT_COMPACTOR_CONFIG);
-  return migrateConfig(parsed as Partial<CompactorConfig>);
+  let config: CompactorConfig;
+  if (!parsed || typeof parsed !== "object") {
+    config = structuredClone(DEFAULT_COMPACTOR_CONFIG);
+  } else {
+    config = migrateConfig(parsed as Partial<CompactorConfig>);
+  }
+
+  // Apply per-project overrides if cwd is provided and project config exists
+  if (cwd) {
+    const projPath = projectConfigPath(cwd);
+    const projOverride = readJson(projPath);
+    if (projOverride && typeof projOverride === "object") {
+      config = deepMerge(config, projOverride as Partial<CompactorConfig>);
+    }
+  }
+
+  return config;
 }
 
 /**
  * Save config to disk with schema validation.
+ * If perProject is true, saves to <cwd>/.unipi/config/compactor.json instead of global.
  */
-export function saveConfig(config: CompactorConfig): { success: boolean; error?: string } {
+export function saveConfig(config: CompactorConfig, opts?: { perProject?: boolean; cwd?: string }): { success: boolean; error?: string } {
   try {
-    const dir = dirname(COMPACTOR_CONFIG_PATH);
+    const targetPath = (opts?.perProject && opts?.cwd)
+      ? projectConfigPath(opts.cwd)
+      : COMPACTOR_CONFIG_PATH;
+    const dir = dirname(targetPath);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-    writeFileSync(COMPACTOR_CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`);
+    writeFileSync(targetPath, `${JSON.stringify(config, null, 2)}\n`);
     return { success: true };
   } catch (err) {
     return { success: false, error: String(err) };
@@ -67,6 +115,7 @@ export function migrateConfig(partial: Partial<CompactorConfig>): CompactorConfi
     fts5Index: mergeStrategy("fts5Index", defaults.fts5Index, partial.fts5Index),
     sandboxExecution: mergeStrategy("sandboxExecution", defaults.sandboxExecution, partial.sandboxExecution),
     toolDisplay: mergeStrategy("toolDisplay", defaults.toolDisplay, partial.toolDisplay),
+    pipeline: mergeStrategy("pipeline", defaults.pipeline, (partial as any).pipeline) as any,
     overrideDefaultCompaction: partial.overrideDefaultCompaction ?? defaults.overrideDefaultCompaction,
     debug: partial.debug ?? defaults.debug,
     showTruncationHints: partial.showTruncationHints ?? defaults.showTruncationHints,