Conversation

Overview

The Conversation class manages conversation history for agents, allowing for addition, deletion, and retrieval of messages. It supports saving and loading in JSON/YAML formats, per-message token counting, and trimming the rendered history to a context window. Every Agent keeps its history in one, as agent.short_memory.

Installation

pip install -U swarms

from swarms import Conversation

Parameters

Optional[str]

default:"auto-generated"

Unique identifier for the conversation.

Optional[str]

default:"None"

Name of the conversation. When omitted, each instance gets a unique name of the form conversation-<8 hex characters>. Only an explicitly named conversation resumes from its save file.

Optional[str]

default:"None"

Added as the first message, with role "System", when a new conversation starts. Not re-added when history is restored from disk.

bool

default:"False"

Add an ISO timestamp to each message.

bool

default:"False"

Call export() after every add(), writing the history to save_filepath.

str

default:"None"

File the history is saved to. Defaults to <conversations_dir>/conversation_<name>.json (or .yaml, following export_method). An extension that does not match export_method is replaced. Setting it explicitly makes the conversation resume from that file when it exists.

str

default:"None"

Marks the conversation as one that resumes from disk. The constructor still reads save_filepath, not this path. To load a specific file, call load(path) or Conversation.load_conversation(name, load_filepath=path).

int

default:"8192"

Maximum number of tokens allowed in the conversation history. Used by truncate_memory_with_tokenizer() and dynamic_context_window.

str

default:"None"

Added after the system prompt as a message whose role is user, when a new conversation starts.

str

default:"None"

Added after rules as a message whose role is user, when a new conversation starts.

str

default:"User"

Role used for the rules and custom_rules_prompt messages.

bool

default:"False"

Stored but not read. The save format comes from export_method.

bool

default:"False"

Stored but not read. The save format comes from export_method.

bool

default:"False"

Count each message’s tokens and store the result under its token_count key.

bool

default:"False"

Attach a UUID4 message_id to every message.

str

default:"gpt-5.4"

Model name used by the tokenizer for token counting and truncation.

Optional[str]

default:"None"

Directory for the default save_filepath, and the default directory for load_conversation() and list_conversations(). When unset, ./conversations under the current working directory is used. The directory is created only when a file is written.

str

default:"json"

Format used by export() and autosave: "json" or "yaml". Any other value raises ValueError at construction.

bool

default:"True"

When True, return_history_as_string() drops text from the front of the rendered history until it fits in context_length tokens. The stored messages are not changed.

bool

default:"False"

Memoize the string returned by return_history_as_string() until the history changes, and record its token count for get_cache_stats().

bool

default:"False"

Stored but not read by Conversation.

Optional[str]

default:"None"

Path to a MEMORY.md file for persistent memory. The file is created with a header if missing. Prior interactions in it are loaded as one "System" message, and every later add() appends to it.

Optional[List[Dict[str, Any]]]

default:"None"

Chat-format messages ({"role": ..., "content": ...}) added after the system prompt and rules, through add_messages(). Agent(messages=...) uses this to seed short_memory.

Construction and resume

The constructor runs these steps in order:

Resume

If you passed name, save_filepath, or load_filepath, and the file at save_filepath exists, its history is loaded.

Seed

Only when nothing was restored: system_prompt, then rules, then custom_rules_prompt are added.

Persistent memory

With memory_md_path, prior MEMORY.md content is added as one "System" message.

Messages

messages, if given, are appended.

An unnamed conversation gets a fresh random name, so it never resumes another instance’s file. Constructing a Conversation writes nothing to disk unless memory_md_path is set, or autosave is on and a seeded message triggers a save.

Methods

add()

Add a message to the conversation history.

def add(
    self,
    role: str,
    content: Union[str, dict, list, Any],
    metadata: Optional[dict] = None,
    category: Optional[str] = None,
) -> dict

Parameters:

role (str): The role of the speaker (e.g., ‘User’, ‘System’, ‘Agent’)
content (Union[str, dict, list]): The content of the message
metadata (Optional[dict]): Optional metadata, stored under the message’s metadata key
category (Optional[str]): Optional category for the message (e.g., ‘input’, ‘output’)

Returns: The stored message dict. Depending on the constructor flags it also carries timestamp, message_id, category, metadata, and token_count. With autosave=True, the conversation is exported after the add.

add_messages()

Add chat-format messages in order.

def add_messages(self, messages: List[Dict[str, Any]]) -> list

Parameters:

messages (List[Dict[str, Any]]): Dicts with a role key and usually a content key. Any other keys, such as name, tool_calls, or tool_call_id, are kept under the message’s metadata, so a tool exchange survives the round trip.

Returns: The result of each add(), in order. Raises ValueError when an item is not a dict or has no role.

return_history_as_string()

Return the conversation history as a formatted string.

def return_history_as_string(self) -> str:

