Dataclasses and Domain Models

Relevant source files

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

• models.py
• session_manager.py
• tests/test_models.py
• README.md
• CLAUDE.md
• memory-bank/memories/67944906-43bc-4c85-9424-f2261850bc97.md

Dataclasses in models.py define the core domain entities for the Sequential Thinking MCP server. These models structure reasoning sessions, persist thoughts and memories, and track architectural decisions. The UnifiedSession class acts as the aggregate root, centralizing all related data entities within a single lifecycle.

Sources: models.py , CLAUDE.md:Core Files

Core System Entities

The domain model consists of seven primary types that represent different aspects of the reasoning and persistence process. All entities, except for the SessionType enum, utilize Python dataclasses and generate unique UUIDs for identification upon initialization.

Entity Relationship Overview

The following diagram illustrates the relationships between the session aggregate root and its child entities.

The UnifiedSession owns all lists of child objects. A Branch references a specific Thought ID to indicate where a reasoning path diverged, while individual Thoughts optionally link back to a Branch.

Sources: models.py:16-118, memory-bank/sessions/7a56026e-0a71-42e5-a577-ae854a3ae896.md:Thought 2

Data Model Specifications

UnifiedSession

UnifiedSession tracks the high-level context of a reasoning task. It serves as the primary container for all session data and is persisted as a Markdown file in the memory-bank/sessions/ directory.

Field	Type	Description
id	str	Unique UUID for the session.
problem	str	The core problem statement or task.
success_criteria	str	Definition of what constitutes a successful outcome.
session_type	SessionType	Enum value: GENERAL or CODING.
codebase_context	str	Technical details about the environment or repository.
package_exploration_required	bool	Flag to trigger automatic package discovery.

Sources: models.py:16-30, session_manager.py:53-73

Reasoning: Thought and Branch

These models facilitate structured, non-linear reasoning. A Thought represents a single logical step, while a Branch allows for parallel exploration of different solutions.

• Thought: Captures content, confidence levels, and package suggestions. It supports dependencies on prior thoughts.
• Branch: Groups thoughts under a specific purpose and name, branching off from a specific from_thought_id.

Persistence: Memory and ArchitectureDecision

These entities provide durable long-term storage for conclusions and technical choices.

• Memory: Stores reusable knowledge artifacts. It includes a code_snippet field and tags for semantic retrieval. Memories are persisted both within session files and as standalone files in memory-bank/memories/.
• ArchitectureDecision: Implements a structured format for ADRs (Architecture Decision Records), capturing context, options, and consequences.

Sources: models.py:40-66, models.py:103-113, session_manager.py:202-225

Validation Logic

The domain models implement self-validation via the __post_init__ method to maintain data integrity. The UnifiedSessionManager relies on these validations to ensure consistent state before persistence.

# From models.py:79-90
def __post_init__(self):
    """Validate thought data after initialization."""
    if not self.content or not self.content.strip():
        raise ValidationError("Thought content cannot be empty")

    if self.confidence < 0 or self.confidence > 1:
        raise ValidationError("Thought confidence must be between 0 and 1")

    # Ensure dependencies is always a list
    if isinstance(self.dependencies, str):
        if self.dependencies.strip():
            self.dependencies = [dep.strip() for dep in self.dependencies.split(",") if dep.strip()]
        else:
            self.dependencies = []

Constraint Table

Model	Field	Constraint	Action
Memory	content	Non-empty string	Raises ValidationError
Memory	confidence	Range [0.0, 1.0]	Raises ValidationError
Thought	content	Non-empty string	Raises ValidationError
Thought	confidence	Range [0.0, 1.0]	Raises ValidationError
Memory	tags	Auto-conversion	Converts CSV string to List[str]

Sources: models.py:51-66, models.py:79-90, tests/test_models.py:228-250

Package Discovery Model

The PackageInfo dataclass stores results from the explore_packages tool. It records technical metadata about libraries found in the environment that are relevant to the session's problem statement.

• Relevance Scoring: A relevance_score (float) indicates how well the package matches the task description.
• API Visibility: The api_signatures list stores common function or class signatures discovered during exploration.

Sources: models.py:116-126, session_manager.py:284-307

Summary of Data Flow

The UnifiedSessionManager acts as the orchestrator for these models. When a tool is invoked, the manager instantiates the relevant domain model, triggers the internal validation, and subsequently serializes the object into the Markdown-based storage layout.