Orchestration Agents

The orchestration layer is an LLM-powered router that dispatches work to specialized tools grouped into agents (GET /api/tools returns the live list). Instead of the fixed Expand-Counterpoint-Synthesize pipeline, the orchestrator reads your thought, decides which tools to run, orders them by dependencies, and executes them in parallel where possible.

Enabling the Orchestrator

Toggle Use Orchestrator for Deep Think in Settings, or go to the Agents panel for full configuration. When enabled, the Deep Think button and cortexa_think MCP tool use the orchestrator instead of the fixed pipeline.

How It Works

1. Plan -- The orchestrator LLM reads the thought content and the list of available tools. It produces a JSON execution plan with reasoning, steps, parameters, and dependency ordering.
2. Approve (optional) -- Click Preview Plan on any thought to see the plan before running. Review each step, then Execute or Cancel.
3. Execute -- Steps with no dependencies run in parallel (wave-based scheduling). Steps that depend on earlier outputs wait for them to complete.
4. Report -- Results from all tools are collected, logged to the orchestration log, and stored with the thought.

Thought ──▶ Orchestrator LLM ──▶ Execution Plan
                                       │
                    ┌──────────────────┼──────────────────┐
                    ▼                  ▼                  ▼
              Wave 1 (parallel)  Wave 2 (depends)   Wave 3
              ┌──────────┐      ┌──────────┐      ┌──────────┐
              │decompose │      │challenge │      │synthesize│
              │web_search│      │detect_bias│     │          │
              └──────────┘      └──────────┘      └──────────┘

The Agents

Analyst (6 tools)

Structural analysis and decomposition.

Tool	Purpose
decompose	Break into sub-claims, assumptions, dependencies, and key questions
apply_lens	Run through an analytical lens: pre-mortem, first-principles, inversion, or steelman
generate_questions	Produce probing questions to clarify or stress-test the idea
identify_assumptions	Extract implicit assumptions with confidence tags
map_dependencies	Identify what the idea depends on: tech, resources, market, prior decisions
synthesize_brief	Combine analysis outputs into a structured JSON brief

Critic (7 tools)

Adversarial review and quality assessment.

Tool	Purpose
challenge_claims	Generate specific counterarguments for each claim
detect_bias	Identify cognitive biases: confirmation, survivorship, anchoring, etc.
rate_confidence	Produce a high/medium/low confidence rating with justification
find_contradictions	Compare claims against vault evidence for conflicts
find_logical_fallacies	Scan for false dichotomy, appeal to authority, slippery slope, etc.
red_team	Adversarial pre-mortem: assume failure, explain exactly how
steelman_opposition	Build the strongest possible argument against the idea

Writer (7 tools)

Content transformation and formatting.

Tool	Purpose
summarize	Generate a concise one-paragraph summary
rewrite_for_clarity	Editorial pass: fix grammar, tighten prose, preserve meaning
generate_title	Produce a compelling 3-10 word title
extract_action_items	Pull concrete next steps into a priority-ordered checklist
adapt_tone	Rewrite for a target audience: technical, casual, academic, or executive
format_blog_post	Structure content into a full Markdown blog post with sections
generate_abstract	Write a 2-3 sentence abstract for feed or index listings

Researcher (7 tools)

External evidence and knowledge retrieval.

Tool	Purpose
search_vault	Semantic search across your vault using embeddings
web_search	Search DuckDuckGo for a query, returns top-N snippets with URLs
fetch_page	Fetch and extract readable text from a URL
summarize_sources	Synthesize a set of sources into a briefing with citations
search_hive	Search shared thoughts across Hive peers
request_source	Ask Loom to discover and build a missing source (asynchronous; only when autonomy is enabled)
check_intent	Read back what happened to a request_source intent

Connector (9 tools)

Knowledge graph and relationship discovery.

Tool	Purpose
find_similar	Semantic similarity search, returns top-K with cosine scores
bridge_thoughts	Explain how two thoughts connect: shared concepts, tensions, insights
suggest_merges	Identify near-duplicate or complementary thoughts to combine
detect_evolution	Track how an idea evolved across captures over time
map_knowledge_gaps	Analyze vault coverage, identify sparse areas to capture
find_thematic_clusters	Group related thoughts into labeled thematic clusters
thought_lineage	Trace an idea's ancestry chain and write temporal edges into the graph
blind_spots_report	Silos, open loops, and stale areas — what the vault doesn't cover
graph_stats	Exact connectivity numbers: link counts by kind, linked vs. isolated thoughts, most connected thoughts by degree. Deterministic, no LLM

Librarian (5 tools)

Vault curation. Every Librarian tool is deterministic (no LLM calls) and read-only — it recommends, you act.

