Sessions

Agentix automatically manages session state across turns. Every query() call on a live AgentixClient shares the same session by default.

Default behavior

async with AgentixClient(options) as client:
    async for msg in client.query("Remember: my name is Alice."):
        if isinstance(msg, ResultMessage): pass

    # Same session — agent remembers "Alice"
    async for msg in client.query("What is my name?"):
        if isinstance(msg, ResultMessage):
            print(msg.result)  # "Your name is Alice."

The session ID is tracked automatically from ResultMessage.session_id. You never need to pass it manually.

Starting a fresh conversation

client.reset_session()  # clears session ID; next query() starts a fresh session

Resuming a previous session

# Resume by explicit session ID
options = AgentixAgentOptions(resume="sess-abc123")

# Auto-resume the most recent session for this agent/project
options = AgentixAgentOptions(continue_conversation=True)

Forking a session

Forking creates a copy under a new ID — useful for branching a conversation to explore different paths without losing the original.

options = AgentixAgentOptions(fork_session=True)

continue_conversation and fork_session cannot both be True — a ConfigurationError is raised.

Getting the session ID

async for msg in client.query("Hello"):
    if isinstance(msg, ResultMessage):
        print(msg.session_id)   # e.g. "sess-abc123"

Listing and loading sessions

from agentix import list_sessions, get_session_messages

# List all sessions under a project directory (newest first)
sessions = list_sessions(directory="/path/to/project")
for s in sessions:
    print(s.session_id, s.summary, s.last_modified)

# List sessions across all projects
all_sessions = list_sessions()

# Limit results
recent = list_sessions(directory="/path/to/project", limit=10)

list_sessions returns list[SDKSessionInfo] sorted by last_modified descending.

SDKSessionInfo field	Description
session_id	Session identifier
summary	Custom title, first prompt, or session ID (in that priority)
last_modified	Milliseconds since epoch
file_size	Session file size in bytes
custom_title	Custom title if set
first_prompt	First user message if available
cwd	Working directory when session was created

from agentix import get_session_messages

# Load all messages for a session
messages = get_session_messages(session_id="sess-abc123")

# Scope to a project directory
messages = get_session_messages(
    session_id="sess-abc123",
    directory="/path/to/project",
)

# Paginate
page = get_session_messages(
    session_id="sess-abc123",
    offset=20,
    limit=10,
)

get_session_messages returns list[SessionMessage] in chronological order.

Persistence configuration

options = AgentixAgentOptions(
    persistence_enabled=True,                        # default: True
    storage_base_path="~/.agentix/projects",         # default storage location
    conversation_summarization_enabled=True,         # default: True — summarize vs drop old messages
    max_conversation_window=10,                      # default: keep last 10 messages verbatim
    max_context_tokens=16384,                        # default: trigger compaction at 16k tokens
)

When persistence_enabled=False, sessions exist only in memory for the lifetime of the AgentixClient. Use a storage backend for distributed deployments.

Context compaction

When the conversation exceeds max_context_tokens, older messages are automatically summarized to keep the context window within budget. The most recent memory_window messages are always kept verbatim.

options = AgentixAgentOptions(
    max_context_tokens=16384,          # default: trigger compaction at 16k tokens
    max_conversation_window=10,        # default: keep last 10 messages verbatim
)

The PreCompact hook fires before each compaction:

from agentix import HookMatcher

async def on_compact(hook_input: dict, context) -> None:
    print(f"Compacting — {hook_input['current_count']} messages in history")

options = AgentixAgentOptions(
    hooks={"PreCompact": [HookMatcher(matcher=None, hooks=[on_compact])]}
)

Conversation summarization

When compaction triggers, Agentix summarizes older messages by default (conversation_summarization_enabled=True). The summary is injected as a system message so the agent retains context without the full history.

To disable summarization — older messages are dropped instead of summarized:

options = AgentixAgentOptions(
    conversation_summarization_enabled=False,
)