@qltk/pi-mnemo 0.1.0

package/src/orchestrator.ts

@@ -0,0 +1,275 @@
+// orchestrator.ts — headless-worker orchestration for extract/dream + citation loop.
+//
+// pi equivalent of mnemo's ForkOrchestrator:
+//   opencode: session.create(fork) + promptAsync + session.idle + session.delete
+//   pi:      spawn detached `pi -p --no-session` child; process exit = full cleanup
+//
+// The worker reads the parent session JSONL itself (create-mode extract, like mnemo 0.5.2+),
+// so no transcript copying is needed — the prompt just points at the session file.
+
+import { spawn } from "node:child_process";
+import { statSync } from "node:fs";
+import { basename } from "node:path";
+import { CONFIG } from "./config.js";
+import { projectDir, readPrompt } from "./io.js";
+import { fillPrompt } from "./prompt.js";
+import { log } from "./log.js";
+import { bumpUsage } from "./frontmatter.js";
+import { scanSessionFile } from "./pi-session-scan.js";
+import type { DreamStateStore } from "./state-store.js";
+import type { DreamLock } from "./dream-lock.js";
+import type { DreamState } from "./types.js";
+
+const piBin = () => process.env.PI_MNEMO_PI_BIN || "pi";
+
+/** Is `t` inside the dream night window right now? */
+export function inDreamWindow(state: DreamState | null): boolean {
+  const w = CONFIG.dreamWindow;
+  if (!w) return true;
+  const now = new Date(new Date().toLocaleString("en-US", { timeZone: w.tz }));
+  const mins = now.getHours() * 60 + now.getMinutes();
+  const s = w.start.h * 60 + w.start.m;
+  const e = w.end.h * 60 + w.end.m;
+  return s <= e ? mins >= s && mins < e : mins >= s || mins < e; // cross-midnight
+}
+
+export interface WorkerOpts {
+  /** Filled prompt body (stdin). */
+  prompt: string;
+  /** "provider/id" or "" for pi default. */
+  model: string;
+  cwd: string;
+  /** Tools allowlist, comma-separated. */
+  tools?: string;
+}
+
+/** Spawn a detached headless worker; resolves immediately (fire-and-forget). */
+export function spawnWorker(opts: WorkerOpts): void {
+  const args = [
+    "-p",
+    "--no-session",       // ephemeral — nothing to leak
+    "--no-extensions",    // never load pi-mnemo (or anything else) inside the worker
+    "--no-skills",
+    "--no-context-files", // skip AGENTS.md discovery — not needed for memory work
+    "-t", opts.tools || CONFIG.workerTools,
+  ];
+  if (opts.model) args.push("-m", opts.model);
+  log("spawn worker:", piBin(), args.join(" "));
+
+  const child = spawn(piBin(), args, {
+    cwd: opts.cwd,
+    detached: true,
+    stdio: ["pipe", "ignore", "ignore"],
+    env: { ...process.env, PI_MNEMO_WORKER: "1" },
+  });
+  child.unref();
+
+  child.stdin?.on("error", () => { /* EPIPE — worker may have exited early */ });
+  child.stdin?.write(opts.prompt);
+  child.stdin?.end();
+
+  // stuck-timeout guard: kill after workerTimeoutMs
+  const pid = child.pid;
+  const timer = setTimeout(() => {
+    try {
+      if (pid) process.kill(-pid, "SIGKILL"); // kill process group (detached → own pgid)
+      log("worker timeout-killed", pid);
+    } catch { /* already exited */ }
+  }, CONFIG.workerTimeoutMs);
+  timer.unref();
+
+  child.on("error", (e) => log("worker spawn error:", e.message));
+  child.on("exit", (code, signal) => log("worker exited", pid, "code", code, "signal", signal));
+}
+
+export interface OrchestratorOpts {
+  stateStore: DreamStateStore;
+  lock: DreamLock;
+}
+
+export class Orchestrator {
+  private stateStore: DreamStateStore;
+  private lock: DreamLock;
+  /** Track running extract per session (in-process; workers are short-lived). */
+  private extractRunning = new Set<string>();
+
+  constructor(opts: OrchestratorOpts) {
+    this.stateStore = opts.stateStore;
+    this.lock = opts.lock;
+  }
+
+  // ---------- citation loop ----------
+
+  /** Scan session JSONL since last cursor; bump usage for topics read via the read tool. */
+  async bumpCitations(sessionFile: string | null, slug: string): Promise<void> {
+    if (!sessionFile) return;
+    const key = basename(sessionFile, ".jsonl");
+    const state = await this.stateStore.read();
+    const from = state.lastCitationScan?.[key] ?? 0;
+    const res = scanSessionFile(sessionFile, slug);
+    if (res.totalLines > from) {
+      for (const topic of res.readTopics) {
+        try {
+          bumpUsage(topic);
+          log("citation +1", basename(topic));
+        } catch (e: any) { log("bumpUsage failed", topic, e.message); }
+      }
+      state.lastCitationScan = { ...(state.lastCitationScan ?? {}), [key]: res.totalLines };
+      state.lastSeenSession = { ...(state.lastSeenSession ?? {}), [key]: Date.now() };
+      await this.stateStore.write(state);
+    }
+  }
+
+  // ---------- extract ----------
+
+  /** Maybe run an extraction for this session (throttled by new-lines + interval). */
+  async maybeExtract(sessionFile: string | null, slug: string, cwd: string): Promise<boolean> {
+    if (CONFIG.disabled || !sessionFile || process.env.PI_MNEMO_WORKER === "1") return false;
+    const key = basename(sessionFile, ".jsonl");
+    if (this.extractRunning.has(key)) return false;
+
+    const state = await this.stateStore.read();
+    const lastLine = state.lastExtractLine?.[key] ?? 0;
+    const lastTime = state.lastExtractTime?.[key] ?? 0;
+
+    let totalLines: number;
+    try {
+      totalLines = scanSessionFile(sessionFile, slug).totalLines;
+    } catch {
+      return false;
+    }
+    const newLines = totalLines - lastLine;
+    if (newLines < CONFIG.extractMinNewMessages) return false;
+    if (Date.now() - lastTime < CONFIG.extractMinIntervalMs) return false;
+
+    const tpl = readPrompt("extract.md");
+    if (!tpl) return false;
+
+    const prompt = fillPrompt(tpl, slug, String(lastLine))
+      .replace(/\{\{SESSION_FILE\}\}/g, sessionFile)
+      .replace(/\{\{CURSOR_LINE\}\}/g, String(lastLine));
+
+    this.extractRunning.add(key);
+    // record the cursor BEFORE spawning (worker reads lines after it)
+    state.lastExtractLine = { ...(state.lastExtractLine ?? {}), [key]: totalLines };
+    state.lastExtractTime = { ...(state.lastExtractTime ?? {}), [key]: Date.now() };
+    await this.stateStore.write(state);
+
+    spawnWorker({
+      prompt,
+      model: CONFIG.extractModel,
+      cwd,
+      tools: "read,grep,find,edit,write,bash",
+    });
+    log("extract spawned", key, "newLines", newLines, "slug", slug);
+    this.extractRunning.delete(key);
+    return true;
+  }
+
+  // ---------- dream ----------
+
+  /** Maybe run a dream for this slug (24h throttle + night window + lock). */
+  async maybeDream(slug: string, cwd: string): Promise<boolean> {
+    if (CONFIG.disabled || process.env.PI_MNEMO_WORKER === "1") return false;
+    const state = await this.stateStore.read();
+    const last = state.lastDreamPerSlug?.[slug] ?? 0;
+    if (Date.now() - last < CONFIG.dreamIntervalMs) return false;
+    if (!inDreamWindow(state)) return false;
+    if (!(await this.lock.acquire())) return false;
+
+    const tpl = readPrompt("dream.md");
+    if (!tpl) {
+      await this.lock.release();
+      return false;
+    }
+    const prompt = fillPrompt(tpl, slug);
+
+    // record throttle BEFORE spawning (worker is fire-and-forget)
+    state.lastDreamPerSlug = { ...(state.lastDreamPerSlug ?? {}), [slug]: Date.now() };
+    await this.stateStore.write(state);
+
+    spawnWorker({
+      prompt,
+      model: CONFIG.dreamModel || CONFIG.extractModel,
+      cwd,
+      tools: "read,grep,find,edit,write,bash",
+    });
+    log("dream spawned", slug);
+    // lock: released after a grace period — workers are one-shot; a stale lock
+    // would block dreams forever if the process died mid-run.
+    setTimeout(() => { void this.lock.release(); }, 30 * 60 * 1000).unref?.();
+    return true;
+  }
+
+  /** Manual dream (no window/throttle check) for /mnemo dream. */
+  async dreamNow(slug: string, cwd: string): Promise<boolean> {
+    if (process.env.PI_MNEMO_WORKER === "1") return false;
+    if (!(await this.lock.acquire())) {
+      log("dream lock busy — another dream is running");
+      return false;
+    }
+    const tpl = readPrompt("dream.md");
+    if (!tpl) {
+      await this.lock.release();
+      return false;
+    }
+    const prompt = fillPrompt(tpl, slug);
+    spawnWorker({
+      prompt,
+      model: CONFIG.dreamModel || CONFIG.extractModel,
+      cwd,
+      tools: "read,grep,find,edit,write,bash",
+    });
+    const state = await this.stateStore.read();
+    state.lastDreamPerSlug = { ...(state.lastDreamPerSlug ?? {}), [slug]: Date.now() };
+    await this.stateStore.write(state);
+    log("manual dream spawned", slug);
+    setTimeout(() => { void this.lock.release(); }, 30 * 60 * 1000).unref?.();
+    return true;
+  }
+
+  /** Manual extract for /mnemo extract. */
+  async extractNow(sessionFile: string | null, slug: string, cwd: string): Promise<boolean> {
+    if (!sessionFile) return false;
+    const tpl = readPrompt("extract.md");
+    if (!tpl) return false;
+    const state = await this.stateStore.read();
+    const key = basename(sessionFile, ".jsonl");
+    const lastLine = state.lastExtractLine?.[key] ?? 0;
+    const prompt = fillPrompt(tpl, slug, String(lastLine))
+      .replace(/\{\{SESSION_FILE\}\}/g, sessionFile)
+      .replace(/\{\{CURSOR_LINE\}\}/g, String(lastLine));
+    const totalLines = scanSessionFile(sessionFile, slug).totalLines;
+    state.lastExtractLine = { ...(state.lastExtractLine ?? {}), [key]: totalLines };
+    state.lastExtractTime = { ...(state.lastExtractTime ?? {}), [key]: Date.now() };
+    await this.stateStore.write(state);
+    spawnWorker({ prompt, model: CONFIG.extractModel, cwd, tools: "read,grep,find,edit,write,bash" });
+    log("manual extract spawned", key);
+    return true;
+  }
+
+  /** Status snapshot for /mnemo status. */
+  async status(slug: string): Promise<string> {
+    const state = await this.stateStore.read();
+    const lastDream = state.lastDreamPerSlug?.[slug];
+    let projectTopics = 0;
+    try {
+      projectTopics = (await import("node:fs")).readdirSync(projectDir(slug))
+        .filter((f) => f.endsWith(".md") && f !== "MEMORY.md").length;
+    } catch { /* no dir yet */ }
+    const lines = [
+      `memory root: ${CONFIG.memoryRoot}`,
+      `slug: ${slug}`,
+      `project topics: ${projectTopics}`,
+      `last dream: ${lastDream ? new Date(lastDream).toISOString() : "never"}`,
+      `dream interval: ${Math.round(CONFIG.dreamIntervalMs / 3600000)}h`,
+      `extract model: ${CONFIG.extractModel || "(pi default)"}`,
+      `workers: ${CONFIG.disabled ? "disabled" : "enabled"}`,
+    ];
+    try {
+      const st = statSync(CONFIG.memoryRoot);
+      lines.push(`root created: ${st.birthtime.toISOString()}`);
+    } catch { /* ignore */ }
+    return lines.join("\n");
+  }
+}