Tool	Purpose
suggest_archives	List stale, low-confidence thoughts nothing has recalled in months — with reasons
suggest_tag_cleanup	Group casing/punctuation/plural tag variants into rename suggestions; list orphan tags
suggest_project_assignments	Suggest a project for unassigned thoughts via semantic neighbor vote, with confidence
vault_health_report	One-shot hygiene overview: embedding/tag/project counters, archive candidates, job queue state
resurface	Decent-confidence thoughts nothing has recalled in weeks — worth revisiting

Janitor (1 tool)

Junk detection. Read-only; apply through the Junk Sweep review.

Tool	Purpose
suggest_junk	Near-empty captures, test artifacts and duplicate captures, each with a reason

Custodian (1 tool)

Long-horizon memory reclamation. Read-only; apply through the Custodian review.

Tool	Purpose
suggest_gc	Sort low-signal thoughts into reversible deep-archive and approval-gated purge candidates

Synthesist (1 tool)

Roll-up and consolidation. Read-only; apply through the Roll-up review.

Tool	Purpose
suggest_rollups	Clusters of near-duplicate or tightly related thoughts that could merge into one

Visualizer (3 tools)

Mermaid diagrams from thoughts and their relationships. Diagrams save as notes on the item and render as SVG in the app.

Tool	Purpose
generate_diagram	LLM-authored flowchart, mindmap, sequence, or timeline of the thought
visualize_connections	Deterministic graph of the item's stored links, labeled by kind and weight
visualize_evolution	Deterministic timeline of the idea's semantic neighbors by capture date

Scheduler (3 tools)

Deadlines and reminders. Reminders are delivered by the background ticker as standard notifications; manage them under Settings → Notifications.

Tool	Purpose
extract_deadlines	Find deadlines in a thought, resolving relative dates against today
schedule_reminder	Set a reminder that fires a notification at its time, linked to the thought
list_upcoming_reminders	Pending reminders in the window, soonest first

Historian (5 tools)

The vault as a time series: period digests, "on this day", quantitative counts, opinion drift.

Tool	Purpose
period_digest	Themes, decisions, and open threads from a window of captures
on_this_day	What past-you captured on this calendar day
count_thoughts	Counts by type / project / tag / month / day
list_thoughts	Exact list of thoughts matching project / type / tag / time-window filters, newest first
opinion_drift	Early vs. current position on a topic, with turning points

Orchestration Patterns

The orchestrator dynamically picks tools based on what the thought needs. Common patterns:

Quick Capture -- simple notes

summarize → generate_title → find_similar

Full Analysis -- complex ideas

decompose → [parallel] apply_lens(pre-mortem) + apply_lens(first-principles)
          → challenge_claims → rate_confidence → synthesize_brief

Research -- claims needing evidence

[parallel] web_search + search_vault → summarize_sources

Fact Check -- verify assertions

decompose → find_contradictions → detect_bias → find_logical_fallacies

Plan Approval

Click Preview Plan (Eye icon) on any thought to see the orchestrator's plan before executing:

• Reasoning -- why the orchestrator chose these tools
• Steps -- numbered list with tool names, purposes, and dependency ordering
• Execute or Cancel buttons

This lets you review and approve expensive orchestration runs before they consume LLM tokens.

Token Tracking

Each tool call tracks token usage from the LLM provider. Anthropic and OpenAI report exact counts (input + output tokens). The orchestration log in the Agents settings panel shows total tool calls, successes, failures, and duration for each run.

Orchestration Logs

View the history of all orchestration runs in Settings > Agents > Orchestration Logs. Each entry shows:

• Status (running, done, dead)
• Number of tool calls with success/failure breakdown
• Duration
• Which thought was analyzed
• Timestamp

Using via MCP

Three MCP tools expose the orchestration layer:

Tool	Purpose
cortexa_list_tools	List every agent tool with descriptions and parameter schemas
cortexa_orchestrate	Run the full orchestration pipeline on a thought
cortexa_run_tool	Run any individual tool by name with custom parameters

// Run a specific tool
cortexa_run_tool({
  tool_name: "decompose",
  item_id: "abc123"
})

// Run full orchestration
cortexa_orchestrate({ item_id: "abc123" })

Using via HTTP API

# List all tools
curl http://localhost:7373/api/tools -H "Authorization: Bearer $TOKEN"

# Run orchestration on a thought
curl -X POST http://localhost:7373/api/orchestrate/$ITEM_ID -H "Authorization: Bearer $TOKEN"

# Run a specific tool
curl -X POST http://localhost:7373/api/tools/decompose/run \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"item_id": "'$ITEM_ID'"}'