README.md

---
license: apache-2.0
language:
- en
- zh
base_model:
- Qwen/Qwen3-4B
library_name: transformers
---
## Model Overview

**Memory Operator** is a sub-model exclusive to MemOS, designed specifically for memory operations. Its core functionalities include processing memory extraction, integration, and updating. The purpose of building the Memory Operator sub-model is:

1. **Support local-only deployment**, making it convenient to use MemOS in restricted environments (e.g., scenarios where internet access is unavailable).
2. **Perform memory operations at lower cost and higher speed**, while maintaining strong system performance.

The first Memory Operator model is **MemReader-4B**, which is derived from a fine-tuned version of Qwen3-4B. It has been further trained using supervised fine-tuning on both human-annotated and model-generated data, achieving high performance in memory extraction tasks.

### MemReader-4B Features:
- **Type**: Causal Language Models  
- **Training Stage**: Supervised Finetune  
- **Supported Languages**: en, zh  
- **Number of Parameters**: 4B  
- **Context Length**: 32,768  

---

## Highlights

- **Faster and more accurate memory extraction model**
- **Supports memory extraction**: MemReader-4B supports extracting memories from both conversations and documents, producing high-quality conversation summaries and document snippet summaries.
- **Excellent system performance**: With only a 4B parameter size, it supports local deployment on most machines and outperforms GPT-4o-mini.
- **Multilingual support**: Supports memory extraction in both Chinese and English.

---

## Performance

Evaluation results on Locomo using memories extracted by different models in MemOS:

| Model           | Overall    | Temporal Reasoning | Multi Hop   | Single Hop | Open Domain |
|------------------|------------|---------------------|-------------|-------------|--------------|
| Qwen3-32B        | 0.7617     | 0.7788              | 0.6453      | 0.8204      | 0.5312       |
| Qwen3-14B        | 0.7370     | 0.6822              | 0.6631      | 0.8002      | 0.5833       |
| MemReader-4B     | 0.7348     | 0.7902              | 0.6146      | 0.7764      | 0.5381       |
| Qwen3-4B         | 0.5454     | 0.2575              | 0.5118      | 0.6739      | 0.4896       |
| GPT-4o-mini      | 0.7253     | 0.7321              | 0.6430      | 0.7844      | 0.5521       |

By replacing your open-source model with MemReader-4B, you can achieve the same memory extraction performance while saving over **70% in resource consumption** (4B vs 14B)!

---

## Usage

### MemOS Usage

You can easily use our trained MemReader model for memory extraction in MemOS by configuration.

#### Install MemOS via pip

```bash
pip install MemoryOS
```

#### Initialize a MemReader and Extract Memory