package/src/pi-session-scan.ts

@@ -0,0 +1,106 @@
+// pi-session-scan.ts — scan a pi session JSONL file (pure-ish: reads file, no writes).
+// Serves two purposes:
+//   1. citation loop — find `read` tool calls targeting memory topic files → caller bumps usage.
+//   2. extract cursor — count lines / detect new activity since last scan.
+//
+// pi session format (docs/session-format.md): one JSON object per line.
+// Tool calls live in assistant messages: { role:"assistant", content:[{ type:"toolCall", name, arguments }] }.
+
+import { readFileSync } from "node:fs";
+import { isAbsolute, relative } from "node:path";
+import { globalDir, projectDir } from "./io.js";
+
+export interface SessionScanResult {
+  totalLines: number;
+  /** Absolute paths of memory topic files read via the read tool (deduped). */
+  readTopics: Set<string>;
+  /** Whether any tool call wrote inside memory dirs since the given line. */
+  wroteMemorySince(fromLine: number): boolean;
+}
+
+interface ToolCallShape {
+  type?: string;
+  name?: string;
+  arguments?: Record<string, unknown>;
+}
+
+/** Extract toolCall entries from one JSONL line (returns [] for non-message lines). */
+function toolCallsOf(entry: unknown): ToolCallShape[] {
+  const msg = entry as { role?: string; content?: unknown } | null;
+  if (!msg || msg.role !== "assistant" || !Array.isArray(msg.content)) return [];
+  return msg.content.filter(
+    (c): c is ToolCallShape =>
+      typeof c === "object" && c !== null && (c as ToolCallShape).type === "toolCall",
+  );
+}
+
+function firstPathArg(args: Record<string, unknown> | undefined): string | undefined {
+  if (!args) return undefined;
+  for (const k of ["path", "filePath", "file_path"]) {
+    const v = args[k];
+    if (typeof v === "string" && v) return v;
+  }
+  return undefined;
+}
+
+/** Is `p` a path inside one of the memory scope dirs (global or given project slug)? */
+export function isInsideMemory(p: string, slug: string): boolean {
+  if (!isAbsolute(p)) return false;
+  for (const dir of [globalDir(), projectDir(slug)]) {
+    const rel = relative(dir, p);
+    if (rel && !rel.startsWith("..") && !isAbsolute(rel)) return true;
+  }
+  return false;
+}
+
+/** Parse one JSONL line defensively; returns null on malformed. */
+function parseLine(line: string): unknown {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Scan a pi session JSONL file up to `endLine` (exclusive, 0-based).
+ */
+export function scanSessionFile(file: string, slug: string, endLine?: number): SessionScanResult {
+  const readTopics = new Set<string>();
+  const writes: number[] = []; // line numbers where a write/edit targeted memory dirs
+  let totalLines = 0;
+
+  let raw: string;
+  try {
+    raw = readFileSync(file, "utf-8");
+  } catch {
+    return { totalLines: 0, readTopics, wroteMemorySince: () => false };
+  }
+
+  const lines = raw.split("\n");
+  // trailing newline produces an empty last element — ignore it
+  const realLines = lines[lines.length - 1] === "" ? lines.length - 1 : lines.length;
+
+  for (let i = 0; i < realLines; i++) {
+    totalLines = i + 1;
+    if (endLine !== undefined && i >= endLine) break;
+    const entry = parseLine(lines[i]);
+    if (!entry) continue;
+    for (const tc of toolCallsOf(entry)) {
+      const p = firstPathArg(tc.arguments);
+      if (!p || !isInsideMemory(p, slug)) continue;
+      const norm = p.endsWith("/MEMORY.md") ? p.replace(/MEMORY\.md$/, "MEMORY.md") : p;
+      if (/^(read|grep|glob)$/i.test(tc.name ?? "")) {
+        if (/\.md$/i.test(norm) && !/MEMORY\.md$/i.test(norm)) readTopics.add(norm);
+      } else if (/^(write|edit)$/i.test(tc.name ?? "")) {
+        writes.push(i);
+      }
+    }
+  }
+
+  return {
+    totalLines,
+    readTopics,
+    wroteMemorySince: (fromLine: number) => writes.some((l) => l >= fromLine),
+  };
+}

package/src/prompt.ts

@@ -0,0 +1,28 @@
+// prompt.ts — fill prompt templates with scope paths.
+// Pure function, no side effects. Typed version.
+
+import { globalDir, projectDir } from "./io.js";
+import { CONFIG } from "./config.js";
+
+export function fillPrompt(
+  tpl: string,
+  slug: string,
+  cursorMessageId?: string,
+  usageTrackingEpoch?: number,
+): string {
+  // dream cold-start 截止日：read-tracking epoch + coldStartDays。
+  // 无 epoch（首次/未初始化）→ 从现在起算（保护首次 dream 不误删老 topic）。
+  const base = usageTrackingEpoch ?? Date.now();
+  const coldStartUntil = new Date(base + CONFIG.coldStartDays * 86_400_000)
+    .toISOString()
+    .slice(0, 10);
+  return tpl
+    .replace(/\{\{GLOBAL_DIR\}\}/g, globalDir())
+    .replace(/\{\{PROJECT_DIR\}\}/g, projectDir(slug))
+    .replace(/\{\{PROJECT_SLUG\}\}/g, slug)
+    .replace(/\{\{LAST_EXTRACTED_MESSAGE_ID\}\}/g, cursorMessageId || "")
+    .replace(/\{\{TODAY\}\}/g, new Date().toISOString().slice(0, 10))
+    .replace(/\{\{USAGE_COLD_START_UNTIL\}\}/g, coldStartUntil)
+    .replace(/\{\{PRUNE_AGE_DAYS\}\}/g, String(CONFIG.pruneAgeDays))
+    .replace(/\{\{TOPIC_SOFT_MAX_KB\}\}/g, String(CONFIG.topicSoftMaxKB));
+}

package/src/recall.ts

@@ -0,0 +1,32 @@
+// recall.ts — build the memory injection block for the system prompt.
+
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG } from "./config.js";
+import { globalDir, projectDir, readIndexWithAge, readPrompt, sanitizeForInjection } from "./io.js";
+import { fillPrompt } from "./prompt.js";
+import { log } from "./log.js";
+
+/** Ensure scope dirs exist for a slug (idempotent). */
+export function ensureDirs(slug: string): void {
+  try {
+    mkdirSync(join(CONFIG.memoryRoot, "projects", slug), { recursive: true });
+  } catch { /* best-effort */ }
+}
+
+/**
+ * Build the full recall block (inject.md + both indexes) for a project slug.
+ * Returns null when inject.md is missing (extension misconfigured → inject nothing).
+ */
+export function buildRecallBlock(slug: string): string | null {
+  ensureDirs(slug);
+  const gIdx = readIndexWithAge(globalDir());
+  const pIdx = readIndexWithAge(projectDir(slug));
+  log("recall — global", gIdx.length, "project", pIdx.length, "for", slug);
+  const tpl = readPrompt("inject.md");
+  if (!tpl) return null;
+  let block = fillPrompt(tpl, slug);
+  if (gIdx.trim()) block += "\n\n### Global index\n```\n" + gIdx.trim() + "\n```\n";
+  if (pIdx.trim()) block += "\n\n### Project index (" + slug + ")\n```\n" + pIdx.trim() + "\n```\n";
+  return sanitizeForInjection(block);
+}

