@tekmidian/pai 1.0.0 → 1.0.2

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "pai",
   "displayName": "PAI Knowledge OS",
   "description": "Personal AI Infrastructure — persistent memory, session continuity, and knowledge graph for Claude Code",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "author": {
     "name": "Matthias Nott"
   },

package/README.md

@@ -1,25 +1,87 @@
 # PAI Knowledge OS
 
-PAI is an operating layer for Claude Code. From the first day it gives every session a memory: notes written in the background, searchable across sessions, projects and vaults, all stored locally. `pai` starts or resumes a Claude Code session in the current project, and `pai pause` and `pai end` save your place.
+## Local AI used to be hard. Now it is a button.
 
-It can also hand work to cheaper background Claude Code runs (workers) on other providers or a local model, with a router and a cockpit page that show what the models and your token budget are doing. You do not need this to start. Terms are explained in the [glossary](docs/README.md#words-used-in-these-docs).
+I have spent a long time on local AI. Getting a strong model to run on my own machine was the easy part; making it actually useful was not. Which server, which quantization, which port, how to keep it alive, how to send it only the work it can do, and how to fall back to the cloud when it cannot. Every piece worked on its own and none of them worked together.
 
-![The PAI router cockpit: limits per cloud provider, the local model server, and the routing table with one line per delegation tier](docs/images/cockpit-limits-routing.jpg)
+PAI is what came out of that, and I am giving it to the community. A MacBook can already run a serious model: on mine, [Strata](https://github.com/Niko1221/Strata) serves [Qwen3.8-Flash-Next](https://huggingface.co/Qwen/Qwen3.8-Flash-Next) in its compact [Gyro-M](https://huggingface.co/agentionai/Qwen3.8-Flash-Next-Gyro-GGUF) quantization, and PAI turns that into a worker like any other. Start it from the cockpit, and PAI routes worker jobs to it automatically, shows its speed and cache live, and hands a job to the cloud only when it needs a wider context or deeper reasoning than the local model has. You stop thinking about local AI. It just takes its share of the work.
+
+**An AI chat is one vendor, one model, one budget and no memory. PAI turns it into a team: it remembers, it routes every job to the right model, cloud or local, and it shows you all of it live.**
+
+You burn your premium tokens on work a local model could do. You hit the weekly limit on a Tuesday. Every new session starts from zero. PAI fixes all three:
+
+- **Not bound to Anthropic.** Claude Code is only the front end you type into; the model behind it is your choice. Run a whole session on GLM, Kimi, any other provider you add, or a model on your own machine, with no Anthropic model involved at all. Or mix them: switch on the fly with `/model`, in the middle of a session, without losing your place.
+- **Model routing, cloud and local.** When one provider's budget runs out, the next one takes over by itself, and every request is accounted per provider and per session.
+- **A hierarchy that spends tokens where they matter.** Three tiers: `t0` the session you talk to, `t1` the orchestrator that plans and reviews, `t2` the workers that implement. Workers go local first, because local tokens are free. Cloud comes first only where it earns its price: wide context and real reasoning. And all of it is yours to set: each tier is an ordered list of models, the first available one serves, and you change the order as your default (`pai worker route set t2 local,glm/glm-5.3-flash`, or from the cockpit) or just for one session (`--session <name>`), without touching the others. Every worker runs in its own visible pane and git worktree; you review the diff, PAI merges it.
+- **A live cockpit.** One page shows your token budget per provider, cache hits, every model and local server with start and stop buttons, running workers, routing per tier, and memory and embedding progress. Drag the cards into the layout you want.
+- **Memory underneath it all.** Every session writes its own notes in the background, searchable across sessions, projects and your notes vault, by keyword, meaning or both. Everything stays on your machine.
+
+**What's inside**
+
+- Sessions: [pick and open](docs/features.md#pick-and-open-a-session) · [pause and end](docs/features.md#pause-and-end-a-session) · [session notes](docs/features.md#session-notes) · [context preservation](docs/features.md#context-preservation-and-auto-compact)
+- Memory and search: [search memory](docs/features.md#search-your-memory) · [knowledge graph](docs/features.md#knowledge-graph) · [embeddings](docs/features.md#index-and-embeddings) · [observations](docs/features.md#observations)
+- Notes and vault: [connect two ideas](docs/features.md#connect-two-ideas) · [find orphans](docs/features.md#find-orphans) · [what is emerging](docs/features.md#what-is-emerging) · [trace an idea](docs/features.md#trace-an-idea)
+- Zettelkasten: [explore links](docs/features.md#explore-links) · [surprising connections](docs/features.md#surprising-connections) · [ask the vault](docs/features.md#ask-the-vault) · [vault health](docs/features.md#vault-health)
+- Journal, review, plan: [journal](docs/features.md#journal) · [review](docs/features.md#review) · [plan](docs/features.md#plan)
+- Tasks and ingress: [Todoist](docs/features.md#todoist-as-an-input-channel) · [GitHub issues](docs/features.md#github-issues-as-an-input-channel) · [PAILot](docs/features.md#pailot-as-an-input-channel) · [WhatsApp](docs/features.md#whatsapp-as-an-input-channel) · [Telegram](docs/features.md#telegram-as-an-input-channel)
+- Workers: [run a worker](docs/features.md#run-a-worker) · [tiers and routing](docs/features.md#tiers-and-routing) · [local models](docs/features.md#local-models) · [plans](docs/features.md#plans) · [queue](docs/features.md#queue)
+- Router and cockpit: [router](docs/features.md#router) · [cockpit](docs/features.md#cockpit) · [where tokens go](docs/features.md#where-tokens-go)
+- Messaging and rules: [AIBroker](docs/features.md#aibroker) · [whisper rules](docs/features.md#whisper-rules) · [budget advisor](docs/features.md#budget-and-advisor-mode)
+- Make and share: [art and diagrams](docs/features.md#art-and-diagrams) · [share](docs/features.md#share) · [research](docs/features.md#research-and-extraction)
+- Care: [setup](docs/features.md#setup-and-update) · [backup](docs/features.md#backup-and-restore)
+
+Everything PAI does: [docs/features.md](docs/features.md)
+
+`pai` starts or resumes a session in the current project. `pai pause` and `pai end` save your place. Memory works on its own; the router, workers and cockpit join when you want them. Terms are explained in the [glossary](docs/README.md#words-used-in-these-docs).
+
+**Install it in one sentence: tell Claude Code "Clone https://github.com/mnott/PAI and set it up for me".** [Jump to install](#install).
+
+![Cockpit: system memory, load, temperature and power, local model server speed, and tokens per bucket and per day per model](docs/images/cockpit-01-system-tokens.jpg)
+
+![Cockpit: totals in the window, cache hit ratio per model, local prefix cache and providers](docs/images/cockpit-02-totals-cache.jpg)
+
+![Cockpit: local servers with their instances, the models with start and stop, and the worker pool](docs/images/cockpit-03-local-servers-models-pool.jpg)
+
+![Cockpit: workers running and waiting, and the memory section with backend, passes, embedding and index progress](docs/images/cockpit-04-workers-memory.jpg)
+
+![Cockpit: performance details with the cache verdict by pause and sessions by tokens](docs/images/cockpit-05-performance.jpg)
+
+![Cockpit: worker runs, speed per model, and routing with one line per delegation tier](docs/images/cockpit-06-runs-speed-routing.jpg)
+
+![Cockpit: settings with the model registry editor and its backups](docs/images/cockpit-07-settings-registry.jpg)
 
 *The router cockpit (`http://127.0.0.1:8790/cockpit`). See [the cockpit page](docs/cockpit.md).*
 
+## How it fits together
+
+<img src="docs/images/architecture.svg" width="100%" alt="PAI architecture: Claude Code sessions with PAI hooks and skills on top; PAI core (CLI, daemon, storage, notes, router on port 8790 with tiers t0, t1, t2 and the cockpit, workers) side by side with AIBroker (messaging hub, session control, inbound channels with prefixes); ingress from Todoist, GitHub issues, PAILot, WhatsApp and Telegram feeding AIBroker; model providers Anthropic, other cloud and local models behind the router; an operating system layer with iTerm2 and tmux for worker panes and session tabs, launchd or systemd services, and git worktrees">
+
+*Source: [docs/images/architecture.drawio](docs/images/architecture.drawio), editable in draw.io.*
+
 ## Install
 
 Prerequisites: [Claude Code](https://claude.com/claude-code) and Node.js 20 or newer. Docker is only needed for the optional PostgreSQL storage (semantic search); the default sqlite needs nothing.
 
-Inside Claude Code, add this repository as a plugin marketplace and install the `pai` plugin:
+The easy way: tell Claude Code
+
+> Clone https://github.com/mnott/PAI and set it up for me
+
+Claude reads this repository, finds the setup skill and walks you through it: it checks each phase first, does only what is missing, and ends with a pass/fail list of its checks.
+
+Or install it as a plugin, then say **"set up PAI"**:
 
 ```
 /plugin marketplace add mnott/PAI
 /plugin install pai@pai
 ```
 
-Then say **"set up PAI"**. `/plugin` lists `pai` once it is installed. The skill checks each phase first and does only what is missing, and ends with a pass/fail list of its checks.
+Setup also installs [AIBroker](https://github.com/mnott/AIBroker), a separate project that is PAI's messaging layer: messages between sessions, worker reports to the session that started them, terminal tab names, and WhatsApp, Telegram and PAILot all go through it. PAI starts without it, but none of that works until it is there. To install it by hand:
+
+```bash
+npm install -g aibroker@^0.62.4
+aibroker setup      # service, MCP registration, Claude Code hooks
+aibroker doctor     # every check green, or it says exactly what to fix
+```
 
 Without the plugin, from a clone, or for a one-session plugin load: [docs/install/index.md](docs/install/index.md). Memory works as soon as setup is done; workers are optional ([First workers](docs/install/first-workers.md)).
 

package/dist/aibroker-client-BxzeEHPF.mjs

@@ -0,0 +1,3 @@
+import { i as switchToSession, n as fetchLiveSessions, r as sendToSession, t as callAiBroker } from "./aibroker-client-CQPGqLxL.mjs";
+
+export { callAiBroker, sendToSession };

package/dist/{aibroker-client-CXEYBzbf.mjs → aibroker-client-CQPGqLxL.mjs}

@@ -177,4 +177,4 @@ async function switchToSession(target, opts = {}) {
 
 //#endregion
 export { switchToSession as i, fetchLiveSessions as n, sendToSession as r, callAiBroker as t };
-//# sourceMappingURL=aibroker-client-CXEYBzbf.mjs.map
+//# sourceMappingURL=aibroker-client-CQPGqLxL.mjs.map

package/dist/atomic-file-BorMa4T3.mjs

@@ -0,0 +1,21 @@
+import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { dirname } from "node:path";
+
+//#region src/config/atomic-file.ts
+/** Write text to a temp file and rename it over `path`: a crash mid-write leaves the old file intact. */
+function writeFileAtomic(path, text) {
+	mkdirSync(dirname(path), { recursive: true });
+	const tmp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+	try {
+		writeFileSync(tmp, text, "utf8");
+		renameSync(tmp, path);
+	} catch (e) {
+		rmSync(tmp, { force: true });
+		throw e;
+	}
+}
+
+//#endregion
+export { writeFileAtomic as t };
+//# sourceMappingURL=atomic-file-BorMa4T3.mjs.map

package/dist/{auto-route-D5SXrMpB.mjs → auto-route-B4azPk4l.mjs}

@@ -1,5 +1,5 @@
-import { r as readPaiMarker } from "./pai-marker-kIYuNt3c.mjs";
-import { i as populateSlugs } from "./search-CPoE0830.mjs";
+import { r as readPaiMarker } from "./pai-marker-DurzIbw8.mjs";
+import { i as populateSlugs } from "./search-RSyeQqj1.mjs";
 import { existsSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 
@@ -158,4 +158,4 @@ function formatAutoRouteJson(result) {
 
 //#endregion
 export { formatAutoRouteJson as n, detectTopicShift as r, autoRoute as t };
-//# sourceMappingURL=auto-route-D5SXrMpB.mjs.map
+//# sourceMappingURL=auto-route-B4azPk4l.mjs.map

package/dist/auto-route-BjoMHKyI.mjs

@@ -0,0 +1,11 @@
+import "./config-XpZWOYOG.mjs";
+import "./config-Bu1_vbY8.mjs";
+import "./paths-CHifubDh.mjs";
+import "./worktree-CrnOqTBW.mjs";
+import "./status-ggJ7lgVg.mjs";
+import "./pool-BRvoOkv6.mjs";
+import "./registrable-Uzgmfyhz.mjs";
+import "./pai-marker-DurzIbw8.mjs";
+import { n as formatAutoRouteJson, t as autoRoute } from "./auto-route-B4azPk4l.mjs";
+
+export { autoRoute, formatAutoRouteJson };

package/dist/budget-Dod6rnA9.mjs

@@ -0,0 +1,15 @@
+import "./config-XpZWOYOG.mjs";
+import "./config-Bu1_vbY8.mjs";
+import "./paths-CHifubDh.mjs";
+import "./status-ggJ7lgVg.mjs";
+import "./scope-D-h6F6DN.mjs";
+import { A as budgetSkipReason, D as budgetExceeded, E as budgetCache, M as budgetWall, N as fetchBudgetReading, O as budgetFresh, P as pickBudgetWindow, T as BudgetCache, j as budgetUntilLabel, k as budgetFull, w as BUDGET_TTL_MS } from "./routing-BAAST9vT.mjs";
+import "./tool-errors-7E13StWd.mjs";
+import "./wait-ByV0OyMZ.mjs";
+import "./local-tiers-BE4jGaMa.mjs";
+import "./caller-identity-yLFb7CKq.mjs";
+import "./capacity-DEveQdFV.mjs";
+import "./local-instances-DOxSgT_L.mjs";
+import "./local-candidate-DLdwQt0s.mjs";
+
+export { BUDGET_TTL_MS, BudgetCache, budgetCache, budgetExceeded, budgetFresh, budgetFull, budgetSkipReason, budgetUntilLabel, budgetWall, fetchBudgetReading, pickBudgetWindow };

package/dist/{caller-identity-CVTuiLSs.mjs → caller-identity-yLFb7CKq.mjs}

@@ -1,6 +1,7 @@
 import { g as paiHomePath, l as claudeHomeDir } from "./runtime-paths-WsO9sJFc.mjs";
-import { f as readMainConfigRaw } from "./config-BSXKyeJ1.mjs";
-import { i as itermUuid } from "./scope-D5VSQxe4.mjs";
+import { f as readMainConfigRaw } from "./config-Bu1_vbY8.mjs";
+import { i as itermUuid } from "./scope-D-h6F6DN.mjs";
+import { n as minOf } from "./min-max-DrSRUaWQ.mjs";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
@@ -271,7 +272,7 @@ async function buildNext(dir, idOrLabel, d = {}) {
 		const t = all.find((x) => x.id === idOrLabel) ?? all.find((x) => x.label === idOrLabel && x.state === "waiting");
 		if (!t) throw new Error(`no queued build "${idOrLabel}"`);
 		if (t.state !== "waiting") throw new Error(`build ${t.id} is already running`);
-		const lowest = Math.min(...all.filter((x) => x.state === "waiting").map((x) => x.seq));
+		const lowest = minOf(all.filter((x) => x.state === "waiting").map((x) => x.seq));
 		writeTicket(dir, {
 			...t,
 			seq: lowest - 1
@@ -369,5 +370,5 @@ function callerIdentity(env = process.env, deps = {}) {
 }
 
 //#endregion
-export { poolSlots as _, enqueue as a, testSlots as b, listBuildsSync as c, removeTicket as d, renderBuildQueue as f, buildSlots as g, waitReason as h, buildsDir as i, patchTicket as l, tryStart as m, buildLogPath as n, getTicket as o, ticketKind as p, buildNext as r, listBuilds as s, callerIdentity as t, releaseBuildsOf as u, slotsFor as v, stallMinutes as y };
-//# sourceMappingURL=caller-identity-CVTuiLSs.mjs.map
+export { buildSlots as _, buildsDir as a, stallMinutes as b, listBuilds as c, releaseBuildsOf as d, removeTicket as f, waitReason as g, tryStart as h, buildNext as i, listBuildsSync as l, ticketKind as m, breakStaleMutex as n, enqueue as o, renderBuildQueue as p, buildLogPath as r, getTicket as s, callerIdentity as t, patchTicket as u, poolSlots as v, testSlots as x, slotsFor as y };
+//# sourceMappingURL=caller-identity-yLFb7CKq.mjs.map

package/dist/{capacity-DaXrVj3J.mjs → capacity-DEveQdFV.mjs}

@@ -1,5 +1,5 @@
-import { m as isLocalProvider } from "./config-D5chi2LO.mjs";
-import { O as reconcileStatuses, g as isLive, s as alive, v as loadStatus, w as ownsPid, y as loadStatuses } from "./status-CvVi9cDf.mjs";
+import { m as isLocalProvider } from "./config-XpZWOYOG.mjs";
+import { O as reconcileStatuses, g as isLive, s as alive, v as loadStatus, w as ownsPid, y as loadStatuses } from "./status-ggJ7lgVg.mjs";
 import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
@@ -488,4 +488,4 @@ async function capacityGate(o) {
 
 //#endregion
 export { liveQueue as a, queuedText as c, resolveCap as d, sessionOf as f, staggerGate as h, effectiveCap as i, reorderQueue as l, recordWarmup as m, capacityGate as n, providerCap as o, sessionScopeKey as p, capacityOf as r, queueRows as s, admitCap as t, reorderQueueTo as u };
-//# sourceMappingURL=capacity-DaXrVj3J.mjs.map
+//# sourceMappingURL=capacity-DEveQdFV.mjs.map

package/dist/{chain-BcQlIlEd.mjs → chain-D-yvET_y.mjs}

@@ -1,7 +1,7 @@
-import { j as readWorkersSection, wt as appendLedger } from "./config-D5chi2LO.mjs";
-import { i as ledgerPath, u as workersLogDir } from "./paths-DoIyRnhx.mjs";
-import { $ as isFlagToken, S as newWorkerId, nt as shortText } from "./status-CvVi9cDf.mjs";
-import { t as runWorker } from "./run-ulAi5dFD.mjs";
+import { j as readWorkersSection, wt as appendLedger } from "./config-XpZWOYOG.mjs";
+import { i as ledgerPath, u as workersLogDir } from "./paths-CHifubDh.mjs";
+import { $ as isFlagToken, S as newWorkerId, nt as shortText } from "./status-ggJ7lgVg.mjs";
+import { t as runWorker } from "./run-6Q9kCPem.mjs";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
@@ -163,4 +163,4 @@ async function runChain(opts, deps = {}) {
 
 //#endregion
 export { swapPromptArg as n, runChain as t };
-//# sourceMappingURL=chain-BcQlIlEd.mjs.map
+//# sourceMappingURL=chain-D-yvET_y.mjs.map