Architecture Decision Records (ADRs)

Relevant source files

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

• models.py
• session_manager.py
• README.md
• tests/test_models.py
• tests/test_integration.py
• CLAUDE.md

Architecture Decision Records (ADRs) document significant technical choices and their rationale within the sequential-thinking-mcp-v2 project. These records capture the context, options, and consequences of decisions to provide a durable history for both human developers and AI agents.

ADRs constitute part of the "Canonical Human Truth" layer within the system's memory model. They reside within the UnifiedSession structure and persist in the project's memory bank as human-readable markdown files.

Sources: README.md:52-59, CLAUDE.md:31-36

Data Architecture

The system represents an ADR using the ArchitectureDecision dataclass. Each record uniquely identifies a specific architectural choice linked to a session.

The ArchitectureDecision Model

The ArchitectureDecision class stores the core components of a technical decision. The model includes fields for context, options, and dependencies.

Field	Type	Description
id	str	Unique UUID for the record.
session_id	str	Reference to the parent session.
decision_title	str	Descriptive name of the decision.
context	str	The problem or situation necessitating a choice.
options_considered	str	List of alternatives evaluated.
chosen_option	str	The selected path or technology.
rationale	str	Explanation of why the option was chosen.
consequences	str	The trade-offs and results of the decision.
package_dependencies	List[str]	Libraries or packages required by this choice.

Sources: models.py:114-125, tests/test_models.py:164-183

Entity Relationships

ADRs are aggregate members of a UnifiedSession. A single session can track multiple decisions as the project architecture evolves.

Decision Management Workflow

The UnifiedSessionManager handles the lifecycle of an ADR. It manages the creation, validation, and storage of records during an active session.

Recording Decisions

You record a decision by invoking the record_decision method on the UnifiedSessionManager. This method instantiates the ArchitectureDecision model and appends it to the active session's collection.

Functional Implementation

The following snippet demonstrates how the UnifiedSessionManager processes a new decision:

def record_decision(
    self,
    decision_title: str,
    context: str,
    options_considered: str,
    chosen_option: str,
    rationale: str,
    consequences: str,
    package_dependencies: str = "",
) -> str:
    if not self.current_session:
        raise ValueError("No active session")
    decision = ArchitectureDecision(
        session_id=self.current_session.id,
        decision_title=decision_title,
        context=context,
        options_considered=options_considered,
        chosen_option=chosen_option,
        rationale=rationale,
        consequences=consequences,
        package_dependencies=(
            package_dependencies.split(",") if package_dependencies else []
        ),
    )
    self.current_session.architecture_decisions.append(decision)
    self._save_session_to_file(self.current_session)
    return decision.id

Sources: session_manager.py:243-261

Persistence and Storage

ADRs persist within the session markdown files located in memory-bank/sessions/. The system uses a specific markdown schema to ensure records are both human-readable and machine-parseable.

Markdown Serialization

When saving a session, the UnifiedSessionManager generates a "Architecture Decisions" section. Each decision follows a standard header and metadata block.

1. The system iterates through the architecture_decisions list.
2. It formats the title as an H3 header.
3. It writes key-value pairs for context, options, rationale, and consequences.
4. It lists package dependencies as comma-separated values.

Sources: session_manager.py:105-116

Data Recovery

The UnifiedSessionManager reconstructs ADR objects from markdown files using regex-based parsing. The _parse_session_markdown method extracts decision blocks to re-hydrate the UnifiedSession state.

Integration in Workflows

ADRs serve as critical checkpoints in complex coding tasks. Integration tests verify that decisions are properly recorded and persisted alongside thoughts and memories.

• Workflow Verification: Integration tests confirm that recording a decision increases the count in session analysis.
• Exporting: ADRs are included when exporting sessions to external markdown files for project documentation.
• Package Exploration: Decisions often capture the outcome of package exploration tasks, linking library choices to specific rationales.

Sources: tests/test_integration.py:95-116, tests/test_integration.py:255-265

Summary

Architecture Decision Records provide a structured method for documenting the "why" behind technical implementations. By integrating ADRs directly into the session management and persistence layers, the project ensures that architectural history remains accessible, searchable, and durable across different reasoning sessions.