@tekmidian/pai 0.5.1 → 0.5.3

package/ARCHITECTURE.md

@@ -500,6 +500,90 @@ PAI implements six Luhmann-inspired operations on the vault's dual representatio
 
 ---
 
+## Hook System
+
+PAI ships a comprehensive set of lifecycle hooks that integrate with Claude Code's hook events. Hooks are TypeScript source files (`src/hooks/ts/`) compiled to `.mjs` modules and deployed to `~/.claude/Hooks/`.
+
+### Hook Architecture
+
+```
+Claude Code Event
+    │
+    ├── stdin: JSON { session_id, transcript_path, cwd, hook_event_name }
+    │
+    ├── Hook Process (.mjs)
+    │       ├── Reads stdin for context
+    │       ├── Performs side effects (file writes, notifications)
+    │       └── Writes stdout (injected as <system-reminder> into conversation)
+    │
+    └── stderr: diagnostic logs (visible in Claude Code's hook output)
+```
+
+**Key constraint:** Not all hook events support stdout injection. `SessionStart` does. `PreCompact` does not. This matters for context preservation.
+
+### Hook Inventory
+
+| Hook | Event | Purpose |
+|------|-------|---------|
+| `load-core-context.mjs` | SessionStart | Loads PAI skill system and core configuration |
+| `load-project-context.mjs` | SessionStart | Detects project, loads notes dir, TODO, session note |
+| `initialize-session.mjs` | SessionStart | Creates numbered session note, registers in PAI registry |
+| `post-compact-inject.mjs` | SessionStart (compact) | Reads saved state and injects into post-compaction context |
+| `security-validator.mjs` | PreToolUse (Bash) | Validates shell commands against security rules |
+| `capture-all-events.mjs` | All events | Observability — logs every hook event to session timeline |
+| `context-compression-hook.mjs` | PreCompact | Extracts session state, saves checkpoint, writes temp file for relay |
+| `capture-tool-output.mjs` | PostToolUse | Records tool inputs/outputs for observability dashboard |
+| `update-tab-on-action.mjs` | PostToolUse | Updates terminal tab title based on current activity |
+| `sync-todo-to-md.mjs` | PostToolUse (TodoWrite) | Syncs Claude's internal TODO list to `Notes/TODO.md` |
+| `cleanup-session-files.mjs` | UserPromptSubmit | Cleans up stale temp files between prompts |
+| `update-tab-titles.mjs` | UserPromptSubmit | Sets terminal tab title from session context |
+| `stop-hook.mjs` | Stop | Writes work items to session note, sends notification |
+| `capture-session-summary.mjs` | SessionEnd | Final session summary written to session note |
+| `subagent-stop-hook.mjs` | SubagentStop | Captures sub-agent completion for observability |
+
+### Context Preservation Relay
+
+The most critical hook interaction is the PreCompact → SessionStart relay that preserves context across compaction:
+
+```
+PreCompact fires (context-compression-hook.mjs)
+    │
+    ├── Reads transcript JSONL from stdin { transcript_path }
+    ├── Extracts: recent user messages, work summaries, files modified, captures
+    ├── Writes checkpoint to session note (persistent)
+    ├── Writes injection payload to /tmp/pai-compact-state-{session_id}.txt
+    └── Sends notification (WhatsApp or ntfy.sh)
+
+    ⬇ Claude Code runs compaction (conversation is summarized)
+
+SessionStart(compact) fires (post-compact-inject.mjs)
+    │
+    ├── Reads /tmp/pai-compact-state-{session_id}.txt
+    ├── Outputs content to stdout → injected into post-compaction context
+    └── Deletes temp file (one-shot relay)
+```
+
+**Why the relay?** PreCompact hooks cannot inject into the conversation (stdout is ignored by Claude Code for this event). SessionStart hooks can. The temp file bridges the gap.
+
+### Building Hooks
+
+```bash
+bun run build              # Builds everything including hooks
+node scripts/build-hooks.mjs   # Build hooks only
+```
+
+The build script compiles each `.ts` hook to a self-contained `.mjs` module using `tsx` bundling, then copies them to the configured hooks directory (`~/.claude/Hooks/` by default).
+
+### Adding a New Hook
+
+1. Create the TypeScript source in the appropriate `src/hooks/ts/<event>/` directory
+2. Read stdin for `HookInput` JSON (session_id, transcript_path, cwd, hook_event_name)
+3. Use stderr for diagnostics, stdout only if the event supports injection
+4. Register the hook in `~/.claude/settings.json` under the appropriate event with the correct matcher
+5. Run `bun run build` to compile and deploy
+
+---
+
 ## Templates
 
 PAI ships three templates used during setup and customizable for your workflow.

