@tekmidian/pai 0.9.6 → 0.9.8

package/FEATURE.md

@@ -48,7 +48,14 @@ different direction: persistent memory, session continuity, and deep Claude Code
 | **Session note reconstruction** | No | Yes — /reconstruct skill retroactively creates notes from JSONL + git history |
 | **Backup / restore** | No | Yes — timestamped pg_dump + registry export |
 | **Multi-session concurrency** | n/a | Yes — daemon multiplexes Claude sessions |
-| **Custom statusline** | No | Yes — model, MCPs, context meter, colors |
+| **Budget-aware advisor mode** | No | Yes — auto-adjusts subagent model tiering based on weekly usage (normal/conservative/strict/critical) |
+| **Natural language mode switching** | No | Yes — say "go easy on the budget" or "lock it down" to change advisor mode |
+| **22 built-in skills** | No | Yes — /review, /plan, /journal, /share, /whisper, /advisor, /reconstruct, /consolidate, /vault-*, /research, /art, and more |
+| **God-note detection** | No | Yes — detects overgrown session notes with confidence tagging, Louvain community detection |
+| **Privacy tags** | Yes — `<private>` blocks excluded from memory | Yes — `<private>` blocks stripped before indexing, never stored or searched |
+| **3-layer search pattern** | Yes — search index → timeline → get_observations | Yes — compact format (~50 tokens/result) → memory_get for full content |
+| **One-command install** | Yes — `npx claude-mem install` | Yes — `npx @tekmidian/pai install` |
+| **Custom statusline** | No | Yes — model, MCPs, context meter, usage limits, advisor mode, pace indicator, colors |
 | **Local / private** | Yes | Yes — no cloud, no external API for core |
 | **Docker required** | No | Only for full mode (PostgreSQL); SQLite mode needs none |
 | **macOS / Linux** | Yes | Yes |

package/README.md

@@ -1,7 +1,59 @@
-# PAI Knowledge OS — v0.8.0
+# PAI Knowledge OS — v0.9.7
 
 Claude Code has a memory problem. Every new session starts cold — no idea what you built yesterday, what decisions you made, or where you left off. PAI fixes this.
 
+Install PAI and Claude remembers. Ask it what you were working on. Ask it to find that conversation about the database schema. Ask it to pick up exactly where the last session ended. It knows.
+
+## Quick Start
+
+Tell Claude Code:
+
+> Clone https://github.com/mnott/PAI and set it up for me
+
+Or install with a single command:
+
+```bash
+npx @tekmidian/pai install
+```
+
+Or manually:
+
+### 1. Install
+
+```bash
+git clone https://github.com/mnott/PAI
+cd PAI
+bun install
+bun run build
+```
+
+### 2. Run the setup wizard
+
+```bash
+pai setup
+```
+
+The wizard walks you through: storage mode (SQLite or PostgreSQL), project directories, Obsidian vault path, MCP server registration, CLAUDE.md template, and daemon configuration. It's idempotent — safe to re-run anytime.
+
+### 3. Start the daemon
+
+```bash
+pai daemon start
+```
+
+The daemon runs in the background via launchd, indexing your sessions and serving the MCP tools. It starts automatically on login.
+
+### 4. Verify
+
+```bash
+pai daemon status    # should show "running"
+pai memory search "test"   # should return results after indexing
+```
+
+That's it. Claude Code now has persistent memory across all sessions.
+
+---
+
 ## Automatic Session Notes — by Topic
 
 PAI's headline feature: **every session is automatically documented.** No manual note-taking, no "pause session" commands, no forgetting to save what you did.
@@ -96,15 +148,112 @@ This is not a template or a skeleton. These are real notes with build error chro
 - "Suggest connections for this note" — proactive link suggestions using semantic + graph signals
 - "What does my vault say about knowledge management?" — use the vault as a thinking partner
 
+### Budget Management
+
+- "How much budget do I have left?" — shows current weekly usage and advisor mode
+- "Go easy on the budget" — switches to conservative mode (prefer haiku subagents)
+- "Lock it down" — switches to critical mode (minimize all token usage)
+- "Go full power" — switches to normal mode (no constraints)
+- "Back to auto" — resets to auto mode (derives from weekly budget percentage)
+
 ---
 