Returns: One role: content entry per message, separated by blank lines. Messages with a timestamp are prefixed with [timestamp]. With dynamic_context_window=True, the string is trimmed from the front to fit context_length tokens.

compact()

Collapse the interaction history into a single summary message, preserving the agent’s static context (system_prompt → rules → custom_rules_prompt) ahead of it. If memory_md_path is configured, the on-disk MEMORY.md is archived to <agent_folder>/archive/history_<timestamp>.md and then wiped/re-seeded so the log doesn’t keep growing across compressions.

def compact(
    self,
    summary: str,
    summary_role: str = "System",
) -> None

Parameters:

summary (str): The compressed summary content that replaces the raw history.
summary_role (str): Role attached to the summary message. Defaults to "System".

conv.compact(
    summary="User asked about X. Assistant explained X.",
    summary_role="System",
)

export()

Save the conversation to save_filepath in the export_method format.

def export(self, force: bool = True)

Parameters:

force (bool): If True, saves regardless of autosave setting

The file holds the bare list of message dicts. The parent directory is created if needed.

load()

Load conversation history from a file, choosing the parser by extension.

def load(self, filename: str)

Parameters:

filename (str): Path to a .json, .yaml, or .yml file

Replaces the current history. Accepts the bare message list that export() writes, or a {"metadata": ..., "conversation_history": ...} wrapper. A missing file logs a warning and changes nothing. Any other extension raises ValueError.

search()

Search for messages containing a keyword.

def search(self, keyword: str) -> list

Parameters:

keyword (str): The keyword to search for

Returns: List of messages containing the keyword

truncate_memory_with_tokenizer()

Truncate the stored history to context_length tokens.

def truncate_memory_with_tokenizer(self)

Messages are kept from the start until the budget runs out. The message that crosses the limit is cut to fit, at a sentence boundary when possible, and every later message is dropped.

export_and_count_categories()

Export all messages with category ‘input’ and ‘output’ and count their tokens.

def export_and_count_categories(self) -> Dict[str, int]

Returns: Dictionary with input_tokens, output_tokens, and total_tokens

Other Methods

Method	Description
`query(index)`	Return the message dict at `index`, or `None` if out of range
`delete(index)`	Remove the message at `index`; raises `IndexError` if out of range
`update(index, role, content)`	Replace the role/content of the message at `index`; logs a warning if out of range
`add_multiple(roles, contents)` / `add_multiple_messages(roles, contents)`	Add several messages in order through `add()`; raises `ValueError` if the lists differ in length
`batch_add(messages)`	Append message dicts as-is: no timestamps, IDs, token counts, `MEMORY.md` writes, or autosave
`add_tool_output_to_agent(role, tool_output)`	Add a tool result through `add()`
`get_str()`	Alias for `return_history_as_string()`
`dynamic_auto_chunking()`	The rendered history trimmed from the front to fit `context_length` tokens
`get_cache_stats()`	Returns `{hits, misses, cached_tokens, hit_rate}` for the history-string cache (only meaningful when `cache_enabled=True`)
`get_last_message_as_string()` / `get_final_message()`	The last message as a `"role: content"` string
`get_final_message_content()`	The last message’s content
`return_messages_as_list()` / `return_messages_as_dictionary()`	The history as `{"role", "content"}` dicts
`return_messages_as_strings()`	The history rendered as `"role: content"` strings
`return_json()`	The `{"role", "content"}` dicts as an indented JSON string
`return_all_except_first()`	Messages after the system prompt (when the first message has role `"System"`) and the first input
`return_all_except_first_string()`	The contents of those same messages, joined by newlines
`return_list_final()` / `return_dict_final()`	The last message’s content as `[content]` / as the tuple `(content, content)`
`to_dict()` / `to_list()`	The history list itself (`to_dict()` does not return a dict)
`to_json()` / `to_yaml()`	The history list as a JSON / YAML string
`save_as_json(force=True)` / `save_as_yaml(force=True)`	Write the history to `save_filepath`; with `force=False` and `autosave` off, only log a warning
`load_from_json(filename)` / `load_from_yaml(filename)`	Format-specific forms of `load()`
`export_conversation(filename)`	For a `.json` name, calls `save_as_json()`, which writes to `save_filepath`, not `filename`; otherwise writes `role: content` lines to `filename`
`import_conversation(filename)`	Alias for `load_from_json(filename)`
`search_keyword_in_conversation(keyword)`	Like `search()`, for string contents only
`count_messages_by_role()`	Dict of message counts keyed by role. `system`, `user`, `assistant`, and `function` are always present; roles are case-sensitive
`get_visible_messages(agent, turn)`	Messages whose `turn` is below `turn` and whose `visible_to` is `"all"` or includes the agent’s name; requires those keys on every message
`clear()`	Empty the conversation history
`Conversation.load_conversation(name, conversations_dir=None, load_filepath=None)`	Classmethod. With `load_filepath`, loads that file. Otherwise looks for `<name>.json`, `.yaml`, `.yml`, then `<name>` in the directory, and returns a conversation built with `name` if none is found
`Conversation.list_conversations(conversations_dir=None)`	Classmethod: `{id, name, created_at, filepath}` for each JSON file with a `metadata` wrapper, newest first
`Conversation.list_cached_conversations(conversations_dir=None)`	Classmethod: sorted file names (without extension) of every `.json`, `.yaml`, and `.yml` file in the directory

