MemReader-4B-thinking

MemReader-4B-thinking

Introduction

MemReader-4B-thinking is a 4B language model for long-term agent memory management. Instead of treating memory writing as a one-step structured extraction task, it formulates memory construction as a reasoning-and-action process: the model first evaluates whether incoming information is valuable, complete, and unambiguous, and then selects one of four memory operations:

• add_memory: write useful and complete information into long-term memory
• search_memory: retrieve historical memory for disambiguation
• buffer_memory: temporarily hold incomplete but potentially valuable information
• ignore_memory: discard low-value or repetitive content

Built on top of Qwen/Qwen3-4B, MemReader-4B-thinking is further optimized for memory management with supervised fine-tuning and GRPO. It is designed for long-horizon dialogue systems, personalized assistants, and agent frameworks that require low-noise, updatable, and retrievable long-term memory.

News

• MemReader-4B-thinking is released as an open model for active memory management.
• The model is designed for tool-calling workflows and memory-centric agent systems.
• It is part of the MemReader family introduced in the paper MemReader: Active Memory Management for Long-Term Agent Memory.

Usage

• Model ID: IAAR-Shanghai/MemReader-4B-thinking
• Base model: Qwen/Qwen3-4B
• Primary use: long-term memory extraction and memory management for agents
• Inference modes: transformers, OpenAI-compatible serving, vLLM, and SGLang

Citation

If you use MemReader in your research or product, please cite:

@misc{kang2025memreader,
  title={MemReader: Active Memory Management for Long-Term Agent Memory},
  author={Kang, Jingyi and Li, Chunyu and Chen, Ding and Tang, Bo and Xiong, Feiyu and Li, Zhiyu},
  year={2026},
  note={Manuscript in preparation}
}

Highlights

• Active memory management instead of passive memory extraction
• Explicit reasoning with thinking traces and tool calls
• Strong performance on ambiguity resolution, knowledge update, and temporal reasoning
• Native fit for OpenAI-style tool-calling workflows
• Efficient local deployment with a 4B parameter footprint
• Designed for integration with memory-centric agent systems such as MemOS

What Makes MemReader Different

Most memory pipelines directly convert the current dialogue into JSON memories. In realistic settings, that approach is often insufficient:

• low-value chatter can pollute memory
• pronouns and missing references may require historical lookup
• some information is useful but not yet complete
• newer facts may need to update or overwrite older memory

MemReader-4B-thinking reframes memory writing as active memory management. Under a ReAct-style workflow, the model reasons before acting, making memory construction closer to how practical agent systems maintain state over time.

Benchmark Performance

MemReader was evaluated on LOCOMO, LongMemEval, and HaluMem. The 4B GRPO version showed especially strong gains on knowledge update, temporal reasoning, and end-to-end memory usability.

LOCOMO

LongMemEval

HaluMem

The full HaluMem table in the paper is relatively long. Below we report a compact subset of the memory extraction and memory updating results.

These results show that stronger memory writing quality also translates into better memory updating behavior, especially on correctness and omission.

Recommended Use Cases

• long-term conversational agents
• personalized assistants
• agent memory extraction pipelines
• memory update and conflict resolution workflows
• retrieval-augmented memory systems

Intended Use

MemReader-4B-thinking is intended for research and production scenarios where an agent needs to convert conversational context into structured long-term memory. Typical use cases include memory extraction, ambiguity resolution with retrieval, memory update pipelines, and persistent assistant systems.

The model is especially suitable when the application requires explicit control over memory-writing behavior through tool calls such as search_memory, add_memory, buffer_memory, and ignore_memory.

Model Specs

• Base model: Qwen/Qwen3-4B
• Parameters: 4B
• Tensor type: BF16
• Architecture: Qwen3ForCausalLM
• Context length: 40,960 tokens
• Primary capability: reasoning-driven memory extraction with tool calling

Quickstart

OpenAI-Compatible API Example

