Scene History Nodes

Work with the scene's message history and its summarized archive: query messages by type or id, push/pop messages, and manage static archive entries (pre-authored history that survives summarization).

13 nodes.

Node	Registry path
Character Activity	scene/history/ActiveCharacterActivity
Context History	scene/history/ContextHistory
Create Static Archive Entry	scene/history/CreateStaticArchiveEntry
Get Message By ID	scene/history/GetMessageById
Scene Has History	scene/history/HasHistory
Last Message of Type	scene/history/LastMessageOfType
Pop History	scene/history/Pop
Push History	scene/history/Push
Remove Static Archive Entry	scene/history/RemoveStaticArchiveEntry
Set Arrival Note	scene/history/SetArrivalNote
Static Archive Entries	scene/history/StaticArchiveEntries
Unpack Archive Entry	scene/history/UnpackArchiveEntry
Unpack Character Transition	scene/history/UnpackCharacterTransition

Character Activity

scene/history/ActiveCharacterActivity

Returns a list of all active characters sorted by which were last active

The most recently active character is first in the list.

Outputs

Output	Type	Description
none_have_acted	bool	whether no characters have acted
characters	list	list of characters

Properties

Property	Type	Default	Description
since_time_passage	bool	False	Only include characters that have acted since the last time passage message

Context History

scene/history/ContextHistory

Compiles history for inclusion in a prompt context.

Inputs

Input	Type	Description
budget	int	(optional) The budget for the history (number of tokens, defaults to 8192)
perspective	str,character	Compile the history as this character knows it (optional). With Character Perspectives on, it is built from the character's own views of each passage; otherwise passages and summaries the character does not know are left out.

Outputs

Output	Type	Description
messages	list	list of messages
compiled	str	compiled message
characters	list	list of characters that have actively participated in the scene

Properties

Property	Type	Default	Description
budget	int	8192	The budget for the history (number of tokens, defaults to 8192). Min: 0.
keep_director_messages	bool	False	Whether to keep director messages
keep_investigation_messages	bool	False	Whether to keep investigation messages
keep_reinforcement_messages	bool	False	Whether to keep reinforcement messages
show_hidden	bool	False	Whether to show hidden messages
min_dialogue_length	int	5	The minimum length of dialogue to keep, this will ensure that there are always N dialogue messages in the history regardless of whether they are covered by summarization. Min: 0.
label_chapters	bool	False	Whether to label chapters in the summarized history

Create Static Archive Entry

scene/history/CreateStaticArchiveEntry

Create a static (manually written) archive entry in the scene's base history, dated a given amount of time before the current scene time.

The time amount and unit are converted to an offset in seconds. The entry must predate the summarized history.

Inputs

Input	Type	Description
state	any	The graph state
time_unit	str	The unit of time for the offset (minute, hour, day, week, month, year)
time_amount	int	The amount of time for the offset
text	str	The text of the entry

Outputs

Output	Type	Description
state	any	The state input, passed through
entry	history/archive_entry	The created archive entry
offset	int	The offset in seconds that was applied
context_id	context_id	Context ID for the created entry
time_unit	str	The time unit input, passed through
time_amount	int	The time amount input, passed through
text	str	The text input, passed through

Properties

Property	Type	Default	Description
time_unit	str	"day"	The unit of time. Choices: minute, hour, day, week, month, year.
time_amount	int	1	The amount of time
text	str	""	The text of the entry

Get Message By ID

scene/history/GetMessageById

Get a message from the scene history by its ID

Inputs

Input	Type	Description
message_id	int	The ID of the message to get

Outputs

Output	Type	Description
message	message_object	The message object (None if not found, or no value if stop_on_missing is true)
message_id	int	The ID of the message (passthrough)

Properties

Property	Type	Default	Description
stop_on_missing	bool	True	If true, deactivate the message output wire when message is not found

Scene Has History

scene/history/HasHistory

Check if the scene has history

Looks for a character, narrator or context_investigation message within the most recent 100 history entries.

Outputs

Output	Type	Description
has_history	bool	True if such a message was found

Last Message of Type

scene/history/LastMessageOfType

Get the last message of a certain type from the history with some basic filtering.

Inputs