-## Quick Start
+## Skills
 
-Tell Claude Code:
+PAI ships 22 skills — slash commands that activate specialized workflows. Each responds to natural language triggers as well as the `/command` syntax.
 
-> Clone https://github.com/mnott/PAI and set it up for me
+### Productivity
+
+| Skill | Trigger | What it does |
+|-------|---------|-------------|
+| `/advisor` | "budget mode", "save budget", "go easy on the budget" | Manage budget-aware model tiering for subagents |
+| `/plan` | "plan my week", "what should I focus on", "priorities" | Plan tomorrow/week/month based on open tasks and calendar |
+| `/review` | "review my week", "what did I do", "recap" | Daily/weekly/monthly review of work accomplished |
+| `/journal` | "journal", "note to self", "capture this thought" | Create, read, or search personal journal entries |
+| `/share` | "share on LinkedIn", "tweet about", "post to Bluesky" | Generate social media posts about completed work |
+
+### Session Management
+
+| Skill | Trigger | What it does |
+|-------|---------|-------------|
+| `/sessions` | "list sessions", "where was I working" | Navigate sessions, projects, switch working context |
+| `/route` | "what project is this", "tag this session" | Detect which PAI project the current session belongs to |
+| `/name` | "name this session", "rename session" | Name or rename the current session |
+| `/search-history` | "search history", "find past", "what did we do" | Search past sessions and previous work by keyword |
+| `/consolidate` | "consolidate notes", "clean up notes", "merge duplicates" | Merge duplicate session notes, fix titles, renumber |
+| `/reconstruct` | "reconstruct sessions", "backfill session notes" | Retroactively create notes from JSONL transcripts and git history |
+
+### Obsidian Vault
 
-Claude finds the setup skill, checks your system, runs the interactive wizard, and configures itself. You answer a few questions — simple mode or full mode, where your projects live, whether you use Obsidian — and Claude does the rest.
+| Skill | Trigger | What it does |
+|-------|---------|-------------|
+| `/vault-context` | "morning briefing", "load vault context" | Load Obsidian vault context for a briefing |
+| `/vault-connect` | "connect X and Y", "how does X relate to Y" | Find connections between two topics in the vault |
+| `/vault-emerge` | "what's emerging", "find patterns", "themes in vault" | Surface emerging themes and clusters |
+| `/vault-orphans` | "find orphans", "unlinked notes" | Find and reconnect orphaned notes with zero inbound links |
+| `/vault-trace` | "trace idea", "how did X evolve", "idea history" | Trace the evolution of an idea across vault notes over time |
+
+### Tools & System
+
+| Skill | Trigger | What it does |
+|-------|---------|-------------|
+| `/whisper` | "add whisper rule", "show whisper rules" | Manage persistent behavioral constraints injected on every prompt |
+| `/research` | "do research", "extract wisdom", "analyze content" | Web research, content extraction, and analysis via parallel agents |
+| `/art` | "create diagram", "flowchart", "visualize" | Create visual content, diagrams, flowcharts, and AI-generated images |
+| `/story` | "explain this as a story", "create story explanation" | Create numbered narrative story explanations of any content |
+| `/observability` | "start observability", "monitor agents" | Start, stop, or check the multi-agent observability dashboard |
+| `/createskill` | "create skill", "validate skill" | Create, validate, update, or canonicalize a PAI skill |
+
+---
+
+## Budget-Aware Advisor Mode
+
+PAI tracks your weekly Claude usage and automatically adjusts subagent model selection to stay within budget. The statusline shows your current mode at a glance.
+
+### How it works
+
+The statusline reads your OAuth usage from the Anthropic API (5-hour and 7-day windows) and writes the weekly budget percentage to `~/.claude/advisor-mode.json`. A whisper-rules hook reads this file on every prompt and injects model-tiering guidance.
+
+### Automatic thresholds
+
+| Budget Used | Mode | Subagent Model | Behavior |
+|-------------|------|----------------|----------|
+| < 60% | normal | Any | No constraints |
+| 60–80% | conservative | Haiku preferred | Escalate to sonnet only if haiku insufficient |
+| 80–92% | strict | Haiku only | Minimize spawning, no opus subagents |
+| > 92% | critical | Haiku or none | Essential work only, minimize all token usage |
+
+### Statusline display
+
+The advisor mode label appears on the context line:
+
+```
+💎 Context: 12K / 1000K (68%) │ 5h: 3% → 13:18 │ 1d: 5% / 8% │ 7d: strict 91% → Fr. 08:00
+```
+
+Manually forced modes show a 📌 prefix (e.g. `📌normal 91%`) so you always know whether the mode was auto-calculated or manually set.
+
+### Switching modes
+
+Use `/budget` commands, `/Advisor` skill, or plain language:
+
+```
+/budget auto                  — reset to auto (budget-driven)
+/budget mode normal           — force normal mode
+/budget force haiku           — force all subagents to haiku
+
+/Advisor auto                 — same, via skill (note: capital A)
+/Advisor mode strict          — force strict mode
+
+"go full power"               — normal mode (plain language)
+"be conservative"             — conservative mode
+"lock it down"                — critical mode
+"back to auto"                — auto mode
+```
+
+Changes take effect on the next prompt — no restart needed.
+
+> **Note:** `/advisor` (lowercase) conflicts with a Claude Code built-in command. Use `/budget` or `/Advisor` (capital A) instead.
 
 ---
 
