clementine-agent 1.0.88 → 1.0.89

package/README.md

@@ -585,6 +585,19 @@ The dashboard's "The Office" page shows each agent as an animated desk station w
 - Channel assignment, model badge, project badge, tool count
 - Edit and "Let Go" (delete) actions
 
+### Decision-loop reflection
+
+Each agent's autonomous decisions are recorded to a proactive ledger (action chosen, signal source, eventual outcome). The `decision_reflection` MCP tool reads that ledger, computes per-action success rates, and surfaces calibration patterns:
+
+- "act_now success rate is 33% — many autonomous actions did not advance"
+- "Queue-heavy bias: 12 queued vs 2 act_now — engine is being conservative"
+- "Zero ask_user despite active autonomous work"
+- Plus concrete tuning suggestions
+
+By default the report is saved to `vault/00-System/agents/<slug>/reflections/<date>.md`. Pass `append_to_memory: true` to also write a compact summary into the agent's `working-memory.md` so the next heartbeat tick reads it as prompt context — that's how agents self-tune without code changes.
+
+The shipped `vault/00-System/CRON.md` template includes a `weekly-decision-reflection` job (Sundays 9am) that runs reflection for the daemon and every active specialist.
+
 ### Per-agent heartbeats
 
 Each specialist (Ross / Sasha / your hires) gets their own autonomous heartbeat scheduler alongside Clementine's. The cycle:

package/dist/agent/decision-reflection.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Clementine TypeScript — Per-agent decision-loop reflection.
+ *
+ * Reads an agent's slice of the proactive decision ledger and produces
+ * a calibration report:
+ *
+ *   - How many decisions per action (act_now / queue / ask_user / snooze / ignore)
+ *   - Of those, how many had recorded outcomes
+ *   - Success rate (advanced / withOutcomes) per action
+ *   - Top signal sources by volume
+ *   - Plain-English patterns + concrete tuning suggestions
+ *
+ * The report is meant to land in the agent's working-memory so it
+ * shapes their next heartbeat tick — they read their own track record
+ * and self-correct without code changes.
+ *
+ * Pure analysis: no I/O side effects. The MCP tool wrapper handles
+ * file writes (history) and working-memory updates separately.
+ */
+import type { ProactiveAction, ProactiveDecision, ProactiveSource } from './proactive-engine.js';
+export interface ActionBucket {
+    decided: number;
+    withOutcomes: number;
+    advanced: number;
+    blocked: number;
+    failed: number;
+    /** advanced / withOutcomes * 100, or null if no outcomes recorded yet. */
+    successRatePct: number | null;
+}
+export interface DecisionReflection {
+    slug: string;
+    windowDays: number;
+    totalDecisions: number;
+    byAction: Record<ProactiveAction, ActionBucket>;
+    topSources: Array<{
+        source: ProactiveSource;
+        count: number;
+    }>;
+    patterns: string[];
+    suggestions: string[];
+    generatedAt: string;
+}
+/**
+ * Read the ledger, filter by agent + window, compute the calibration
+ * stats. Returns a DecisionReflection ready to format.
+ *
+ * Agent matching: a record belongs to `slug` when context.owner === slug
+ * OR context.goalId resolves to a goal whose owner is slug. For now we
+ * match only on context.owner — slug-by-goal is more expensive (would
+ * need listAllGoals) and not worth it until owner is consistently set.
+ */
+export declare function analyzeAgentDecisions(slug: string, windowDays?: number, opts?: {
+    ledgerPath?: string;
+    now?: Date;
+}): DecisionReflection;
+export declare function formatReflectionReport(r: DecisionReflection): string;
+/**
+ * Compact summary for working-memory append. Skips the full table and
+ * keeps just the patterns + suggestions so the agent's prompt doesn't
+ * get bloated with raw stats.
+ */
+export declare function formatReflectionSummary(r: DecisionReflection): string;
+/** Internal type alias used by tests / tool. */
+export type { ProactiveDecision };
+//# sourceMappingURL=decision-reflection.d.ts.map

