diff --git a/README.md b/README.md index 1d0790c9..0a5edc94 100644 --- a/README.md +++ b/README.md @@ -223,9 +223,22 @@ if __name__ == "__main__": ### Architecture of the file-based ReMeLight memory system -[CoPaw MemoryManager](https://github.com/agentscope-ai/CoPaw/blob/main/src/copaw/agents/memory/memory_manager.py) -inherits -`ReMeLight` and integrates its memory capabilities into the agent reasoning loop: +#### Context data structure + +```mermaid +flowchart TD + A[Context] --> B[compact_summary] + B --> C[dialog path guide + Goal/Constraints/Progress/KeyDecisions/NextSteps] + A --> E[messages: full dialogue history] + A --> F[File System Cache] + F --> G[dialog/YYYY-MM-DD.jsonl] + F --> H[tool_result/uuid.txt N-day TTL] +``` + +--- + +[CoPaw MemoryManager](https://github.com/agentscope-ai/CoPaw/blob/main/src/copaw/agents/memory/reme_light_memory_manager.py) +inherits `ReMeLight` and integrates its memory capabilities into the agent reasoning loop: ```mermaid graph LR @@ -283,16 +296,18 @@ graph LR **Summary structure** (context checkpoints): -| Field | Description | -|-----------------------|------------------------------------------------------------------------| -| `## Goal` | User goals | -| `## Constraints` | Constraints and preferences | -| `## Progress` | Task progress | -| `## Key Decisions` | Key decisions | -| `## Next Steps` | Next step plans | -| `## Critical Context` | Critical data such as file paths, function names, error messages, etc. | +| Field | Description | +|-----------------------|-----------------------------------------------------------------------------------------| +| `## Goal` | User goals | +| `## Constraints` | Constraints and preferences | +| `## Progress` | Task progress | +| `## Key Decisions` | Key decisions | +| `## Next Steps` | Next step plans | +| `## Critical Context` | Critical data such as file paths, function names, error messages, etc. | - **Incremental updates**: when `previous_summary` is provided, new conversations are merged into the existing summary. +- **Thinking enhancement**: with `add_thinking_block=True` (default), a reasoning step is added before generating the + summary to improve quality. --- @@ -325,18 +340,25 @@ graph LR #### 4. `compact_tool_result` — tool result compaction [ToolResultCompactor](reme/memory/file_based/components/tool_result_compactor.py) addresses the problem of long tool -outputs bloating the context. +outputs bloating the context. It applies two different truncation strategies depending on whether a message falls within +the `recent_n` window: ```mermaid graph LR - M[messages] --> L{Iterate tool_result
len > threshold?} - L -->|No| K[Keep as-is] - L -->|Yes| T[truncate_text
Truncate to threshold] - T --> S[Write full content
tool_result/uuid.txt] - S --> R[Append file path reference
to message] - R --> C[cleanup_expired_files
Delete expired files] + M[messages] --> B{Within recent_n?} + B -->|Yes - recent| C[Low truncation recent_max_bytes=100KB
Save full content to tool_result/uuid.txt
Hint: 'Read from line N'] + B -->|No - old| D[High truncation old_max_bytes=3KB
Reference existing file
More aggressive truncation] + C --> E[cleanup_expired_files
Delete expired files] + D --> E ``` +| Parameter | Default | Description | +|--------------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------| +| `recent_n` | `1` | Minimum number of trailing consecutive tool-result messages treated as "recent" (use low truncation) | +| `recent_max_bytes` | `100 * 1024` (100 KB) | Truncation threshold for recent messages; content beyond this is saved to `tool_result/` with a file path and start-line hint | +| `old_max_bytes` | `3000` (3 KB) | Truncation threshold for older messages; truncation is more aggressive | +| `retention_days` | `3` | Number of days to retain tool result files; expired files are auto-cleaned | + - **Auto cleanup**: expired files (older than `retention_days`) are deleted automatically during `start` / `close` / `compact_tool_result`. @@ -411,10 +433,18 @@ graph LR **Execution flow**: -1. `compact_tool_result` — compact long tool outputs. -2. `check_context` — check whether the context exceeds limits. -3. `compact_memory` — generate compact summary (sync). -4. `summary_memory` — persist memory (async in the background). +1. `compact_tool_result` — compact long tool outputs for all messages except the most recent + `tool_result_compact_keep_n`. +2. `check_context` — check whether the context exceeds limits (remaining space = threshold minus tokens used by system + prompt and compressed summary). +3. `compact_memory` — generate compact summary (sync), appended into `compact_summary`. +4. `summary_memory` — persist memory to `memory/*.md` (async in the background, non-blocking). + +| Key parameter | Default | Description | +|------------------------------|---------|-------------------------------------------------------------------------------------| +| `tool_result_compact_keep_n` | `3` | Skip tool result compaction for the most recent N messages (preserve full content) | +| `memory_compact_reserve` | `10000` | Token count to reserve for recent messages; messages beyond this trigger compaction | +| `compact_ratio` | `0.7` | Compaction threshold ratio: `max_input_length × compact_ratio × 0.95` | --- diff --git a/README_ZH.md b/README_ZH.md index ee455318..306dc66a 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -215,7 +215,21 @@ if __name__ == "__main__": ### 基于文件的 ReMeLight 记忆系统架构 -[CoPaw MemoryManager](https://github.com/agentscope-ai/CoPaw/blob/main/src/copaw/agents/memory/memory_manager.py) 继承 +#### 上下文数据结构 + +```mermaid +flowchart TD + A[Context] --> B[compact_summary] + B --> C[dialog 路径引导 + Goal/Constraints/Progress/KeyDecisions/NextSteps] + A --> E[messages: 完整对话历史] + A --> F[文件系统缓存] + F --> G[dialog/YYYY-MM-DD.jsonl] + F --> H[tool_result/uuid.txt N天TTL] +``` + +--- + +[CoPaw MemoryManager](https://github.com/agentscope-ai/CoPaw/blob/main/src/copaw/agents/memory/reme_light_memory_manager.py) 继承 `ReMeLight`，将记忆能力集成到 Agent 推理流程中： ```mermaid @@ -281,6 +295,7 @@ graph LR | `## Critical Context` | 文件路径、函数名、错误信息等关键数据 | - **增量更新**：传入 `previous_summary` 时，自动将新对话与旧摘要合并 +- **思考增强**：`add_thinking_block=True`（默认）时，在生成摘要前加入思考步骤，提升摘要质量 --- @@ -311,18 +326,24 @@ graph LR #### 4. compact_tool_result — 工具结果压缩 -[ToolResultCompactor](reme/memory/file_based/components/tool_result_compactor.py) 解决工具输出过长导致上下文膨胀的问题。 +[ToolResultCompactor](reme/memory/file_based/components/tool_result_compactor.py) 解决工具输出过长导致上下文膨胀的问题。根据消息是否在 `recent_n` 范围内，采用不同的截断策略： ```mermaid graph LR - M[messages] --> L{遍历 tool_result
len > threshold?} - L -->|否| K[保留原样] - L -->|是| T[truncate_text
截断到 threshold] - T --> S[完整内容写入
tool_result/uuid.txt] - S --> R[消息追加文件路径引用] - R --> C[cleanup_expired_files
清理过期文件] + M[messages] --> B{属于 recent_n 范围?} + B -->|是 近期消息| C[低截断 recent_max_bytes=100KB
完整内容写入 tool_result/uuid.txt
消息追加: 从第N行开始读] + B -->|否 历史消息| D[高截断 old_max_bytes=3KB
引用已有文件路径
更激进截断] + C --> E[cleanup_expired_files
清理过期文件] + D --> E ``` +| 参数 | 默认值 | 说明 | +|--------------------|---------------------|----------------------------------------------| +| `recent_n` | `1` | 末尾连续工具结果消息的最小数量，视为"近期"，使用低截断阈值 | +| `recent_max_bytes` | `100 * 1024`（100KB） | 近期消息的截断阈值；超出部分转存到 `tool_result/` 并附注文件路径和起始行 | +| `old_max_bytes` | `3000`（3KB） | 历史消息的截断阈值，截断更激进 | +| `retention_days` | `3` | 工具结果文件的保留天数，过期自动清理 | + - **自动清理**：过期文件（超过 `retention_days`）在 `start`/`close`/`compact_tool_result` 时自动删除 --- @@ -394,10 +415,16 @@ graph LR **执行流程**： -1. `compact_tool_result` — 压缩超长工具输出 -2. `check_context` — 检查上下文是否超限 -3. `compact_memory` — 生成压缩摘要（同步） -4. `summary_memory` — 持久化记忆（异步后台） +1. `compact_tool_result` — 对除最近 `tool_result_compact_keep_n` 条消息之外的历史消息压缩超长工具输出 +2. `check_context` — 检查上下文是否超限（扣除 system_prompt 和 compressed_summary 的 token 后计算剩余空间） +3. `compact_memory` — 生成压缩摘要（同步），结果追加到 `compact_summary` +4. `summary_memory` — 持久化记忆到 `memory/*.md`（异步后台，不阻塞推理） + +| 关键参数 | 默认值 | 说明 | +|------------------------------|---------|--------------------------------------------------| +| `tool_result_compact_keep_n` | `3` | 最近 N 条消息跳过工具结果压缩（保留完整内容） | +| `memory_compact_reserve` | `10000` | 保留近期消息的 token 数，超出部分触发压缩 | +| `compact_ratio` | `0.7` | 压缩阈值比例：`max_input_length × compact_ratio × 0.95` | ---