list_conversations() only lists files that carry a {"metadata": {"id", "name", "created_at"}} wrapper. export() writes a bare message list, so conversations saved by this class are skipped. Use list_cached_conversations() to find them.

Output formats

Agents and swarms turn a Conversation into their return value with history_output_formatter. Each output_type maps to one method:

`output_type`	Method	Result
`"list"`	`return_messages_as_list()`	List of `{"role", "content"}` dicts
`"dict"`, `"dictionary"`	`to_dict()`	The full message list, with every stored key
`"string"`, `"str"`, `"all"`	`get_str()`	The rendered history
`"final"`, `"last"`	`get_final_message_content()`	The last message’s content
`"json"`	`to_json()`	JSON string
`"yaml"`	`to_dict()`, then `yaml.safe_dump`	YAML string
`"dict-all-except-first"`	`return_all_except_first()`	Messages after the system prompt and first input
`"str-all-except-first"`	`return_all_except_first_string()`	Their contents as one string
`"list-final"`	`return_list_final()`	`[content]`
`"dict-final"`	`return_dict_final()`	`(content, content)`

Any other value raises ValueError. The "xml" output type has been removed.

Usage Examples

Basic Usage

from swarms import Conversation

conversation = Conversation(
    name="my-conversation",
    system_prompt="You are a helpful assistant.",
    time_enabled=True,
    autosave=True,
    token_count=True,
    context_length=8192,
)

conversation.add("user", "Hello, how are you?")
conversation.add("assistant", "I am doing well, thanks.")
conversation.add("user", "What is the weather in Tokyo?")

print(conversation.return_history_as_string())

Because it is named and autosaved, this conversation is written to ./conversations/conversation_my-conversation.json. Running the script again resumes that history instead of starting over.

Seed from chat messages

from swarms import Conversation

conversation = Conversation(
    system_prompt="You are a helpful assistant.",
    messages=[
        {"role": "user", "content": "What is 2 + 2?"},
        {"role": "assistant", "content": "4."},
    ],
)

Export and Load

from swarms import Conversation

conversation = Conversation(name="my-conversation", export_method="json")
conversation.add("user", "Remember that my project is called Helios.")
conversation.export()
print(conversation.save_filepath)

# Same name: resumes from ./conversations/conversation_my-conversation.json
restored = Conversation(name="my-conversation")

# Any file on disk: load() replaces the current history
other = Conversation()
other.load(conversation.save_filepath)

Token Management

from swarms import Conversation

conversation = Conversation(
    token_count=True,
    context_length=4096,
    dynamic_context_window=True,
)

conversation.add("user", "My input", category="input")
conversation.add("assistant", "My response", category="output")

tokens = conversation.export_and_count_categories()
print(f"Input tokens: {tokens['input_tokens']}")
print(f"Output tokens: {tokens['output_tokens']}")
print(f"Total tokens: {tokens['total_tokens']}")

Search and Query

results = conversation.search("weather")

last_message = conversation.get_last_message_as_string()

message = conversation.query(0)

Features

Automatic Saving: Enable autosave to persist the history after every message
Resume by Name: A named conversation picks up its saved history on construction
Token Management: Count tokens per message, trim the rendered history to the context length, or truncate the stored history on demand
Multiple Export Formats: Save as JSON or YAML
Message Search: Search through conversation history by keyword
Categorization: Tag messages with categories for organized tracking
Time Tracking: Optionally track timestamps for all messages

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

Overview

Installation

Parameters

Construction and resume

Methods

add()

add_messages()

return_history_as_string()

compact()

export()

load()

search()

truncate_memory_with_tokenizer()

export_and_count_categories()

Other Methods

Output formats

Usage Examples

Basic Usage

Seed from chat messages

Export and Load

Token Management

Search and Query

Features

​Overview

​Installation

​Parameters

​Construction and resume

​Methods

​add()

​add_messages()

​return_history_as_string()

​compact()

​export()

​load()

​search()

​truncate_memory_with_tokenizer()

​export_and_count_categories()

​Other Methods

​Output formats

​Usage Examples

​Basic Usage

​Seed from chat messages

​Export and Load

​Token Management

​Search and Query

​Features

Overview

Installation

Parameters

Construction and resume

Methods

add()

add_messages()

return_history_as_string()

compact()

export()

load()

search()

truncate_memory_with_tokenizer()

export_and_count_categories()

Other Methods

Output formats

Usage Examples

Basic Usage

Seed from chat messages

Export and Load

Token Management

Search and Query

Features