@wierdbytes/pi-dream 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.1.1
+
+- **Fix:** a note is no longer superseded or deprecated on evidence older than its own — the curator and the fact check see when each note was last observed, and the report flags replacements of notes with newer evidence.
+- **Fix:** on Linux, paths under `/home/<user>` in shell commands now count when a session is matched to its project.
+
+## 0.1.0
+
+- **New:** dreaming — a background pi run distills new sessions into evidence-backed memory notes: per-session cards (Sonnet 5.5), a curator that proposes add / update / supersede / deprecate / confirm operations (Opus 5.5), and an independent fact check of every operation against the original transcript entries (GPT-6.1).
+- **New:** every change goes to a pull request in your private memory repo (`~/.pi/memory` → GitHub); comments on the PR are applied by the next dream, closing it rejects its notes.
+- **New:** approved memory is injected into new sessions as a small `<memory>` index (global + current project, token budgets enforced), frozen per session so the prompt cache keeps hitting.
+- **New:** `memory_search` (notes and past sessions), `memory_read` (notes and transcript entries) and `memory_inbox` (keep something for the next dream) tools.
+- **New:** notes go to the project a session was about — sessions started in a workspace folder (`~/me/dev`, `~`) belong to the project whose files they worked with; `global` is kept for general preferences and machine-wide setup, and a single project's findings never land there without your own words.
+- **New:** notes can be moved between scopes (by the curator, the fact checker or a PR comment).
+- **New:** AGENTS.md / CLAUDE.md change proposals as pull requests in the project's own repository, one open proposal per repository.
+- **New:** `/dream` (status, run, review, dry, init, log, index), `/memory` (status, sync), `/remember`, and the `--no-memory` flag.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leo Henon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,103 @@
-# Temporary Holding Version
+# @wierdbytes/pi-dream
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Offline memory consolidation — "dreaming" — for the [pi](https://pi.dev) coding agent.
+
+While you work, pi sessions pile up in `~/.pi/agent/sessions`. Every so often pi-dream "falls asleep" in a background pi process, reads the new sessions, and distills what future sessions will need into a few small, evidence-backed memory notes. **Every change goes to a pull request in your private memory repository**; only what you merge is loaded into new sessions — as a small index, within a token budget, frozen per session so the prompt cache keeps hitting.
+
+Built after Anthropic's [The components of agent memory](https://www.anthropic.com/research/components-of-agent-memory) and the evidence on what makes agent memory hurt: wrong or stale notes, full-text rewrites, bloated always-on context.
+
+## Install
+
+```bash
+pi install npm:@wierdbytes/pi-dream
+```
+
+Then, in pi:
+
+```text
+/dream init
+```
+
+This creates `~/.pi/memory` (a git repo), a **private** GitHub repository `<you>/pi-memory` as its `origin` (needs the `gh` CLI, logged in), a `pi-dream` label, and `~/.pi/agent/@wierdbytes/pi-dream/settings.json`.
+
+## How a dream works
+
+1. **Digests.** Every session (active branch) becomes a compact digest: user messages, assistant text, one line per tool call, tool-result heads, errors; no images, no thinking; credentials scrubbed. Digests are also the corpus for `memory_search`.
+2. **Cards** (`anthropic/claude-sonnet-5-5`). Each new or grown session gets a card: what happened, how it ended, the user's feedback (verbatim), candidate learnings — each citing digest entry ids.
+3. **Curator** (`anthropic/claude-opus-5-5`, per project). Sees the current notes (global + project), the cards, *history hits* (older sessions that mention a candidate, to judge recurrence), other projects the evidence points to, inbox items, the project's AGENTS.md, and what you rejected before. Proposes operations: `add`, `update` (also moves a note to another scope), `supersede`, `deprecate`, `confirm`, `skill`, `agents_md`.
+
+   **Scope.** A session belongs to the project it was about, not to the folder pi was started in: when pi runs in a workspace folder (`~/me/dev`, `~` — a folder that contains other projects), the session goes to the project whose files it worked with most. Only real projects count (git repositories or folders with markers such as `.pi`, `AGENTS.md`, `package.json`); `~/Downloads` or `/tmp` never become one. `global` is only for your general preferences and machine-wide setup; a topic used in several projects goes to each of them. The fact checker can move a note out of global, and code refuses global notes whose evidence comes from a single project without your own words.
+4. **Fact check** (`openai-codex/gpt-6.1-sol`). Every cited entry is looked up in the raw session; operations citing entries that do not exist are dropped. An independent model checks each operation against those excerpts: supported, partial (with a fix), unsupported, contradicted, unsafe.
+5. **Code applies** what passed — item by item, never a full rewrite; near-duplicates merge into the existing note; superseded notes stay with `valid_until`; credentials and prompt-injection patterns are refused. `MEMORY.md` indexes are regenerated from note front matter within the token budgets.
+6. **Pull request.** Changes are committed on a `pi-dream/…` branch with a report — every change with its rationale, evidence and verdict, plus what the fact check rejected. While a PR is open, later dreams add commits to it.
+7. **AGENTS.md / CLAUDE.md** edits become pull requests in the project's own repository (from a temporary worktree, your working copy is never touched; public repos get no session details). One open proposal per repository: no new one is made while it awaits review.
+
+Reviewing:
+
+- **Merge** — the changes become memory.
+- **Edit notes in the PR** — the next dream continues from your version.
+- **Comment on the PR** — an instruction for the dream (edit, drop, move to another project); `/dream review` applies new comments right away without processing new sessions.
+- **Close without merging** — the notes count as rejected and are not proposed again without new evidence.
+
+## In a session
+
+- A `<memory>` section with the approved global index and the current project's index (built on the first turn, frozen for the session, replayed on resume). Nothing is injected while memory is empty.
+- `memory_search` — notes and past-session digests (BM25, Russian + English).
+- `memory_read` — a note (`m-xxxxxx`) with its evidence, or a past session entry (`s:<session>#<entry>`).
+- `memory_inbox` — keep something for the next dream; it becomes memory only after review.
+- `/remember <text>` — the same, from you.
+- `/memory` — what this session got; `/memory sync` — pull merged memory now.
+- `/dream` — status; `/dream run [--since <days>] [--max <sessions>]`, `/dream review` (apply new PR comments now), `/dream dry` (no push, report and worktree stay local), `/dream index` (rebuild digests), `/dream log`, `/dream init`.
+- `--no-memory` — no injection and no memory tools for this run (`PI_DREAM_DISABLE=1` does the same).
+
+## When it dreams
+
+pi is the scheduler: when a session starts and a dream is due — at least `schedule.minHoursBetween` hours (20) since the last one and `schedule.minNewSessions` (3) new sessions or inbox items — a detached headless pi process runs it:
+
+```text
+pi -p --no-session --no-extensions -e <childExtensions…> -e runner.ts "/pi-dream-run …"
+```
+
+It survives the interactive pi exiting, holds a lock (one dream at a time across all pi processes; stale locks are taken over), and loads only the extensions listed in `dream.childExtensions` (default: `@wierdbytes/pi-anthropic`, so Claude Pro/Max OAuth behaves as in your sessions). Sessions written to in the last `dream.minIdleMinutes` (30) are left for the next dream.
+
+## Memory repository
+
+```text
+~/.pi/memory/
+  scopes/global/{charter.md, MEMORY.md, notes/, skills/}
+  scopes/projects/<key>/{charter.md?, MEMORY.md, notes/, skills/, scope.json}
+  scopes/projects/_charter.md      default purpose of project memory
+  reports/<run>.md
+  prompts/{cards,curator,review,verify}.md   optional prompt overrides
+  .local/                          gitignored: inbox, digests, cards, runs, logs, state
+```
+
+Projects are keyed by their `origin` remote (`github.com/owner/repo`) or by path; worktrees map to their main repository. `charter.md` says what a scope's memory is *for* — it steers the dream and is never injected.
+
+## Settings
+
+`~/.pi/agent/@wierdbytes/pi-dream/settings.json`:
+
+| Key | Default | |
+|---|---|---|
+| `memoryDir` | `~/.pi/memory` | memory repository (`PI_DREAM_DIR` overrides) |
+| `language` | `Russian` | language of notes and reports |
+| `inject` | `true` | inject the approved index into sessions |
+| `models.cards` / `analyze` / `verify` | Sonnet 5.5 low / Opus 5.5 high / GPT-6.1 sol medium | `{ "model": "provider/id", "thinking": "…" }` |
+| `schedule` | `{ enabled: true, minHoursBetween: 20, minNewSessions: 3 }` | when a dream is due |
+| `dream.firstRunLookbackDays` | `14` | how far back the first dream looks |
+| `dream.maxSessionsPerRun` | `60` | the rest waits for the next dream |
+| `dream.minIdleMinutes` | `30` | sessions written more recently are skipped |
+| `dream.concurrency` | `4` | parallel card calls |
+| `dream.maxRuntimeMinutes` | `180` | hard limit of one dream |
+| `dream.childExtensions` | `["npm:@wierdbytes/pi-anthropic"]` | extensions the dream process loads |
+| `budgets.globalTokens` / `projectTokens` | `1000` / `1500` | index budgets |
+| `github` | `{ repo: "pi-memory", base: "main", label: "pi-dream" }` | |
+| `agentsMd` | `true` | propose AGENTS.md / CLAUDE.md changes |
+
+## Development
+
+```bash
+cd packages/dream && bun run test
+pi -e ./index.ts            # try in a session
+```

package/agentsmd.ts

@@ -0,0 +1,171 @@
+/**
+ * AGENTS.md / CLAUDE.md proposals.
+ *
+ * Edits are exact text replacements. They are applied in a temporary git
+ * worktree checked out from the project's default branch on `origin` — the
+ * user's working copy is never touched — committed on a `pi-dream/…` branch,
+ * pushed, and opened as a pull request in the project's own repository.
+ * Without a GitHub remote the edits are returned as a patch for the report.
+ * Public repositories get a minimal PR body: no rationale from private sessions.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gh, ghOk, git, githubRepoOf, gitOk } from "./gitops.ts";
+
+export interface AgentsEdit {
+	old: string;
+	new: string;
+}
+
+export const CONTEXT_FILES = ["AGENTS.md", "CLAUDE.md", "AGENTS.MD", "CLAUDE.MD"];
+
+export function findContextFile(dir: string | undefined): { path: string; rel: string } | undefined {
+	if (!dir) return undefined;
+	for (const rel of CONTEXT_FILES) {
+		const path = join(dir, rel);
+		if (existsSync(path)) return { path, rel };
+	}
+	return undefined;
+}
+
+export function applyEdits(content: string, edits: AgentsEdit[]): { content: string; skipped: number } | { error: string } {
+	let out = content;
+	let skipped = 0;
+	for (const [i, e] of edits.entries()) {
+		if (e.old === "") {
+			if (e.new.trim() && out.includes(e.new.trim())) {
+				skipped++;
+				continue;
+			}
+			out = `${out.replace(/\s*$/, "")}\n\n${e.new.trim()}\n`;
+			continue;
+		}
+		const first = out.indexOf(e.old);
+		if (first < 0) {
+			// Already applied (e.g. proposed again while the first pull request is open).
+			if (e.new && out.includes(e.new)) {
+				skipped++;
+				continue;
+			}
+			return { error: `edit ${i + 1}: text not found` };
+		}
+		if (out.indexOf(e.old, first + 1) >= 0) return { error: `edit ${i + 1}: text is not unique` };
+		out = out.slice(0, first) + e.new + out.slice(first + e.old.length);
+	}
+	return { content: out, skipped };
+}
+
+export function renderEditsDiff(rel: string, edits: AgentsEdit[]): string {
+	const blocks = edits.map((e) => {
+		const minus = e.old ? e.old.split("\n").map((l) => `- ${l}`) : ["- (append at the end)"];
+		const plus = e.new.split("\n").map((l) => `+ ${l}`);
+		return [...minus, ...plus].join("\n");
+	});
+	return `\`${rel}\`\n\n\`\`\`diff\n${blocks.join("\n\n")}\n\`\`\``;
+}
+
+/** URL of an open pi-dream AGENTS.md pull request in the repository at `repoRoot`, if any. */
+export async function openAgentsPr(repoRoot: string): Promise<string | undefined> {
+	const remote = await git(repoRoot, ["remote", "get-url", "origin"]);
+	const repo = remote.code === 0 ? githubRepoOf(remote.stdout.trim()) : undefined;
+	if (!repo) return undefined;
+	const r = await gh(["pr", "list", "--repo", repo, "--state", "open", "--json", "url,headRefName"]);
+	if (r.code !== 0) return undefined;
+	try {
+		return (JSON.parse(r.stdout || "[]") as Array<{ url: string; headRefName: string }>).find((p) => p.headRefName.startsWith("pi-dream/agents-"))?.url;
+	} catch {
+		return undefined;
+	}
+}
+
+export interface AgentsPublishInput {
+	/** Main repository root of the project. */
+	repoRoot: string;
+	rel: string;
+	edits: AgentsEdit[];
+	runId: string;
+	worktreesDir: string;
+	title: string;
+	/** Rationale lines, shown only for private repositories. */
+	details: string[];
+	log: (msg: string) => void;
+}
+
+export interface AgentsPublishResult {
+	url?: string;
+	error?: string;
+	patch: string;
+}
+
+async function defaultBranch(root: string, repo: string): Promise<string> {
+	const head = await git(root, ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]);
+	if (head.code === 0 && head.stdout.trim().startsWith("origin/")) return head.stdout.trim().slice("origin/".length);
+	const r = await gh(["repo", "view", repo, "--json", "defaultBranchRef", "--jq", ".defaultBranchRef.name"]);
+	return r.code === 0 && r.stdout.trim() ? r.stdout.trim() : "main";
+}
+
+export async function publishAgentsEdits(input: AgentsPublishInput): Promise<AgentsPublishResult> {
+	const patch = renderEditsDiff(input.rel, input.edits);
+	const remote = await git(input.repoRoot, ["remote", "get-url", "origin"]);
+	const repo = remote.code === 0 ? githubRepoOf(remote.stdout.trim()) : undefined;
+	if (!repo) return { patch, error: "no GitHub remote: patch only" };
+	const wt = join(input.worktreesDir, `agents-${input.runId}-${repo.replace("/", "__")}`);
+	let branch = `pi-dream/agents-${input.runId}`;
+	try {
+		await gitOk(input.repoRoot, ["fetch", "origin", "--quiet"], 120_000);
+		const base = await defaultBranch(input.repoRoot, repo);
+		// One open pi-dream pull request per repository: later proposals are added to it.
+		const open = await gh(["pr", "list", "--repo", repo, "--state", "open", "--json", "number,url,headRefName"]);
+		const existing = open.code === 0
+			? (JSON.parse(open.stdout || "[]") as Array<{ number: number; url: string; headRefName: string }>).find((p) => p.headRefName.startsWith("pi-dream/agents-"))
+			: undefined;
+		if (existing) {
+			branch = existing.headRefName;
+			await gitOk(input.repoRoot, ["fetch", "origin", branch, "--quiet"], 120_000);
+		}
+		mkdirSync(input.worktreesDir, { recursive: true });
+		await gitOk(input.repoRoot, ["worktree", "add", "--detach", wt, existing ? `origin/${branch}` : `origin/${base}`], 120_000);
+		const file = join(wt, input.rel);
+		if (!existsSync(file)) return { patch, error: `${input.rel} does not exist on origin/${base}` };
+		const before = readFileSync(file, "utf-8");
+		const res = applyEdits(before, input.edits);
+		if ("error" in res) return { patch, error: `${res.error} on ${existing ? branch : `origin/${base}`}` };
+		if (res.content === before) {
+			input.log(`  agents_md: already proposed in ${existing?.url ?? repo}`);
+			return { url: existing?.url, patch, error: existing ? undefined : "nothing to change" };
+		}
+		writeFileSync(file, res.content, "utf-8");
+		if (!existing) await gitOk(wt, ["checkout", "-b", branch]);
+		await gitOk(wt, ["add", input.rel]);
+		await gitOk(wt, ["commit", "--no-verify", "-m", `${input.rel}: ${input.title}\n\nProposed by pi-dream.`]);
+		await gitOk(wt, ["push", "origin", `HEAD:refs/heads/${branch}`], 120_000);
+		if (existing) {
+			input.log(`  agents_md: added to ${existing.url}`);
+			return { url: existing.url, patch };
+		}
+		const vis = await gh(["repo", "view", repo, "--json", "visibility", "--jq", ".visibility"]);
+		const isPublic = vis.code !== 0 || vis.stdout.trim().toUpperCase() !== "PRIVATE";
+		const body = [
+			`Proposed by [pi-dream](https://github.com/wierdbytes/pi-wierd-stuff/tree/master/packages/dream) from the owner's pi session history.`,
+			"",
+			...(isPublic ? ["Details are in the owner's private memory review."] : input.details.map((d) => `- ${d}`)),
+			"",
+			"<!-- pi-dream:agents -->",
+		].join("\n");
+		const url = await ghOk(["pr", "create", "--repo", repo, "--base", base, "--head", branch, "--title", `${input.rel}: ${input.title}`, "--body", body], {
+			timeoutMs: 120_000,
+		});
+		input.log(`  agents_md PR: ${url}`);
+		return { url: url.split("\n").pop()?.trim(), patch };
+	} catch (err) {
+		return { patch, error: err instanceof Error ? err.message : String(err) };
+	} finally {
+		if (existsSync(wt)) {
+			await git(input.repoRoot, ["worktree", "remove", "--force", wt]);
+			rmSync(wt, { recursive: true, force: true });
+		}
+		await git(input.repoRoot, ["worktree", "prune"]);
+		if (branch.startsWith("pi-dream/agents-")) await git(input.repoRoot, ["branch", "-D", branch]);
+	}
+}

