clementine-agent 1.0.6 → 1.0.8

package/README.md

@@ -7,11 +7,15 @@
  ╚═════╝╚══════╝╚══════╝╚═╝     ╚═╝╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═╝╚═╝  ╚═══╝╚══════╝
 ```
 
-A persistent, ever-learning personal AI assistant that runs as a background daemon on macOS.
+A persistent, ever-learning personal AI assistant that runs as a background daemon on macOS and Linux.
 Built on the [Claude Code SDK](https://docs.anthropic.com/en/docs/claude-code-sdk), Obsidian-compatible vault, and SQLite FTS5.
 
 Connects to Discord, Slack, Telegram, WhatsApp, and webhooks. Remembers everything. Runs 24/7.
 
+**Requirements:** Node.js 20+ (22 recommended) · [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) authenticated · macOS or Linux.
+
+**Contents:** [How it works](#how-it-works) · [Install](#install-recommended) · [Architecture](#architecture) · [CLI](#cli-reference) · [Configuration](#configuration) · [Channels](#channels) · [Agents & Teams](#agents--teams) · [Cron](#scheduled-tasks--cron-jobs) · [Unleashed mode](#unleashed-mode) · [Self-improvement](#self-improvement) · [Vault](#vault) · [Development](#development) · [Troubleshooting](#troubleshooting)
+
 ---
 
 ## How it works
@@ -63,45 +67,55 @@ The result: Clementine gets better the more you talk to it.
 
 ---
 
-## Prerequisites
+## Install (recommended)
 
-- **Node.js 20-24 LTS** — `nvm install 22`
-- **Claude Code CLI** — already installed if you're reading this in Claude Code
+Runtime: **Node.js 22 (recommended) or Node.js 20+**.
 
-## Quick start
-
-**Option A — npm (recommended):**
 ```bash
-npm install -g clementine-agent
+npm install -g clementine-agent@latest
 clementine setup
 ```
 
-**Option B — from source (for development):**
+After setup:
+
 ```bash
-git clone https://github.com/Natebreynolds/Clementine-AI-Assistant.git clementine
-cd clementine
-bash install.sh
+clementine launch         # start as background daemon
+clementine status         # verify it's running
+clementine dashboard      # open the web command center
 ```
 
-The install script handles everything: system dependencies (redis, libomp, build tools), npm packages, TypeScript build, global CLI install, and launches the setup wizard. Safe to re-run — skips anything already installed.
+Already installed? Update in place with `clementine update`.
 
-The setup wizard auto-generates a Discord bot invite URL from your token and offers to open it in your browser — no need to visit the Developer Portal manually.
+### Troubleshooting
 
-After setup:
+**`EACCES: permission denied` on `npm install -g`.** Your Node was installed system-wide (`/usr/local/lib/...`) and npm can't write there without sudo. Fix it once, permanently:
 
 ```bash
-clementine launch         # start as background daemon
-clementine status         # verify it's running
-clementine dashboard      # open the web command center
+mkdir -p ~/.npm-global
+npm config set prefix ~/.npm-global
+echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc && source ~/.zshrc
+npm install -g clementine-agent@latest
 ```
 
-Already have it? Update in place:
+Or install Node via [nvm](https://github.com/nvm-sh/nvm) — user-scoped by default, no permission issues ever.
+
+**`clementine: command not found` after install succeeded.** Run `npm config get prefix` — its `/bin` directory needs to be on your `PATH`. Add `export PATH="$(npm config get prefix)/bin:$PATH"` to your shell profile.
 
+**Node version too old.** Install via nvm:
 ```bash
