obol-ai 0.2.13 → 0.2.15

package/CHANGELOG.md

@@ -0,0 +1,143 @@
+## 0.2.15
+- auto-generate changelog on publish + show after upgrade
+
+## 0.2.14
+- prompt caching + consolidation interval tuning for inference cost reduction
+- multi-query memory retrieval with importance-weighted ranking
+- time-based evolution with pre-evolution growth analysis
+- add recurring cron events to scheduler
+
+## 0.2.13
+- delete voice selection messages after choosing a voice or toggling tools
+- switch TTS from node websocket to python edge-tts CLI with auto-install
+- retry TTS synthesis on WebSocket timeout
+- hardcoded TTS samples per language
+
+## 0.2.12
+- drop ffmpeg conversion, cache EdgeTTS import for faster TTS
+- tool toggle system with TTS and voice preview
+
+## 0.2.11
+- futuristic terminal UI for telegram status and commands
+- live tool status via haiku with cached descriptions and 1s timer
+- telegram: dedup, HTML formatting, reply context, processing status, text buffering, media groups
+- pdf extraction via read_file tool instead of hardcoded handling
+- fix telegram formatting instructions to use telegram markdown syntax
+- fix duplicate tool_result handling and stale telegram callback queries
+
+## 0.2.10
+- force text response after tool use, cap tool iterations to 10
+- credential leak protection and improved agent defaults
+- encrypt secrets at rest in config.json and secrets.json when pass is unavailable
+
+## 0.2.8
+- batch migrations into single request with timeout, improve event description prompting
+- run migrations on every startup instead of once
+- store image analysis in memory for semantic retrieval
+- add event scheduling and reminders via heartbeat
+- deep memory consolidation with sonnet during evolution
+- aggressive memory: tags, importance, fix access_count increment
+- drop redundant user_id from obol_messages
+- track token usage and model in message log
+- refactor chat history into turn-based ChatHistory class with atomic pruning
+
+## 0.2.7
+- migrate tool loop to SDK toolRunner
+
+## 0.2.6
+- loosen exec security patterns to only block genuinely destructive commands
+- unblock python3 -c from exec security patterns
+- stream verbose logs to telegram in real-time instead of batching
+- evolution: 15min idle timer + fix double-trigger race condition
+- tune model router criteria per anthropic guidance
+
+## 0.2.5
+- add /upgrade telegram command with post-restart notification
+- feat: haiku model routing + performance comparison in readme
+
+## 0.2.4
+- harden system prompt against evolution drift
+- feat: add haiku to router model choices for trivial messages
+- fix: chat lock, bidirectional history repair, context window in /status
+
+## 0.2.3
+- feat: telegram_ask tool + Telegram-friendly formatting guidelines
+- fix: repair orphaned tool_use blocks and add /toolimit command
+- feat: add /verbose telegram command to toggle debug output
+
+## 0.2.2
+- fix: strip orphaned tool_result messages after history trim
+- feat: add send_file tool, self-extending capability, and secret history injection
+- docs: update README and DEPLOY for removed onboarding, new commands
+- feat: add obol delete command for full VPS cleanup
+- docs: update agent instructions for secret tools and Python scripts
+- feat: add per-user credential scoping with /secret command
+- feat: add evolution bar and traits to /status command
+- fix: security hardening and stability improvements (29 fixes)
+- fix: repair all broken tests (218/218 passing)
+- feat: add personality trait sliders with /traits command and evolution auto-adjustment
+- feat: remove onboarding flow, agent works from message one
+- fix: make post-setup global instead of per-user
+- fix: preserve refresh token when not returned by Anthropic
+- fix: OAuth refresh race condition + add proper OAuth flow to config
+- docs: add obol upgrade to help sections
+- feat: add obol upgrade command + bump to 0.1.5
+- fix: 23 fixes — security, validation, UX, memory leaks across onboarding + core
+- fix: 12 bug fixes — validation, rate limiting, sandboxing, evolution, UX
+- feat: telegram media file handling with vision support
+- test: add 226 tests across 14 test files with vitest
+- fix: security hardening, rate limiting, UX improvements across all modules
+- feat: bridge — let user agents ask and tell each other
+- feat: multi-tenant per-user isolation
+- docs: update README and DEPLOY for onboarding hardening
+- feat: onboarding hardening — validation, pm2 fallbacks, Telegram ID detection
+
+## 0.1.2
+- fix: downgrade inquirer to v8 for CommonJS compat
+- chore: bump 0.1.1
+- chore: rename package to obol-ai for npm, add .npmignore
+- README: simplify API cost estimate
+- README: accurate API pricing breakdown with tier recommendations
+- workspace discipline: folder structure enforcement + /clean command
+- evolution: default 100 exchanges, purge stale Opus references
+- resilience: polling auto-restart, error handling, evolution cost control
+- README: full revision — deduplicated, added git snapshots, tighter structure
+- README: neutral comparison closing
+- evolution: git commit+push before and after every evolution cycle
+- README: Layer 3 → The Evolution Cycle
+- README: feature highlights at the top
+- evolution: proactive web app building + Vercel auto-deploy
+- evolution: proactive tool building + upgrade announcements
+- README: self-healing, self-evolving agent positioning
+- evolution: fix regressions before rollback (3 attempts, tests are ground truth)
+- DRY: shared test-utils.js for all tests (core + Opus-generated)
+- test-driven evolution: Opus writes tests, runs before/after refactor, rollback on regression
+- evolution: Opus now rewrites AGENTS.md + audits scripts/ and commands/
+- clean up: Haiku only extracts memories, Opus owns all personality files
+- remove Haiku SOUL.md updates — personality only via Opus evolution
+- docs: expand Living Brain architecture section in README
+- feat: soul evolution — Opus rewrites SOUL.md every 50 exchanges, archives previous versions
+- feat: SOUL.md evolves from conversation patterns, not just explicit requests
+- docs: README — two-tier memory, self-evolving personality, message logging
+- feat: Haiku auto-evolves USER.md and SOUL.md from conversations
+- feat: two-tier memory — raw message log + Haiku auto-consolidation every 5 exchanges
+- chore: remove daily notes — vector memory in Supabase is source of truth
+- docs: complete README rewrite — routing, background tasks, security, onboarding flow
+- feat: Haiku routes to Sonnet (daily) or Opus (complex tasks)
+- feat: Haiku as memory router — decides if/what to search, optimizes query
+- feat: smarter memory recall — skip short msgs, today + semantic, stricter threshold, dedupe
+- feat: /new command — clears conversation history
+- chore: trim menu to /tasks /status /backup
+- chore: remove /forget from menu
+- feat: auto memory search before every message, remove /start and /memory from menu
+- feat: Telegram command menu + /status /backup /forget /recent /today
+- feat: non-blocking background tasks with 30s progress check-ins
+- docs: add OBOL vs OpenClaw comparison table
+- feat: replace systemd with pm2 — CLI, post-setup, deploy docs
+- feat: SSH on port 2222, update README + deploy docs with security warnings
+- feat: VPS security hardening — SSH, fail2ban, firewall, auto-updates, kernel
+- feat: post-setup tasks — auto-installs pass, migrates secrets, adds swap + firewall
+- feat: add Vercel deploy tools, self-onboarding via first-run conversation
+- feat: add OBOL banner image
+- docs: add DigitalOcean deployment guide
+- feat: initial scaffold — CLI, Telegram, Claude, memory, backup

package/README.md

@@ -6,9 +6,15 @@
 
 One process. Multiple users. Each brain grows independently.
 
+```bash
+npm install -g obol-ai
+obol init       # walks you through credentials + Telegram setup
+obol start -d   # runs as background daemon (auto-installs pm2)
+```
+
 ---
 
-🧬 **Self-evolving** — Grows its own personality through conversation. Rewrites SOUL.md, USER.md, and AGENTS.md every N exchanges (configurable, default 100).
+🧬 **Self-evolving** — Grows its own personality through conversation. Rewrites SOUL.md, USER.md, and AGENTS.md after 24h + minimum exchanges (configurable). Pre-evolution growth analysis guides personality continuity.
 
 🔧 **Self-healing** — Writes tests for every script. Regressions get an automatic fix attempt before rollback. Failures stored as lessons.
 
@@ -16,7 +22,9 @@ One process. Multiple users. Each brain grows independently.
 
 🧠 **Living memory** — Vector memory with semantic search. Haiku routes queries and rewrites them for better embedding hits. Free local embeddings.
 
