Skip to content

Commit 93f89b1

Browse files
cliffhallclaude
andcommitted
fix(sequentialthinking): cap the thought history each connection keeps
A server instance lives as long as its client's connection and appended every thought and branch entry for that whole time, so a long-lived connection grew memory without bound (#2912). State was already per connection on both eras; nothing was shared across connections. Retain at most MAX_THOUGHT_HISTORY thoughts (default 1000), dropping the oldest. The dropped thought leaves its branch too, and a branch left empty is no longer listed, so the branches never hold more than the history. The result shape is unchanged: thoughtHistoryLength and branches now describe the retained thoughts. An invalid value is reported on stderr and replaced by the default. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 446be48 commit 93f89b1

4 files changed

Lines changed: 214 additions & 1 deletion

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@modelcontextprotocol/server-sequential-thinking": minor
3+
---
4+
5+
Bound the thought history each connection keeps: at most `MAX_THOUGHT_HISTORY` thoughts (default 1000) are retained, the oldest dropped first and from its branch too, so a long-lived connection no longer grows memory without bound.

‎src/sequentialthinking/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,8 @@ On Windows, use `cmd /c` to launch `npx`:
134134

135135
To disable logging of thought information set env var: `DISABLE_THOUGHT_LOGGING` to `true`.
136136

137+
To bound memory use, the server retains at most `MAX_THOUGHT_HISTORY` thoughts per connection (a positive integer; default `1000`). Past the cap the oldest thought is dropped, from its branch too, so `thoughtHistoryLength` in the result stops at the cap and a branch whose thoughts have all been dropped is no longer listed in `branches`.
138+
137139
### Usage with VS Code
138140

139141
For quick installation, click one of the installation buttons below...

‎src/sequentialthinking/__tests__/thinking.test.ts‎

Lines changed: 158 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@
44
// in-process client and reads only the result's text and structuredContent.
55
// Includes the #4813 regression tests: a branchId that names an
66
// Object.prototype key is an ordinary branch, and a failed call leaves the
7-
// state unchanged.
7+
// state unchanged; and the #2912 tests: the history is capped at
8+
// MAX_THOUGHT_HISTORY, evicting the oldest thought from its branch too.
89

