File-Based Memory System

Relevant source files

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

• README.md
• app.py
• orchestrator.py
• memory_utils.py
• reset_demo.py
• memory/company_context.md
• memory/customer_history.md
• memory/sales_notes.md
• memory/open_tasks.md

Introduction

The File-Based Memory System in BrightPath is a lightweight persistence layer designed to provide AI agents with long-term context, historical data, and operational guidelines. Unlike traditional database-only systems, this module utilizes Markdown (.md) files to store information in a human-readable format, allowing for both programmatic access by Claude agents and direct manual editing by administrators.

The system ensures that multi-agent pipelines—including Triage, Sales, and Customer Service agents—maintain continuity across sessions by reading from and writing back to these files. This architecture supports complex logic such as detecting duplicate leads, applying VIP policies, and tracking ongoing customer complaints over time.
Sources: README.md:92-101, app.py:539-543

System Architecture

The memory system operates as a "read-on-start, write-on-finish" mechanism. On every pipeline run, the orchestrator aggregates the content of relevant memory files into a rich text context block, which is then injected into the system prompts of the AI agents.

Core Memory Components

The system is composed of five primary Markdown files, each serving a distinct architectural role:

Memory File	Description	Usage in System
company_context.md	Contains static policies, pricing tiers, and tone guidelines.	Policy enforcement and product knowledge.
customer_history.md	Per-customer logs including previous interactions and status.	Identifying returning customers and VIP status.
sales_notes.md	Pipeline activity, competitor analysis, and lead stages.	Managing sales opportunities and conversion logic.
open_tasks.md	A centralized list of outstanding manual actions.	Task tracking and prioritization.
decision_log.md	A historical log of automated agent actions and reasons.	Audit trail and behavioral consistency.

Sources: README.md:103-109, orchestrator.py:126-133

Data Flow Diagram

The following diagram illustrates how memory is retrieved, processed by agents, and subsequently updated in the file system.

The flow shows the circular relationship where agent outputs are parsed by utility functions to update the source files for future runs.
Sources: orchestrator.py:202-270, memory_utils.py:18-25

Memory Retrieval Logic

Memory retrieval is handled by the load_memory() function, which performs a structured aggregation of files. It iterates through the specific list of files and wraps them in Markdown headers (## filename) to help the LLM distinguish between different context types.

def load_memory() -> str:
    files = ["company_context.md", "customer_history.md", "sales_notes.md", "open_tasks.md"]
    combined = []
    for f in files:
        content = load_file(MEMORY / f)
        if content:
            combined.append(f"## {f}\n\n{content}")
    return "\n\n---\n\n".join(combined)

Sources: orchestrator.py:126-133, app.py:279-286

For administrative or briefing requests, the system utilizes build_admin_context(), which merges file-based memory with recent data from the SQLite database to provide a "full operational context."
Sources: orchestrator.py:90-111

Persistence and Update Mechanisms

Updates to the memory files are managed by memory_utils.py. Instead of overwriting entire files, the system primarily uses structured appends to maintain history.

Structured Write-Backs

The system includes specialized functions to modify files based on agent outcomes:

• update_customer_history: Searches for a customer's ## Name header and injects updates before the next separator or at the end of the file.
• add_open_task: Injects new tasks into specific priority sections (e.g., ## HIGH PRIORITY) within open_tasks.md.
• update_decision_log: Appends a timestamped block detailing the event, agent, action, and reasoning.

Sources: memory_utils.py:46-68, memory_utils.py:73-86, memory_utils.py:34-43

Sequence of a Memory Update

This sequence highlights how specific scenario triggers in the code map to file system modifications.
Sources: orchestrator.py:263-267, memory_utils.py:252-270

Maintenance and Resets

Since the system modifies local files, a reset_demo.py utility is provided to manage file state during testing or demonstrations.

• Backup: Creates copies of current .md files in a memory_backup/ directory.
• Restore: Overwrites the active memory/ files with the versions from the backup to return the system to a known baseline state.
• Database Sync: Simultaneously clears the SQLite events, tasks, and crm_log tables to ensure consistency between the file memory and the relational logs.

Sources: reset_demo.py:19-53

Conclusion

The File-Based Memory System provides a transparent and accessible way to manage agent knowledge. By leveraging the structured formatting of Markdown, BrightPath achieves a balance between automated LLM context management and human-in-the-loop oversight. This system ensures that critical business intelligence—from customer complaints to sales pipeline stages—is preserved and evolved through every automated interaction.