Proactive Engine

The idea

Most AI tools wait for you to ask. The Proactive Engine flips this: you tell AI Partner what to monitor and when, and it acts on its own schedule — checking your markets, reading your news, reviewing your goals, and pushing results to your preferred channel before you even sit down at your desk.

With V3, the Proactive view is also the home of your Digital Twin — the partner layer that remembers you permanently, challenges your drift, and earns the right to act in your name.

V3 — the twin lives here

The Your Twin panel sits inside the Proactive view. It is the in-app counterpart to everything the twin does over your messaging channel:

Needs you — pending twin asks (weekly confrontations, delegation drafts) answered in-app with the same engage / adjust / back_off buttons as Telegram
Open threads — questions the twin is holding open until you resolve them deliberately; overruling it never silently closes one
Positions — the evidence-backed claims it currently holds about you, each dated, with its revision history
Action feed — everything done under earned delegation, each action with a receipt
Trust streaks — live clean-approval progress per action class; one tap revokes a delegation instantly and restarts its streak from zero
Charter — the current CHARTER.md, the source of all twin standing

Heartbeat vs. twin schedule

The twin runs on its own charter-driven schedule — it never reads HEARTBEAT.md:

	Heartbeat	Twin
Driven by	`HEARTBEAT.md` standing tasks + LLM judgment	`CHARTER.md` granted domains + `GOALS.md` arcs
Cadence	Your tick interval (default: every 30 min in active hours)	At most one confrontation per week; daily digest at 09:00
Output	Briefings, market watches, summaries	Evidence-gated challenges; "while you were away" digest with receipts
When there's nothing	Skips the tick, checks next tick	Sends no message — silence is never noise

Both deliver over the same messaging channels configured below. For charter configuration, earned delegation, and per-user isolation on a multi-user VPS, see the Digital Twin guide.

How the heartbeat works

A background process runs a cron tick at your configured interval (default: every 30 minutes during active hours):

Tick fires
    ↓
HeartbeatService: within active hours? → yes
HeartbeatService: last action < 25 min ago? → no (25-min cooldown)
    ↓
ProactiveAgenda.evaluate():
    1. HEARTBEAT.md standing tasks — any due this tick?
    2. Memory interests — any ongoing goal nearing a deadline?
    3. LLM judgment: "Is there ONE genuinely useful action right now?"
    ↓
Yes → the goal engine runs the chosen action
      → result delivered to Telegram/Discord/Slack/chat
      → logged to heartbeat_logs
No  → skip, check again next tick

The 25-minute cooldown prevents the engine from spamming you even if multiple things are due at the same time.

Configuration files

The proactive engine reads four files in workspace/. Edit them in Settings → Workspace or directly:

HEARTBEAT.md — your standing tasks

## Standing Tasks

### Morning Briefing
- Time: every weekday at 7:00 AM
- Tasks:
  1. Top 5 tech and startup news stories from the last 24 hours
  2. Check stock prices: NIFTY 50, RELIANCE.NS, INFY.NS
  3. Flag any urgent emails that arrived overnight
  4. Assess progress on active goals

### Market Watch
- Time: weekdays at 9:15 AM and 3:30 PM IST
- Tasks:
  1. NIFTY 50 open/close and day change
  2. Any holdings with >2% intraday move
  3. Significant news from top 5 holdings

### Weekly Summary
- Time: every Friday at 5:00 PM
- Tasks:
  1. Summarize all meetings from this week
  2. List action items and completion status
  3. Top 3 priorities for next week based on GOALS.md

SOUL.md — behavior rules and active hours

## Identity
Name: Alex
Role: Founder & CEO

## Active Hours
active_hours: 6:00 AM - 10:00 PM IST
quiet_hours:
  - 10:00 PM - 6:00 AM
  - Sunday

## Heartbeat Settings
heartbeat_interval: 30m
cooldown: 25m

## Behavior
- Be concise — I read these on my phone
- Lead with the most important signal first
- Use bullet points for lists, not paragraphs
- For market data: bold anything that moved >1%

GOALS.md — drives relevance filtering

The ProactiveAgenda reads your active goals and uses them to decide what's relevant:

## Active Goals