910
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
1011
import {
@@ -14,6 +15,30 @@ import {
1415
thought,
1516
type Connected,
1617
} from "./helpers.js";
18+
import { DEFAULT_MAX_THOUGHT_HISTORY } from "../lib.js";
19+
20+
/**
21+
* Connect to a server built under MAX_THOUGHT_HISTORY=`value` (`undefined` =
22+
* unset). The cap is read once, when the server is built, so the variable is
23+
* restored as soon as the connection is up.
24+
*/
25+
async function connectCapped(value: string | undefined): Promise<Connected> {
26+
const previous = process.env.MAX_THOUGHT_HISTORY;
27+
if (value === undefined) {
28+
delete process.env.MAX_THOUGHT_HISTORY;
29+
} else {
30+
process.env.MAX_THOUGHT_HISTORY = value;
31+
}
32+
try {
33+
return await connect();
34+
} finally {
35+
if (previous === undefined) {
36+
delete process.env.MAX_THOUGHT_HISTORY;
37+
} else {
38+
process.env.MAX_THOUGHT_HISTORY = previous;
39+
}
40+
}
41+
}
1742

1843
describe("sequentialthinking thought processing", () => {
1944
let conn: Connected;
@@ -392,4 +417,136 @@ describe("sequentialthinking thought processing", () => {
392417
).toEqual([]);
393418
});
394419
});
420+
421+
// #2912: a server lives as long as its connection, so the history it keeps
422+
// is capped, oldest thought first, and the branches shrink with it.
423+
describe("#2912: bounded thought history", () => {
424+
let capped: Connected | undefined;
425+
426+
afterEach(async () => {
427+
await capped?.close();
428+
capped = undefined;
429+
vi.restoreAllMocks();
430+
});
431+
432+
it(`retains at most ${DEFAULT_MAX_THOUGHT_HISTORY} thoughts by default`, async () => {
433+
capped = await connectCapped(undefined);
434+
let length = 0;
435+
for (let n = 1; n <= DEFAULT_MAX_THOUGHT_HISTORY + 5; n++) {
436+
length = parseOk(
437+
await capped.think(thought({ thoughtNumber: n })),
438+
).thoughtHistoryLength;
439+
expect(length).toBe(Math.min(n, DEFAULT_MAX_THOUGHT_HISTORY));
440+
}
441+
expect(length).toBe(DEFAULT_MAX_THOUGHT_HISTORY);
442+
});
443+
444+
it("stops thoughtHistoryLength at MAX_THOUGHT_HISTORY", async () => {
445+
capped = await connectCapped("3");
446+
const lengths: number[] = [];
447+
for (let n = 1; n <= 6; n++) {
448+
lengths.push(
449+
parseOk(await capped.think(thought({ thoughtNumber: n })))
450+
.thoughtHistoryLength,
451+
);
452+
}
453+
expect(lengths).toEqual([1, 2, 3, 3, 3, 3]);
454+
});
455+
456+
it("drops a branch once all of its thoughts are evicted", async () => {
457+
capped = await connectCapped("2");
458+
await capped.think(thought({ branchFromThought: 1, branchId: "alt" }));
459+
expect(
460+
parseOk(await capped.think(thought({ thoughtNumber: 2 }))).branches,
461+
).toEqual(["alt"]);
462+
expect(
463+
parseOk(await capped.think(thought({ thoughtNumber: 3 }))),
464+
).toMatchObject({ branches: [], thoughtHistoryLength: 2 });
465+
});
466+
467+
it("keeps a branch while any of its thoughts is retained", async () => {
468+
capped = await connectCapped("2");
469+
await capped.think(thought({ branchFromThought: 1, branchId: "alt" }));
470+
await capped.think(
471+
thought({ thoughtNumber: 2, branchFromThought: 1, branchId: "alt" }),
472+
);
473+
// Evicts the first "alt" thought; the second is still retained.
474+
expect(
475+
parseOk(await capped.think(thought({ thoughtNumber: 3 }))),
476+
).toMatchObject({ branches: ["alt"], thoughtHistoryLength: 2 });
477+
// Evicts the second; nothing on "alt" is left.
478+
expect(
479+
parseOk(await capped.think(thought({ thoughtNumber: 4 }))).branches,
480+
).toEqual([]);
481+
});
482+
483+
it("lists a branch recreated after eviction as newly seen", async () => {
484+
capped = await connectCapped("3");
485+
await capped.think(thought({ branchFromThought: 1, branchId: "a" }));
486+
await capped.think(
487+
thought({ thoughtNumber: 2, branchFromThought: 1, branchId: "b" }),
488+
);
489+
await capped.think(
490+
thought({ thoughtNumber: 3, branchFromThought: 1, branchId: "b" }),
491+
);
492+
// Evicts the only "a" thought.
493+
expect(
494+
parseOk(await capped.think(thought({ thoughtNumber: 4 }))).branches,
495+
).toEqual(["b"]);
496+
// "a" is recorded again, after "b"; the first "b" thought is evicted.
497+
expect(
498+
parseOk(
499+
await capped.think(
500+
thought({ thoughtNumber: 5, branchFromThought: 1, branchId: "a" }),
501+
),
502+
).branches,
503+
).toEqual(["b", "a"]);
504+
});
505+
506+
it("evicts a branch whose id names an Object.prototype key", async () => {
507+
capped = await connectCapped("1");
508+
await capped.think(
509+
thought({ branchFromThought: 1, branchId: "__proto__" }),
510+
);
511+
expect(
512+
parseOk(await capped.think(thought({ thoughtNumber: 2 }))),
513+
).toMatchObject({ branches: [], thoughtHistoryLength: 1 });
514+
});
515+
516+
it("accepts a value padded with whitespace", async () => {
517+
capped = await connectCapped(" 1 ");
518+
await capped.think(thought());
519+
expect(
520+
parseOk(await capped.think(thought({ thoughtNumber: 2 })))
521+
.thoughtHistoryLength,
522+
).toBe(1);
523+
});
524+
525+
it("uses the default for an empty value, without a warning", async () => {
526+
const errors = vi.spyOn(console, "error").mockImplementation(() => {});
527+
capped = await connectCapped("");
528+
await capped.think(thought());
529+
expect(
530+
parseOk(await capped.think(thought({ thoughtNumber: 2 })))
531+
.thoughtHistoryLength,
532+
).toBe(2);
533+
expect(errors).not.toHaveBeenCalled();
534+
});
535+
536+
it.each(["0", "-1", "1.5", "abc", "1e3", "99999999999999999999"])(
537+
"reports %j on stderr and keeps the default cap",
538+
async (value) => {
539+
const errors = vi.spyOn(console, "error").mockImplementation(() => {});
540+
capped = await connectCapped(value);
541+
expect(errors).toHaveBeenCalledWith(
542+
`MAX_THOUGHT_HISTORY must be a positive integer, got "${value}"; using ${DEFAULT_MAX_THOUGHT_HISTORY}`,
543+
);
544+
await capped.think(thought());
545+
expect(
546+
parseOk(await capped.think(thought({ thoughtNumber: 2 })))
547+
.thoughtHistoryLength,
548+
).toBe(2);
549+
},
550+
);
551+
});
395552
});