package/README.md

@@ -60,6 +60,44 @@ Claude finds the setup skill, checks your system, runs the interactive wizard, a
 
 ---
 
+## Context Preservation
+
+When Claude's context window fills up, it compresses the conversation. Without PAI, everything from before that point is lost — Claude forgets what it was working on, what files it changed, and what you asked for.
+
+PAI intercepts this compression with a two-stage relay:
+
+1. **Before compression** — PAI extracts session state from the conversation transcript: your recent requests, work summaries, files modified, and current task context. This gets saved to a checkpoint.
+
+2. **After compression** — PAI reads that checkpoint and injects it back into Claude's fresh context. Claude picks up exactly where it left off.
+
+This happens automatically. You don't need to do anything — just keep working, and PAI handles the continuity.
+
+### What Gets Preserved
+
+- Your last 3 requests (so Claude knows what you were asking)
+- Work summaries and captured context
+- Files modified during the session
+- Current working directory and task state
+- Session note checkpoints (persistent — survive even full restarts)
+
+### Session Lifecycle Hooks
+
+PAI runs hooks at every stage of a Claude Code session:
+
+| Event | What PAI Does |
+|-------|--------------|
+| **Session Start** | Loads project context, detects which project you're in, creates a session note |
+| **User Prompt** | Cleans up temp files, updates terminal tab titles |
+| **Pre-Compact** | Saves session state checkpoint, sends notification |
+| **Post-Compact** | Injects preserved state back into Claude's context |
+| **Tool Use** | Captures tool outputs for observability |
+| **Session End** | Summarizes work done, finalizes session note |
+| **Stop** | Writes work items to session note, sends notification |
+
+All hooks are TypeScript compiled to `.mjs` modules. They run as separate processes, communicate via stdin (JSON input from Claude Code) and stdout (context injection back into the conversation).
+
+---
+
 ## Auto-Compact Context Window
 
 Claude Code can automatically compact your context window when it fills up, preventing session interruptions mid-task. PAI's statusline shows you at a glance whether auto-compact is active.
@@ -195,6 +233,62 @@ pai memory settings rerank false
 
 Settings live in the `search` section of `~/.config/pai/config.json`. Per-call parameters (CLI flags or MCP tool arguments) always override config defaults.
 
