Chat History

The ChatHistoryManager persists conversations, prunes old messages on every read/write, and formats output for the active provider’s role convention.

Auto-pruning

Enabled by default. Runs transparently on every history operation. Permanently deletes — not just hides.

Rules in priority order:

Rule	Default	Behavior
Age	30 days (720 h)	Messages older than maxAgeHours removed first
Count	50 messages	If over maxMessages, oldest go first
Tokens	32 000	If over maxTokens, oldest go first

System messages are always preserved when preserveSystemMessages is true (default).

Token estimation: 4 chars ≈ 1 token — conservative enough to prevent overflow, generous enough not to strip useful context.

sequenceDiagram participant UI participant CHM as ChatHistoryManager participant DB as AgentService (SQLite) participant Cache as In-memory cache UI->>CHM: Send message CHM->>DB: Read existing history CHM->>CHM: Add timestamp, merge Note over CHM: Prune (age → count → tokens)<br/>system messages kept CHM->>DB: Save pruned history CHM->>Cache: Sync fast-path cache CHM->>CHM: Format per provider (role mapping) CHM-->>UI: Formatted history

Provider role mapping

Each provider has its own role names + message shape. LLM_CONFIGS holds the mapping; formatChatHistory(role, message, model, key) produces the correct output for the active model.

Flow per call:

1. Raw history from SQLite (or in-memory fast-path).
2. Append new message with timestamp.
3. Prune combined result.
4. Save pruned back to SQLite.
5. Format each entry via model’s role mapping (user / assistant / system).
6. Return formatted array to the LLM caller.

Conversation summaries

For long conversations you want to keep a synopsis of instead of the full transcript:

await chatHistory.saveSummary(key, "Auth setup covered...");
const summary = await chatHistory.getSummary(key);

Summaries live alongside the full history in SQLite. Useful for injection when the full history is too large to fit.

Storage

• Primary: SQLite via AgentService. Keyed by workspace identity + conversation ID.
• Fast-path: in-memory cache (Memory class in src/memory/base.ts) kept in sync for repeated reads within a session.
• clearHistory() purges both.

Settings

Setting	Default	Purpose
chatHistory.enableAutoPruning	true	Enable pruning
chatHistory.maxMessages	50	Message cap
chatHistory.maxTokens	32000	Token cap
chatHistory.maxAgeHours	720	Age cap (30 days)

These keys are read from settings.json directly and aren’t surfaced in the Settings UI — add them by hand if you want to tune pruning.

Why delete, not hide?

• Memory — old history doesn’t accumulate.
• Privacy — code snippets, keys, and secrets in old messages don’t linger.
• Perf — smaller history = faster queries + less formatting work.
• Quality — LLMs perform better with focused, recent context.

Related

• Context system — how history fits into the per-turn context budget
• Memory — persistent facts (survives conversation clears)
• Self-healing §Layer 4 — window-based summarization for long single conversations