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:

  1. No new pi delegations (coding model stops)
  2. Chat model continues (conversation is cheap)
  3. Intelligence reports: "Daily spending limit reached ($5.00). I can still answer questions but can't make code changes until tomorrow."
  4. 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 ask mode requires human confirmation for code changes
  • never mode 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/chat WebSocket)
  • mesh CLI 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_spending table

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 -p invocation from intelligence
  • Delegation policy enforcement
  • Spending limits
  • Session management for multi-step work
  • Activity log on /intelligence page

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 ask policy 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 architecture
  • DISTRO.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/writer
  • security.go — sanitization, rate limiting
  • transport.go — transport interfaces
  • scheduler.go — cron engine
  • delegation_engine.go — pi headless invocation
  • HandleLedgerEvent() — assignee routing, auto-triage hooks
  • RecordUsage() / 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 use
  • context.go — persistent conversation + compaction
  • tools.go — tool schemas for LLM
  • memory.go — MEMORY.md read/write
  • planning.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:

  1. LLM generates the decomposition (titles, descriptions, priorities, order)
  2. For each task: mesh task create --mesh {mesh} --title "..." --priority P{n}
  3. 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:

  1. LLM already has the goal (from the tool call arguments)
  2. Handler builds a prompt asking the LLM to produce a JSON task list
  3. LLM returns structured decomposition
  4. Handler iterates and runs mesh task create for each task
  5. 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 implementations
  • internal/intelligence/tools.go — tool definitions + executeTool dispatcher
  • internal/intelligence/context.go — ConversationContext with context.jsonl persistence
  • internal/intelligence/memory.go — MEMORY.md read/write helpers

Changes:

  • internal/intelligence/engine.go — rewrite ProcessMessage, add tool-use loop
  • internal/api/api.go — wire /ws/chat WebSocket 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 tools
  • internal/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 ProcessMessage
  • internal/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 ask policy 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.

Generated from the Flow Mesh repository by scripts/build-docs-site.sh. If a page is wrong here, the file it was rendered from is wrong.