The following example calls the model through an OpenAI-compatible endpoint with required tool calling.

import json
import requests

url = "https://YOUR_ENDPOINT/v1/chat/completions"

payload = {
    "model": "IAAR-Shanghai/MemReader-4B-thinking",
    "extra_body": {
        "chat_template_kwargs": {
            "enable_thinking": True
        }
    },
    "messages": [
        {
            "role": "system",
            "content": (
                "You are a memory extraction agent. Your job is to analyze "
                "conversations and decide what information is worth storing in "
                "long-term memory.\n\n"
                "Available actions (call exactly one per turn):\n"
                "- search_memory: Search existing memories for context\n"
                "- add_memory: Extract and store valuable facts, preferences, or events\n"
                "- buffer_memory: Accumulate this turn and wait for more context\n"
                "- ignore_memory: Nothing worth storing\n\n"
                "Guidelines:\n"
                "- Store specific, verifiable facts\n"
                "- Do not store generic greetings, chitchat, or vague statements\n"
                "- UserMemory: personal attributes or preferences about the user\n"
                "- LongTermMemory: facts, events, or shared knowledge from the conversation\n"
                "- If unsure whether information already exists, call search_memory first"
            ),
        },
        {
            "role": "user",
            "content": (
                "Please analyze the following conversation and decide what to store:\n\n"
                "[user]: How is that project at the company going lately? The one he said he wanted to rewrite with a new language.\n"
                "[assistant]: Do you mean the recommendation system refactoring project? Last time we mentioned that Michael planned to rewrite some core modules in Rust, and it was still in the evaluation stage.\n"
                "[user]: Yes, that one. He said he is going to produce a performance comparison report this week, benchmarking Python against Rust."
            ),
        },
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "search_memory",
                "description": "Search historical memories for context.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "query": {"type": "string"}
                    },
                    "required": ["query"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "add_memory",
                "description": "Extract and store memories.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "memory_list": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "key": {"type": "string"},
                                    "memory_type": {
                                        "type": "string",
                                        "enum": ["LongTermMemory", "UserMemory"],
                                    },
                                    "value": {"type": "string"},
                                    "tags": {
                                        "type": "array",
                                        "items": {"type": "string"},
                                    },
                                },
                                "required": ["key", "memory_type", "value", "tags"],
                            },
                        },
                        "summary": {"type": "string"},
                    },
                    "required": ["memory_list", "summary"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "buffer_memory",
                "description": "Buffer for later processing.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "reason": {"type": "string"}
                    },
                    "required": ["reason"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "ignore_memory",
                "description": "Ignore low-value content.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "reason": {"type": "string"}
                    },
                    "required": ["reason"],
                },
            },
        },
    ],
    "tool_choice": "required",
    "temperature": 0.2,
    "max_tokens": 1024,
}

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}

response = requests.post(url, headers=headers, json=payload)
print(response.text)

Hugging Face Transformers Usage

You can also load the model directly from Hugging Face and run memory extraction with tool calling.

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "IAAR-Shanghai/MemReader-4B-thinking"

tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype="auto",
    device_map="auto",
)