package/dist/agent/decision-reflection.js

@@ -0,0 +1,240 @@
+/**
+ * Clementine TypeScript — Per-agent decision-loop reflection.
+ *
+ * Reads an agent's slice of the proactive decision ledger and produces
+ * a calibration report:
+ *
+ *   - How many decisions per action (act_now / queue / ask_user / snooze / ignore)
+ *   - Of those, how many had recorded outcomes
+ *   - Success rate (advanced / withOutcomes) per action
+ *   - Top signal sources by volume
+ *   - Plain-English patterns + concrete tuning suggestions
+ *
+ * The report is meant to land in the agent's working-memory so it
+ * shapes their next heartbeat tick — they read their own track record
+ * and self-correct without code changes.
+ *
+ * Pure analysis: no I/O side effects. The MCP tool wrapper handles
+ * file writes (history) and working-memory updates separately.
+ */
+import { recentDecisions } from './proactive-ledger.js';
+// ── Constants ────────────────────────────────────────────────────────
+const ALL_ACTIONS = ['act_now', 'queue', 'ask_user', 'snooze', 'ignore'];
+const LOW_SUCCESS_THRESHOLD = 50; // < 50% success → flag as miscalibrated
+const HIGH_VOLUME_THRESHOLD = 20; // > 20 decisions in window → "active loop"
+const DORMANT_THRESHOLD = 0; // 0 decisions → "dormant"
+function emptyBucket() {
+    return { decided: 0, withOutcomes: 0, advanced: 0, blocked: 0, failed: 0, successRatePct: null };
+}
+function emptyByAction() {
+    const out = {};
+    for (const a of ALL_ACTIONS)
+        out[a] = emptyBucket();
+    return out;
+}
+// ── Analysis ─────────────────────────────────────────────────────────
+/**
+ * Read the ledger, filter by agent + window, compute the calibration
+ * stats. Returns a DecisionReflection ready to format.
+ *
+ * Agent matching: a record belongs to `slug` when context.owner === slug
+ * OR context.goalId resolves to a goal whose owner is slug. For now we
+ * match only on context.owner — slug-by-goal is more expensive (would
+ * need listAllGoals) and not worth it until owner is consistently set.
+ */
+export function analyzeAgentDecisions(slug, windowDays = 7, opts) {
+    const now = opts?.now ?? new Date();
+    const sinceMs = windowDays * 24 * 60 * 60 * 1000;
+    const records = recentDecisions({ sinceMs }, opts?.ledgerPath ? { filePath: opts.ledgerPath, now } : { now });
+    // Filter to records relevant to this agent. Inclusion rule:
+    //   - context.owner === slug (preferred — explicitly attributed)
+    //   - else if slug === 'clementine': include records with no owner
+    //     (the daemon's own decisions default to no-owner)
+    const isClementine = slug === 'clementine';
+    const mine = records.filter((r) => {
+        const owner = r.context.owner;
+        if (owner)
+            return owner === slug;
+        return isClementine; // unowned → Clementine
+    });
+    // Outcome records share the original decision's id and have an
+    // `outcome` field. Index by id so we can pair decisions with their
+    // outcomes in one pass.
+    const outcomeById = new Map();
+    for (const r of mine) {
+        if (r.outcome)
+            outcomeById.set(r.id, r.outcome.status);
+    }
+    const byAction = emptyByAction();
+    const sourceCounts = new Map();
+    let totalDecisions = 0;
+    for (const r of mine) {
+        if (r.outcome)
+            continue; // outcomes are indexed; only count original decisions here
+        totalDecisions++;
+        const action = r.decision.action;
+        const bucket = byAction[action];
+        bucket.decided++;
+        const outcomeStatus = outcomeById.get(r.id);
+        if (outcomeStatus !== undefined) {
+            bucket.withOutcomes++;
+            if (outcomeStatus === 'advanced')
+                bucket.advanced++;
+            else if (typeof outcomeStatus === 'string' && outcomeStatus.startsWith('blocked-'))
+                bucket.blocked++;
+            else if (outcomeStatus === 'failed')
+                bucket.failed++;
+        }
+        const src = r.decision.source;
+        sourceCounts.set(src, (sourceCounts.get(src) ?? 0) + 1);
+    }
+    // Compute success rates
+    for (const a of ALL_ACTIONS) {
+        const b = byAction[a];
+        b.successRatePct = b.withOutcomes > 0 ? Math.round((b.advanced / b.withOutcomes) * 100) : null;
+    }
+    const topSources = [...sourceCounts.entries()]
+        .map(([source, count]) => ({ source, count }))
+        .sort((a, b) => b.count - a.count)
+        .slice(0, 5);
+    const { patterns, suggestions } = derivePatterns({ slug, totalDecisions, byAction, topSources, windowDays });
+    return {
+        slug,
+        windowDays,
+        totalDecisions,
+        byAction,
+        topSources,
+        patterns,
+        suggestions,
+        generatedAt: now.toISOString(),
+    };
+}
+/**
+ * Derive plain-English patterns + tuning suggestions from the stats.
+ * Each pattern is a one-line observation; each suggestion is concrete
+ * advice the agent (or human) can act on.
+ */
+function derivePatterns(input) {
+    const patterns = [];
+    const suggestions = [];
+    if (input.totalDecisions === DORMANT_THRESHOLD) {
+        patterns.push(`No decisions recorded in the last ${input.windowDays} days.`);
+        suggestions.push('Agent is dormant. Either no signals are reaching the heartbeat, or every signal is being deduped. Check the proactive ledger directly to confirm.');
+        return { patterns, suggestions };
+    }
+    if (input.totalDecisions >= HIGH_VOLUME_THRESHOLD) {
+        patterns.push(`High decision volume: ${input.totalDecisions} decisions in ${input.windowDays} days.`);
+    }
+    const actNow = input.byAction.act_now;
+    if (actNow.withOutcomes >= 3 && (actNow.successRatePct ?? 100) < LOW_SUCCESS_THRESHOLD) {
+        patterns.push(`act_now success rate is ${actNow.successRatePct}% (${actNow.advanced}/${actNow.withOutcomes}). Low — many autonomous actions did not advance.`);
+        suggestions.push('Raise the urgency threshold for act_now (in proactive-engine.ts decideGoalAdvancement / decideDailyPlanPriority) — currently firing too aggressively. Consider requiring urgency >= 5 instead of >= 4.');
+    }
+    const queue = input.byAction.queue;
+    if (queue.withOutcomes >= 3 && (queue.successRatePct ?? 100) < LOW_SUCCESS_THRESHOLD) {
+        patterns.push(`Queued items are not landing: ${queue.advanced}/${queue.withOutcomes} advanced (${queue.successRatePct}%).`);
+        suggestions.push('Queued work is going stale. Review the work-queue dwell time — items may be timing out before the heartbeat runs them.');
+    }
+    if (queue.decided > actNow.decided * 3 && actNow.decided > 0) {
+        patterns.push(`Queue-heavy bias: ${queue.decided} queued vs ${actNow.decided} act_now. The engine is being conservative.`);
+        suggestions.push('If most queued items eventually advance manually, consider lowering the queue→act_now threshold or expanding act_now eligibility.');
+    }
+    const blockedTotal = ALL_ACTIONS.reduce((sum, a) => sum + input.byAction[a].blocked, 0);
+    if (blockedTotal >= 3) {
+        patterns.push(`${blockedTotal} decisions ended blocked (waiting on user/external).`);
+        suggestions.push('Frequent blocking suggests the agent is hitting questions only the owner can answer. Review whether earlier ask_user prompts would clear the blockage faster.');
+    }
+    const askUserCount = input.byAction.ask_user.decided;
+    if (askUserCount === 0 && actNow.decided + queue.decided >= 5) {
+        patterns.push('Zero ask_user decisions despite active autonomous work.');
+        suggestions.push('Agent never asked for owner input over the window. Either everything is unambiguously autonomous (good) or the agent is over-deciding without clarity (suspect when blocked outcomes are non-trivial).');
+    }
+    const failedTotal = ALL_ACTIONS.reduce((sum, a) => sum + input.byAction[a].failed, 0);
+    if (failedTotal >= 3) {
+        patterns.push(`${failedTotal} decisions ended in failed outcomes.`);
+        suggestions.push('Multiple failures — check cron logs for the failing job names. May indicate a tool that needs maintenance, a budget cap being hit, or a misconfigured trigger.');
+    }
+    if (patterns.length === 0) {
+        patterns.push('No notable patterns detected — calibration looks healthy for this window.');
+    }
+    return { patterns, suggestions };
+}
+// ── Markdown formatter ───────────────────────────────────────────────
+const ACTION_LABELS = {
+    act_now: 'Doing now',
+    queue: 'Queued',
+    ask_user: 'Needs you',
+    snooze: 'Snoozed',
+    ignore: 'Skipped',
+};
+export function formatReflectionReport(r) {
+    const lines = [];
+    lines.push(`# Decision reflection — ${r.slug}`);
+    lines.push('');
+    lines.push(`Generated: ${r.generatedAt}  `);
+    lines.push(`Window: last ${r.windowDays} day(s)  `);
+    lines.push(`Total decisions: **${r.totalDecisions}**`);
+    lines.push('');
+    if (r.totalDecisions === 0) {
+        lines.push('## No decisions in window');
+        lines.push('');
+        for (const p of r.patterns)
+            lines.push(`- ${p}`);
+        if (r.suggestions.length > 0) {
+            lines.push('');
+            lines.push('### Suggestions');
+            for (const s of r.suggestions)
+                lines.push(`- ${s}`);
+        }
+        return lines.join('\n');
+    }
+    lines.push('## By action');
+    lines.push('');
+    lines.push('| Action | Decided | Outcomes | Advanced | Blocked | Failed | Success |');
+    lines.push('|---|---:|---:|---:|---:|---:|---:|');
+    for (const a of ALL_ACTIONS) {
+        const b = r.byAction[a];
+        if (b.decided === 0)
+            continue;
+        const pct = b.successRatePct === null ? '—' : `${b.successRatePct}%`;
+        lines.push(`| ${ACTION_LABELS[a]} (${a}) | ${b.decided} | ${b.withOutcomes} | ${b.advanced} | ${b.blocked} | ${b.failed} | ${pct} |`);
+    }
+    if (r.topSources.length > 0) {
+        lines.push('');
+        lines.push('## Top sources');
+        for (const s of r.topSources) {
+            lines.push(`- **${s.source}**: ${s.count}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Patterns');
+    for (const p of r.patterns)
+        lines.push(`- ${p}`);
+    if (r.suggestions.length > 0) {
+        lines.push('');
+        lines.push('## Suggestions');
+        for (const s of r.suggestions)
+            lines.push(`- ${s}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Compact summary for working-memory append. Skips the full table and
+ * keeps just the patterns + suggestions so the agent's prompt doesn't
+ * get bloated with raw stats.
+ */
+export function formatReflectionSummary(r) {
+    const lines = [];
+    lines.push(`### Self-reflection (${r.generatedAt.slice(0, 10)}, last ${r.windowDays}d, ${r.totalDecisions} decisions)`);
+    lines.push('');
+    for (const p of r.patterns)
+        lines.push(`- ${p}`);
+    if (r.suggestions.length > 0) {
+        lines.push('');
+        lines.push('**Tuning suggestions:**');
+        for (const s of r.suggestions)
+            lines.push(`- ${s}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=decision-reflection.js.map

package/dist/tools/decision-reflection-tools.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Clementine TypeScript — Decision-loop reflection MCP tool.
+ *
+ * `decision_reflection` runs the analysis from agent/decision-reflection.ts
+ * for an agent and surfaces the result as a markdown report. Optionally
+ * persists the report to the agent's reflections history and/or appends
+ * a summary to their working-memory so the next heartbeat tick reads it
+ * as prompt context.
+ *
+ * Intended usage:
+ *   - Manual call by the owner ("Clementine, reflect on your week")
+ *   - Weekly cron job that calls this for each active agent
+ *   - On-demand by an agent when they suspect they're miscalibrated
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDecisionReflectionTools(server: McpServer): void;
+//# sourceMappingURL=decision-reflection-tools.d.ts.map

package/dist/tools/decision-reflection-tools.js

@@ -0,0 +1,83 @@
+/**
+ * Clementine TypeScript — Decision-loop reflection MCP tool.
+ *
+ * `decision_reflection` runs the analysis from agent/decision-reflection.ts
+ * for an agent and surfaces the result as a markdown report. Optionally
+ * persists the report to the agent's reflections history and/or appends
+ * a summary to their working-memory so the next heartbeat tick reads it
+ * as prompt context.
+ *
+ * Intended usage:
+ *   - Manual call by the owner ("Clementine, reflect on your week")
+ *   - Weekly cron job that calls this for each active agent
+ *   - On-demand by an agent when they suspect they're miscalibrated
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { analyzeAgentDecisions, formatReflectionReport, formatReflectionSummary, } from '../agent/decision-reflection.js';
+import { ACTIVE_AGENT_SLUG, AGENTS_DIR, logger, textResult } from './shared.js';
+function reflectionsDir(slug) {
+    return path.join(AGENTS_DIR, slug, 'reflections');
+}
+function workingMemoryPath(slug) {
+    return path.join(AGENTS_DIR, slug, 'working-memory.md');
+}
+function todayStamp() {
+    return new Date().toISOString().slice(0, 10);
+}
+/** Append a summary block to working-memory.md, creating the file if needed. */
+function appendToWorkingMemory(slug, summary) {
+    const file = workingMemoryPath(slug);
+    mkdirSync(path.dirname(file), { recursive: true });
+    let existing = '';
+    if (existsSync(file))
+        existing = readFileSync(file, 'utf-8');
+    const appended = (existing.endsWith('\n') || existing === '' ? existing : existing + '\n')
+        + '\n'
+        + summary
+        + '\n';
+    writeFileSync(file, appended);
+}
+export function registerDecisionReflectionTools(server) {
+    server.tool('decision_reflection', 'Run a self-reflection on your recent autonomous decisions: read the proactive ledger, compute success rates per action type, identify miscalibration patterns, and surface concrete tuning suggestions. Use to spot when you are over-acting, under-acting, or going dormant. Optionally writes a summary to working-memory so your next heartbeat tick reads it as context.', {
+        slug: z.string().optional().describe('Agent slug to reflect on. Defaults to the calling agent (or "clementine" for the daemon).'),
+        window_days: z.number().optional().describe('Window in days to analyze. Default 7. Range 1-90.'),
+        save_to_history: z.boolean().optional().describe('Persist the full report to vault/00-System/agents/<slug>/reflections/<date>.md (default true).'),
+        append_to_memory: z.boolean().optional().describe('Append a compact summary to working-memory.md so the next tick reads it (default false). Be deliberate — repeated appends bloat the prompt.'),
+    }, async ({ slug, window_days, save_to_history, append_to_memory }) => {
+        const targetSlug = slug || ACTIVE_AGENT_SLUG || 'clementine';
+        const window = Math.max(1, Math.min(90, typeof window_days === 'number' ? window_days : 7));
+        const persistHistory = save_to_history !== false; // default true
+        const updateMemory = append_to_memory === true; // default false (explicit opt-in)
+        const reflection = analyzeAgentDecisions(targetSlug, window);
+        const report = formatReflectionReport(reflection);
+        const writes = [];
+        if (persistHistory) {
+            try {
+                const dir = reflectionsDir(targetSlug);
+                mkdirSync(dir, { recursive: true });
+                const file = path.join(dir, `${todayStamp()}.md`);
+                writeFileSync(file, report);
+                writes.push(`Saved to ${file}`);
+            }
+            catch (err) {
+                logger.warn({ err, slug: targetSlug }, 'Failed to save reflection history');
+                writes.push(`Failed to save history: ${String(err).slice(0, 200)}`);
+            }
+        }
+        if (updateMemory) {
+            try {
+                appendToWorkingMemory(targetSlug, formatReflectionSummary(reflection));
+                writes.push(`Appended summary to ${workingMemoryPath(targetSlug)}`);
+            }
+            catch (err) {
+                logger.warn({ err, slug: targetSlug }, 'Failed to append reflection to working-memory');
+                writes.push(`Failed to update working-memory: ${String(err).slice(0, 200)}`);
+            }
+        }
+        const footer = writes.length > 0 ? '\n\n---\n' + writes.map((w) => `- ${w}`).join('\n') : '';
+        return textResult(report + footer);
+    });
+}
+//# sourceMappingURL=decision-reflection-tools.js.map

package/dist/tools/mcp-server.js

@@ -28,6 +28,7 @@ import { registerArtifactTools } from './artifact-tools.js';
 import { registerBrainTools } from './brain-tools.js';
 import { registerAgentHeartbeatTools } from './agent-heartbeat-tools.js';
 import { registerBackgroundTaskTools } from './background-task-tools.js';
+import { registerDecisionReflectionTools } from './decision-reflection-tools.js';
 // ── Server ──────────────────────────────────────────────────────────────
 const serverName = (env['ASSISTANT_NAME'] ?? 'Clementine').toLowerCase() + '-tools';
 const server = new McpServer({ name: serverName, version: '1.0.0' });
@@ -43,6 +44,7 @@ registerArtifactTools(server);
 registerBrainTools(server);
 registerAgentHeartbeatTools(server);
 registerBackgroundTaskTools(server);
+registerDecisionReflectionTools(server);
 // ── Main ────────────────────────────────────────────────────────────────
 async function main() {
     // Initialize memory store and run full sync on startup

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.0.88",
+  "version": "1.0.89",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",

package/vault/00-System/CRON.md

@@ -37,6 +37,21 @@ jobs:
       4. Write a brief summary of the day in today's daily note under ## Summary
     tier: 1
     enabled: true
+
+  - name: weekly-decision-reflection
+    schedule: "0 9 * * 0"
+    prompt: >
+      Run a self-reflection on the past week's autonomous decisions.
+      1. Call `decision_reflection` with window_days=7, save_to_history=true, append_to_memory=true.
+         This reads the proactive ledger, computes per-action success rates, identifies
+         miscalibration patterns, and writes a tuning note to your working-memory so the
+         next heartbeat tick reads it as context.
+      2. For each specialist on the team (use `team_list` to enumerate), also run
+         `decision_reflection` with their slug, save_to_history=true, append_to_memory=true.
+      3. Briefly summarize in today's daily note under "## Decision reflection" — list each
+         agent's headline pattern (e.g., "Ross: act_now success 33%, raise threshold").
+    tier: 1
+    enabled: true
 tags:
   - system
   - cron
@@ -53,6 +68,7 @@ Scheduled tasks that run automatically at specific times. Edit the frontmatter a
 | morning-briefing | 8:00 AM daily | Comprehensive morning briefing |
 | weekly-review | 6:00 PM Fridays | Weekly summary + planning |
 | daily-memory-cleanup | 10:00 PM daily | Promote daily facts to long-term memory |
+| weekly-decision-reflection | 9:00 AM Sundays | Per-agent self-tuning from proactive ledger |
 
 ## Schedule Syntax