Flow Mesh — Intelligence Layer
Status: Implemented (Intelligence V2, commit 604f360+) Related: HOOKS.md (provider system), DISTRO.md (distribution), SCOPE.md (current spec) Dependencies: pi (coding agent), pi-agent-core + pi-ai (LLM engine)
What It Is
An AI orchestration layer that lets humans talk to Flow Mesh in natural language through any chat platform. It understands intent, delegates coding work to pi, manages tasks through the mesh CLI, and reports results — all without a human opening a terminal.
PM in Slack: "the auth page is broken, users can't log in"
Intelligence:
1. Understands: this is a bug report about authentication
2. Checks mesh: finds project-alpha, looks at recent events
3. Investigates: pi -p "Read session.go, identify auth issues"
4. Fixes: pi -p --model opus:high "Fix the race condition, add tests"
5. Tracks: mesh task create "Auth fix" → mesh task close
6. Reports: "Fixed — session race condition. 3 tests added. PR #142."
PM in Slack sees: "Fixed ✓ — PR #142 ready for review"
The PM never left Slack. Never opened a terminal. Described a problem in English, got a fix.
Architecture
┌─────────────────────────────────────────────────────────────┐
│ │
│ Humans │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Slack │ │ Discord │ │ Web Chat │ │ Terminal │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ └──────────────┴─────────────┴──────────────┘ │
│ │ │
│ ┌─────────▼──────────┐ │
│ │ │ │
│ │ INTELLIGENCE │ │
│ │ │ │
│ │ pi-agent-core │ ← LLM (chat model) │
│ │ + pi-ai │ understands intent │
│ │ │ maintains memory │
│ │ Multi-transport │ orchestrates work │
│ │ Delegation policy │ │
│ │ Spending limits │ │
│ │ Per-mesh perms │ │
│ │ │ │
│ └──┬──────────┬──────┘ │
│ │ │ │
│ ┌────────▼──┐ ┌───▼────────────┐ │
│ │ mesh CLI │ │ pi -p │ │
│ │ │ │ (headless) │ │
│ │ task CRUD │ │ │ │
│ │ conflicts │ │ reads code │ ← LLM │
│ │ events │ │ writes fixes │ (coding model) │
│ │ sync ctrl │ │ runs tests │ heavier model │
│ │ │ │ commits │ only when needed│
│ └─────┬─────┘ └───────────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ Flow Mesh │ │
│ │ Engine │ │
│ │ │ │
│ │ Event Ledger │ │
│ │ Policy Engine │ │
│ │ Projectors │ │
│ └────────┬────────┘ │
│ │ │
│ ┌──────────┼──────────┬──────────┐ │
│ ▼ ▼ ▼ ▼ │
│ Asana GitHub Obsidian Slack/Discord │
│ Linear Issues Notion (notifications) │
│ Jira │
│ │
└─────────────────────────────────────────────────────────────┘
Two-Model Strategy
The intelligence layer uses two different LLM configurations for different purposes:
| Layer | Purpose | Model | Why |
|---|---|---|---|
| Chat model | Understand human messages, orchestrate, summarize, respond | Lightweight (Haiku, Sonnet) | Fast response, cheap, conversational |
| Coding model | Read code, edit files, run tests, commit | Heavy (Sonnet:high, Opus) | Thorough, precise, expensive — only invoked when needed |
The chat model runs on every message. The coding model only runs when the intelligence decides code changes are needed. A status check costs fractions of a cent. A code fix costs the going rate for the coding model — but only when triggered.
"what's the status of project X?" → chat model only (~$0.002)
"fix the typo in README" → chat + coding haiku (~$0.01)
"refactor auth to use JWT" → chat + coding opus:high (~$0.50)
"deploy to production" → chat only, refused by policy ($0.002)
Transports
The intelligence layer speaks to humans through multiple chat platforms simultaneously. Each transport implements the same interface:
Transport:
connect() → establish connection
onMessage(callback) → incoming messages
send(channelId, text, opts) → post a message
reply(threadId, text, opts) → reply in thread
react(messageId, emoji) → add reaction
uploadFile(channelId, file) → attach file
getChannelInfo(id) → name, members, type
getUserInfo(id) → name, email, avatar
Slack Transport
Uses Socket Mode (same as pi-mom). Requires: Slack is a driver name the provider contract allows, not an implementation this build ships: there is no Slack adapter and no Slack credential is read. When one is added it follows the same generic provider contract as Asana, Discord, Google Tasks and SendyKit.
Activated by @mention or DM. Responds in threads for detail, top-level for summaries.
Discord Transport
Uses Gateway WebSocket. Requires:
- Discord Bot Token (reuses existing Flow Mesh Discord connection)
Activated by @mention. Uses forum threads or reply chains.
Web Transport
Built into the Flow Mesh UI at /chat. WebSocket connection. No external service required.
┌─────────────────────────────────────────────┐
│ Flow Mesh Dashboard │
│ │
│ ● 3 meshes active ● 0 conflicts │
│ │
│ ─── Chat ──────────────────────────── │
│ ┌───────────────────────────────────────┐ │
│ │ You: what's behind schedule? │ │
│ │ │ │
│ │ Mesh: 2 tasks overdue in alpha: │ │
│ │ • TASK-201 "Rate limiting" (4d) │ │
│ │ • TASK-189 "Onboarding" (2d) │ │
│ │ │ │
│ │ You: assign 189 to sarah and ping her │ │
│ │ │ │
│ │ Mesh: Done. │ │
│ │ → Assigned to @sarah in Asana ✓ │ │
│ │ → Notified in #dev-alpha Slack ✓ │ │
│ │ → Updated beads ✓ │ │
│ │ │ │
│ │ [Type a message...] [Send] │ │
│ └───────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────┘
No Slack or Discord account required. Talk to your mesh directly from the dashboard.
CLI Transport
For agents and scripts that want conversational interaction without a chat platform:
# One-shot
mesh ask "what's behind schedule in project-alpha?"
# Interactive
mesh chat --mesh project-alpha
> what's the status?
2 tasks in progress, 1 overdue...
> fix the overdue one
Investigating... found issue in rate_limiter.go...
[delegates to pi -p]
Fixed. PR #143 created.
> thanks
Delegation Engine
When the intelligence layer decides code work is needed, it delegates to pi running in headless mode on the VPS.
How Delegation Works
Intelligence receives: "fix the auth bug"
│
▼
┌─────────────────────────────────────┐
│ 1. Check delegation policy │
│ modify_code: "ask" → ask human │
│ modify_code: "auto" → proceed │
│ modify_code: "never" → suggest │
└──────────┬──────────────────────────┘
│ (policy says "auto" or human confirmed)
▼
┌─────────────────────────────────────┐
│ 2. Check per-mesh permissions │
│ project-alpha: "full" → proceed │
│ client-site: "disabled" → refuse │
└──────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 3. Check spending limit │
│ $3.20 / $5.00 today → proceed │
│ $5.00 / $5.00 today → refuse │
└──────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 4. Select coding model │
│ Simple fix → haiku │
│ Complex refactor → opus:high │
│ (configurable per task type) │
└──────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 5. Invoke pi │
│ pi -p --model {selected} │
│ --mode json │
│ --session /data/fm/sessions/ │
│ "Fix the auth race condition │
│ in /data/project/session.go" │
└──────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 6. Parse pi output │
│ What files changed? │
│ Did tests pass? │
│ Was a commit made? │
└──────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 7. Update mesh │
│ mesh task update/close │
│ → syncs to all connected systems │
└──────────┬──────────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 8. Report to human │
│ Summary in chat │
│ Details in thread │
└─────────────────────────────────────┘
Multi-Step Sessions
Complex tasks use pi's session continuity. The intelligence layer orchestrates multiple invocations:
# Step 1: Investigate
pi -p --model sonnet --mode json \
--session /data/fm/sessions/task-456 \
"Investigate auth failures in session.go. Report findings."
# Intelligence reads output, decides a fix is needed
# Step 2: Fix
pi -p --model opus:high --mode json \
--session /data/fm/sessions/task-456 \
-c "Fix the race condition you found. Add mutex locking. Write tests."
# Intelligence reads output, checks if tests passed
# Step 3: Verify (if tests failed)
pi -p --model sonnet --mode json \
--session /data/fm/sessions/task-456 \
-c "Tests failed on line 42. Fix the assertion and re-run."
# Step 4: Ship
pi -p --model haiku --mode json \
--session /data/fm/sessions/task-456 \
-c "All tests pass. Create a conventional commit."
Each step uses the cheapest model that fits. Investigation and verification use Sonnet. The actual fix uses Opus. The commit uses Haiku. The session flag (-c) means pi remembers everything from previous steps.
pi Invocation Details
pi -p \
--provider anthropic \
--model claude-sonnet-4-5 \
--thinking high \
--mode json \
--session /data/flow-mesh/intelligence/sessions/{task-id} \
--system-prompt "You are working on behalf of Flow Mesh intelligence.
Project: {mesh_name}. Repo: {repo_path}.
Task: {task_title}. Context: {task_description}.
Rules: Make minimal changes. Write tests. Use conventional commits." \
"{user's request translated to specific coding instructions}"
| Flag | Purpose |
|---|---|
-p |
Headless mode — no TUI, process and exit |
--provider / --model |
From intelligence config (UI-configurable) |
--thinking |
From intelligence config |
--mode json |
Structured output for parsing |
--session |
Persistent session per task for multi-step work |
--system-prompt |
Inject mesh context (project, repo, task info) |
-c |
Continue previous session (for multi-step) |
Memory
The intelligence layer maintains memory across conversations, modeled after pi-mom's MEMORY.md pattern:
/data/flow-mesh/intelligence/
MEMORY.md # Global: team conventions, preferences
channels/
slack-C123ABC/
MEMORY.md # Channel-specific context
log.jsonl # Full message history
context.jsonl # LLM context window
discord-987654/
MEMORY.md
log.jsonl
context.jsonl
web-default/
MEMORY.md
log.jsonl
context.jsonl
sessions/
task-456/ # pi session files per delegated task
task-789/
Global Memory (auto-populated from mesh state)
## Team
- PM: Sarah (Slack @sarah, Asana [email protected])
- Dev: Alex (GitHub @alex, beads author)
- Design: Jordan (Slack @jordan)
## Conventions
- Commit style: conventional commits (feat/fix/refactor)
- Branch naming: feature/{task-id}-{slug}
- PR required for all production code changes
- Tests must pass before merge
## Meshes
- project-alpha: Asana "Alpha" + GitHub org/alpha + #dev-alpha Slack
- Active, 12 open tasks, 3 overdue
- PM: Sarah. Lead dev: Alex.
- project-beta: Linear "Beta" + GitHub org/beta + #dev-beta Slack
- Paused (waiting on design review)
## Preferences
- Sarah prefers summaries, not technical details
- Alex wants code snippets in responses
- Daily standup summary at 9am PT in #general
The intelligence auto-updates mesh state in memory by running mesh task list --format json periodically. Human preferences are learned from conversation and stored.
Scheduled Events
Same pattern as pi-mom — JSON files that trigger the intelligence on a schedule:
{
"type": "periodic",
"channelId": "slack-C123ABC",
"text": "Daily standup: summarize yesterday's progress, today's plan, and blockers",
"schedule": "0 9 * * 1-5",
"timezone": "America/Los_Angeles"
}
{
"type": "periodic",
"channelId": "slack-C123ABC",
"text": "Check for mesh conflicts and overdue tasks. Report if any.",
"schedule": "*/15 * * * *",
"timezone": "America/Los_Angeles"
}
The intelligence runs the checks, posts only when there's something to report (silent otherwise).
Configuration
All configurable from the Flow Mesh UI at /setup and stored in the database.
Database Tables
-- Intelligence configuration
intelligence_config (
key TEXT PRIMARY KEY,
value TEXT NOT NULL,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
-- Per-mesh intelligence permissions
intelligence_permissions (
mesh_id TEXT NOT NULL REFERENCES project_spaces(id),
access TEXT NOT NULL DEFAULT 'full'
CHECK(access IN ('full','read_only','disabled')),
PRIMARY KEY (mesh_id)
);
-- Delegation audit log
intelligence_delegations (
id TEXT PRIMARY KEY,
mesh_id TEXT,
channel_id TEXT NOT NULL,
user_id TEXT NOT NULL,
request TEXT NOT NULL, -- what the human asked
action TEXT NOT NULL, -- what intelligence did
model_used TEXT NOT NULL, -- which model was invoked
tokens_in INTEGER DEFAULT 0,
tokens_out INTEGER DEFAULT 0,
cost_estimate REAL DEFAULT 0, -- USD
pi_session TEXT, -- session path if pi was invoked
status TEXT NOT NULL DEFAULT 'pending'
CHECK(status IN ('pending','approved','running','completed','failed','refused')),
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
completed_at DATETIME
);
-- Spending tracking
intelligence_spending (
date TEXT NOT NULL, -- YYYY-MM-DD
provider TEXT NOT NULL,
model TEXT NOT NULL,
tokens_in INTEGER DEFAULT 0,
tokens_out INTEGER DEFAULT 0,
cost_estimate REAL DEFAULT 0,
delegations INTEGER DEFAULT 0,
PRIMARY KEY (date, provider, model)
);
Config Keys (intelligence_config table)
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
bool | false |
Master switch |
chat_provider |
string | anthropic |
LLM provider for conversation |
chat_model |
string | claude-haiku-4-5 |
Model for conversation |
chat_thinking |
string | off |
Thinking level for chat |
chat_api_key |
string | (env var) | API key (prefer FLOW_MESH_INTELLIGENCE_API_KEY) |
coding_provider |
string | anthropic |
LLM provider for pi delegation |
coding_model |
string | claude-sonnet-4-5 |
Model for coding |
coding_thinking |
string | high |
Thinking level for coding |
coding_api_key |
string | (env var) | API key for the coding model; the config key is authoritative — no environment variable is read for it today |
transport_slack |
bool | false |
Enable Slack transport |
transport_discord |
bool | false |
Enable Discord transport |
transport_web |
bool | true |
Enable web chat widget |
policy_create_tasks |
string | auto |
auto / ask / never |
policy_modify_code |
string | ask |
auto / ask / never |
policy_fix_bugs |
string | ask |
auto / ask / never |
policy_run_tests |
string | auto |
auto / ask / never |
policy_deploy |
string | never |
auto / ask / never |
spending_limit_day |
float | 5.00 |
Daily USD limit |
standup_enabled |
bool | false |
Daily standup summary |
standup_schedule |
string | 0 9 * * 1-5 |
Cron for standup |
standup_channel |
string | Channel ID for standup | |
conflict_check_interval |
int | 15 |
Minutes between conflict checks |
Environment Variables
| Variable | Description |
|---|---|
FLOW_MESH_INTELLIGENCE_API_KEY |
Primary API key for the intelligence chat model |
FLOW_MESH_GROQ_API_KEY |
Alternative provider key |
coding_api_key has no environment variable; it is read from config.yaml. An earlier draft of this document promised FLOW_MESH_CODING_API_KEY and Slack credentials, neither of which this build reads — Slack is a driver name the provider contract allows, not an adapter that ships here.
Where a variable exists it takes precedence over the stored value, and a secret belongs in the environment or a 0600 config file rather than the UI, for the same reason the Asana token does.
UI Pages
Setup: Intelligence Section
On the existing /setup page, after the connection cards:
┌─────────────────────────────────────────────────────────┐
│ Intelligence │
│ │
│ Enable Intelligence [━━━━━━●] ON │
│ │
│ ┌─── Chat Model ─────────────────────────────────────┐ │
│ │ Provider [anthropic ▼] │ │
│ │ Model [claude-haiku-4-5 ▼] ← populated from │ │
│ │ Thinking [off ▼] pi --list-models│ │
│ │ API Key [••••••••••••••••] or FLOW_MESH_INTEL...│ │
│ │ [Test] ● Connected │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ ┌─── Coding Model ──────────────────────────────────┐ │
│ │ Provider [anthropic ▼] │ │
│ │ Model [claude-sonnet-4-5 ▼] │ │
│ │ Thinking [high ▼] │ │
│ │ API Key [use chat key ✓ / ••••] │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ ┌─── Transports ────────────────────────────────────┐ │
│ │ ☑ Web chat (built-in, no config needed) │ │
│ │ ☑ Slack Bot Token [••••••] App Token [••••••] │ │
│ │ ☑ Discord (reuses existing connection) │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ ┌─── Delegation Policy ─────────────────────────────┐ │
│ │ Create tasks [auto ▼] │ │
│ │ Fix bugs [ask first ▼] │ │
│ │ Modify code [ask first ▼] │ │
│ │ Run tests [auto ▼] │ │
│ │ Deploy [never ▼] │ │
│ │ Daily spending limit [$5.00 ___] │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ ┌─── Mesh Permissions ──────────────────────────────┐ │
│ │ project-alpha [full access ▼] ● active │ │
│ │ project-beta [read only ▼] ● paused │ │
│ │ client-site [disabled ▼] ● active │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ ┌─── Scheduled ─────────────────────────────────────┐ │
│ │ ☑ Daily standup [09:00] [PT ▼] [#general ▼] │ │
│ │ ☑ Conflict check every [15] minutes │ │
│ │ ☐ Weekly digest [Mon 09:00] [PT ▼] │ │
│ └────────────────────────────────────────────────────┘ │
│ │
│ [Save] │
│ │
└─────────────────────────────────────────────────────────┘
Dashboard: Spending Card
On the main / dashboard, a new card showing intelligence activity:
┌─────────────────────────────────────────────┐
│ Intelligence today $1.24 / $5.00 │
│ ████████░░░░░░░░░░░ 24% │
│ │
│ 7 conversations · 3 delegations · 0 refused │
│ │
│ Recent: │
│ • Fixed auth race condition (sonnet, $0.45) │
│ • Created 2 tasks from standup ($0.02) │
│ • Resolved conflict on TASK-201 ($0.01) │
└─────────────────────────────────────────────┘
New Page: /intelligence
Dedicated page for intelligence history and management:
┌─────────────────────────────────────────────────────────┐
│ Intelligence │
│ │
│ ─── Activity Log ────────────────────────────────── │
│ │
│ 14:23 Slack #dev-alpha · @sarah │
│ "fix the auth bug" │
│ → Delegated to pi (sonnet:high) │
│ → Fixed session.go:142, 3 tests added │
│ → TASK-456 closed · $0.45 │
│ │
│ 14:15 Discord #general · @alex │
│ "what conflicts need resolving?" │
│ → Reported 2 conflicts │
│ → Chat only · $0.002 │
│ │
│ 09:00 Scheduled · Daily standup │
│ → Summarized 5 completed, 2 overdue │
│ → Posted to Slack #general · $0.01 │
│ │
│ ─── Spending ────────────────────────────────────── │
│ │
│ Today $1.24 / $5.00 ████████░░░░░░░ 24% │
│ This week $8.50 avg $1.70/day │
│ This month $34.20 avg $1.71/day │
│ │
│ By model: │
│ haiku-4-5 412 calls $0.82 │
│ sonnet-4-5 23 calls $12.40 │
│ opus-4-5 3 calls $20.98 │
│ │
│ ─── Pending Approvals ───────────────────────────── │
│ │
│ @sarah asked: "refactor the payment module" │
│ Policy: modify_code = ask │
│ Estimated cost: ~$2.00 (opus:high) │
│ [Approve] [Refuse] [Change Model ▼] │
│ │
└─────────────────────────────────────────────────────────┘
Web Chat Widget
On every page, a collapsible chat panel in the bottom-right corner:
┌──────────┐
│ 💬 Chat │
└────┬─────┘
│ click
┌──────────▼──────────┐
│ Flow Mesh │
│ │
│ What's overdue? │
│ │
│ ┌──────────────────┐ │
│ │ 2 tasks overdue: │ │
│ │ • TASK-201 (4d) │ │
│ │ • TASK-189 (2d) │ │
│ └──────────────────┘ │
│ │
│ [Type here...] [⏎] │
└─────────────────────┘
Powered by a WebSocket to /ws/chat. Uses the same intelligence engine as Slack/Discord. Available even without any external chat platform configured.
Delegation Policy Reference
Each action type has three modes:
| Mode | Behavior |
|---|---|
| auto | Intelligence acts immediately. Reports what it did afterward. |
| ask | Intelligence explains what it would do and waits for confirmation in chat. "I can fix this by adding a mutex to session.go. Should I proceed?" Human replies yes/no. |
| never | Intelligence describes the issue and suggests a fix but never executes. "This looks like a race condition. You'd need to add a mutex to session.go:142." |
Default Policies
| Action | Default | Rationale |
|---|---|---|
create_tasks |
auto |
Low risk — creating a task is easily undone |
fix_bugs |
ask |
Medium risk — changes code, but targeted |
modify_code |
ask |
Medium risk — broader code changes |
run_tests |
auto |
No risk — read-only, informational |
deploy |
never |
High risk — production impact |
Spending Limit
When spending_limit_day is reached:
- No new pi delegations (coding model stops)
- Chat model continues (conversation is cheap)
- Intelligence reports: "Daily spending limit reached ($5.00). I can still answer questions but can't make code changes until tomorrow."
- Limit resets at midnight in the configured timezone
Per-Mesh Permissions
| Access Level | Intelligence Can... |
|---|---|
| full | Read code, write code, create/update/close tasks, run tests |
| read_only | Read code, report status, answer questions. Cannot modify files or tasks. |
| disabled | Intelligence ignores this mesh entirely. Won't report on it or accept commands for it. |
Interaction Patterns
Pattern 1: Status Check (chat model only)
Human: what's happening on project-alpha?
Intelligence:
→ mesh task list --mesh project-alpha --format json
→ Parses JSON, summarizes
"project-alpha: 12 tasks open, 3 in progress, 2 overdue.
TASK-201 'Rate limiting' is 4 days overdue (assigned to agent).
TASK-189 'Onboarding flow' is 2 days overdue (unassigned)."
Cost: ~$0.002. No pi invocation.
Pattern 2: Task Management (chat model + mesh CLI)
Human: create a task for adding dark mode support, assign to alex, high priority
Intelligence:
→ mesh task create "Add dark mode support" \
--mesh project-alpha --priority high --assign alex
→ mesh task show TASK-567 --format json
"Created TASK-567 'Add dark mode support' — high priority, assigned to @alex.
Synced to: Asana ✓ GitHub Issue #94 ✓"
Cost: ~$0.003. No pi invocation.
Pattern 3: Bug Fix (chat model + coding model)
Human: the login page throws a 500 error when email has a plus sign
Intelligence:
→ Checks policy: fix_bugs = "ask"
"I can investigate and fix this. The issue is likely in email validation.
Estimated cost: ~$0.20 (sonnet). Proceed?"
Human: "yes, go ahead"
Intelligence:
-> pi -p --model sonnet:high --mode json
"Investigate and fix: login 500 error when email contains +.
Repo: /data/project-alpha. Look at email validation."
-> pi finds url.QueryEscape used instead of proper email parsing
-> pi fixes validation, adds test for plus-sign emails
-> pi runs tests: all passing
-> mesh task create "Fix email validation for + characters" --mesh project-alpha
-> mesh task close TASK-568 --note "Fixed url.QueryEscape, added test"
"Fixed. The email validator was URL-encoding the + sign.
Changed to proper RFC 5321 parsing. Test added. Commit abc123."
Cost: ~$0.25 (chat model for conversation + coding model for the fix).
Pattern 4: Conflict Resolution (chat model + mesh CLI)
Human: any conflicts?
Intelligence:
-> mesh conflicts --format json
"2 conflicts in project-alpha:
1. TASK-456 'Auth refactor' - Asana says 'review', GitHub says 'in progress'
Last human edit: Asana (PM moved it 2hr ago)
2. TASK-501 'DB migration' - description differs
Asana has client language, beads has technical spec.
Recommend accepting Asana for both (PM edits were more recent)."
Human: "do it"
Intelligence:
-> mesh resolve CONFLICT-1 --winner asana
-> mesh resolve CONFLICT-2 --winner asana
"Resolved both. Asana version pushed to all systems."
Cost: ~$0.003. No pi invocation.
Pattern 5: Proactive Alert (scheduled event)
[No human trigger — scheduled conflict check fires]
Intelligence:
-> mesh conflicts --format json
-> mesh events --state failed --since 1h --format json
Finds: 3 failed projections to Asana (rate limited)
Posts to #dev-alpha:
"Heads up: Asana sync is failing (rate limited). 3 events stuck.
This usually resolves in ~15 minutes. I'll retry automatically.
Ping me if it's still stuck in 30 min."
Cost: ~$0.002. Proactive, no human triggered it.
Pattern 6: Complex Refactor (multi-step delegation)
Human: "refactor the payment module to use Stripe instead of Braintree"
Intelligence:
-> Checks policy: modify_code = "ask"
-> Checks spending: $1.20 / $5.00
"This is a significant refactor. I'd approach it in steps:
1. Audit current Braintree usage (~$0.10, sonnet)
2. Design Stripe integration (~$0.10, sonnet)
3. Implement changes (~$1.50, opus:high)
4. Update tests (~$0.50, sonnet:high)
5. Run full test suite (~$0.00, no LLM)
Total estimate: ~$2.20. This would use most of today's budget.
Should I proceed with step 1 first?"
Human: "do step 1, then tell me what you find before continuing"
Intelligence:
-> pi -p --model sonnet --mode json
--session /data/fm/sessions/payment-refactor
"Audit all Braintree usage in /data/project-alpha.
List every file, function, and API call. Report findings."
"Audit complete. Braintree is used in 4 files:
- payment/client.go (API calls: charge, refund, subscribe)
- payment/webhook.go (event handler)
- payment/models.go (Braintree-specific types)
- api/checkout.go (handler calling payment.Charge)
12 functions, 3 webhook types, 2 cron jobs.
The models are tightly coupled — Stripe equivalents exist for all of them.
Estimated 400 lines of changes. Want me to proceed with the Stripe design?"
Cost: $0.10 for audit. Full refactor deferred until human approves each step.
Security
Principle of Least Privilege
The intelligence layer should run with the minimum permissions needed:
- Coding model runs as the Flow Mesh service user, not root
- Per-mesh permissions restrict which repos can be modified
- Delegation policy prevents autonomous destructive actions
- Spending limits cap runaway costs
Prompt Injection
Same risks as pi-mom: malicious content in task descriptions, PR bodies, or comments could inject instructions. Mitigations:
- Intelligence never executes raw user content as code
- pi's system prompt overrides injected instructions
- Code changes go through git (reviewable, revertable)
- Delegation policy
askmode requires human confirmation for code changes nevermode for deploy means no production impact regardless of injection
Credential Isolation
- Intelligence API keys are separate from provider credentials
- pi runs in the project directory, not the Flow Mesh directory
- pi cannot access Flow Mesh's database or config
- Coding model sees only the project repo, not other meshes
Audit Trail
Every delegation is logged in intelligence_delegations:
- Who asked (user ID, channel)
- What they asked (original message)
- What intelligence did (action taken)
- What model was used
- How much it cost
- Whether it succeeded or failed
- pi session path for full replay
Implementation Phases
Phase 1: Web Chat Only
- Intelligence engine using
pi-agent-core+pi-ai - Web transport only (
/ws/chatWebSocket) meshCLI as the primary skill- No pi delegation yet — chat model answers questions and manages tasks
- Setup UI for model selection and API key
- Cost tracking in
intelligence_spendingtable
This is the MVP. A chat widget on the dashboard that can answer "what's overdue?" and "create a task for X." No external chat platforms, no coding delegation. Test the intelligence engine in isolation.
Phase 2: Pi Delegation
- Add pi
-pinvocation from intelligence - Delegation policy enforcement
- Spending limits
- Session management for multi-step work
- Activity log on
/intelligencepage
Phase 3: External Transports
- Slack transport (Socket Mode)
- Discord transport (Gateway WebSocket)
- Per-channel memory and context
- Scheduled events (standup, conflict checks)
Phase 4: Advanced
- CLI transport (
mesh ask,mesh chat) - Approval queue (for
askpolicy mode) - Weekly digest emails
- Model auto-selection based on task complexity
- Cost optimization (route simple tasks to cheapest capable model)
Relationship to Other Docs
| Doc | Covers | Intelligence Touches |
|---|---|---|
SCOPE.md |
Current implementation (17 sections) | Intelligence is a new section (§18) |
HOOKS.md |
Provider system, 16 providers, 4 roles | Intelligence uses providers via mesh CLI, not directly |
DISTRO.md |
Distribution channels | Tauri app bundles intelligence; Docker includes it |
AGENTS.md |
Agent instructions | Add intelligence CLI commands (mesh ask, mesh chat) |
Key Principle
Intelligence does NOT bypass the engine. It uses the same mesh CLI and the same event ledger as every other consumer. It's a user of Flow Mesh, not a component of it. This means:
- Policy engine still controls what syncs where
- Event ledger still tracks everything
- Loop guards still prevent echoes
- Conflict detection still works
- Intelligence can't do anything a human with CLI access couldn't do
The only special power is pi -p delegation — and that's governed by its own policy layer with spending limits and human approval gates.
See Also
HOOKS.md— Provider system architectureDISTRO.md— Distribution (Tauri bundles intelligence)SCOPE.md— Current implementation spec- pi-mom README — Inspiration for memory, skills, events patterns
- pi CLI
--help— Headless mode flags (-p,--mode json,--model)
Appendix A: LLM-Powered Intelligence — Implementation Spec
Status: Spec (supersedes keyword classifier) Date: 2026-02-20 Prerequisite: Everything above remains the design target. This appendix specifies how to get from the current keyword-based stub to the real LLM-powered system.
A.1 Current State vs Target
| Aspect | Current (stub) | Target |
|---|---|---|
| Message processing | classify.go keyword matching → hardcoded skill route |
LLM decides what to do; keyword fast-path for trivial cases |
| Conversation | In-memory map[string]*Conversation, lost on restart |
Persistent context.jsonl per channel + compaction |
| LLM calls | Zero — no API calls anywhere | Provider-agnostic client; every non-trivial message goes to LLM |
| Tools | 7 Go functions shelling out to mesh CLI |
Same functions, but exposed as LLM tool schemas so the model chooses |
| Planning | Not possible | Multi-turn: user describes goal → LLM decomposes → creates tasks in loop |
| Memory | None | MEMORY.md files (global + per-channel), auto-updated |
| Model config | chat_model/coding_model keys stored but never read |
Fully configurable: provider, model, API key, base URL, thinking level |
| Context management | None | Token counting, compaction when window exceeded, grep-back for history |
What stays untouched
config.go— DB config reader/writersecurity.go— sanitization, rate limitingtransport.go— transport interfacesscheduler.go— cron enginedelegation_engine.go— pi headless invocationHandleLedgerEvent()— assignee routing, auto-triage hooksRecordUsage()/UsageStats()— spending tracking- All DB tables (
intelligence_config,intelligence_delegations,intelligence_spending,intelligence_permissions)
What changes
engine.go→ProcessMessage()rewritten (~50 lines)classify.go→ demoted to fast-path, not primary router
What's new
llmclient.go— provider-agnostic LLM client with tool usecontext.go— persistent conversation + compactiontools.go— tool schemas for LLMmemory.go— MEMORY.md read/writeplanning.go— project planning / task decomposition skill
A.2 LLM Client Abstraction
A single Go interface that wraps any LLM provider supporting tool use.
Interface
// llmclient.go
// Provider identifies an LLM API provider.
type Provider string
const (
ProviderAnthropic Provider = "anthropic"
ProviderOpenAI Provider = "openai"
ProviderOpenRouter Provider = "openrouter"
ProviderOllama Provider = "ollama"
)
// LLMConfig holds connection settings for one LLM endpoint.
type LLMConfig struct {
Provider Provider // which API format to use
Model string // e.g. "claude-sonnet-4-5", "gpt-4o", "llama3.1"
APIKey string // secret (from env var or config set-secret)
BaseURL string // optional override (required for ollama/openrouter)
Thinking string // "off", "low", "medium", "high" (anthropic extended thinking)
MaxTokens int // max output tokens (default 4096)
Temperature float64 // 0.0–1.0 (default 0.7 for chat, 0.0 for coding)
}
// Message is a single turn in a conversation.
type Message struct {
Role string // "system", "user", "assistant", "tool_result"
Content string // text content
ToolCalls []ToolCall // assistant requesting tool use
ToolResult *ToolResult // result of a tool call
}
// ToolCall is the LLM requesting a tool invocation.
type ToolCall struct {
ID string // unique call ID
Name string // tool name
Arguments map[string]interface{} // parsed JSON arguments
}
// ToolResult is the response to a ToolCall.
type ToolResult struct {
CallID string // matches ToolCall.ID
Content string // tool output (stdout, JSON, error message)
IsError bool
}
// ToolDef defines a tool the LLM can call.
type ToolDef struct {
Name string // e.g. "mesh_task_create"
Description string // what this tool does
Parameters map[string]interface{} // JSON Schema for arguments
}
// LLMResponse is what comes back from the model.
type LLMResponse struct {
Content string // text response (may be empty if tool_use)
ToolCalls []ToolCall // tools the model wants to invoke
StopReason string // "end_turn", "tool_use", "max_tokens"
Usage Usage
}
// Usage tracks token consumption for cost accounting.
type Usage struct {
InputTokens int
OutputTokens int
CacheRead int // anthropic prompt caching
CacheWrite int
}
// LLMClient calls an LLM with tool support.
type LLMClient interface {
// Chat sends messages and returns the model's response.
// Tools are optional — pass nil for pure conversation.
Chat(ctx context.Context, cfg LLMConfig, messages []Message, tools []ToolDef) (*LLMResponse, error)
}
Provider Implementations
Each provider maps to one HTTP API format:
| Provider | API Format | Base URL Default | Auth |
|---|---|---|---|
anthropic |
Anthropic Messages API | https://api.anthropic.com/v1 |
x-api-key header |
openai |
OpenAI Chat Completions | https://api.openai.com/v1 |
Authorization: Bearer |
openrouter |
OpenAI-compatible | https://openrouter.ai/api/v1 |
Authorization: Bearer |
ollama |
OpenAI-compatible | http://localhost:11434/v1 |
none |
The key insight: OpenAI, OpenRouter, and Ollama all use the same API format (OpenAI Chat Completions). So there are really only two implementations:
func NewLLMClient(provider Provider) LLMClient {
switch provider {
case ProviderAnthropic:
return &anthropicClient{} // Anthropic Messages API
default:
return &openaiClient{} // OpenAI-compatible (covers openai, openrouter, ollama)
}
}
Anthropic Messages API mapping
POST {baseURL}/messages
Headers: x-api-key, anthropic-version: 2023-06-01
Body: {
model, max_tokens, system, messages,
tools: [{ name, description, input_schema }],
thinking: { type: "enabled", budget_tokens: N } // if thinking != "off"
}
Response: { content: [{type: "text"/"tool_use", ...}], stop_reason, usage }
OpenAI Chat Completions mapping
POST {baseURL}/chat/completions
Headers: Authorization: Bearer {apiKey}
Body: {
model, max_tokens, messages,
tools: [{ type: "function", function: { name, description, parameters } }]
}
Response: { choices: [{message: {content, tool_calls}, finish_reason}], usage }
Thinking Level mapping (Anthropic only)
| Setting | Budget |
|---|---|
off |
Thinking disabled |
low |
2,048 tokens |
medium |
8,192 tokens |
high |
32,768 tokens |
For non-Anthropic providers, thinking level is ignored (most don't support it).
A.3 Tool Definitions
The LLM receives these tools and decides which to call. Each tool wraps an existing mesh CLI command. The intelligence engine executes the CLI and returns the output.
Core Tools
// tools.go
var MeshTools = []ToolDef{
{
Name: "mesh_task_list",
Description: "List tasks in a mesh. Returns JSON array of tasks with id, title, status, priority, assignee, due_date.",
Parameters: jsonSchema(map[string]interface{}{
"mesh": {Type: "string", Desc: "Mesh ID or name (optional, lists all if omitted)"},
"status": {Type: "string", Desc: "Filter: backlog, in_progress, done, all (default: open tasks)"},
"priority": {Type: "string", Desc: "Filter: P0, P1, P2, P3, unset"},
"assignee": {Type: "string", Desc: "Filter by assignee name"},
}),
},
{
Name: "mesh_task_create",
Description: "Create a new task in a mesh. Returns the created task ID.",
Parameters: jsonSchema(map[string]interface{}{
"mesh": {Type: "string", Desc: "Mesh ID or name (required)"},
"title": {Type: "string", Desc: "Task title (required)"},
"description": {Type: "string", Desc: "Task description/body"},
"priority": {Type: "string", Desc: "P0, P1, P2, P3, or unset"},
"assignee": {Type: "string", Desc: "Assignee name or ID"},
"due_date": {Type: "string", Desc: "Due date YYYY-MM-DD"},
"status": {Type: "string", Desc: "Initial status (default: backlog)"},
}),
},
{
Name: "mesh_task_update",
Description: "Update an existing task's fields.",
Parameters: jsonSchema(map[string]interface{}{
"task_id": {Type: "string", Desc: "Task/work item ID (required)"},
"title": {Type: "string", Desc: "New title"},
"description": {Type: "string", Desc: "New description"},
"priority": {Type: "string", Desc: "New priority"},
"assignee": {Type: "string", Desc: "New assignee"},
"due_date": {Type: "string", Desc: "New due date"},
"status": {Type: "string", Desc: "New status"},
}),
},
{
Name: "mesh_task_close",
Description: "Close/complete a task.",
Parameters: jsonSchema(map[string]interface{}{
"task_id": {Type: "string", Desc: "Task/work item ID (required)"},
"note": {Type: "string", Desc: "Closing note/reason"},
}),
},
{
Name: "mesh_task_show",
Description: "Show full details of a single task including description, comments, and sync status.",
Parameters: jsonSchema(map[string]interface{}{
"task_id": {Type: "string", Desc: "Task/work item ID (required)"},
}),
},
{
Name: "mesh_list",
Description: "List all meshes with their state, provider connections, and task counts.",
Parameters: jsonSchema(map[string]interface{}{}),
},
{
Name: "mesh_events",
Description: "Query the event ledger. Shows sync activity, errors, and audit trail.",
Parameters: jsonSchema(map[string]interface{}{
"mesh": {Type: "string", Desc: "Filter by mesh ID"},
"type": {Type: "string", Desc: "Filter by event type (create, update, delete, comment, sync, etc.)"},
"since": {Type: "string", Desc: "Time filter: 1h, 24h, 7d, etc."},
"state": {Type: "string", Desc: "Filter by projection state: pending, projected, failed"},
"limit": {Type: "integer", Desc: "Max events to return (default 20)"},
}),
},
{
Name: "mesh_conflicts",
Description: "List active sync conflicts that need resolution.",
Parameters: jsonSchema(map[string]interface{}{
"mesh": {Type: "string", Desc: "Filter by mesh ID (optional)"},
}),
},
{
Name: "mesh_resolve",
Description: "Resolve a sync conflict by choosing a winner.",
Parameters: jsonSchema(map[string]interface{}{
"conflict_id": {Type: "string", Desc: "Conflict event ID (required)"},
"winner": {Type: "string", Desc: "Winner system: asana, beads, discord, mesh (required)"},
}),
},
{
Name: "mesh_ps_create",
Description: "Create a new mesh with provider connections.",
Parameters: jsonSchema(map[string]interface{}{
"name": {Type: "string", Desc: "Mesh name (required)"},
"repo": {Type: "string", Desc: "Git repo path on disk"},
"asana_create": {Type: "boolean", Desc: "Create a new Asana project"},
"discord_create": {Type: "boolean", Desc: "Create a new Discord forum channel"},
}),
},
{
Name: "update_memory",
Description: "Save important information to memory for future conversations. Use when you learn team preferences, conventions, project context, or the user asks you to remember something.",
Parameters: jsonSchema(map[string]interface{}{
"scope": {Type: "string", Desc: "'global' or channel ID (required)"},
"content": {Type: "string", Desc: "Markdown content to append to memory (required)"},
}),
},
{
Name: "read_memory",
Description: "Read current memory contents.",
Parameters: jsonSchema(map[string]interface{}{
"scope": {Type: "string", Desc: "'global' or channel ID (required)"},
}),
},
}
Delegation Tool (gated by policy)
var DelegationTool = ToolDef{
Name: "delegate_to_pi",
Description: `Delegate a coding task to pi (headless coding agent). Use for: reading code, writing fixes, running tests, committing changes. This invokes a separate coding model — only use when actual code work is needed, not for status checks or task management. Subject to delegation policy and spending limits.`,
Parameters: jsonSchema(map[string]interface{}{
"mesh": {Type: "string", Desc: "Mesh ID (required — determines which repo to work in)"},
"prompt": {Type: "string", Desc: "Detailed coding instructions for pi (required)"},
"session_id": {Type: "string", Desc: "Session ID for multi-step work (optional — omit for new session, provide to continue)"},
}),
}
Planning Tool
var PlanningTool = ToolDef{
Name: "plan_and_create_tasks",
Description: `Decompose a project goal into tasks and create them all in a mesh. Use when the user describes a feature, project, or initiative that needs to be broken down. You decide the decomposition — titles, priorities, ordering, dependencies — then create each task via mesh CLI. Return the full plan with task IDs.`,
Parameters: jsonSchema(map[string]interface{}{
"mesh": {Type: "string", Desc: "Target mesh ID or name (required)"},
"goal": {Type: "string", Desc: "The high-level goal to decompose (required)"},
"num_tasks": {Type: "integer", Desc: "Approximate number of tasks (optional, LLM decides if omitted)"},
}),
}
The planning tool is not a single CLI call — it's a multi-step orchestration:
- LLM generates the decomposition (titles, descriptions, priorities, order)
- For each task:
mesh task create --mesh {mesh} --title "..." --priority P{n} - Returns the full plan as structured output
This happens inside a single tool execution — the LLM calls plan_and_create_tasks once, and the tool handler runs the loop internally.
Tool Execution
// executeTool runs a tool call and returns the result.
func (e *Engine) executeTool(ctx context.Context, call ToolCall, channelID string) ToolResult {
switch call.Name {
case "mesh_task_list":
args := buildCLIArgs("mesh", "task", "list", "--format", "json", call.Arguments)
out, err := execMeshCLI(ctx, args...)
return toolResult(call.ID, out, err)
case "mesh_task_create":
args := buildCLIArgs("mesh", "task", "create", call.Arguments)
out, err := execMeshCLI(ctx, args...)
return toolResult(call.ID, out, err)
case "delegate_to_pi":
return e.executeDelegation(ctx, call, channelID)
case "plan_and_create_tasks":
return e.executePlanning(ctx, call, channelID)
case "update_memory":
return e.executeUpdateMemory(call, channelID)
// ... other tools
}
}
// execMeshCLI shells out to the mesh binary.
func execMeshCLI(ctx context.Context, args ...string) (string, error) {
cmd := exec.CommandContext(ctx, "mesh", append(args, "--format", "json")...)
out, err := cmd.CombinedOutput()
return string(out), err
}
A.4 ProcessMessage Rewrite
The current ProcessMessage() does: sanitize → classify keywords → route to skill.
The new version does: sanitize → fast-path check → LLM with tools → execute tool loop.
func (e *Engine) ProcessMessage(ctx context.Context, channelID, userMessage, actor string) (*Response, error) {
if !e.config.Enabled() {
return &Response{Text: "Intelligence is disabled. Enable it in Setup → Intelligence."}, nil
}
// Security: input validation + rate limiting + sanitization
if err := ValidateInputLength(userMessage); err != nil {
return &Response{Text: fmt.Sprintf("⚠️ %s", err)}, nil
}
if err := e.limiter.AllowMessage(channelID); err != nil {
return &Response{Text: fmt.Sprintf("🚦 %s", err)}, nil
}
sanitized, _ := SanitizeInput(userMessage)
// Fast-path: trivial intents that don't need an LLM call
if resp := e.tryFastPath(sanitized); resp != nil {
return resp, nil
}
// Load conversation context (persistent)
conv := e.loadContext(channelID)
// Build messages: system prompt + conversation history + new user message
systemPrompt := e.buildSystemPrompt(channelID)
messages := conv.BuildLLMMessages(systemPrompt, sanitized, actor)
// Resolve LLM config from DB/env
llmCfg := e.chatLLMConfig()
// Tool-use loop: call LLM, execute tools, feed results back, repeat
var finalText string
var totalUsage Usage
for iterations := 0; iterations < 20; iterations++ {
resp, err := e.llm.Chat(ctx, llmCfg, messages, e.availableTools(channelID))
if err != nil {
return &Response{Text: fmt.Sprintf("LLM error: %v", err)}, nil
}
totalUsage = totalUsage.Add(resp.Usage)
if resp.StopReason == "end_turn" || len(resp.ToolCalls) == 0 {
finalText = resp.Content
break
}
// Append assistant message with tool calls
messages = append(messages, Message{Role: "assistant", ToolCalls: resp.ToolCalls})
// Execute each tool and append results
for _, tc := range resp.ToolCalls {
result := e.executeTool(ctx, tc, channelID)
messages = append(messages, Message{Role: "tool_result", ToolResult: &result})
}
}
// Persist conversation
conv.AppendUser(sanitized, actor)
conv.AppendAssistant(finalText)
e.saveContext(channelID, conv)
// Record spending
e.RecordUsage(llmCfg.Model, totalUsage.InputTokens, totalUsage.OutputTokens, estimateCost(llmCfg, totalUsage))
return &Response{
Text: finalText,
Model: llmCfg.Model,
TokensUsed: totalUsage.InputTokens + totalUsage.OutputTokens,
}, nil
}
Fast-Path (no LLM call)
Trivial messages that don't need an API call:
func (e *Engine) tryFastPath(msg string) *Response {
lower := strings.ToLower(strings.TrimSpace(msg))
switch {
case lower == "help":
return &Response{Text: e.helpText()}
case lower == "status":
out, _ := execMeshCLI(context.Background(), "ps", "list", "--format", "json")
return &Response{Text: formatMeshStatus(out)}
default:
return nil // not a fast-path case, use LLM
}
}
Only exact-match trivial commands. Everything else goes to the LLM.
System Prompt
func (e *Engine) buildSystemPrompt(channelID string) string {
memory := e.readMemory("global") + "\n" + e.readMemory(channelID)
meshSummary, _ := execMeshCLI(context.Background(), "ps", "list", "--format", "json")
return fmt.Sprintf(`You are Flow Mesh Intelligence — an AI assistant for project management and development.
You help humans plan projects, manage tasks, track sync status, resolve conflicts, and delegate coding work.
## What you can do
- Answer questions about meshes, tasks, sync status, events
- Create, update, close, and assign tasks
- Plan and decompose projects into task lists
- Resolve sync conflicts between providers
- Delegate coding work to pi (headless coding agent on the server)
- Remember team preferences and conventions
## Rules
- Use tools to get real data. Never guess task IDs, mesh names, or statuses.
- For task management: use mesh_task_* tools (they sync to Asana/Discord/Beads automatically).
- For coding work: use delegate_to_pi (subject to policy — may require human approval).
- For planning: use plan_and_create_tasks to decompose goals into actionable tasks.
- Be concise. Summarize tool output for the human — don't dump raw JSON.
- If a tool call fails, explain what went wrong and suggest alternatives.
## Current State
%s
## Memory
%s
`, meshSummary, memory)
}
A.5 Conversation Persistence
Each channel gets a directory under /data/flow-mesh/intelligence/channels/:
/data/flow-mesh/intelligence/
MEMORY.md # global memory
channels/
slack-C0A34FL8PMH/
MEMORY.md # channel memory
context.jsonl # conversation (LLM messages + tool results)
discord-1474455868907983052/
MEMORY.md
context.jsonl
web-default/
MEMORY.md
context.jsonl
context.jsonl Format
One JSON object per line. Each line is a message in the conversation:
{"role":"user","content":"what's overdue?","actor":"sarah","ts":"2026-02-20T08:50:00Z"}
{"role":"assistant","content":"","tool_calls":[{"id":"tc_1","name":"mesh_task_list","arguments":{"status":"all"}}],"ts":"2026-02-20T08:50:01Z"}
{"role":"tool_result","call_id":"tc_1","content":"[{\"id\":\"...\",\"title\":\"Rate limiting\",\"status\":\"in_progress\",\"due_date\":\"2026-02-16\"}]","ts":"2026-02-20T08:50:01Z"}
{"role":"assistant","content":"1 task overdue: **Rate limiting** (4 days). Assigned to agent.","ts":"2026-02-20T08:50:02Z"}
Context Loading
type ConversationContext struct {
channelDir string
messages []Message
}
func (e *Engine) loadContext(channelID string) *ConversationContext {
dir := filepath.Join(e.intelligenceDir, "channels", channelID)
os.MkdirAll(dir, 0755)
ctx := &ConversationContext{channelDir: dir}
ctx.loadFromFile(filepath.Join(dir, "context.jsonl"))
return ctx
}
Compaction
When the conversation exceeds the model's context window (estimated via token counting), compact: keep the last N messages verbatim, summarize everything before them.
func (c *ConversationContext) CompactIfNeeded(maxTokens int) {
estimated := c.estimateTokens()
if estimated < maxTokens * 80 / 100 { // 80% threshold
return
}
// Keep last 20 messages verbatim
keep := 20
if len(c.messages) <= keep {
return
}
// Summarize older messages into a single compaction message
older := c.messages[:len(c.messages)-keep]
summary := summarizeMessages(older) // can use LLM or simple extraction
compaction := Message{
Role: "system",
Content: fmt.Sprintf("[Compacted %d earlier messages]\n\n%s", len(older), summary),
}
c.messages = append([]Message{compaction}, c.messages[len(c.messages)-keep:]...)
c.saveToFile()
}
Token estimation uses a simple heuristic: len(content) / 4 (roughly 4 chars per token for English). This avoids needing a tokenizer dependency. The 80% threshold gives headroom for the model's response.
A.6 Memory
MEMORY.md Files
Global memory at /data/flow-mesh/intelligence/MEMORY.md:
## Team
- Verious: owner, admin, primary user (Asana GID 1475590109155)
## Conventions
- Conventional commits (feat/fix/refactor/chore)
- Go, SQLite, htmx stack
- All tasks sync to Asana + Discord + Beads
## Preferences
- Telegraph style: concise responses
- Show task IDs in responses for easy reference
Channel memory at /data/flow-mesh/intelligence/channels/{id}/MEMORY.md:
## Context
- This channel is for Flow Mesh development
- Active mesh: Flow Mesh Live Demo (019c7c11-da09-751a-8ea0-6eed596b3833)
Memory Tools
The LLM can update memory via the update_memory and read_memory tools. Memory is also loaded into the system prompt on every message, so the LLM always has access without an explicit tool call.
func (e *Engine) executeUpdateMemory(call ToolCall, channelID string) ToolResult {
scope, _ := call.Arguments["scope"].(string)
content, _ := call.Arguments["content"].(string)
var path string
if scope == "global" {
path = filepath.Join(e.intelligenceDir, "MEMORY.md")
} else {
path = filepath.Join(e.intelligenceDir, "channels", channelID, "MEMORY.md")
}
// Append to existing memory
f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
if err != nil {
return ToolResult{CallID: call.ID, Content: err.Error(), IsError: true}
}
defer f.Close()
fmt.Fprintf(f, "\n%s\n", content)
return ToolResult{CallID: call.ID, Content: "Memory updated."}
}
A.7 Planning & Decomposition
The core use case: user describes a project goal, the LLM decomposes it into tasks, creates them all in the mesh, and returns a structured plan.
How It Works
The plan_and_create_tasks tool handler:
- LLM already has the goal (from the tool call arguments)
- Handler builds a prompt asking the LLM to produce a JSON task list
- LLM returns structured decomposition
- Handler iterates and runs
mesh task createfor each task - Returns the plan with created task IDs
func (e *Engine) executePlanning(ctx context.Context, call ToolCall, channelID string) ToolResult {
mesh, _ := call.Arguments["mesh"].(string)
goal, _ := call.Arguments["goal"].(string)
// Ask the chat model to decompose the goal into tasks
decompositionPrompt := fmt.Sprintf(`Decompose this project goal into actionable tasks.
Return ONLY a JSON array. Each element: {"title": "...", "description": "...", "priority": "P0-P3", "order": N}
Goal: %s`, goal)
llmCfg := e.chatLLMConfig()
resp, err := e.llm.Chat(ctx, llmCfg, []Message{
{Role: "user", Content: decompositionPrompt},
}, nil) // no tools — just generate JSON
if err != nil {
return ToolResult{CallID: call.ID, Content: "Failed to decompose: " + err.Error(), IsError: true}
}
// Parse the JSON array from the response
var tasks []struct {
Title string `json:"title"`
Description string `json:"description"`
Priority string `json:"priority"`
Order int `json:"order"`
}
if err := json.Unmarshal(extractJSON(resp.Content), &tasks); err != nil {
return ToolResult{CallID: call.ID, Content: "Failed to parse decomposition: " + err.Error(), IsError: true}
}
// Create each task via mesh CLI
var results []string
for _, t := range tasks {
args := []string{"task", "create",
"--mesh", mesh,
"--title", t.Title,
"--priority", t.Priority,
"--format", "json",
}
if t.Description != "" {
args = append(args, "--description", t.Description)
}
out, err := execMeshCLI(ctx, args...)
if err != nil {
results = append(results, fmt.Sprintf("❌ %s: %v", t.Title, err))
} else {
results = append(results, fmt.Sprintf("✅ %s → %s", t.Title, extractTaskID(out)))
}
}
return ToolResult{
CallID: call.ID,
Content: fmt.Sprintf("Created %d tasks:\n%s", len(results), strings.Join(results, "\n")),
}
}
Example Interaction
User: "Plan out a user authentication system for project-alpha"
LLM thinks → calls plan_and_create_tasks(mesh="project-alpha",
goal="User authentication system")
Tool handler:
1. Asks LLM to decompose → gets 8 tasks
2. Creates each: mesh task create --mesh project-alpha --title "..."
3. Returns task list with IDs
LLM responds:
"Created 8 tasks for user auth in project-alpha:
1. ✅ TASK-601 — Design auth schema (P1)
2. ✅ TASK-602 — Implement JWT token service (P1)
3. ✅ TASK-603 — Login endpoint (P1)
4. ✅ TASK-604 — Registration endpoint (P2)
5. ✅ TASK-605 — Password reset flow (P2)
6. ✅ TASK-606 — OAuth2 Google provider (P2)
7. ✅ TASK-607 — Session management middleware (P1)
8. ✅ TASK-608 — Auth integration tests (P1)
All synced to Asana and Discord. Want me to assign any of these?"
A.8 Provider Configuration
Config Keys (additions to intelligence_config table)
| Key | Type | Default | Description |
|---|---|---|---|
chat_provider |
string | anthropic |
LLM provider for conversation |
chat_model |
string | claude-haiku-4-5 |
Model for conversation |
chat_base_url |
string | (provider default) | Custom API endpoint |
chat_thinking |
string | off |
Thinking level (anthropic only) |
chat_max_tokens |
int | 4096 |
Max output tokens for chat |
chat_temperature |
float | 0.7 |
Temperature for chat responses |
coding_provider |
string | anthropic |
LLM provider for pi delegation |
coding_model |
string | claude-sonnet-4-5 |
Model for coding |
coding_base_url |
string | (provider default) | Custom API endpoint |
coding_thinking |
string | high |
Thinking level for coding |
Secret Keys (env vars or config set-secret)
| Key | Env Var | Description |
|---|---|---|
chat_api_key |
FLOW_MESH_INTELLIGENCE_API_KEY |
API key for chat model |
coding_api_key |
— (config only) | API key for coding model |
Env vars always override DB values. Secrets never stored in config.yaml.
Resolving LLM Config
func (e *Engine) chatLLMConfig() LLMConfig {
provider := Provider(e.config.Get("chat_provider", "anthropic"))
apiKey := os.Getenv("FLOW_MESH_INTELLIGENCE_API_KEY")
if apiKey == "" {
apiKey = e.config.Get("chat_api_key", "")
}
return LLMConfig{
Provider: provider,
Model: e.config.Get("chat_model", defaultChatModel(provider)),
APIKey: apiKey,
BaseURL: e.config.Get("chat_base_url", defaultBaseURL(provider)),
Thinking: e.config.Get("chat_thinking", "off"),
MaxTokens: e.config.GetInt("chat_max_tokens", 4096),
Temperature: e.config.GetFloat("chat_temperature", 0.7),
}
}
Setup UI
The existing Intelligence section on /setup already has the right layout (see "UI Pages" section above). Config is written by the CLI (mesh config set, mesh config set-secret) into config.yaml; the API surface for intelligence is read/query oriented (GET /api/intelligence, POST /api/intelligence, POST /api/intelligence/chat). There is no PUT /api/intelligence/config — an earlier draft of this document described one that was never built.
CLI
# Configure chat model
mesh config set intelligence.chat_provider anthropic
mesh config set intelligence.chat_model claude-haiku-4-5
mesh config set-secret intelligence.chat_api_key
# Configure coding model
mesh config set intelligence.coding_provider openai
mesh config set intelligence.coding_model gpt-4o
mesh config set-secret intelligence.coding_api_key
# Use local Ollama
mesh config set intelligence.chat_provider ollama
mesh config set intelligence.chat_model llama3.1
mesh config set intelligence.chat_base_url http://localhost:11434/v1
# no API key needed for Ollama
# Validate
mesh config validate --live
# Intelligence: ✓ anthropic/claude-haiku-4-5 — responded in 1.2s
A.9 Implementation Plan
Follows the phasing from the main spec, now with concrete file-level detail.
Phase 1: LLM Client + Web Chat (MVP)
New files:
internal/intelligence/llmclient.go— LLMClient interface + anthropic/openai implementationsinternal/intelligence/tools.go— tool definitions + executeTool dispatcherinternal/intelligence/context.go— ConversationContext with context.jsonl persistenceinternal/intelligence/memory.go— MEMORY.md read/write helpers
Changes:
internal/intelligence/engine.go— rewrite ProcessMessage, add tool-use loopinternal/api/api.go— wire/ws/chatWebSocket to new ProcessMessage- Setup UI — wire intelligence config fields to API
What works after Phase 1:
- Web chat widget on dashboard talks to real LLM
- LLM can list/create/update/close tasks via mesh CLI tools
- Conversation persists across restarts (context.jsonl)
- Memory persists (MEMORY.md)
- Any provider/model configurable from Setup UI
- Spending tracked per request
Phase 2: Planning + Delegation
New files:
internal/intelligence/planning.go— plan_and_create_tasks handler
Changes:
internal/intelligence/tools.go— add planning + delegation toolsinternal/intelligence/delegation_engine.go— wire to tool executor
What works after Phase 2:
- "Plan out feature X" → LLM decomposes → tasks created in mesh → synced everywhere
- "Fix the auth bug" → policy check → pi -p headless → result reported in chat
- Multi-step pi sessions with session continuity
Phase 3: External Transports + Scheduling
Changes:
internal/intelligence/transport.go— wire Slack/Discord transports to ProcessMessageinternal/intelligence/scheduler.go— scheduled events trigger ProcessMessage
What works after Phase 3:
- Talk to mesh from Slack, Discord, Web, or CLI
- Daily standups, conflict checks, periodic digests — all automated
- Per-channel memory and context
Phase 4: Advanced
- Compaction (auto-summarize when context window exceeded)
- Model auto-selection (simple query → cheap model, code task → expensive model)
- Approval queue UI for
askpolicy mode - Cost optimization dashboard
A.10 What This Enables
The end state:
Verious in Slack:
"Plan out a billing system for the SaaS product.
Break it into tasks, assign the backend ones to pi,
I'll handle the Stripe dashboard setup myself."
Intelligence:
→ Calls plan_and_create_tasks: decomposes into 12 tasks
→ Creates all 12 in mesh → synced to Asana + Discord + Beads
→ Assigns 7 backend tasks to "pi" (agent)
→ Assigns 5 setup tasks to "Verious"
→ HandleLedgerEvent fires: detects agent assignments
→ Auto-delegates each to pi -p with appropriate context
→ pi works through them sequentially (rate-limited to 3 concurrent)
→ Each completion syncs back: Asana ✓, Discord ✓, Beads ✓
→ Intelligence posts progress to Slack: "3/7 backend tasks done"
Verious checks in 2 hours:
"How's the billing system going?"
Intelligence:
→ mesh task list --mesh billing --format json
"7/7 backend tasks complete. 2/5 of your tasks still open:
- TASK-615 'Configure Stripe webhooks' (assigned to you)
- TASK-617 'Set up pricing tiers' (assigned to you)
Pi's work: all tests passing, 4 commits pushed."
The human never opened a terminal. Described a vision in natural language. The mesh decomposed it, delegated it, tracked it, and reported back. All through the same sync engine that was already built.