@qltk/pi-mnemo 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.2.1 — 2026-09-05
+
+worker 可观测性：stderr 落盘。
+
+### 修复/改进
+- spawnWorker 的 stderr 从 `ignore` 改为 append 到 `~/.pi/agent/mnemo/.worker.log`（同 logMaxBytes 滚动阈值）。workers 是 fire-and-forget，stderr 静默丢弃意味着静默死亡无法诊断（2026-09-05 一次 321 行大抽取无声消失，无产物/无 exit 日志/无进程，排查时发现该盲区）。
+## 0.2.0 — 2026-09-05
+
+配置文件 seam：`~/.pi/agent/mnemo.json`（或 `$PI_MNEMO_CONFIG`），优先级 文件 > env > 默认。
+
+### 背景
+pi-web 跑在 systemd 下不读 shell rc——worker 模型若只靠 env 配不进去，需要改 unit/造 EnvironmentFile。配置文件 seam 从根上消除：一个 json 管所有进程（pi-web / 命令行 pi / worker），改完重启 pi 生效。
+
+### 用法
+```jsonc
+// ~/.pi/agent/mnemo.json
+{
+  "extractModel": "zen/big-pickle",
+  "dreamModel": "zai-coding-cn/glm-5.3-flash",
+  "dreamWindow": "18:30-08:30",   // 或 "" 关闭
+  "modelFallback": ["mimo-v2.5-free"]  // 数组或逗号分隔字符串
+}
+```
+字段名 camelCase 对齐 `MemoryConfig`；数字字段接数字。仅未知字段忽略，文件缺失/损坏 → env+默认。
+
 ## 0.1.1 — 2026-09-05
 
 修复 worker 模型指定 bug。

package/README.md

@@ -62,7 +62,20 @@ ln -s /path/to/pi-mnemo ~/.pi/agent/extensions/pi-mnemo
 | project | project | 代码/git 推导不出的背景、决策、约束 |
 | reference | project | 外部系统链接 |
 
-## 配置（环境变量，全部可选）
+## 配置
+
+推荐用配置文件 `~/.pi/agent/mnemo.json`（或 `$PI_MNEMO_CONFIG` 指定路径），优先级 **文件 > env > 默认**。改完重启 pi 生效（pi-web：`systemctl --user restart pi-web`）。
+
+```jsonc
+{
+  "extractModel": "zen/big-pickle",          // 抽取 worker（免费档即可）
+  "dreamModel": "zai-coding-cn/glm-5.3-flash", // 整理 worker（建议大窗口）
+  "dreamWindow": "18:30-08:30",              // dream 夜间窗口，"" = 全天
+  "disabled": false
+}
+```
+
+也可用环境变量（同名语义，前缀 `PI_MNEMO_`）：
 
 | env | 默认 | 说明 |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qltk/pi-mnemo",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Persistent memory for the pi coding agent — auto recall/extract/dream, file-based (MEMORY.md index + topic files), global + project dual scope. Port of mnemo (opencode).",
   "type": "module",
   "license": "MIT",

package/src/config.ts

@@ -1,12 +1,45 @@
-// config.ts — configuration seam for pi-mnemo (env vars with defaults).
+// config.ts — configuration seam for pi-mnemo.
+// Priority: ~/.pi/agent/mnemo.json (file) > env (PI_MNEMO_*) > defaults.
+// The file is read once at process start — edit it, then restart pi (pi-web: `systemctl --user restart pi-web`).
 
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
 import type { MemoryConfig, DreamWindow } from "./types.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+/**
