• 个人助理：为像 CoPaw 这样的智能体提供长期记忆，记住用户偏好和对话历史。
• 编程助手：记录代码风格偏好和项目上下文，在不同会话间保持一致的开发体验。
• 客户服务机器人：跟踪用户问题历史和偏好设置，提供个性化服务。
• 任务自动化：从历史任务中学习成功/失败模式，

🚀 快速开始

安装

从源码安装：

git clone https://github.com/agentscope-ai/ReMe.git
cd ReMe
pip install -e ".[light]"

更新到最新版本：

git pull
pip install -e ".[light]"

环境变量

ReMeLight 使用环境变量来配置嵌入模型（embedding model）和存储后端：

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. 创建会话内记忆实例（管理单个对话的上下文）
    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 📋 示例运行日志: test_reme_light_log.txt (223,838 tokens → 1,105 tokens, 99.5% 压缩率)

基于文件的 ReMeLight 内存系统架构

上下文数据结构

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 继承了 ReMeLight 并将其内存能力集成到代理推理循环中：

graph LR
    Agent[Agent] -->|每次推理步骤之前| Hook[pre_reasoning_hook]
    Hook --> TC[compact_tool_result<br>压缩工具输出]
    TC --> CC[check_context<br>Token 计数]
    CC -->|超出限制| CM[compact_memory<br>生成摘要]
    CC -->|超出限制| SM[summary_memory<br>异步持久化]
    SM -->|ReAct + FileIO| Files[memory/*.md]
    CC -->|超出限制| MMC[mark_messages_compressed<br>持久化原始对话]
    MMC --> Dialog[dialog/*.jsonl]
    Agent -->|显式调用| Search[memory_search<br>向量+BM25]
    Agent -->|会话内| InMem[ReMeInMemoryMemory<br>Token 感知内存]
    InMem -->|压缩/清除| Dialog
    Files -.->|FileWatcher| Store[(FileStore<br>向量+FTS 索引)]
    Search --> Store

1. check_context — 上下文检查

ContextChecker 使用 token 计数来判断上下文是否超过阈值，并自动将消息分为“待压缩”组和“保留”组。

graph LR
    M[messages] --> H[AsMsgHandler<br>Token 计数]
    H --> C{total > threshold?}
    C -->|No| K[返回所有消息]
    C -->|Yes| S[从尾部保留<br>reserve tokens]
    S --> CP[messages_to_compact<br>较早的消息]
    S --> KP[messages_to_keep<br>最近的消息]
    S --> V{is_valid<br>工具调用对齐？}

• 核心逻辑: 从尾部保留 reserve 个 token；其余标记为待压缩消息。
• 完整性保证: 保留完整的用户-助手轮次以及 tool_use/tool_result 对，不拆分它们。

2. compact_memory — 对话压缩

Compactor 使用 ReActAgent 将对话历史压缩为结构化上下文摘要。

graph LR
    M[messages] --> H[AsMsgHandler<br>format_msgs_to_str]
    H --> A[ReActAgent<br>reme_compactor]
    P[previous_summary] -->|增量更新| A
    A --> S[结构化摘要<br>目标/进展/决策...]

摘要结构（上下文检查点）：

• 增量更新：当提供 previous_summary 时，新对话将合并到现有摘要中。
• 思维增强：通过设置 add_thinking_block=True（默认值），在生成摘要前增加推理步骤以提高质量。

3. summary_memory — 持久化记忆

Summarizer 使用 ReAct + 文件工具 模式，使 AI 能够决定写什么以及写在哪里。

graph LR
    M[messages] --> A[ReActAgent<br>reme_summarizer]
    A -->|read| R[Read memory/YYYY-MM-DD.md]
    R --> T{Reason: how to merge?}
    T -->|write| W[Overwrite]
    T -->|edit| E[Edit in place]
    W --> F[memory/YYYY-MM-DD.md]
    E --> F

文件工具 (FileIO)：

4. compact_tool_result — 工具结果压缩

ToolResultCompactor 解决了长工具输出导致上下文膨胀的问题。它根据消息是否在 recent_n 窗口内应用两种不同的截断策略：

graph LR
    M[messages] --> B{Within recent_n?}
    B -->|Yes - recent| C[Low truncation recent_max_bytes=100KB<br>Save full content to tool_result/uuid.txt<br>Hint: 'Read from line N']
    B -->|No - old| D[High truncation old_max_bytes=3KB<br>Reference existing file<br>More aggressive truncation]
    C --> E[cleanup_expired_files<br>Delete expired files]
    D --> E

• 自动清理：过期文件（超过 retention_days 的文件）会在 start / close / compact_tool_result 期间自动删除。

5. memory_search — 记忆检索

MemorySearch 提供 向量 + BM25 混合检索。

graph LR
    Q[query] --> E[Embedding<br>Vectorization]
    E --> V[vector_search<br>Semantic similarity]
    Q --> B[BM25<br>Keyword matching]
    V -->|" weight: 0.7 "| M[Deduplicate + weighted merge]
    B -->|" weight: 0.3 "| M
    M --> F[min_score filter]
    F --> R[Top-N results]

• 融合机制：向量权重 0.7 + BM25 权重 0.3 —— 平衡语义相似性和精确匹配。

6. ReMeInMemoryMemory — 会话内记忆

ReMeInMemoryMemory 扩展了 AgentScope 的 InMemoryMemory，提供基于 token 的记忆管理以及原始对话持久化。

graph LR
    C[content] --> G[get_memory<br>exclude_mark=COMPRESSED]
    G --> F[Filter out compressed messages]
    F --> P{prepend_summary?}
    P -->|Yes| S[Prepend previous summary]
    S --> O[Output messages]
    P -->|No| O
    M[mark_messages_compressed] --> D[Persist to dialog/YYYY-MM-DD.jsonl]
    D --> R[Remove from memory]

原始对话持久化：当消息被压缩或清除时，它们会自动保存到 {dialog_path}/{date}.jsonl，每行一条 JSON 格式的消息。

7. pre_reasoning_hook — 推理前处理

这是一个统一的入口点，将上述所有组件连接在一起，并在每次推理步骤之前自动管理上下文。

graph LR
    M[messages] --> TC[compact_tool_result<br>Compact long tool outputs]
    TC --> CC[check_context<br>Compute remaining space]
    CC --> D{messages_to_compact<br>Non-empty?}
    D -->|No| K[Return original messages + summary]
    D -->|Yes| V{is_valid?}
    V -->|No| K
    V -->|Yes| CM[compact_memory<br>Sync summary generation]
    V -->|Yes| SM[add_async_summary_task<br>Async persistence]
    CM --> R[Return messages_to_keep + new summary]

执行流程：

1. compact_tool_result — 对所有消息（最近的 tool_result_compact_keep_n 条除外）压缩长工具输出。
2. check_context — 检查上下文是否超出限制（剩余空间 = 阈值减去系统提示和压缩摘要所用的 token 数）。
3. compact_memory — 生成紧凑的摘要（同步），追加到 compact_summary 中。
4. summary_memory — 将记忆持久化到 memory/*.md 文件中（异步后台运行，非阻塞）。

🗃️ 基于向量的记忆系统

ReMe Vector Based 是基于向量的记忆系统的核心类。它管理三种类型的记忆：

核心功能

安装与环境变量

安装和环境配置与 ReMeLight 相同。 API 密钥通过环境变量配置，并可以存储在项目根目录下的 .env 文件中。

Python 使用示例

import asyncio

from reme import ReMe


async def main():
    # 初始化 ReMe
    reme = ReMe(
        working_dir=".reme",
        default_llm_config={
            "backend": "openai",
            "model_name": "qwen3.5-plus",
        },
        default_embedding_model_config={
            "backend": "openai",
            "model_name": "text-embedding-v4",
            "dimensions": 1024,
        },
        default_vector_store_config={
            "backend": "local",  # 支持 local/chroma/qdrant/elasticsearch
        },
    )
    await reme.start()

    messages = [
        {"role": "user", "content": "Help me write a Python script", "time_created": "2026-02-28 10:00:00"},
        {"role": "assistant", "content": "Sure, I'll help you with that.", "time_created": "2026-02-28 10:00:05"},
    ]

    # 1. 从对话中总结记忆（自动提取用户偏好、任务经验等）
    result = await reme.summarize_memory(
        messages=messages,
        user_name="alice",  # 个人记忆
        # task_name="code_writing",  # 程序记忆
    )
    print(f"Summary result: {result}")

    # 2. 检索相关记忆
    memories = await reme.retrieve_memory(
        query="Python programming",
        user_name="alice",
        # task_name="code_writing",
    )
    print(f"Retrieved memories: {memories}")

    # 3. 手动添加记忆
    memory_node = await reme.add_memory(
        memory_content="The user prefers concise code style.",
        user_name="alice",
    )
    print(f"Added memory: {memory_node}")
    memory_id = memory_node.memory_id

    # 4. 通过 ID 获取单个记忆
    fetched_memory = await reme.get_memory(memory_id=memory_id)
    print(f"Fetched memory: {fetched_memory}")

    # 5. 更新记忆内容
    updated_memory = await reme.update_memory(
        memory_id=memory_id,
        user_name="alice",
        memory_content="The user prefers concise code with comments.",
    )
    print(f"Updated memory: {updated_memory}")

    # 6. 列出用户的全部记忆（支持过滤和排序）
    all_memories = await reme.list_memory(
        user_name="alice",
        limit=10,
        sort_key="time_created",
        reverse=True,
    )
    print(f"User memory list: {all_memories}")

    # 7. 删除特定记忆
    await reme.delete_memory(memory_id=memory_id)
    print(f"Deleted memory: {memory_id}")

    # 8. 删除所有记忆（请谨慎使用）
    # await reme.delete_all()

    await reme.close()


if __name__ == "__main__":
    asyncio.run(main())

技术架构

graph LR
    User[用户 / 代理] --> ReMe[基于向量的 ReMe]
    ReMe --> Summarize[总结记忆]
    ReMe --> Retrieve[检索记忆]
    ReMe --> CRUD[CRUD 操作]
    Summarize --> PersonalSum[个人总结器]
    Summarize --> ProceduralSum[程序总结器]
    Summarize --> ToolSum[工具总结器]
    Retrieve --> PersonalRet[个人检索器]
    Retrieve --> ProceduralRet[程序检索器]
    Retrieve --> ToolRet[工具检索器]
    PersonalSum --> VectorStore[向量数据库]
    ProceduralSum --> VectorStore
    ToolSum --> VectorStore
    PersonalRet --> VectorStore
    ProceduralRet --> VectorStore
    ToolRet --> VectorStore

实验结果

评估基于两个基准测试：LoCoMo 和 HaluMem。实验设置如下：

1. ReMe 主干模型：如每个表格中指定。
2. 评估协议：遵循 MemOS 的 LLM-as-a-Judge 方法——每个答案由 GPT-4o-mini 进行评分。

基线结果尽可能在一致的设置下从各自论文中复现。

LoCoMo

HaluMem

🧪 程序记忆论文

我们的程序（任务）记忆论文已在 arXiv 上发布。

🌍 Appworld 基准测试

我们在 Appworld 环境中使用 Qwen3-8B（非思考模式）评估 ReMe：

Pass@K 衡量的是 K 个生成的候选者中至少有一个成功完成任务（得分=1）的概率。 当前实验使用的是内部 AppWorld 环境，可能与公开版本略有不同。

有关如何重现实验的更多详细信息，请参阅 quickstart.md。

🔧 BFCL-V3 基准测试

我们在 BFCL-V3 多轮任务（随机拆分 50 训练 / 150 验证）上使用 Qwen3-8B（思考模式）评估 ReMe：

有关如何重现实验的更多详细信息，请参阅 quickstart.md。

⭐ 社区与支持

• Star & Watch：加星有助于更多代理开发者发现 ReMe；关注可以让你及时了解新版本和功能。
• 分享你的成果：在 Issues 或 Discussions 中分享 ReMe 如何增强你的代理——我们很乐意展示优秀的社区用例。
• 需要新功能？ 提交功能请求；我们将与社区一起发展 ReMe。
• 代码贡献：欢迎任何形式的贡献。请参阅 贡献指南。
• 致谢：感谢 OpenClaw、Mem0、MemU 和 CoPaw 等优秀开源项目提供的灵感和支持。

贡献者

感谢所有为 ReMe 做出贡献的人：

📄 引用

@software{AgentscopeReMe2025,
  title = {AgentscopeReMe: Memory Management Kit for Agents},
  author = {ReMe Team},
  url = {https://reme.agentscope.io},
  year = {2025}
}

⚖️ 许可证

本项目在 Apache License 2.0 下开源。详见 LICENSE。

🤔 为什么选择 ReMe？

ReMe 代表 Remember Me（记住我）和 Refine Me（优化我），象征着我们帮助 AI 代理“记住”用户并通过交互“优化”自身的目标。我们希望 ReMe 不仅仅是一个冰冷的记忆模块，而是一个真正帮助代理理解用户、积累经验并不断进化的伙伴。

📈 Star 历史