GitHub - agentscope-ai/ReMe: ReMe: Memory Management Kit for Agents

Memory Management Kit for Agents, Remember Me, Refine Me.
⭐ Love ReMe? Star the repo to help more builders discover memory-first agents.

English | 简体中文

ReMe provides AI agents with a unified memory system—enabling the ability to extract, reuse, and share memories across users, tasks, and agents.

Personal Memory + Task Memory + Tool Memory = Agent Memory

Personal memory helps "understand user preferences", task memory helps agents "perform better", and tool memory enables "smarter tool usage".

🚀 Why Teams Choose ReMe

Ship smarter agents faster: Plug-and-play memory primitives with configurable pipelines.
Amplify success rates: Validated lifts up to +15% on tool usage and +9.7% on multi-turn tasks (see Experiments).
Scale with confidence: Unified memory across users, tasks, and tools—no more babysitting embedding hacks.
Deploy anywhere: HTTP server, MCP service, or direct Python import—same config, same results.
Team-ready workflows: Pre-built libraries, audit trails, and guideline generation keep agents accountable.

Quick win: Try the Quick Start below, then drop a ⭐ if ReMe saves you tokens, time, or both.

✨ Architecture Design

ReMe integrates three complementary memory capabilities:

🧠 Task Memory/Experience

Procedural knowledge reused across agents

Success Pattern Recognition: Identify effective strategies and understand their underlying principles
Failure Analysis Learning: Learn from mistakes and avoid repeating the same issues
Comparative Patterns: Different sampling trajectories provide more valuable memories through comparison
Validation Patterns: Confirm the effectiveness of extracted memories through validation modules

Learn more about how to use task memory from task memory

👤 Personal Memory

Contextualized memory for specific users

Individual Preferences: User habits, preferences, and interaction styles
Contextual Adaptation: Intelligent memory management based on time and context
Progressive Learning: Gradually build deep understanding through long-term interaction
Time Awareness: Time sensitivity in both retrieval and integration

Learn more about how to use personal memory from personal memory

🔧 Tool Memory

Data-driven tool selection and usage optimization

Historical Performance Tracking: Success rates, execution times, and token costs from real usage
LLM-as-Judge Evaluation: Qualitative insights on why tools succeed or fail
Parameter Optimization: Learn optimal parameter configurations from successful calls
Dynamic Guidelines: Transform static tool descriptions into living, learned manuals

Learn more about how to use tool memory from tool memory

📰 Latest Updates

[2025-10] 🚀 Direct Python import support: use from reme_ai import ReMeApp without HTTP/MCP service
[2025-10] 🔧 Tool Memory: data-driven tool selection and parameter optimization (Guide)
[2025-09] 🎉 Async operations support, integrated into agentscope-runtime
[2025-09] 🎉 Task memory and personal memory integration
[2025-09] 🧪 Validated effectiveness in appworld, bfcl(v3), and frozenlake (Experiments)
[2025-08] 🚀 MCP protocol support (Quick Start)
[2025-06] 🚀 Multiple backend vector storage (Elasticsearch & ChromaDB) (Guide)
[2024-09] 🧠 Personalized and time-aware memory storage

🛠️ Installation

Install from PyPI (Recommended)

pip install reme-ai

Install from Source

git clone https://github.com/agentscope-ai/ReMe.git
cd ReMe
pip install .

Environment Configuration

Copy example.env to .env and modify the corresponding parameters:

FLOW_LLM_API_KEY=sk-xxxx
FLOW_LLM_BASE_URL=https://xxxx/v1
FLOW_EMBEDDING_API_KEY=sk-xxxx
FLOW_EMBEDDING_BASE_URL=https://xxxx/v1

🚀 Quick Start

HTTP Service Startup

reme \
  backend=http \
  http.port=8002 \
  llm.default.model_name=qwen3-30b-a3b-thinking-2507 \
  embedding_model.default.model_name=text-embedding-v4 \
  vector_store.default.backend=local

MCP Server Support

reme \
  backend=mcp \
  mcp.transport=stdio \
  llm.default.model_name=qwen3-30b-a3b-thinking-2507 \
  embedding_model.default.model_name=text-embedding-v4 \
  vector_store.default.backend=local

Core API Usage

Task Memory Management

import requests

# Experience Summarizer: Learn from execution trajectories
response = requests.post("http://localhost:8002/summary_task_memory", json={
    "workspace_id": "task_workspace",
    "trajectories": [
        {"messages": [{"role": "user", "content": "Help me create a project plan"}], "score": 1.0}
    ]
})

# Retriever: Get relevant memories
response = requests.post("http://localhost:8002/retrieve_task_memory", json={
    "workspace_id": "task_workspace",
    "query": "How to efficiently manage project progress?",
    "top_k": 1
})

Python import version

