HistoryConfig
Defined in: packages/engine/src/lib/history/history-manager.ts:29
Persistence, retention, and prompt-projection policy for Engine history.
Type Parameters
Section titled “Type Parameters”TMeta = unknown
Properties
Section titled “Properties”deriveLLMContext?
Section titled “deriveLLMContext?”
readonlyoptionalderiveLLMContext?: (entry,defaults) => readonlyLLMContextMessage[]
Defined in: packages/engine/src/lib/history/history-manager.ts:69
Optional projection from a stored entry to the LLM-context messages it
contributes. Called once per retained entry during getLLMContext and
once per entry during truncation cost estimation, so keep the projection
cheap and side-effect-free. When omitted, the engine uses its default
projection: turns produce a user message (from user_intent reasons) +
an assistant message (from the response’s userMessage); injections
produce a single assistant message.
The defaults callback returns the engine’s default projection for the
same entry, enabling compose-with-default overrides without reimplementing
the full projection. Call it from any branch that should fall through to
default behavior; ignore it entirely for a full replacement.
Override to expose richer stored metadata to the LLM, rewrite roles,
or merge multiple entries into a single context message.
Parameters
Section titled “Parameters”HistoryEntry<TMeta>
defaults
Section titled “defaults”() => readonly LLMContextMessage[]
Returns
Section titled “Returns”readonly LLMContextMessage[]
maxChars?
Section titled “maxChars?”
readonlyoptionalmaxChars?:number
Defined in: packages/engine/src/lib/history/history-manager.ts:44
Budget for total characters in retained LLM-context projections. Omit to
disable it. With createEngine, this must be a positive integer and
an assistant_message whose content.length exceeds it is rejected.
Truncation retains the newest entry even if its projection alone exceeds
the budget. Direct createHistoryManager calls skip those Engine
boundary checks; a non-positive value retains no entries.
maxEntries?
Section titled “maxEntries?”
readonlyoptionalmaxEntries?:number
Defined in: packages/engine/src/lib/history/history-manager.ts:35
Hard cap on per-session entry count. Omit to disable the entry-count
cap entirely — truncation then relies solely on maxChars (or becomes
a no-op if that is also omitted).
readonlystore:HistoryStore<TMeta>
Defined in: packages/engine/src/lib/history/history-manager.ts:81
Backing store. Required — the engine never silently defaults to an
in-process store. Local dev and tests should pass createInMemoryStore()
explicitly; production deployments supply a persistent, atomic store.
Making this explicit prevents the footgun of shipping a configured
history block to production and silently losing every session on
process restart.
transformEntry?
Section titled “transformEntry?”
readonlyoptionaltransformEntry?: (entry) =>HistoryEntry<TMeta>
Defined in: packages/engine/src/lib/history/history-manager.ts:51
Optional per-entry transform applied before persistence. Runs for both
turn and injection entries. Use to strip fields a production store
doesn’t need (rationale, vessel snapshots, etc.) — or to enrich entries
with typed metadata before they’re stored.
Parameters
Section titled “Parameters”HistoryEntry<TMeta>
Returns
Section titled “Returns”HistoryEntry<TMeta>