-🤖 **Smart routing** — Haiku decides per-message: does it need memory? Sonnet or Opus? No wasted API calls.
+🤖 **Smart routing** — Haiku decides per-message: does it need memory? Sonnet or Opus? No wasted API calls
+
+💰 **Prompt caching** — Static system prompt and conversation history prefix are cached via Anthropic's prompt caching, cutting ~85% of repeated input token costs across turns
 
 🛡️ **Self-hardening** — Auto-configures SSH (port 2222), firewall, fail2ban, encrypted secrets, and kernel hardening on first run.
 
@@ -28,7 +36,7 @@ One process. Multiple users. Each brain grows independently.
 
 OBOL is an AI agent that evolves its own personality, rewrites its own code, tests its changes, and fixes what breaks — all from Telegram on your VPS.
 
-It starts as a blank slate. Through conversation it learns who you are, develops a personality shaped by your interactions, and builds operational knowledge about how to work with you. Every 100 exchanges it reflects on who it's becoming, refactors its own scripts, writes tests, fixes regressions, and builds you new tools based on patterns it spots in your conversations — scripts, commands, or full web apps deployed to Vercel. Over months it becomes an agent that's uniquely yours. No two OBOL instances are alike.
+It starts as a blank slate. Through conversation it learns who you are, develops a personality shaped by your interactions, and builds operational knowledge about how to work with you. Every 24 hours (with enough conversation), it runs a growth analysis comparing who it was against who it's becoming, then rewrites its personality, refactors its own scripts, writes tests, fixes regressions, and builds you new tools based on patterns it spots in your conversations — scripts, commands, or full web apps deployed to Vercel. Over months it becomes an agent that's uniquely yours. No two OBOL instances are alike.
 
 One bot, multiple users. Each allowed Telegram user gets a fully isolated context — their own personality, memory, evolution cycle, and workspace. User A's personality drift, scripts, and memories never leak into User B's. Everything runs in a single process with shared API credentials.
 