import asyncio
from reme_ai import ReMeApp

async def main():
    async with ReMeApp(
        "llm.default.model_name=qwen3-30b-a3b-thinking-2507",
        "embedding_model.default.model_name=text-embedding-v4",
        "vector_store.default.backend=memory"
    ) as app:
        # Experience Summarizer: Learn from execution trajectories
        result = await app.async_execute(
            name="summary_task_memory",
            workspace_id="task_workspace",
            trajectories=[
                {
                    "messages": [
                        {"role": "user", "content": "Help me create a project plan"}
                    ],
                    "score": 1.0
                }
            ]
        )
        print(result)

        # Retriever: Get relevant memories
        result = await app.async_execute(
            name="retrieve_task_memory",
            workspace_id="task_workspace",
            query="How to efficiently manage project progress?",
            top_k=1
        )
        print(result)

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

curl version

# Experience Summarizer: Learn from execution trajectories
curl -X POST http://localhost:8002/summary_task_memory \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "task_workspace",
    "trajectories": [
      {"messages": [{"role": "user", "content": "Help me create a project plan"}], "score": 1.0}
    ]
  }'

# Retriever: Get relevant memories
curl -X POST http://localhost:8002/retrieve_task_memory \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "task_workspace",
    "query": "How to efficiently manage project progress?",
    "top_k": 1
  }'

Node.js version

// Experience Summarizer: Learn from execution trajectories
fetch("http://localhost:8002/summary_task_memory", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    workspace_id: "task_workspace",
    trajectories: [
      {messages: [{role: "user", content: "Help me create a project plan"}], score: 1.0}
    ]
  })
})
.then(response => response.json())
.then(data => console.log(data));

// Retriever: Get relevant memories
fetch("http://localhost:8002/retrieve_task_memory", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    workspace_id: "task_workspace",
    query: "How to efficiently manage project progress?",
    top_k: 1
  })
})
.then(response => response.json())
.then(data => console.log(data));

Personal Memory Management

# Memory Integration: Learn from user interactions
response = requests.post("http://localhost:8002/summary_personal_memory", json={
    "workspace_id": "task_workspace",
    "trajectories": [
        {"messages":
            [
                {"role": "user", "content": "I like to drink coffee while working in the morning"},
                {"role": "assistant",
                 "content": "I understand, you prefer to start your workday with coffee to stay energized"}
            ]
        }
    ]
})

# Memory Retrieval: Get personal memory fragments
response = requests.post("http://localhost:8002/retrieve_personal_memory", json={
    "workspace_id": "task_workspace",
    "query": "What are the user's work habits?",
    "top_k": 5
})

Python import version

import asyncio
from reme_ai import ReMeApp

async def main():
    async with ReMeApp(
        "llm.default.model_name=qwen3-30b-a3b-thinking-2507",
        "embedding_model.default.model_name=text-embedding-v4",
        "vector_store.default.backend=memory"
    ) as app:
        # Memory Integration: Learn from user interactions
        result = await app.async_execute(
            name="summary_personal_memory",
            workspace_id="task_workspace",
            trajectories=[
                {
                    "messages": [
                        {"role": "user", "content": "I like to drink coffee while working in the morning"},
                        {"role": "assistant",
                         "content": "I understand, you prefer to start your workday with coffee to stay energized"}
                    ]
                }
            ]
        )
        print(result)

        # Memory Retrieval: Get personal memory fragments
        result = await app.async_execute(
            name="retrieve_personal_memory",
            workspace_id="task_workspace",
            query="What are the user's work habits?",
            top_k=5
        )
        print(result)

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

curl version

# Memory Integration: Learn from user interactions
curl -X POST http://localhost:8002/summary_personal_memory \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "task_workspace",
    "trajectories": [
      {"messages": [
        {"role": "user", "content": "I like to drink coffee while working in the morning"},
        {"role": "assistant", "content": "I understand, you prefer to start your workday with coffee to stay energized"}
      ]}
    ]
  }'

# Memory Retrieval: Get personal memory fragments
curl -X POST http://localhost:8002/retrieve_personal_memory \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "task_workspace",
    "query": "What are the users work habits?",
    "top_k": 5
  }'

Node.js version

// Memory Integration: Learn from user interactions
fetch("http://localhost:8002/summary_personal_memory", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    workspace_id: "task_workspace",
    trajectories: [
      {messages: [
        {role: "user", content: "I like to drink coffee while working in the morning"},
        {role: "assistant", content: "I understand, you prefer to start your workday with coffee to stay energized"}
      ]}
    ]
  })
})
.then(response => response.json())
.then(data => console.log(data));

// Memory Retrieval: Get personal memory fragments
fetch("http://localhost:8002/retrieve_personal_memory", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    workspace_id: "task_workspace",
    query: "What are the user's work habits?",
    top_k: 5
  })
})
.then(response => response.json())
.then(data => console.log(data));

