PreferenceTextMemory: Textual Memory for User Preferences

PreferenceTextMemory is a textual memory module in MemOS for storing and managing user preferences. It is suitable for scenarios where memory retrieval needs to be based on user preferences.

Why Preference Memory is Needed
- Key Features
- Application Scenarios
Core Concepts and Workflow
API Reference
Hands-on Practice: From Zero to One

Why Preference Memory is Needed

Key Features

Dual Preference Extraction: Automatically identifies explicit and implicit preferences
Semantic Understanding: Uses vector embeddings to understand the deep meaning of preferences
Smart Deduplication: Automatically detects and merges duplicate or conflicting preferences
Precise Retrieval: Semantic search based on vector similarity
Persistent Storage: Supports vector databases (Qdrant/Milvus)
Scalability: Supports large-scale preference data management
Personalization Enhancement: Maintains independent preference profiles for each user

Application Scenarios

Personalized conversational agents (remembering user likes/dislikes)
Intelligent recommendation systems (recommendations based on preferences)
Customer service systems (providing customized services)
Content filtering systems (filtering content based on preferences)
Learning assistance systems (adapting to learning styles)

Applicable Scenarios
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

Memory Structure

In MemOS, preference memory is represented by PreferenceTextMemory, where each memory item is a TextualMemoryItem stored in Milvus database.

id: Unique memory ID (automatically generated if omitted)
memory: Main text content
metadata: Includes hierarchical structure information, embeddings, tags, entities, sources, and status

Preference memory can be divided into explicit preference memory and implicit preference memory:

Explicit Preference Memory: Preferences that users explicitly express. Examples:
- "I like dark mode"
- "I don't eat spicy food"
- "Please use short answers"
- "I prefer technical documentation over video tutorials"
Implicit Preference Memory: Preferences inferred from user behavior and conversation patterns. Examples:
- User always asks for code examples → prefers practice-oriented learning
- User frequently requests detailed explanations → prefers in-depth understanding
- User mentions environmental topics multiple times → concerned about sustainable development

Intelligent Extraction
PreferenceTextMemory automatically extracts both explicit and implicit preferences from conversations using LLM, no manual annotation required!

Metadata Fields (`PreferenceTextualMemoryMetadata`)

Field	Type	Description
`preference_type`	`"explicit_preference"`, `"implicit_preference"`	Preference memory type, divided into explicit and implicit preference memory
`dialog_id`	`str`	Dialog ID, used to associate preference memory with specific dialogs
`original_text`	`str`	Original text containing user preference information
`embedding`	`str`	Embedding vector for semantic search and retrieval
`preference`	`str`	User preference information
`create_at`	`str`	Creation timestamp (ISO 8601)
`mem_cube_id`	`str`	Memory cube ID, used to associate preference memory with specific memory cubes
`score`	`float`	Similarity score between preference memory and query in search results

Core Workflow

When you run this example, your workflow will:

Extraction: Use LLM to extract structured memory from raw text.
Embedding: Generate vector embeddings for similarity search.
Storage: Store preference memory in Milvus database while updating metadata fields.
Search: Return the most relevant preference memories through vector similarity queries.

API Reference

Initialization

PreferenceTextMemory(config: PreferenceTextMemoryConfig)

Core Methods

Method	Description
`get_memory(messages)`	Extract preference memories from original dialogues.
`search(query, top_k)`	Retrieve top-k preference memories using vector similarity.
`load(dir)`	Load preference memories from stored files.
`dump(dir)`	Serialize all preference memories to JSON files in the directory.
`add(memories)`	Batch add preference memories to Milvus database.
`get_with_collection_name(collection_name, memory_id)`	Get specific type of preference memory by collection name and memory ID.
`get_by_ids_with_collection_name(collection_name, memory_ids)`	Batch get specific type of preference memory by collection name and memory IDs.
`get_all()`	Get all preference memories.
`get_memory_by_filter(filter)`	Get preference memories based on filter conditions.
`delete(memory_ids)`	Delete preference memories by specified IDs.
`delete_by_filter(filter)`	Delete preference memories based on filter conditions.
`delete_with_collection_name(collection_name, memory_ids)`	Delete all preference memories with specified collection name and IDs.
`delete_all()`	Delete all preference memories.

File Storage

When calling dump(dir), MemOS will serialize all preference memories to JSON files in the directory:

<dir>/<config.memory_filename>

Hands-on Practice: From Zero to One

Create PreferenceTextMemory Configuration

Define:

Your embedding model (e.g., nomic-embed-text:latest),
Your Milvus database backend,
Memory extractor (based on LLM) (optional).

from memos.configs.memory import PreferenceTextMemoryConfig

config = PreferenceTextMemoryConfig.from_json_file("examples/data/config/preference_config.json")

Initialize PreferenceTextMemory

from memos.memories.textual.preference import PreferenceTextMemory

preference_memory = PreferenceTextMemory(config)

Extract Structured Memory

Use the memory extractor to parse dialogues, files, or documents into multiple TextualMemoryItem.

scene_data = [[
    {"role": "user", "content": "Tell me about your childhood."},
    {"role": "assistant", "content": "I loved playing in the garden with my dog."}
]]

memories = preference_memory.get_memory(scene_data, type="chat", info={"user_id": "1234"})
preference_memory.add(memories)

Search Memory

results = preference_memory.search("Tell me more about the user", top_k=2)

Backup and Restore

Support persistent storage and on-demand reloading of preference memories:

preference_memory.dump("tmp/pref_memories")
preference_memory.load("tmp/pref_memories")

GeneralTextMemory is a flexible, vector-based textual memory module in MemOS, designed for storing, searching, and managing unstructured knowledge. It is suitable for conversational agents, personal assistants, and any system requiring semantic memory retrieval.

Tree Textual Memory