+### Using Search from Within Claude
+
+When PAI is configured as an MCP server, Claude uses the `memory_search` tool automatically. You don't need to call it yourself — just ask Claude naturally and it searches your memory behind the scenes.
+
+**Example prompts you can give Claude:**
+
+```
+"Search your memory for authentication"
+"What do you know about the database migration?"
+"Find where we discussed the notification system"
+```
+
+Claude calls `memory_search` with the right parameters based on your config defaults. Reranking and recency boost are both active by default — you don't need to configure anything for good results.
+
+**Overriding defaults for a specific search:**
+
+You can ask Claude to adjust search behavior per-query:
+
+```
+"Search for authentication using semantic mode"
+  → Claude passes mode: "semantic"
+
+"Search for the old logging discussion without recency boost"
+  → Claude passes recency_boost: 0
+
+"Search for database schema across all projects with no reranking"
+  → Claude passes all_projects: true, rerank: false
+```
+
+**The `memory_search` MCP tool accepts these parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string | Free-text search query (required) |
+| `project` | string | Scope to one project by slug |
+| `all_projects` | boolean | Explicitly search all projects |
+| `sources` | array | Restrict to `"memory"` or `"notes"` |
+| `limit` | integer | Max results (1–100, default from config) |
+| `mode` | string | `"keyword"`, `"semantic"`, or `"hybrid"` |
+| `rerank` | boolean | Cross-encoder reranking (default: true from config) |
+| `recency_boost` | integer | Recency half-life in days (0 = off, default from config) |
+
+All parameters except `query` are optional. Omitted values fall back to your `~/.config/pai/config.json` defaults.
+
+**Changing defaults permanently:**
+
+Tell Claude to change your search settings:
+
+```
+"Set my default search mode to hybrid"
+"Turn off reranking by default"
+"Change the recency boost to 60 days"
+```
+
+Claude runs `pai memory settings <key> <value>` to update `~/.config/pai/config.json`. Changes take effect on the next search — no restart needed.
+
 ---
 
 ## Zettelkasten Intelligence

package/dist/cli/index.mjs

