fix(sequentialthinking): prevent unbounded memory growth in thought history

[Limitless2023]

Summary

Fixes #2912 — The SequentialThinkingServer stores all thoughts in memory arrays (thoughtHistory and branches) that grow without bound across the server process lifetime. In long-running sessions (6-8+ hours of frequent use), this can lead to 10GB+ RAM consumption.

Root Cause

thoughtHistory: ThoughtData[] and branches: Record<string, ThoughtData[]> are append-only — thoughts are pushed but never removed or trimmed. Since the server is a long-lived stdio process, memory accumulates indefinitely.

Changes

1. Configurable max history with auto-trimming (lib.ts)

• Added SEQUENTIAL_THINKING_MAX_HISTORY environment variable (default: 1000)
• When thought count exceeds the limit, oldest thoughts are trimmed via splice()
• This bounds memory usage to a predictable maximum regardless of session length

2. Explicit clearHistory() method (lib.ts)

• New public method that resets both thoughtHistory and branches to empty
• Returns metadata about what was cleared (previous thought/branch counts)

3. New sequentialthinking_clear tool (index.ts)

• Registers a tool that clients can invoke to explicitly free memory
• Useful between distinct thinking sessions within the same server process

4. Documentation (README.md)

• Added environment variables table documenting both DISABLE_THOUGHT_LOGGING and the new SEQUENTIAL_THINKING_MAX_HISTORY

5. Tests (lib.test.ts)

• clearHistory — verifies thoughts and branches are fully reset
• Memory management — verifies history trimming at default limit
• Environment variable — verifies custom SEQUENTIAL_THINKING_MAX_HISTORY is respected

Testing

All 17 tests pass:

✓ __tests__/lib.test.ts (17 tests) 4ms
Test Files  1 passed (1)
     Tests  17 passed (17)

Design Decisions

• Default limit of 1000: Conservative — retains substantial context while preventing runaway growth. A single thought is typically a few hundred bytes of text, so 1000 thoughts ≈ a few hundred KB.
• Trim oldest first: Most recent thoughts are the most relevant for ongoing reasoning. Oldest thoughts are the least likely to be referenced.
• Separate clear tool: Allows explicit memory management without losing the auto-trim safety net.

[lucamorettibuilds]

Excellent fix for a classic long-running server problem! The approach here is solid:

What I like:

1. Pragmatic defaults - 1000 thoughts is a great balance between context retention and memory safety
2. Layered defense - Auto-trim + explicit clear tool gives users both safety and control
3. Proper testing - Memory management tests are critical for this kind of fix
4. Good documentation - Environment variable table makes configuration discoverable

One consideration:

The splice() approach for trimming is O(n) since it shifts remaining elements. For the default 1000-thought limit this is negligible, but if operators set SEQUENTIAL_THINKING_MAX_HISTORY to very large values (e.g., 100k+), trimming could become a performance issue.

Alternatives (only if this becomes a problem in practice):

• Circular buffer with index tracking (O(1) operations)
• Sliding window that drops oldest batch when limit is exceeded

But honestly, for the stated use case (preventing 10GB+ accumulation in 6-8 hour sessions), the current implementation is perfect. Don't optimize prematurely!

Minor suggestion:

Consider logging a warning when history is trimmed for the first time in a session:

if (!this.hasWarnedAboutTrimming) {
  console.warn(`Thought history trimmed (limit: ${maxHistory}). Set SEQUENTIAL_THINKING_MAX_HISTORY to increase.`);
  this.hasWarnedAboutTrimming = true;
}

This would help operators detect if they need to tune the limit without being noisy on every trim.

Great work on documenting the root cause and design decisions in the PR description!