ChocolateLMLite Conversation Statistics: A Complete Guide to TalkStats

ChocolateLMLite tracks seven conversation-level metrics—including total messages, archived history, and token counts—via the TalkStats class and exposes them to the LLM as XML-like tags when the statistics feature is enabled.

The gpsnmeajp/chocolatelmlite repository implements a lightweight LLM interface that monitors conversation health through structured conversation statistics. These metrics help manage context windows, enforce rate limiting, and trigger break reminders based on user activity patterns.

Available Conversation Statistics in TalkStats

The TalkStats class defined in src/FileManager.cs encapsulates seven key metrics calculated from the active persona's message history.

• Total (Total): Count of all messages stored (user + assistant + system).
• Archived (Archived): Messages removed from the active chat window by time-based or token-based cutoff.
• UserLast8h (UserLast8h): Number of user-originated messages sent within the last 8 hours.
• TotalTokens (TotalTokens): Token count for the entire message history including system prompts.
• NeedUserRestRemind (NeedUserRestRemind): Boolean flag set to true when UserLast8h exceeds the global BreakReminderThreshold.
• RawSystemPromptTokens (RawSystemPromptTokens): Token count of the base system prompt before persona-specific augmentation.
• BuiltSystemPromptTokens (BuiltSystemPromptTokens): Token count of the final system prompt actually injected into the LLM request.

How Statistics Are Calculated and Retrieved

The FileManager Implementation

In src/FileManager.cs (lines 164‑173), the TalkStats class serves as the data transfer object for all conversation metrics. The engine populates this structure through FileManager.GetTalkStatsFromActivePersona(), which aggregates data from the current persona's talk history and global settings to produce real-time statistics.

Programmatic Access

Developers can retrieve these metrics programmatically for custom tooling or extensions:

var fm = new FileManager();                     
TalkStats? stats = fm.GetTalkStatsFromActivePersona();

if (stats != null) {
    Console.WriteLine($"Total messages: {stats.Total}");
    Console.WriteLine($"Archived messages: {stats.Archived}");
    Console.WriteLine($"User msgs (last 8h): {stats.UserLast8h}");
    Console.WriteLine($"Total tokens: {stats.TotalTokens}");
    Console.WriteLine($"Rest reminder needed? {stats.NeedUserRestRemind}");
}

Injecting Statistics into LLM Prompts

When the statistics and break-reminder feature is enabled via EnableStatisticsAndBreakReminder, ChocolateLMLite injects a <conversations_statistics/> tag into the prompt header constructed in src/LLM.cs.

XML Tag Construction

The engine builds the tag at lines 259‑266 in src/LLM.cs, conditionally appending the need_rest_reminder attribute only when the threshold is exceeded:

string additionalInfo = $"<conversations_statistics total='{stats.Total}' archived='{stats.Archived}' user_messages_last_8h='{stats.UserLast8h}' total_tokens='{stats.TotalTokens}'";
if (stats.NeedUserRestRemind) {
    additionalInfo += $" need_rest_reminder='{stats.NeedUserRestRemind}'";
}
additionalInfo += "/>\n";
builtUserMessageHeader += additionalInfo;

This XML fragment provides the LLM with real-time context about conversation length and token pressure, enabling the model to adjust its responses for long-running sessions.

API and UI Integration

REST API Exposure

While not part of the core REST API surface directly, the statistics are packaged into JSON responses via src/Persona.cs (lines 560‑580) when the /api/persona endpoint is queried. This allows frontend applications to display conversation health badges without parsing prompt internals.

Web Interface Toggle

Users can observe these metrics without writing code. The Web UI includes a toggle for statistics and break-reminder that controls the EnableStatisticsAndBreakReminder setting. When enabled, the interface renders a badge showing message counts and token usage, and the <conversations_statistics/> tag appears in the generated prompt visible in debug outputs.

Summary

ChocolateLMLite provides a robust conversation statistics framework through the TalkStats class:

• Seven tracked metrics cover message counts, archival status, token usage, and rest reminders.
• FileManager.cs handles calculation via GetTalkStatsFromActivePersona().
• LLM.cs injects statistics as XML tags into prompts when enabled.
• Persona.cs exposes data to the REST API for UI consumption.
• Conditional break reminders trigger when user message volume exceeds the 8‑hour threshold.

Frequently Asked Questions

How do I enable conversation statistics in ChocolateLMLite?

Enable the EnableStatisticsAndBreakReminder setting in your global configuration. When active, the system calculates TalkStats for the current persona and inserts the <conversations_statistics/> tag into every LLM prompt. The Web UI provides a toggle switch for this feature, allowing non-technical users to activate statistics without modifying code.

What is the difference between RawSystemPromptTokens and BuiltSystemPromptTokens?

RawSystemPromptTokens counts tokens in the base system prompt before any persona-specific augmentation or dynamic content injection. BuiltSystemPromptTokens represents the final token count after all replacements, context additions, and formatting are applied—the actual payload sent to the LLM. This distinction helps developers optimize prompt engineering by comparing base template size versus final request size.

How does the break reminder threshold work?

The system compares UserLast8h (user messages in the last 8 hours) against the global BreakReminderThreshold value. When the count exceeds this threshold, NeedUserRestRemind becomes true, and the XML tag includes need_rest_reminder='True'. This signals both the UI to display a rest suggestion and the LLM to potentially adjust its tone for users showing high engagement levels.

Can I access conversation statistics through the REST API?

Yes, though indirectly. The /api/persona endpoint returns JSON containing the conversation statistics packaged by src/Persona.cs (lines 560‑580). While there is no dedicated /api/stats endpoint, querying the active persona provides the same TalkStats values available in the prompt injection system, suitable for building custom dashboards or monitoring tools.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}