clementine-agent 1.1.19 → 1.1.20

package/dist/agent/self-improve.js

@@ -23,6 +23,7 @@ const DEFAULT_CONFIG = {
     iterationBudgetMs: 300_000, // 5 min
     maxDurationMs: 3_600_000, // 1 hour
     acceptThreshold: 0.7,
+    surfaceThreshold: 0.85,
     plateauLimit: 3,
     // 'source' deprecated — self-improvement produces data, not engine TS edits.
     // 'advisor-rule' writes YAML to ~/.clementine/advisor-rules/user/.
@@ -300,12 +301,25 @@ export class SelfImproveLoop {
                     const score = evaluation?.score ?? 0;
                     const normalizedScore = score / 10; // Convert 0-10 to 0-1
                     const accepted = normalizedScore >= this.config.acceptThreshold;
+                    // Surface gate: even when accepted, only score >= surfaceThreshold
+                    // reaches the user's pending-changes inbox. Below that floor we
+                    // keep the experiment in the trend log but don't ping the user.
+                    const surfaceFloor = this.config.surfaceThreshold ?? this.config.acceptThreshold;
+                    const surfaced = normalizedScore >= surfaceFloor;
                     const priorScores = history
                         .filter(e => e.area === proposal.area && e.target === proposal.target && e.score > 0)
                         .map(e => e.score);
                     const baselineScore = priorScores.length > 0
                         ? priorScores.reduce((a, b) => a + b, 0) / priorScores.length
                         : 0.5;
+                    const initialStatus = accepted
+                        ? (surfaced ? 'pending' : 'unsurfaced')
+                        : 'denied';
+                    const reason = accepted
+                        ? (surfaced
+                            ? `Score ${score}/10 exceeds surface threshold — pending approval`
+                            : `Score ${score}/10 accepted but below surface floor (${surfaceFloor * 10}/10) — kept in trend log only`)
+                        : `Score ${score}/10 below accept threshold (${this.config.acceptThreshold * 10}/10)`;
                     const experiment = {
                         id,
                         iteration: i,
@@ -319,17 +333,19 @@ export class SelfImproveLoop {
                         baselineScore,
                         score: normalizedScore,
                         accepted,
-                        approvalStatus: accepted ? 'pending' : 'denied',
-                        reason: accepted
-                            ? `Score ${score}/10 exceeds threshold — pending approval`
-                            : `Score ${score}/10 below threshold (${this.config.acceptThreshold * 10}/10)`,
+                        approvalStatus: initialStatus,
+                        reason,
                     };
                     // Step 7: Log
                     this.appendExperimentLog(experiment);
                     history.push(experiment);
                     state.totalExperiments++;
-                    // Step 6: Gate — save pending change + notify (tiered by risk)
-                    if (accepted) {
+                    if (accepted && !surfaced) {
+                        logger.info({ id, area: proposal.area, target: proposal.target, score: score, surfaceFloor: surfaceFloor * 10 }, 'Proposal accepted but unsurfaced — below noise floor, not added to review queue');
+                    }
+                    // Step 6: Gate — save pending change + notify (tiered by risk).
+                    // Only proposals that ALSO clear the surface floor reach the inbox.
+                    if (accepted && surfaced) {
                         const risk = classifyRisk(proposal.area);
                         if (this.config.autoApply && risk === 'low') {
                             // Low-risk + auto-apply enabled: apply immediately without approval

package/dist/cli/index.js

@@ -2090,6 +2090,169 @@ configCmd
         console.error(`  Failed to open editor: ${editor}`);
     }
 });
+// ── Agent commands ──────────────────────────────────────────────────
+const agentCmd = program
+    .command('agent')
+    .description('Hire, list, and manage specialist agents');
+agentCmd
+    .command('list')
+    .description('List all agents with status and tier')
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async (opts) => {
+    const BOLD = '\x1b[1m';
+    const DIM = '\x1b[0;90m';
+    const GREEN = '\x1b[0;32m';
+    const YELLOW = '\x1b[0;33m';
+    const RED = '\x1b[0;31m';
+    const RESET = '\x1b[0m';
+    try {
+        const { AgentManager } = await import('../agent/agent-manager.js');
+        const AGENTS_DIR = path.join(BASE_DIR, 'agents');
+        const mgr = new AgentManager(AGENTS_DIR);
+        const agents = mgr.listAll();
+        if (opts.json) {
+            console.log(JSON.stringify(agents.map(a => ({
+                slug: a.slug, name: a.name, status: a.status, tier: a.tier,
+                description: a.description, hasChannel: !!a.team?.channelName,
+            })), null, 2));
+            return;
+        }
+        if (agents.length === 0) {
+            console.log(`\n  No agents found in ${AGENTS_DIR}.`);
+            console.log(`  Hire one: ${BOLD}clementine agent new <slug>${RESET}\n`);
+            return;
+        }
+        console.log();
+        console.log(`  ${BOLD}${'SLUG'.padEnd(28)}${'NAME'.padEnd(24)}${'STATUS'.padEnd(12)}${'TIER'.padEnd(6)}${RESET}`);
+        console.log(`  ${DIM}${'─'.repeat(70)}${RESET}`);
+        for (const a of agents) {
+            const statusColor = a.status === 'active' ? GREEN : a.status === 'paused' ? YELLOW : RED;
+            const statusStr = `${statusColor}${(a.status ?? 'active').padEnd(10)}${RESET}`;
+            console.log(`  ${a.slug.padEnd(28)}${(a.name ?? '').slice(0, 22).padEnd(24)}${statusStr}  ${String(a.tier).padEnd(6)}`);
+        }
+        console.log();
+    }
+    catch (err) {
+        console.error(`  Error listing agents: ${err}`);
+        process.exit(1);
+    }
+});
+agentCmd
+    .command('new <slug>')
+    .description('Scaffold a new agent at agents/<slug>/agent.md (does not overwrite)')
+    .option('-n, --name <name>', 'Display name (default: title-case of slug)')
+    .option('-d, --description <text>', 'One-line description of what the agent does')
+    .option('-r, --role <role>', 'Role template — auto-scaffolds CRON.md / PLAYBOOK.md (sdr, researcher)')
+    .option('-t, --tier <tier>', 'Security tier — 1 = vault-only, 2 = bash/git allowed', '1')
+    .option('-m, --model <model>', 'Default model (sonnet, haiku, opus). Inherits global default if omitted.')
+    .option('--channel <name>', 'Discord/Slack channel name the agent listens in (enables team mode)')
+    .action(async (slug, opts) => {
+    const BOLD = '\x1b[1m';
+    const DIM = '\x1b[0;90m';
+    const GREEN = '\x1b[0;32m';
+    const RED = '\x1b[0;31m';
+    const RESET = '\x1b[0m';
+    // Validate slug — lowercase, dashes, alphanumeric, no leading/trailing dash.
+    if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(slug) || slug.length < 3) {
+        console.error(`  ${RED}Invalid slug${RESET}: must be 3+ chars, lowercase letters/digits/dashes, no leading/trailing dash. Got: "${slug}"`);
+        process.exit(1);
+    }
+    if (slug === 'clementine') {
+        console.error(`  ${RED}Reserved slug${RESET}: "clementine" is the master assistant. Pick a different name.`);
+        process.exit(1);
+    }
+    const tier = Math.max(1, Math.min(2, parseInt(opts.tier ?? '1', 10) || 1));
+    const name = opts.name ?? slug.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+    const description = opts.description ?? `${name} — specialist agent.`;
+    try {
+        const { AgentManager } = await import('../agent/agent-manager.js');
+        const AGENTS_DIR = path.join(BASE_DIR, 'agents');
+        const mgr = new AgentManager(AGENTS_DIR);
+        // Refuse if already taken (createAgent throws but we want a friendly error)
+        if (mgr.get(slug)) {
+            console.error(`  ${RED}Agent "${slug}" already exists${RESET}. Edit ${path.join(AGENTS_DIR, slug, 'agent.md')} or pick a different slug.`);
+            process.exit(1);
+        }
+        const config = {
+            name,
+            description,
+            tier,
+        };
+        if (opts.model)
+            config.model = opts.model;
+        if (opts.channel)
+            config.channelName = opts.channel;
+        if (opts.role)
+            config.role = opts.role;
+        const profile = mgr.createAgent(config);
+        const agentMdPath = path.join(profile.agentDir ?? path.join(AGENTS_DIR, slug), 'agent.md');
+        console.log();
+        console.log(`  ${GREEN}✓${RESET} Created agent ${BOLD}${profile.name}${RESET} (${profile.slug})`);
+        console.log(`  ${DIM}File: ${agentMdPath}${RESET}`);
+        if (opts.role) {
+            console.log(`  ${DIM}Role scaffold "${opts.role}" wrote CRON.md / PLAYBOOK.md / SEQUENCES.md if applicable.${RESET}`);
+        }
+        console.log();
+        console.log(`  Next steps:`);
+        console.log(`    1. Edit ${BOLD}agent.md${RESET} to refine personality / standing instructions`);
+        if (!opts.channel) {
+            console.log(`    2. Add a ${BOLD}channelName${RESET} (and DISCORD/SLACK token via 'clementine config set') to give them their own bot`);
+        }
+        console.log(`    3. Edit ${BOLD}~/.clementine/agents/${slug}/CRON.md${RESET} to schedule autonomous work`);
+        console.log(`    4. Restart the daemon: ${BOLD}clementine restart${RESET}`);
+        console.log();
+    }
+    catch (err) {
+        console.error(`  ${RED}Failed to create agent${RESET}: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+});
+agentCmd
+    .command('show <slug>')
+    .description('Show an agent\'s file path and parsed profile summary')
+    .action(async (slug) => {
+    const BOLD = '\x1b[1m';
+    const DIM = '\x1b[0;90m';
+    const RED = '\x1b[0;31m';
+    const RESET = '\x1b[0m';
+    try {
+        const { AgentManager } = await import('../agent/agent-manager.js');
+        const AGENTS_DIR = path.join(BASE_DIR, 'agents');
+        const mgr = new AgentManager(AGENTS_DIR);
+        const profile = mgr.get(slug);
+        if (!profile) {
+            console.error(`  ${RED}Agent "${slug}" not found${RESET}.`);
+            console.error(`  List agents: ${BOLD}clementine agent list${RESET}`);
+            process.exit(1);
+        }
+        const agentMdPath = path.join(profile.agentDir ?? path.join(AGENTS_DIR, slug), 'agent.md');
+        console.log();
+        console.log(`  ${BOLD}${profile.name}${RESET}  ${DIM}(${profile.slug})${RESET}`);
+        console.log(`  ${DIM}${agentMdPath}${RESET}`);
+        console.log();
+        console.log(`  Status:       ${profile.status ?? 'active'}`);
+        console.log(`  Tier:         ${profile.tier}`);
+        if (profile.model)
+            console.log(`  Model:        ${profile.model}`);
+        console.log(`  Description:  ${profile.description || DIM + '(none)' + RESET}`);
+        if (profile.team?.channelName) {
+            const ch = Array.isArray(profile.team.channelName) ? profile.team.channelName.join(', ') : profile.team.channelName;
+            console.log(`  Channel:      ${ch}`);
+        }
+        if (profile.activeHours) {
+            console.log(`  Active hours: ${profile.activeHours.start.toFixed(2)}–${profile.activeHours.end.toFixed(2)} (decimal hours)`);
+        }
+        if (profile.budgetMonthlyCents != null && profile.budgetMonthlyCents > 0) {
+            console.log(`  Budget/mo:    $${(profile.budgetMonthlyCents / 100).toFixed(2)}`);
+        }
+        console.log(`  Strict mem:   ${profile.strictMemoryIsolation === false ? 'no (soft boost)' : 'yes (default)'}`);
+        console.log();
+    }
+    catch (err) {
+        console.error(`  Error reading agent: ${err}`);
+        process.exit(1);
+    }
+});
 // ── Memory commands ─────────────────────────────────────────────────
 const memoryCmd = program
     .command('memory')

package/dist/tools/memory-tools.js

@@ -305,7 +305,7 @@ export function registerMemoryTools(server) {
         return textResult(results.join('\n'));
     });
     // ── 4. memory_recall ───────────────────────────────────────────────────
-    server.tool('memory_recall', getToolDescription('memory_recall') ?? 'Context retrieval combining FTS5 relevance + recency search. Better than memory_search for finding related content by meaning. Optional category/topic filters narrow results.', {
+    server.tool('memory_recall', getToolDescription('memory_recall') ?? 'Context retrieval combining FTS5 relevance + recency search, scoped to your memory + global. For cross-agent synthesis use brain_recall.', {
         query: z.string().describe('Natural language search query'),
         category: z.enum(['facts', 'events', 'discoveries', 'preferences', 'advice']).optional().describe('Filter by category'),
         topic: z.string().optional().describe('Filter by topic'),
@@ -321,11 +321,56 @@ export function registerMemoryTools(server) {
             store.recordAccess(chunkIds);
         const lines = results.map(r => {
             const label = `[${r.matchType}]`;
+            const agentTag = r.agentSlug ? ` [agent: ${r.agentSlug}]` : '';
             const preview = r.content.slice(0, 300).replace(/\n/g, ' ');
-            return `**${r.sourceFile} > ${r.section}** ${label} (score: ${r.score.toFixed(3)})\n${preview}\n`;
+            return `**${r.sourceFile} > ${r.section}** ${label}${agentTag} (score: ${r.score.toFixed(3)})\n${preview}\n`;
         });
         return textResult(lines.join('\n'));
     });
+    // ── 4b. brain_recall ──────────────────────────────────────────────────
+    //
+    // Cross-agent unified recall. Differs from memory_recall in two ways:
+    //   1. No agentSlug scope — pulls from every agent's memory + global.
+    //   2. Always tags each result with [agent: <slug>] so the caller can
+    //      see provenance (which agent's memory the chunk came from).
+    //
+    // Intended caller: Clementine herself. Specialist agents normally stay in
+    // memory_recall (which respects strict isolation). brain_recall is the
+    // "single brain" view that lets the master assistant synthesize across
+    // the whole team.
+    server.tool('brain_recall', getToolDescription('brain_recall') ?? 'Cross-agent unified recall — searches across all agents with source-agent attribution. Use for synthesis questions or when you need the full picture, not just your own scope.', {
+        query: z.string().describe('Natural language query — what to find across all agents'),
+        category: z.enum(['facts', 'events', 'discoveries', 'preferences', 'advice']).optional().describe('Filter by category'),
+        topic: z.string().optional().describe('Filter by topic'),
+        limit: z.number().optional().describe('Max results across all agents (default 12)'),
+    }, async ({ query, category, topic, limit }) => {
+        const store = await getStore();
+        // Intentionally omit agentSlug — we want the unscoped, cross-agent view.
+        const results = store.searchContext(query, { category, topic, limit: limit ?? 12 });
+        if (!results.length) {
+            return textResult(`No results for: ${query}`);
+        }
+        const chunkIds = results.map(r => r.chunkId).filter(Boolean);
+        if (chunkIds.length)
+            store.recordAccess(chunkIds);
+        // Group attribution counts so the agent gets a quick summary of the spread.
+        const perAgent = new Map();
+        for (const r of results) {
+            const key = r.agentSlug ?? 'global';
+            perAgent.set(key, (perAgent.get(key) ?? 0) + 1);
+        }
+        const spread = Array.from(perAgent.entries())
+            .sort((a, b) => b[1] - a[1])
+            .map(([slug, n]) => `${slug}:${n}`)
+            .join(', ');
+        const lines = results.map(r => {
+            const agent = r.agentSlug ?? 'global';
+            const label = `[${r.matchType}]`;
+            const preview = r.content.slice(0, 300).replace(/\n/g, ' ');
+            return `**${r.sourceFile} > ${r.section}** ${label} [agent: ${agent}] (score: ${r.score.toFixed(3)})\n${preview}\n`;
+        });
+        return textResult(`Cross-agent spread: ${spread}\n\n${lines.join('\n')}`);
+    });
     // ── 10. memory_connections ─────────────────────────────────────────────
     server.tool('memory_connections', 'Query the wikilink graph — find all notes connected to/from a given note.', {
         note_name: z.string().describe('Note name (without .md) to find connections for'),

package/dist/tools/tool-meta.js

@@ -22,10 +22,15 @@ const TOOL_META = {
         paginationNote: 'Default limit is 20 results. For broad queries, start with limit=5 and increase only if needed.',
     },
     memory_recall: {
-        description: 'Context retrieval combining text relevance + recency. Better than memory_search for finding related content — it considers how recently notes were updated. Use this as your default "what do I know about X" tool.',
-        exampleUsage: 'Use before responding to questions about people, projects, or topics the user has discussed before.',
+        description: 'Context retrieval combining text relevance + recency, scoped to YOUR memory + global memory. Best as your default "what do I know about X" tool when the question lives in your domain. For cross-agent synthesis (what your team as a whole knows), use brain_recall instead.',
+        exampleUsage: 'Use before responding to questions about people, projects, or topics the user has discussed with you before.',
         returnHint: 'Ranked chunks with source file, category, and content preview.',
     },
+    brain_recall: {
+        description: 'CROSS-AGENT unified recall — searches the entire memory store across YOU and every team agent, with source-agent attribution per result. Use for synthesis questions ("what does my team know about X?", "have any of my agents discussed Y?"), or whenever you need the full picture instead of just your own scope. Specialist agents normally stay in memory_recall (which respects their isolation); brain_recall is the single-brain view, primarily for Clementine.',
+        exampleUsage: 'When the user asks "what have we collectively learned about Acme this quarter", brain_recall returns chunks from every agent that touched the topic.',
+        returnHint: 'Ranked chunks tagged [agent: <slug>] or [agent: global], plus source file and content preview.',
+    },
     memory_read: {
         description: "Read a note from the Obsidian vault. Shortcuts: 'today' (daily note), 'yesterday', 'memory' (MEMORY.md), 'tasks' (TASKS.md), 'heartbeat', 'cron', 'soul'. Or pass a relative path like '03-Projects/my-project.md'.",
         exampleUsage: "memory_read('today') to check what happened today before making plans.",

package/dist/types.d.ts

@@ -508,7 +508,7 @@ export interface SelfImproveExperiment {
     baselineScore: number;
     score: number;
     accepted: boolean;
-    approvalStatus: 'pending' | 'approved' | 'denied' | 'expired';
+    approvalStatus: 'pending' | 'approved' | 'denied' | 'expired' | 'unsurfaced';
     reason: string;
     error?: string;
 }
@@ -548,6 +548,13 @@ export interface SelfImproveConfig {
     iterationBudgetMs: number;
     maxDurationMs: number;
     acceptThreshold: number;
+    /**
+     * Default: 0.85. Stricter floor for what reaches the user's pending-changes
+     * inbox. Proposals scoring >= acceptThreshold but < surfaceThreshold are
+     * marked 'unsurfaced' — kept in the experiment log for trend analysis but
+     * NOT written to PENDING_DIR. Cuts noise without losing signal data.
+     */
+    surfaceThreshold?: number;
     plateauLimit: number;
     areas: ('soul' | 'cron' | 'workflow' | 'memory' | 'agent' | 'source' | 'communication' | 'goal' | 'advisor-rule' | 'prompt-override')[];
     /** Enable tiered auto-apply: low-risk changes apply without approval. Default: false. */

package/package.json

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