@mingxy/cerebro-claude-code 0.3.3 → 0.3.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cerebro",
   "description": "Persistent memory for Claude Code — memories survive across sessions, projects, and machines",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "author": {
     "name": "mingxy-cerebro",
     "email": "hi@cerebro.dev"

package/hooks/apply-dream.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// apply-dream: merge a dream output archive into MEMORY_DIR under the merge contract:
+//   join key = name (the only anchor; server prompt forces verbatim copy for kept)
+//   kept   → old archive wins verbatim; every LLM-provided field except name is ignored
+//   unknown kept name → surfaced as `unknown`, NEVER silently dropped (that is memory evaporation)
+//   dropped → removal candidate, listed for review; applied only with --apply
+//   merged/updated/added → LLM version wins (content is allowed to change there)
+//   stats.total still counts kept entries — the ledger is the server's, not ours to re-derive
+//
+// Read-only review by default (prints the diff); `--apply` writes after user approval.
+// Usage:
+//   node apply-dream.mjs            # review diff for the unconsumed output
+//   node apply-dream.mjs --apply    # write files + rebuild MEMORY.md index lines
+import { existsSync, readFileSync, writeFileSync, readdirSync, rmSync, mkdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+
+const HOME = process.env.HOME || "/home/dongx";
+const DREAM_DIR = process.env.OMEM_DREAM_DIR || join(HOME, ".cache", "cerebro", "dream");
+const OUT_DIR = join(DREAM_DIR, "output");
+const STATE = join(DREAM_DIR, "state.json");
+const MEMORY_DIR = process.env.OMEM_DREAM_MEMORY_DIR || join(HOME, ".claude", "projects", "-home-dongx", "memory");
+const INDEX = join(MEMORY_DIR, "MEMORY.md");
+const APPLY = process.argv.includes("--apply");
+
+// ─── old archive: parse every memory file into {name, description, type, body, raw} ──
+function parseMemoryFile(path) {
+  const raw = readFileSync(path, "utf8");
+  const m = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!m) return { name: null, raw };
+  const fm = {};
+  for (const line of m[1].split("\n")) {
+    const kv = line.match(/^(\w[\w-]*):\s*(.*)$/);
+    if (kv) fm[kv[1]] = kv[2].replace(/^["']|["']$/g, "");
+  }
+  return { name: fm.name || null, description: fm.description || "", type: (fm.metadata || "").replace(/.*type:\s*/, "").trim() || "", body: m[2], fmText: m[1], raw };
+}
+
+const oldFiles = new Map(); // name → {path, parsed}
+const byBase = new Map();   // basename → same objects, second-chance join by file
+const alias = new Map();    // MEMORY.md link text (often Chinese) → name
+const orphanFiles = [];     // unparseable / no name — never touched, surfaced
+for (const f of readdirSync(MEMORY_DIR)) {
+  if (!f.endsWith(".md") || f === "MEMORY.md") continue;
+  const p = { path: join(MEMORY_DIR, f), parsed: parseMemoryFile(join(MEMORY_DIR, f)) };
+  byBase.set(f, p);
+  if (p.parsed.name) oldFiles.set(p.parsed.name, p); else orphanFiles.push(p.path);
+}
+// the dream LLM sees MEMORY.md too and sometimes echoes the Chinese link text
+// instead of the frontmatter slug — join those via the index line
+{
+  const idxRaw = existsSync(INDEX) ? readFileSync(INDEX, "utf8") : "";
+  for (const m of idxRaw.matchAll(/\[([^\]]+)\]\(([^)]+\.md)\)/g)) {
+    const hit = byBase.get(m[2].replace(/.*\//, ""));
+    if (hit?.parsed.name) alias.set(m[1], hit.parsed.name);
+  }
+}
+
+// ─── pick the archive: unconsumed output from state, else newest output file ──
+let archivePath = null;
+try {
+  const st = JSON.parse(readFileSync(STATE, "utf8"));
+  if (st.output && existsSync(st.output)) archivePath = st.output;
+} catch {}
+if (!archivePath && existsSync(OUT_DIR)) {
+  const files = readdirSync(OUT_DIR).filter((f) => f.endsWith(".json")).sort();
+  if (files.length) archivePath = join(OUT_DIR, files[files.length - 1]);
+}
+if (!archivePath) { console.error("apply-dream: no dream output found"); process.exit(1); }
+const entries = JSON.parse(readFileSync(archivePath, "utf8")).entries || [];
+
+// ─── merge ────────────────────────────────────────────────────────────────────
+const unknown = [];   // kept names missing from the old archive — LLM renamed, memory at risk
+const report = { keep: 0, write: [], drop: [], dropCount: 0 };
+for (let e of entries) {
+  // normalize BEFORE any branch: an LLM-emitted Chinese name that the MEMORY.md
+  // index can resolve must land on the old file, or updated entries fork duplicates
+  if (!oldFiles.has(e.name) && alias.has(e.name)) e = { ...e, name: alias.get(e.name) };
+  const act = e.source || e.action || "";
+  if (e.source === "kept" || act === "kept") {
+    if (!oldFiles.has(e.name)) { unknown.push(e.name); continue; }
+    report.keep++; // old archive wins; nothing to do, not even a rewrite
+  } else if (act === "dropped") {
+    report.drop.push(e.name);
+    report.dropCount++;
+  } else if (act === "added" || act === "merged" || act === "updated") {
+    report.write.push(e); // LLM content is authoritative for these actions
+  } else {
+    unknown.push(`${e.name} (action=${act || "?"})`);
+  }
+}
+
+// ─── review output ────────────────────────────────────────────────────────────
+const lines = [
+  `apply-dream review · archive ${archivePath}`,
+  `kept ${report.keep} / write ${report.write.length} / drop ${report.dropCount} / unknown ${unknown.length}`,
+];
+for (const e of report.write) lines.push(`  ${e.source || e.action}  ${e.name} — ${(e.description || "").slice(0, 60)}`);
+for (const n of report.drop) lines.push(`  drop  ${n}`);
+for (const n of unknown) lines.push(`  ?     ${n}  ← surfaced, not dropped`);
+if (orphanFiles.length) lines.push(`  (unparsed old files left untouched: ${orphanFiles.length})`);
+console.log(lines.join("\n"));
+if (unknown.length) console.log("\n⚠ URGENT: unknown kept names above — surface to the user BEFORE applying; they may be renames the LLM invented.");
+if (!APPLY) { console.log("\ndry run — pass --apply to write"); process.exit(0); }
+
+// ─── write phase (--apply) ─────────────────────────────────────────────────────
+mkdirSync(MEMORY_DIR, { recursive: true });
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "memory";
+for (const e of report.write) {
+  const old = oldFiles.get(e.name);
+  const path = old?.path || join(MEMORY_DIR, `${slug(e.name)}.md`);
+  const type = e.type || old?.parsed.type || "project";
+  const out = [
+    "---",
+    `name: ${e.name}`,
+    ...(e.description ? [`description: ${e.description.replace(/\n/g, " ")}`] : []),
+    "metadata:",
+    `  type: ${type}`,
+    "---",
+    "",
+    (e.body || "").trim(),
+    "",
+  ].join("\n");
+  const tmp = path + ".tmp";
+  writeFileSync(tmp, out); renameSync(tmp, path); // atomic, same convention as state.json
+}
+for (const n of report.drop) {
+  const old = oldFiles.get(n);
+  if (old) rmSync(old.path);
+}
+
+// MEMORY.md index: keep human-written lines by name, append new, drop removed
+const idx = existsSync(INDEX) ? readFileSync(INDEX, "utf8").split("\n") : ["# MEMORY.md — 本地记忆索引", ""];
+const keptNames = new Set([...entries.filter((e) => e.source !== "kept" || e.action !== "dropped" && oldFiles.has(e.name) || true).map((e) => e.name)]);
+const outLines = idx.filter((l) => {
+  const m = l.match(/\]\(([^)]+\.md)\)/);
+  if (!m) return true; // headers, blanks, non-link lines stay
+  const base = m[1].replace(/.*\//, "");
+  const hit = report.write.find((e) => (oldFiles.get(e.name)?.path || "").endsWith(base));
+  if (hit) return keptNames.has(hit.name);
+  const drop = report.drop.find((n) => (oldFiles.get(n)?.path || "").endsWith(base));
+  return !drop;
+});
+for (const e of report.write) {
+  if (outLines.some((l) => l.includes(`(${slug(e.name)}.md)`))) continue;
+  outLines.push(`- [${e.name}](${slug(e.name)}.md) — ${(e.description || "").slice(0, 40)}`);
+}
+writeFileSync(INDEX, outLines.join("\n").replace(/\n{3,}/g, "\n\n") + "\n");
+console.log(`\napplied: ${report.write.length} written, ${report.dropCount} dropped, index rebuilt`);

package/hooks/dream.mjs

@@ -23,6 +23,7 @@ const DREAM_DIR = process.env.OMEM_DREAM_DIR || join(HOME, ".cache", "cerebro",
 const OUT_DIR = join(DREAM_DIR, "output");
 const STATE = join(DREAM_DIR, "state.json");
 const LOCK = join(DREAM_DIR, "trigger.lock");
+const CONF = join(DREAM_DIR, "config.json");
 // ponytail: hardcodes the home-project memory dir as the dream subject; DREAM_MEMORY_DIR
 // escapes hatch for other projects if per-project dreams ever matter
 const MEMORY_DIR = process.env.OMEM_DREAM_MEMORY_DIR || join(HOME, ".claude", "projects", "-home-dongx", "memory");
@@ -39,6 +40,14 @@ const LOCK_TTL_MS = 15 * 60 * 1000;   // > 600s server job budget
 const POLL_INTERVAL_MS = 2000;
 const POLL_BUDGET_MS = 660 * 1000;    // > 600s server timeout (ADR-3)
 
+// ─── runtime config: on/off switch + badge TTL ───────────────────────────────
+// Absent file = defaults (on): fresh install dreams without any setup.
+const DEFAULT_CONF = { enabled: true, badge_ttl_secs: 3600 };
+export function readDreamConfig() {
+  try { return { ...DEFAULT_CONF, ...JSON.parse(readFileSync(CONF, "utf8")) }; }
+  catch { return { ...DEFAULT_CONF }; }
+}
+
 // ─── state helpers (tmp+rename atomic) ───────────────────────────────────────
 export function readState() {
   try { return JSON.parse(readFileSync(STATE, "utf8")); } catch { return null; }
@@ -74,7 +83,7 @@ function collectMemory() {
 }
 
 // ─── food: sessions (mechanical extraction, no LLM in hooks) ─────────────────
-function listTranscripts(sinceMs) {
+function listTranscripts() {
   const out = [];
   for (const proj of readdirSync(PROJECTS_DIR)) {
     const dir = join(PROJECTS_DIR, proj);
@@ -114,17 +123,40 @@ function extractTranscript(path) {
 // ─── rhythm judge ────────────────────────────────────────────────────────────
 export function judgeMaterial(state) {
   const last = state?.last_dream_at ? Date.parse(state.last_dream_at) : 0;
-  const sinceMs = last || 0;
-  const newer = listTranscripts(sinceMs).filter((t) => t.mtime > sinceMs && t.mtime > last);
+  const newer = listTranscripts().filter((t) => t.mtime > last);
   const age = Date.now() - last;
   const enoughTime = age >= MIN_INTERVAL_MS;
   const fallback = last > 0 && age >= FALLBACK_MS;
-  return { ok: newer.length >= MIN_NEW_SESSIONS && (enoughTime || !last) || fallback, since: last ? new Date(last).toISOString() : null, count: newer.length };
+  const remaining_ms = last ? Math.max(0, MIN_INTERVAL_MS - age) : null;
+  return { ok: newer.length >= MIN_NEW_SESSIONS && (enoughTime || !last) || fallback, since: last ? new Date(last).toISOString() : null, count: newer.length, remaining_ms };
+}
+
+// ─── statusline badge: all state→label/color decisions live here, bash renders ─
+// off grey / run orange (zombie run >30min falls through) / fail red until TTL /
+// rdy green (gates met) / accumulating `[n/2]·3h 41m` (needs n sessions + time).
+const RUN_ZOMBIE_MS = 30 * 60 * 1000; // > lock TTL 15min + poll 11min: live run can't outlive it
+function fmtRemain(ms) {
+  if (ms == null || ms <= 0) return "";
+  const m = Math.ceil(ms / 60000); // entry guard ⇒ m ≥ 1
+  return m < 60 ? `${m}m` : `${Math.floor(m / 60)}h ${m % 60}m`;
+}
+export function badgeLine() {
+  const conf = readDreamConfig();
+  if (!conf.enabled) return { text: "cerebro dream off", color: 90 };
+  const st = readState();
+  const age = st?.updated_at ? Date.now() - Date.parse(st.updated_at) : Infinity;
+  if (st?.phase === "run" && age < RUN_ZOMBIE_MS) return { text: "cerebro dream run", color: 208 };
+  if (st?.phase === "fail" && age < conf.badge_ttl_secs * 1000) return { text: "cerebro dream fail", color: 196 };
+  const judge = judgeMaterial(st);
+  if (judge.ok) return { text: "cerebro dream rdy", color: 71 };
+  const rem = fmtRemain(judge.remaining_ms);
+  return { text: `cerebro dream [${Math.min(judge.count, MIN_NEW_SESSIONS)}/${MIN_NEW_SESSIONS}]${rem ? "·" + rem : ""}`, color: 250 };
 }
 
 // ─── detached main: trigger + poll + persist ─────────────────────────────────
 export async function runDream() {
   if (!config.apiKey) return;
+  if (!readDreamConfig().enabled) { logDebug("dream: disabled by config"); return; }
   if (!acquireLock()) { logDebug("dream: lock held, another window is dreaming"); return; }
   try {
     const prev = readState();
@@ -132,7 +164,7 @@ export async function runDream() {
     if (!judge.ok) { logDebug(`dream: not enough material (new=${judge.count})`); return; }
 
     const memory = collectMemory();
-    const trans = listTranscripts(0).filter((t) => !judge.since || t.mtime > Date.parse(judge.since));
+    const trans = listTranscripts().filter((t) => !judge.since || t.mtime > Date.parse(judge.since));
     const sessions = [];
     let bytes = memory.length;
     for (const t of trans) { // newest first; drop oldest by simply stopping
@@ -233,6 +265,7 @@ export async function fetchOrphanResult(st) {
 
 // ─── direct CLI entry (detached worker) ──────────────────────────────────────
 if (process.argv[1] && basename(process.argv[1]) === "dream.mjs") {
+  if (process.argv[2] === "--badge") { console.log(JSON.stringify(badgeLine())); process.exit(0); }
   if (!existsSync(LOCK) && judgeMaterial(readState()).ok) {
     await runDream();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mingxy/cerebro-claude-code",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Persistent memory for Claude Code — memories survive across sessions, projects, and machines",
   "author": {
     "name": "mingxy-cerebro",

package/skills/apply-dream/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: apply-dream
+description: Review and merge auto dream output. Use when the session-start report says Dream report ready, /dream status shows done, or the user asks to "check the dream result / merge memories". Prints a diff by default; runs --apply only after approval.
+---
+
+# apply-dream — dream output review and merge
+
+Script: `$CLAUDE_PLUGIN_ROOT/hooks/apply-dream.mjs` (shipped with the plugin — path never breaks)
+
+## Usage
+
+```bash
+# Step 1: read-only review (touches nothing)
+node "$CLAUDE_PLUGIN_ROOT/hooks/apply-dream.mjs"
+
+# Step 2: after the user reviews the diff and approves
+node "$CLAUDE_PLUGIN_ROOT/hooks/apply-dream.mjs" --apply
+```
+
+## Merge contract (built into the script; here for cross-checking)
+
+- join key = name; MEMORY.md index display names (often Chinese) resolve as a second-chance join
+- kept entries: old archive wins verbatim; every LLM field except name is ignored
+- unknown (unmatched names): surface to the user, never silently dropped
+- dropped: listed for review first; deleted only with --apply
+- updated/added: LLM content wins, written atomically
+
+## Reporting rule
+
+Summarize the dry run in plain words: kept / updated / added / dropped counts, any unmatched names — wait for the user's go-ahead before --apply.

package/skills/dream/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: dream
+description: Control the auto dream switch and status. Use when the user says /dream on, /dream off, /dream status, or "dream switch / dream status / enable / disable dreaming".
+---
+
+# /dream — auto dream master switch
+
+Args: `on` | `off` | `status` (default `status`).
+
+## Config file
+
+`~/.cache/cerebro/dream/config.json`:
+
+```json
+{"enabled": true, "badge_ttl_secs": 3600}
+```
+
+- `enabled`: master switch. When false, every trigger path (session-end hook / session-start fallback / systemd timer) exits immediately — no dreaming.
+- `badge_ttl_secs`: how long (seconds) the red fail badge stays on the statusline before falling back to the accumulating state.
+
+## on / off
+
+Rewrite the whole file with the Write tool (Bash sandbox has a read-only home — no echo/jq redirects). Change only the `enabled` field, keep the rest verbatim. Then verify:
+
+```bash
+node "$CLAUDE_PLUGIN_ROOT/hooks/dream.mjs" --badge
+```
+
+Expected: off prints `{"text":"cerebro dream off","color":90}`; on returns to the normal state.
+
+## status
+
+Report four items in plain words for the user (translate, no raw JSON):
+
+1. **Badge**: run `--badge` above and translate:
+   - `off` grey = disabled
+   - `run` orange = dreaming right now
+   - `fail` red = last dream failed (check `error` in state)
+   - `rdy` green = material ready, waiting for a trigger
+   - `[n/2]·Xh Ym` = accumulating: n new sessions since the last dream, Xh Ym left to the 6h window
+2. **State**: `jq '{phase, last_dream_at, error, consumed}' ~/.cache/cerebro/dream/state.json`
+3. **Timer**: `systemctl --user list-timers cerebro-dream.timer --no-pager | head -3` (sandbox blocks D-Bus with "Failed to connect to bus" — rerun via a host channel like `wsl.exe -- bash -lc`, or ask the user to run it with the `!` prefix)
+4. **Output**: `ls -t ~/.cache/cerebro/dream/output/ | head -3`; to consume a result suggest `/apply-dream` (diff only by default, writes after approval).