Skip to content

docs: sync memory module docs English version #367

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
abbyzhou02 wants to merge 1 commit into
base: v2
Choose a base branch
from
Open

docs: sync memory module docs English version #367

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 4 additions & 5 deletions content/cn/open_source/modules/memories/naive_textual_memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,12 @@
---
title: "NaiveTextMemory: 简单明文记忆"
desc: "MemOS 中最轻量级的记忆模块，专为快速原型开发和简单场景设计。无需向量数据库，使用关键词匹配即可快速检索。"
desc: "MemOS 中最轻量级的记忆模块，专为快速原型开发和简单场景设计。无需向量数据库，使用关键词匹配即可快速检索。让我们用最简单的方式开始使用 MemOS 记忆系统！
`NaiveTextMemory` 是一个基于内存的明文记忆模块，将记忆存储在内存列表中，使用关键词匹配进行检索。它是学习 MemOS 的最佳起点，也适用于演示、测试和小规模应用。"

---

# NaiveTextMemory: 简单明文记忆

让我们用最简单的方式开始使用 MemOS 记忆系统！

`NaiveTextMemory` 是一个轻量级、基于内存的明文记忆模块，将记忆存储在内存列表中，使用关键词匹配进行检索。它是学习 MemOS 的最佳起点，也适用于演示、测试和小规模应用。

## 目录

Expand Down Expand Up @@ -144,7 +143,7 @@ memory = NaiveTextMemory(config: NaiveTextMemoryConfig)



::alert{type="info"}
::note
**示例对比**<br>
查询："猫咪" <br>
- **关键词匹配**：只匹配包含"猫"、"猫咪"的记忆<br>
Expand Down
9 changes: 5 additions & 4 deletions content/cn/open_source/modules/memories/tree_textual_memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
---
title: "TreeTextMemory: 分层结构的明文记忆"
---

让我们在MemOS中构建你的第一个**基于图的、树形明文记忆**！
desc: "让我们在MemOS中构建你的第一个**基于图的、树形明文记忆**！

**TreeTextMemory** 支持以结构化方式组织、关联并检索记忆，同时保留丰富的上下文信息与良好的可解释性。

MemOS当前使用[Neo4j](/open_source/modules/memories/neo4j_graph_db)作为后端，未来计划支持更多图数据库。
MemOS当前使用[Neo4j](/open_source/modules/memories/neo4j_graph_db)作为后端，未来计划支持更多图数据库。"
---



## 目录

Expand Down
18 changes: 16 additions & 2 deletions content/en/open_source/modules/memories/general_textual_memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,20 @@ Each memory is represented as a `TextualMemoryItem`:

All values are validated. Invalid values will raise errors.

### Search Mechanism
Unlike NaiveTextMemory, which relies on keyword matching, GeneralTextMemory utilizes vector-based semantic search.

## Algorithm Comparison

| Feature | Keyword Matching | Vector Semantic Search |
| ------------------ | ---------------------------------- | ------------------------------------------ |
| **Semantic Understanding** | ❌ Doesn't understand synonyms | ✅ Understands similar concepts |
| **Resource Usage** | ✅ Extremely low | ⚠️ Requires embedding model and vector DB |
| **Execution Speed** | ✅ Fast (O(n)) | ⚠️ Slower (indexing + querying) |
| **Suitable Scale** | < 1K memories | 10K - 100K memories |
| **Predictability** | ✅ Intuitive results | ⚠️ Black box model


## API Summary (`GeneralTextMemory`)

