# ChocolateLMLite Conversation Statistics: A Complete Guide to TalkStats

> Explore ChocolateLMLite conversation statistics with TalkStats. Discover total messages, archived history, token counts, and more with this comprehensive guide.

- Repository: [Segment (gpsnmeajp)/chocolatelmlite](https://github.com/gpsnmeajp/chocolatelmlite)
- Tags: tutorial
- Published: 2026-03-02

---

**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`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/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`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/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:

```csharp
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`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/LLM.cs).

### XML Tag Construction

The engine builds the tag at lines 259‑266 in [`src/LLM.cs`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/src/LLM.cs), conditionally appending the `need_rest_reminder` attribute only when the threshold is exceeded:

```csharp
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`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/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`](https://github.com/gpsnmeajp/chocolatelmlite/blob/main/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.