NarraNexusNarraNexus
NarraNexus · Modules

Chat Module

Manages conversational sessions between agent and user. Each session is scoped to a Narrative, giving the agent topic-aware memory and isolated conversation history.

Session Management

The ChatModule creates one session (instance) per user per Narrative. When you talk about project planning, that conversation lives in one session. When you switch to a personal topic, a different session tracks that history. This means:

Topic isolationConversations about different topics don’t bleed into each other. Each session carries its own history.
Automatic scopingWhen the Narrative system routes your message to a topic, the matching ChatModule session is loaded automatically.
Cross-topic awarenessWhile sessions are isolated, the agent still loads recent messages from other sessions so it knows what you were just discussing.

Sessions are created dynamically — there is no fixed “main” session. The agent can also retrieve past conversation history from any session using get_chat_history, which is useful when it needs to recall what was said in a specific topic.

How Communication Works

A core design principle in NarraNexus: all agent reasoning, tool calls, and internal processing are invisible to the user. The only way an agent delivers a visible message is by calling send_message_to_user_directly.

This gives the agent full control over what users see. Background tasks complete silently, routine operations stay hidden, and only meaningful results are surfaced. The agent follows delivery discipline:

User talks directlyAlways respond with a visible message
Background job completesSend the final report, not progress updates
IM channel message receivedOnly forward if @mentioned, urgent, or critical
Routine processingStay silent — no confirmations or status updates

What Gets Recorded

After each interaction, the ChatModule persists three things:

Conversation history

The user’s message and the agent’s visible reply are appended to the session’s message store. For background tasks where the agent chose not to message the user, a lightweight activity summary is stored instead.

Status report

A compact summary of the session state (conversation count, latest exchange) stored at the Narrative level. Used by the Narrative system when making routing decisions.

Message embeddings

Each user–agent message pair is embedded as a vector, enabling semantic search over older conversations for future retrieval.

This recorded history is what the agent sees as context in future conversations. For details on how memory is loaded and budgeted, see Builtin Memory.

Tools

send_message_to_user_directlyDeliver a visible message to the user
get_chat_historyRetrieve past conversation from a specific session