Memory Write-Back Utilities

Relevant source files

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

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

The Memory Write-Back Utilities system in BrightPath is a specialized module designed to maintain persistent state across multi-agent AI interactions. While the system utilizes a SQLite database for structured logging, the Write-Back Utilities focus on updating human-readable Markdown (.md) files that serve as "long-term memory" for specialized agents.

This module ensures that context—such as customer complaints, updated sales leads, and new tasks—is preserved and accessible to the Triage, Sales, and Customer Service agents during subsequent pipeline runs. By updating these files, the system allows agents to carry over context from previous interactions, such as a customer's history of prior complaints or specific budget approvals.

Sources: memory_utils.py:1-12, README.md:104-114

System Architecture and Integration

The memory utilities act as a bridge between the agentic outputs and the filesystem. When the orchestrator.py or app.py finishes a pipeline run for a specific scenario, it triggers the memory update logic to persist the results of the AI's decisions.

The diagram above shows how agent execution leads to specific memory updates via the dispatch table.
Sources: memory_utils.py:214-232, orchestrator.py:321-324, app.py:539-541

Core Write-Back Functions

The utility provides several core functions that manage the appending and formatting of data into the various memory files.

File Manipulation Logic

All updates are handled through append_to_file, which performs a standard read-then-write operation to append new content to existing Markdown files.

Function	Targeted File	Description
append_to_file	Dynamic	Appends a block of text to any file in the /memory directory.
update_decision_log	decision_log.md	Logs the timestamp, event, agent involved, action taken, and reasoning.
update_customer_history	customer_history.md	Inserts update blocks under specific customer headers or creates new entries.
add_open_task	open_tasks.md	Appends a new task line to a specific priority section (HIGH/MEDIUM/LOW).
update_sales_notes	sales_notes.md	Appends sales activity updates for specific companies.

Sources: memory_utils.py:27-105

Customer History Management

The update_customer_history function uses string splitting to find existing headers (e.g., ## Linda Okafor). If found, it injects the update before the next thematic separator (---). If the customer is new, it appends a new section with a "First logged" timestamp.

Sources: memory_utils.py:48-73

Scenario-Specific Handlers

The system contains dedicated logic for 8 "Memory-Dependent Scenarios." These handlers define exactly what information should be written back based on the interaction type.

Scenario Index	Name	Primary Action
11	Repeat Complaint	Escalates to manager and adds a High Priority task.
13	Invoice Flag	Logs unpaid invoice status and creates a chase task.
14	Cold Lead Return	Updates status from "Cold" to "Warm" in sales notes.
16	Duplicate Lead	Flags conflicting contacts to avoid duplicate proposals.
17	Renewal Reminder	Triggers a High Priority task for upcoming contract renewal.

Sources: memory_utils.py:112-210, scenarios.py:46-77

Example Data Flow: Scenario 14 (Cold Lead Re-engagement)

When Rachel Drummond re-engages, multiple memory updates occur simultaneously:

This diagram illustrates the multi-file synchronization required for complex state transitions.
Sources: memory_utils.py:148-167

State Maintenance and Reset

To ensure a clean testing environment, the reset_demo.py utility provides a mechanism to restore the memory files to their original baseline. It utilizes a memory_backup/ directory to store clean copies of the .md files.

• Restore: Overwrites the current /memory files with the backup files.
• Backup: Creates a snapshot of the current /memory state.
• DB Clear: Simultaneously empties the events, tasks, and crm_log tables in the SQLite database.

Sources: reset_demo.py:17-56

Database Interaction

While the .md files provide the "memory" for the LLM agents, the orchestrator.py also logs structured data into the database alongside the write-back utilities.

# From orchestrator.py:312-320
# Add task to SQLite DB
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")

# Update Markdown memory via memory_utils
if scenario_key:
    updated = run_memory_update(scenario_key, triage, agent_result)

Sources: orchestrator.py:312-324

Summary

The Memory Write-Back Utilities provide a lightweight yet effective persistent storage layer for the BrightPath system. By utilizing human-readable Markdown files, the system allows developers to easily inspect the AI's internal "memory" while providing the agents with the necessary context to handle complex, multi-step customer and sales interactions.