@@ -4,13 +4,13 @@ import { _ as warn, a as fmtDate, c as ok, d as scaffoldProjectDirs, f as shorte
 import { a as slugify$1, i as parseSessionFilename, n as decodeEncodedDir, t as buildEncodedDirMap } from "../migrate-jokLenje.mjs";
 import { n as ensurePaiMarker, t as discoverPaiMarkers } from "../pai-marker-CXQPX2P6.mjs";
 import { n as openFederation } from "../db-Dp8VXIMR.mjs";
-import { a as indexProject, n as embedChunks, r as indexAll } from "../indexer-CKQcgKsz.mjs";
+import { a as indexProject, n as embedChunks, r as indexAll } from "../indexer-CMPOiY1r.mjs";
 import "../embeddings-DGRAPAYb.mjs";
 import { n as populateSlugs, r as searchMemory } from "../search-_oHfguA5.mjs";
 import { a as expandHome, i as ensureConfigDir, n as CONFIG_FILE$2, o as loadConfig$1, t as CONFIG_DIR } from "../config-Cf92lGX_.mjs";
 import { n as formatDetection, r as formatDetectionJson, t as detectProject } from "../detect-BU3Nx_2L.mjs";
 import { t as PaiClient } from "../ipc-client-Bjg_a1dc.mjs";
-import { t as createStorageBackend } from "../factory-CeXQzlwn.mjs";
+import { t as createStorageBackend } from "../factory-Bzcy70G9.mjs";
 import { appendFileSync, chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, renameSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
@@ -1811,7 +1811,7 @@ function cmdActive(db, opts) {
 async function cmdAutoRoute(opts) {
 	const { autoRoute, formatAutoRoute, formatAutoRouteJson } = await import("../auto-route-BG6I_4B1.mjs");
 	const { openRegistry } = await import("../db-4lSqLFb8.mjs").then((n) => n.t);
-	const { createStorageBackend } = await import("../factory-CeXQzlwn.mjs").then((n) => n.n);
+	const { createStorageBackend } = await import("../factory-Bzcy70G9.mjs").then((n) => n.n);
 	const { loadConfig } = await import("../config-Cf92lGX_.mjs").then((n) => n.r);
 	const config = loadConfig();
 	const registryDb = openRegistry();
@@ -2341,7 +2341,7 @@ async function countVectorDbPaths(oldPaths) {
 	if (oldPaths.length === 0) return 0;
 	try {
 		const { loadConfig } = await import("../config-Cf92lGX_.mjs").then((n) => n.r);
-		const { PostgresBackend } = await import("../postgres-CIxeqf_n.mjs");
+		const { PostgresBackend } = await import("../postgres-FXrHDPcE.mjs");
 		const config = loadConfig();
 		if (config.storageBackend !== "postgres") return 0;
 		const pgBackend = new PostgresBackend(config.postgres ?? {});
@@ -2368,7 +2368,7 @@ async function updateVectorDbPaths(moves) {
 	if (moves.length === 0) return 0;
 	try {
 		const { loadConfig } = await import("../config-Cf92lGX_.mjs").then((n) => n.r);
-		const { PostgresBackend } = await import("../postgres-CIxeqf_n.mjs");
+		const { PostgresBackend } = await import("../postgres-FXrHDPcE.mjs");
 		const config = loadConfig();
 		if (config.storageBackend !== "postgres") return 0;
 		const pgBackend = new PostgresBackend(config.postgres ?? {});
@@ -3737,7 +3737,7 @@ function cmdLogs(opts) {
 }
 function registerDaemonCommands(daemonCmd) {
 	daemonCmd.command("serve").description("Start the PAI daemon in the foreground").action(async () => {
-		const { serve } = await import("../daemon-a1W4KgFq.mjs").then((n) => n.t);
+		const { serve } = await import("../daemon-D9evGlgR.mjs").then((n) => n.t);
 		const { loadConfig: lc, ensureConfigDir } = await import("../config-Cf92lGX_.mjs").then((n) => n.r);
 		ensureConfigDir();
 		await serve(lc());
@@ -4142,9 +4142,18 @@ function mergeEnv(settings, incoming, report) {
 	return changed;
 }
 /**
+* Strip file extension from a command basename for extension-agnostic dedup.
+* This ensures that e.g. "context-compression-hook.ts" and
+* "context-compression-hook.mjs" are treated as the same hook.
+*/
+function commandStem(cmd) {
+	return (cmd.split("/").pop() ?? cmd).replace(/\.(mjs|ts|js|sh)$/, "");
+}
+/**
 * Collect every command string already registered for a given hookType.
-* Stores both the full command and the basename for flexible matching
-* (handles ${PAI_DIR}/Hooks/foo.sh vs /Users/.../Hooks/foo.sh).
+* Stores full command, basename, AND extension-stripped stem for flexible
+* matching (handles ${PAI_DIR}/Hooks/foo.sh vs /Users/.../Hooks/foo.sh,
+* and .ts → .mjs migrations).
 */
 function existingCommandsForHookType(rules) {
 	const cmds = /* @__PURE__ */ new Set();
@@ -4152,11 +4161,30 @@ function existingCommandsForHookType(rules) {
 		cmds.add(entry.command);
 		const base = entry.command.split("/").pop();
 		if (base) cmds.add(base);
+		cmds.add(commandStem(entry.command));
 	}
 	return cmds;
 }
 /**
+* Find and remove an existing rule whose command has the same stem
+* (extension-agnostic) as the incoming command. Returns true if a
+* replacement was made. This handles .ts → .mjs migrations cleanly.
+*/
+function replaceStaleHook(existingRules, incomingStem, incomingCommand, incomingMatcher) {
+	for (let i = 0; i < existingRules.length; i++) {
+		const rule = existingRules[i];
+		for (let j = 0; j < rule.hooks.length; j++) if (commandStem(rule.hooks[j].command) === incomingStem && rule.hooks[j].command !== incomingCommand) {
+			rule.hooks[j].command = incomingCommand;
+			if (incomingMatcher !== void 0) rule.matcher = incomingMatcher;
+			return true;
+		}
+	}
+	return false;
+}
+/**
 * Merge hooks — append entries, deduplicating by command string.
+* Extension-agnostic: a .mjs hook replaces an existing .ts hook with the
+* same stem, ensuring clean .ts → .mjs migrations without duplicates.
 */
 function mergeHooks(settings, incoming, report) {
 	let changed = false;
@@ -4164,12 +4192,21 @@ function mergeHooks(settings, incoming, report) {
 	for (const entry of incoming) {
 		const { hookType, matcher, command } = entry;
 		const existingRules = Array.isArray(hooksSection[hookType]) ? hooksSection[hookType] : [];
-		const existingCmds = existingCommandsForHookType(existingRules);
 		const basename = command.split("/").pop() ?? command;
+		const stem = commandStem(command);
+		const existingCmds = existingCommandsForHookType(existingRules);
 		if (existingCmds.has(command) || existingCmds.has(basename)) {
 			report.push(chalk.dim(`  Skipped: hook ${hookType} → ${basename} already registered`));
 			continue;
 		}
+		if (existingCmds.has(stem)) {
+			if (replaceStaleHook(existingRules, stem, command, matcher)) {
+				hooksSection[hookType] = existingRules;
+				report.push(chalk.yellow(`  Upgraded: hook ${hookType} → ${basename} (replaced stale extension)`));
+				changed = true;
+				continue;
+			}
+		}
 		const newRule = { hooks: [{
 			type: "command",
 			command
@@ -4874,6 +4911,7 @@ async function stepTsHooks(rl) {
 	line$1();
 	let copiedCount = 0;
 	let skippedCount = 0;
+	let cleanedCount = 0;
 	for (const filename of allFiles) {
 		const src = join(distHooksDir, filename);
 		const dest = join(hooksTarget, filename);
@@ -4882,6 +4920,12 @@ async function stepTsHooks(rl) {
 			if (srcContent === readFileSync(dest, "utf-8")) {
 				console.log(c.dim(`  Unchanged: ${filename}`));
 				skippedCount++;
+				const staleTsPath = join(hooksTarget, filename.replace(/\.mjs$/, ".ts"));
+				if (existsSync(staleTsPath)) {
+					unlinkSync(staleTsPath);
+					console.log(c.ok(`Cleaned up stale: ${filename.replace(/\.mjs$/, ".ts")}`));
+					cleanedCount++;
+				}
 				continue;
 			}
 		}
@@ -4889,11 +4933,22 @@ async function stepTsHooks(rl) {
 		chmodSync(dest, 493);
 		console.log(c.ok(`Installed: ${filename}`));
 		copiedCount++;
+		const staleTsPath = join(hooksTarget, filename.replace(/\.mjs$/, ".ts"));
+		if (existsSync(staleTsPath)) {
+			unlinkSync(staleTsPath);
+			console.log(c.ok(`Cleaned up stale: ${filename.replace(/\.mjs$/, ".ts")}`));
+			cleanedCount++;
+		}
 	}
 	line$1();
-	if (copiedCount > 0) console.log(c.ok(`${copiedCount} hook(s) installed, ${skippedCount} unchanged.`));
-	else console.log(c.dim(`  All ${skippedCount} hook(s) already up-to-date.`));
-	return copiedCount > 0;
+	if (copiedCount > 0 || cleanedCount > 0) {
+		const parts = [];
+		if (copiedCount > 0) parts.push(`${copiedCount} hook(s) installed`);
+		if (skippedCount > 0) parts.push(`${skippedCount} unchanged`);
+		if (cleanedCount > 0) parts.push(`${cleanedCount} stale .ts file(s) cleaned up`);
+		console.log(c.ok(parts.join(", ") + "."));
+	} else console.log(c.dim(`  All ${skippedCount} hook(s) already up-to-date.`));
+	return copiedCount > 0 || cleanedCount > 0;
 }
 /**
 * Step 8b: Prompt for the DA (Digital Assistant) name
@@ -4952,6 +5007,11 @@ async function stepSettings(rl, daName) {
 				hookType: "SessionStart",
 				command: "${PAI_DIR}/Hooks/capture-all-events.mjs --event-type SessionStart"
 			},
+			{
+				hookType: "SessionStart",
+				matcher: "compact",
+				command: "${PAI_DIR}/Hooks/post-compact-inject.mjs"
+			},
 			{
 				hookType: "UserPromptSubmit",
 				command: "${PAI_DIR}/Hooks/cleanup-session-files.mjs"