Tool Memory Management

import requests

# Record tool execution results
response = requests.post("http://localhost:8002/add_tool_call_result", json={
    "workspace_id": "tool_workspace",
    "tool_call_results": [
        {
            "create_time": "2025-10-21 10:30:00",
            "tool_name": "web_search",
            "input": {"query": "Python asyncio tutorial", "max_results": 10},
            "output": "Found 10 relevant results...",
            "token_cost": 150,
            "success": True,
            "time_cost": 2.3
        }
    ]
})

# Generate usage guidelines from history
response = requests.post("http://localhost:8002/summary_tool_memory", json={
    "workspace_id": "tool_workspace",
    "tool_names": "web_search"
})

# Retrieve tool guidelines before use
response = requests.post("http://localhost:8002/retrieve_tool_memory", json={
    "workspace_id": "tool_workspace",
    "tool_names": "web_search"
})

Python import version

import asyncio
from reme_ai import ReMeApp

async def main():
    async with ReMeApp(
        "llm.default.model_name=qwen3-30b-a3b-thinking-2507",
        "embedding_model.default.model_name=text-embedding-v4",
        "vector_store.default.backend=memory"
    ) as app:
        # Record tool execution results
        result = await app.async_execute(
            name="add_tool_call_result",
            workspace_id="tool_workspace",
            tool_call_results=[
                {
                    "create_time": "2025-10-21 10:30:00",
                    "tool_name": "web_search",
                    "input": {"query": "Python asyncio tutorial", "max_results": 10},
                    "output": "Found 10 relevant results...",
                    "token_cost": 150,
                    "success": True,
                    "time_cost": 2.3
                }
            ]
        )
        print(result)

        # Generate usage guidelines from history
        result = await app.async_execute(
            name="summary_tool_memory",
            workspace_id="tool_workspace",
            tool_names="web_search"
        )
        print(result)

        # Retrieve tool guidelines before use
        result = await app.async_execute(
            name="retrieve_tool_memory",
            workspace_id="tool_workspace",
            tool_names="web_search"
        )
        print(result)

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

curl version

# Record tool execution results
curl -X POST http://localhost:8002/add_tool_call_result \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "tool_workspace",
    "tool_call_results": [
      {
        "create_time": "2025-10-21 10:30:00",
        "tool_name": "web_search",
        "input": {"query": "Python asyncio tutorial", "max_results": 10},
        "output": "Found 10 relevant results...",
        "token_cost": 150,
        "success": true,
        "time_cost": 2.3
      }
    ]
  }'

# Generate usage guidelines from history
curl -X POST http://localhost:8002/summary_tool_memory \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "tool_workspace",
    "tool_names": "web_search"
  }'

# Retrieve tool guidelines before use
curl -X POST http://localhost:8002/retrieve_tool_memory \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "tool_workspace",
    "tool_names": "web_search"
  }'

Node.js version

// Record tool execution results
fetch("http://localhost:8002/add_tool_call_result", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    workspace_id: "tool_workspace",
    tool_call_results: [
      {
        create_time: "2025-10-21 10:30:00",
        tool_name: "web_search",
        input: {query: "Python asyncio tutorial", max_results: 10},
        output: "Found 10 relevant results...",
        token_cost: 150,
        success: true,
        time_cost: 2.3
      }
    ]
  })
})
.then(response => response.json())
.then(data => console.log(data));

// Generate usage guidelines from history
fetch("http://localhost:8002/summary_tool_memory", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    workspace_id: "tool_workspace",
    tool_names: "web_search"
  })
})
.then(response => response.json())
.then(data => console.log(data));

// Retrieve tool guidelines before use
fetch("http://localhost:8002/retrieve_tool_memory", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    workspace_id: "tool_workspace",
    tool_names: "web_search"
  })
})
.then(response => response.json())
.then(data => console.log(data));

📦 Ready-to-Use Memories

ReMe provides pre-built memories that agents can immediately use with verified best practices:

Available Memories

appworld.jsonl: Memory for Appworld agent interactions, covering complex task planning and execution patterns
bfcl_v3.jsonl: Working memory for BFCL tool calls

Quick Usage

# Load pre-built memories
response = requests.post("http://localhost:8002/vector_store", json={
    "workspace_id": "appworld",
    "action": "load",
    "path": "./docs/library/"
})

# Query relevant memories
response = requests.post("http://localhost:8002/retrieve_task_memory", json={
    "workspace_id": "appworld",
    "query": "How to navigate to settings and update user profile?",
    "top_k": 1
})

Python import version

import asyncio
from reme_ai import ReMeApp

