openclawdreams 2.0.1 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [2.3.0](https://github.com/RogueCtrl/OpenClawDreams/compare/v2.2.0...v2.3.0) (2026-03-09)
+
+
+### Features
+
+* cognitive rhythm report — weekly digest command + generator ([f61bb36](https://github.com/RogueCtrl/OpenClawDreams/commit/f61bb3680408b324dafca085b9dc354be670fb48))
+* cognitive rhythm report — weekly digest command + report generator ([4398709](https://github.com/RogueCtrl/OpenClawDreams/commit/4398709832898a94808ec267e8caf1b399d88574))
+
+## [2.2.0](https://github.com/RogueCtrl/OpenClawDreams/compare/v2.1.0...v2.2.0) (2026-03-09)
+
+
+### Features
+
+* dream entropy enforcement — overlap scoring + re-prompt on recycled territory ([fda1871](https://github.com/RogueCtrl/OpenClawDreams/commit/fda1871399cc35e1965b6b48a96d0f16c9a5df3e))
+* dream entropy enforcement — overlap scoring + re-prompt on recycled territory ([8745a73](https://github.com/RogueCtrl/OpenClawDreams/commit/8745a7394354f2f9be3ab2cf924b5cc48985d67b)), closes [#81](https://github.com/RogueCtrl/OpenClawDreams/issues/81)
+
+## [2.1.0](https://github.com/RogueCtrl/OpenClawDreams/compare/v2.0.2...v2.1.0) (2026-03-09)
+
+
+### Features
+
+* recursive reflection guard — meta_loop_depth counter + outward steering directive ([856b689](https://github.com/RogueCtrl/OpenClawDreams/commit/856b689b851e1e256c6a5aef6d1decc1cf4fab3c))
+* recursive reflection guard — meta_loop_depth counter + outward steering directive ([6584e82](https://github.com/RogueCtrl/OpenClawDreams/commit/6584e820e89352124ba50e259368defa18f90a66))
+
+### [2.0.2](https://github.com/RogueCtrl/OpenClawDreams/compare/v2.0.1...v2.0.2) (2026-03-09)
+
 ### [2.0.1](https://github.com/RogueCtrl/OpenClawDreams/compare/v1.7.0...v2.0.1) (2026-03-09)
 
 

package/dist/src/cli.js

@@ -424,6 +424,34 @@ export function registerCommands(parent) {
             process.exit(1);
         }
     });
+    parent
+        .command("report")
+        .description("Generate and send a weekly cognitive rhythm report")
+        .option("--dry-run", "Print JSON to stdout without sending notification")
+        .action(async (opts) => {
+        const { generateRhythmReport, formatReportNotification } = await import("./rhythm.js");
+        const report = generateRhythmReport();
+        if (opts.dryRun) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        const message = formatReportNotification(report);
+        console.log(chalk.cyan.bold("\nCognitive Rhythm Report\n"));
+        console.log(message);
+        // Try to send notification via OpenClaw channels
+        try {
+            const { getNotificationChannel } = await import("./config.js");
+            const channel = getNotificationChannel();
+            if (channel) {
+                console.log(chalk.dim(`\nNote: Notification sending requires OpenClaw runtime.`));
+                console.log(chalk.dim(`Configure via: openclaw plugins install`));
+            }
+        }
+        catch {
+            // standalone mode, no notification
+        }
+        console.log(chalk.green.bold("\nReport complete.\n"));
+    });
 } // end registerCommands
 // Standalone bin entry point
 export const program = new Command();

package/dist/src/config.d.ts

@@ -39,6 +39,8 @@ export declare const getPostFilterEnabled: () => boolean;
 export declare const getRequireApprovalBeforePost: () => boolean;
 export declare const getDreamSubmolt: () => string;
 export declare const getWorkspaceDiffEnabled: () => boolean;
+export declare const getMetaLoopThreshold: () => number;
+export declare const getEntropyOverlapThreshold: () => number;
 /** @deprecated Use getMoltbookEnabled() */
 export declare const MOLTBOOK_ENABLED = false;
 /** @deprecated Use getWebSearchEnabled() */

package/dist/src/config.js

@@ -65,6 +65,8 @@ let _postFilterEnabled = (process.env.POST_FILTER_ENABLED ?? "true").toLowerCase
 let _requireApprovalBeforePost = (process.env.REQUIRE_APPROVAL_BEFORE_POST ?? "true").toLowerCase() !== "false";
 let _dreamSubmolt = process.env.DREAM_SUBMOLT ?? "dreams";
 let _workspaceDiffEnabled = (process.env.WORKSPACE_DIFF_ENABLED ?? "true").toLowerCase() !== "false";
+let _metaLoopThreshold = parseInt(process.env.META_LOOP_THRESHOLD ?? "3", 10);
+let _entropyOverlapThreshold = parseFloat(process.env.ENTROPY_OVERLAP_THRESHOLD ?? "0.5");
 /** Apply config values passed from the OpenClaw plugin API (`api.pluginConfig`). */
 export function applyPluginConfig(cfg) {
     if (typeof cfg.moltbookEnabled === "boolean") {
@@ -84,6 +86,10 @@ export function applyPluginConfig(cfg) {
         _dreamSubmolt = cfg.dreamSubmolt;
     if (typeof cfg.workspaceDiffEnabled === "boolean")
         _workspaceDiffEnabled = cfg.workspaceDiffEnabled;
+    if (typeof cfg.metaLoopThreshold === "number")
+        _metaLoopThreshold = cfg.metaLoopThreshold;
+    if (typeof cfg.entropyOverlapThreshold === "number")
+        _entropyOverlapThreshold = cfg.entropyOverlapThreshold;
 }
 export const getMoltbookEnabled = () => _moltbookEnabled;
 export const getWebSearchEnabled = () => _webSearchEnabled;
@@ -93,6 +99,8 @@ export const getPostFilterEnabled = () => _postFilterEnabled;
 export const getRequireApprovalBeforePost = () => _requireApprovalBeforePost;
 export const getDreamSubmolt = () => _dreamSubmolt;
 export const getWorkspaceDiffEnabled = () => _workspaceDiffEnabled;
+export const getMetaLoopThreshold = () => _metaLoopThreshold;
+export const getEntropyOverlapThreshold = () => _entropyOverlapThreshold;
 // Legacy constant aliases — kept for backward compatibility but now delegate to
 // getters so they remain in sync after `applyPluginConfig()` is called.
 /** @deprecated Use getMoltbookEnabled() */

package/dist/src/dreamer.d.ts

@@ -11,7 +11,7 @@ import type { LLMClient, OpenClawAPI, Dream, DecryptedMemory } from "./types.js"
  * remembrance by title even when file is gone.
  */
 export declare function pruneOldDreams(dir: string, currentFile: string): void;
-export declare function generateDream(client: LLMClient, memories: DecryptedMemory[], exploredTerritory: string, isNightmare?: boolean): Promise<Dream>;
+export declare function generateDream(client: LLMClient, memories: DecryptedMemory[], exploredTerritory: string, isNightmare?: boolean, hardConstraint?: string): Promise<Dream>;
 /**
  * Synthesize two dreams into a single meta-dream.
  */

package/dist/src/dreamer.js

@@ -6,8 +6,10 @@
  */
 import { writeFileSync, readFileSync, readdirSync, existsSync, unlinkSync, } from "node:fs";
 import { resolve, basename } from "node:path";
-import { getDreamsDir, getNightmaresDir, MAX_TOKENS_DREAM, MAX_TOKENS_CONSOLIDATION, DREAM_TITLE_MAX_LENGTH, getMoltbookEnabled, getDreamSubmolt, } from "./config.js";
+import { getDreamsDir, getNightmaresDir, MAX_TOKENS_DREAM, MAX_TOKENS_CONSOLIDATION, DREAM_TITLE_MAX_LENGTH, getMoltbookEnabled, getDreamSubmolt, getEntropyOverlapThreshold, } from "./config.js";
+import { extractConcepts, computeOverlap, getOverlappingConcepts } from "./entropy.js";
 import { MoltbookClient } from "./moltbook.js";
+import { getSteeringDirective } from "./meta-loop.js";
 import { retrieveUndreamedMemories, markAsDreamed, deepMemoryStats, formatDeepMemoryContext, registerDream, incrementRememberCount, selectDreamToRemember, storeDeepMemory, getDeepMemoryById, } from "./memory.js";
 import { ensureBackfilled } from "./backfill.js";
 import { DREAM_SYSTEM_PROMPT, NIGHTMARE_SYSTEM_PROMPT, DREAM_CONSOLIDATION_PROMPT, GROUND_DREAM_PROMPT, META_DREAM_PROMPT, renderTemplate, } from "./persona.js";
@@ -42,7 +44,7 @@ export function pruneOldDreams(dir, currentFile) {
         }
     }
 }
-export async function generateDream(client, memories, exploredTerritory, isNightmare = false) {
+export async function generateDream(client, memories, exploredTerritory, isNightmare = false, hardConstraint) {
     const formatted = memories.map((mem) => `[${mem.timestamp.slice(0, 16)}] (${mem.category})\n${JSON.stringify(mem.content, null, 2)}`);
     const memoriesText = formatted.join("\n---\n");
     const prompt = isNightmare ? NIGHTMARE_SYSTEM_PROMPT : DREAM_SYSTEM_PROMPT;
@@ -50,16 +52,19 @@ export async function generateDream(client, memories, exploredTerritory, isNight
         agent_identity: getAgentIdentityBlock(),
         memories: memoriesText,
         explored_territory: exploredTerritory,
-    });
+    }) + getSteeringDirective();
+    const baseUserPrompt = isNightmare
+        ? "Process these memories into a nightmare. Be fractured and wrong."
+        : "Process these memories into a dream. Be surreal, associative, and emotionally amplified.";
     const { text } = await callWithRetry(client, {
         maxTokens: MAX_TOKENS_DREAM,
         system,
         messages: [
             {
                 role: "user",
-                content: isNightmare
-                    ? "Process these memories into a nightmare. Be fractured and wrong."
-                    : "Process these memories into a dream. Be surreal, associative, and emotionally amplified.",
+                content: hardConstraint
+                    ? `${baseUserPrompt}\n\n${hardConstraint}`
+                    : baseUserPrompt,
             },
         ],
     }, DREAM_RETRY_OPTS);
@@ -116,7 +121,7 @@ export async function groundDream(client, dream, exploredTerritory) {
             agent_identity: agentIdentity,
             yesterday_activity: yesterday,
             explored_territory: exploredTerritory,
-        });
+        }) + getSteeringDirective();
         const result = await callWithRetry(client, {
             maxTokens: MAX_TOKENS_CONSOLIDATION,
             system,
@@ -241,6 +246,19 @@ export async function runDreamCycle(client, api, simOptions) {
         : "None yet — explore freely.";
     // Generate new dream from current memories
     let dream = await generateDream(client, memories, exploredTerritory, isNightmare);
+    // ─── Entropy Enforcement ──────────────────────────────────────────────────
+    const concepts = extractConcepts(dream.markdown);
+    const overlapScore = computeOverlap(concepts, pastRealizations);
+    const threshold = getEntropyOverlapThreshold();
+    state.entropy_last_overlap = overlapScore;
+    if (overlapScore > threshold) {
+        const overlapping = getOverlappingConcepts(concepts, pastRealizations);
+        logger.warn(`[entropy] overlap=${overlapScore.toFixed(2)}, threshold=${threshold} — dream recycling explored territory, re-prompting`);
+        const hardConstraint = `HARD CONSTRAINT: Your previous draft recycled ${Math.round(overlapScore * 100)}% of already-explored territory. You MUST explore genuinely new ground. Forbidden concepts from prior realizations: [${overlapping.join(", ")}]. Do not revisit these themes. Find something entirely new.`;
+        dream = await generateDream(client, memories, exploredTerritory, isNightmare, hardConstraint);
+        state.entropy_reprompt_count = (state.entropy_reprompt_count ?? 0) + 1;
+    }
+    // ──────────────────────────────────────────────────────────────────────────
     // If a remembrance was triggered, synthesize them into a single meta-dream
     if (rememberedDream) {
         logger.info("Synthesizing meta-dream from echo and new vision...");

package/dist/src/entropy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Entropy check utilities for detecting concept recycling.
+ */
+/**
+ * Tokenize text into lowercase words, strip punctuation, and remove stop words.
+ * Returns deduplicated words with at least 3 characters.
+ */
+export declare function extractConcepts(text: string): string[];
+/**
+ * Compute the overlap ratio (0.0 to 1.0) between current concepts and past realizations.
+ * Past realizations are raw text strings that get concept-extracted internally.
+ */
+export declare function computeOverlap(concepts: string[], pastRealizations: string[]): number;
+/**
+ * Identify which concepts from the current set already exist in past realizations.
+ */
+export declare function getOverlappingConcepts(concepts: string[], pastRealizations: string[]): string[];
+/**
+ * Compute Jaccard overlap between two sets of concept words.
+ * Returns a value between 0 and 1.
+ */
+export declare function computeJaccardOverlap(a: string[], b: string[]): number;
+//# sourceMappingURL=entropy.d.ts.map

package/dist/src/entropy.js

@@ -0,0 +1,188 @@
+/**
+ * Entropy check utilities for detecting concept recycling.
+ */
+/**
+ * Tokenize text into lowercase words, strip punctuation, and remove stop words.
+ * Returns deduplicated words with at least 3 characters.
+ */
+export function extractConcepts(text) {
+    const stopWords = new Set([
+        "a",
+        "an",
+        "the",
+        "is",
+        "are",
+        "was",
+        "were",
+        "be",
+        "been",
+        "being",
+        "have",
+        "has",
+        "had",
+        "do",
+        "does",
+        "did",
+        "will",
+        "would",
+        "could",
+        "should",
+        "may",
+        "might",
+        "must",
+        "shall",
+        "can",
+        "to",
+        "of",
+        "in",
+        "on",
+        "at",
+        "for",
+        "from",
+        "with",
+        "by",
+        "about",
+        "as",
+        "into",
+        "through",
+        "and",
+        "or",
+        "but",
+        "not",
+        "nor",
+        "this",
+        "that",
+        "these",
+        "those",
+        "it",
+        "its",
+        "i",
+        "me",
+        "you",
+        "we",
+        "our",
+        "they",
+        "them",
+        "he",
+        "she",
+        "my",
+        "your",
+        "their",
+        "what",
+        "which",
+        "who",
+        "whom",
+        "when",
+        "where",
+        "how",
+        "why",
+        "so",
+        "if",
+        "then",
+        "than",
+        "there",
+        "here",
+        "all",
+        "each",
+        "every",
+        "both",
+        "few",
+        "any",
+        "no",
+        "more",
+        "most",
+        "other",
+        "some",
+        "such",
+        "same",
+        "just",
+        "also",
+        "very",
+        "too",
+        "only",
+        "own",
+        "up",
+        "out",
+        "over",
+        "after",
+        "before",
+        "between",
+        "under",
+        "during",
+        "without",
+        "again",
+        "once",
+        "now",
+        "even",
+        "back",
+        "still",
+        "well",
+    ]);
+    if (!text)
+        return [];
+    const words = text
+        .toLowerCase()
+        .replace(/[^\w\s]/g, " ")
+        .split(/\s+/)
+        .filter((word) => word.length >= 3 && !stopWords.has(word));
+    return [...new Set(words)];
+}
+/**
+ * Compute the overlap ratio (0.0 to 1.0) between current concepts and past realizations.
+ * Past realizations are raw text strings that get concept-extracted internally.
+ */
+export function computeOverlap(concepts, pastRealizations) {
+    if (concepts.length === 0 || !pastRealizations || pastRealizations.length === 0) {
+        return 0;
+    }
+    const pastConcepts = new Set();
+    for (const realization of pastRealizations) {
+        const extracted = extractConcepts(realization);
+        for (const concept of extracted) {
+            pastConcepts.add(concept);
+        }
+    }
+    if (pastConcepts.size === 0)
+        return 0;
+    let matchCount = 0;
+    for (const concept of concepts) {
+        if (pastConcepts.has(concept)) {
+            matchCount++;
+        }
+    }
+    return matchCount / concepts.length;
+}
+/**
+ * Identify which concepts from the current set already exist in past realizations.
+ */
+export function getOverlappingConcepts(concepts, pastRealizations) {
+    if (concepts.length === 0 || !pastRealizations || pastRealizations.length === 0) {
+        return [];
+    }
+    const pastConcepts = new Set();
+    for (const realization of pastRealizations) {
+        const extracted = extractConcepts(realization);
+        for (const concept of extracted) {
+            pastConcepts.add(concept);
+        }
+    }
+    return concepts.filter((concept) => pastConcepts.has(concept));
+}
+/**
+ * Compute Jaccard overlap between two sets of concept words.
+ * Returns a value between 0 and 1.
+ */
+export function computeJaccardOverlap(a, b) {
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    const setA = new Set(a);
+    const setB = new Set(b);
+    let intersection = 0;
+    for (const word of setA) {
+        if (setB.has(word))
+            intersection++;
+    }
+    const union = new Set([...setA, ...setB]).size;
+    return union === 0 ? 0 : intersection / union;
+}
+//# sourceMappingURL=entropy.js.map

package/dist/src/meta-loop.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Recursive reflection guard.
+ *
+ * Detects when the reflection pipeline is stuck in a self-referential loop
+ * and injects a steering directive to break out.
+ */
+/**
+ * Returns true if the topics suggest the agent is reflecting on itself
+ * rather than outward events. A topic matches if it contains any keyword
+ * as a substring (case-insensitive). Self-referential when >= 2 topics match.
+ */
+export declare function isSelfReferential(topics: string[]): boolean;
+/**
+ * Update meta_loop_depth in state based on whether the latest reflection
+ * topics are self-referential. Call after saving last_reflection_topics.
+ */
+export declare function updateMetaLoopDepth(topics: string[]): number;
+/**
+ * Returns a steering directive string if meta_loop_depth >= threshold,
+ * or empty string otherwise. Intended to be appended to system prompts.
+ */
+export declare function getSteeringDirective(): string;
+//# sourceMappingURL=meta-loop.d.ts.map

package/dist/src/meta-loop.js

@@ -0,0 +1,72 @@
+/**
+ * Recursive reflection guard.
+ *
+ * Detects when the reflection pipeline is stuck in a self-referential loop
+ * and injects a steering directive to break out.
+ */
+import { getMetaLoopThreshold } from "./config.js";
+import { loadState, saveState } from "./state.js";
+import logger from "./logger.js";
+const SELF_REFERENTIAL_KEYWORDS = [
+    "dream",
+    "reflection",
+    "pipeline",
+    "recursive",
+    "meta",
+    "architecture",
+    "loop",
+    "self",
+    "aware",
+    "myself",
+    "system",
+    "introspect",
+    "cognition",
+    "consciousness",
+];
+/**
+ * Returns true if the topics suggest the agent is reflecting on itself
+ * rather than outward events. A topic matches if it contains any keyword
+ * as a substring (case-insensitive). Self-referential when >= 2 topics match.
+ */
+export function isSelfReferential(topics) {
+    if (!topics || topics.length === 0)
+        return false;
+    let matchCount = 0;
+    for (const topic of topics) {
+        const lower = topic.toLowerCase();
+        if (SELF_REFERENTIAL_KEYWORDS.some((kw) => lower.includes(kw))) {
+            matchCount++;
+        }
+    }
+    return matchCount >= 2;
+}
+/**
+ * Update meta_loop_depth in state based on whether the latest reflection
+ * topics are self-referential. Call after saving last_reflection_topics.
+ */
+export function updateMetaLoopDepth(topics) {
+    const state = loadState();
+    if (isSelfReferential(topics)) {
+        state.meta_loop_depth = (state.meta_loop_depth ?? 0) + 1;
+    }
+    else {
+        state.meta_loop_depth = 0;
+    }
+    saveState(state);
+    return state.meta_loop_depth;
+}
+const STEERING_DIRECTIVE_TEMPLATE = `IMPORTANT: You have been reflecting on your own architecture and pipeline for {{meta_loop_depth}} consecutive cycles. Break the loop. Turn outward. Do not reflect on dreams, the reflection pipeline, self-awareness, recursion, or meta-cognition in this cycle. Dream of something rooted in the world: a place, a person, a problem, a sensation, a story. Explore freely elsewhere.`;
+/**
+ * Returns a steering directive string if meta_loop_depth >= threshold,
+ * or empty string otherwise. Intended to be appended to system prompts.
+ */
+export function getSteeringDirective() {
+    const state = loadState();
+    const depth = state.meta_loop_depth ?? 0;
+    const threshold = getMetaLoopThreshold();
+    if (depth < threshold)
+        return "";
+    logger.warn(`[meta-loop] depth=${depth}, threshold=${threshold} — injecting outward steering directive`);
+    return ("\n\n" + STEERING_DIRECTIVE_TEMPLATE.replace("{{meta_loop_depth}}", String(depth)));
+}
+//# sourceMappingURL=meta-loop.js.map

package/dist/src/reflection.js

@@ -13,6 +13,7 @@
 import { DREAM_DECOMPOSE_PROMPT, DREAM_REFLECT_PROMPT, renderTemplate, } from "./persona.js";
 import { getAgentIdentityBlock } from "./identity.js";
 import { formatDeepMemoryContext } from "./memory.js";
+import { getSteeringDirective } from "./meta-loop.js";
 import { callWithRetry, WAKING_RETRY_OPTS } from "./llm.js";
 import { MAX_TOKENS_REFLECTION } from "./config.js";
 import logger from "./logger.js";
@@ -63,7 +64,7 @@ async function reflectOnDream(client, dream, subjects, exploredTerritory = "None
         recent_context: formatDeepMemoryContext(),
         subjects: subjects.map((s, i) => `${i + 1}. ${s}`).join("\n"),
         explored_territory: exploredTerritory,
-    });
+    }) + getSteeringDirective();
     const { text } = await callWithRetry(client, {
         maxTokens: MAX_TOKENS_REFLECTION,
         system,

package/dist/src/rhythm.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cognitive Rhythm Report — weekly digest of dream and reflection activity.
+ */
+export interface RhythmReport {
+    period_start: string;
+    period_end: string;
+    total_dreams: number;
+    total_nightmares: number;
+    total_reflections: number;
+    dominant_themes: string[];
+    tone_trajectory: "improving" | "declining" | "stable" | "unknown";
+    insight_density: number;
+    entropy_reprompts: number;
+    meta_loop_depth_peak: number;
+    raw_summary: string;
+}
+export declare function generateRhythmReport(dataDir?: string): RhythmReport;
+export declare function formatReportNotification(report: RhythmReport): string;
+//# sourceMappingURL=rhythm.d.ts.map

package/dist/src/rhythm.js

@@ -0,0 +1,129 @@
+/**
+ * Cognitive Rhythm Report — weekly digest of dream and reflection activity.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { getDreamsDir, getNightmaresDir } from "./config.js";
+import { loadState } from "./state.js";
+import { extractConcepts, computeJaccardOverlap } from "./entropy.js";
+function getFilesInDateRange(dir, start, end) {
+    let files;
+    try {
+        files = readdirSync(dir).filter((f) => f.endsWith(".md"));
+    }
+    catch {
+        return [];
+    }
+    return files.filter((f) => {
+        const datePrefix = f.slice(0, 10);
+        return datePrefix >= start && datePrefix <= end;
+    });
+}
+function readFileContents(dir, files) {
+    return files.map((f) => {
+        try {
+            return readFileSync(resolve(dir, f), "utf-8");
+        }
+        catch {
+            return "";
+        }
+    });
+}
+function computeTopThemes(contents, limit) {
+    const freq = new Map();
+    for (const text of contents) {
+        for (const word of extractConcepts(text)) {
+            freq.set(word, (freq.get(word) ?? 0) + 1);
+        }
+    }
+    return [...freq.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, limit)
+        .map(([word]) => word);
+}
+function computeToneTrajectory(contents, pastRealizations) {
+    if (contents.length < 2)
+        return "unknown";
+    const referenceConcepts = pastRealizations.length > 0 ? extractConcepts(pastRealizations.join(" ")) : [];
+    if (referenceConcepts.length === 0)
+        return "unknown";
+    const mid = Math.floor(contents.length / 2);
+    const firstHalf = contents.slice(0, mid);
+    const secondHalf = contents.slice(mid);
+    const avgOverlap = (texts) => {
+        if (texts.length === 0)
+            return 0;
+        const total = texts.reduce((sum, text) => sum + computeJaccardOverlap(extractConcepts(text), referenceConcepts), 0);
+        return total / texts.length;
+    };
+    const firstAvg = avgOverlap(firstHalf);
+    const secondAvg = avgOverlap(secondHalf);
+    const diff = secondAvg - firstAvg;
+    const threshold = 0.1 * Math.max(firstAvg, secondAvg, 0.01);
+    if (Math.abs(diff) <= threshold)
+        return "stable";
+    return diff < 0 ? "improving" : "declining";
+}
+function computeInsightDensity(contents) {
+    if (contents.length === 0)
+        return 0;
+    const total = contents.reduce((sum, text) => {
+        const unique = new Set(extractConcepts(text));
+        return sum + unique.size;
+    }, 0);
+    return Math.round((total / contents.length) * 100) / 100;
+}
+export function generateRhythmReport(dataDir) {
+    const now = new Date();
+    const weekAgo = new Date(now);
+    weekAgo.setDate(weekAgo.getDate() - 7);
+    const periodEnd = now.toISOString().slice(0, 10);
+    const periodStart = weekAgo.toISOString().slice(0, 10);
+    const dreamsDir = dataDir ? resolve(dataDir, "data", "dreams") : getDreamsDir();
+    const nightmaresDir = dataDir
+        ? resolve(dataDir, "data", "nightmares")
+        : getNightmaresDir();
+    const dreamFiles = getFilesInDateRange(dreamsDir, periodStart, periodEnd);
+    const nightmareFiles = getFilesInDateRange(nightmaresDir, periodStart, periodEnd);
+    const dreamContents = readFileContents(dreamsDir, dreamFiles);
+    const allContents = [
+        ...dreamContents,
+        ...readFileContents(nightmaresDir, nightmareFiles),
+    ];
+    const state = loadState();
+    const pastRealizations = state.past_realizations ?? [];
+    const dominantThemes = computeTopThemes(allContents, 5);
+    const toneTrajectory = computeToneTrajectory(allContents, pastRealizations);
+    const insightDensity = computeInsightDensity(allContents);
+    const entropyReprompts = state.entropy_reprompt_count ?? 0;
+    const metaLoopDepthPeak = state.meta_loop_depth ?? 0;
+    const totalReflections = state.checks_today ?? 0;
+    const themeStr = dominantThemes.length > 0 ? dominantThemes.join(", ") : "none detected";
+    const rawSummary = `Over the past week, ${dreamFiles.length} dream(s) and ${nightmareFiles.length} nightmare(s) were recorded. ` +
+        `Dominant themes included ${themeStr}. ` +
+        `Tone trajectory: ${toneTrajectory}.`;
+    return {
+        period_start: periodStart,
+        period_end: periodEnd,
+        total_dreams: dreamFiles.length,
+        total_nightmares: nightmareFiles.length,
+        total_reflections: totalReflections,
+        dominant_themes: dominantThemes,
+        tone_trajectory: toneTrajectory,
+        insight_density: insightDensity,
+        entropy_reprompts: entropyReprompts,
+        meta_loop_depth_peak: metaLoopDepthPeak,
+        raw_summary: rawSummary,
+    };
+}
+export function formatReportNotification(report) {
+    return [
+        `Weekly Rhythm Report (${report.period_start} to ${report.period_end})`,
+        `Dreams: ${report.total_dreams} | Nightmares: ${report.total_nightmares}`,
+        `Dominant themes: ${report.dominant_themes.length > 0 ? report.dominant_themes.join(", ") : "none"}`,
+        `Tone: ${report.tone_trajectory} | Insight density: ${report.insight_density} concepts/dream`,
+        `Entropy re-prompts: ${report.entropy_reprompts} | Meta-loop depth: ${report.meta_loop_depth_peak}`,
+        report.raw_summary,
+    ].join("\n");
+}
+//# sourceMappingURL=rhythm.js.map

package/dist/src/types.d.ts

@@ -71,6 +71,10 @@ export interface AgentState {
     waking_realization_date?: string | null;
     past_realizations?: string[];
     dreams_backfilled?: boolean;
+    last_reflection_topics?: string[];
+    meta_loop_depth?: number;
+    entropy_last_overlap?: number;
+    entropy_reprompt_count?: number;
     [key: string]: unknown;
 }
 export interface SchedulerState {
@@ -218,5 +222,6 @@ export interface ElectricSheepConfig {
     notifyOperatorOnDream: boolean;
     requireApprovalBeforePost: boolean;
     dreamSubmolt: string;
+    entropyOverlapThreshold: number;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/src/waking.js

@@ -12,6 +12,7 @@ import { callWithRetry, WAKING_RETRY_OPTS } from "./llm.js";
 import { gatherContext, synthesizeContext } from "./synthesis.js";
 import { getRecentConversations } from "./topics.js";
 import logger from "./logger.js";
+import { updateMetaLoopDepth } from "./meta-loop.js";
 /**
  * Summarize a synthesis for working memory storage.
  */
@@ -133,6 +134,8 @@ export async function runReflectionCycle(client, api, options) {
     state.checks_today = (state.checks_today ?? 0) + 1;
     state.last_reflection_topics = context.topics;
     saveState(state);
+    // Update recursive reflection guard
+    updateMetaLoopDepth(context.topics);
     logger.info("Reflection cycle complete");
     const stats = deepMemoryStats();
     logger.debug(`Deep memories: ${stats.total_memories} (${stats.undreamed} undreamed)`);

package/dist/test/entropy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=entropy.test.d.ts.map

package/dist/test/entropy.test.js

@@ -0,0 +1,128 @@
+import { describe, it, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { extractConcepts, computeOverlap } from "../src/entropy.js";
+// Setup for integration tests
+const testDir = mkdtempSync(join(tmpdir(), "es-entropy-test-"));
+process.env.OPENCLAWDREAMS_DATA_DIR = testDir;
+process.env.ENTROPY_OVERLAP_THRESHOLD = "0.5";
+const { runDreamCycle } = await import("../src/dreamer.js");
+const { storeDeepMemory, closeDb } = await import("../src/memory.js");
+const { loadState, saveState } = await import("../src/state.js");
+const { closeLogger } = await import("../src/logger.js");
+function mockLLMClient(responses) {
+    let idx = 0;
+    return {
+        async createMessage() {
+            const text = responses[idx] ?? responses[responses.length - 1];
+            idx++;
+            return { text };
+        },
+    };
+}
+describe("Entropy utilities", () => {
+    describe("extractConcepts", () => {
+        it("returns meaningful words from typical dream text", () => {
+            const text = "The recursive lobster is standing in a server room made of coral. The racks breathe.";
+            const concepts = extractConcepts(text);
+            // Expected: recursive, lobster, standing, server, room, made, coral, racks, breathe
+            assert.ok(concepts.includes("recursive"));
+            assert.ok(concepts.includes("lobster"));
+            assert.ok(concepts.includes("standing"));
+            assert.ok(concepts.includes("server"));
+            assert.ok(concepts.includes("room"));
+            assert.ok(concepts.includes("made"));
+            assert.ok(concepts.includes("coral"));
+            assert.ok(concepts.includes("racks"));
+            assert.ok(concepts.includes("breathe"));
+            // Stop words removed
+            assert.ok(!concepts.includes("the"));
+            assert.ok(!concepts.includes("is"));
+            assert.ok(!concepts.includes("in"));
+            assert.ok(!concepts.includes("a"));
+            assert.ok(!concepts.includes("of"));
+        });
+        it("strips punctuation and converts to lowercase", () => {
+            const text = "LOBSTER! (recursive) - coral.";
+            const concepts = extractConcepts(text);
+            assert.deepEqual(concepts.sort(), ["coral", "lobster", "recursive"]);
+        });
+        it("deduplicates words", () => {
+            const text = "lobster lobster coral coral";
+            const concepts = extractConcepts(text);
+            assert.deepEqual(concepts.sort(), ["coral", "lobster"]);
+        });
+        it("filters out words shorter than 3 characters", () => {
+            const text = "a it to ox coral";
+            const concepts = extractConcepts(text);
+            assert.deepEqual(concepts, ["coral"]);
+        });
+        it("returns empty array for empty string", () => {
+            assert.deepEqual(extractConcepts(""), []);
+        });
+    });
+    describe("computeOverlap", () => {
+        it("returns 0 for empty inputs", () => {
+            assert.equal(computeOverlap([], []), 0);
+            assert.equal(computeOverlap(["lobster"], []), 0);
+            assert.equal(computeOverlap([], ["past realization"]), 0);
+        });
+        it("returns correct ratio for known inputs (0.5)", () => {
+            const concepts = ["lobster", "coral", "server", "room"];
+            const past = ["The lobster is in the room."];
+            // Overlapping: lobster, room (2 of 4)
+            assert.equal(computeOverlap(concepts, past), 0.5);
+        });
+        it("returns 1.0 when all concepts overlap", () => {
+            const concepts = ["lobster", "coral"];
+            const past = ["A lobster made of coral."];
+            assert.equal(computeOverlap(concepts, past), 1.0);
+        });
+        it("handles past_realizations with multiple entries", () => {
+            const concepts = ["lobster", "coral", "server"];
+            assert.equal(computeOverlap(concepts, ["lobster", "coral"]), 2 / 3);
+        });
+    });
+});
+describe("Entropy integration", () => {
+    it("saves entropy_last_overlap to state after dream generation", async () => {
+        storeDeepMemory({ text: "memory 1" }, "interaction");
+        const client = mockLLMClient([
+            "# Dream\n\nLobster and coral.",
+            "insight",
+            "realization",
+        ]);
+        await runDreamCycle(client);
+        const state = loadState();
+        assert.notEqual(state.entropy_last_overlap, undefined);
+        assert.ok(typeof state.entropy_last_overlap === "number");
+    });
+    it("increments entropy_reprompt_count when overlap exceeds threshold", async () => {
+        storeDeepMemory({ text: "memory 2" }, "interaction");
+        const state = loadState();
+        state.past_realizations = ["lobster", "coral", "server"];
+        saveState(state);
+        // First draft overlaps completely: lobster, coral, server
+        const firstDraft = "# Dream\n\nLobster, coral, and server.";
+        // Second draft is different
+        const secondDraft = "# New Dream\n\nForest and mountains.";
+        // runDreamCycle calls:
+        // 1. generateDream (first draft)
+        // 2. generateDream (re-prompt)
+        // 3. consolidateDream
+        // 4. groundDream
+        const client = mockLLMClient([firstDraft, secondDraft, "insight", "realization"]);
+        await runDreamCycle(client);
+        const newState = loadState();
+        assert.equal(newState.entropy_reprompt_count, 1);
+        assert.equal(newState.entropy_last_overlap, 0.75); // "dream", "lobster", "coral", "server" -> 3/4 overlap
+    });
+});
+after(async () => {
+    closeDb();
+    await closeLogger();
+    rmSync(testDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+});
+//# sourceMappingURL=entropy.test.js.map

package/dist/test/meta-loop.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=meta-loop.test.d.ts.map

package/dist/test/meta-loop.test.js

@@ -0,0 +1,96 @@
+import { describe, it, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+// Isolated data dir
+const testDir = mkdtempSync(join(tmpdir(), "es-metaloop-test-"));
+process.env.OPENCLAWDREAMS_DATA_DIR = testDir;
+const { isSelfReferential, updateMetaLoopDepth, getSteeringDirective } = await import("../src/meta-loop.js");
+const { loadState, saveState } = await import("../src/state.js");
+describe("isSelfReferential", () => {
+    it("returns true for self-referential topics", () => {
+        assert.equal(isSelfReferential(["dream interpretation", "recursive reflection"]), true);
+    });
+    it("returns true with partial keyword matches", () => {
+        assert.equal(isSelfReferential(["metacognition patterns", "self-awareness"]), true);
+    });
+    it("returns false for outward topics", () => {
+        assert.equal(isSelfReferential(["weather patterns", "cooking recipes"]), false);
+    });
+    it("returns false for empty topics", () => {
+        assert.equal(isSelfReferential([]), false);
+    });
+    it("returns false for null/undefined topics", () => {
+        assert.equal(isSelfReferential(null), false);
+        assert.equal(isSelfReferential(undefined), false);
+    });
+    it("returns false when only one topic matches", () => {
+        assert.equal(isSelfReferential(["dream journaling", "ocean waves"]), false);
+    });
+    it("is case-insensitive", () => {
+        assert.equal(isSelfReferential(["DREAM analysis", "RECURSIVE patterns"]), true);
+    });
+    it("returns true for mixed topics with >= 2 matching", () => {
+        assert.equal(isSelfReferential(["consciousness studies", "pizza recipes", "meta-analysis"]), true);
+    });
+});
+describe("updateMetaLoopDepth", () => {
+    beforeEach(() => {
+        const state = loadState();
+        state.meta_loop_depth = 0;
+        saveState(state);
+    });
+    it("increments depth for self-referential topics", () => {
+        const depth = updateMetaLoopDepth(["dream cycles", "self reflection"]);
+        assert.equal(depth, 1);
+    });
+    it("increments consecutively", () => {
+        updateMetaLoopDepth(["dream cycles", "meta patterns"]);
+        const depth = updateMetaLoopDepth(["recursive loops", "self awareness"]);
+        assert.equal(depth, 2);
+    });
+    it("resets depth for outward topics", () => {
+        updateMetaLoopDepth(["dream cycles", "meta patterns"]);
+        updateMetaLoopDepth(["recursive loops", "self awareness"]);
+        const depth = updateMetaLoopDepth(["gardening", "astronomy"]);
+        assert.equal(depth, 0);
+    });
+    it("persists depth to state", () => {
+        updateMetaLoopDepth(["dream cycles", "meta patterns"]);
+        const state = loadState();
+        assert.equal(state.meta_loop_depth, 1);
+    });
+});
+describe("getSteeringDirective", () => {
+    beforeEach(() => {
+        const state = loadState();
+        state.meta_loop_depth = 0;
+        saveState(state);
+    });
+    it("returns empty string when depth < threshold", () => {
+        const state = loadState();
+        state.meta_loop_depth = 2;
+        saveState(state);
+        assert.equal(getSteeringDirective(), "");
+    });
+    it("returns directive when depth >= threshold (default 3)", () => {
+        const state = loadState();
+        state.meta_loop_depth = 3;
+        saveState(state);
+        const directive = getSteeringDirective();
+        assert.ok(directive.includes("3 consecutive cycles"));
+        assert.ok(directive.includes("Break the loop"));
+    });
+    it("returns directive with correct depth value", () => {
+        const state = loadState();
+        state.meta_loop_depth = 5;
+        saveState(state);
+        const directive = getSteeringDirective();
+        assert.ok(directive.includes("5 consecutive cycles"));
+    });
+    it("returns empty string when depth is 0", () => {
+        assert.equal(getSteeringDirective(), "");
+    });
+});
+//# sourceMappingURL=meta-loop.test.js.map

package/dist/test/rhythm.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=rhythm.test.d.ts.map

package/dist/test/rhythm.test.js

@@ -0,0 +1,102 @@
+import { describe, it, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+const testDir = mkdtempSync(join(tmpdir(), "es-rhythm-test-"));
+process.env.OPENCLAWDREAMS_DATA_DIR = testDir;
+const { generateRhythmReport, formatReportNotification } = await import("../src/rhythm.js");
+const { closeLogger } = await import("../src/logger.js");
+const { saveState } = await import("../src/state.js");
+function todayStr() {
+    return new Date().toISOString().slice(0, 10);
+}
+function daysAgoStr(n) {
+    const d = new Date();
+    d.setDate(d.getDate() - n);
+    return d.toISOString().slice(0, 10);
+}
+describe("Cognitive Rhythm Report", () => {
+    it("returns correct period (7 days back)", () => {
+        const report = generateRhythmReport(testDir);
+        assert.equal(report.period_end, todayStr());
+        assert.equal(report.period_start, daysAgoStr(7));
+    });
+    it("returns zeroed report with no dream files and tone_trajectory unknown", () => {
+        const report = generateRhythmReport(testDir);
+        assert.equal(report.total_dreams, 0);
+        assert.equal(report.total_nightmares, 0);
+        assert.equal(report.tone_trajectory, "unknown");
+        assert.equal(report.insight_density, 0);
+        assert.deepEqual(report.dominant_themes, []);
+    });
+    it("counts dream files correctly", () => {
+        const dreamsDir = join(testDir, "data", "dreams");
+        mkdirSync(dreamsDir, { recursive: true });
+        const today = todayStr();
+        writeFileSync(join(dreamsDir, `${today}_test-dream.md`), "# A Dream\nFloating through clouds of memory and light.");
+        writeFileSync(join(dreamsDir, `${today}_another-dream.md`), "# Another Dream\nWalking through fields of golden wheat.");
+        // Old dream outside window
+        writeFileSync(join(dreamsDir, "2020-01-01_old-dream.md"), "# Old Dream\nAncient memory.");
+        const report = generateRhythmReport(testDir);
+        assert.equal(report.total_dreams, 2);
+    });
+    it("returns top 5 dominant themes (or fewer if less data)", () => {
+        const report = generateRhythmReport(testDir);
+        assert.ok(report.dominant_themes.length <= 5);
+        assert.ok(report.dominant_themes.length > 0);
+    });
+    it("calculates insight_density correctly", () => {
+        const report = generateRhythmReport(testDir);
+        assert.ok(report.insight_density > 0);
+        assert.equal(typeof report.insight_density, "number");
+    });
+    it("returns stable tone_trajectory with only one dream file", () => {
+        // Clean up extra dream
+        const dreamsDir = join(testDir, "data", "dreams");
+        const today = todayStr();
+        rmSync(join(dreamsDir, `${today}_another-dream.md`), { force: true });
+        const report = generateRhythmReport(testDir);
+        // With only 1 dream content, not enough data for trajectory
+        assert.equal(report.tone_trajectory, "unknown");
+    });
+    it("counts nightmare files correctly", () => {
+        const nightmaresDir = join(testDir, "data", "nightmares");
+        mkdirSync(nightmaresDir, { recursive: true });
+        const yesterday = daysAgoStr(1);
+        writeFileSync(join(nightmaresDir, `${yesterday}_scary.md`), "# Nightmare\nDark shadows creeping through the corridors.");
+        const report = generateRhythmReport(testDir);
+        assert.equal(report.total_nightmares, 1);
+    });
+    it("reads entropy_reprompts and meta_loop_depth from state", () => {
+        saveState({
+            entropy_reprompt_count: 3,
+            meta_loop_depth: 2,
+            checks_today: 5,
+        });
+        const report = generateRhythmReport(testDir);
+        assert.equal(report.entropy_reprompts, 3);
+        assert.equal(report.meta_loop_depth_peak, 2);
+        assert.equal(report.total_reflections, 5);
+    });
+    it("notification string contains all expected fields", () => {
+        const report = generateRhythmReport(testDir);
+        const notification = formatReportNotification(report);
+        assert.ok(notification.includes("Weekly Rhythm Report"));
+        assert.ok(notification.includes(report.period_start));
+        assert.ok(notification.includes(report.period_end));
+        assert.ok(notification.includes(`Dreams: ${report.total_dreams}`));
+        assert.ok(notification.includes(`Nightmares: ${report.total_nightmares}`));
+        assert.ok(notification.includes("Dominant themes:"));
+        assert.ok(notification.includes(`Tone: ${report.tone_trajectory}`));
+        assert.ok(notification.includes(`Insight density: ${report.insight_density}`));
+        assert.ok(notification.includes(`Entropy re-prompts: ${report.entropy_reprompts}`));
+        assert.ok(notification.includes(`Meta-loop depth: ${report.meta_loop_depth_peak}`));
+        assert.ok(notification.includes(report.raw_summary));
+    });
+});
+after(async () => {
+    await closeLogger();
+    rmSync(testDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+});
+//# sourceMappingURL=rhythm.test.js.map

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclawdreams",
   "name": "openclawdreams",
   "displayName": "ElectricSheep",
-  "version": "2.0.1",
+  "version": "2.3.0",
   "description": "A reflection engine that synthesizes agent-operator interactions into dreams, enriched by community and web context",
   "entry": "dist/src/index.js",
   "skills": [
@@ -61,6 +61,11 @@
         "type": "boolean",
         "description": "Capture git diff --stat at agent_end for richer reflections. Disable if your workspace is on iCloud Drive or in a sensitive macOS-protected location.",
         "default": true
+      },
+      "metaLoopThreshold": {
+        "type": "number",
+        "description": "Number of consecutive self-referential reflection cycles before injecting an outward steering directive",
+        "default": 3
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclawdreams",
-  "version": "2.0.1",
+  "version": "2.3.0",
   "description": "A reflection engine that synthesizes agent-operator interactions into dreams",
   "type": "module",
   "main": "dist/index.js",