A memory management toolkit for AI agents ŌĆö Remember Me, Refine Me.
For legacy versions, see 0.2.x Documentation
¤¦? ReMe is a memory management framework built for AI agents, offering both file-based and vector-based memory systems.
It addresses two core problems of agent memory: limited context windows (early information gets truncated or lost during long conversations) and stateless sessions (new conversations cannot inherit history and always start from scratch).
ReMe gives agents real memory ŌĆö old conversations are automatically condensed, important information is persisted, and the next conversation can recall it automatically.
Memory as files, files as memory
Treat memory as files ŌĆö readable, editable, and portable.
CoPaw implements long-term memory and context management by inheriting
ReMeLight.
| Traditional Memory Systems | File-Based ReMe |
|---|---|
| ¤Śä’ĖÅ Database storage | ¤ōØ Markdown files |
| ¤öÆ Opaque | ¤æĆ Read anytime |
| ŌØī Hard to modify | ԣŒĖÅ Edit directly |
| ¤Ü½ Hard to migrate | ¤ō” Copy to migrate |
working_dir/
Ōö£ŌöĆŌöĆ MEMORY.md # Long-term memory: user preferences, project config, etc.
Ōö£ŌöĆŌöĆ memory/
Ōöé ŌööŌöĆŌöĆ YYYY-MM-DD.md # Daily summary logs: written automatically after conversation ends
ŌööŌöĆŌöĆ tool_result/ # Cache for oversized tool outputs (auto-managed, auto-cleaned when expired)
ŌööŌöĆŌöĆ <uuid>.txt
ReMeLight is the core class of this memory system, providing complete memory management capabilities for AI Agents:
| Method | Function | Key Components |
|---|---|---|
start |
¤ÜĆ Start memory system | Initialize file store, file watcher, Embedding cache; clean up expired tool result files |
close |
¤ōĢ Close and clean up | Clean tool result files, stop file watcher, save Embedding cache |
compact_memory |
¤ō” Compact history to summary | Compactor ŌĆö ReActAgent generates structured context checkpoint |
summary_memory |
¤ōØ Write important memory to files | Summarizer ŌĆö ReActAgent + file tools (read / write / edit) |
compact_tool_result |
Ō£é’ĖÅ Compact oversized tool output | ToolResultCompactor ŌĆö Truncate and save to tool_result/, keep file reference in message |
memory_search |
¤öŹ Semantic memory search | MemorySearch ŌĆö Vector + BM25 hybrid retrieval |
get_in_memory_memory |
¤Śé’ĖÅ Create in-memory instance | ReMeInMemoryMemory ŌĆö Token-aware memory management, supports compression summary and state serialization |
pip install -e ".[light]"ReMeLight environment variables configure Embedding and storage backend
| 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 (Optional) | sk-xxx |
EMBEDDING_BASE_URL |
Embedding base URL (Optional) | https://dashscope.aliyuncs.com/compatible-mode/v1 |
LLM_MODEL_NAME |
LLM model name | qwen3.5-plus |
import asyncio
from agentscope.message import Msg
from reme.reme_light import ReMeLight
async def main():
reme = ReMeLight(
working_dir=".reme", # Memory file storage directory
max_input_length=128000, # Model context window (tokens)
memory_compact_ratio=0.7, # Trigger compaction when reaching max_input_length * 0.7
language="zh", # Summary language (zh / "")
tool_result_threshold=1000, # Auto-save tool outputs exceeding this character count
retention_days=7, # tool_result/ file retention days
)
await reme.start()
messages = [...]
# 1. Compact oversized tool outputs (prevent tool results from overflowing context)
messages = await reme.compact_tool_result(messages)
# 2. Compact history to structured summary (trigger: context approaching limit), can pass previous summary for incremental update
summary = await reme.compact_memory(messages=messages, previous_summary="")
# 3. Submit async summary task in background (non-blocking, writes to memory/YYYY-MM-DD.md)
reme.add_async_summary_task(messages=messages)
# 4. Semantic memory search (Vector + BM25 hybrid retrieval)
result = await reme.memory_search(query="Python version preference", max_results=5)
# 5. Get in-memory instance (ReMeInMemoryMemory, manages single conversation context) AgentScope InMemoryMemory
memory = reme.get_in_memory_memory()
token_stats = await memory.estimate_tokens()
print(f"Current context usage: {token_stats['context_usage_ratio']:.1f}%")
print(f"Message tokens: {token_stats['messages_tokens']}")
print(f"Estimated total tokens: {token_stats['estimated_tokens']}")
# 6. Wait for background tasks before closing
summary_result = await reme.await_summary_tasks()
# Close ReMeLight
await reme.close()
if __name__ == "__main__":
asyncio.run(main())CoPaw MemoryManager
inherits ReMeLight and integrates memory capabilities into the Agent reasoning flow:
graph TB
CoPaw["CoPaw MemoryManager\n(inherits ReMeLight)"] -->|pre_reasoning hook| Hook[MemoryCompactionHook]
CoPaw --> ReMeLight[ReMeLight]
Hook -->|exceeds threshold| ReMeLight
ReMeLight --> CompactMemory[compact_memory\nHistory compaction]
ReMeLight --> SummaryMemory[summary_memory\nWrite memory to files]
ReMeLight --> CompactToolResult[compact_tool_result\nOversized tool output compaction]
ReMeLight --> MemSearch[memory_search\nSemantic search]
ReMeLight --> InMemory[get_in_memory_memory\nReMeInMemoryMemory]
CompactMemory --> Compactor[Compactor\nReActAgent]
SummaryMemory --> Summarizer[Summarizer\nReActAgent + file tools]
CompactToolResult --> ToolResultCompactor[ToolResultCompactor\nTruncate + save to file]
Summarizer --> FileIO[FileIO\nread / write / edit]
FileIO --> MemoryFiles[memory/YYYY-MM-DD.md]
ToolResultCompactor --> ToolResultFiles[tool_result/*.txt]
MemoryFiles -.->|File change| FileWatcher[Async File Watcher]
FileWatcher -->|Update index| FileStore[Local DB]
MemSearch --> FileStore
Compactor uses ReActAgent to compact history into structured context checkpoints:
| Field | Description |
|---|---|
## Goal |
¤Ä» User's objectives (can be multiple) |
## Constraints |
ŌÜÖ’ĖÅ Constraints and preferences mentioned by user |
## Progress |
¤ōł Completed / in progress / blocked tasks |
## Key Decisions |
¤öæ Decisions made with brief reasons |
## Next Steps |
¤Ś║’ĖÅ Next action plan (ordered list) |
## Critical Context |
¤ōī File paths, function names, error messages, etc. |
Supports incremental updates: when previous_summary is passed, automatically merges new conversation with old
summary, preserving historical progress.
ToolResultCompactor solves context overflow caused by oversized tool outputs (e.g., browser use):
graph LR
A[tool_result message] --> B{Content length > threshold?}
B -->|No| C[Keep as-is]
B -->|Yes| D[Truncate to threshold characters]
D --> E[Write full content to tool_result/uuid.txt]
E --> F[Append file reference path to message]
Expired files (exceeding retention_days) are automatically cleaned up during start / close /
compact_tool_result.
Summarizer uses the ReAct + file tools pattern, letting AI autonomously decide what to write and where:
graph LR
A[Receive conversation] --> B{Think: What's worth recording?}
B --> C[Act: read memory/YYYY-MM-DD.md]
C --> D{Think: How to merge with existing content?}
D --> E[Act: edit to update file]
E --> F{Think: Anything missing?}
F -->|Yes| B
F -->|No| G[Done]
FileIO provides file operation tools:
| Tool | Function | Use case |
|---|---|---|
read |
Read file content (line range) | View existing memory, avoid duplicates |
write |
Overwrite file | Create new memory file or major rewrite |
edit |
Replace after exact match | Append or modify specific sections |
ReMeInMemoryMemory extends AgentScope's InMemoryMemory:
| Feature | Description |
|---|---|
get_memory |
Filter messages by mark, auto-prepend compression summary |
estimate_tokens |
Precisely estimate current context token usage and ratio |
get_history_str |
Generate human-readable conversation summary (with token stats) |
state_dict / load_state_dict |
Support state serialization / deserialization (session persistence) |
mark_messages_compressed |
Mark messages as compressed state |
get_compressed_summary |
Get compressed summary content |
MemorySearch provides vector + BM25 hybrid retrieval:
| Retrieval | Strength | Weakness |
|---|---|---|
| Vector semantic | Captures similar meaning with different wording | Weaker on exact token match |
| BM25 full-text | Strong exact token match | No synonym or paraphrase understanding |
Fusion: Both retrieval paths are weighted and summed (vector 0.7 + BM25 0.3), so both natural-language queries and exact lookups get reliable results.
graph LR
Q[Search query] --> V[Vector search ├Ś 0.7]
Q --> B[BM25 ├Ś 0.3]
V --> M[Dedupe + weighted merge]
B --> M
M --> R[Top-N results]
ReMe Vector Based is the core class for the vector-based memory system, supporting unified management of three memory types:
| Memory Type | Purpose | Usage Context |
|---|---|---|
| Personal memory | User preferences, habits | user_name |
| Task / procedural memory | Task execution experience, success/failure patterns | task_name |
| Tool memory | Tool usage experience, parameter tuning | tool_name |
| Method | Function | Description |
|---|---|---|
summarize_memory |
¤¦? Summarize memory | Automatically extract and store memory from conversations |
retrieve_memory |
¤öŹ Retrieve memory | Retrieve relevant memory by query |
add_memory |
Ō×Ģ Add memory | Manually add memory to vector store |
get_memory |
¤ō¢ Get memory | Fetch a single memory by ID |
update_memory |
ԣŒĖÅ Update memory | Update content or metadata of existing memory |
delete_memory |
¤Śæ’ĖÅ Delete memory | Delete specified memory |
list_memory |
¤ōŗ List memory | List memories with filtering and sorting |
pip install -U reme-aiAPI keys are set via environment variables; you can put them in a .env file in the project root:
| 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 |
import asyncio
from reme import ReMe
async def main():
# Initialize 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", # Supports 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 write it", "time_created": "2026-02-28 10:00:05"},
]
# 1. Summarize memory from conversation (auto-extract user preferences, task experience, etc.)
result = await reme.summarize_memory(
messages=messages,
user_name="alice", # Personal memory
# task_name="code_writing", # Task memory
)
print(f"Summarize result: {result}")
# 2. Retrieve relevant memory
memories = await reme.retrieve_memory(
query="Python programming",
user_name="alice",
# task_name="code_writing",
)
print(f"Retrieve result: {memories}")
# 3. Manually add memory
memory_node = await reme.add_memory(
memory_content="User prefers concise code style",
user_name="alice",
)
print(f"Added memory: {memory_node}")
memory_id = memory_node.memory_id
# 4. Get single memory by ID
fetched_memory = await reme.get_memory(memory_id=memory_id)
print(f"Fetched memory: {fetched_memory}")
# 5. Update memory content
updated_memory = await reme.update_memory(
memory_id=memory_id,
user_name="alice",
memory_content="User prefers concise, well-commented code style",
)
print(f"Updated memory: {updated_memory}")
# 6. List all memories for user (with filtering and sorting)
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. Delete specified memory
await reme.delete_memory(memory_id=memory_id)
print(f"Deleted memory: {memory_id}")
# 8. Delete all memories (use with caution)
# await reme.delete_all()
await reme.close()
if __name__ == "__main__":
asyncio.run(main())graph TB
User[User / Agent] --> ReMe[Vector Based ReMe]
ReMe --> Summarize[Memory Summarize]
ReMe --> Retrieve[Memory Retrieve]
ReMe --> CRUD[CRUD]
Summarize --> PersonalSum[PersonalSummarizer]
Summarize --> ProceduralSum[ProceduralSummarizer]
Summarize --> ToolSum[ToolSummarizer]
Retrieve --> PersonalRet[PersonalRetriever]
Retrieve --> ProceduralRet[ProceduralRetriever]
Retrieve --> ToolRet[ToolRetriever]
PersonalSum --> VectorStore[Vector DB]
ProceduralSum --> VectorStore
ToolSum --> VectorStore
PersonalRet --> VectorStore
ProceduralRet --> VectorStore
ToolRet --> VectorStore
- Star & Watch: Star helps more agent developers discover ReMe; Watch keeps you updated on new releases and features.
- Share your work: In Issues or Discussions, share what ReMe unlocks for your agents ŌĆö we're happy to highlight great community examples.
- Need a new feature? Open a Feature Request; we'll iterate with the community.
- Code contributions: All forms of code contribution are welcome. See the Contribution Guide.
- Acknowledgments: Thanks to OpenClaw, Mem0, MemU, CoPaw, and other open-source projects for inspiration and support.
@software{AgentscopeReMe2025,
title = {AgentscopeReMe: Memory Management Kit for Agents},
author = {ReMe Team},
url = {https://reme.agentscope.io},
year = {2025}
}This project is open source under the Apache License 2.0. See the LICENSE file for details.
