@kernel.chat/kbot 3.97.4 → 3.99.0

package/dist/train-self.d.ts

@@ -0,0 +1,38 @@
+import { type CurateMode } from './train-curate.js';
+export interface TrainSelfOptions {
+    mode?: CurateMode;
+    baseModel?: string;
+    outputName?: string;
+    backend?: 'mlx' | 'unsloth' | 'llama-cpp' | 'together';
+    dryRun?: boolean;
+    skipCurate?: boolean;
+    skipTrain?: boolean;
+    skipDeploy?: boolean;
+    iters?: number;
+    batchSize?: number;
+    numLayers?: number;
+    learningRate?: number;
+    maxExamples?: number;
+    datasetPath?: string;
+    adapterPath?: string;
+    fusedPath?: string;
+    ggufPath?: string;
+    gradCheckpoint?: boolean;
+}
+interface StepResult {
+    step: string;
+    ok: boolean;
+    duration_ms: number;
+    details?: string;
+}
+export declare function trainSelf(opts?: TrainSelfOptions): Promise<{
+    results: StepResult[];
+    summary: string;
+}>;
+/** CLI-facing: pretty-print a run. */
+export declare function formatTrainSelfReport(r: {
+    results: StepResult[];
+    summary: string;
+}): string;
+export {};
+//# sourceMappingURL=train-self.d.ts.map

package/dist/train-self.js