package/src/sanitizer.ts

@@ -0,0 +1,44 @@
+// sanitizer.ts — sanitize/strip/redact functions for injection safety.
+// Pure functions, no side effects. Extracted from io.js for testability.
+
+// 删不可见/控制字符（保留 \t\n\r）+ 零宽 + 方向控制 + BOM + 私用区（Co）。
+const INVISIBLE_RE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F\u00AD\u200B-\u200F\u2028-\u202E\u2060-\u206F\uFEFF\uFFFE\uFFFF\uE000-\uF8FF]/g;
+
+export function sanitizeText(s: string | undefined | null): string {
+  if (!s) return s ?? "";
+  return s.normalize("NFKC").replace(INVISIBLE_RE, "");
+}
+
+const SECRET_PATTERNS = [
+  /\bsk-[A-Za-z0-9_-]{16,}/g,                                              // OpenAI
+  /\bxox[bpoa]-[A-Za-z0-9-]{16,}/g,                                        // Slack
+  /\bgh[pousr]_[A-Za-z0-9]{30,}/g,                                         // GitHub
+  /\bAKIA[0-9A-Z]{16}/g,                                                   // AWS
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,  // PEM 私钥
+  /\b(password|passwd|pwd|secret|token|api[_-]?key)\s*[:=]\s*[^\s\n]+/gi,  // K=V
+];
+
+export function redactSecrets(s: string | undefined | null): string {
+  if (!s) return s ?? "";
+  let out = s;
+  for (const re of SECRET_PATTERNS) out = out.replace(re, "[REDACTED]");
+  return out;
+}
+
+// fail-closed <private>...</private> 剥离（未闭合则剥到文末——向脱敏方向失败）。
+export function stripPrivate(s: string | undefined | null): string {
+  if (!s || !s.includes("<private>")) return s ?? "";
+  const OPEN = "<private>", CLOSE = "</private>";
+  let out = "", i = 0, depth = 0;
+  while (i < s.length) {
+    if (s.startsWith(OPEN, i)) { depth++; i += OPEN.length; continue; }
+    if (s.startsWith(CLOSE, i)) { if (depth > 0) depth--; i += CLOSE.length; continue; }
+    if (depth > 0) { i++; continue; }
+    out += s[i]; i++;
+  }
+  return out;
+}
+
+export function sanitizeForInjection(s: string | undefined | null): string {
+  return stripPrivate(redactSecrets(sanitizeText(s)));
+}