+ * Overrides from ~/.pi/agent/mnemo.json (or $PI_MNEMO_CONFIG).
+ * Keys mirror MemoryConfig fields in camelCase, e.g.:
+ *   { "extractModel": "zen/big-pickle", "dreamModel": "zai-coding-cn/glm-5.3-flash", "disabled": true }
+ * numeric fields accept numbers; dreamWindow accepts "18:30-08:30" or "" (off) or null.
+ */
+function loadFileOverrides(): Record<string, unknown> {
+  const file =
+    process.env.PI_MNEMO_CONFIG || join(homedir(), ".pi", "agent", "mnemo.json");
+  try {
+    return JSON.parse(readFileSync(file, "utf-8"));
+  } catch {
+    return {}; // missing/malformed → env+defaults apply
+  }
+}
+
+const FILE = loadFileOverrides();
+
+function pick<T>(key: string, envKey: string, envDefault: T, isNum = false): T {
+  if (FILE[key] !== undefined && FILE[key] !== null) {
+    const v = FILE[key] as unknown;
+    return isNum ? (Number(v) as T) : (v as T);
+  }
+  if (process.env[envKey] !== undefined && process.env[envKey] !== "") {
+    const v = process.env[envKey];
+    return isNum ? (Number(v) as T) : (v as T);
+  }
+  return envDefault;
+}
+
 /** Parse "HH:MM" → {h,m}, null if invalid. */
 function parseHM(s: string): { h: number; m: number } | null {
   const mt = /^(\d{1,2}):(\d{2})$/.exec(s.trim());
@@ -16,8 +49,21 @@ function parseHM(s: string): { h: number; m: number } | null {
   return { h, m };
 }
 
-/** Parse dream window (env override, default 18:30-08:30 crossing midnight). null = always allowed. */
+/** Parse dream window. Accepts file form "18:30-08:30" / "" (off) / null, or env pair. */
 function parseDreamWindow(): DreamWindow | null {
+  const fileWin = FILE["dreamWindow"];
+  if (fileWin !== undefined) {
+    if (fileWin === null || fileWin === "") return null;
+    if (typeof fileWin === "string" && fileWin.includes("-")) {
+      const [s, e] = fileWin.split("-", 2);
+      const start = parseHM(s);
+      const end = parseHM(e);
+      if (start && end) {
+        return { start, end, tz: Intl.DateTimeFormat().resolvedOptions().timeZone };
+      }
+    }
+    return null; // malformed → window off
+  }
   const startRaw = process.env.PI_MNEMO_DREAM_WINDOW_START ?? "18:30";
   const endRaw = process.env.PI_MNEMO_DREAM_WINDOW_END ?? "08:30";
   if (startRaw === "" || endRaw === "") return null; // explicitly disabled
@@ -40,51 +86,41 @@ function parseDreamWindow(): DreamWindow | null {
   return { start, end, tz };
 }
 
-/** Parse comma-separated list (drop empties). */
-function parseList(s: string): string[] {
-  return s.split(",").map((x) => x.trim()).filter(Boolean);
-}
-
-/** Read env number (empty/missing/non-numeric → default; explicit 0 honored). */
-function envNum(key: string, def: number): number {
-  const v = process.env[key];
-  if (v === undefined || v === "") return def;
-  const n = Number(v);
-  return Number.isFinite(n) ? n : def;
-}
-
-function envBool(key: string): boolean {
-  const v = process.env[key];
-  return v === "1" || v === "true" || v === "yes";
+/** Parse comma-separated list (drop empties). File form accepts a JSON array directly. */
+function pickList(raw: string | unknown[]): string[] {
+  if (Array.isArray(raw)) return raw.map(String).filter(Boolean);
+  return String(raw ?? "").split(",").map((x) => x.trim()).filter(Boolean);
 }
 
 export const CONFIG: MemoryConfig = {
   memoryRoot:
-    process.env.PI_MNEMO_ROOT ||
+    (pick("memoryRoot", "PI_MNEMO_ROOT", "") as string) ||
     join(homedir(), ".pi", "agent", "mnemo"),
   promptsDir:
-    process.env.PI_MNEMO_PROMPTS_DIR || join(__dirname, "..", "prompts"),
+    (pick("promptsDir", "PI_MNEMO_PROMPTS_DIR", "") as string) ||
+    join(__dirname, "..", "prompts"),
 
   // Headless worker model ("provider/id"; empty = pi's default model at spawn time)
-  extractModel: process.env.PI_MNEMO_EXTRACT_MODEL || "",
-  dreamModel: process.env.PI_MNEMO_DREAM_MODEL || "",
-  modelFallback: parseList(process.env.PI_MNEMO_MODEL_FALLBACK || ""),
-  workerTools: process.env.PI_MNEMO_WORKER_TOOLS || "read,grep,glob,bash",
+  extractModel: pick("extractModel", "PI_MNEMO_EXTRACT_MODEL", "") as string,
+  dreamModel: pick("dreamModel", "PI_MNEMO_DREAM_MODEL", "") as string,
+  modelFallback: pickList(pick("modelFallback", "PI_MNEMO_MODEL_FALLBACK", "") as string),
+  workerTools: pick("workerTools", "PI_MNEMO_WORKER_TOOLS", "read,grep,glob,bash") as string,
 
-  dreamIntervalMs: envNum("PI_MNEMO_DREAM_INTERVAL_MS", 24 * 60 * 60 * 1000),
+  dreamIntervalMs: pick("dreamIntervalMs", "PI_MNEMO_DREAM_INTERVAL_MS", 24 * 60 * 60 * 1000, true) as number,
   dreamWindow: parseDreamWindow(),
 
-  extractMinNewMessages: envNum("PI_MNEMO_EXTRACT_MIN_NEW_MESSAGES", 5),
-  extractMinIntervalMs: envNum("PI_MNEMO_EXTRACT_MIN_INTERVAL_MS", 30 * 60 * 1000),
+  extractMinNewMessages: pick("extractMinNewMessages", "PI_MNEMO_EXTRACT_MIN_NEW_MESSAGES", 5, true) as number,
+  extractMinIntervalMs: pick("extractMinIntervalMs", "PI_MNEMO_EXTRACT_MIN_INTERVAL_MS", 30 * 60 * 1000, true) as number,
 
-  dreamBacklogDays: envNum("PI_MNEMO_DREAM_BACKLOG_DAYS", 2),
-  dreamBacklogPerIdle: envNum("PI_MNEMO_DREAM_BACKLOG_PER_IDLE", 1),
+  dreamBacklogDays: pick("dreamBacklogDays", "PI_MNEMO_DREAM_BACKLOG_DAYS", 2, true) as number,
+  dreamBacklogPerIdle: pick("dreamBacklogPerIdle", "PI_MNEMO_DREAM_BACKLOG_PER_IDLE", 1, true) as number,
 
-  pruneAgeDays: envNum("PI_MNEMO_PRUNE_AGE_DAYS", 30),
-  coldStartDays: envNum("PI_MNEMO_COLD_START_DAYS", 14),
-  topicSoftMaxKB: envNum("PI_MNEMO_TOPIC_SOFT_MAX_KB", 8),
-  logMaxBytes: envNum("PI_MNEMO_LOG_MAX_BYTES", 1024 * 1024),
+  pruneAgeDays: pick("pruneAgeDays", "PI_MNEMO_PRUNE_AGE_DAYS", 30, true) as number,
+  coldStartDays: pick("coldStartDays", "PI_MNEMO_COLD_START_DAYS", 14, true) as number,
+  topicSoftMaxKB: pick("topicSoftMaxKB", "PI_MNEMO_TOPIC_SOFT_MAX_KB", 8, true) as number,
+  logMaxBytes: pick("logMaxBytes", "PI_MNEMO_LOG_MAX_BYTES", 1024 * 1024, true) as number,
 
-  workerTimeoutMs: envNum("PI_MNEMO_WORKER_TIMEOUT_MS", 10 * 60 * 1000),
-  disabled: envBool("PI_MNEMO_DISABLED"),
+  workerTimeoutMs: pick("workerTimeoutMs", "PI_MNEMO_WORKER_TIMEOUT_MS", 10 * 60 * 1000, true) as number,
+  disabled: pick<string>("disabled", "PI_MNEMO_DISABLED", "0") === "1" ||
+    String(FILE["disabled"]) === "true",
 };

package/src/orchestrator.ts

@@ -8,8 +8,8 @@
 // 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 { openSync, statSync, renameSync } from "node:fs";
+import { join, basename } from "node:path";
 import { CONFIG } from "./config.js";
 import { projectDir, readPrompt } from "./io.js";
 import { fillPrompt } from "./prompt.js";
@@ -56,10 +56,23 @@ export function spawnWorker(opts: WorkerOpts): void {
   if (opts.model) args.push("--model", opts.model);  // pi 的 flag 是 --model（无 -m 短写）
   log("spawn worker:", piBin(), args.join(" "));
 
+  // stderr → ~/.pi/agent/mnemo/.worker.log (rotation-capped): workers are fire-and-forget,
+  // silent stderr means silent deaths — this log is the only post-mortem.
+  let errFd: number | "ignore";
+  try {
+    const wl = join(CONFIG.memoryRoot, ".worker.log");
+    try {
+      if (statSync(wl).size > CONFIG.logMaxBytes) renameSync(wl, wl + ".1");
+    } catch { /* not created yet */ }
+    errFd = openSync(wl, "a");
+  } catch {
+    errFd = "ignore";
+  }
+
   const child = spawn(piBin(), args, {
     cwd: opts.cwd,
     detached: true,
-    stdio: ["pipe", "ignore", "ignore"],
+    stdio: ["pipe", "ignore", errFd],
     env: { ...process.env, PI_MNEMO_WORKER: "1" },
   });
   child.unref();