@@ -134,8 +283,8 @@ 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, auto-registers new projects, creates a session note |
-| **User Prompt** | Cleans up temp files, updates terminal tab titles, injects whisper rules on every prompt |
+| **Session Start** | Loads project context, detects which project you're in, auto-registers new projects, creates a session note, injects recent observations |
+| **User Prompt** | Cleans up temp files, updates terminal tab titles, injects whisper rules and advisor mode guidance on every prompt |
 | **Pre-Compact** | Saves session state checkpoint, pushes `session-summary` work item to daemon, sends notification |
 | **Post-Compact** | Injects preserved state back into Claude's context |
 | **Tool Use** | Classifies tool calls into structured observations (decision/bugfix/feature/refactor/discovery/change) |
@@ -261,7 +410,7 @@ A PostToolUse hook fires after every Claude Code tool call. A rule-based classif
 | **discovery** | File reads, searches | Reading code, grep searches, glob patterns |
 | **change** | File edits | Editing source files, updating configs |
 
-Observations are stored in PostgreSQL with content-hash deduplication (30-second window) to prevent duplicates from rapid tool calls.
+Observations are stored with content-hash deduplication (30-second window) to prevent duplicates from rapid tool calls.
 
 ### Progressive context injection
 
@@ -326,6 +475,50 @@ The pattern is inspired by [Letta's claude-subconscious](https://github.com/lett
 
 ---
 
+## Privacy Tags
+
+Wrap any content in `<private>...</private>` tags to exclude it from PAI's memory index. Private content is stripped before chunking — it's never stored, never searched, never surfaced.
+
+```markdown
+## API Keys
+<private>
+STRIPE_KEY=sk_live_abc123
+DATABASE_URL=postgres://user:pass@host/db
+</private>
+
+## Architecture Notes
+The payment system uses Stripe webhooks...
+```
+
+The architecture notes get indexed. The API keys don't. Works in session notes, memory files, and any markdown PAI indexes.
+
+---
+
+## Token-Efficient Search (3-Layer Pattern)
+
+For budget-conscious usage, PAI supports a compact search format that returns ~10x fewer tokens per result. Instead of fetching full snippets upfront, get a compact index first, then drill into interesting results.
+
+### The workflow
+
+```
+1. Search with format="compact"  →  IDs + paths + scores (~50 tokens/result)
+2. Review the index, pick interesting results
+3. Use memory_get to read full content for those specific files
+```
+
+### Example
+
+```
+"Search for authentication with compact format"
+  → Claude passes format: "compact" to memory_search
+  → Gets a tight index: [1] pai — src/auth.ts L10-45 score=0.892
+  → Then reads only the files that matter
+```
+
+Via MCP, pass `format: "compact"` to the `memory_search` tool. Default is `"full"` (current behavior with snippets).
+
+---
+
 ## 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.
@@ -350,7 +543,7 @@ The value is the context percentage at which compaction triggers. `80` means com
 
 ### Statusline indicator
 
-Once set, PAI's statusline shows `[auto-compact:80%]` next to the context meter on line 3, so you always know auto-compact is active and at what threshold.
+PAI's statusline shows the remaining context until auto-compact triggers as a percentage on line 3, along with your 5-hour and 7-day usage limits, daily pace indicator, and advisor mode label.
 
 ### Set it up with one prompt
 
@@ -559,6 +752,36 @@ External URLs (`https://`, `mailto:`, etc.) are excluded — only relative paths
 
 ---
 
+## Release History
+
+18 releases shipped from v0.7.2 to v0.9.7 (March 19 – April 10, 2026):
+
+| Version | Feature |
+|---------|---------|
+| v0.7.2 | Auto-registration, one-note-per-session, Reconstruct skill |
+| v0.7.3 | Automatic AI-powered session notes via daemon |
+| v0.7.4 | Auto-register on parent match |
+| v0.7.5 | Tiered model selection (opus/sonnet/haiku) |
+| v0.7.6 | Find claude binary in launchd |
+| v0.7.7 | Whisper rules hook |
+| v0.7.8 | Strip API key from daemon (prevent billing) |
+| v0.8.0 | Topic-based note splitting |
+| v0.8.1 | /whisper skill, remove hardcoded defaults |
+| v0.8.2 | Reduce topic split sensitivity |
+| v0.8.3 | /consolidate skill |
+| v0.8.4 | Store TOPIC in HTML comment |
+| v0.8.5 | God-note detection, confidence tagging, Louvain communities, query feedback |
+| v0.9.0 | 4-layer wake-up, temporal KG, taxonomy, tunnels, mid-session auto-save |
+| v0.9.1 | KG backfill CLI, shared kg-extraction module |
+| v0.9.2 | Stop-hook first-run safeguard |
+| v0.9.3 | Silence stop-hook diagnostics |
+| v0.9.4 | Remove exit(2) noise |
+| v0.9.5 | Budget-aware advisor mode |
+| v0.9.6 | Statusline auto-writes budget to advisor |
+| v0.9.7 | Advisor mode label in statusline, natural language mode switching |
+
+---
+
 ## Companion Projects
 
 PAI works great alongside these tools (also by the same author):
@@ -582,4 +805,3 @@ The automatic observation capture system — classifying tool calls into structu
 ## License
 
 MIT
-

package/dist/cli/index.mjs

@@ -4,8 +4,8 @@ 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-DdUperSl.mjs";
-import "../helpers-BEST-4Gx.mjs";
-import { i as indexProject, n as indexAll, t as embedChunks } from "../sync-BOsnEj2-.mjs";
+import "../helpers-OCVFgprQ.mjs";
+import { i as indexProject, n as indexAll, t as embedChunks } from "../sync-CdHSL9Kc.mjs";
 import "../embeddings-DGRAPAYb.mjs";
 import { t as STOP_WORDS } from "../stop-words-BaMEGVeY.mjs";
 import { n as populateSlugs, r as searchMemory } from "../search-DC1qhkKn.mjs";
@@ -3794,7 +3794,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-kp49BE7u.mjs").then((n) => n.t);
+		const { serve } = await import("../daemon-WQY1kwOF.mjs").then((n) => n.t);
 		const { loadConfig: lc, ensureConfigDir } = await import("../config-BuhHWyOK.mjs").then((n) => n.r);
 		ensureConfigDir();
 		await serve(lc());
@@ -5531,7 +5531,7 @@ async function runSetup() {
 	}
 }
 function registerSetupCommand(program) {
-	program.command("setup").description("Interactive setup wizard — configure storage, embeddings, agent config, and indexing").action(async () => {
+	program.command("setup").alias("install").description("Interactive setup wizard — configure storage, embeddings, agent config, and indexing").action(async () => {
 		await runSetup();
 	});
 }