core.history.permanent

Maintain an append-only chronological turn history with coalesced consecutive user turns.

Maintain an append-only chronological turn history with coalesced consecutive user turns.

class PermanentHistory

Bases: object

Append-only chronological turn history with timestamps.

Each turn stores a role ("user" or "assistant"), structured content, a per-turn timestamp, and optional metadata. Consecutive user turns are coalesced by appending content unless the caller passes non-None metadata, in which case a new turn is always created (so distinct prompt_name metadata is never silently merged).

add_turn_assistant(content, metadata=None)

Append an assistant turn with the current timestamp.

Parameters:

• content (str) – The assistant’s response text.

• metadata (dict[str, Any] | None) – Optional caller metadata. When provided, stored on the turn dict under the "metadata" key. Defaults to an empty dict.

Return type:

None

add_turn_user(content, metadata=None)

Append a user turn, coalescing with the previous user turn when adjacent.

Coalescing only happens when metadata is None. If metadata is provided, a new turn is always created so distinct prompt_name metadata is never silently merged into the previous user turn.

Parameters:

• content (str) – The user’s input text.

• metadata (dict[str, Any] | None) – Optional caller metadata. When non-None, forces creation of a new turn (no coalescing).

Return type:

None

get_all_turns()

Return a deep copy of all turns with their timestamps.

Returns:

List of turn dictionaries.

Return type:

list[dict[str, Any]]

get_turns_since(timestamp)

Return turns that occurred after the specified timestamp.

Parameters:

timestamp (float) – Unix timestamp cutoff (exclusive).

Returns:

List of turn dictionaries whose timestamp is greater than timestamp.

Return type:

list[dict[str, Any]]

Classes

class PermanentHistory

Bases: object

Append-only chronological turn history with timestamps.

Each turn stores a role ("user" or "assistant"), structured content, a per-turn timestamp, and optional metadata. Consecutive user turns are coalesced by appending content unless the caller passes non-None metadata, in which case a new turn is always created (so distinct prompt_name metadata is never silently merged).

add_turn_assistant(content, metadata=None)

Append an assistant turn with the current timestamp.

Parameters:

• content (str) – The assistant’s response text.

• metadata (dict[str, Any] | None) – Optional caller metadata. When provided, stored on the turn dict under the "metadata" key. Defaults to an empty dict.

Return type:

None

add_turn_user(content, metadata=None)

Append a user turn, coalescing with the previous user turn when adjacent.

Coalescing only happens when metadata is None. If metadata is provided, a new turn is always created so distinct prompt_name metadata is never silently merged into the previous user turn.

Parameters:

• content (str) – The user’s input text.

• metadata (dict[str, Any] | None) – Optional caller metadata. When non-None, forces creation of a new turn (no coalescing).

Return type:

None

get_all_turns()

Return a deep copy of all turns with their timestamps.

Returns:

List of turn dictionaries.

Return type:

list[dict[str, Any]]

get_turns_since(timestamp)

Return turns that occurred after the specified timestamp.

Parameters:

timestamp (float) – Unix timestamp cutoff (exclusive).

Returns:

List of turn dictionaries whose timestamp is greater than timestamp.

Return type:

list[dict[str, Any]]