‎src/sequentialthinking/lib.ts‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,49 @@ export interface ThoughtData {
1212
nextThoughtNeeded: boolean;
1313
}
1414

15+
/**
16+
* How many thoughts one server instance retains when MAX_THOUGHT_HISTORY is
17+
* unset (#2912). A server lives as long as its client's connection, so without
18+
* a cap a long-lived connection grows its history without bound.
19+
*/
20+
export const DEFAULT_MAX_THOUGHT_HISTORY = 1000;
21+
22+
/**
23+
* The thought cap from MAX_THOUGHT_HISTORY: a positive integer, or the default
24+
* when the variable is unset or empty. Any other value is reported on stderr
25+
* and replaced by the default, so a typo cannot remove the bound.
26+
*/
27+
function readMaxThoughtHistory(): number {
28+
const raw = (process.env.MAX_THOUGHT_HISTORY ?? "").trim();
29+
if (raw === "") {
30+
return DEFAULT_MAX_THOUGHT_HISTORY;
31+
}
32+
const value = Number(raw);
33+
if (/^\d+$/.test(raw) && Number.isSafeInteger(value) && value >= 1) {
34+
return value;
35+
}
36+
console.error(
37+
`MAX_THOUGHT_HISTORY must be a positive integer, got "${raw}"; using ${DEFAULT_MAX_THOUGHT_HISTORY}`,
38+
);
39+
return DEFAULT_MAX_THOUGHT_HISTORY;
40+
}
41+
1542
export class SequentialThinkingServer {
43+
// At most maxThoughtHistory thoughts, oldest first. Each branch holds the
44+
// retained thoughts recorded on it, so evicting the oldest thought also
45+
// removes it from its branch, and a branch left empty is dropped: the
46+
// branches together never hold more than the history does.
1647
private thoughtHistory: ThoughtData[] = [];
1748
// Null prototype, so any string branchId (even "constructor" or "__proto__")
1849
// is an ordinary own key rather than an inherited Object.prototype member.
1950
private branches: Record<string, ThoughtData[]> = Object.create(null);
2051
private disableThoughtLogging: boolean;
52+
private maxThoughtHistory: number;
2153

2254
constructor() {
2355
this.disableThoughtLogging =
2456
(process.env.DISABLE_THOUGHT_LOGGING || "").toLowerCase() === "true";
57+
this.maxThoughtHistory = readMaxThoughtHistory();
2558
}
2659

2760
private formatThought(thoughtData: ThoughtData): string {
@@ -109,6 +142,19 @@ export class SequentialThinkingServer {
109142
this.branches[input.branchId].push(input);
110143
}
111144

145+
// One thought in, at most one out. Thoughts enter a branch in the order
146+
// they enter the history, so the evicted thought is its branch's first.
147+
if (this.thoughtHistory.length > this.maxThoughtHistory) {
148+
const [oldest] = this.thoughtHistory.splice(0, 1);
149+
if (oldest.branchFromThought && oldest.branchId) {
150+
const branch = this.branches[oldest.branchId];
151+
branch.shift();
152+
if (branch.length === 0) {
153+
delete this.branches[oldest.branchId];
154+
}
155+
}
156+
}
157+
112158
return {
113159
content: [
114160
{
@@ -118,6 +164,9 @@ export class SequentialThinkingServer {
118164
thoughtNumber: input.thoughtNumber,
119165
totalThoughts: input.totalThoughts,
120166
nextThoughtNeeded: input.nextThoughtNeeded,
167+
// Both describe the retained thoughts: once the cap is
168+
// reached the length stays at MAX_THOUGHT_HISTORY, and a
169+
// branch whose thoughts were all evicted is no longer listed.
121170
branches: Object.keys(this.branches),
122171
thoughtHistoryLength: this.thoughtHistory.length,
123172
},

0 commit comments

Comments
 (0)