Token Management Policy

Token Management Policy governs the consumption and optimization of context window resources within the Sequential Thinking MCP. It treats token limits as a first-class design constraint to ensure the system remains performant during long-running coding tasks and large-codebase analysis.

The policy establishes clear boundaries between ephemeral reasoning and durable memory. It optimizes token usage by prioritizing semantic retrieval and session compaction over the maintenance of raw transcripts or exhaustive logs.
Sources: README.md:77-78, CLAUDE.md:44-46

Context Boundaries and Thresholds

The system operates with specific engineering defaults for context management. These limits prevent the active context from exceeding model capabilities and degrading performance.

Sources: README.md:79-81, CLAUDE.md:44-46

Context Flow Control

The following diagram illustrates the lifecycle of context management as it approaches policy thresholds.

The diagram shows the transition from active thought generation to compaction once the 45K token trigger is met.
Sources: README.md:79-88, CLAUDE.md:44-46

Reasoning Lifecycle Management

The Token Management Policy dictates that the system must distinguish between disposable and durable data to save tokens.

Reasoning Tiers

1. Scratch Reasoning: Local, ephemeral, and bounded. It is disposable once a subtask completes.
2. Checkpoint Summaries: Compact artifacts used for state recovery.
3. Promoted Conclusions: Durable machine memory. These are the only artifacts that persist long-term.
4. Canonical Truth: Human-maintained markdown documentation (ADRs, design docs).

Raw chain-of-thought (CoT) data does not become long-term memory. The system discards raw transcripts in favor of summaries and handoff bundles.
Sources: CLAUDE.md:34-42, README.md:83-88

Promotion Gating

Promotion of ephemeral thoughts to durable memory requires validation. This gating prevents "token bloat" by ensuring only high-value information consumes permanent storage and future context.

The diagram outlines the logic gates (Evidence, Confidence, Reuse) required to transition an artifact to durable storage.
Sources: CLAUDE.md:34-42, README.md:65-75

Implementation Strategies

The UnifiedSessionManager and associated tools implement the following strategies to adhere to the Token Management Policy:

Retrieval and Storage Efficiency

• On-Demand Retrieval: The system does not preload the entire codebase. It retrieves context specific to the active task.
• Semantic Recall: The system uses Zvec for promoted artifacts and qmd for canonical docs to ensure precise, token-efficient retrieval.
• Metadata Tagging: Data structures include fields like confidence, importance, and tags to allow the system to rank and filter content during retrieval.

Sources: CLAUDE.md:20-32, session_manager.py:285-350, models.py:59-80

Session Compaction

The system tracks session volume via the analyze_session method, which provides the necessary metrics to determine if compaction is required.

# session_manager.py:440-452
def analyze_session(self) -> Dict[str, Any]:
    if not self.current_session:
        return {"error": "No active session"}
    return {
        "session_id": self.current_session.id,
        "total_thoughts": len(self.current_session.thoughts),
        "total_memories": len(self.current_session.memories),
        "total_branches": len(self.current_session.branches),
        "created_at": self.current_session.created_at.isoformat(),
    }

Sources: session_manager.py:440-452, tests/test_integration.py:108-115

Conclusion

The Token Management Policy ensures the sequential-thinking-mcp-v2 project maintains a high signal-to-noise ratio within the LLM context. By enforcing a 64K ceiling and a 45K compaction trigger, and by strictly separating ephemeral reasoning from durable promoted conclusions, the system preserves reasoning quality while minimizing token costs.
Sources: README.md:16-25, CLAUDE.md:34-46