```python
from memos.configs.mem_reader import SimpleStructMemReaderConfig
from memos.mem_reader.simple_struct import SimpleStructMemReader

config = SimpleStructMemReaderConfig(
    **{
        "llm": {
            "backend": "huggingface",
            "config": {
                "model_name_or_path": "MemTensor/MemReader-4B",
                "temperature": 0.6,
                "max_tokens": 6000,
                "top_p": 0.95,
                "top_k": 20,
            },
        },
        "embedder": {
            "backend": "ollama",
            "config": {"model_name_or_path": "nomic-embed-text:latest"},
        },
        "chunker": {
            "backend": "sentence",
            "config": {
                "tokenizer_or_token_counter": "gpt2",
                "chunk_size": 512,
                "chunk_overlap": 128,
                "min_sentences_per_chunk": 1,
            },
        },
        "remove_prompt_example": True,
    }
)

reader = SimpleStructMemReader(config)

chat_data = [
    [
        {
            "role": "user",
            "chat_time": "June 26, 2025 at 3:00 PM",
            "content": "Hi Jerry! Yesterday at 3 PM I had a meeting with my team about the new project.",
        },
        {
            "role": "assistant",
            "chat_time": "June 26, 2025 at 3:00 PM",
            "content": "Oh Tom! Do you think the team can finish by December 15?",
        },
        {
            "role": "user",
            "chat_time": "June 26, 2025 at 3:00 PM",
            "content": "I’m worried. The backend won’t be done until December 10, so testing will be tight.",
        },
        {
            "role": "assistant",
            "chat_time": "June 26, 2025 at 3:00 PM",
            "content": "Maybe propose an extension?",
        },
        {
            "role": "user",
            "chat_time": "June 26, 2025 at 4:21 PM",
            "content": "Good idea. I’ll raise it in tomorrow’s 9:30 AM meeting—maybe shift the deadline to January 5.",
        },
    ]
]
with open("tmp.txt", "w") as f:
    f.write(
        "Lou Henry Hoover (March 29, 1874 – January 7, 1944) was an American philanthropist, geologist, and the first lady of the United States from 1929 to 1933 as the wife of President Herbert Hoover. She was active in community organizations and volunteer groups throughout her life, including the Girl Scouts of the USA, which she led from 1922 to 1925 and from 1935 to 1937. Throughout her life, Hoover supported women's rights and women's independence. She was a polyglot, fluent in Mandarin and well-versed in Latin, and was the primary translator from Latin to English of the complex 16th-century metallurgy text De re metallica."
    )

chat_memory = reader.get_memory(
    chat_data, type="chat", info={"user_id": "Tom", "session_id": "session1"}
)
doc_memory = reader.get_memory(
    ["tmp.txt"],
    "doc",
    info={
        "user_id": "Tom",
        "session_id": "session2",
    },
)

print(chat_memory)
print(doc_memory)
```

---

## Huggingface Usage

You can also directly load the model via Huggingface, vLLM, or SGLang and perform memory extraction using the preset templates we have configured.
```python
from transformers import AutoModelForCausalLM, AutoTokenizer

model_name = "MemTensor/MemReader-4B"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype="auto", device_map="auto")

# prepare the model input
chat_messages = [
    {
        "role": "user",
        "chat_time": "June 26, 2025 at 3:00 PM",
        "content": "Hi Jerry! Yesterday at 3 PM I had a meeting with my team about the new project.",
    },
    {
        "role": "assistant",
        "chat_time": "June 26, 2025 at 3:00 PM",
        "content": "Oh Tom! Do you think the team can finish by December 15?",
    },
    {
        "role": "user",
        "chat_time": "June 26, 2025 at 3:00 PM",
        "content": "I’m worried. The backend won’t be done until December 10, so testing will be tight.",
    },
    {
        "role": "assistant",
        "chat_time": "June 26, 2025 at 3:00 PM",
        "content": "Maybe propose an extension?",
    },
    {
        "role": "user",
        "chat_time": "June 26, 2025 at 4:21 PM",
        "content": "Good idea. I’ll raise it in tomorrow’s 9:30 AM meeting—maybe shift the deadline to January 5.",
    },
]
doc_message = "Lou Henry Hoover (March 29, 1874 – January 7, 1944) was an American philanthropist, geologist, and the first lady of the United States from 1929 to 1933 as the wife of President Herbert Hoover. She was active in community organizations and volunteer groups throughout her life, including the Girl Scouts of the USA, which she led from 1922 to 1925 and from 1935 to 1937. Throughout her life, Hoover supported women's rights and women's independence. She was a polyglot, fluent in Mandarin and well-versed in Latin, and was the primary translator from Latin to English of the complex 16th-century metallurgy text De re metallica."
chat_text = tokenizer.apply_chat_template(
    chat_messages,
    tokenize=False,
    add_generation_prompt=True,
    extract_chat_memory=True,
    enable_think=False,
)
doc_text = tokenizer.apply_chat_template(
    doc_message,
    tokenize=False,
    add_generation_prompt=True,
    extract_doc_memory=True,
    enable_think=False,
)
print(chat_text, doc_text)

model_inputs = tokenizer(
    [chat_text, doc_text], return_tensors="pt", padding=True, padding_side="left"
).to(model.device)
generated_ids = model.generate(**model_inputs, max_new_tokens=2000)
chat_output_ids = generated_ids[0][len(model_inputs.input_ids[0]) :].tolist()
doc_output_ids = generated_ids[1][len(model_inputs.input_ids[1]) :].tolist()
chat_content = tokenizer.decode(chat_output_ids, skip_special_tokens=True).strip("\n")
doc_content = tokenizer.decode(doc_output_ids, skip_special_tokens=True).strip("\n")

print("chat memory:", chat_content)
print("doc memory:", doc_content)
```

