Task Management

Relevant source files

The following files were used as context for generating this wiki page:

• memory/open_tasks.md
• app.py
• orchestrator.py
• memory_utils.py
• README.md
• agents/sales_agent.md
• agents/customer_service_agent.md

The Task Management system within BrightPath is a hybrid architecture designed to track, prioritize, and manage operational actions generated by AI agents. Its primary purpose is to ensure that "human-in-the-loop" requirements and automated next steps are captured during the processing of inbound customer messages. The system operates across two primary storage layers: a relational SQLite database for structured persistence and a Markdown-based "memory" file for agent context.

Tasks are primarily generated as side effects of the Agent Pipeline. When a specialist agent (Sales or Customer Service) identifies a necessary follow-up, it outputs a task description and priority. These are then synchronously written to the database and the open_tasks.md memory file, ensuring that subsequent agent runs have visibility into outstanding obligations.

Sources: README.md:5-15, orchestrator.py:245-251, app.py:440-445

Data Architecture and Storage

Task Management utilizes a dual-storage strategy to balance structured querying with LLM context accessibility.

Relational Schema (SQLite)

The tasks table in the brightpath.db database stores the formal record of all generated tasks. It tracks the lifecycle of a task from creation to completion.

Field	Type	Description
id	INTEGER	Primary key, auto-incremented.
created	TEXT	ISO-8601 timestamp of task creation.
task	TEXT	Detailed description of the action required.
priority	TEXT	Urgency level (high, medium, low).
status	TEXT	Current state (defaults to 'open').
source	TEXT	Originating interface (e.g., 'streamlit', 'orchestrator').

Sources: app.py:195-201, orchestrator.py:48-57

File-Based Memory (open_tasks.md)

The system maintains a Markdown file that acts as "long-term memory" for AI agents. This file is organized by priority sections and includes checkboxes for human tracking. Agents read this file on every run to understand the current operational backlog.

Sources: memory/open_tasks.md:1-18, orchestrator.py:126-128

Task Lifecycle and Data Flow

Tasks are created during the specialist agent execution phase of the pipeline. The following diagram illustrates how a task moves from an inbound message to the various storage layers.

This flow shows how the specialist agents identify tasks which are then persisted by the orchestrator into both the database and the Markdown memory system.
Sources: app.py:420-445, orchestrator.py:245-255, memory_utils.py:61-78

Implementation Details

Automated Task Generation

Task generation is integrated into the JSON output schemas of the specialist agents.

• Sales Agent: Identifies tasks via the crm_update.next_action field.
• Customer Service Agent: Identifies tasks via the open_task field.

The orchestrator.py logic extracts these fields after an agent call:

open_task = agent_result.get("open_task") or agent_result.get("crm_update", {}).get("next_action")
if open_task:
    add_task(open_task, triage.get("urgency", "medium"), "orchestrator")

Sources: orchestrator.py:246-249, agents/sales_agent.md:38-41, agents/customer_service_agent.md:52

Memory Synchronization

The memory_utils.py module contains the logic for updating the Markdown-based task list. It uses string manipulation to inject new tasks under the appropriate priority header.

def add_open_task(task: str, priority: str = "MEDIUM"):
    path = MEMORY / "open_tasks.md"
    content = path.read_text(encoding="utf-8")
    task_line = f"- [ ] {task} — **added {_today()}**\n"
    section = f"## {priority} PRIORITY"
    if section in content:
        content = content.replace(section, section + "\n" + task_line, 1)
    path.write_text(content, encoding="utf-8")

Sources: memory_utils.py:61-78

Task Visualization and Management

The system provides multiple interfaces for viewing and managing tasks:

1. Streamlit Dashboard: The "TASKS & HISTORY" tab displays tasks with color-coded priority tags (High: Red, Medium: Orange, Low: Green).
2. Terminal Interface: The orchestrator.py CLI provides a [t] command to show a formatted table of open tasks using the rich library.
3. Manager Briefing: Tasks are summarized for the manager via a Telegram-ready summary, highlighting actions that specifically require human intervention.

The sequence diagram represents the multi-source retrieval process used by the UI to present the current task state to the user.
Sources: app.py:545-565, orchestrator.py:102-114, agents/manager_briefing_agent.md:10-15

Conclusion

Task Management in BrightPath serves as the critical bridge between AI-driven analysis and human operational action. By synchronizing tasks across structured databases and LLM-readable Markdown files, the system ensures that no customer request or sales opportunity is lost, while providing the Manager Briefing Agent with the context needed to alert the business owner to high-priority items.

Sources: README.md:52-60, orchestrator.py:245-255