Skip to content

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

fix(openclaw-plugin): use character budget for auto recall (#1740)

Eurakaxun16c0bfe76f09
diff --git a/examples/openclaw-plugin/config.ts b/examples/openclaw-plugin/config.ts
index c2d745809..584db0e1d 100644
--- a/examples/openclaw-plugin/config.ts
+++ b/examples/openclaw-plugin/config.ts
@@ -39,8 +39,12 @@ export type MemoryOpenVikingConfig = {
recallResources?: boolean;
recallLimit?: number;
recallScoreThreshold?: number;
+ /** Maximum total characters injected by auto-recall. */
+ recallMaxInjectedChars?: number;
+ /** @deprecated Auto-recall no longer truncates individual memories. */
recallMaxContentChars?: number;
recallPreferAbstract?: boolean;
+ /** @deprecated Use recallMaxInjectedChars. */
recallTokenBudget?: number;
commitTokenThreshold?: number;
bypassSessionPatterns?: string[];
@@ -63,7 +67,7 @@ const DEFAULT_RECALL_LIMIT = 6;
const DEFAULT_RECALL_SCORE_THRESHOLD = 0.15;
const DEFAULT_RECALL_MAX_CONTENT_CHARS = 5000;
const DEFAULT_RECALL_PREFER_ABSTRACT = true;
-const DEFAULT_RECALL_TOKEN_BUDGET = 8000;
+const DEFAULT_RECALL_MAX_INJECTED_CHARS = 4000;
const DEFAULT_COMMIT_TOKEN_THRESHOLD = 20000;
const DEFAULT_BYPASS_SESSION_PATTERNS: string[] = [];
const DEFAULT_EMIT_STANDARD_DIAGNOSTICS = false;
@@ -174,6 +178,7 @@ export const memoryOpenVikingConfigSchema = {
"recallResources",
"recallLimit",
"recallScoreThreshold",
+ "recallMaxInjectedChars",
"recallMaxContentChars",
"recallPreferAbstract",
"recallTokenBudget",
@@ -259,6 +264,18 @@ export const memoryOpenVikingConfigSchema = {
explicitIsolateAgentScopeByUser ??
envIsolateAgentScopeByUser ??
(hasExplicitAgentScopeMode && agentScopeMode === "user_agent" ? true : false);
+ const recallMaxInjectedChars = Math.max(
+ 100,
+ Math.min(
+ 50000,
+ Math.floor(
+ toNumber(
+ cfg.recallMaxInjectedChars,
+ toNumber(cfg.recallTokenBudget, DEFAULT_RECALL_MAX_INJECTED_CHARS),
+ ),
+ ),
+ ),
+ );
return {
mode,
@@ -293,10 +310,8 @@ export const memoryOpenVikingConfigSchema = {
Math.min(10000, Math.floor(toNumber(cfg.recallMaxContentChars, DEFAULT_RECALL_MAX_CONTENT_CHARS))),
),
recallPreferAbstract: cfg.recallPreferAbstract === true,
- recallTokenBudget: Math.max(
- 100,
- Math.min(50000, Math.floor(toNumber(cfg.recallTokenBudget, DEFAULT_RECALL_TOKEN_BUDGET))),
- ),
+ recallMaxInjectedChars,
+ recallTokenBudget: recallMaxInjectedChars,
commitTokenThreshold: Math.max(
0,
Math.min(100_000, Math.floor(toNumber(cfg.commitTokenThreshold, DEFAULT_COMMIT_TOKEN_THRESHOLD))),
@@ -430,11 +445,17 @@ export const memoryOpenVikingConfigSchema = {
placeholder: String(DEFAULT_RECALL_SCORE_THRESHOLD),
advanced: true,
},
+ recallMaxInjectedChars: {
+ label: "Recall Max Injected Chars",
+ placeholder: String(DEFAULT_RECALL_MAX_INJECTED_CHARS),
+ advanced: true,
+ help: "Maximum total characters for auto-recall memory injection. Complete memories that do not fit are skipped, not truncated.",
+ },
recallMaxContentChars: {
- label: "Recall Max Content Chars",
+ label: "Deprecated Recall Max Content Chars",
placeholder: String(DEFAULT_RECALL_MAX_CONTENT_CHARS),
advanced: true,
- help: "Maximum characters per memory content in auto-recall injection. Content exceeding this is truncated.",
+ help: "Deprecated compatibility option and will be removed in a future release. Auto-recall now keeps individual memories intact and uses recallMaxInjectedChars.",
},
recallPreferAbstract: {
label: "Recall Prefer Abstract",
@@ -442,10 +463,10 @@ export const memoryOpenVikingConfigSchema = {
help: "Use memory abstract instead of fetching full content when abstract is available. Reduces token usage.",
},
recallTokenBudget: {
- label: "Recall Token Budget",
- placeholder: String(DEFAULT_RECALL_TOKEN_BUDGET),
+ label: "Deprecated Recall Token Budget",
+ placeholder: String(DEFAULT_RECALL_MAX_INJECTED_CHARS),
advanced: true,
- help: "Maximum estimated tokens for auto-recall memory injection. Injection stops when budget is exhausted.",
+ help: "Deprecated compatibility alias and will be removed in a future release. Use recallMaxInjectedChars.",
},
bypassSessionPatterns: {
label: "Bypass Session Patterns",
diff --git a/examples/openclaw-plugin/index.ts b/examples/openclaw-plugin/index.ts
index e9e6dd691..6ef00db58 100644
--- a/examples/openclaw-plugin/index.ts
+++ b/examples/openclaw-plugin/index.ts
@@ -1573,13 +1573,18 @@ const mergeFindResults = (results: FindResult[]): FindResult => {
(uri) => client.read(uri, agentId),
{
recallPreferAbstract: cfg.recallPreferAbstract,
- recallMaxContentChars: cfg.recallMaxContentChars,
- recallTokenBudget: cfg.recallTokenBudget,
+ recallMaxInjectedChars: cfg.recallMaxInjectedChars,
},
);
const memoryContext = memoryLines.join("\n");
+ if (memoryLines.length === 0) {
+ verboseRoutingInfo(
+ `openviking: skipping auto-recall injection; no complete memories fit maxInjectedChars=${cfg.recallMaxInjectedChars}`,
+ );
+ return;
+ }
verboseRoutingInfo(
- `openviking: injecting ${memoryLines.length} memories (~${estimatedTokens} tokens, budget=${cfg.recallTokenBudget})`,
+ `openviking: injecting ${memoryLines.length} memories (${memoryContext.length} chars, ~${estimatedTokens} tokens, maxInjectedChars=${cfg.recallMaxInjectedChars})`,
);
verboseRoutingInfo(
`openviking: inject-detail ${toJsonLog({ count: memories.length, memories: summarizeInjectionMemories(memories) })}`,
@@ -1905,7 +1910,7 @@ const mergeFindResults = (results: FindResult[]): FindResult => {
},
};
-/** Estimate token count using chars/4 heuristic (adequate for budget enforcement). */
+/** Estimate token count using chars/4 heuristic for diagnostics. */
export function estimateTokenCount(text: string): number {
if (!text) return 0;
return Math.ceil(text.length / 4);
@@ -1913,7 +1918,6 @@ export function estimateTokenCount(text: string): number {
export type BuildMemoryLinesOptions = {
recallPreferAbstract: boolean;
- recallMaxContentChars: number;
};
async function resolveMemoryContent(
@@ -1939,10 +1943,6 @@ async function resolveMemoryContent(
content = item.abstract?.trim() || item.uri;
}
- if (content.length > options.recallMaxContentChars) {
- content = content.slice(0, options.recallMaxContentChars) + "...";
- }
-
return content;
}
@@ -1960,44 +1960,46 @@ export async function buildMemoryLines(
}
export type BuildMemoryLinesWithBudgetOptions = BuildMemoryLinesOptions & {
- recallTokenBudget: number;
+ recallMaxInjectedChars?: number;
+ recallTokenBudget?: number;
};
/**
- * Build memory lines with a token budget constraint.
+ * Build memory lines with a character budget constraint.
*
- * The first memory is always included even if its token count exceeds the
- * remaining budget. This is intentional (spec Section 6.2): with
- * `recallMaxContentChars=5000`, a single line is at most ~1250 tokens — well
- * within the 8000-token default budget — so overshoot is bounded and
- * guarantees at least one memory is surfaced.
+ * Individual memories are never truncated. A memory that cannot fit within the
+ * remaining character budget is skipped so only complete memory entries are
+ * injected.
*/
export async function buildMemoryLinesWithBudget(
memories: FindResultItem[],
readFn: (uri: string) => Promise<string>,
options: BuildMemoryLinesWithBudgetOptions,
): Promise<{ lines: string[]; estimatedTokens: number }> {
- let budgetRemaining = options.recallTokenBudget;
+ const charBudget = options.recallMaxInjectedChars ?? options.recallTokenBudget ?? 0;
const lines: string[] = [];
let totalTokens = 0;
+ let totalChars = 0;
for (const item of memories) {
- if (budgetRemaining <= 0) {
+ if (totalChars >= charBudget) {
break;
}
const content = await resolveMemoryContent(item, readFn, options);
const line = `- [${item.category ?? "memory"}] ${content}`;
- const lineTokens = estimateTokenCount(line);
+ const separatorChars = lines.length > 0 ? 1 : 0;
+ const projectedChars = totalChars + separatorChars + line.length;
- // First line is always included even if it exceeds the budget (spec §6.2).
- if (lineTokens > budgetRemaining && lines.length > 0) {
- break;
+ if (projectedChars > charBudget) {
+ continue;
}
+ const lineTokens = estimateTokenCount(line);
+
lines.push(line);
totalTokens += lineTokens;
- budgetRemaining -= lineTokens;
+ totalChars = projectedChars;
}
return { lines, estimatedTokens: totalTokens };
diff --git a/examples/openclaw-plugin/openclaw.plugin.json b/examples/openclaw-plugin/openclaw.plugin.json
index e72f48075..c1dc1a09f 100644
--- a/examples/openclaw-plugin/openclaw.plugin.json
+++ b/examples/openclaw-plugin/openclaw.plugin.json
@@ -115,11 +115,17 @@
"placeholder": "0.15",
"advanced": true
},
+ "recallMaxInjectedChars": {
+ "label": "Recall Max Injected Chars",
+ "placeholder": "4000",
+ "advanced": true,
+ "help": "Maximum total characters for auto-recall memory injection. Complete memories that do not fit are skipped, not truncated."
+ },
"recallMaxContentChars": {
- "label": "Recall Max Content Chars",
+ "label": "Deprecated Recall Max Content Chars",
"placeholder": "5000",
"advanced": true,
- "help": "Maximum characters per memory content in auto-recall injection"
+ "help": "Deprecated compatibility option and will be removed in a future release. Auto-recall now keeps individual memories intact and uses recallMaxInjectedChars."
},
"recallPreferAbstract": {
"label": "Recall Prefer Abstract",
@@ -127,10 +133,10 @@
"help": "Use memory abstract instead of fetching full content when available"
},
"recallTokenBudget": {
- "label": "Recall Token Budget",
- "placeholder": "8000",
+ "label": "Deprecated Recall Token Budget",
+ "placeholder": "4000",
"advanced": true,
- "help": "Maximum estimated tokens for auto-recall memory injection"
+ "help": "Deprecated compatibility alias and will be removed in a future release. Use recallMaxInjectedChars."
},
"bypassSessionPatterns": {
"label": "Bypass Session Patterns",
@@ -222,6 +228,9 @@
"recallScoreThreshold": {
"type": "number"
},
+ "recallMaxInjectedChars": {
+ "type": "number"
+ },
"recallMaxContentChars": {
"type": "number"
},
diff --git a/examples/openclaw-plugin/tests/context-bloat-730.test.ts b/examples/openclaw-plugin/tests/context-bloat-730.test.ts
index 7c650f4f6..ca78ddcc0 100644
--- a/examples/openclaw-plugin/tests/context-bloat-730.test.ts
+++ b/examples/openclaw-plugin/tests/context-bloat-730.test.ts
@@ -74,7 +74,6 @@ describe("Slice B: prefer abstract over full content fetch", () => {
const lines = await buildMemoryLines(memories, mockRead, {
recallPreferAbstract: true,
- recallMaxContentChars: 500,
});
// Item 1 has abstract — read() should NOT be called for it
@@ -85,8 +84,8 @@ describe("Slice B: prefer abstract over full content fetch", () => {
});
});
-describe("Slice D: recallMaxContentChars truncation", () => {
- it("should truncate content exceeding recallMaxContentChars", async () => {
+describe("Slice D: individual memory integrity", () => {
+ it("should keep full memory content intact", async () => {
const { buildMemoryLines } = await import("../index.js");
const longContent = "A".repeat(2000);
@@ -103,24 +102,15 @@ describe("Slice D: recallMaxContentChars truncation", () => {
const lines = await buildMemoryLines(memories, mockRead, {
recallPreferAbstract: false,
- recallMaxContentChars: 500,
});
- // Content should be truncated to 500 chars + "..."
const contentPart = lines[0]!.replace("- [memory] ", "");
- expect(contentPart.length).toBeLessThanOrEqual(503); // 500 + "..."
- expect(contentPart.endsWith("...")).toBe(true);
- });
-
- it("should have recallMaxContentChars and recallPreferAbstract in parsed config", () => {
- const cfg = memoryOpenVikingConfigSchema.parse({});
- expect(cfg.recallMaxContentChars).toBe(500);
- expect(cfg.recallPreferAbstract).toBe(false);
+ expect(contentPart).toBe(longContent);
});
});
-describe("Slice E: tokenBudget enforcement", () => {
- it("should stop injecting when token budget is exhausted", async () => {
+describe("Slice E: character budget enforcement", () => {
+ it("should stop injecting before the character budget is exceeded", async () => {
const { buildMemoryLinesWithBudget } = await import("../index.js");
// Each memory ~200 chars -> ~50 tokens per line (200 chars + "- [memory] " prefix)
@@ -140,17 +130,13 @@ describe("Slice E: tokenBudget enforcement", () => {
mockRead,
{
recallPreferAbstract: true,
- recallMaxContentChars: 500,
- recallTokenBudget: 100,
+ recallMaxInjectedChars: 400,
},
);
- // Budget = 100 tokens. Each line ~53 tokens ((200 + 13 prefix chars) / 4).
- // First line is always included even if it exceeds the budget (spec §6.2),
- // so we expect at most 2 lines (~106 tokens).
- expect(lines.length).toBeLessThanOrEqual(2);
- expect(lines.length).toBeGreaterThan(0);
- expect(estimatedTokens).toBeLessThanOrEqual(106);
+ expect(lines).toHaveLength(1);
+ expect(lines.join("\n").length).toBeLessThanOrEqual(400);
+ expect(estimatedTokens).toBeLessThanOrEqual(53);
});
it("should estimate tokens as ceil(chars/4)", async () => {
@@ -161,9 +147,10 @@ describe("Slice E: tokenBudget enforcement", () => {
expect(estimateTokenCount("A".repeat(100))).toBe(25);
});
- it("should have recallTokenBudget in parsed config with default 2000", () => {
+ it("should have recallMaxInjectedChars in parsed config with default 4000-character budget", () => {
const cfg = memoryOpenVikingConfigSchema.parse({});
- expect(cfg.recallTokenBudget).toBe(2000);
+ expect(cfg.recallMaxInjectedChars).toBe(4000);
+ expect(cfg.recallTokenBudget).toBe(4000);
});
});
diff --git a/examples/openclaw-plugin/tests/ut/build-memory-lines.test.ts b/examples/openclaw-plugin/tests/ut/build-memory-lines.test.ts
index 71813d3d2..d3b12e056 100644
--- a/examples/openclaw-plugin/tests/ut/build-memory-lines.test.ts
+++ b/examples/openclaw-plugin/tests/ut/build-memory-lines.test.ts
@@ -45,7 +45,6 @@ describe("buildMemoryLines", () => {
const lines = await buildMemoryLines(memories, readFn, {
recallPreferAbstract: true,
- recallMaxContentChars: 500,
});
expect(lines).toHaveLength(2);
@@ -59,7 +58,6 @@ describe("buildMemoryLines", () => {
await buildMemoryLines(memories, readFn, {
recallPreferAbstract: true,
- recallMaxContentChars: 500,
});
expect(readFn).not.toHaveBeenCalled();
@@ -71,7 +69,6 @@ describe("buildMemoryLines", () => {
const lines = await buildMemoryLines(memories, readFn, {
recallPreferAbstract: false,
- recallMaxContentChars: 500,
});
expect(readFn).toHaveBeenCalledWith("viking://user/memories/test-1");
@@ -84,7 +81,6 @@ describe("buildMemoryLines", () => {
const lines = await buildMemoryLines(memories, readFn, {
recallPreferAbstract: false,
- recallMaxContentChars: 500,
});
expect(lines[0]).toContain("Fallback abstract");
@@ -96,24 +92,21 @@ describe("buildMemoryLines", () => {
const lines = await buildMemoryLines(memories, readFn, {
recallPreferAbstract: false,
- recallMaxContentChars: 500,
});
expect(lines[0]).toContain("Fallback abstract");
});
- it("truncates content exceeding recallMaxContentChars", async () => {
+ it("keeps individual memory content intact", async () => {
const longAbstract = "x".repeat(600);
const memories = [makeMemory({ abstract: longAbstract })];
const readFn = vi.fn();
const lines = await buildMemoryLines(memories, readFn, {
recallPreferAbstract: true,
- recallMaxContentChars: 100,
});
- expect(lines[0]).toContain("...");
- expect(lines[0].length).toBeLessThan(600);
+ expect(lines[0]).toBe(`- [core] ${longAbstract}`);
});
it("uses uri as fallback when no abstract", async () => {
@@ -122,7 +115,6 @@ describe("buildMemoryLines", () => {
const lines = await buildMemoryLines(memories, readFn, {
recallPreferAbstract: true,
- recallMaxContentChars: 500,
});
expect(lines[0]).toContain("viking://user/memories/test-1");
@@ -134,7 +126,6 @@ describe("buildMemoryLines", () => {
const lines = await buildMemoryLines(memories, readFn, {
recallPreferAbstract: true,
- recallMaxContentChars: 500,
});
expect(lines[0]).toContain("[memory]");
@@ -142,31 +133,30 @@ describe("buildMemoryLines", () => {
});
describe("buildMemoryLinesWithBudget", () => {
- it("stops adding when budget is exhausted", async () => {
+ it("stops adding before total injected characters exceed the budget", async () => {
const memories = [
- makeMemory({ abstract: "a".repeat(100), category: "a" }),
- makeMemory({ abstract: "b".repeat(100), category: "b" }),
- makeMemory({ abstract: "c".repeat(100), category: "c" }),
+ makeMemory({ abstract: "a".repeat(3000), category: "a" }),
+ makeMemory({ abstract: "b".repeat(1500), category: "b" }),
];
const readFn = vi.fn();
- // Each line ~100 chars → ~25 tokens. Budget=40 fits 1-2 lines.
const { lines, estimatedTokens } = await buildMemoryLinesWithBudget(
memories,
readFn,
{
recallPreferAbstract: true,
- recallMaxContentChars: 500,
- recallTokenBudget: 40,
+ recallMaxInjectedChars: 4000,
},
);
- expect(lines.length).toBeLessThan(3);
- expect(estimatedTokens).toBeLessThanOrEqual(40 + 30); // first always included even if over
+ expect(lines).toHaveLength(1);
+ expect(lines[0]!.length).toBeLessThanOrEqual(4000);
+ expect(estimatedTokens).toBe(estimateTokenCount(lines[0]!));
});
- it("always includes the first memory even if over budget", async () => {
+ it("skips memories that do not fit the remaining character budget", async () => {
const memories = [
- makeMemory({ abstract: "a".repeat(400) }), // ~100 tokens
+ makeMemory({ abstract: "a".repeat(400), category: "large" }),
+ makeMemory({ abstract: "short", category: "small" }),
];
const readFn = vi.fn();
@@ -175,12 +165,31 @@ describe("buildMemoryLinesWithBudget", () => {
readFn,
{
recallPreferAbstract: true,
- recallMaxContentChars: 500,
- recallTokenBudget: 10,
+ recallMaxInjectedChars: 20,
},
);
expect(lines).toHaveLength(1);
+ expect(lines[0]).toBe("- [small] short");
+ });
+
+ it("returns no lines when no complete memory fits the character budget", async () => {
+ const memories = [
+ makeMemory({ abstract: "a".repeat(400), category: "large" }),
+ ];
+ const readFn = vi.fn();
+
+ const { lines, estimatedTokens } = await buildMemoryLinesWithBudget(
+ memories,
+ readFn,
+ {
+ recallPreferAbstract: true,
+ recallMaxInjectedChars: 20,
+ },
+ );
+
+ expect(lines).toHaveLength(0);
+ expect(estimatedTokens).toBe(0);
});
it("returns correct estimatedTokens sum", async () => {
@@ -194,7 +203,6 @@ describe("buildMemoryLinesWithBudget", () => {
readFn,
{
recallPreferAbstract: true,
- recallMaxContentChars: 500,
recallTokenBudget: 2000,
},
);
@@ -210,7 +218,6 @@ describe("buildMemoryLinesWithBudget", () => {
readFn,
{
recallPreferAbstract: true,
- recallMaxContentChars: 500,
recallTokenBudget: 2000,
},
);
diff --git a/examples/openclaw-plugin/tests/ut/config.test.ts b/examples/openclaw-plugin/tests/ut/config.test.ts
index d94de3817..da44b7dfe 100644
--- a/examples/openclaw-plugin/tests/ut/config.test.ts
+++ b/examples/openclaw-plugin/tests/ut/config.test.ts
@@ -20,7 +20,8 @@ describe("memoryOpenVikingConfigSchema.parse()", () => {
expect(cfg.autoCapture).toBe(true);
expect(cfg.autoRecall).toBe(true);
expect(cfg.recallPreferAbstract).toBe(false);
- expect(cfg.recallTokenBudget).toBe(8000);
+ expect(cfg.recallMaxInjectedChars).toBe(4000);
+ expect(cfg.recallTokenBudget).toBe(4000);
expect(cfg.commitTokenThreshold).toBe(20000);
expect(cfg.captureMode).toBe("semantic");
expect(cfg.captureMaxLength).toBe(24000);
@@ -32,6 +33,37 @@ describe("memoryOpenVikingConfigSchema.parse()", () => {
expect(cfg.emitStandardDiagnostics).toBe(false);
});
+ it("defaults recallMaxInjectedChars to the 4000-character memory budget", () => {
+ const cfg = memoryOpenVikingConfigSchema.parse({});
+ expect(cfg.recallMaxInjectedChars).toBe(4000);
+ expect(cfg.recallTokenBudget).toBe(4000);
+ });
+
+ it("uses recallMaxInjectedChars as the canonical auto-recall character budget", () => {
+ const cfg = memoryOpenVikingConfigSchema.parse({
+ recallMaxInjectedChars: 1234,
+ });
+ expect(cfg.recallMaxInjectedChars).toBe(1234);
+ expect(cfg.recallTokenBudget).toBe(1234);
+ });
+
+ it("falls back to deprecated recallTokenBudget when recallMaxInjectedChars is unset", () => {
+ const cfg = memoryOpenVikingConfigSchema.parse({
+ recallTokenBudget: 2345,
+ });
+ expect(cfg.recallMaxInjectedChars).toBe(2345);
+ expect(cfg.recallTokenBudget).toBe(2345);
+ });
+
+ it("prefers recallMaxInjectedChars over deprecated recallTokenBudget", () => {
+ const cfg = memoryOpenVikingConfigSchema.parse({
+ recallMaxInjectedChars: 3456,
+ recallTokenBudget: 2345,
+ });
+ expect(cfg.recallMaxInjectedChars).toBe(3456);
+ expect(cfg.recallTokenBudget).toBe(3456);
+ });
+
it("remote mode preserves custom baseUrl", () => {
const cfg = memoryOpenVikingConfigSchema.parse({
mode: "remote",