| 类别 | 方法 | 功能 | 关键组件 |
|---|
| 上下文管理 | 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 混合检索 |
| 会话内存 | get_in_memory_memory | 💾 创建会话内存实例 | 返回 ReMeInMemoryMemory，自动配置 dialog_path 实现对话持久化 |
await_summary_tasks | ⏳ 等待异步摘要任务 | 阻塞等待所有后台摘要任务完成 |
| - | 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},
enable_load_env=True,
)
await reme.start()
messages = [...] # 对话消息列表
# 1. 检查上下文大小（Token 计数，判断是否需要压缩）
messages_to_compact, messages_to_keep, is_valid = await reme.check_context(
messages=messages,
memory_compact_threshold=90000, # 触发压缩的阈值（tokens）
memory_compact_reserve=10000, # 保留的近期消息 token 数
)
# 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. 压缩超长工具输出（防止工具结果撑爆上下文）
messages = await reme.compact_tool_result(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. 将重要记忆写入文件（摘要写入 memory/YYYY-MM-DD.md）
summary_result = await reme.summary_memory(
messages=messages,
language="zh",
)
# 6. 语义搜索记忆（向量 + BM25 混合检索）
result = await reme.memory_search(query="Python 版本偏好", max_results=5)
# 7. 创建会话内存实例（管理单次对话的上下文）
from reme.memory.file_based.reme_in_memory_memory import ReMeInMemoryMemory
memory = reme.get_in_memory_memory() # 自动配置 dialog_path
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']}")
# 8. 标记消息为压缩状态（自动持久化到 dialog/YYYY-MM-DD.jsonl）
# await memory.mark_messages_compressed(messages_to_compact)
# 关闭 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 记忆系统架构
#### 上下文数据结构
```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
graph LR
Agent[Agent] -->|每轮推理前| Hook[pre_reasoning_hook]
Hook --> TC[compact_tool_result