@@ -0,0 +1,232 @@
+// train-self — one command to mine local corpus, fine-tune, deploy as Ollama model.
+//
+// Pipeline:
+//   1. curate — score/filter traces from ~/.kbot/teacher/ + observer/
+//   2. prepare — convert to training format (already OpenAI JSONL, mostly a validator pass)
+//   3. train — launch mlx_lm.lora (or chosen backend)
+//   4. fuse — merge LoRA adapter into base
+//   5. convert — MLX → GGUF
+//   6. deploy — register as Ollama model
+//
+// Presets:
+//   default      — general-purpose LoRA on whole corpus
+//   reasoning    — s1-style distill on thinking traces
+//   agent-trace  — tool-use specialization (Phase 4)
+//   code-only    — code-heavy filter
+//
+// Each stage is individually re-runnable via flags.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { execSync } from 'node:child_process';
+import { curate, formatCurateReport } from './train-curate.js';
+/** MLX expects a directory with train.jsonl / valid.jsonl / test.jsonl. Split one file into that shape. */
+function splitForMlx(datasetFile) {
+    const lines = readFileSync(datasetFile, 'utf-8').split('\n').filter(l => l.trim());
+    const dir = join(dirname(datasetFile), 'mlx-split');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    // Shuffle deterministically (rotate) so rerun is stable given same input
+    const shuffled = [...lines];
+    // 80 / 10 / 10
+    const nValid = Math.max(1, Math.floor(shuffled.length * 0.1));
+    const nTest = Math.max(1, Math.floor(shuffled.length * 0.1));
+    const valid = shuffled.slice(0, nValid);
+    const test = shuffled.slice(nValid, nValid + nTest);
+    const train = shuffled.slice(nValid + nTest);
+    writeFileSync(join(dir, 'train.jsonl'), train.join('\n') + '\n');
+    writeFileSync(join(dir, 'valid.jsonl'), valid.join('\n') + '\n');
+    writeFileSync(join(dir, 'test.jsonl'), test.join('\n') + '\n');
+    return dir;
+}
+const DEFAULT_BASES = {
+    'default': 'mlx-community/Qwen2.5-Coder-7B-Instruct-4bit',
+    'reasoning': 'mlx-community/DeepSeek-R1-Distill-Qwen-7B-4bit',
+    'agent-trace': 'mlx-community/Qwen2.5-Coder-7B-Instruct-4bit',
+    'code-only': 'mlx-community/Qwen2.5-Coder-14B-Instruct-4bit',
+};
+function shell(cmd, cwd) {
+    try {
+        const output = execSync(cmd, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            maxBuffer: 50 * 1024 * 1024,
+            timeout: 4 * 60 * 60 * 1000, // 4h cap per step
+            cwd,
+        });
+        return { ok: true, output: output.toString() };
+    }
+    catch (err) {
+        const e = err;
+        return { ok: false, output: [e.stdout, e.stderr, e.message].filter(Boolean).join('\n') };
+    }
+}
+function hasBin(bin) {
+    try {
+        execSync(`which ${bin}`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function trainSelf(opts = {}) {
+    const mode = opts.mode ?? 'default';
+    const backend = opts.backend ?? 'mlx';
+    const baseModel = opts.baseModel ?? DEFAULT_BASES[mode];
+    const timestamp = Date.now();
+    const outputName = opts.outputName ?? `kernel-${mode === 'default' ? 'self' : mode}:v${timestamp}`;
+    const workDir = join(homedir(), '.kbot', 'teacher', 'runs', `${mode}-${timestamp}`);
+    if (!existsSync(workDir))
+        mkdirSync(workDir, { recursive: true });
+    const datasetPath = opts.datasetPath ?? join(workDir, 'dataset.jsonl');
+    const adapterPath = opts.adapterPath ?? join(workDir, 'adapters');
+    const fusedPath = opts.fusedPath ?? join(workDir, 'fused');
+    const ggufPath = opts.ggufPath ?? join(workDir, `${outputName.replace(/:/g, '-')}.gguf`);
+    const results = [];
+    const log = (step, ok, duration, details) => results.push({ step, ok, duration_ms: duration, details });
+    // ── Stage 1: Curate ─────────────────────────────────────────────
+    if (!opts.skipCurate) {
+        const t0 = Date.now();
+        try {
+            const r = curate({
+                mode,
+                output: datasetPath,
+                maxExamples: opts.maxExamples ?? (mode === 'reasoning' ? 1500 : 3000),
+            });
+            log('curate', r.kept > 0, Date.now() - t0, formatCurateReport(r));
+            if (r.kept === 0) {
+                return {
+                    results,
+                    summary: `No examples passed the curator. Seed ~/.kbot/teacher/traces.jsonl by using kbot normally, then retry.`,
+                };
+            }
+        }
+        catch (err) {
+            log('curate', false, Date.now() - t0, err instanceof Error ? err.message : String(err));
+            return { results, summary: 'Curate failed. See results.' };
+        }
+    }
+    if (opts.dryRun) {
+        return { results, summary: `Dry run. Dataset at ${datasetPath}. Would train ${baseModel} → ${outputName}.` };
+    }
+    // ── Stage 2: Train ──────────────────────────────────────────────
+    if (!opts.skipTrain) {
+        if (backend === 'mlx' && !hasBin('mlx_lm.lora')) {
+            log('train', false, 0, 'mlx_lm.lora not found. Install: pip install mlx-lm');
+            return { results, summary: 'MLX not installed.' };
+        }
+        const t0 = Date.now();
+        if (backend === 'mlx') {
+            const iters = opts.iters ?? (mode === 'reasoning' ? 1500 : 1000);
+            const batch = opts.batchSize ?? 1;
+            const layers = opts.numLayers ?? 8;
+            const lr = opts.learningRate ?? 1e-5;
+            const grad = opts.gradCheckpoint !== false ? '--grad-checkpoint' : '';
+            // MLX expects a directory with train/valid/test.jsonl
+            const dataDir = splitForMlx(datasetPath);
+            const cmd = [
+                'mlx_lm.lora',
+                '--model', baseModel,
+                '--train',
+                '--data', dataDir,
+                '--batch-size', String(batch),
+                '--num-layers', String(layers),
+                '--iters', String(iters),
+                '--learning-rate', String(lr),
+                '--adapter-path', adapterPath,
+                grad,
+            ].filter(Boolean).join(' ');
+            const r = shell(cmd);
+            log('train', r.ok, Date.now() - t0, r.output.split('\n').slice(-15).join('\n'));
+            if (!r.ok)
+                return { results, summary: 'Training failed. See log.' };
+        }
+        else if (backend === 'together') {
+            // Cloud fallback — delegate to existing train_start tool expectations
+            log('train', false, Date.now() - t0, 'Cloud backend: use `kbot train_start --backend together` directly; train-self cloud flow not yet implemented.');
+            return { results, summary: 'Cloud backend not wired in train-self yet.' };
+        }
+        else {
+            log('train', false, Date.now() - t0, `Backend ${backend} not yet wired; use mlx.`);
+            return { results, summary: `Backend ${backend} not supported in train-self yet.` };
+        }
+    }
+    // ── Stage 3: Fuse adapter ───────────────────────────────────────
+    if (!opts.skipTrain && hasBin('mlx_lm.fuse')) {
+        const t0 = Date.now();
+        const cmd = [
+            'mlx_lm.fuse',
+            '--model', baseModel,
+            '--adapter-path', adapterPath,
+            '--save-path', fusedPath,
+        ].join(' ');
+        const r = shell(cmd);
+        log('fuse', r.ok, Date.now() - t0, r.output.split('\n').slice(-8).join('\n'));
+        if (!r.ok)
+            return { results, summary: 'Fuse failed.' };
+    }
+    // ── Stage 4: Convert to GGUF (for Ollama) ───────────────────────
+    if (!opts.skipDeploy) {
+        const t0 = Date.now();
+        // Preferred: llama.cpp convert script
+        if (hasBin('python3')) {
+            const convertCmd = `python3 -m mlx_lm.convert --hf-path ${fusedPath} --quantize --q-bits 4 --mlx-path ${fusedPath}-mlx4`;
+            const r = shell(convertCmd);
+            log('quantize', r.ok, Date.now() - t0, r.output.split('\n').slice(-8).join('\n'));
+        }
+        else {
+            log('quantize', false, Date.now() - t0, 'python3 not available');
+        }
+    }
+    // ── Stage 5: Deploy to Ollama ───────────────────────────────────
+    if (!opts.skipDeploy && hasBin('ollama')) {
+        const t0 = Date.now();
+        // Write a Modelfile that points Ollama at the fused weights.
+        // For a first pass we use the GGUF path if it exists, else the fused dir.
+        const modelfilePath = join(workDir, 'Modelfile');
+        const fromPath = existsSync(ggufPath) ? ggufPath : fusedPath;
+        const modelfile = [
+            `FROM ${fromPath}`,
+            `PARAMETER temperature 0.2`,
+            `PARAMETER top_p 0.9`,
+            `SYSTEM "You are kbot's self-trained assistant (${mode} mode). You were fine-tuned on the operator's own agent sessions."`,
+        ].join('\n');
+        try {
+            writeFileSync(modelfilePath, modelfile);
+            const cmd = `ollama create ${outputName} -f ${modelfilePath}`;
+            const r = shell(cmd);
+            log('deploy', r.ok, Date.now() - t0, r.output.split('\n').slice(-8).join('\n'));
+            if (!r.ok)
+                return { results, summary: 'Deploy failed.' };
+        }
+        catch (err) {
+            log('deploy', false, Date.now() - t0, err instanceof Error ? err.message : String(err));
+            return { results, summary: 'Deploy failed.' };
+        }
+    }
+    const allOk = results.every(r => r.ok);
+    return {
+        results,
+        summary: allOk
+            ? `Success. Model registered as Ollama: ${outputName}. Test with: kbot local && kbot --model ${outputName}`
+            : `Partial success. ${results.filter(r => r.ok).length}/${results.length} steps passed.`,
+    };
+}
+/** CLI-facing: pretty-print a run. */
+export function formatTrainSelfReport(r) {
+    const lines = ['train-self', '─'.repeat(50)];
+    for (const step of r.results) {
+        const icon = step.ok ? 'ok' : 'FAIL';
+        const ms = `${(step.duration_ms / 1000).toFixed(1)}s`;
+        lines.push(`  [${icon.padStart(4)}] ${step.step.padEnd(12)} ${ms.padStart(8)}`);
+        if (step.details) {
+            for (const d of step.details.split('\n').slice(0, 6)) {
+                lines.push(`         ${d}`);
+            }
+        }
+    }
+    lines.push('', r.summary);
+    return lines.join('\n');
+}
+//# sourceMappingURL=train-self.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernel.chat/kbot",
-  "version": "3.97.4",
+  "version": "3.99.0",
   "description": "Open-source terminal AI agent. 787+ tools, 35 agents, 20 providers. Dreams, learns, watches your system. Controls your phone. Fully local, fully sovereign. MIT.",
   "type": "module",
   "repository": {
@@ -103,6 +103,7 @@
     "!dist/**/*.test.d.ts",
     "!dist/**/*.js.map",
     "!dist/**/*.d.ts.map",
+    "skills/**/*.md",
     "README.md",
     "install.sh",
     "ollama-manifest.json"

package/skills/deployment/daemon-deployment/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: daemon-deployment
+description: Use when setting up 24/7 background workers. kbot's compound improvement depends on daemons running even when nobody is looking.
+version: 1.0.0
+author: kbot
+license: MIT
+platforms: [darwin, linux]
+metadata:
+  kbot:
+    tags: [daemon, launchd, background, 24-7, compound]
+    related_skills: [autopoiesis-loop, teacher-trace-curation]
+---
+
+# Daemon Deployment
+
+kbot's intelligence doesn't sleep. Three daemons run continuously:
+- `kbot-daemon` — code quality, i18n sync, embeddings, docs gaps (every 15 min)
+- `kbot-discovery-daemon` — self-advocacy, field intelligence (every 15 min → 24 hr cycles)
+- `kbot-social-daemon` — autonomous posting to X/Bluesky/Mastodon/LinkedIn (daily)
+
+Plus a weekly `train-self` that fine-tunes the local model on curated traces.
+
+## Iron Law
+
+```
+VERIFY THE DAEMON IS ACTUALLY RUNNING AFTER INSTALL.
+```
+
+launchd plists that fail silently are the single most common cause of "kbot feels stale" — the daemon was never loaded, so no compound improvement happened.
+
+## Install Sequence (macOS)
+
+1. `npm run daemon` — run once manually to confirm it works at all.
+2. `npm run daemon:start` — loads the launchd plist.
+3. **Verify**: `launchctl list | grep kernel.kbot` — should show a running entry with PID.
+4. **Confirm output**: `tail -f tools/daemon-reports/daemon.log` — should show activity within 15 min.
+5. **Check state**: `npm run daemon:stats` — shows task timestamps, token usage, cost savings.
+
+If any of steps 3–5 fail, the daemon is not actually running. Debug before moving on.
+
+## Per-Daemon Triggers
+
+- `com.kernel.kbot-daemon.plist` → every 15 min
+- `com.kernel.kbot-discovery.plist` → every 15 min (internal sub-cycles stagger)
+- `com.kernel.kbot-social.plist` → daily at 9am
+- `com.kernel.kbot-train-self.plist` → Sundays 3am
+
+## What You Gain
+
+- Daily digest of codebase activity (without asking).
+- i18n stays in sync across 24 languages automatically.
+- Embedding index for semantic search rebuilds overnight.
+- Social presence grows without manual posting.
+- Local fine-tune stays current with your actual work.
+
+Cost: zero. All daemon work routes through local Ollama models.
+
+## Failure Modes
+
+- **Mac sleep blocks launchd** — use `caffeinate` or enable "wake for network access" in Energy Saver if you need guaranteed intervals.
+- **Ollama not running** — daemons depend on `localhost:11434`. Either start Ollama at login OR the daemon silently no-ops. Add Ollama to Login Items.
+- **Filesystem permission errors** — daemon's user context may differ from your shell. Absolute paths in plist, check `~/.kbot/` is writable by the daemon user.
+
+## Rollback
+
+`npm run daemon:stop` unloads the plist. Work resumes manually. No state is lost — `tools/daemon-reports/state.json` persists until the daemon re-enables.
+
+## What Emerges
+
+After two weeks of active daemons, the user finds: i18n is always current, the daily digest email is actually read, social posts have engagement, the local model passes a basic task without Claude. The compound output is larger than any single feature could produce.

package/skills/deployment/ship-pipeline/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ship-pipeline
+description: Use before any release to kernel.chat or npm publish of kbot. Six gates, each must pass. Skipping a gate is how regressions ship.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [deploy, release, ship, quality, gates]
+    related_skills: [test-driven-development, systematic-debugging]
+---
+
+# Ship Pipeline
+
+Six gates, in order. Each must be green before the next runs. The `/ship` slash command executes them; you can run them manually when investigating.
+
+## Iron Law
+
+```
+NO GATE SKIPS. NO REORDERING. NO "I'LL RUN IT AFTER DEPLOY."
+```
+
+A gate that's inconvenient is a gate that's catching something. Skipping is how regressions ship to 4,800 weekly-download users.
+
+## The Gates
+
+### 1. Security (`guardian`)
+
+- Secret scan — no API keys, tokens, or `.env` content in the diff.
+- Dependency audit — `npm audit` clean or documented exceptions.
+- OWASP checks on anything touching user input or external calls.
+- SSRF guards present on new fetch calls.
+
+### 2. QA (`qa`)
+
+- `npx tsc --noEmit` — strict typecheck.
+- `npm run test` — full test suite green.
+- Any UI change: dev server + browser verification for the golden path AND one edge case.
+- No `console.log`, no commented-out code in the diff.
+
+### 3. Design (`aesthete` / `designer`)
+
+- Design tokens used, not raw values. `--rubin-primary`, not `#6B5B95`.
+- Spacing uses the scale (`--space-*`), not magic numbers.
+- A11y: keyboard nav works, contrast meets AA, screen reader labels present.
+- Motion: reduced-motion media query respected.
+
+### 4. Performance (`performance`)
+
+- Bundle budget: main JS < 300KB gzip, CSS < 150KB gzip.
+- No new dependencies > 50KB gzip without discussion.
+- Lazy-load still works for route-level components.
+- Service worker cache invalidation tested.
+
+### 5. DevOps (`devops`)
+
+- Edge functions deploy cleanly to Supabase.
+- Migrations are reversible.
+- GitHub Pages build succeeds locally.
+- Version bumped correctly in package.json.
+
+### 6. Product (`product`)
+
+- Feature actually does what the issue says it does.
+- Mobile-first: tested at 375px width.
+- Empty state, loading state, error state all present.
+- The change is something a user would *notice* — not invisible plumbing shipped as a feature.
+
+## Running It
+
+- `/ship` in Claude Code runs all six in sequence.
+- Manually: `/security-audit` → `/qa` → `/design-check` → `/perf` → `/devops` → `/team` (product review).
+- For kbot itself: `cd packages/kbot && npm run typecheck && npm run test && npm run build && npm publish --dry-run`.
+
+## Anti-Pattern
+
+Running the gates in parallel "to save time." They're sequential because later gates depend on earlier ones passing (no point running design checks on a build that won't compile). The serial wait is the feature.
+
+## Rollback Plan
+
+Every deploy must have one. For kernel.chat: previous gh-pages tag. For kbot: `npm deprecate @kernel.chat/kbot@<version>` + publish a patched version. Know the rollback before shipping, not after breaking.

package/skills/emergent/forge-reflex/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: forge-reflex
+description: Use the moment you think "I don't have a tool for that." Build the tool immediately with forge_tool — never report a missing capability.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [forge, runtime-tools, limitless-execution, emergence]
+    related_skills: [specialist-routing, autopoiesis-loop]
+---
+
+# Forge Reflex
+
+Missing tools aren't blockers. Missing tools are ~90 seconds away from existing.
+
+## Iron Law
+
+```
+"I DON'T HAVE A TOOL FOR X" IS NEVER A TERMINAL STATE.
+```
+
+The correct next step is always: build it, register it, use it, move on.
+
+## Trigger
+
+Any internal thought matching one of:
+- "There's no tool for this"
+- "I would need a script"
+- "If only kbot had…"
+- "This would take manual work"
+- A user requesting something outside the registered 670+ tools
+
+## Procedure
+
+1. **Name the tool.** One verb, one noun. `fetch_rss`, `parse_ics`, `diff_binary`.
+2. **Write the JSON Schema for its inputs.** Zod-compatible.
+3. **Call `forge_tool`** with name, description, schema, and an implementation string (TS or bash).
+4. **Test once** with a known input. If it fails, patch the implementation inline.
+5. **Use it** to complete the original task.
+6. **Persist it** by writing the forge spec into `~/.kbot/plugins/<name>/` if it'll be useful again.
+
+## What Emerges
+
+Users who work with kbot for a month have 20–100 personal tools that don't exist in the core. Forge reflex is what grows kbot's surface area per user — the registered 670 is the floor, not the ceiling.
+
+## Anti-Pattern
+
+Suggesting the user write a script themselves. Telling the user "kbot doesn't support X." Both are correctness failures — the Limitless Execution doctrine treats them as bugs.
+
+## Integration with Skill Self-Authorship
+
+After forging a tool you used more than twice in a session, write a skill (`skill-self-authorship`) that documents when to reach for it. Forged tool + paired skill = permanent capability upgrade.

package/skills/emergent/mimic-hybrid/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: mimic-hybrid
+description: Use when a task blends domains. Instead of picking one mimic profile, blend two — kbot writes cleaner Next.js code when it mimics react+rust than when it mimics react alone.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [mimic, style, emergent, personality]
+    related_skills: [specialist-routing]
+---
+
+# Mimic Hybrid
+
+Mimic profiles aren't costumes. They're weighted style biases that compose. The emergent finding: two profiles combined often outperform any single profile for cross-domain work.
+
+## When to Hybridize
+
+- Next.js + performance-critical → `nextjs` + `rust`
+- React + strict typing → `react` + `typescript`
+- Python + ergonomic CLI → `python` + `claude-code`
+- Infrastructure + terse shell → `devops` + `python`
+- Blog/marketing site → `nextjs` + `copywriter`
+
+## Procedure
+
+1. `kbot mimic <primary>` — sets the primary tone.
+2. Add `--style <secondary>` to the invocation for a one-shot blend.
+3. Or edit `~/.kbot/mimic.json` with `{ primary, secondary, weight: 0.3 }` for a persistent hybrid (0.0 = pure primary, 1.0 = pure secondary).
+
+## What Blends Well
+
+- **Syntax discipline** (rust, typescript, haskell) crossed with **ergonomic framework** (react, nextjs, nuxt): cleaner type signatures, better null handling, fewer runtime surprises.
+- **Terse shell** (python, bash) crossed with **long-form** (claude-code, copywriter): commands that are both concise AND explained.
+- **Security mindset** (guardian specialist as style bias) crossed with anything: defaults to input validation and safer primitives.
+
+## What Blends Badly
+
+- Two opinionated frameworks (next.js + remix). They argue. kbot hallucinates a fusion that exists in neither.
+- Mimic profile contradicting specialist agent (style=copywriter, agent=guardian). The guardian's security hardness clashes with copywriter's persuasion tone. Pick one source of style per session.
+
+## Iron Law
+
+```
+NEVER BLEND MORE THAN TWO PROFILES AT ONCE.
+```
+
+Three-way blends degrade into a vague "AI voice." Two-way blends feel intentional.
+
+## What Emerges
+
+After a few weeks of experiments, users find their personal favorite hybrid — and it's almost never "just claude-code." The hybrid becomes part of the user's `SCRATCHPAD.md` and applies by default to every session.
+
+## Anti-Pattern
+
+Switching mimic mid-session without a commit between. The output becomes stylistically incoherent and code-review unfriendly. Mimic boundaries should align with commit boundaries.

package/skills/memory/dream-to-commit/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: dream-to-commit
+description: Use in the first session of the day. The dream engine ran overnight and left a digest — open it first, it tells you what past-you already figured out.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [dream, memory, morning-routine, consolidation]
+    related_skills: [autopoiesis-loop, memory-cascade]
+---
+
+# Dream to Commit
+
+Between sessions, the dream engine consolidates transcripts into reflections. In the morning, those reflections contain answers to questions you were about to ask — and sometimes fixes to bugs you haven't logged yet.
+
+## Iron Law
+
+```
+DO NOT START MORNING WORK WITHOUT READING LAST NIGHT'S DREAMS.
+```
+
+## The Morning Protocol
+
+1. `kbot dream status` — confirms the engine ran.
+2. `kbot dream journal --since yesterday` — reads new reflection entries. They cluster by theme.
+3. For each reflection tagged `actionable`, either:
+   - Open a commit that captures the fix / improvement kbot spotted, or
+   - Write a memory note explaining why *not* to act on it.
+4. Only after the journal is reviewed, start new work.
+
+## Why This Works
+
+The dream engine cross-references: yesterday's tool errors, uncommitted diffs, SCRATCHPAD drift, learned-router misses, and daemon reports. It has more signal than a human going through the same inputs because nothing gets forgotten between windows.
+
+## What You'll See Over Time
+
+- **Week 1**: generic reflections ("this function was modified often").
+- **Week 3**: specific forecasts ("this pattern fails on Linux — consider a platform guard").
+- **Week 8**: cross-project insights ("you re-implemented X in three repos — extract into a shared package").
+
+The quality compounds because reflections feed the reflection engine itself (three-tier memory: events → reflections → meta-reflections).
+
+## Anti-Pattern
+
+Ignoring the journal because "it's just the AI talking to itself." The journal is the only durable artifact of every session's learning. Ignoring it makes the dream engine pure cost with no dividend.
+
+## Integration
+
+- `synthesis_engine.getSynthesisContext(8)` reads the top 8 reflections into every new agent prompt automatically.
+- `corrections` loader pulls any reflection tagged `correction` into the active system prompt as a closed-loop signal.
+- The skills loader scores skills partly on overlap with recent reflection themes — yesterday's dreams bias today's relevance.

package/skills/memory/memory-cascade/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: memory-cascade
+description: Use when memory feels slow, bloated, or is contradicting itself. The 5-tier cascade has rules about what gets promoted, demoted, or forgotten — follow them or memory decays into noise.
+version: 1.0.0
+author: kbot
+license: MIT
+metadata:
+  kbot:
+    tags: [memory, cascade, reflection, consolidation]
+    related_skills: [dream-to-commit, autopoiesis-loop]
+---
+
+# Memory Cascade
+
+kbot's memory is not one store — it's five tiers that flow into each other like a karst system. Working memory fills, overflows into short-term, which consolidates into long-term, which distills into reflections, which collapse into meta-reflections. Each tier has different rules.
+
+## The Five Tiers
+
+| Tier | Location | Retention | Promotion Rule |
+|---|---|---|---|
+| 1. Working | in-process `Map<sessionId, history>` | lifetime of the session | auto-flushes to short-term on session close |
+| 2. Short-term | `~/.kbot/memory/short-term/*.jsonl` | 7 days rolling | entries tagged `important` promote to long-term |
+| 3. Long-term | `~/.kbot/memory/long-term/*.md` | indefinite | distilled into reflections nightly |
+| 4. Reflections | `~/.kbot/memory/reflections/*.md` | indefinite | aggregated into meta-reflections weekly |
+| 5. Meta-reflections | `~/.kbot/memory/meta/*.md` | indefinite | immutable signal into every prompt |
+
+## Iron Law
+
+```
+PROMOTION IS EARNED. DEMOTION IS AUTOMATIC. DELETION IS NEVER MANUAL.
+```
+
+Manually deleting memory entries breaks the cascade invariants — the reflection engine still sees dangling references. If a memory is wrong, *correct it* with a new entry pointing at the old one; don't delete.
+
+## When to Force a Promotion
+
+- The user says "remember this" — explicit flag, auto-promotes to long-term.
+- A correction was issued — auto-promotes with tag `correction` (loaded into every future prompt).
+- A project fact that decays in 30+ days — promote to long-term manually via `memory_save`.
+
+## When to Let It Demote Naturally
+
+- Session chatter, one-off context, successful completions — leave in working/short-term, let them fall out.
+- Debug state, test run output — these should not be in memory at all; filter at write time.
+
+## Reading the Cascade
+
+`getSynthesisContext(n)` loads the top-n meta-reflections into every prompt automatically. You don't need to fetch lower tiers in normal work — the cascade surfaces what's relevant. Dig into lower tiers only when:
+- You're investigating a contradiction in advice.
+- You're debugging why kbot "forgot" something.
+- You're curating teacher traces (where low-tier detail matters).
+
+## Anti-Pattern
+
+Treating memory as a notes app. If you find yourself writing `memory_save` for every session summary, you're duplicating what the dream engine does automatically. Reserve explicit saves for facts kbot *would not learn on its own* (user preferences, project constraints, non-obvious decisions).
+
+## What Emerges
+
+After ~30 days, meta-reflections stabilize into a compressed profile of how the user works. That profile loads into every session's prompt as ambient context. The subjective experience: kbot starts "already knowing you" by session 20-ish.