messages = [
    {
        "role": "system",
        "content": (
            "You are a memory extraction agent. Analyze conversations and decide "
            "what information should be stored in long-term memory."
        ),
    },
    {
        "role": "user",
        "content": (
            "Please analyze the following conversation and decide what to store:\n\n"
            "[user]: How is that project at the company going lately? The one he said he wanted to rewrite with a new language.\n"
            "[assistant]: Do you mean the recommendation system refactoring project? Last time we mentioned that Michael planned to rewrite some core modules in Rust, and it was still in the evaluation stage.\n"
            "[user]: Yes, that one. He said he is going to produce a performance comparison report this week, benchmarking Python against Rust."
        ),
    },
]

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_memory",
            "description": "Search historical memories for context.",
            "parameters": {
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "add_memory",
            "description": "Extract and store memories.",
            "parameters": {
                "type": "object",
                "properties": {
                    "memory_list": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "key": {"type": "string"},
                                "memory_type": {
                                    "type": "string",
                                    "enum": ["LongTermMemory", "UserMemory"],
                                },
                                "value": {"type": "string"},
                                "tags": {
                                    "type": "array",
                                    "items": {"type": "string"},
                                },
                            },
                            "required": ["key", "memory_type", "value", "tags"],
                        },
                    },
                    "summary": {"type": "string"},
                },
                "required": ["memory_list", "summary"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "buffer_memory",
            "description": "Buffer for later processing.",
            "parameters": {
                "type": "object",
                "properties": {"reason": {"type": "string"}},
                "required": ["reason"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "ignore_memory",
            "description": "Ignore low-value content.",
            "parameters": {
                "type": "object",
                "properties": {"reason": {"type": "string"}},
                "required": ["reason"],
            },
        },
    },
]

text = tokenizer.apply_chat_template(
    messages,
    tools=tools,
    tokenize=False,
    add_generation_prompt=True,
    enable_thinking=True,
)

model_inputs = tokenizer([text], return_tensors="pt").to(model.device)
generated_ids = model.generate(**model_inputs, max_new_tokens=1024)
output_ids = generated_ids[0][len(model_inputs.input_ids[0]):]
output = tokenizer.decode(output_ids, skip_special_tokens=True)
print(output)

vLLM Usage

Start an OpenAI-compatible vLLM server:

python -m vllm.entrypoints.openai.api_server \
  --model IAAR-Shanghai/MemReader-4B-thinking \
  --served-model-name MemReader-4B-thinking \
  --port 8000 \
  --tensor-parallel-size 1 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

Then send a standard chat completion request to http://localhost:8000/v1/chat/completions.

SGLang Usage

MemReader-4B-thinking can also be deployed with SGLang through its OpenAI-compatible serving interface. Please make sure tool calling and thinking mode are enabled in your serving configuration.

Output Format

MemReader-4B-thinking is trained to produce thinking traces and tool calls. A typical response looks like this:

<think>
The conversation refers to an already known project and adds a new update:
Michael plans to produce a Python vs Rust benchmark report this week.
This is valuable project-state information and should be added to memory.
</think>

<tool_call>
{"name": "add_memory", "arguments": {"memory_list": [{"key": "Rust benchmark plan", "memory_type": "LongTermMemory", "value": "Michael said the recommendation system refactoring project is still in evaluation, and he plans to produce a Python-vs-Rust benchmark report this week for the core modules under consideration for Rust rewriting.", "tags": ["project", "Rust", "benchmark", "refactoring"]}], "summary": "Added one memory about the project update and the planned benchmark report."}}
</tool_call>

Best Practices

• Use search_memory first when the conversation contains pronouns, ellipsis, or implicit historical references.
• Use buffer_memory only when the information is genuinely incomplete and cannot be resolved from history.
• Keep tool definitions stable between training and inference.
• For production pipelines, execute tool calls externally and feed tool responses back to the model when multi-step reasoning is needed.
• If you want shorter outputs, reduce max_tokens and control whether thinking traces are exposed in your serving layer.

Limitations

• The model is optimized for memory-management scenarios rather than general-purpose chatting.
• Quality depends on the external memory schema, retrieval quality, and tool-execution loop.
• For highly domain-specific memory schemas, additional instruction tuning may still be beneficial.
• As with other LLMs, outputs may still contain mistakes, omissions, or unsupported inferences and should be validated in safety-critical workflows.

License Notice

This model is released under the Apache-2.0 license. As it is derived from Qwen/Qwen3-4B, users should also review and comply with the upstream base model license, usage terms, and any applicable third-party requirements before deployment.

Links

• GitHub: MemTensor/MemOS
• API Documentation: docs.openmem.net
• Model: IAAR-Shanghai/MemReader-4B-thinking
• Base model: Qwen/Qwen3-4B