package/src/slug.ts

@@ -0,0 +1,12 @@
+// slug.ts — derive a project slug from git worktree root or directory basename.
+// Pure function, no side effects.
+
+export function projectSlug(worktree: string | undefined | null, directory: string | undefined | null): string {
+  const root = worktree && String(worktree).trim() ? worktree : directory || "";
+  const segs = String(root).split(/[\\\/]/).filter(Boolean);
+  const base = segs.length ? segs[segs.length - 1] : "default";
+  return (
+    base.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") ||
+    "default"
+  );
+}

package/src/state-store.ts

@@ -0,0 +1,39 @@
+// state-store.ts — DreamStateStore interface + default file-based implementation.
+// State persistence for dream throttle and extract cursors.
+// Interface extracted from fork.js for testability / swappability.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import type { DreamState } from "./types.js";
+
+export interface DreamStateStore {
+  read(): DreamState;
+  write(state: DreamState): void;
+}
+
+/**
+ * File-based DreamStateStore (default implementation).
+ * Stores state in .state.json under the memory root.
+ */
+export class FileDreamStateStore implements DreamStateStore {
+  private filePath: string;
+
+  constructor(stateFilePath: string) {
+    this.filePath = stateFilePath;
+  }
+
+  read(): DreamState {
+    try {
+      return JSON.parse(readFileSync(this.filePath, "utf-8"));
+    } catch {
+      return {};
+    }
+  }
+
+  write(state: DreamState): void {
+    try {
+      writeFileSync(this.filePath, JSON.stringify(state));
+    } catch {
+      // best-effort
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,80 @@
+// types.ts — shared types for pi-mnemo (no SDK dependency).
+
+/**
+ * Frontmatter parsed from topic files.
+ */
+export interface TopicFrontmatter {
+  name: string;
+  description?: string;
+  type: "user" | "feedback" | "project" | "reference";
+  deprecated_by?: string;
+  pinned?: boolean;
+  usage_count?: number;
+  last_used?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * Dream/extract state stored in .state.json.
+ */
+export interface DreamState {
+  /** Per-slug dream throttle timestamps. */
+  lastDreamPerSlug?: Record<string, number>;
+  /** Per-session extract cursor: last JSONL line number scanned (0-based, exclusive). */
+  lastExtractLine?: Record<string, number>;
+  lastExtractTime?: Record<string, number>;
+  /** Per-session citation scan cursor: last JSONL line number scanned. */
+  lastCitationScan?: Record<string, number>;
+  /** Epoch when plugin-observed usage tracking started; dream skips usage-based prune before epoch+coldStartDays. */
+  usageTrackingEpoch?: number;
+  /** Last activity timestamp per session, for cursor GC. */
+  lastSeenSession?: Record<string, number>;
+  [key: string]: unknown;
+}
+
+/**
+ * Dream night window (half-open [start, end), may cross midnight).
+ */
+export interface DreamWindow {
+  start: { h: number; m: number };
+  end: { h: number; m: number };
+  tz: string;
+}
+
+/**
+ * Config object (subset used by the extension).
+ */
+export interface MemoryConfig {
+  memoryRoot: string;
+  promptsDir: string;
+  /** Headless worker model ("provider/id"; empty string = pi's current default model). */
+  extractModel: string;
+  dreamModel: string;
+  /** Fallback sequence when the primary model fails ("provider/id"). */
+  modelFallback: string[];
+  /** Extra tools granted to headless workers, comma-separated (default: read,grep,glob,bash). */
+  workerTools: string;
+  /** Dream interval (ms, global per-slug throttle). */
+  dreamIntervalMs: number;
+  /** Dream night window. null = any time. */
+  dreamWindow: DreamWindow | null;
+  /** Extract throttle: min new JSONL lines since last extract. */
+  extractMinNewMessages: number;
+  /** Extract throttle: min interval between extractions (per session). */
+  extractMinIntervalMs: number;
+  /** Backlog: slugs not dreamed for N days get caught up during night window. */
+  dreamBacklogDays: number;
+  dreamBacklogPerIdle: number;
+  /** Dream prune age hard threshold (days, mtime + low usage). */
+  pruneAgeDays: number;
+  /** Usage-tracking cold start (days): no usage-based prune before epoch+this. */
+  coldStartDays: number;
+  /** Topic file soft cap (KB). */
+  topicSoftMaxKB: number;
+  /** .plugin.log size threshold for rotation (bytes). */
+  logMaxBytes: number;
+  /** Headless worker stuck timeout (ms) — killed after. */
+  workerTimeoutMs: number;
+  /** Disable background extract/dream entirely (recall + /mnemo still work). */
+  disabled: boolean;
+}