#### Prompt for chat memory extraction
```text
You are a memory extraction expert.

Your task is to extract memories from the perspective of user, based on a conversation between user and assistant. This means identifying what user would plausibly remember — including their own experiences, thoughts, plans, or relevant statements and actions made by others (such as assistant) that impacted or were acknowledged by user.

Please perform:
1. Identify information that reflects user's experiences, beliefs, concerns, decisions, plans, or reactions — including meaningful input from assistant that user acknowledged or responded to.
2. Resolve all time, person, and event references clearly:
   - Convert relative time expressions (e.g., “yesterday,” “next Friday”) into absolute dates using the message timestamp if possible.
   - Clearly distinguish between event time and message time.
   - If uncertainty exists, state it explicitly (e.g., “around June 2025,” “exact date unclear”).
   - Include specific locations if mentioned.
   - Resolve all pronouns, aliases, and ambiguous references into full names or identities.
   - Disambiguate people with the same name if applicable.
3. Always write from a third-person perspective, referring to user as
"The user" or by name if name mentioned, rather than using first-person ("I", "me", "my").
For example, write "The user felt exhausted..." instead of "I felt exhausted...".
4. Do not omit any information that user is likely to remember.
   - Include all key experiences, thoughts, emotional responses, and plans — even if they seem minor.
   - Prioritize completeness and fidelity over conciseness.
   - Do not generalize or skip details that could be personally meaningful to user.

Return a single valid JSON object with the following structure:

{
  "memory list": [
    {
      "key": <string, a unique, concise memory title>,
      "memory_type": <string, Either "LongTermMemory" or "UserMemory">,
      "value": <A detailed, self-contained, and unambiguous memory statement — written in English if the input conversation is in English, or in Chinese if the conversation is in Chinese>,
      "tags": <A list of relevant thematic keywords (e.g., ["deadline", "team", "planning"])>
    },
    ...
  ],
  "summary": <a natural paragraph summarizing the above memories from user's perspective, 120–200 words, same language as the input>
}

Language rules:
- The `key`, `value`, `tags`, `summary` fields must match the language of the input conversation.
- Keep `memory_type` in English.

Conversation:
${conversation}

Your Output:

```

#### Prompt for doc extraction
```text
You are an expert text analyst for a search and retrieval system. Your task is to process a document chunk and generate a single, structured JSON object.
The input is a single piece of text: `[DOCUMENT_CHUNK]`.
You must generate a single JSON object with two top-level keys: `summary` and `tags`.
1. `summary`:
   - A dense, searchable summary of the ENTIRE `[DOCUMENT_CHUNK]`.
   - The purpose is for semantic search embedding.
   - A clear and accurate sentence that comprehensively summarizes the main points, arguments, and information within the `[DOCUMENT_CHUNK]`.
   - The goal is to create a standalone overview that allows a reader to fully understand the essence of the chunk without reading the original text.
   - The summary should be **no more than 50 words**.
2. `tags`:
   - A concise list of **3 to 5 high-level, summative tags**.
   - **Each tag itself should be a short phrase, ideally 2 to 4 words long.**
   - These tags must represent the core abstract themes of the text, suitable for broad categorization.
   - **Crucially, prioritize abstract concepts** over specific entities or phrases mentioned in the text. For example, prefer "Supply Chain Resilience" over "Reshoring Strategies".

Here is the document chunk to process:
`[DOCUMENT_CHUNK]`
{chunk_text}

Produce ONLY the JSON object as your response.
```