@tritard/waterbrother 0.6.6 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tritard/waterbrother",
-  "version": "0.6.6",
+  "version": "0.7.0",
   "description": "Waterbrother: Grok-powered coding CLI with local tools, sessions, operator modes, and approval controls",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -101,6 +101,7 @@ function buildSystemPrompt(profile, experienceMode = "standard", autonomyMode =
     if (executionContext.chosenOption) ctxLines.push(`Chosen approach: ${executionContext.chosenOption}`);
     if (executionContext.contractSummary) ctxLines.push(`Contract: ${executionContext.contractSummary}`);
     if (executionContext.phase) ctxLines.push(`Phase: ${executionContext.phase}. Execute the chosen approach — do not re-decide.`);
+    if (executionContext.reminders) ctxLines.push(`Scope reminders:\n${executionContext.reminders}`);
     if (ctxLines.length > 0) base += `\n\nExecution context:\n${ctxLines.join("\n")}`;
   }
   if (!memoryBlock) return base;

package/src/cli.js

@@ -19,6 +19,7 @@ import { runDecisionPass, runInventPass, formatDecisionForDisplay, formatDecisio
 import { runBuildWorkflow, startFeatureTask, runChallengeWorkflow } from "./workflow.js";
 import { createPanelRenderer, buildPanelState } from "./panel.js";
 import { deriveTaskNameFromPrompt, nextActionsForState, routeNaturalInput } from "./router.js";
+import { compressEpisode, saveEpisode, loadRecentEpisodes, findRelevantEpisodes, buildEpisodicMemoryBlock, buildReminderBlock } from "./episodic.js";
 
 const execFileAsync = promisify(execFile);
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -4033,6 +4034,21 @@ async function promptLoop(agent, session, context) {
   if (!context.runtime.projectMemory) {
     context.runtime.projectMemory = await readProjectMemory(context.cwd);
   }
+
+  // Load episodic memory and combine with project memory
+  try {
+    const recentEpisodes = await loadRecentEpisodes({ cwd: context.cwd, limit: 5 });
+    if (recentEpisodes.length > 0) {
+      const episodicBlock = buildEpisodicMemoryBlock(recentEpisodes);
+      context.runtime.episodicMemory = episodicBlock;
+      const fullMemory = [
+        context.runtime.projectMemory?.promptText || "",
+        episodicBlock
+      ].filter(Boolean).join("\n\n");
+      agent.setMemory(fullMemory);
+    }
+  } catch {}
+
   if (!Array.isArray(context.runtime.lastSearchResults)) {
     context.runtime.lastSearchResults = [];
   }
@@ -5002,6 +5018,13 @@ async function promptLoop(agent, session, context) {
         continue;
       }
       try {
+        // Save episodic memory before closing
+        try {
+          const receipt = context.runtime.lastReceipt || null;
+          const episode = compressEpisode({ task, receipt });
+          await saveEpisode({ cwd: context.cwd, episode });
+        } catch {}
+
         await closeTask({ cwd: context.cwd, taskId: task.id });
         clearTaskFromSession(currentSession);
         agent.toolRuntime.setTaskContext(null);
@@ -5117,6 +5140,29 @@ async function promptLoop(agent, session, context) {
 
       await maybeAutoCompactConversation({ agent, currentSession, context, pendingInput: buildPrompt });
 
+      // Inject adaptive reminders from episodic memory
+      try {
+        const contractPaths = task.activeContract?.paths || [];
+        const taskTags = [task.name, task.goal].filter(Boolean).join(" ").toLowerCase().split(/\s+/).filter((w) => w.length >= 3);
+        const relevant = await findRelevantEpisodes({ cwd: context.cwd, filePatterns: contractPaths, tags: taskTags, limit: 3 });
+        if (relevant.length > 0) {
+          const reminders = buildReminderBlock({
+            episodes: relevant,
+            memoryText: context.runtime.projectMemory?.raw || "",
+            contractPaths
+          });
+          if (reminders) {
+            agent.setExecutionContext({
+              taskName: task.name,
+              chosenOption: task.chosenOption || null,
+              contractSummary: task.activeContract?.summary || null,
+              phase: "build",
+              reminders
+            });
+          }
+        }
+      } catch {}
+
       const turnSummary = { startedAt: Date.now(), tools: [], events: [{ at: Date.now(), name: "thinking" }] };
       const spinner = createProgressSpinner("building...");
       let lastProgressAt = Date.now();

package/src/episodic.js

@@ -0,0 +1,279 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+
+const STOP_WORDS = new Set(["the", "a", "an", "in", "to", "for", "of", "on", "at", "by", "and", "or", "is", "it", "this", "that", "with", "from", "as", "be", "was", "are"]);
+const MAX_INDEX_ENTRIES = 200;
+const MAX_EPISODIC_PROMPT_CHARS = 2000;
+const MAX_REMINDER_CHARS = 1500;
+const MAX_FILES_PER_EPISODE = 50;
+
+function memoryDir(cwd) {
+  return path.join(cwd, ".waterbrother", "memory");
+}
+
+function indexPath(cwd) {
+  return path.join(memoryDir(cwd), "index.json");
+}
+
+function episodePath(cwd, id) {
+  return path.join(memoryDir(cwd), `${id}.json`);
+}
+
+function slugify(name) {
+  return String(name || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "")
+    .slice(0, 60);
+}
+
+function makeEpisodeId(taskName) {
+  const slug = slugify(taskName);
+  const rand = crypto.randomBytes(3).toString("hex");
+  return slug ? `ep_${slug}-${rand}` : `ep_${rand}`;
+}
+
+function deriveTags(text) {
+  return String(text || "")
+    .toLowerCase()
+    .split(/[\s/\\._\-:,;!?'"()[\]{}]+/)
+    .filter((w) => w.length >= 3 && !STOP_WORDS.has(w))
+    .filter((v, i, a) => a.indexOf(v) === i)
+    .slice(0, 20);
+}
+
+function deriveFilePatterns(files) {
+  const dirs = new Set();
+  for (const f of files) {
+    const dir = path.dirname(f).replace(/\\/g, "/");
+    if (dir && dir !== ".") dirs.add(`${dir}/**`);
+  }
+  return [...dirs];
+}
+
+async function readIndex(cwd) {
+  try {
+    const raw = await fs.readFile(indexPath(cwd), "utf8");
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+async function writeIndex(cwd, index) {
+  await fs.mkdir(memoryDir(cwd), { recursive: true });
+  await fs.writeFile(indexPath(cwd), `${JSON.stringify(index, null, 2)}\n`, "utf8");
+}
+
+export function compressEpisode({ task, receipt }) {
+  const id = makeEpisodeId(task.name || task.id);
+  const filesChanged = (receipt?.changedFiles || []).slice(0, MAX_FILES_PER_EPISODE);
+  const filePatterns = deriveFilePatterns(filesChanged);
+
+  // Key facts
+  const keyFacts = [];
+  if (task.goal) keyFacts.push(`Goal: ${task.goal}`);
+  if (task.chosenOption) {
+    const option = task.lastDecision?.options?.find((o) => o.id === task.chosenOption);
+    keyFacts.push(`Chose: ${task.chosenOption}${option?.title ? ` — ${option.title}` : ""}`);
+  }
+  if (receipt?.diffStat) {
+    const lastLine = receipt.diffStat.split("\n").pop()?.trim();
+    if (lastLine) keyFacts.push(`Diff: ${lastLine}`);
+  }
+  if (Array.isArray(receipt?.verification)) {
+    for (const v of receipt.verification) {
+      keyFacts.push(`Verify ${v.command}: ${v.ok ? "passed" : "FAILED"}`);
+    }
+  }
+
+  // Warnings and concerns
+  const warnings = [];
+  const sentinelConcerns = [];
+  if (receipt?.review?.concerns?.length) {
+    sentinelConcerns.push(...receipt.review.concerns);
+  }
+  if (receipt?.challenge?.concerns?.length) {
+    for (const c of receipt.challenge.concerns) {
+      if (!sentinelConcerns.includes(c)) sentinelConcerns.push(c);
+    }
+  }
+  if (Array.isArray(receipt?.verification)) {
+    for (const v of receipt.verification) {
+      if (!v.ok) warnings.push(`Verification failed: ${v.command}`);
+    }
+  }
+
+  // Outcome
+  let outcome = "closed-empty";
+  if (receipt?.mutated) {
+    outcome = task.accepted ? "accepted" : "closed-unaccepted";
+  }
+
+  // Tags from task name, goal, and file paths
+  const tagSource = [task.name, task.goal, ...filesChanged].join(" ");
+  const tags = deriveTags(tagSource);
+
+  return {
+    id,
+    taskId: task.id,
+    taskName: task.name || "",
+    closedAt: new Date().toISOString(),
+    goal: task.goal || "",
+    chosenOption: task.chosenOption || null,
+    outcome,
+    filesChanged,
+    filePatterns,
+    keyFacts: keyFacts.slice(0, 8),
+    warnings: warnings.slice(0, 5),
+    sentinelConcerns: sentinelConcerns.slice(0, 5),
+    tags
+  };
+}
+
+export async function saveEpisode({ cwd, episode }) {
+  await fs.mkdir(memoryDir(cwd), { recursive: true });
+  await fs.writeFile(episodePath(cwd, episode.id), `${JSON.stringify(episode, null, 2)}\n`, "utf8");
+
+  // Update index
+  const index = await readIndex(cwd);
+  const entry = {
+    id: episode.id,
+    taskName: episode.taskName,
+    closedAt: episode.closedAt,
+    tags: episode.tags,
+    filePatterns: episode.filePatterns,
+    outcome: episode.outcome
+  };
+  index.unshift(entry);
+  if (index.length > MAX_INDEX_ENTRIES) index.length = MAX_INDEX_ENTRIES;
+  await writeIndex(cwd, index);
+}
+
+export async function loadRecentEpisodes({ cwd, limit = 5 }) {
+  const index = await readIndex(cwd);
+  const recent = index.slice(0, limit);
+  const episodes = [];
+  for (const entry of recent) {
+    try {
+      const raw = await fs.readFile(episodePath(cwd, entry.id), "utf8");
+      episodes.push(JSON.parse(raw));
+    } catch {
+      // Skip missing/corrupt episodes
+    }
+  }
+  return episodes;
+}
+
+export async function findRelevantEpisodes({ cwd, filePatterns = [], tags = [], limit = 5 }) {
+  const index = await readIndex(cwd);
+  if (index.length === 0) return [];
+
+  const queryDirs = filePatterns.map((p) => p.replace(/\/?\*\*$/, "").replace(/\\/g, "/"));
+  const queryTags = new Set(tags.map((t) => t.toLowerCase()));
+
+  const scored = [];
+  for (const entry of index) {
+    let score = 0;
+
+    // File pattern overlap
+    if (queryDirs.length > 0 && Array.isArray(entry.filePatterns)) {
+      for (const ep of entry.filePatterns) {
+        const epDir = ep.replace(/\/?\*\*$/, "").replace(/\\/g, "/");
+        for (const qd of queryDirs) {
+          if (epDir.startsWith(qd) || qd.startsWith(epDir)) {
+            score += 3;
+            break;
+          }
+        }
+      }
+    }
+
+    // Tag overlap
+    if (queryTags.size > 0 && Array.isArray(entry.tags)) {
+      for (const t of entry.tags) {
+        if (queryTags.has(t)) score += 1;
+      }
+    }
+
+    if (score > 0) scored.push({ entry, score });
+  }
+
+  scored.sort((a, b) => b.score - a.score || new Date(b.entry.closedAt) - new Date(a.entry.closedAt));
+  const top = scored.slice(0, limit);
+
+  const episodes = [];
+  for (const { entry } of top) {
+    try {
+      const raw = await fs.readFile(episodePath(cwd, entry.id), "utf8");
+      episodes.push(JSON.parse(raw));
+    } catch {}
+  }
+  return episodes;
+}
+
+export function buildEpisodicMemoryBlock(episodes) {
+  if (!episodes || episodes.length === 0) return "";
+  const lines = ["Recent work in this project:"];
+  let chars = lines[0].length;
+
+  for (const ep of episodes) {
+    const date = ep.closedAt ? ep.closedAt.slice(0, 10) : "unknown";
+    const parts = [`[${date}] "${ep.taskName}" (${ep.outcome})`];
+    if (ep.keyFacts?.length > 0) parts.push(ep.keyFacts[0]);
+    if (ep.warnings?.length > 0) parts.push(`Warning: ${ep.warnings[0]}`);
+    if (ep.sentinelConcerns?.length > 0) parts.push(`Sentinel: ${ep.sentinelConcerns[0]}`);
+    const line = `- ${parts.join(". ")}`;
+    if (chars + line.length + 1 > MAX_EPISODIC_PROMPT_CHARS) break;
+    lines.push(line);
+    chars += line.length + 1;
+  }
+
+  return lines.join("\n");
+}
+
+export function buildReminderBlock({ episodes = [], memoryText = "", contractPaths = [] }) {
+  const contractDirs = contractPaths.map((p) => p.replace(/\/?\*\*$/, "").replace(/\\/g, "/").toLowerCase());
+  const reminders = [];
+  let chars = 0;
+
+  // From episodes: warnings and concerns for overlapping scopes
+  for (const ep of episodes) {
+    const epDirs = (ep.filePatterns || []).map((p) => p.replace(/\/?\*\*$/, "").replace(/\\/g, "/").toLowerCase());
+    const overlaps = contractDirs.length === 0 || epDirs.some((ed) => contractDirs.some((cd) => ed.startsWith(cd) || cd.startsWith(ed)));
+    if (!overlaps) continue;
+
+    for (const w of (ep.warnings || [])) {
+      const line = `[from "${ep.taskName}"]: ${w}`;
+      if (chars + line.length > MAX_REMINDER_CHARS) break;
+      reminders.push(line);
+      chars += line.length;
+    }
+    for (const c of (ep.sentinelConcerns || [])) {
+      const line = `[from "${ep.taskName}"]: Sentinel flagged: ${c}`;
+      if (chars + line.length > MAX_REMINDER_CHARS) break;
+      reminders.push(line);
+      chars += line.length;
+    }
+  }
+
+  // From WATERBROTHER.md: lines mentioning paths in contract scope
+  if (memoryText && contractDirs.length > 0) {
+    const memLines = memoryText.split("\n");
+    for (const ml of memLines) {
+      const lower = ml.toLowerCase();
+      const relevant = contractDirs.some((cd) => lower.includes(cd.split("/").pop()));
+      if (relevant && ml.trim().length > 5) {
+        const line = `[from WATERBROTHER.md]: ${ml.trim()}`;
+        if (chars + line.length > MAX_REMINDER_CHARS) break;
+        reminders.push(line);
+        chars += line.length;
+      }
+    }
+  }
+
+  if (reminders.length === 0) return "";
+  return `Reminders for this scope:\n${reminders.join("\n")}`;
+}