-clementine update
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
+nvm install 22
+```
+
+### Install from source (for development)
+
+```bash
+git clone https://github.com/Natebreynolds/Clementine-AI-Assistant.git clementine
+cd clementine
+bash install.sh
 ```
 
-That's it. Clementine is now running, connected to your configured channels, and learning.
+Handles system dependencies (redis, libomp, build tools), npm packages, TypeScript build, global CLI install, and launches the setup wizard. Safe to re-run.
 
 ---
 
@@ -728,15 +742,6 @@ Key system files:
 
 ---
 
-## Requirements
-
-- **Node.js 20-24 LTS** (for `--import` loader and `cpSync`)
-- **macOS** (Keychain integration, LaunchAgent — works on Linux without these)
-- **Claude Code CLI** installed and authenticated (`npm install -g @anthropic-ai/claude-code && claude login`)
-- No API key needed — authentication is handled by the Claude Code CLI
-
----
-
 ## Development
 
 ```bash

package/dist/agent/assistant.d.ts

@@ -37,6 +37,7 @@ export declare class PersonalAssistant {
     private sessionTimestamps;
     private lastExchanges;
     private pendingContext;
+    private saveSessionsTimer?;
     private restoredSessions;
     private profileManager;
     private promptCache;
@@ -79,7 +80,15 @@ export declare class PersonalAssistant {
     injectPendingContext(sessionKey: string, userPrompt: string, result: string): void;
     private initMemoryStore;
     private loadSessions;
+    /**
+     * Schedule a debounced session persist. Multiple calls within 500ms collapse
+     * into a single write, eliminating synchronous disk I/O from the per-turn
+     * hot path. On shutdown, call flushSessions() to write any pending state.
+     */
     private saveSessions;
+    /** Flush any pending debounced save synchronously. Call on shutdown. */
+    flushSessions(): void;
+    private saveSessionsNow;
     getExchangeCount(sessionKey: string): number;
     getMemoryChunkCount(): number;
     private buildSystemPrompt;

package/dist/agent/assistant.js

@@ -532,6 +532,7 @@ export class PersonalAssistant {
     sessionTimestamps = new Map();
     lastExchanges = new Map();
     pendingContext = new Map();
+    saveSessionsTimer;
     restoredSessions = new Set();
     profileManager;
     promptCache;
@@ -695,7 +696,28 @@ export class PersonalAssistant {
             logger.warn({ err }, 'Session restore failed — starting fresh');
         }
     }
+    /**
+     * Schedule a debounced session persist. Multiple calls within 500ms collapse
+     * into a single write, eliminating synchronous disk I/O from the per-turn
+     * hot path. On shutdown, call flushSessions() to write any pending state.
+     */
     saveSessions() {
+        if (this.saveSessionsTimer)
+            return;
+        this.saveSessionsTimer = setTimeout(() => {
+            this.saveSessionsTimer = undefined;
+            this.saveSessionsNow();
+        }, 500);
+    }
+    /** Flush any pending debounced save synchronously. Call on shutdown. */
+    flushSessions() {
+        if (this.saveSessionsTimer) {
+            clearTimeout(this.saveSessionsTimer);
+            this.saveSessionsTimer = undefined;
+        }
+        this.saveSessionsNow();
+    }
+    saveSessionsNow() {
         try {
             const data = {};
             // Collect all keys that have any state worth saving
@@ -1301,7 +1323,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
         // terminal, so 'auto' mode (which requires plan support + human approval) doesn't apply.
         const effectivePermissionMode = 'bypassPermissions';
         return {
-            systemPrompt: stripLoneSurrogates(fullSystemPrompt),
+            systemPrompt: fullSystemPrompt,
             model: resolvedModel,
             ...(fallback ? { fallbackModel: fallback } : {}),
             permissionMode: effectivePermissionMode,
@@ -1562,10 +1584,8 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
             this.exchangeCounts.set(key, 0);
             sessionRotated = true;
         }
-        // Sanitize lone Unicode surrogates before any JSON serialization to the API.
-        // Lone surrogates (U+D800–U+DFFF) are valid JS strings but invalid JSON,
-        // causing 400 "no low surrogate in string" errors from the Claude API.
-        let effectivePrompt = stripLoneSurrogates(text);
+        // Lone-surrogate sanitization happens at the SDK boundary (see query() wrapper).
+        let effectivePrompt = text;
         // If session rotated, use instant local summary + handoff + kick off LLM summary in background
         if (sessionRotated && key) {
             const summary = this.buildLocalSummary(key);
@@ -1684,7 +1704,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
         const effectiveMaxTurns = maxTurns;
         const CHAT_TIMEOUT_MS = 30 * 60 * 1000;
         const guard = new StallGuard();
-        let [responseText, sessionId] = await this.runQuery(stripLoneSurrogates(effectivePrompt), key, onText, model, profile, securityAnnotation, effectiveMaxTurns, projectOverride, onToolActivity, verboseLevel, abortController, guard, CHAT_TIMEOUT_MS, intent);
+        let [responseText, sessionId] = await this.runQuery(effectivePrompt, key, onText, model, profile, securityAnnotation, effectiveMaxTurns, projectOverride, onToolActivity, verboseLevel, abortController, guard, CHAT_TIMEOUT_MS, intent);
         // If we got a context-length / prompt-too-long error, retry with a fresh session
         const errLower = responseText.toLowerCase();
         const isContextOverflow = errLower.includes('prompt is too long') ||
@@ -1695,7 +1715,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
             logger.warn({ sessionKey: key }, 'Context overflow detected — rotating session');
             this.sessions.delete(key);
             this.exchangeCounts.set(key, 0);
-            let retryPrompt = stripLoneSurrogates(text);
+            let retryPrompt = text;
             const summary = await this.summarizeSession(key);
             if (summary) {
                 retryPrompt =
@@ -1703,7 +1723,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
                         `Here is a summary of what we were discussing:\n${summary}]\n\n` +
                         `IMPORTANT: The previous attempt overflowed the context window, likely from large tool responses. ` +
                         `If this task involves pulling data for multiple entities, delegate each to a sub-agent using the Agent tool ` +
-                        `instead of calling data-heavy tools directly.\n\n${stripLoneSurrogates(text)}`;
+                        `instead of calling data-heavy tools directly.\n\n${text}`;
             }
             [responseText, sessionId] = await this.runQuery(retryPrompt, key, onText, model, profile, securityAnnotation, maxTurns, undefined, onToolActivity, verboseLevel, abortController);
         }
@@ -1715,7 +1735,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
             this.exchangeCounts.set(key, (this.exchangeCounts.get(key) ?? 0) + 1);
             this.sessionTimestamps.set(key, new Date());
             const history = this.lastExchanges.get(key) ?? [];
-            history.push({ user: stripLoneSurrogates(text), assistant: responseText });
+            history.push({ user: text, assistant: responseText });
             if (history.length > SESSION_EXCHANGE_HISTORY_SIZE) {
                 this.lastExchanges.set(key, history.slice(-SESSION_EXCHANGE_HISTORY_SIZE));
             }
@@ -1734,7 +1754,7 @@ You have a cost budget per message — not a hard turn limit. Work until the tas
         // Save transcript turns
         if (key && this.memoryStore) {
             try {
-                this.memoryStore.saveTurn(key, 'user', stripLoneSurrogates(text));
+                this.memoryStore.saveTurn(key, 'user', text);
                 this.memoryStore.saveTurn(key, 'assistant', responseText, model ?? MODEL);
             }
             catch (err) {

package/dist/gateway/heartbeat-scheduler.d.ts

@@ -46,15 +46,25 @@ export declare class HeartbeatScheduler {
      * agent knows what happened since the last beat.
      */
     private getRecentActivitySummary;
+    /**
+     * Read and parse all goal JSON files from GOALS_DIR once. Callers that
+     * need filtered subsets (active only, priority-based, etc.) do their own
+     * filtering over the returned array. Used by heartbeatTick to avoid
+     * repeating the readdirSync+readFileSync pass for every goal-consuming
+     * method.
+     */
+    static loadAllGoals(): Array<any>;
     /**
      * Load active goal summaries for injection into heartbeat prompts.
-     * Returns null if no active goals exist.
+     * Returns null if no active goals exist. Pass `preloadedGoals` to reuse
+     * an already-read goal list and skip disk I/O.
      */
-    static loadGoalSummary(): string | null;
+    static loadGoalSummary(preloadedGoals?: Array<any>): string | null;
     /**
      * Enrich top active goals with relevant memory snippets.
      * Searches FTS5 memory for each goal's title+description to surface
      * recent conversations and facts the heartbeat agent can act on.
+     * Pass `preloadedGoals` to reuse an already-read goal list.
      */
     private enrichGoalsWithMemory;
     /**

package/dist/gateway/heartbeat-scheduler.js

@@ -312,16 +312,17 @@ export class HeartbeatScheduler {
         if (activitySummary) {
             changesSummary += `\n\nRecent activity:\n${activitySummary}`;
         }
+        // Load all goals once for this tick — loadGoalSummary, enrichGoalsWithMemory,
+        // and advanceGoals all read the same set from disk. One readdirSync + N
+        // readFileSyncs, reused by each consumer below.
+        const tickGoals = HeartbeatScheduler.loadAllGoals();
         // Inject active goal summaries so the heartbeat can flag goals needing attention
-        const goalSummary = HeartbeatScheduler.loadGoalSummary();
+        const goalSummary = HeartbeatScheduler.loadGoalSummary(tickGoals);
         if (goalSummary) {
             changesSummary += `\n\n${goalSummary}`;
         }
-        // Enrich active goals with relevant memory snippets
-        const goalMemoryContext = this.enrichGoalsWithMemory();
-        if (goalMemoryContext) {
-            changesSummary += `\n\n${goalMemoryContext}`;
-        }
+        // Note: enrichGoalsWithMemory() runs below, inside the non-silent branch —
+        // silent heartbeats discard the result, so we skip the work entirely.
         // Inject daily plan summary if available
         try {
             const todayPlan = dailyPlanner?.getPlan();
@@ -391,11 +392,17 @@ export class HeartbeatScheduler {
             this.saveState();
             logger.info({ silentBeats: this.lastState.consecutiveSilentBeats }, 'Heartbeat silent — nothing new');
             // Still run housekeeping
-            this.advanceGoals();
+            this.advanceGoals(tickGoals);
             this.processInbox();
             // Fall through to nightly tasks below — don't return early
         }
         else {
+            // Enrich active goals with relevant memory snippets — only done when
+            // we're actually going to invoke the agent (silent ticks discarded the result).
+            const goalMemoryContext = this.enrichGoalsWithMemory(tickGoals);
+            if (goalMemoryContext) {
+                changesSummary += `\n\n${goalMemoryContext}`;
+            }
             // Build dedup context from previously reported topics
             const dedupContext = this.buildDedupContext();
             // Build work summary for completed items
@@ -492,7 +499,7 @@ export class HeartbeatScheduler {
                 logger.error({ err }, 'Heartbeat tick failed');
             }
             // Fire-and-forget: advance active goals by writing trigger files
-            this.advanceGoals();
+            this.advanceGoals(tickGoals);
             // Fire-and-forget: process inbox items
             this.processInbox();
             // ── Confidence-based escalations from cron jobs ──────────────────
@@ -780,24 +787,42 @@ export class HeartbeatScheduler {
         return lines.join('\n');
     }
     /**
-     * Load active goal summaries for injection into heartbeat prompts.
-     * Returns null if no active goals exist.
+     * Read and parse all goal JSON files from GOALS_DIR once. Callers that
+     * need filtered subsets (active only, priority-based, etc.) do their own
+     * filtering over the returned array. Used by heartbeatTick to avoid
+     * repeating the readdirSync+readFileSync pass for every goal-consuming
+     * method.
      */
-    static loadGoalSummary() {
+    static loadAllGoals() {
         try {
             if (!existsSync(GOALS_DIR))
-                return null;
+                return [];
             const files = readdirSync(GOALS_DIR).filter(f => f.endsWith('.json'));
-            if (files.length === 0)
-                return null;
-            const activeGoals = files
+            return files
                 .map(f => { try {
                 return JSON.parse(readFileSync(path.join(GOALS_DIR, f), 'utf-8'));
             }
             catch {
                 return null;
             } })
-                .filter((g) => g && g.status === 'active');
+                .filter((g) => g !== null);
+        }
+        catch (err) {
+            logger.warn({ err }, 'loadAllGoals failed');
+            return [];
+        }
+    }
+    /**
+     * Load active goal summaries for injection into heartbeat prompts.
+     * Returns null if no active goals exist. Pass `preloadedGoals` to reuse
+     * an already-read goal list and skip disk I/O.
+     */
+    static loadGoalSummary(preloadedGoals) {
+        try {
+            const allGoals = preloadedGoals ?? HeartbeatScheduler.loadAllGoals();
+            if (allGoals.length === 0)
+                return null;
+            const activeGoals = allGoals.filter((g) => g && g.status === 'active');
             if (activeGoals.length === 0)
                 return null;
             const now = Date.now();
@@ -837,22 +862,14 @@ export class HeartbeatScheduler {
      * Enrich top active goals with relevant memory snippets.
      * Searches FTS5 memory for each goal's title+description to surface
      * recent conversations and facts the heartbeat agent can act on.
+     * Pass `preloadedGoals` to reuse an already-read goal list.
      */
-    enrichGoalsWithMemory() {
+    enrichGoalsWithMemory(preloadedGoals) {
         try {
-            if (!existsSync(GOALS_DIR))
-                return null;
-            const files = readdirSync(GOALS_DIR).filter(f => f.endsWith('.json'));
-            if (files.length === 0)
-                return null;
-            const goals = files
-                .map(f => { try {
-                return JSON.parse(readFileSync(path.join(GOALS_DIR, f), 'utf-8'));
-            }
-            catch {
+            const allGoals = preloadedGoals ?? HeartbeatScheduler.loadAllGoals();
+            if (allGoals.length === 0)
                 return null;
-            } })
-                .filter((g) => g && g.status === 'active' && g.priority !== 'low');
+            const goals = allGoals.filter((g) => g && g.status === 'active' && g.priority !== 'low');
             if (goals.length === 0)
                 return null;
             // Sort by priority (high first) and take top 3
@@ -888,7 +905,7 @@ export class HeartbeatScheduler {
      *
      * Conservative: max 2 triggers per tick, skips if triggers are already pending.
      */
-    advanceGoals() {
+    advanceGoals(preloadedGoals) {
         try {
             const goalTriggerDir = path.join(BASE_DIR, 'cron', 'goal-triggers');
             mkdirSync(goalTriggerDir, { recursive: true });
@@ -896,10 +913,8 @@ export class HeartbeatScheduler {
             const pending = readdirSync(goalTriggerDir).filter(f => f.endsWith('.trigger.json'));
             if (pending.length > 0)
                 return;
-            if (!existsSync(GOALS_DIR))
-                return;
-            const files = readdirSync(GOALS_DIR).filter(f => f.endsWith('.json'));
-            if (files.length === 0)
+            const allGoals = preloadedGoals ?? HeartbeatScheduler.loadAllGoals();
+            if (allGoals.length === 0)
                 return;
             const now = Date.now();
             const DAY_MS = 86_400_000;
@@ -965,9 +980,8 @@ export class HeartbeatScheduler {
             // Score ALL active goals — stale goals get urgency bonus, but
             // non-stale high-priority goals with pending work also qualify.
             const scoredGoals = [];
-            for (const f of files) {
+            for (const goal of allGoals) {
                 try {
-                    const goal = JSON.parse(readFileSync(path.join(GOALS_DIR, f), 'utf-8'));
                     if (goal.status !== 'active')
                         continue;
                     // Skip goals in cooldown (failed recently or producing stale output)

package/dist/index.js

@@ -880,6 +880,13 @@ async function asyncMain() {
     if (restartRequested) {
         await drainActiveSessions(gateway);
     }
+    // Flush any pending debounced session writes before exit.
+    try {
+        assistant.flushSessions();
+    }
+    catch (err) {
+        logger.warn({ err }, 'Session flush on shutdown failed');
+    }
     // Now safe to tear down remaining infrastructure
     heartbeat.stop();
     cronScheduler.stop();

package/package.json

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