Input	Type	Description
message_type	str,list	The type of message to get (or a list of types)
filters	dict	(optional) filter the messages by property values

Outputs

Output	Type	Description
message	message_object	The message object

Properties

Property	Type	Default	Description
message_type	str	unset	The type of message to get (or a list of types). Choices: scene, character, narrator, director, time, reinforcement, context_investigation, character_transition, scene_backdrop.
max_iterations	int	100	The maximum number of iterations to go back
stop_on_time_passage	bool	False	Stop when a time passage message is encountered
filters	dict	{}	Filter the messages by property values

Pop History

scene/history/Pop

Pop a message from the scene history

Inputs

Input	Type	Description
message	message_object	The message to pop

Outputs

Output	Type	Description
message	message_object	The message object

Properties

Property	Type	Default	Description
emit_removal	bool	True	Emit the removal of the message

Push History

scene/history/Push

Push a message to the scene history at the lowest (e.g., dialogue) layer

This will emit the message to the screen as part of the ongoing scene

Inputs

Input	Type	Description
message	message_object	The message to push

Outputs

Output	Type	Description
message	message_object	The message object

Properties

Property	Type	Default	Description
emit_message	bool	True	Emit the message to the screen

Remove Static Archive Entry

scene/history/RemoveStaticArchiveEntry

Remove a static archive entry

The entry can be specified either directly or via a context ID item - at least one of the two is required. Raises an error if the resolved entry is not a static history entry.

Inputs

Input	Type	Description
state	any	The graph state
entry	history/archive_entry	The archive entry to remove
context_id_item	context_id_item	A context ID item referencing a static history entry

Outputs

Output	Type	Description
state	any	The graph state
entry	history/archive_entry	The removed entry
context_id_item	context_id_item	The context ID item input, passed through

Set Arrival Note

scene/history/SetArrivalNote

Write the note of an arrival entry, as the note field under an arrival in the history does: what the character did or learned while away.

Inputs

Input	Type	Description
state	any	graph state (passthrough)
message	message_object	the arrival entry
text	str	(optional) the note; empty removes it

Outputs

Output	Type	Description
state	any	graph state
message	message_object	the arrival entry

Properties

Property	Type	Default	Description
text	text	""	The arrival note

Static Archive Entries

scene/history/StaticArchiveEntries

Get the static scene history entries

Static entries are manually written archive entries that predate the summarized history. Collection stops at the first summarized (dynamic) entry. Entries are annotated with a human readable time relative to the current scene time.

Outputs

Output	Type	Description
entries	list	The list of static archive entries

Unpack Archive Entry

scene/history/UnpackArchiveEntry

Unpack an archive (summarized history) entry into its individual fields and build a context ID for it.

Inputs

Input	Type	Description
entry	history/archive_entry	The archive entry to unpack

Outputs

Output	Type	Description
entry	history/archive_entry	The entry, passed through
id	str	The id of the entry
text	str	The text of the entry
index	int	The index of the entry within its history layer
layer	int	The history layer the entry belongs to
start	int	Index of the first source entry covered by the entry (None for static entries)
end	int	Index of the last source entry covered by the entry (None for static entries)
ts_start	int	Starting timestamp of the covered range (seconds since scene start)
ts_end	int	Ending timestamp of the covered range (seconds since scene start)
ts	int	Timestamp of the entry (seconds since scene start)
time	str	Human readable time relative to the current scene time
time_start	str	Human readable starting time of the covered range
time_end	str	Human readable ending time of the covered range
context_id	context_id	Context ID for the entry (static or dynamic depending on the entry type)

Unpack Character Transition

scene/history/UnpackCharacterTransition

Read an arrival or departure entry of the history, for example the transition of a character.activated or character.deactivated event.

Inputs

Input	Type	Description
message	message_object	the arrival or departure entry

Outputs

Output	Type	Description
message	message_object	the entry, passed through
character_name	str	who arrived or left
kind	str	activated (arrival) or deactivated (departure)
returning	bool	True when the character arrives back after a departure
participants	list	the characters in the scene at the arrival
arrival_note	str	the note written for the arrival
departure_message_id	int	the entry the absence started at, or None
absence_seconds	int	scene time the character was away, or None