Conversation and Context Management

Relevant source files

The following files were used as context for generating this wiki page:

• utils/conversation_memory.py
• tests/test_conversation_memory.py
• server.py
• systemprompts/chat_prompt.py
• systemprompts/planner_prompt.py
• systemprompts/generate_code_prompt.py
• README.md

The Conversation and Context Management system is a core feature of the Zen MCP Server, designed to enable stateful, multi-turn interactions with and between AI models. While the underlying Model Context Protocol (MCP) can be stateless, this system provides a layer of persistence that allows for "Conversation Continuity." It achieves this by creating and managing conversation threads, storing the history of interactions, and rebuilding the context for subsequent tool executions. This capability is fundamental to complex workflows like multi-model debates, iterative debugging, and phased project planning.

The central mechanism for this continuity is the continuation_id, a unique identifier for each conversation thread. When a tool response includes a continuation_id, clients can use it in subsequent requests to maintain the full conversational context, allowing models to "remember" previous parts of the discussion. This transforms simple, one-shot tool calls into a collaborative session.

Sources: README.md, utils/conversation_memory.py, systemprompts/planner_prompt.py:84-88

Core Architecture

The system is implemented primarily within utils/conversation_memory.py and relies on an in-memory dictionary to store active conversation threads.

Sources: utils/conversation_memory.py:28

Components

• Thread Storage: A global, in-memory dictionary named _threads holds all active ThreadContext objects, keyed by their thread_id.
• ThreadContext: A data class that represents a single conversation thread. It stores metadata like creation time and the full sequence of conversational turns.
• ConversationTurn: A data class representing a single exchange (e.g., a user prompt or an assistant response) within a thread.
• Management Functions: A set of functions (create_thread, get_thread, add_turn) provide the interface for creating, retrieving, and updating conversation threads.

Data Model

The relationship between ThreadContext and ConversationTurn is a one-to-many composition. Each ThreadContext contains a list of ConversationTurn objects.

Sources: utils/conversation_memory.py:12-26

Data Structure Details

ThreadContext

The ThreadContext class encapsulates the entire state of a conversation.

Field	Type	Description
thread_id	str	A unique UUID for the conversation thread.
tool_name	str	The name of the tool that initiated the thread.
created_at	datetime	Timestamp of when the thread was created.
last_activity	datetime	Timestamp of the last turn added to the thread.
turns	list[ConversationTurn]	A list of all conversational turns in chronological order.
initial_context	dict	The initial context or prompt that started the conversation.

Sources: utils/conversation_memory.py:12-19

ConversationTurn

The ConversationTurn class represents a single message or action within the conversation.

Field	Type	Description
role	str	The role of the speaker (e.g., "user", "assistant", "system").
content	str	The textual content of the turn.
timestamp	datetime	Timestamp of when the turn occurred.
files	list[str]	A list of file paths associated with this turn.
model_name	Optional[str]	The AI model used for this turn, if applicable.
tool_name	Optional[str]	The tool used for this turn, if applicable.

Sources: utils/conversation_memory.py:20-26

Conversation Lifecycle

A conversation thread follows a distinct lifecycle from creation to potential expiration and cleanup.

Sources: utils/conversation_memory.py:31-75, tests/test_conversation_memory.py:53-63

1. Thread Creation

A new conversation thread is created by the create_thread function when a tool execution requires state to be maintained.

• It generates a unique thread_id using uuid.uuid4().
• It initializes a ThreadContext object with the current timestamp and initial context.
• The new context is stored in the global _threads dictionary.
• The thread_id is returned to the caller, which then includes it in the tool's response as a continuation_id.

Sources: utils/conversation_memory.py:31-41, systemprompts/planner_prompt.py:87

2. Thread Continuation

When a client sends a request containing a continuation_id, the server uses get_thread to retrieve the corresponding ThreadContext.

• If the thread exists and has not expired, its last_activity is updated.
• The add_turn function is then called to append the new user request and subsequent assistant response to the turns list.
• The maximum number of turns is capped by MAX_CONVERSATION_TURNS. If the limit is exceeded, the oldest turn is removed.

Sources: utils/conversation_memory.py:43-63, tests/test_conversation_memory.py:39-51

3. Thread Expiration and Cleanup

To prevent memory leaks from abandoned conversations, a cleanup mechanism is in place.

• The cleanup_expired_threads function periodically iterates through all stored threads.
• It checks if a thread's last_activity is older than the configured CONVERSATION_TIMEOUT_HOURS.
• Expired threads are removed from the _threads dictionary.
• This cleanup is scheduled to run in the background by the main server application.

Sources: utils/conversation_memory.py:65-75, server.py:228-232

Context Building for AI Models

The primary purpose of storing conversation history is to provide context to AI models in subsequent turns. The build_conversation_history function is responsible for this.

The function transforms the list of ConversationTurn objects into a list of dictionaries, each with a role and content, which is the standard format expected by most chat-based AI model APIs. This history allows the AI to understand the full dialogue that has occurred so far. The importance of this is highlighted in prompts for tools like generate_code, which explicitly state that the implementation builds upon the "ongoing conversation context" and that the agent has "full conversation history".

Sources: utils/conversation_memory.py:77-90, systemprompts/generate_code_prompt.py:127-132, systemprompts/chat_prompt.py

Summary

The Conversation and Context Management system is the backbone of Zen MCP Server's collaborative capabilities. By creating an abstraction layer for state management on top of a stateless protocol, it enables sophisticated, multi-step workflows that involve multiple tools and AI models. The use of a continuation_id provides a simple yet powerful mechanism for clients to maintain dialogue, making the server a true "thought-partner" for developers rather than just a simple tool executor. The system's design, including its in-memory storage and automatic cleanup, balances functionality with resource management.

Sources: utils/conversation_memory.py, README.md