Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(openclaw-plugin): enforce assemble token budgets (#1511)

Mingjian Que00cd0e9422d3
diff --git a/examples/openclaw-plugin/context-engine.ts b/examples/openclaw-plugin/context-engine.ts
index cf257e98a..8fbfff3a5 100644
--- a/examples/openclaw-plugin/context-engine.ts
+++ b/examples/openclaw-plugin/context-engine.ts
@@ -117,10 +117,12 @@ const RESERVED_MIN = 20_000;
const RESERVED_RATIO = 0.15;
const ARCHIVE_INDEX_TRIM_LIMIT = 10;
-function allocateContextBudget(totalBudget: number): ContextBudgets {
- const reserved = Math.max(totalBudget * RESERVED_RATIO, RESERVED_MIN);
- const archiveMemory = Math.min(totalBudget * ARCHIVE_BUDGET_RATIO, ARCHIVE_BUDGET_CAP);
- const sessionContext = Math.max(totalBudget - archiveMemory - reserved, 0);
+function allocateContextBudget(totalBudget: number, instructionTokens = 0): ContextBudgets {
+ const reserveFloor = totalBudget >= RESERVED_MIN * 2 ? RESERVED_MIN : 0;
+ const reserved = Math.min(totalBudget, Math.max(totalBudget * RESERVED_RATIO, reserveFloor));
+ const usableBudget = Math.max(totalBudget - reserved - instructionTokens, 0);
+ const archiveMemory = Math.min(usableBudget * ARCHIVE_BUDGET_RATIO, ARCHIVE_BUDGET_CAP);
+ const sessionContext = Math.max(usableBudget - archiveMemory, 0);
return { archiveMemory, sessionContext, reserved };
}
@@ -731,15 +733,21 @@ export function createMemoryOpenVikingContextEngine(params: {
budgets: ContextBudgets;
instruction: { text: string; tokens: number };
} {
- // 4-layer context partitioning (budget computed for diag; BUDGET_UNLIMITED bypasses limits):
+ const hasArchives = Boolean(overview) || preAbstracts.length > 0;
+ const instruction = hasArchives ? buildInstructionPrompt() : { text: "", tokens: 0 };
+
+ // 4-layer context partitioning:
// Instruction — system prompt guide (Archive Index / Session History usage)
// Archive — session history summary + per-archive one-line abstracts
// Session — active OV messages converted to AgentMessage format
// Reserved — headroom for model output (not consumed here)
- const budgets = allocateContextBudget(tokenBudget);
- const instruction = buildInstructionPrompt();
- const archive = buildArchiveMemory(overview, preAbstracts, BUDGET_UNLIMITED);
- const session = buildSessionContext(ovMessages, BUDGET_UNLIMITED);
+ const budgets = allocateContextBudget(tokenBudget, instruction.tokens);
+ const archive = buildArchiveMemory(overview, preAbstracts, budgets.archiveMemory);
+ const sessionBudget = Math.max(
+ tokenBudget - budgets.reserved - instruction.tokens - archive.tokens,
+ 0,
+ );
+ const session = buildSessionContext(ovMessages, sessionBudget);
const assembled = [...archive.messages, ...session.messages];
logger.info(
@@ -840,7 +848,7 @@ export function createMemoryOpenVikingContextEngine(params: {
});
}
- const assembledTokens = roughEstimate(sanitized);
+ const assembledTokens = roughEstimate(sanitized) + instruction.tokens;
const tokensSaved = originalTokens - assembledTokens;
const savingPct = originalTokens > 0 ? Math.round((tokensSaved / originalTokens) * 100) : 0;
@@ -864,7 +872,7 @@ export function createMemoryOpenVikingContextEngine(params: {
return {
messages: sanitized,
estimatedTokens: assembledTokens,
- ...(hasArchives ? { systemPromptAddition: instruction.text } : {}),
+ ...(instruction.text ? { systemPromptAddition: instruction.text } : {}),
};
} catch (err) {
logger.warn?.(
diff --git a/examples/openclaw-plugin/tests/context-engine-assemble.test.ts b/examples/openclaw-plugin/tests/context-engine-assemble.test.ts
index b986d7060..e0d20991e 100644
--- a/examples/openclaw-plugin/tests/context-engine-assemble.test.ts
+++ b/examples/openclaw-plugin/tests/context-engine-assemble.test.ts
@@ -16,6 +16,10 @@ function roughEstimate(messages: unknown[]): number {
return Math.ceil(JSON.stringify(messages).length / 4);
}
+function systemPromptTokens(text?: string): number {
+ return text ? Math.ceil(text.length / 4) : 0;
+}
+
function makeLogger() {
return {
info: vi.fn(),
@@ -110,7 +114,9 @@ describe("context-engine assemble()", () => {
expect(resolveAgentId).toHaveBeenCalledWith("session-1", undefined, "session-1");
expect(client.getSessionContext).toHaveBeenCalledWith("session-1", 4096, "agent:session-1");
- expect(result.estimatedTokens).toBe(roughEstimate(result.messages));
+ expect(result.estimatedTokens).toBe(
+ roughEstimate(result.messages) + systemPromptTokens(result.systemPromptAddition),
+ );
expect(result.systemPromptAddition).toContain("Session Context Guide");
expect(result.messages).toEqual([
{
@@ -286,4 +292,44 @@ describe("context-engine assemble()", () => {
estimatedTokens: roughEstimate(liveMessages),
});
});
+
+ it("keeps assembled output within the requested token budget", async () => {
+ const longText = "A".repeat(2500);
+ const { engine } = makeEngine({
+ latest_archive_overview: "# Session Summary\nA short overview",
+ pre_archive_abstracts: [],
+ messages: [
+ {
+ id: "msg_long_1",
+ role: "user",
+ created_at: "2026-03-24T00:00:00Z",
+ parts: [{ type: "text", text: longText }],
+ },
+ {
+ id: "msg_long_2",
+ role: "assistant",
+ created_at: "2026-03-24T00:00:01Z",
+ parts: [{ type: "text", text: longText }],
+ },
+ ],
+ estimatedTokens: 2000,
+ stats: {
+ ...makeStats(),
+ totalArchives: 1,
+ includedArchives: 1,
+ activeTokens: 2000,
+ archiveTokens: 10,
+ },
+ });
+
+ const result = await engine.assemble({
+ sessionId: "session-budgeted",
+ messages: [],
+ tokenBudget: 1024,
+ });
+
+ expect(result.estimatedTokens).toBeLessThanOrEqual(1024);
+ expect(result.messages.length).toBeGreaterThan(0);
+ expect(result.systemPromptAddition).toContain("Session Context Guide");
+ });
});
diff --git a/examples/openclaw-plugin/tests/ut/context-engine-assemble.test.ts b/examples/openclaw-plugin/tests/ut/context-engine-assemble.test.ts
index 3ea1c504a..d24cbc46d 100644
--- a/examples/openclaw-plugin/tests/ut/context-engine-assemble.test.ts
+++ b/examples/openclaw-plugin/tests/ut/context-engine-assemble.test.ts
@@ -16,6 +16,10 @@ function roughEstimate(messages: unknown[]): number {
return Math.ceil(JSON.stringify(messages).length / 4);
}
+function systemPromptTokens(text?: string): number {
+ return text ? Math.ceil(text.length / 4) : 0;
+}
+
function makeLogger() {
return {
info: vi.fn(),
@@ -123,7 +127,9 @@ describe("context-engine assemble()", () => {
expect(resolveAgentId).toHaveBeenCalledWith("session-1", undefined, "session-1");
expect(client.getSessionContext).toHaveBeenCalledWith("session-1", 4096, "agent:session-1");
- expect(result.estimatedTokens).toBe(roughEstimate(result.messages));
+ expect(result.estimatedTokens).toBe(
+ roughEstimate(result.messages) + systemPromptTokens(result.systemPromptAddition),
+ );
expect(result.systemPromptAddition).toContain("Session Context Guide");
expect(result.messages[0]).toEqual({
role: "user",
@@ -435,6 +441,46 @@ describe("context-engine assemble()", () => {
expect(result.systemPromptAddition).toContain("Session Context Guide");
});
+ it("keeps assembled output within the requested token budget", async () => {
+ const longText = "A".repeat(2500);
+ const { engine } = makeEngine({
+ latest_archive_overview: "# Session Summary\nA short overview",
+ pre_archive_abstracts: [],
+ messages: [
+ {
+ id: "msg_long_1",
+ role: "user",
+ created_at: "2026-03-24T00:00:00Z",
+ parts: [{ type: "text", text: longText }],
+ },
+ {
+ id: "msg_long_2",
+ role: "assistant",
+ created_at: "2026-03-24T00:00:01Z",
+ parts: [{ type: "text", text: longText }],
+ },
+ ],
+ estimatedTokens: 2000,
+ stats: {
+ ...makeStats(),
+ totalArchives: 1,
+ includedArchives: 1,
+ activeTokens: 2000,
+ archiveTokens: 10,
+ },
+ });
+
+ const result = await engine.assemble({
+ sessionId: "session-budgeted",
+ messages: [],
+ tokenBudget: 1024,
+ });
+
+ expect(result.estimatedTokens).toBeLessThanOrEqual(1024);
+ expect(result.messages.length).toBeGreaterThan(0);
+ expect(result.systemPromptAddition).toContain("Session Context Guide");
+ });
+
it("falls back to original messages when getClient throws", async () => {
const logger = makeLogger();
const getClient = vi.fn().mockRejectedValue(new Error("OV connection refused"));