### Initialization
Expand Down Expand Up @@ -112,13 +126,13 @@ m.dump("tmp/mem")
m.load("tmp/mem")
```

::alert{type="info"}
::note
**Extension: Internet Retrieval**<br>
GeneralTextMemory can be combined with Internet Retrieval to extract content from web pages and add to memory.<br>
View example: [Retrieve Memories from the Internet](./tree_textual_memory#retrieve-memories-from-the-internet-optional)
::

::alert{type="info"}
::note
**Advanced: Using MultiModal Reader**<br>
For processing images, URLs, or files within conversations, see the comprehensive MultiModal Reader examples.<br>
View documentation: [Using MultiModalStructMemReader](./tree_textual_memory#using-multimodalstructmemreader-advanced)
Expand Down
27 changes: 7 additions & 20 deletions content/en/open_source/modules/memories/naive_textual_memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,9 @@ title: "NaiveTextMemory: Simple Plain Text Memory"
desc: "The most lightweight memory module in MemOS, designed for rapid prototyping and simple scenarios. No vector database required—quickly retrieve memories using keyword matching."
---

# NaiveTextMemory: Simple Plain Text Memory
Let's get started with the MemOS memory system in the simplest way possible!

Let's start using the MemOS memory system in the simplest way possible!

**NaiveTextMemory** is a lightweight, in-memory plain text memory module that stores memories in a memory list and uses keyword matching for retrieval. It's the best starting point for learning MemOS and is suitable for demos, testing, and small-scale applications.
NaiveTextMemory is a lightweight, memory-based, plain-text memory module. It stores memories in an in-memory list and retrieves them using keyword matching. It is the perfect starting point for learning MemOS, as well as an ideal choice for demos, testing, and small-scale applications.

## Table of Contents

Expand Down Expand Up @@ -62,7 +60,7 @@ By the end of this guide, you will be able to:
- Keyword search scenarios (queries directly match memories)
::

::alert{type="warning"}
::note
**Performance Tip**<br>
When memory count exceeds 1000, it's recommended to upgrade to [GeneralTextMemory](/open_source/modules/memories/general_textual_memory), which uses vector search for better performance.
::
Expand Down Expand Up @@ -139,19 +137,8 @@ Sort all memories by match count in descending order
#### Step 4: Return Results
Return the top-k memories as search results

::

**Algorithm Comparison**

| Feature | Keyword Matching (NaiveTextMemory) | Vector Semantic Search (GeneralTextMemory) |
| ------------------ | ---------------------------------- | ------------------------------------------ |
| **Semantic Understanding** | ❌ Doesn't understand synonyms | ✅ Understands similar concepts |
| **Resource Usage** | ✅ Extremely low | ⚠️ Requires embedding model and vector DB |
| **Execution Speed** | ✅ Fast (O(n)) | ⚠️ Slower (indexing + querying) |
| **Suitable Scale** | < 1K memories | 10K - 100K memories |
| **Predictability** | ✅ Intuitive results | ⚠️ Black box model |

::alert{type="info"}
::note
**Example Comparison**<br>
Query: "cat" <br>
- **Keyword Matching**: Only matches memories containing "cat"<br>
Expand Down Expand Up @@ -238,7 +225,7 @@ memory.add(memories)
print(f"✓ Added {len(memories)} memories")
```

