Customer History

Relevant source files

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

• memory/customer_history.md
• memory_utils.py
• app.py
• orchestrator.py
• data/crm.json
• agents/triage_agent.md
• agents/customer_service_agent.md

The Customer History system is a core memory component of the BrightPath AI Operations platform. It serves as a persistent, file-based record of all interactions, sentiments, and statuses for both individual clients and corporate partners. This system enables AI agents to maintain context across multiple sessions, allowing them to reference past complaints, VIP statuses, and payment behaviors to inform current decision-making.

Sources: README.md:99-105, memory/customer_history.md

Architecture and Data Flow

The Customer History system operates as part of a multi-agent pipeline. Data flows from inbound messages through a Triage Agent and Specialist Agents (Sales or Customer Service), which read from and eventually trigger updates to the history files.

Data Components

The system relies on two primary data structures to track customer state:

1. memory/customer_history.md: A human-readable Markdown file containing qualitative notes, sentiment history, and detailed interaction logs.
2. data/crm.json: A structured JSON file containing quantitative data such as total_spend, vip status, and unique IDs (C001, C002, etc.).

Sources: memory/customer_history.md:1-80, data/crm.json:1-80

Key Data Fields

The following fields are typically tracked within the customer history and CRM records:

Field	Description	Source File
Status	Current relationship state (e.g., Active, Warm lead, At risk, VIP).	crm.json:6
Sentiment History	Cumulative emotional state tracked across interactions.	customer_history.md:10
Workshops Attended	List or count of previous training sessions completed.	crm.json:9
Tags	Metadata used by agents (e.g., slow_payer, annual_partner).	crm.json:30
Last Contact	Date of the most recent interaction.	customer_history.md:9

Sources: memory/customer_history.md:1-80, data/crm.json:1-80

Management Logic and Updates

Updating the customer history is handled by the memory_utils.py module, which provides functions to manipulate the Markdown file content without overwriting the entire structure.

Core Functions

• update_customer_history(contact, update_lines): Searches for a customer section (denoted by ## Name) and appends a timestamped update. If the contact is not found, it initializes a new entry.
• append_to_file(filename, content): A low-level utility to append raw text blocks to the memory files.

Sources: memory_utils.py:35-61

# From memory_utils.py:35-61
def update_customer_history(contact: str, update_lines: list):
    path = MEMORY / "customer_history.md"
    content = path.read_text(encoding="utf-8")
    update_block = f"\n**Update {_today()}:**\n" + "\n".join(f"- {line}" for line in update_lines)

    if f"## {contact}" in content:
        # Logic to append before the next '---' separator
        parts = content.split(f"## {contact}", 1)
        # ... content manipulation ...
        path.write_text(new_content, encoding="utf-8")

Sources: memory_utils.py:35-61

Interaction Sequence

The following sequence diagram shows how a specialist agent interacts with the history during a "Repeat Complaint" scenario.

Agent Integration

Agents use Customer History to apply specific business policies:

• Customer Service Agent: Uses history to identify "At Risk" customers or to apply the "VIP / Annual Partner" booking change policy (allowing changes up to 24 hours before with no fee).
• Triage Agent: Identifies existing customers to provide context notes for the next agent in the pipeline.
• Sales Agent: Checks history for prior contact or budget discussions to avoid duplicate proposals or conflicting quotes.

Sources: agents/customer_service_agent.md:16-19, agents/triage_agent.md:46, agents/sales_agent.md:27-31

Conclusion

The Customer History system ensures that BrightPath AI maintains a "long-term memory," preventing repetitive interactions and enabling sophisticated behaviors like automated escalation and VIP treatment. By combining structured JSON data for metrics and unstructured Markdown for narrative history, the system provides a comprehensive view of the customer journey.

Sources: README.md:99-105, memory/customer_history.md