Skip to content

Commit 1bdcf28

Browse files
authored
feat(recall): cap injected memory context (#71)
- Add `recall.maxCharsPerMemory` and `recall.maxTotalRecallChars` with defaults of `0`, which do not alter existing behavior. Users can opt in by setting positive values to cap injected memory context. - Apply the budget after L1 search and before `<relevant-memories>` injection, preserving score order while truncating oversized entries and dropping overflow. - Document the new guards in README, README_CN, and `openclaw.plugin.json`.
1 parent d92cbd3 commit 1bdcf28

5 files changed

Lines changed: 96 additions & 1 deletion

File tree

README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -259,6 +259,8 @@ docker exec -it hermes-memory hermes
259259
| `storeBackend` | `"sqlite"` | Storage backend: `sqlite` |
260260
| `recall.strategy` | `"hybrid"` | Recall strategy: `keyword` / `embedding` / `hybrid` (RRF fusion, recommended) |
261261
| `recall.maxResults` | `5` | Number of items returned per recall |
262+
| `recall.maxCharsPerMemory` | `0` | Max characters injected for one recalled L1 memory; `0` disables this guard |
263+
| `recall.maxTotalRecallChars` | `0` | Total character budget for auto-recalled L1 memories; `0` disables this guard |
262264
| `pipeline.everyNConversations` | `5` | Trigger an L1 memory extraction every N turns |
263265
| `extraction.maxMemoriesPerSession` | `20` | Max memories extracted per L1 pass |
264266
| `persona.triggerEveryN` | `50` | Generate the user persona every N new memories |

README_CN.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,8 @@ docker exec -it hermes-memory hermes
263263
| `storeBackend` | `"sqlite"` | 存储后端:`sqlite` |
264264
| `recall.strategy` | `"hybrid"` | 召回策略:`keyword` / `embedding` / `hybrid`(RRF 融合,推荐) |
265265
| `recall.maxResults` | `5` | 每次召回条数 |
266+
| `recall.maxCharsPerMemory` | `0` | 单条 L1 记忆注入的最大字符数;`0` 表示不限制 |
267+
| `recall.maxTotalRecallChars` | `0` | 每轮 auto-recall 注入的 L1 记忆总字符预算;`0` 表示不限制 |
266268
| `pipeline.everyNConversations` | `5` | 每 N 轮对话触发一次 L1 记忆提取 |
267269
| `extraction.maxMemoriesPerSession` | `20` | 单次 L1 最多提取多少条 |
268270
| `persona.triggerEveryN` | `50` | 每 N 条新记忆触发用户画像生成 |

openclaw.plugin.json

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,8 @@
6969
"properties": {
7070
"enabled": { "type": "boolean", "default": true, "description": "是否启用自动召回" },
7171
"maxResults": { "type": "number", "default": 5, "description": "召回最大结果数" },
72+
"maxCharsPerMemory": { "type": "number", "default": 0, "description": "单条 L1 记忆注入的最大字符数;填 0 表示不限制" },
73+
"maxTotalRecallChars": { "type": "number", "default": 0, "description": "本轮 auto-recall 注入的 L1 记忆总字符预算;填 0 表示不限制" },
7274
"scoreThreshold": { "type": "number", "default": 0.3, "description": "最低分数阈值" },
7375
"strategy": { "type": "string", "enum": ["embedding", "keyword", "hybrid"], "default": "hybrid", "description": "搜索策略:keyword(关键词)、embedding(向量)、hybrid(混合RRF融合,推荐)" },
7476
"timeoutMs": { "type": "number", "default": 5000, "description": "召回整体超时(毫秒),超时后跳过记忆注入并打印警告日志" }

src/config.ts

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,10 @@ export interface RecallConfig {
8080
enabled: boolean;
8181
/** Max results to return (default: 5) */
8282
maxResults: number;
83+
/** Max characters injected for a single recalled L1 memory. 0 disables the per-memory limit. */
84+
maxCharsPerMemory: number;
85+
/** Max total characters injected for all recalled L1 memories. 0 disables the total limit. */
86+
maxTotalRecallChars: number;
8387
/** Minimum score threshold (default: 0.3) */
8488
scoreThreshold: number;
8589
/** Search strategy (default: "hybrid") */
@@ -486,6 +490,8 @@ export function parseConfig(raw: Record<string, unknown> | undefined): MemoryTda
486490
recall: {
487491
enabled: bool(recallGroup, "enabled") ?? true,
488492
maxResults: num(recallGroup, "maxResults") ?? 5,
493+
maxCharsPerMemory: num(recallGroup, "maxCharsPerMemory") ?? 0,
494+
maxTotalRecallChars: num(recallGroup, "maxTotalRecallChars") ?? 0,
489495
scoreThreshold: num(recallGroup, "scoreThreshold") ?? 0.3,
490496
strategy: validateStrategy(str(recallGroup, "strategy")) ?? "hybrid",
491497
timeoutMs: num(recallGroup, "timeoutMs") ?? 5000,

src/core/hooks/auto-recall.ts

Lines changed: 84 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@ import type { EmbeddingService, EmbeddingCallOptions } from "../store/embedding.
2222
import { sanitizeText } from "../../utils/sanitize.js";
2323

2424
const TAG = "[memory-tdai] [recall]";
25+
const RECALL_TRUNCATION_SUFFIX = "…(已截断;可用 tdai_memory_search 或 tdai_conversation_search 查看详情)";
26+
const MIN_TRUNCATED_RECALL_LINE_CHARS = 40;
27+
const RECALL_LINE_SEPARATOR = "\n";
2528

2629
/**
2730
* Memory tools usage guide — injected at the end of memory context so the
@@ -127,6 +130,7 @@ async function performAutoRecallInner(params: {
127130
const searchResult = await searchMemories(userText, pluginDataDir, cfg, logger, effectiveStrategy as "keyword" | "embedding" | "hybrid", vectorStore, embeddingService);
128131
memoryLines = searchResult.lines;
129132
searchTiming = searchResult.timing;
133+
memoryLines = applyRecallBudget(memoryLines, cfg.recall, logger);
130134

131135
// Extract structured RecalledMemory from formatted lines for metric reporting
132136
recalledL1Memories = memoryLines.map((line) => {
@@ -206,7 +210,7 @@ async function performAutoRecallInner(params: {
206210
let prependContext: string | undefined;
207211
if (memoryLines.length > 0) {
208212
prependContext =
209-
`<relevant-memories>\n以下是当前对话召回的相关记忆,不代表当前任务进程,仅作为参考:\n\n${memoryLines.join("\n")}\n</relevant-memories>`;
213+
`<relevant-memories>\n以下是当前对话召回的相关记忆,不代表当前任务进程,仅作为参考:\n\n${memoryLines.join(RECALL_LINE_SEPARATOR)}\n</relevant-memories>`;
210214
}
211215

212216
// Append memory tools usage guide to the stable part so the agent knows
@@ -706,6 +710,85 @@ function formatMemoryLine(m: FormatableMemory): string {
706710
return line;
707711
}
708712

713+
function applyRecallBudget(
714+
lines: string[],
715+
recall: MemoryTdaiConfig["recall"],
716+
logger?: Logger,
717+
): string[] {
718+
const maxCharsPerMemory = normalizeBudgetLimit(recall.maxCharsPerMemory);
719+
const maxTotalRecallChars = normalizeBudgetLimit(recall.maxTotalRecallChars);
720+
721+
if (!maxCharsPerMemory && !maxTotalRecallChars) {
722+
return lines;
723+
}
724+
725+
const budgeted: string[] = [];
726+
let usedChars = 0;
727+
let truncatedCount = 0;
728+
let droppedCount = 0;
729+
730+
for (let i = 0; i < lines.length; i++) {
731+
const line = lines[i];
732+
const perMemoryBounded = maxCharsPerMemory
733+
? truncateRecallLine(line, maxCharsPerMemory)
734+
: line;
735+
let wasTruncated = perMemoryBounded !== line;
736+
737+
if (!maxTotalRecallChars) {
738+
budgeted.push(perMemoryBounded);
739+
if (wasTruncated) truncatedCount++;
740+
continue;
741+
}
742+
743+
const separatorChars = budgeted.length > 0 ? RECALL_LINE_SEPARATOR.length : 0;
744+
const remainingChars = maxTotalRecallChars - usedChars - separatorChars;
745+
if (remainingChars <= 0) {
746+
droppedCount += lines.length - i;
747+
break;
748+
}
749+
750+
if (perMemoryBounded.length > remainingChars) {
751+
const canFit = remainingChars >= MIN_TRUNCATED_RECALL_LINE_CHARS;
752+
if (canFit) {
753+
const totalBounded = truncateRecallLine(perMemoryBounded, remainingChars);
754+
budgeted.push(totalBounded);
755+
usedChars += separatorChars + totalBounded.length;
756+
wasTruncated ||= totalBounded !== perMemoryBounded;
757+
if (wasTruncated) truncatedCount++;
758+
}
759+
droppedCount += lines.length - i - (canFit ? 1 : 0);
760+
break;
761+
}
762+
763+
budgeted.push(perMemoryBounded);
764+
usedChars += separatorChars + perMemoryBounded.length;
765+
if (wasTruncated) truncatedCount++;
766+
}
767+
768+
if (truncatedCount > 0 || droppedCount > 0) {
769+
logger?.debug?.(
770+
`${TAG} Recall budget applied: input=${lines.length}, output=${budgeted.length}, ` +
771+
`truncated=${truncatedCount}, dropped=${droppedCount}, ` +
772+
`maxCharsPerMemory=${recall.maxCharsPerMemory}, maxTotalRecallChars=${recall.maxTotalRecallChars}`,
773+
);
774+
}
775+
776+
return budgeted;
777+
}
778+
779+
function normalizeBudgetLimit(value: number | undefined): number | undefined {
780+
if (value == null || !Number.isFinite(value) || value <= 0) return undefined;
781+
return Math.floor(value);
782+
}
783+
784+
function truncateRecallLine(line: string, maxChars: number): string {
785+
if (line.length <= maxChars) return line;
786+
if (maxChars <= RECALL_TRUNCATION_SUFFIX.length) {
787+
return line.slice(0, maxChars);
788+
}
789+
return `${line.slice(0, maxChars - RECALL_TRUNCATION_SUFFIX.length).trimEnd()}${RECALL_TRUNCATION_SUFFIX}`;
790+
}
791+
709792
/**
710793
* Format an ISO 8601 timestamp to a concise date or datetime string.
711794
* - If the time part is 00:00:00 → show date only (e.g. "2025-03-01")

0 commit comments

Comments
 (0)