Demo Reset & State Management

Relevant source files

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

• reset_demo.py
• README.md
• app.py
• orchestrator.py
• memory_utils.py

Introduction

The BrightPath AI Operations system utilizes a multi-layered approach to state management to ensure AI agents maintain context across sessions while providing a reliable mechanism for demonstration resets. The state is distributed across a file-based memory system for agent context, a SQLite database for structured event logging and task tracking, and a JSON-based CRM for contact management.

This architecture allows the system to simulate a "live" environment where agent decisions are persisted and impact subsequent interactions. The Demo Reset functionality is critical for restoring this distributed state to a known baseline, enabling consistent demonstrations or testing cycles.

Sources: README.md:12-25, app.py:539-550

System State Architecture

The system state is composed of three primary storage mechanisms that work in tandem to provide context to the agent pipeline.

Component Overview

Component	Storage Type	Purpose
Memory Files	Markdown (.md)	Provides long-term, unstructured context (policies, history, tasks) for Claude agents.
Operational Database	SQLite (.db)	Stores structured logs of events, generated tasks, and CRM update histories.
CRM Data	JSON (.json)	Maintains the master record of contacts, VIP status, and estimated values.

Sources: README.md:37-60, orchestrator.py:27-33

State Flow Diagram

The following diagram illustrates how state is retrieved and updated during a standard pipeline execution.

The system reads memory and CRM data at the start of the pipeline and utilizes memory_utils.py to write back changes to the Markdown files after agent processing.
Sources: app.py:350-410, orchestrator.py:260-310

Memory Management

Agents rely on five core Markdown files located in the memory/ directory to maintain continuity. These files are updated programmatically via memory_utils.py after specific scenario runs to reflect changes in customer sentiment, task status, or sales pipeline progression.

Core Memory Files

• company_context.md: Static policies and guidelines.
• customer_history.md: Per-customer interaction logs.
• sales_notes.md: Pipeline activity and lead tracking.
• open_tasks.md: Active items requiring human or agent attention.
• decision_log.md: Historical record of past agent reasoning.

Sources: README.md:106-113, app.py:246-258

Programmatic Updates

The memory_utils.py module provides functions to append data to these files using structured Markdown blocks. For example, the update_customer_history function locates customer sections using ## [Customer Name] headers and inserts new update blocks before the next separator.

Sources: memory_utils.py:46-70

Database State Management

The SQLite database (brightpath.db) manages the structured transactional state. It is initialized automatically if it does not exist and contains three primary tables.

Database Schema

Data Retention Logic

• Events: Captured via log_event() to record every pipeline execution.
• Tasks: Generated by agents (e.g., open_task in agent JSON output) and inserted into the tasks table with a default 'open' status.
• CRM Log: Tracks every update made by sales agents to provide an audit trail of CRM changes.

Sources: app.py:167-194, orchestrator.py:87-118

Demo Reset Logic

The reset_demo.py script is the primary tool for state restoration. It ensures the environment is clean for new demonstrations by handling both the file-based memory and the database.

Reset Process Flow

Implementation Details

The reset script performs two main actions:

1. Memory Restoration: It copies Markdown files from the memory_backup/ directory back into the memory/ directory. If no backup exists, it creates one from the current state.
2. Database Cleansing: It executes DELETE statements on the events, tasks, and crm_log tables and resets the sqlite_sequence to ensure ID counters start from zero.

Sources: reset_demo.py:38-51

Conclusion

The BrightPath state management system provides a robust framework for persistent AI interactions. By combining the flexibility of Markdown-based memory with the structure of SQLite, the system allows agents to "remember" past interactions while the reset_demo.py utility ensures that this complex state can be instantly reverted to a clean baseline for consistent demonstration purposes.

Sources: README.md:124-129, reset_demo.py:10-15