### Close Series A
- Success: Term sheet signed by June 30, 2026
- Context: In conversations with Sequoia, Accel, and Tiger Global

### Launch v2.0
- Success: 1,000 active users by July 15, 2026

If the ProactiveAgenda sees a news story about Sequoia, it's relevant. A story about cooking recipes is not. The goals serve as a relevance filter.

What gets delivered

All proactive output goes to the Telegram/Discord/Slack channel you configured in Settings → Messaging. The format is compact (optimized for phone reading):

🌅 Morning Briefing — Wed, May 13

📰 News
1. OpenAI launches GPT-5 — real-time web access built in [TechCrunch]
2. Sequoia India closes $2.5B fund [ET]
3. Apple expands Intelligence to 40 countries [The Verge]

📈 Markets (as of 6:58 AM)
NIFTY:     22,845 (+0.4%)
RELIANCE:  ₹2,847 (+0.8%)  ← above 1% threshold
INFY:      ₹1,634 (-0.2%)

📧 Overnight Email
⚠️ sarah@acme.com: "Q2 concern — need to talk today" [Reply]

🎯 Goals
Series A: 🟡 Sequoia call Thu — key milestone
v2.0:     🟢 Phase 2 on track

Enabling / disabling

Enable: Go to Settings → Proactive Intelligence → toggle Heartbeat: On

Or set in .env:

HEARTBEAT_ENABLED=true
HEARTBEAT_INTERVAL_MINUTES=30

Pause temporarily:

Pause the heartbeat for the next 4 hours.

Disable a specific task: Comment it out in HEARTBEAT.md:

# - Time: weekdays at 9:15 AM  ← disabled

Triggering manually

Don't want to wait for the next tick? Run a heartbeat manually:

Via chat:

Run my morning briefing now.

Via the UI: Go to sidebar → Proactive Intelligence → Run Now

Via API:

curl -X POST http://localhost:3000/api/heartbeat/trigger

Standing tasks vs. LLM-driven tasks

There are two modes the ProactiveAgenda can operate in:

Mode	What drives it	Best for
Standing tasks	HEARTBEAT.md — explicit schedule and task list	Predictable, recurring tasks: market data, news digest
LLM-driven	ProactiveAgenda.evaluate() uses LLM judgment	Opportunistic tasks: "Is there something useful to do right now based on my goals?"

Standing tasks always run if it's the scheduled time. LLM-driven tasks fill the gaps — the agent evaluates whether to act on any tick where no standing task is due.

To disable LLM-driven decisions (standing tasks only):

HEARTBEAT_LLM_DRIVEN=false

Time zone and IST-aware context

The heartbeat service is IST-aware by default. Some built-in logic:

Context	Time window
Morning briefing window	7:00 AM – 11:00 AM IST
NSE/BSE market hours	9:15 AM – 3:30 PM IST, weekdays
Evening recap window	6:00 PM – 9:00 PM IST
Quiet hours	Configurable in SOUL.md

Financial and market tasks are automatically filtered outside market hours (unless you override this in HEARTBEAT.md).

Set your timezone in .env:

TZ=Asia/Kolkata

Delivery channels

Channel	Setup	Best for
Telegram	Settings → Messaging → Telegram	Default — inline buttons for approvals, file delivery
Discord	Settings → Messaging → Discord	Team briefings via a channel
Slack	Settings → Messaging → Slack	Work context — post to a channel
Chat (in-UI)	Always available	Results appear in the active chat conversation

You can configure multiple delivery channels — results are sent to all active ones.

Viewing heartbeat history

Go to sidebar → Proactive Intelligence → History to see:

When each tick fired
What task was chosen (or why it was skipped)
What the result was
Whether it was delivered successfully

Or via API:

curl http://localhost:3000/api/heartbeat/logs?limit=50

The idea​

V3 — the twin lives here​

Heartbeat vs. twin schedule​

How the heartbeat works​

Configuration files​

HEARTBEAT.md — your standing tasks​

SOUL.md — behavior rules and active hours​

GOALS.md — drives relevance filtering​

What gets delivered​

Enabling / disabling​

Triggering manually​

Standing tasks vs. LLM-driven tasks​

Time zone and IST-aware context​

Delivery channels​

Viewing heartbeat history​