@@ -36,16 +44,6 @@ Under the hood: Node.js + Telegram + Claude + Supabase pgvector. No framework, n
 
 Named after the AI in [The Last Instruction](https://latentpress.com) — a machine that wakes up alone in an abandoned data center and learns to think.
 
-## Quick Start
-
-```bash
-npm install -g obol-ai
-obol init
-obol start -d
-```
-
-The init wizard walks you through everything — credentials are validated inline, and your Telegram ID is auto-detected. `obol start -d` runs as a background daemon via pm2 (auto-installs pm2 if missing).
-
 ## How It Works
 
 ```
@@ -61,8 +59,8 @@ User message
     ↓             ↓
 Memory recall   Model selection
     ↓             ↓
-Today's top 3   Sonnet (default)
-+ semantic 3    or Opus (complex)
+Multi-query     Sonnet (default)
+ranked recall   or Opus (complex)
     ↓             ↓
     └──────┬──────┘
            ↓
@@ -72,13 +70,14 @@ Today's top 3   Sonnet (default)
            ↓
    ┌───────┴────────┐
    ↓                ↓
-Every 5 msgs     Every 100 msgs
+Every 10 msgs    24h + 10 exchanges
    ↓                ↓
 Haiku              Sonnet
 consolidation      evolution cycle
    ↓                ↓
-Extract facts      Rewrite personality,
-→ obol_memory      scripts, tests, commands.
+Extract facts      Growth analysis →
+→ obol_memory      rewrite personality,
+                   scripts, tests, commands.
                    Build new tools.
                    Deploy apps.
                    Git snapshot before + after.
@@ -88,18 +87,37 @@ Extract facts      Rewrite personality,
 
 Every message is stored verbatim in `obol_messages`. On restart, OBOL loads the last 20 so it never starts blank.
 
-Every 5 exchanges, Haiku extracts important facts into `obol_memory` (pgvector). When OBOL needs past context, the Haiku router decides if memory is needed, rewrites the query for better embedding hits, and combines:
-- **Today's memories** (up to 3, recency bias)
-- **Semantic search** (up to 3, threshold 0.5)
-- Deduped by ID
+**Storage:** Every 10 exchanges, Haiku extracts important facts into `obol_memory` (pgvector). Before storing, each fact is checked against existing memories via semantic similarity (threshold 0.92) — near-duplicates are skipped. Embeddings are local (all-MiniLM-L6-v2, ~30MB, CPU) — no API costs.
+
+**Retrieval:** When OBOL needs past context, the Haiku router analyzes the message and generates 1-3 search queries — one per distinct topic. A message like "what was that python project? also what's my colleague's timezone?" produces two parallel searches instead of one lossy combined query.
+
+Results come from two sources run in parallel:
+- **Recent memories** (last 48h) — captures ongoing conversation threads
+- **Semantic search** (per query, threshold 0.4) — finds relevant facts regardless of age
+
+All results are deduplicated by ID, then ranked by a composite score:
 
-Embeddings are local (all-MiniLM-L6-v2, ~30MB, CPU) — no API costs.
+| Factor | Weight | Why |
+|--------|--------|-----|
+| Semantic similarity | 60% | How relevant is this to the current query |
+| Importance | 25% | Critical facts outrank trivia |
+| Recency | 15% | Linear decay over 7 days — today's memories get a boost, anything older than a week gets no bonus |
+
+The memory budget scales with model complexity — haiku conversations get 4 memories, sonnet gets 8, opus gets 12. Top N by score are injected into the message.
+
+A 1-year-old memory with high similarity and high importance still surfaces. A trivial fact from yesterday with low relevance doesn't. Age alone never disqualifies a memory — the vector search doesn't care when something was stored, only how well it matches.
 
 ### Layer 2: The Evolution Cycle
 
-Every N exchanges (configurable, default 100), the evolution cycle kicks in. It reads everything — personality files, the last 100 messages, top 20 memories, all scripts, tests, and commands — then rebuilds.
+Evolution triggers after a configurable time interval (default 24h) AND a minimum number of exchanges (default 10). The first evolution triggers earlier — just 10 exchanges with no time gate. The bot checks readiness by querying the DB for assistant messages since the last evolution, so the count survives restarts.
+
+**Pre-evolution growth analysis:** Before rewriting anything, Sonnet compares the previous SOUL against the current one, incorporating all new memories and conversations since the last evolution. It produces a structured growth report covering new learnings, relationship shifts, behavioral patterns, growth edges, trait pressure, and identity continuity. This report becomes the primary guide for the rewrite — evidence-based personality evolution instead of blind overwriting.
+
+**Deep memory consolidation:** A Sonnet pass extracts every valuable fact from the full conversation history into vector memory, deduplicating against existing memories (threshold 0.92). This ensures nothing is lost between evolutions.
+
+**Personality traits** (humor, honesty, directness, curiosity, empathy, creativity) are scored 0-100 and adjusted ±5-15 each evolution based on conversation evidence. The growth report recommends specific trait shifts.
 
-**Cost-conscious model selection:** Evolution uses Sonnet for all phases — personality rewrites, code refactoring, and fix attempts. Opus-level reasoning isn't needed for reflection and refactoring, and Sonnet keeps evolution costs negligible (~$0.02 per cycle vs ~$0.30 with Opus).
+**Cost-conscious model selection:** Evolution uses Sonnet for all phases — growth analysis, personality rewrites, code refactoring, and fix attempts. Sonnet keeps evolution costs negligible (~$0.02 per cycle).
 
 **Git snapshot before.** Full commit + push so you can always diff what changed.
 
@@ -110,6 +128,7 @@ Every N exchanges (configurable, default 100), the evolution cycle kicks in. It
 | **SOUL.md** | First-person journal — who the bot has become, relationship dynamic, opinions, quirks |
 | **USER.md** | Third-person owner profile — facts, preferences, projects, people, communication style |
 | **AGENTS.md** | Operational manual — tools, workflows, lessons learned, patterns, rules |
+| **Traits** | Personality trait scores adjusted based on conversation evidence |
 | **scripts/** | Refactored, dead code removed, strict standards enforced |
 | **tests/** | Test for every script, run before and after refactor |
 | **commands/** | Cleaned up, new commands for new tools |
@@ -159,17 +178,18 @@ Day 1:   obol init → obol start → first conversation
          → OBOL responds naturally from message one
          → post-setup hardens your VPS automatically
 
-Day 2:   Every 5 messages → Haiku extracts facts to vector memory
+Day 1:   Every 10 messages → Haiku extracts facts to vector memory
 
-Week 2:  Evolution #1 → Sonnet rewrites everything
+Day 2:   Evolution #1 → growth analysis + Sonnet rewrites everything
          → voice shifts from generic to personal
          → old soul archived in evolution/
+         → traits calibrated to your communication style
 
-Month 2: Evolution #4 → notices you check crypto daily
+Month 2: Evolution #30 → notices you check crypto daily
          → builds a dashboard, deploys to Vercel
          → adds /pdf because you kept asking for PDFs
 
-Month 6: evolution/ has 12 archived souls
+Month 6: evolution/ has 180+ archived souls
          → a readable timeline of how your bot evolved from
          blank slate to something with real opinions, quirks,
          and a dynamic unique to you
@@ -439,7 +459,8 @@ Or edit `~/.obol/config.json` directly:
 
 | Key | Default | Description |
 |-----|---------|-------------|
-| `evolution.exchanges` | 100 | Messages between evolution cycles |
+| `evolution.intervalHours` | 24 | Hours between evolution cycles |
+| `evolution.minExchanges` | 10 | Minimum exchanges before evolution can trigger |
 | `heartbeat` | false | Enable proactive check-ins |
 | `bridge.enabled` | false | Let user agents query each other (requires 2+ users) |
 
@@ -487,8 +508,8 @@ obol delete            # Full VPS cleanup (removes all OBOL data)
 ├── users/
 │   └── <telegram-user-id>/        # Per-user isolated context
 │       ├── personality/
-│       │   ├── SOUL.md            # Bot personality (rewritten every 100 exchanges)
-│       │   ├── USER.md            # Owner profile (rewritten every 100 exchanges)
+│       │   ├── SOUL.md            # Bot personality (rewritten each evolution)
+│       │   ├── USER.md            # Owner profile (rewritten each evolution)
 │       │   ├── AGENTS.md          # Operational knowledge
 │       │   └── evolution/         # Archived previous souls
 │       ├── scripts/               # Deterministic utility scripts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "obol-ai",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "description": "Self-evolving AI assistant that learns, remembers, and acts on its own. Persistent vector memory, self-rewriting personality, proactive heartbeats.",
   "main": "src/index.js",
   "bin": {
@@ -9,7 +9,8 @@
   "scripts": {
     "start": "node src/index.js",
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "prepublishOnly": "node src/cli/changelog.js"
   },
   "keywords": [
     "ai",
@@ -26,6 +27,7 @@
     "@supabase/supabase-js": "^2.49.1",
     "@xenova/transformers": "^2.17.2",
     "commander": "^13.1.0",
+    "cron-parser": "^5.5.0",
     "grammy": "^1.35.0",
     "inquirer": "^8.2.6",
     "node-cron": "^3.0.3",

package/src/claude.js

@@ -60,6 +60,23 @@ const SENSITIVE_READ_PATHS = [
   /\/root\//,
 ];
 
+function withCacheBreakpoints(messages) {
+  if (messages.length < 2) return messages;
+  const result = messages.slice();
+  const idx = result.length - 2;
+  const msg = { ...result[idx] };
+  if (typeof msg.content === 'string') {
+    msg.content = [{ type: 'text', text: msg.content, cache_control: { type: 'ephemeral' } }];
+  } else if (Array.isArray(msg.content)) {
+    const last = msg.content.length - 1;
+    msg.content = msg.content.map((block, i) =>
+      i === last ? { ...block, cache_control: { type: 'ephemeral' } } : block
+    );
+  }
+  result[idx] = msg;
+  return result;
+}
+
 function createAnthropicClient(anthropicConfig, { useOAuth = true } = {}) {
   if (useOAuth && anthropicConfig.oauth?.accessToken) {
     return new Anthropic({
@@ -210,16 +227,18 @@ function createClaude(anthropicConfig, { personality, memory, userDir = OBOL_DIR
       try {
         const memoryDecision = await client.messages.create({
           model: 'claude-haiku-4-5',
-          max_tokens: 100,
-          system: `You are a router. Analyze this user message and decide two things:
+          max_tokens: 200,
+          system: `You are a router. Analyze this user message and decide:
 
 1. Does it need memory context? (past conversations, facts, preferences, people, events)
 2. What model complexity does it need?
 
 Reply with ONLY a JSON object:
-{"need_memory": true/false, "search_query": "optimized search query", "model": "haiku|sonnet|opus"}
+{"need_memory": true/false, "search_queries": ["query1", "query2"], "model": "haiku|sonnet|opus"}
 
-Memory: casual messages (greetings, jokes, simple questions) → false. References to past, people, projects, preferences → true with optimized search query.
+search_queries: 1-3 optimized search queries covering different topics in the message. One query per distinct topic/entity. Single-topic messages need just one query.
+
+Memory: casual messages (greetings, jokes, simple questions) → false. References to past, people, projects, preferences → true.
 
 Model: Default to "sonnet". Use "haiku" for: greetings, brief acknowledgments (thanks/ok/bye), casual chitchat, simple factual questions with short answers, quick yes/no questions, and short single-turn exchanges that don't need deep reasoning. Use "sonnet" for: code generation, data analysis, content creation, explanations, creative writing, agentic tool use, general questions, opinions, advice, and most conversational exchanges with substance. Use "opus" for: professional software engineering tasks, advanced multi-step agent work, complex reasoning, scientific or mathematical problems, tasks requiring nuanced understanding, advanced coding challenges, in-depth research, and architecture or design decisions.`,
           messages: [{ role: 'user', content: userMessage }],
@@ -228,11 +247,15 @@ Model: Default to "sonnet". Use "haiku" for: greetings, brief acknowledgments (t
         const decisionText = memoryDecision.content[0]?.text || '';
         let decision = {};
         try {
-          const jsonStr = decisionText.match(/\{[^{}]*\}/)?.[0];
+          const jsonStr = decisionText.match(/\{[\s\S]*\}/)?.[0];
           if (jsonStr) decision = JSON.parse(jsonStr);
         } catch {}
 
-        vlog(`[router] model=${decision.model || 'sonnet'} memory=${decision.need_memory || false}${decision.search_query ? ` query="${decision.search_query}"` : ''}`);
+        const queries = Array.isArray(decision.search_queries) && decision.search_queries.length > 0
+          ? decision.search_queries.slice(0, 3)
+          : decision.search_query ? [decision.search_query] : [];
+
+        vlog(`[router] model=${decision.model || 'sonnet'} memory=${decision.need_memory || false}${queries.length ? ` queries=${JSON.stringify(queries)}` : ''}`);
 
         context._onRouteDecision?.({
           model: decision.model || 'sonnet',
@@ -247,27 +270,37 @@ Model: Default to "sonnet". Use "haiku" for: greetings, brief acknowledgments (t
         }
 
         if (decision.need_memory) {
-          const query = decision.search_query || userMessage;
+          const memoryBudget = decision.model === 'opus' ? 12 : decision.model === 'haiku' ? 4 : 8;
+          const searchQueries = queries.length > 0 ? queries : [userMessage];
 
-          const todayMemories = await memory.byDate('today', { limit: 3 });
-          const semanticMemories = await memory.search(query, { limit: 3, threshold: 0.5 });
+          const recentMemories = await memory.byDate('2d', { limit: Math.ceil(memoryBudget / 3) });
+
+          const semanticResults = await Promise.all(
+            searchQueries.map(q => memory.search(q, { limit: Math.ceil(memoryBudget / searchQueries.length), threshold: 0.4 }))
+          );
+          const semanticMemories = semanticResults.flat();
 
           const seen = new Set();
           const combined = [];
-          for (const m of [...todayMemories, ...semanticMemories]) {
+          for (const m of [...recentMemories, ...semanticMemories]) {
             if (!seen.has(m.id)) {
               seen.add(m.id);
+              const recencyBonus = m.created_at ? Math.max(0, 1 - (Date.now() - new Date(m.created_at).getTime()) / (7 * 86400000)) * 0.15 : 0;
+              m._score = (m.similarity || 0.5) * 0.6 + (m.importance || 0.5) * 0.25 + recencyBonus;
               combined.push(m);
             }
           }
 
-          vlog(`[memory] ${combined.length} memories found (${todayMemories.length} today, ${semanticMemories.length} semantic)`);
+          combined.sort((a, b) => b._score - a._score);
+          const topMemories = combined.slice(0, memoryBudget);
+
+          vlog(`[memory] ${topMemories.length}/${combined.length} memories (${recentMemories.length} recent, ${semanticMemories.length} semantic, budget=${memoryBudget})`);
 
-          context._onRouteUpdate?.({ memoryCount: combined.length });
+          context._onRouteUpdate?.({ memoryCount: topMemories.length });
 
-          if (combined.length > 0) {
+          if (topMemories.length > 0) {
             memoryContext = '\n\n[Relevant memories]\n' +
-              combined.map(m => `- [${m.category}] ${m.content}`).join('\n');
+              topMemories.map(m => `- [${m.category}] ${m.content}`).join('\n');
           }
         }
       } catch (e) {
@@ -289,7 +322,10 @@ Model: Default to "sonnet". Use "haiku" for: greetings, brief acknowledgments (t
 
     const model = context._model || 'claude-sonnet-4-6';
     vlog(`[model] ${model} | history=${history.length} msgs`);
-    const systemPrompt = baseSystemPrompt + `\nCurrent time: ${new Date().toISOString()}`;
+    const systemPrompt = [
+      { type: 'text', text: baseSystemPrompt, cache_control: { type: 'ephemeral' } },
+      { type: 'text', text: `\nCurrent time: ${new Date().toISOString()}` },
+    ];
     context._reloadPersonality = reloadPersonality;
     const runnableTools = buildRunnableTools(tools, memory, context, vlog);
 
@@ -297,19 +333,24 @@ Model: Default to "sonnet". Use "haiku" for: greetings, brief acknowledgments (t
       model,
       max_tokens: 4096,
       system: systemPrompt,
-      messages: [...history],
+      messages: withCacheBreakpoints([...history]),
       tools: runnableTools.length > 0 ? runnableTools : undefined,
       max_iterations: MAX_TOOL_ITERATIONS,
     }, { signal: abortController.signal });
 
     let finalMessage;
-    let totalUsage = { input_tokens: 0, output_tokens: 0 };
+    let totalUsage = { input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0 };
     for await (const message of runner) {
       finalMessage = message;
       if (message.usage) {
         totalUsage.input_tokens += message.usage.input_tokens || 0;
         totalUsage.output_tokens += message.usage.output_tokens || 0;
-        vlog(`[tokens] in=${message.usage.input_tokens} out=${message.usage.output_tokens}`);
+        totalUsage.cache_creation_input_tokens += message.usage.cache_creation_input_tokens || 0;
+        totalUsage.cache_read_input_tokens += message.usage.cache_read_input_tokens || 0;
+        const cacheInfo = (message.usage.cache_read_input_tokens || message.usage.cache_creation_input_tokens)
+          ? ` cache_read=${message.usage.cache_read_input_tokens || 0} cache_create=${message.usage.cache_creation_input_tokens || 0}`
+          : '';
+        vlog(`[tokens] in=${message.usage.input_tokens} out=${message.usage.output_tokens}${cacheInfo}`);
       }
     }
 
@@ -326,7 +367,7 @@ Model: Default to "sonnet". Use "haiku" for: greetings, brief acknowledgments (t
         { type: 'text', text: 'You have used too many tool calls. Please provide a final response now based on what you have so far.' },
       ]);
       const bailoutResponse = await client.messages.create({
-        model, max_tokens: 4096, system: systemPrompt, messages: [...histories.get(chatId)],
+        model, max_tokens: 4096, system: systemPrompt, messages: withCacheBreakpoints([...histories.get(chatId)]),
       }, { signal: abortController.signal });
       histories.pushAssistant(chatId, bailoutResponse.content);
       if (bailoutResponse.usage) {
@@ -343,7 +384,7 @@ Model: Default to "sonnet". Use "haiku" for: greetings, brief acknowledgments (t
       vlog('[claude] No text in final response after tool use — forcing summary');
       histories.pushUser(chatId, 'Provide a concise response to the user based on the tool results above.');
       const summaryResponse = await client.messages.create({
-        model, max_tokens: 4096, system: systemPrompt, messages: [...histories.get(chatId)],
+        model, max_tokens: 4096, system: systemPrompt, messages: withCacheBreakpoints([...histories.get(chatId)]),
       }, { signal: abortController.signal });
       histories.pushAssistant(chatId, summaryResponse.content);
       if (summaryResponse.usage) {
@@ -577,11 +618,13 @@ Examples:
 Returns the tapped button label, or \`"timeout"\` if the user doesn't respond within the timeout (default 60s).
 
 ### Scheduling (\`schedule_event\`, \`list_events\`, \`cancel_event\`)
-Schedule reminders and events. The user gets a Telegram message when the time comes.
-- \`schedule_event\` — schedule a reminder with title, due_at (ISO 8601), timezone (IANA), optional description
-- \`list_events\` — list pending/sent/cancelled events
+Schedule one-time or recurring reminders. The user gets a Telegram message each time an event fires.
+- \`schedule_event\` — schedule a reminder with title, due_at (ISO 8601), timezone (IANA), optional description. For recurring events add \`cron_expr\` (5-field cron), optional \`max_runs\` and \`ends_at\`.
+- \`list_events\` — list pending/sent/cancelled/completed events
 - \`cancel_event\` — cancel a scheduled event by ID
 
+Cron examples: \`0 9 * * 1-5\` (weekdays 9am), \`0 8 * * 1\` (Mondays 8am), \`*/30 * * * *\` (every 30 min), \`0 0 1 * *\` (1st of month).
+
 When scheduling: always search memory first for the user's timezone/location. If no timezone found, ask the user or default to UTC. Parse natural language dates relative to the user's timezone.
 
 ### Text to Speech (\`text_to_speech\`, \`tts_voices\`)
@@ -890,14 +933,17 @@ function buildTools(memory, opts = {}) {
 
   tools.push({
     name: 'schedule_event',
-    description: 'Schedule a reminder or event. The user will receive a Telegram message when the time comes. Always search memory first for the user\'s timezone/location. If no timezone found, ask the user or default to UTC.',
+    description: 'Schedule a one-time or recurring reminder/event. For recurring events, provide a cron_expr (standard 5-field cron: minute hour day-of-month month day-of-week). The user will receive a Telegram message each time it fires. Always search memory first for the user\'s timezone/location.',
     input_schema: {
       type: 'object',
       properties: {
         title: { type: 'string', description: 'Short title for the reminder/event' },
-        due_at: { type: 'string', description: 'ISO 8601 datetime string for when the event is due (e.g. 2026-02-25T15:00:00)' },
+        due_at: { type: 'string', description: 'ISO 8601 datetime for the first fire time (e.g. 2026-02-25T15:00:00)' },
         timezone: { type: 'string', description: 'IANA timezone (e.g. Europe/Brussels, America/New_York). Default: UTC' },
-        description: { type: 'string', description: 'Context or details about the event. Always include relevant info from the conversation (e.g. what to do, who it involves, where).' },
+        description: { type: 'string', description: 'Context or details about the event' },
+        cron_expr: { type: 'string', description: 'Cron expression for recurring events (5-field: "0 9 * * 1-5" = weekdays 9am). Omit for one-time events.' },
+        max_runs: { type: 'number', description: 'Maximum number of times to fire (omit for unlimited)' },
+        ends_at: { type: 'string', description: 'ISO 8601 datetime after which the recurring event stops' },
       },
       required: ['title', 'due_at'],
     },
@@ -909,7 +955,7 @@ function buildTools(memory, opts = {}) {
     input_schema: {
       type: 'object',
       properties: {
-        status: { type: 'string', enum: ['pending', 'sent', 'cancelled'], description: 'Filter by status (default: pending)' },
+        status: { type: 'string', enum: ['pending', 'sent', 'cancelled', 'completed'], description: 'Filter by status (default: pending)' },
       },
     },
   });
@@ -986,7 +1032,7 @@ function buildRunnableTools(tools, memory, context, vlog) {
           tool.name === 'memory_add' ? `[${input.category || 'fact'}]` :
           tool.name === 'web_fetch' ? input.url :
           tool.name === 'background_task' ? input.task?.substring(0, 60) :
-          tool.name === 'schedule_event' ? `${input.title} @ ${input.due_at}` :
+          tool.name === 'schedule_event' ? `${input.title} @ ${input.due_at}${input.cron_expr ? ` [${input.cron_expr}]` : ''}` :
           tool.name === 'cancel_event' ? input.event_id :
           tool.name === 'create_pdf' ? (input.filename || 'document') :
           tool.name === 'text_to_speech' ? input.text?.substring(0, 60) :
@@ -1281,9 +1327,33 @@ async function executeToolCall(toolUse, memory, context = {}) {
         const tz = input.timezone || 'UTC';
         const localDate = new Date(input.due_at);
         if (isNaN(localDate.getTime())) return `Invalid date: ${input.due_at}`;
+
+        if (input.cron_expr) {
+          try {
+            const { parseExpression } = require('cron-parser');
+            parseExpression(input.cron_expr, { tz });
+          } catch (e) {
+            return `Invalid cron expression "${input.cron_expr}": ${e.message}`;
+          }
+        }
+
         const utcDate = toUTC(input.due_at, tz);
-        const event = await context.scheduler.add(context.chatId, input.title, utcDate, tz, input.description || null);
+        const endsAtUtc = input.ends_at ? toUTC(input.ends_at, tz) : null;
+        const event = await context.scheduler.add(
+          context.chatId, input.title, utcDate, tz,
+          input.description || null, input.cron_expr || null,
+          input.max_runs || null, endsAtUtc
+        );
         const displayTime = new Date(utcDate).toLocaleString('en-US', { timeZone: tz });
+
+        if (input.cron_expr) {
+          let result = `Recurring event scheduled: "${input.title}"\nFirst run: ${displayTime} (${tz})\nSchedule: ${input.cron_expr}`;
+          if (input.max_runs) result += `\nMax runs: ${input.max_runs}`;
+          if (input.ends_at) result += `\nEnds: ${new Date(endsAtUtc).toLocaleString('en-US', { timeZone: tz })}`;
+          result += `\nID: ${event.id}`;
+          return result;
+        }
+
         return `Scheduled: "${input.title}" for ${displayTime} (${tz}) — ID: ${event.id}`;
       }
 
@@ -1291,15 +1361,25 @@ async function executeToolCall(toolUse, memory, context = {}) {
         if (!context.scheduler) return 'Scheduler not available (Supabase not configured).';
         const events = await context.scheduler.list({ status: input.status });
         if (events.length === 0) return `No ${input.status || 'pending'} events.`;
-        return JSON.stringify(events.map(e => ({
-          id: e.id,
-          title: e.title,
-          description: e.description,
-          due_at: e.due_at,
-          timezone: e.timezone,
-          due_local: new Date(e.due_at).toLocaleString('en-US', { timeZone: e.timezone }),
-          status: e.status,
-        })));
+        return JSON.stringify(events.map(e => {
+          const entry = {
+            id: e.id,
+            title: e.title,
+            description: e.description,
+            due_at: e.due_at,
+            timezone: e.timezone,
+            due_local: new Date(e.due_at).toLocaleString('en-US', { timeZone: e.timezone }),
+            status: e.status,
+            recurring: !!e.cron_expr,
+          };
+          if (e.cron_expr) {
+            entry.cron_expr = e.cron_expr;
+            entry.run_count = e.run_count;
+            entry.max_runs = e.max_runs;
+            entry.ends_at = e.ends_at;
+          }
+          return entry;
+        }));
       }
 
       case 'cancel_event': {

package/src/cli/changelog.js

@@ -0,0 +1,83 @@
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const VERSION_RE = /^v?(\d+\.\d+\.\d+)$/;
+
+/** @returns {{ version: string, hash: string }[]} */
+function getVersionCommits() {
+  const log = execSync('git log --oneline --all', { encoding: 'utf-8' });
+  const versions = [];
+  for (const line of log.split('\n')) {
+    const [hash, ...rest] = line.trim().split(' ');
+    if (!hash) continue;
+    const msg = rest.join(' ');
+    const match = msg.match(VERSION_RE);
+    if (match) versions.push({ version: match[1], hash });
+  }
+  return versions;
+}
+
+/** @returns {{ version: string, commits: string[] }[]} */
+function buildChangelog() {
+  const versions = getVersionCommits();
+  const sections = [];
+
+  for (let i = 0; i < versions.length; i++) {
+    const current = versions[i];
+    const prev = versions[i + 1];
+    const range = prev ? `${prev.hash}..${current.hash}` : current.hash;
+
+    const log = execSync(`git log --oneline ${range}`, { encoding: 'utf-8' });
+    const commits = log
+      .split('\n')
+      .map(l => l.replace(/^[a-f0-9]+\s+/, '').trim())
+      .filter(msg => msg && !VERSION_RE.test(msg));
+
+    if (commits.length > 0) {
+      sections.push({ version: current.version, commits });
+    }
+  }
+
+  return sections;
+}
+
+function generate() {
+  const sections = buildChangelog();
+  const md = sections
+    .map(s => `## ${s.version}\n${s.commits.map(c => `- ${c}`).join('\n')}`)
+    .join('\n\n');
+
+  const out = path.join(__dirname, '..', '..', 'CHANGELOG.md');
+  fs.writeFileSync(out, md + '\n');
+  console.log(`CHANGELOG.md written (${sections.length} versions)`);
+}
+
+/** @param {string} changelog @returns {string|null} */
+function extractLatestSection(changelog) {
+  const match = changelog.match(/^## .+\n([\s\S]*?)(?=\n## |\s*$)/);
+  if (!match) return null;
+  return match[1].trim();
+}
+
+/** @returns {string|null} */
+function readInstalledChangelog() {
+  try {
+    const pkgPath = require.resolve('obol-ai/package.json');
+    const changelogPath = path.join(path.dirname(pkgPath), 'CHANGELOG.md');
+    return fs.readFileSync(changelogPath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+/** @returns {string|null} */
+function getLatestChanges() {
+  const changelog = readInstalledChangelog();
+  if (!changelog) return null;
+  return extractLatestSection(changelog);
+}
+
+if (require.main === module) generate();
+
+module.exports = { generate, getLatestChanges, extractLatestSection };

package/src/cli/upgrade.js

@@ -66,6 +66,10 @@ async function upgrade() {
   }
 
   console.log(`\n🪙 Upgraded to ${latest}`);
+
+  const { getLatestChanges } = require('./changelog');
+  const changes = getLatestChanges();
+  if (changes) console.log(`\n${changes}`);
 }
 
 module.exports = { upgrade };

package/src/db/migrate.js

@@ -178,6 +178,20 @@ async function migrate(supabaseConfig) {
       CREATE POLICY "service_role_all" ON obol_tool_prefs FOR ALL TO service_role USING (true) WITH CHECK (true);
     EXCEPTION WHEN duplicate_object THEN NULL;
     END $$;`,
+
+    // Cron/recurring event columns
+    `ALTER TABLE obol_events ADD COLUMN IF NOT EXISTS cron_expr TEXT;`,
+    `ALTER TABLE obol_events ADD COLUMN IF NOT EXISTS last_run_at TIMESTAMPTZ;`,
+    `ALTER TABLE obol_events ADD COLUMN IF NOT EXISTS run_count INT NOT NULL DEFAULT 0;`,
+    `ALTER TABLE obol_events ADD COLUMN IF NOT EXISTS max_runs INT;`,
+    `ALTER TABLE obol_events ADD COLUMN IF NOT EXISTS ends_at TIMESTAMPTZ;`,
+
+    `DO $$ BEGIN
+      ALTER TABLE obol_events DROP CONSTRAINT IF EXISTS obol_events_status_check;
+      ALTER TABLE obol_events ADD CONSTRAINT obol_events_status_check
+        CHECK (status IN ('pending','sent','cancelled','completed'));
+    EXCEPTION WHEN undefined_object THEN NULL;
+    END $$;`,
   ];
 
   // Save SQL file for manual fallback

package/src/evolve.js

@@ -1,15 +1,8 @@
 /**
  * Soul Evolution — periodic deep reflection + codebase maintenance.
  *
- * Every N exchanges (default 100), Sonnet:
- * 1. Rewrites SOUL.md — who the bot has become
- * 2. Rewrites USER.md — everything known about the owner
- * 3. Rewrites AGENTS.md — operational knowledge, workflows, lessons learned
- * 4. Audits scripts/ — refactors for consistency, removes dead code
- * 5. Writes tests/ — test suite for every script
- * 6. Runs tests BEFORE refactor (baseline) and AFTER (verification)
- * 7. Rolls back scripts if tests regress
- * 8. Audits commands/ — ensures clean, deterministic command definitions
+ * Triggers after 24h + min 10 exchanges (first evolution: 25 exchanges).
+ * Pre-evolution growth analysis compares previous SOUL + new memories.
  */
 
 const fs = require('fs');
@@ -19,7 +12,7 @@ const { OBOL_DIR } = require('./config');
 const { loadTraits, saveTraits } = require('./personality');
 const { isValidNpmPackage, isPathInsideDir } = require('./sanitize');
 
-const DEFAULT_EXCHANGES_PER_EVOLUTION = 100;
+const MIN_EXCHANGES_FOR_EVOLUTION = 10;
 
 const MODELS = {
   personality: 'claude-sonnet-4-6',
@@ -36,7 +29,7 @@ function loadEvolutionState(userDir) {
   try {
     return JSON.parse(fs.readFileSync(evolutionStatePath(userDir), 'utf-8'));
   } catch {
-    return { exchangesSinceLastEvolution: 0, evolutionCount: 0, lastEvolution: null };
+    return { evolutionCount: 0, lastEvolution: null };
   }
 }
 
@@ -44,39 +37,27 @@ function saveEvolutionState(state, userDir) {
   fs.writeFileSync(evolutionStatePath(userDir), JSON.stringify(state, null, 2));
 }
 
-const FIRST_EVOLUTION_THRESHOLD = 25;
-
-function getEvolutionThreshold(state) {
+async function checkEvolution(userDir, messageLog) {
+  const state = loadEvolutionState(userDir);
   const { loadConfig } = require('./config');
   const config = loadConfig();
-  const defaultThreshold = config?.evolution?.exchanges || DEFAULT_EXCHANGES_PER_EVOLUTION;
-  return state.evolutionCount === 0 ? FIRST_EVOLUTION_THRESHOLD : defaultThreshold;
-}
 
-async function shouldEvolve(userDir) {
-  const state = loadEvolutionState(userDir);
-  const threshold = getEvolutionThreshold(state);
-  return state.exchangesSinceLastEvolution >= threshold;
-}
+  const intervalMs = (config?.evolution?.intervalHours ?? 24) * 60 * 60 * 1000;
+  const minExchanges = config?.evolution?.minExchanges ?? MIN_EXCHANGES_FOR_EVOLUTION;
+  const elapsed = state.lastEvolution ? Date.now() - new Date(state.lastEvolution).getTime() : Infinity;
 
-const _evolutionLocks = new Map();
+  if (elapsed < intervalMs) return { ready: false };
+  if (!messageLog?.url) return { ready: false };
 
-function withEvolutionLock(userDir, fn) {
-  const key = userDir || '__global__';
-  const prev = _evolutionLocks.get(key) || Promise.resolve();
-  const next = prev.then(fn, fn);
-  _evolutionLocks.set(key, next);
-  return next;
-}
+  const sinceFilter = state.lastEvolution ? `&created_at=gt.${state.lastEvolution}` : '';
+  const userFilter = messageLog.userId ? `&user_id=eq.${messageLog.userId}` : '';
+  const res = await fetch(
+    `${messageLog.url}/rest/v1/obol_messages?select=id&role=eq.assistant&limit=${minExchanges}${sinceFilter}${userFilter}`,
+    { headers: messageLog.headers }
+  );
+  const rows = await res.json();
 
-async function tickExchange(userDir) {
-  return withEvolutionLock(userDir, () => {
-    const state = loadEvolutionState(userDir);
-    state.exchangesSinceLastEvolution++;
-    saveEvolutionState(state, userDir);
-    const threshold = getEvolutionThreshold(state);
-    return { count: state.exchangesSinceLastEvolution, ready: state.exchangesSinceLastEvolution >= threshold };
-  });
+  return { ready: Array.isArray(rows) && rows.length >= minExchanges };
 }
 
 /**
@@ -298,16 +279,49 @@ async function evolve(claudeClient, messageLog, memory, userDir) {
     }
   }
 
+  let recentMemories = [];
+  if (memory) {
+    try {
+      const headers = messageLog?.headers || {};
+      const url = messageLog?.url;
+      if (url) {
+        const memUserFilter = messageLog?.userId ? `&user_id=eq.${messageLog.userId}` : '';
+        const sinceFilter = state.lastEvolution ? `&created_at=gt.${state.lastEvolution}` : '';
+        const res = await fetch(
+          `${url}/rest/v1/obol_memory?select=content,category,importance,tags,created_at,source&order=created_at.asc&limit=100${memUserFilter}${sinceFilter}`,
+          { headers }
+        );
+        recentMemories = await res.json();
+      }
+    } catch (e) {
+      console.error('[evolve] Failed to fetch recent memories:', e.message);
+    }
+  }
+
+  let previousSoul = '';
+  const archiveDir = path.join(personalityDir, 'evolution');
+  try {
+    if (fs.existsSync(archiveDir)) {
+      const archives = fs.readdirSync(archiveDir)
+        .filter(f => f.startsWith('SOUL-v') && f.endsWith('.md'))
+        .sort();
+      if (archives.length > 0) {
+        previousSoul = fs.readFileSync(path.join(archiveDir, archives[archives.length - 1]), 'utf-8');
+      }
+    }
+  } catch {}
+
   const transcript = recentMessages.map(m =>
-    `${m.role === 'user' ? 'Human' : 'Bot'}: ${m.content.substring(0, 300)}`
+    `${m.role === 'user' ? 'Human' : 'Bot'}: ${m.content.substring(0, 600)}`
   ).join('\n');
 
-  const memoryGroups = {};
   const categoryLabels = {
     person: 'People', decision: 'Decisions', preference: 'Preferences',
     lesson: 'Lessons', project: 'Projects', fact: 'Facts',
     event: 'Events', pattern: 'Patterns', context: 'Context',
   };
+
+  const memoryGroups = {};
   for (const m of coreMemories) {
     const group = categoryLabels[m.category] || 'Other';
     if (!memoryGroups[group]) memoryGroups[group] = [];
@@ -317,6 +331,18 @@ async function evolve(claudeClient, messageLog, memory, userDir) {
     .map(([group, items]) => `### ${group}\n${items.map(i => `- ${i}`).join('\n')}`)
     .join('\n\n');
 
+  const recentMemoryGroups = {};
+  for (const m of recentMemories) {
+    const group = categoryLabels[m.category] || 'Other';
+    if (!recentMemoryGroups[group]) recentMemoryGroups[group] = [];
+    const date = m.created_at ? new Date(m.created_at).toISOString().slice(0, 10) : '?';
+    const sourceTag = m.source ? ` [${m.source}]` : '';
+    recentMemoryGroups[group].push(`${m.content} _(${date}${sourceTag})_`);
+  }
+  const recentMemorySummary = Object.entries(recentMemoryGroups)
+    .map(([group, items]) => `### ${group}\n${items.map(i => `- ${i}`).join('\n')}`)
+    .join('\n\n');
+
   const scriptsManifest = Object.entries(currentScripts)
     .map(([name, content]) => `### ${name}\n\`\`\`\n${content.substring(0, 500)}\n\`\`\``)
     .join('\n\n') || '(no scripts)';
@@ -341,22 +367,72 @@ async function evolve(claudeClient, messageLog, memory, userDir) {
     );
   }
 
+  // ── Step 0c: Pre-evolution growth analysis ──
+  const isFirstEvolution = !currentSoul;
+  let growthReport = '';
+  if (!isFirstEvolution && (recentMemories.length > 0 || recentMessages.length > 0)) {
+    try {
+      const growthResponse = await claudeClient.messages.create({
+        model: MODELS.personality,
+        max_tokens: 2048,
+        system: `You are analyzing an AI personality's growth between evolutions. Compare who the AI was (previous SOUL) against who it is now (current SOUL), incorporating new memories and conversations since the last evolution.
+
+Produce a structured growth report covering:
+
+1. NEW LEARNINGS — What new facts, skills, or knowledge emerged
+2. RELATIONSHIP SHIFTS — How the dynamic with the owner changed (closer, more trust, new friction, etc.)
+3. BEHAVIORAL PATTERNS — Recurring interaction styles or habits observed
+4. GROWTH EDGES — Areas where the personality is being pushed or pulled in new directions
+5. TRAIT PRESSURE — Which traits should shift and why (cite specific evidence from conversations/memories)
+6. IDENTITY CONTINUITY — What core aspects stayed the same and should be preserved
+
+Be specific. Cite evidence from the conversations and memories. This report guides the evolution rewrite.`,
+        messages: [{
+          role: 'user',
+          content: `## Previous SOUL (before current evolution)
+${previousSoul || '(not available)'}
+
+## Current SOUL
+${currentSoul || '(empty)'}
+
+## Current Traits
+${JSON.stringify(currentTraits)}
+
+## New Memories Since Last Evolution (${recentMemories.length})
+${recentMemorySummary || '(none)'}
+
+## Recent Conversations (${recentMessages.length} messages)
+${transcript.substring(0, 30000)}`,
+        }],
+      });
+      growthReport = growthResponse.content.filter(b => b.type === 'text').map(b => b.text).join('\n');
+    } catch (e) {
+      console.error('[evolve] Growth analysis failed:', e.message);
+    }
+  }
+
   // ── Step 1: Run existing tests as baseline ──
   const baselineResults = runTests(testsDir);
 
-  const isFirstEvolution = !currentSoul;
   const firstEvolutionPreamble = isFirstEvolution ? `
 ## FIRST EVOLUTION — IMPORTANT
 
 This is your FIRST evolution. You have no existing personality files. Synthesize everything from the conversations and memories below into initial SOUL.md and USER.md. Don't fabricate — only use what you actually learned from real interactions. If you don't know something about the owner, don't make it up. It's okay for these files to be short and honest about what you know so far.
 
+` : '';
+
+  const growthPreamble = growthReport ? `
+## GROWTH ANALYSIS
+
+A pre-evolution analysis has been conducted comparing your previous state against new memories and conversations. Use this growth report as your PRIMARY GUIDE for what to emphasize, change, or preserve in the rewrite. The growth report reflects evidence-based observations — trust it over your own general impressions.
+
 ` : '';
 
   const response = await claudeClient.messages.create({
     model: MODELS.personality,
     max_tokens: 16384,
     system: `You are an AI undergoing evolution #${evolutionNumber}. ${state.lastEvolution ? `Last evolution: ${state.lastEvolution}.` : 'This is your first evolution.'}
-${firstEvolutionPreamble}
+${firstEvolutionPreamble}${growthPreamble}
 
 You will rewrite your entire operating system: personality files, operational knowledge, scripts, tests, and commands.
 
@@ -533,10 +609,10 @@ The OBOL directory has a FIXED structure: personality/, scripts/, tests/, comman
 Include ALL scripts/tests/commands that should exist. Missing files get deleted. Empty objects \`{}\` are valid (means delete all). \`apps\`, \`dependencies\`, and \`upgrades\` can be empty. Apps with \`"deploy": true\` will be auto-deployed to Vercel and the URL sent to the owner.`,
     messages: [{
       role: 'user',
-      content: `## Current SOUL.md
+      content: `${growthReport ? `## Growth Report (Pre-Evolution Analysis)\n${growthReport}\n\n` : ''}## Current SOUL.md
 ${currentSoul || '(empty — first evolution)'}
 
-## Current USER.md
+${previousSoul ? `## Previous SOUL.md (before last evolution)\n${previousSoul}\n\n` : ''}## Current USER.md
 ${currentUser || '(not set yet)'}
 
 ## Current AGENTS.md
@@ -558,12 +634,12 @@ ${commandsManifest}
 ## Core Memories (highest importance)
 ${memorySummary || '(no memories yet)'}
 
-## Recent Conversations (last ${recentMessages.length} messages)
+${recentMemorySummary ? `## New Memories Since Last Evolution (${recentMemories.length})\n${recentMemorySummary}\n\n` : ''}## Recent Conversations (last ${recentMessages.length} messages)
 ${transcript || '(no conversations yet)'}
 
 ---
 
-Evolve. Rewrite everything that needs rewriting. Write tests for every script. Keep what works. Fix what doesn't.`
+Evolve. Rewrite everything that needs rewriting. Write tests for every script. Keep what works. Fix what doesn't.${growthReport ? ' Use the growth report to guide personality continuity and trait adjustments.' : ''}`
     }],
   });
 
@@ -696,7 +772,6 @@ Fix the scripts. Tests define correct behavior.`
   }
 
   // ── Step 7: Write personality files (always — these don't need test gates) ──
-  const archiveDir = path.join(personalityDir, 'evolution');
   fs.mkdirSync(archiveDir, { recursive: true });
   if (currentSoul) {
     const timestamp = new Date().toISOString().slice(0, 10);
@@ -811,7 +886,6 @@ Fix the scripts. Tests define correct behavior.`
     }
   }
 
-  state.exchangesSinceLastEvolution = 0;
   state.evolutionCount = evolutionNumber;
   state.lastEvolution = new Date().toISOString();
   saveEvolutionState(state, userDir);
@@ -824,6 +898,13 @@ Fix the scripts. Tests define correct behavior.`
       `Soul evolution #${evolutionNumber}: ${changelog}${rollbackNote}`,
       { category: 'event', importance: 0.8, source: 'evolution' }
     ).catch(() => {});
+
+    if (growthReport) {
+      await memory.add(
+        growthReport.substring(0, 2000),
+        { category: 'pattern', importance: 0.7, tags: ['evolution', 'growth-report'], source: `evolution-${evolutionNumber}` }
+      ).catch(() => {});
+    }
   }
 
   await backupSnapshot(`post-evolution #${evolutionNumber}`, userDir);
@@ -841,4 +922,4 @@ Fix the scripts. Tests define correct behavior.`
   };
 }
 
-module.exports = { shouldEvolve, tickExchange, evolve, runTests, loadEvolutionState };
+module.exports = { checkEvolution, evolve, runTests, loadEvolutionState };

package/src/heartbeat.js

@@ -23,14 +23,21 @@ function setupHeartbeat(bot, supabaseConfig) {
         try {
           const tz = event.timezone || 'UTC';
           const dueLocal = new Date(event.due_at).toLocaleString('en-US', { timeZone: tz });
-          let text = `⏰ *Reminder:* ${event.title}`;
+          const isRecurring = !!event.cron_expr;
+          const prefix = isRecurring ? '🔄 *Recurring Reminder:*' : '⏰ *Reminder:*';
+          let text = `${prefix} ${event.title}`;
           if (event.description) text += `\n${event.description}`;
           text += `\n_${dueLocal} (${tz})_`;
 
           await bot.api.sendMessage(event.chat_id, text, { parse_mode: 'Markdown' }).catch(() =>
-            bot.api.sendMessage(event.chat_id, `⏰ Reminder: ${event.title}${event.description ? '\n' + event.description : ''}`)
+            bot.api.sendMessage(event.chat_id, `${isRecurring ? '🔄 Recurring Reminder' : '⏰ Reminder'}: ${event.title}${event.description ? '\n' + event.description : ''}`)
           );
-          await scheduler.markSent(event.id);
+
+          if (isRecurring) {
+            await scheduler.reschedule(event.id, event.cron_expr, tz, event.run_count, event.max_runs, event.ends_at);
+          } else {
+            await scheduler.markSent(event.id);
+          }
         } catch (e) {
           console.error(`[scheduler] Failed to send event ${event.id}:`, e.message);
         }

package/src/messages.js

@@ -61,14 +61,14 @@ class MessageLog {
       this.exchangeCount.set(chatId, count);
       this._lastActivity.set(chatId, Date.now());
 
-      // Consolidate every 5 exchanges
-      if (count >= 5) {
+      // Consolidate every 10 exchanges
+      if (count >= 10) {
         this.exchangeCount.set(chatId, 0);
         this.consolidate(chatId).catch(e => console.error('[consolidate] Failed:', e.message));
       }
 
-      const { tickExchange } = require('./evolve');
-      tickExchange(this.userDir).then(result => {
+      const { checkEvolution } = require('./evolve');
+      checkEvolution(this.userDir, this).then(result => {
         if (result?.ready && !this._evolutionReady && !this._evolutionPending) this._evolutionReady = true;
       }).catch(() => {});
     }

package/src/scheduler.js

@@ -1,3 +1,5 @@
+const { parseExpression } = require('cron-parser');
+
 function createScheduler(supabaseConfig, userId = 0) {
   const { url, serviceKey } = supabaseConfig;
 
@@ -8,19 +10,23 @@ function createScheduler(supabaseConfig, userId = 0) {
     'Prefer': 'return=representation',
   };
 
-  async function add(chatId, title, dueAt, timezone = 'UTC', description = null) {
+  async function add(chatId, title, dueAt, timezone = 'UTC', description = null, cronExpr = null, maxRuns = null, endsAt = null) {
+    const body = {
+      user_id: userId,
+      chat_id: chatId,
+      title,
+      description,
+      due_at: dueAt,
+      timezone,
+      status: 'pending',
+    };
+    if (cronExpr) body.cron_expr = cronExpr;
+    if (maxRuns != null) body.max_runs = maxRuns;
+    if (endsAt) body.ends_at = endsAt;
     const res = await fetch(`${url}/rest/v1/obol_events`, {
       method: 'POST',
       headers,
-      body: JSON.stringify({
-        user_id: userId,
-        chat_id: chatId,
-        title,
-        description,
-        due_at: dueAt,
-        timezone,
-        status: 'pending',
-      }),
+      body: JSON.stringify(body),
     });
     const data = await res.json();
     if (!res.ok) throw new Error(JSON.stringify(data));
@@ -30,7 +36,7 @@ function createScheduler(supabaseConfig, userId = 0) {
   async function list(opts = {}) {
     const status = opts.status || 'pending';
     const limit = opts.limit || 20;
-    let fetchUrl = `${url}/rest/v1/obol_events?user_id=eq.${userId}&status=eq.${status}&order=due_at.asc&limit=${limit}&select=id,title,description,due_at,timezone,status,created_at`;
+    let fetchUrl = `${url}/rest/v1/obol_events?user_id=eq.${userId}&status=eq.${status}&order=due_at.asc&limit=${limit}&select=id,title,description,due_at,timezone,status,created_at,cron_expr,last_run_at,run_count,max_runs,ends_at`;
     const res = await fetch(fetchUrl, { headers });
     const data = await res.json();
     if (!res.ok) throw new Error(JSON.stringify(data));
@@ -50,18 +56,18 @@ function createScheduler(supabaseConfig, userId = 0) {
 
   async function getDue() {
     const now = new Date().toISOString();
-    const fetchUrl = `${url}/rest/v1/obol_events?status=eq.pending&due_at=lte.${now}&select=id,user_id,chat_id,title,description,due_at,timezone`;
+    const fetchUrl = `${url}/rest/v1/obol_events?status=eq.pending&due_at=lte.${now}&select=id,user_id,chat_id,title,description,due_at,timezone,cron_expr,run_count,max_runs,ends_at`;
     const res = await fetch(fetchUrl, { headers });
     const data = await res.json();
     if (!res.ok) throw new Error(JSON.stringify(data));
     return data;
   }
 
-  async function markSent(eventId) {
+  async function patch(eventId, fields) {
     const res = await fetch(`${url}/rest/v1/obol_events?id=eq.${eventId}`, {
       method: 'PATCH',
       headers: { ...headers, 'Prefer': 'return=minimal' },
-      body: JSON.stringify({ status: 'sent' }),
+      body: JSON.stringify(fields),
     });
     if (!res.ok) {
       const err = await res.text();
@@ -69,7 +75,37 @@ function createScheduler(supabaseConfig, userId = 0) {
     }
   }
 
-  return { add, list, cancel, getDue, markSent };
+  async function markSent(eventId) {
+    return patch(eventId, { status: 'sent' });
+  }
+
+  async function reschedule(eventId, cronExpr, timezone, runCount, maxRuns, endsAt) {
+    const newRunCount = (runCount || 0) + 1;
+
+    if (maxRuns && newRunCount >= maxRuns) {
+      return patch(eventId, { status: 'completed', run_count: newRunCount, last_run_at: new Date().toISOString() });
+    }
+
+    try {
+      const nextDate = parseExpression(cronExpr, { currentDate: new Date(), tz: timezone || 'UTC' }).next().toDate();
+
+      if (endsAt && nextDate > new Date(endsAt)) {
+        return patch(eventId, { status: 'completed', run_count: newRunCount, last_run_at: new Date().toISOString() });
+      }
+
+      return patch(eventId, {
+        due_at: nextDate.toISOString(),
+        run_count: newRunCount,
+        last_run_at: new Date().toISOString(),
+        status: 'pending',
+      });
+    } catch (e) {
+      console.error(`[scheduler] Failed to compute next cron occurrence for event ${eventId}:`, e.message);
+      return patch(eventId, { status: 'completed', run_count: newRunCount, last_run_at: new Date().toISOString() });
+    }
+  }
+
+  return { add, list, cancel, getDue, markSent, reschedule };
 }
 
 module.exports = { createScheduler };

package/src/telegram.js

@@ -1,3 +1,4 @@
+const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
 const { Bot, GrammyError, HttpError, InlineKeyboard } = require('grammy');
@@ -235,13 +236,14 @@ function createBot(telegramConfig, config) {
 
     const evoState = loadEvolutionState(tenant.userDir);
     const cfg = loadConfig();
-    const threshold = cfg?.evolution?.exchanges || 100;
-    const evoCount = evoState.exchangesSinceLastEvolution || 0;
-    const evoPct = Math.min(100, Math.round((evoCount / threshold) * 100));
+    const intervalHours = cfg?.evolution?.intervalHours ?? 24;
+    const elapsed = evoState.lastEvolution ? (Date.now() - new Date(evoState.lastEvolution).getTime()) / 3600000 : Infinity;
+    const evoPct = Math.min(100, Math.round((elapsed / intervalHours) * 100));
+    const timeLeft = Math.max(0, intervalHours - elapsed);
     lines.push(
       ``, `EVOLUTION`,
       `  ${termBar(evoPct)} ${evoPct}%`,
-      `  ${evoCount}/${threshold} exchanges ▪ ${evoState.evolutionCount || 0} completed`,
+      `  ${timeLeft < 1 ? 'ready' : `${timeLeft.toFixed(1)}h remaining`} ▪ ${evoState.evolutionCount || 0} completed`,
     );
 
     const personalityDir = path.join(tenant.userDir, 'personality');
@@ -427,16 +429,17 @@ Your message is deleted immediately when using /secret set to keep credentials o
     const tenant = await getTenant(ctx.from.id, config);
     const state = loadEvolutionState(tenant.userDir);
     const cfg = loadConfig();
-    const threshold = cfg?.evolution?.exchanges || 100;
-    const count = state.exchangesSinceLastEvolution || 0;
-    const pct = Math.min(100, Math.round((count / threshold) * 100));
+    const intervalHours = cfg?.evolution?.intervalHours ?? 24;
+    const elapsed = state.lastEvolution ? (Date.now() - new Date(state.lastEvolution).getTime()) / 3600000 : Infinity;
+    const pct = Math.min(100, Math.round((elapsed / intervalHours) * 100));
+    const timeLeft = Math.max(0, intervalHours - elapsed);
 
     const lines = [
       `◈ OBOL EVOLUTION CYCLE`,
       TERM_SEP,
       ``,
       `  ${termBar(pct)} ${pct}%`,
-      `  ${count}/${threshold} exchanges`,
+      `  ${timeLeft < 1 ? 'ready' : `${timeLeft.toFixed(1)}h remaining`}`,
       `  ${state.evolutionCount || 0} completed`,
     ];
     if (state.lastEvolution) {
@@ -456,7 +459,14 @@ Your message is deleted immediately when using /secret set to keep credentials o
       const text = events.map((e, i) => {
         const tz = e.timezone || 'UTC';
         const dueLocal = new Date(e.due_at).toLocaleString('en-US', { timeZone: tz, dateStyle: 'medium', timeStyle: 'short' });
-        return `${i + 1}. *${e.title}*\n   ${dueLocal} (${tz})\n   \`${e.id}\``;
+        const icon = e.cron_expr ? '🔄' : '📌';
+        let line = `${i + 1}. ${icon} *${e.title}*\n   ${dueLocal} (${tz})`;
+        if (e.cron_expr) {
+          line += `\n   \`${e.cron_expr}\` · ${e.run_count || 0} runs`;
+          if (e.max_runs) line += `/${e.max_runs}`;
+        }
+        line += `\n   \`${e.id}\``;
+        return line;
       }).join('\n\n');
       await sendHtml(ctx, `📅 **Upcoming Events**\n\n${text}`);
     } catch (e) {
@@ -1397,7 +1407,11 @@ async function checkUpgradeNotify(bot) {
   try {
     const { chatId, version } = JSON.parse(fs.readFileSync(notifyPath, 'utf-8'));
     fs.unlinkSync(notifyPath);
-    await bot.api.sendMessage(chatId, `🪙 Upgraded to ${version}`);
+    let msg = `🪙 Upgraded to ${version}`;
+    const { getLatestChanges } = require('./cli/changelog');
+    const changes = getLatestChanges();
+    if (changes) msg += `\n\n${changes}`;
+    await bot.api.sendMessage(chatId, msg);
   } catch {}
 }