Long-term memory in AgentScope provides agents with the ability to persist and retrieve information across different sessions and conversations. Unlike short-term context which is limited by model token windows, long-term memory allows agents to recall durable facts, user preferences, and historical decisions src/agentscope/middleware/_longterm_memory/_reme/_middleware.py75-82
AgentScope implements long-term memory through a specialized Middleware system. This allows memory operations (retrieval and storage) to be injected into the agent's reasoning loop without modifying the core agent logic src/agentscope/middleware/_longterm_memory/_reme/_middleware.py9-27 Two primary backends are supported: ReMe (AgentScope's native file-based memory) and Mem0.
The long-term memory system bridges the gap between the agent's "Natural Language Space" (messages and reasoning) and the "Code Entity Space" (vector stores and memory jobs).
The following diagram illustrates how memory middleware intercepts the agent's reply process to perform retrieval and storage.
Diagram: Memory Middleware Data Flow
Sources: src/agentscope/middleware/_longterm_memory/_reme/_middleware.py9-27 examples/long_term_memory/reme/README.md91-105 examples/long_term_memory/mem0/README.md127-145
ReMeMiddleware embeds the ReMe application directly in-process. It is a file-based memory toolkit that records memory by listening to conversations and uses LLM-backed jobs to summarize and index facts src/agentscope/middleware/_longterm_memory/_reme/_middleware.py4-12
ReMe is instantiated lazily on the first agent call. It requires a workspace_dir for storage and a ChatModelBase to drive its internal summarization jobs src/agentscope/middleware/_longterm_memory/_reme/_middleware.py89-107
| Parameter | Type | Description |
|---|---|---|
workspace_dir | str | Path where memory cards and indexes are stored src/agentscope/middleware/_longterm_memory/_reme/_middleware.py92 |
chat_model | ChatModelBase | LLM used for the auto_memory summarization job src/agentscope/middleware/_longterm_memory/_reme/_middleware.py138-147 |
embedding_model | EmbeddingModelBase | If provided, enables semantic vector search; otherwise, defaults to BM25 keyword search src/agentscope/middleware/_longterm_memory/_reme/_middleware.py149-161 |
mode | Literal | Controls retrieval: static_control, agent_control, or both src/agentscope/middleware/_longterm_memory/_reme/_middleware.py163-172 |
static_control: The middleware automatically searches ReMe at the start of a reply and injects results as a HintBlock in an AssistantMsg named "memory" src/agentscope/middleware/_longterm_memory/_reme/_middleware.py15-18agent_control: The middleware exposes a memory_search tool. The agent must decide when to call it src/agentscope/middleware/_longterm_memory/_reme/_middleware.py19-20both: Combines automatic injection with tool access src/agentscope/middleware/_longterm_memory/_reme/_middleware.py21Sources: src/agentscope/middleware/_longterm_memory/_reme/_middleware.py85-126 examples/long_term_memory/reme/README.md45-84
Mem0Middleware integrates the Mem0 library, supporting both the open-source (OSS) backend and the hosted Mem0 Platform examples/long_term_memory/mem0/README.md10-17
For the OSS backend, AgentScope provides adapters to wrap AgentScope models (ChatModelBase and EmbeddingModelBase) into a format compatible with Mem0's internal AsyncMemory client examples/long_term_memory/mem0/README.md44-51 This is handled by the Mem0Middleware which can accept either a pre-built client or raw AgentScope models to build one examples/long_term_memory/mem0/README.md98-109
Sources: examples/long_term_memory/mem0/README.md44-51 examples/long_term_memory/mem0/oss_demo.py49-55
The following diagram maps high-level memory concepts to the specific classes and files within the agentscope.middleware and agentscope.rag packages.
Diagram: Memory Code Entity Map
Sources: src/agentscope/middleware/_longterm_memory/_reme/_middleware.py85-90 src/agentscope/middleware/_longterm_memory/_mem0/_middleware.py7-11 src/agentscope/middleware/__init__.py7-11
Both middlewares use the session_id to scope memory writes. In ReMeMiddleware, the session_id is read dynamically from agent.state.session_id during the on_reply hook, allowing a single middleware instance to be shared across multiple agents while maintaining isolated memory streams src/agentscope/middleware/_longterm_memory/_reme/_middleware.py23-27
Memory retrieval often involves network I/O or vector search.
asyncio task started in on_reply. The on_reasoning hook polls this task. If the model is fast and the search is slow (e.g., a single-shot reply), the memory might not be injected in time for the first model call; this is known as "best-effort injection" src/agentscope/middleware/_longterm_memory/_reme/_middleware.py15-18static_control queries Mem0 during the pre-reply phase and injects the result at the ReplyStartEvent examples/long_term_memory/mem0/README.md131-138While memory middlewares focus on conversational history, they utilize underlying vector store infrastructure for semantic retrieval. Concrete implementations include:
MilvusLiteStore: Local file-based Milvus for easy development src/agentscope/rag/_vdb/_milvus_lite.py26-43QdrantStore: Supports in-memory, local disk, and remote server modes src/agentscope/rag/_vdb/_qdrant.py31-56MongoDBStore: Utilizes MongoDB Atlas Vector Search src/agentscope/rag/_vdb/_mongodb.py31-63ElasticsearchStore: Uses dense-vector indexes for approximate kNN search src/agentscope/rag/_vdb/_elasticsearch.py20-31Sources: src/agentscope/middleware/_longterm_memory/_reme/_middleware.py99-107 examples/long_term_memory/reme/README.md135-148 src/agentscope/rag/_vdb/_milvus_lite.py26-43 src/agentscope/rag/_vdb/_qdrant.py31-56 src/agentscope/rag/_vdb/_mongodb.py31-63 src/agentscope/rag/_vdb/_elasticsearch.py20-31
Refresh this wiki