package/commands.ts

@@ -0,0 +1,92 @@
+/**
+ * /dream · /memory · /remember
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { initMemory } from "./setup.ts";
+import type { Runtime } from "./runtime.ts";
+
+const DREAM_SUB = [
+	{ value: "status", label: "status", description: "Memory, last dream, open review PR" },
+	{ value: "run", label: "run", description: "Dream now in the background (--since <days> --max <sessions>)" },
+	{ value: "review", label: "review", description: "Apply new comments on the review PR now (no new sessions)" },
+	{ value: "dry", label: "dry", description: "Dream without pushing: report + worktree stay local" },
+	{ value: "index", label: "index", description: "Rebuild session digests (search corpus) in the background" },
+	{ value: "log", label: "log", description: "Tail of the latest dream log" },
+	{ value: "init", label: "init", description: "Create the memory repo, its private GitHub remote and settings" },
+];
+
+const MEMORY_SUB = [
+	{ value: "status", label: "status", description: "What this session got from memory" },
+	{ value: "sync", label: "sync", description: "Pull approved memory from GitHub now" },
+];
+
+function completions(list: typeof DREAM_SUB) {
+	return (prefix: string) => {
+		const p = prefix.trim().toLowerCase();
+		const items = list.filter((c) => c.value.startsWith(p));
+		return items.length ? items : null;
+	};
+}
+
+export function registerCommands(pi: ExtensionAPI, rt: Runtime): void {
+	pi.registerCommand("dream", {
+		description: "pi-dream: status, run, review, dry, index, log, init",
+		getArgumentCompletions: completions(DREAM_SUB),
+		handler: async (args, ctx) => {
+			const [cmd = "status", ...rest] = (args ?? "").trim().split(/\s+/).filter(Boolean);
+			switch (cmd) {
+				case "status":
+					return ctx.ui.notify(rt.status(ctx), "info");
+				case "log":
+					return ctx.ui.notify(rt.latestLog(), "info");
+				case "init": {
+					const lines: string[] = [];
+					try {
+						const res = await initMemory(rt.cfg, (m) => lines.push(m));
+						lines.push(res.repo ? `ready: https://github.com/${res.repo}` : "ready (no GitHub remote)");
+						ctx.ui.notify(`pi-dream init\n${lines.join("\n")}`, "info");
+					} catch (err) {
+						ctx.ui.notify(`pi-dream init failed: ${err instanceof Error ? err.message : String(err)}\n${lines.join("\n")}`, "error");
+					}
+					return;
+				}
+				case "run":
+				case "review":
+				case "dry":
+				case "index": {
+					if (rt.dreaming()) return ctx.ui.notify("pi-dream: a dream is already running (/dream log)", "warning");
+					const extra = cmd === "dry" ? ["--dry-run", ...rest] : cmd === "index" ? ["--reindex"] : cmd === "review" ? ["--review-only"] : rest;
+					const { runId, log } = rt.startDream(extra);
+					return ctx.ui.notify(`pi-dream: ${cmd} started (${runId})\nlog: ${log}`, "info");
+				}
+				default:
+					return ctx.ui.notify("Usage: /dream [status|run|review|dry|index|log|init]", "info");
+			}
+		},
+	});
+
+	pi.registerCommand("memory", {
+		description: "pi-dream memory: status, sync",
+		getArgumentCompletions: completions(MEMORY_SUB),
+		handler: async (args, ctx) => {
+			const cmd = (args ?? "").trim().toLowerCase() || "status";
+			if (cmd === "sync") {
+				const res = await rt.sync(true);
+				return ctx.ui.notify(`pi-dream sync: ${res}${res === "updated" ? " — new sessions get the merged memory" : ""}`, "info");
+			}
+			const section = await rt.memorySection(ctx);
+			return ctx.ui.notify(`${rt.status(ctx)}${section ? `\n\n<memory>\n${section}\n</memory>` : ""}`, "info");
+		},
+	});
+
+	pi.registerCommand("remember", {
+		description: "Save a note to the pi-dream inbox for the next dream to review",
+		handler: async (args, ctx) => {
+			const text = (args ?? "").trim();
+			if (!text) return ctx.ui.notify("Usage: /remember <what future sessions should know>", "info");
+			const id = await rt.inbox(ctx, text, "user");
+			ctx.ui.notify(`pi-dream: saved to the inbox (${id}) — the next dream will propose it for review`, "info");
+		},
+	});
+}

package/config.ts

@@ -0,0 +1,194 @@
+/**
+ * Settings for @wierdbytes/pi-dream.
+ *
+ * Stored at `~/.pi/agent/@wierdbytes/pi-dream/settings.json` (under
+ * `PI_CODING_AGENT_DIR` when pi is pointed elsewhere). Missing, unknown or
+ * malformed fields fall back to defaults, so a hand-edited file can never
+ * break the extension. `PI_DREAM_DIR` overrides `memoryDir`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+/** Mirrors pi-ai's thinking levels; kept local so this module has no pi-ai runtime import. */
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+export type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+export type Stage = "cards" | "analyze" | "verify";
+export const STAGES: readonly Stage[] = ["cards", "analyze", "verify"];
+
+export interface StageModel {
+	/** `<provider>/<model-id>` */
+	model: string;
+	thinking: ThinkingLevel;
+}
+
+export interface DreamConfig {
+	/** Root of the memory git repository. */
+	memoryDir: string;
+	/** Language the dream writes notes and reports in. */
+	language: string;
+	/** Inject the approved memory index into sessions. */
+	inject: boolean;
+	models: Record<Stage, StageModel>;
+	schedule: {
+		/** Start a background dream from pi when one is due. */
+		enabled: boolean;
+		minHoursBetween: number;
+		/** New or grown sessions (or inbox items) needed before a dream is due. */
+		minNewSessions: number;
+	};
+	dream: {
+		/** How far back the very first dream looks. */
+		firstRunLookbackDays: number;
+		/** Sessions summarized per dream; the rest wait for the next one. */
+		maxSessionsPerRun: number;
+		/** Sessions written to more recently than this are treated as still in use. */
+		minIdleMinutes: number;
+		/** Parallel session-card calls. */
+		concurrency: number;
+		maxRuntimeMinutes: number;
+		/**
+		 * Extensions loaded into the headless dream process (it runs with
+		 * `--no-extensions`). Use it for provider/auth extensions. `npm:<name>`
+		 * resolves to pi's installed copy; missing entries are skipped.
+		 */
+		childExtensions: string[];
+	};
+	budgets: {
+		/** Token budget of the global index injected into every session. */
+		globalTokens: number;
+		/** Token budget of a project's index injected into its sessions. */
+		projectTokens: number;
+	};
+	github: {
+		/** Repository name `/dream init` creates for the memory remote. */
+		repo: string;
+		base: string;
+		label: string;
+	};
+	/** Propose AGENTS.md / CLAUDE.md changes as pull requests in project repositories. */
+	agentsMd: boolean;
+}
+
+export function defaults(): DreamConfig {
+	return {
+		memoryDir: join(homedir(), ".pi", "memory"),
+		language: "Russian",
+		inject: true,
+		models: {
+			cards: { model: "anthropic/claude-sonnet-5-5", thinking: "low" },
+			analyze: { model: "anthropic/claude-opus-5-5", thinking: "high" },
+			verify: { model: "openai-codex/gpt-6.1-sol", thinking: "medium" },
+		},
+		schedule: { enabled: true, minHoursBetween: 20, minNewSessions: 3 },
+		dream: {
+			firstRunLookbackDays: 14,
+			maxSessionsPerRun: 60,
+			minIdleMinutes: 30,
+			concurrency: 4,
+			maxRuntimeMinutes: 180,
+			childExtensions: ["npm:@wierdbytes/pi-anthropic"],
+		},
+		budgets: { globalTokens: 1000, projectTokens: 1500 },
+		github: { repo: "pi-memory", base: "main", label: "pi-dream" },
+		agentsMd: true,
+	};
+}
+
+const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+const oneOf = <T extends string>(list: readonly T[], v: unknown): v is T =>
+	typeof v === "string" && (list as readonly string[]).includes(v);
+const num = (v: unknown, min: number, max: number, fallback: number): number =>
+	typeof v === "number" && Number.isFinite(v) ? Math.min(max, Math.max(min, v)) : fallback;
+const bool = (v: unknown, fallback: boolean): boolean => (typeof v === "boolean" ? v : fallback);
+const str = (v: unknown, fallback: string): string => (typeof v === "string" && v.trim() ? v.trim() : fallback);
+
+export function expandHome(p: string): string {
+	if (p === "~") return homedir();
+	if (p.startsWith("~/")) return join(homedir(), p.slice(2));
+	return resolve(p);
+}
+
+function stageModel(raw: unknown, fallback: StageModel): StageModel {
+	if (!isObj(raw)) return { ...fallback };
+	const model = typeof raw.model === "string" && raw.model.includes("/") ? raw.model.trim() : fallback.model;
+	const thinking = oneOf(THINKING_LEVELS, raw.thinking) ? raw.thinking : fallback.thinking;
+	return { model, thinking };
+}
+
+export function sanitize(raw: unknown): DreamConfig {
+	const d = defaults();
+	if (!isObj(raw)) return d;
+	const cfg = d;
+	cfg.memoryDir = expandHome(str(raw.memoryDir, d.memoryDir));
+	cfg.language = str(raw.language, d.language);
+	cfg.inject = bool(raw.inject, d.inject);
+	if (isObj(raw.models)) {
+		for (const stage of STAGES) cfg.models[stage] = stageModel(raw.models[stage], d.models[stage]);
+	}
+	if (isObj(raw.schedule)) {
+		const s = raw.schedule;
+		cfg.schedule = {
+			enabled: bool(s.enabled, d.schedule.enabled),
+			minHoursBetween: num(s.minHoursBetween, 0, 24 * 30, d.schedule.minHoursBetween),
+			minNewSessions: Math.round(num(s.minNewSessions, 1, 1000, d.schedule.minNewSessions)),
+		};
+	}
+	if (isObj(raw.dream)) {
+		const s = raw.dream;
+		cfg.dream = {
+			firstRunLookbackDays: num(s.firstRunLookbackDays, 0, 3650, d.dream.firstRunLookbackDays),
+			maxSessionsPerRun: Math.round(num(s.maxSessionsPerRun, 1, 1000, d.dream.maxSessionsPerRun)),
+			minIdleMinutes: num(s.minIdleMinutes, 0, 24 * 60, d.dream.minIdleMinutes),
+			concurrency: Math.round(num(s.concurrency, 1, 16, d.dream.concurrency)),
+			maxRuntimeMinutes: num(s.maxRuntimeMinutes, 5, 24 * 60, d.dream.maxRuntimeMinutes),
+			childExtensions: Array.isArray(s.childExtensions)
+				? s.childExtensions.filter((x): x is string => typeof x === "string" && !!x.trim())
+				: d.dream.childExtensions,
+		};
+	}
+	if (isObj(raw.budgets)) {
+		cfg.budgets = {
+			globalTokens: Math.round(num(raw.budgets.globalTokens, 0, 20000, d.budgets.globalTokens)),
+			projectTokens: Math.round(num(raw.budgets.projectTokens, 0, 20000, d.budgets.projectTokens)),
+		};
+	}
+	if (isObj(raw.github)) {
+		cfg.github = {
+			repo: str(raw.github.repo, d.github.repo),
+			base: str(raw.github.base, d.github.base),
+			label: str(raw.github.label, d.github.label),
+		};
+	}
+	cfg.agentsMd = bool(raw.agentsMd, d.agentsMd);
+	return cfg;
+}
+
+export function configPath(): string {
+	return join(getAgentDir(), "@wierdbytes", "pi-dream", "settings.json");
+}
+
+export function loadConfig(path: string = configPath()): DreamConfig {
+	let cfg: DreamConfig;
+	try {
+		cfg = existsSync(path) ? sanitize(JSON.parse(readFileSync(path, "utf-8"))) : defaults();
+	} catch {
+		cfg = defaults();
+	}
+	if (process.env.PI_DREAM_DIR) cfg.memoryDir = expandHome(process.env.PI_DREAM_DIR);
+	return cfg;
+}
+
+export function saveConfig(cfg: DreamConfig, path: string = configPath()): void {
+	mkdirSync(dirname(path), { recursive: true });
+	const out = { ...cfg, memoryDir: cfg.memoryDir.replace(homedir(), "~") };
+	writeFileSync(path, `${JSON.stringify(out, null, 2)}\n`, "utf-8");
+}
+
+/** `true` when the user disabled pi-dream for this process. */
+export function disabledByEnv(): boolean {
+	return process.env.PI_DREAM_DISABLE === "1" || process.env.PI_DREAM_CHILD === "1";
+}