async def main():
    async with ReMeApp(
        "llm.default.model_name=qwen3-30b-a3b-thinking-2507",
        "embedding_model.default.model_name=text-embedding-v4",
        "vector_store.default.backend=memory"
    ) as app:
        # Load pre-built memories
        result = await app.async_execute(
            name="vector_store",
            workspace_id="appworld",
            action="load",
            path="./docs/library/"
        )
        print(result)

        # Query relevant memories
        result = await app.async_execute(
            name="retrieve_task_memory",
            workspace_id="appworld",
            query="How to navigate to settings and update user profile?",
            top_k=1
        )
        print(result)

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

🧪 Experiments

🌍 Appworld Experiment

We tested ReMe on Appworld using qwen3-8b:

Method	pass@1	pass@2	pass@4
without ReMe	0.083	0.140	0.228
with ReMe	0.109 (+2.6%)	0.175 (+3.5%)	0.281 (+5.3%)

Pass@K measures the probability that at least one of the K generated samples successfully completes the task ( score=1). The current experiment uses an internal AppWorld environment, which may have slight differences.

You can find more details on reproducing the experiment in quickstart.md.

🧊 Frozenlake Experiment

without ReMe	with ReMe

We tested on 100 random frozenlake maps using qwen3-8b:

Method	pass rate
without ReMe	0.66
with ReMe	0.72 (+6.0%)

You can find more details on reproducing the experiment in quickstart.md.

🔧 BFCL-V3 Experiment

We tested ReMe on BFCL-V3 multi-turn-base (randomly split 50train/150val) using qwen3-8b:

Method	pass@1	pass@2	pass@4
without ReMe	0.2472	0.2733	0.2922
with ReMe	0.3061 (+5.89%)	0.3500 (+7.67%)	0.3888 (+9.66%)

🛠️ Tool Memory Benchmark

We evaluated Tool Memory effectiveness using a controlled benchmark with three mock search tools using Qwen3-30B-Instruct:

Scenario	Avg Score	Improvement
Train (No Memory)	0.650	-
Test (No Memory)	0.672	Baseline
Test (With Memory)	0.772	+14.88%

Key Findings:

Tool Memory enables data-driven tool selection based on historical performance
Success rates improved by ~15% with learned parameter configurations

You can find more details in tool_bench.md and the implementation at run_reme_tool_bench.py.

📚 Resources

Quick Start: Get started quickly with practical examples
- Tool Memory Demo: Complete lifecycle demonstration of tool memory
- Tool Memory Benchmark: Evaluate tool memory effectiveness
Vector Storage Setup: Configure local/vector databases and usage
MCP Guide: Create MCP services
Personal Memory, Task Memory & Tool Memory: Operators used in personal memory, task memory and tool memory. You can modify the config to customize the pipelines.
Example Collection: Real use cases and best practices

⭐ Support & Community

Star & Watch: Stars surface ReMe to more agent builders; watching keeps you updated on new releases.
Share your wins: Open an issue or discussion with what ReMe unlocked for your agents—we love showcasing community builds.
Need a feature? File a request and we’ll help shape it together.

🤝 Contribution

We believe the best memory systems come from collective wisdom. Contributions welcome 👉Guide:

Code Contributions

New operation and tool development
Backend implementation and optimization
API enhancements and new endpoints

Documentation Improvements

Usage examples and tutorials
Best practice guides

📄 Citation

@software{AgentscopeReMe2025,
  title = {AgentscopeReMe: Memory Management Kit for Agents},
  author = {Li Yu, Jiaji Deng, Zouying Cao},
  url = {https://reme.agentscope.io},
  year = {2025}
}

⚖️ License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 372 Commits
.github/workflows		.github/workflows
cookbook		cookbook
docs		docs
reme_ai		reme_ai
test		test
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
LICENSE		LICENSE
README.md		README.md
README_zh.md		README_zh.md
example.env		example.env
pyproject.toml		pyproject.toml

License

agentscope-ai/ReMe

Folders and files

Latest commit

History

Repository files navigation

🚀 Why Teams Choose ReMe

✨ Architecture Design

🧠 Task Memory/Experience

👤 Personal Memory

🔧 Tool Memory

📰 Latest Updates

🛠️ Installation

Install from PyPI (Recommended)

Install from Source

Environment Configuration

🚀 Quick Start

HTTP Service Startup

MCP Server Support

Core API Usage

Task Memory Management

Personal Memory Management

Tool Memory Management

📦 Ready-to-Use Memories

Available Memories

Quick Usage

🧪 Experiments

🌍 Appworld Experiment

🧊 Frozenlake Experiment

🔧 BFCL-V3 Experiment

🛠️ Tool Memory Benchmark

📚 Resources

⭐ Support & Community

🤝 Contribution

Code Contributions

Documentation Improvements

📄 Citation

⚖️ License

Star History

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors 7

Uh oh!

Languages

Packages