trellis
Version:
Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications
100 lines • 3.27 kB
TypeScript
/**
* Heat-Map Context Manager — Relevance-weighted message retention.
*
* Replaces naive FIFO pruning with a heat-score system that considers:
* - Recency: newer messages score higher
* - Reference frequency: messages the LLM referenced score higher
* - Role priority: system messages are never pruned
*
* Heat scores decay each turn, and messages the model referenced get
* boosted. When pruning to a target token budget, lowest-heat messages
* are dropped first.
*
* @module trellis/context
*/
import type { LLMMessage } from '../llm/types.js';
import type { ContextManager } from './types.js';
export interface HeatMapConfig {
/**
* Decay multiplier applied to all heat scores each turn.
* Lower values = faster decay. Default: 0.85
*/
decayFactor?: number;
/**
* Base heat score assigned to new messages.
* Default: 1.0
*/
baseHeat?: number;
/**
* Heat boost applied when a message is referenced.
* Default: 0.5
*/
referenceBoost?: number;
/**
* Minimum heat score — messages below this during pruning are
* prioritized for removal. Default: 0.1
*/
pruneThreshold?: number;
}
export interface ScoredMessage {
message: LLMMessage;
heat: number;
addedAtTurn: number;
referenceCount: number;
}
export declare class HeatMapContextManager implements ContextManager {
private messages;
private turnCount;
private config;
constructor(config?: HeatMapConfig);
addMessage(message: LLMMessage): void;
getHistory(): LLMMessage[];
prune(targetTokenCount: number): Promise<void>;
summarize(): Promise<string>;
injectRagContext(_query: string, _limit?: number): Promise<void>;
calculateTokenCount(message: LLMMessage): number;
/**
* Advance the turn counter and decay all heat scores.
* Call this at the start of each LLM turn.
*/
advanceTurn(): void;
/**
* Boost heat for messages that were referenced in the model's response.
*
* Detection is based on content overlap: if the response contains
* substrings from a previous message, that message gets boosted.
*
* @param response - The model's response content to check for references
* @param minOverlap - Minimum substring length to count as a reference (default: 20)
*/
boostReferencedMessages(response: string, minOverlap?: number): void;
/**
* Manually boost a specific message's heat score.
* Useful when the caller knows a particular message is relevant.
*/
boostMessage(index: number, boost?: number): void;
/**
* Get the heat scores for all messages.
*/
getHeatMap(): Array<{
role: string;
heat: number;
referenceCount: number;
preview: string;
}>;
/**
* Get the current turn count.
*/
getTurnCount(): number;
/**
* Get scored messages (for inspection/testing).
*/
getScoredMessages(): ReadonlyArray<ScoredMessage>;
private _totalTokens;
/**
* Extract representative substrings from content for overlap detection.
* Takes samples from the beginning, middle, and end.
*/
private _extractSamples;
}
//# sourceMappingURL=heat-map-manager.d.ts.map