::alert{type="info"}
::note
**Advanced: Using MultiModal Reader**<br>
If you need to process multimodal content such as images, URLs, or files, use `MultiModalStructMemReader`.<br>
View complete example: [Using MultiModalStructMemReader (Advanced)](./tree_textual_memory#using-multimodalstructmemreader-advanced)
Expand Down Expand Up @@ -332,7 +319,7 @@ if memories:
# memory.delete_all()
```

::alert{type="info"}
::note
**Extension: Internet Retrieval**<br>
NaiveTextMemory focuses on local memory management. For retrieving information from the internet and adding it to your memory store, see:<br>
[Retrieve Memories from the Internet (Optional)](./tree_textual_memory#retrieve-memories-from-the-internet-optional)
Expand Down Expand Up @@ -367,7 +354,7 @@ When calling `dump(dir)`, the system saves memories to:

Use `load(dir)` to fully restore all memory data.

::alert{type="warning"}
::note
**Important Note**<br>
Memories are stored in memory and will be lost after process restart. Remember to call `dump()` regularly to save data!
::
Expand Down
2 changes: 1 addition & 1 deletion content/en/open_source/modules/memories/neo4j_graph_db.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -185,4 +185,4 @@ You can add support for any other graph engine (e.g., **TigerGraph**, **DGraph**
* `GraphDBConfigFactory.backend_to_class`
* `GraphStoreFactory.backend_to_class`

See `src/memos/graph_dbs/neo4j.py` as a reference implementation.
See `src/memos/graph_dbs/neo4j.py` as a reference for implementation.
13 changes: 6 additions & 7 deletions content/en/open_source/modules/memories/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,18 @@ title: "Memory Modules Overview"
desc: "Complete guide to MemOS memory systems - from lightweight text memory to advanced graph structures, choose the right memory module for your needs"
---

# Memory Modules Overview

MemOS provides a rich set of memory modules to meet various needs from rapid prototyping to production environments. This guide helps you quickly find the most suitable memory solution.
The Memory Module provides Agents with essential long-term memory capabilities. Instead of acting as a static database, it mimics human cognitive processes by automatically extracting, organizing, and linking information. Choosing different memory modules allows you to customize and enhance your Agent's skills.

## 🎯 Quick Selection Guide

::alert{type="info"}
**Not sure which to choose?** Follow this decision tree:
- 🚀 **Quick testing/demo** → [NaiveTextMemory](#naivetextmemory-simple-textual-memory)
- 📝 **General text memory** → [GeneralTextMemory](#generaltextmemory-general-purpose-textual-memory)
- 👤 **User preference management** → [PreferenceTextMemory](#preferencetextmemory-preference-memory)
- 🌳 **Structured knowledge graph** → [TreeTextMemory](#treetextmemory-hierarchical-structured-memory)
- ⚡ **Inference acceleration** → [KVCacheMemory](#kvcachememory-activation-memory)
- 🚀 **Quick testing/demo**: Get started easily with no additional software → [NaiveTextMemory](#naivetextmemory-simple-textual-memory)
- 📝 **General text memory**: Retain chat history or massive documents with semantic search capabilities → [GeneralTextMemory](#generaltextmemory-general-purpose-textual-memory)
- 👤 **User preference management**：Specifically designed for building and managing user profiles → [PreferenceTextMemory](#preferencetextmemory-preference-memory)
- 🌳 **Structured knowledge graph**: Ideal for data with complex logical relationships and interconnections → [TreeTextMemory](#treetextmemory-hierarchical-structured-memory)
- ⚡ **Inference acceleration**: Optimized for high-traffic scenarios to ensure stable and rapid responses → [KVCacheMemory](#kvcachememory-activation-memory)
::

---
Expand Down
4 changes: 1 addition & 3 deletions content/en/open_source/modules/memories/polardb_graph_db.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,9 @@
---
title: "PolarDB Graph Database"
desc: "Configuration and usage of PolarDB graph database in the MemOS framework"
desc: "Configuration and usage of PolarDB graph database in the MemOS framework. MemOS supports using **PolarDB** (based on Apache AGE extension) as a graph database backend for storing and retrieving knowledge graph-style memory data. PolarDB combines the powerful capabilities of PostgreSQL with the flexibility of graph databases, making it particularly suitable for scenarios requiring both relational and graph data queries."
---

# PolarDB Graph Database

MemOS supports using **PolarDB** (based on Apache AGE extension) as a graph database backend for storing and retrieving knowledge graph-style memory data. PolarDB combines the powerful capabilities of PostgreSQL with the flexibility of graph databases, making it particularly suitable for scenarios requiring both relational and graph data queries.


## Features
Expand Down
7 changes: 3 additions & 4 deletions content/en/open_source/modules/memories/preference_textual_memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,8 @@ desc: "`PreferenceTextMemory` is a textual memory module in MemOS for storing an
- Learning assistance systems (adapting to learning styles)
::

::alert{type="info"}
**Applicable Scenarios**<br>
When you need to build systems that can "remember" user preferences and provide personalized services accordingly, `PreferenceTextMemory` is the best choice.

In conclusion, when you need to build systems that can "remember" user preferences and provide personalized services accordingly, `PreferenceTextMemory` is the best choice.
::

## Core Concepts and Workflow
Expand All @@ -74,7 +73,7 @@ Preference memory can be divided into explicit preference memory and implicit pr
- User frequently requests detailed explanations → prefers in-depth understanding
- User mentions environmental topics multiple times → concerned about sustainable development

::alert{type="success"}
::note
**Intelligent Extraction**<br>
`PreferenceTextMemory` automatically extracts both explicit and implicit preferences from conversations using LLM, no manual annotation required!
::
Expand Down
12 changes: 6 additions & 6 deletions content/en/open_source/modules/memories/tree_textual_memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
title: "TreeTextMemory: Structured Hierarchical Textual Memory"
---

Let’s build your first **graph-based, tree-structured memory** in MemOS!
desc: "Let’s build your first **graph-based, tree-structured memory** in MemOS!

**TreeTextMemory** helps you organize, link, and retrieve memories with rich context and explainability.

[Neo4j](/open_source/modules/memories/neo4j_graph_db) is the current backend, with support for additional graph stores planned in the future.
[Neo4j](/open_source/modules/memories/neo4j_graph_db) is the current backend, with support for additional graph stores planned in the future."
---


## Table of Contents

Expand Down Expand Up @@ -309,7 +309,7 @@ for m_list in mixed_memories:
print(f"✓ Extracted and added {len(mixed_memories)} memories from mixed content")
```

::alert{type="info"}
::note
**MultiModal Reader Advantages**<br>
- **Smart Routing**: Automatically identifies content type (image/URL/file) and selects appropriate parser<br>
- **Format Support**: Supports PDF, DOCX, Markdown, HTML, images, and more<br>
Expand All @@ -318,7 +318,7 @@ print(f"✓ Extracted and added {len(mixed_memories)} memories from mixed conten
- **Context Preservation**: Uses sliding window to maintain context continuity between chunks
::

::alert{type="tip"}
::note
**Configuration Tips**<br>
- Use the `direct_markdown_hostnames` parameter to specify which domains should return Markdown format<br>
- Supports both `mode="fast"` and `mode="fine"` extraction modes; fine mode extracts more details<br>
Expand Down