| 类别 | 方法 | 功能 | 关键组件 |
|---|
| 上下文管理 | check_context | 📊 检查上下文大小 | ContextChecker — 检查上下文是否超出阈值并拆分 Message |
compact_memory | 📦 压缩历史对话为摘要 | Compactor — ReActAgent 生成结构化上下文摘要 |
compact_tool_result | ✂️ 压缩超长工具输出 | ToolResultCompactor — 截断超长的工具调用结果并转存到 tool_result/，消息中保留文件引用 |
pre_reasoning_hook | 🔄 推理前预处理钩子 | compact_tool_result + check_context + compact_memory + summary_memory(async) |
| 长期记忆 | summary_memory | 📝 将重要记忆写入文件 | Summarizer — ReActAgent + 文件工具（read / write / edit） |
memory_search | 🔍 语义搜索记忆 | MemorySearch — 向量 + BM25 混合检索 |
| - | start | 🚀 启动记忆系统 | 初始化文件存储、文件监控、Embedding 缓存；清理过期工具结果文件 |
| - | close | 📕 关闭并清理 | 清理工具结果文件、停止文件监控、保存 Embedding 缓存 |
---
### 🚀 快速开始
#### 安装
**从源码安装：**
```bash
git clone https://github.com/agentscope-ai/ReMe.git
cd ReMe
pip install -e ".[light]"
```
**更新到最新版本：**
```bash
git pull
pip install -e ".[light]"
```
#### 环境变量
`ReMeLight` 环境变量配置 Embedding 和存储后端
| Variable | Description | Example |
|----------------------|-------------------------|-----------------------------------------------------|
| `LLM_API_KEY` | LLM API key | `sk-xxx` |
| `LLM_BASE_URL` | LLM base URL | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
| `EMBEDDING_API_KEY` | Embedding API key (可选) | `sk-xxx` |
| `EMBEDDING_BASE_URL` | Embedding base URL (可选) | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
#### Python 使用
```python
import asyncio
from reme.reme_light import ReMeLight
async def main():
# 初始化 ReMeLight
reme = ReMeLight(
default_as_llm_config={"model_name": "qwen3.5-35b-a3b"},
# default_embedding_model_config={"model_name": "text-embedding-v4"},
default_file_store_config={"fts_enabled": True, "vector_enabled": False},
)
await reme.start()
messages = [...] # 对话消息列表
# 1. 压缩超长工具输出（防止工具结果撑爆上下文）
messages = await reme.compact_tool_result(messages)
# 2. 将历史对话压缩为结构化摘要（可传入上轮摘要，实现增量更新）
summary = await reme.compact_memory(
messages=messages,
previous_summary="",
max_input_length=128000, # 模型上下文窗口（tokens）
compact_ratio=0.7, # 达到 max_input_length * 0.7 时触发压缩
language="zh", # 摘要语言（zh / ""）
)
# 3. 后台异步提交摘要任务（不阻塞对话，摘要写入 memory/YYYY-MM-DD.md）
reme.add_async_summary_task(messages=messages)
# 4. 推理前预处理钩子（自动压缩工具结果 + 生成摘要）
processed_messages, compressed_summary = await reme.pre_reasoning_hook(
messages=messages,
system_prompt="你是一个有帮助的 AI 助手。",
compressed_summary="",
max_input_length=128000,
compact_ratio=0.7,
memory_compact_reserve=10000,
enable_tool_result_compact=True,
tool_result_compact_keep_n=3,
)
# 5. 语义搜索记忆（向量 + BM25 混合检索）
result = await reme.memory_search(query="Python 版本偏好", max_results=5)
# 6. 创建会话内存实例（管理单次对话的上下文）
from reme.memory.file_based.reme_in_memory_memory import ReMeInMemoryMemory
memory = ReMeInMemoryMemory()
for msg in messages:
await memory.add(msg)
token_stats = await memory.estimate_tokens(max_input_length=128000)
print(f"当前上下文使用率: {token_stats['context_usage_ratio']:.1f}%")
print(f"消息 Token 数: {token_stats['messages_tokens']}")
print(f"预估总 Token 数: {token_stats['estimated_tokens']}")
# 7. 关闭前等待后台任务完成
summary_result = await reme.await_summary_tasks()
# 关闭 ReMeLight
await reme.close()
if __name__ == "__main__":
asyncio.run(main())
```
> 📂 完整示例代码：[test_reme_light.py](tests/light/test_reme_light.py)
> 📋 运行结果示例：[test_reme_light_log.txt](tests/light/test_reme_light_log.txt)（223,838 tokens → 1,105 tokens，压缩率99.5%）
### 基于文件的 ReMeLight 记忆系统架构
[CoPaw MemoryManager](https://github.com/agentscope-ai/CoPaw/blob/main/src/copaw/agents/memory/memory_manager.py) 继承
`ReMeLight`，将记忆能力集成到 Agent 推理流程中：
```mermaid
graph LR
Agent[Agent] -->|每轮推理前| Hook[pre_reasoning_hook]
Hook --> TC[compact_tool_result
