MemoryOS 2.0.3__py3-none-any.whl

memos/mem_os/utils/reference_utils.py

@@ -0,0 +1,162 @@
+from memos.memories.textual.item import (
+    TextualMemoryItem,
+)
+
+
+def split_continuous_references(text: str) -> str:
+    """
+    Split continuous reference tags into individual reference tags.
+
+    Converts patterns like [1:92ff35fb, 4:bfe6f044] to [1:92ff35fb] [4:bfe6f044]
+
+    Only processes text if:
+    1. '[' appears exactly once
+    2. ']' appears exactly once
+    3. Contains commas between '[' and ']'
+
+    Args:
+        text (str): Text containing reference tags
+
+    Returns:
+        str: Text with split reference tags, or original text if conditions not met
+    """
+    # Early return if text is empty
+    if not text:
+        return text
+    # Check if '[' appears exactly once
+    if text.count("[") != 1:
+        return text
+    # Check if ']' appears exactly once
+    if text.count("]") != 1:
+        return text
+    # Find positions of brackets
+    open_bracket_pos = text.find("[")
+    close_bracket_pos = text.find("]")
+
+    # Check if brackets are in correct order
+    if open_bracket_pos >= close_bracket_pos:
+        return text
+    # Extract content between brackets
+    content_between_brackets = text[open_bracket_pos + 1 : close_bracket_pos]
+    # Check if there's a comma between brackets
+    if "," not in content_between_brackets:
+        return text
+    text = text.replace(content_between_brackets, content_between_brackets.replace(", ", "]["))
+    text = text.replace(content_between_brackets, content_between_brackets.replace(",", "]["))
+
+    return text
+
+
+def process_streaming_references_complete(text_buffer: str) -> tuple[str, str]:
+    """
+    Complete streaming reference processing to ensure reference tags are never split.
+
+    Args:
+        text_buffer (str): The accumulated text buffer.
+
+    Returns:
+        tuple[str, str]: (processed_text, remaining_buffer)
+    """
+    import re
+
+    # Pattern to match complete reference tags: [refid:memoriesID]
+    complete_pattern = r"\[\d+:[^\]]+\]"
+
+    # Find all complete reference tags
+    complete_matches = list(re.finditer(complete_pattern, text_buffer))
+
+    if complete_matches:
+        # Find the last complete tag
+        last_match = complete_matches[-1]
+        end_pos = last_match.end()
+
+        # Check if there's any incomplete reference after the last complete one
+        remaining_text = text_buffer[end_pos:]
+
+        # Look for potential incomplete reference patterns after the last complete tag
+        incomplete_pattern = r"\[\d*:?[^\]]*$"
+        if re.search(incomplete_pattern, remaining_text):
+            # There's a potential incomplete reference, find where it starts
+            incomplete_match = re.search(incomplete_pattern, remaining_text)
+            if incomplete_match:
+                incomplete_start = end_pos + incomplete_match.start()
+                processed_text = text_buffer[:incomplete_start]
+                remaining_buffer = text_buffer[incomplete_start:]
+
+                # Apply reference splitting to the processed text
+                processed_text = split_continuous_references(processed_text)
+                return processed_text, remaining_buffer
+
+        # No incomplete reference after the last complete tag, process all
+        processed_text = split_continuous_references(text_buffer)
+        return processed_text, ""
+
+    # Check for incomplete reference tags - be more specific about what constitutes a potential reference
+    # Look for opening bracket with number and colon that could be a reference tag
+    opening_pattern = r"\[\d+:"
+    opening_matches = list(re.finditer(opening_pattern, text_buffer))
+
+    if opening_matches:
+        # Find the last opening tag
+        last_opening = opening_matches[-1]
+        opening_start = last_opening.start()
+
+        # Check if this might be a complete reference tag (has closing bracket after the pattern)
+        remaining_text = text_buffer[last_opening.end() :]
+        if "]" in remaining_text:
+            # This looks like a complete reference tag, process it
+            processed_text = split_continuous_references(text_buffer)
+            return processed_text, ""
+        else:
+            # Incomplete reference tag, keep it in buffer
+            processed_text = text_buffer[:opening_start]
+            processed_text = split_continuous_references(processed_text)
+            return processed_text, text_buffer[opening_start:]
+
+    # More sophisticated check for potential reference patterns
+    # Only hold back text if we see a pattern that could be the start of a reference tag
+    potential_ref_pattern = r"\[\d*:?$"  # Matches [, [1, [12:, etc. at end of buffer
+    if re.search(potential_ref_pattern, text_buffer):
+        # Find the position of the potential reference start
+        match = re.search(potential_ref_pattern, text_buffer)
+        if match:
+            ref_start = match.start()
+            processed_text = text_buffer[:ref_start]
+            processed_text = split_continuous_references(processed_text)
+            return processed_text, text_buffer[ref_start:]
+
+    # Check for standalone [ only at the very end of the buffer
+    # This prevents cutting off mathematical expressions like [ \Delta U = Q - W ]
+    if text_buffer.endswith("["):
+        # Only hold back the single [ character
+        processed_text = text_buffer[:-1]
+        processed_text = split_continuous_references(processed_text)
+        return processed_text, "["
+
+    # No reference-like patterns found, process all text
+    processed_text = split_continuous_references(text_buffer)
+    return processed_text, ""
+
+
+def prepare_reference_data(memories_list: list[TextualMemoryItem]) -> list[dict]:
+    # Prepare reference data
+    reference = []
+    for memories in memories_list:
+        if isinstance(memories, TextualMemoryItem):
+            memories_json = memories.model_dump()
+            memories_json["metadata"]["ref_id"] = f"{memories.id.split('-')[0]}"
+            memories_json["metadata"]["embedding"] = []
+            memories_json["metadata"]["sources"] = []
+            memories_json["metadata"]["memory"] = memories.memory
+            memories_json["metadata"]["id"] = memories.id
+            reference.append({"metadata": memories_json["metadata"]})
+        else:
+            memories_json = memories
+            memories_json["metadata"]["ref_id"] = f"{memories_json['id'].split('-')[0]}"
+            memories_json["metadata"]["embedding"] = []
+            memories_json["metadata"]["sources"] = []
+            memories_json["metadata"]["memory"] = memories_json["memory"]
+            memories_json["metadata"]["id"] = memories_json["id"]
+            reference.append({"metadata": memories_json["metadata"]})
+
+    return reference

memos/mem_reader/base.py

@@ -0,0 +1,47 @@
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from memos.configs.mem_reader import BaseMemReaderConfig
+from memos.memories.textual.item import TextualMemoryItem
+
+
+if TYPE_CHECKING:
+    from memos.graph_dbs.base import BaseGraphDB
+
+
+class BaseMemReader(ABC):
+    """MemReader interface class for reading information."""
+
+    # Optional graph database for recall operations (for deduplication, conflict
+    # detection .etc)
+    graph_db: "BaseGraphDB | None" = None
+
+    @abstractmethod
+    def __init__(self, config: BaseMemReaderConfig):
+        """Initialize the MemReader with the given configuration."""
+
+    @abstractmethod
+    def set_graph_db(self, graph_db: "BaseGraphDB | None") -> None:
+        """
+        Set the graph database instance for recall operations.
+
+        This enables the mem-reader to perform:
+        - Semantic deduplication: avoid storing duplicate memories
+        - Conflict detection: detect contradictions with existing memories
+
+        Args:
+            graph_db: The graph database instance, or None to disable recall operations.
+        """
+
+    @abstractmethod
+    def get_memory(
+        self, scene_data: list, type: str, info: dict[str, Any], mode: str = "fast"
+    ) -> list[list[TextualMemoryItem]]:
+        """Various types of memories extracted from scene_data"""
+
+    @abstractmethod
+    def fine_transfer_simple_mem(
+        self, input_memories: list[list[TextualMemoryItem]], type: str
+    ) -> list[list[TextualMemoryItem]]:
+        """Fine Transform TextualMemoryItem List into another list of
+        TextualMemoryItem objects via calling llm to better understand users."""

memos/mem_reader/factory.py

@@ -0,0 +1,53 @@
+from typing import TYPE_CHECKING, Any, ClassVar, Optional
+
+from memos.configs.mem_reader import MemReaderConfigFactory
+from memos.mem_reader.base import BaseMemReader
+from memos.mem_reader.multi_modal_struct import MultiModalStructMemReader
+from memos.mem_reader.simple_struct import SimpleStructMemReader
+from memos.mem_reader.strategy_struct import StrategyStructMemReader
+from memos.memos_tools.singleton import singleton_factory
+
+
+if TYPE_CHECKING:
+    from memos.graph_dbs.base import BaseGraphDB
+
+
+class MemReaderFactory(BaseMemReader):
+    """Factory class for creating MemReader instances."""
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "simple_struct": SimpleStructMemReader,
+        "strategy_struct": StrategyStructMemReader,
+        "multimodal_struct": MultiModalStructMemReader,
+    }
+
+    @classmethod
+    @singleton_factory()
+    def from_config(
+        cls,
+        config_factory: MemReaderConfigFactory,
+        graph_db: Optional["BaseGraphDB | None"] = None,
+    ) -> BaseMemReader:
+        """
+        Create a MemReader instance from configuration.
+
+        Args:
+            config_factory: Configuration factory for the MemReader.
+            graph_db: Optional graph database instance for recall operations
+                     (deduplication, conflict detection). Can also be set later
+                     via reader.set_graph_db().
+
+        Returns:
+            Configured MemReader instance.
+        """
+        backend = config_factory.backend
+        if backend not in cls.backend_to_class:
+            raise ValueError(f"Invalid backend: {backend}")
+        reader_class = cls.backend_to_class[backend]
+        reader = reader_class(config_factory.config)
+
+        # Set graph_db if provided (for recall operations)
+        if graph_db is not None:
+            reader.set_graph_db(graph_db)
+
+        return reader

memos/mem_reader/memory.py

@@ -0,0 +1,298 @@
+from datetime import datetime
+from typing import Any
+
+from memos.llms.base import BaseLLM
+
+
+class Memory:
+    """Class representing the memory structure for storing and organizing memory content."""
+
+    def __init__(
+        self,
+        user_id: str,
+        session_id: str,
+        created_at: datetime,
+    ):
+        """
+        Initialize the Memory structure.
+
+        Args:
+            user_id: User identifier
+            session_id: Session identifier
+            created_at: Creation timestamp
+        """
+        self.objective_memory: dict[str, dict[str, Any]] = {}
+        self.subjective_memory: dict[str, dict[str, Any]] = {}
+        self.scene_memory = {
+            "qa_pair": {
+                "section": [],
+                "info": {
+                    "user_id": user_id,
+                    "session_id": session_id,
+                    "created_at": created_at,
+                    "summary": "",
+                    "label": [],
+                },
+            },
+            "document": {
+                "section": [],
+                "info": {
+                    "user_id": user_id,
+                    "session_id": session_id,
+                    "created_at": created_at,
+                    "doc_type": "",  # pdf, txt, etc.
+                    "doc_category": "",  # research_paper, news, etc.
+                    "doc_name": "",
+                    "summary": "",
+                    "label": [],
+                },
+            },
+        }
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Convert the Memory object to a dictionary.
+
+        Returns:
+            Dictionary representation of the Memory object
+        """
+        return {
+            "objective_memory": self.objective_memory,
+            "subjective_memory": self.subjective_memory,
+            "scene_memory": self.scene_memory,
+        }
+
+    def update_user_memory(
+        self,
+        memory_type: str,
+        key: str,
+        value: Any,
+        origin_data: str,
+        confidence_score: float = 1.0,
+        timestamp: str | None = None,
+    ) -> None:
+        """
+        Update a memory item in either objective_memory or subjective_memory.
+        If a key already exists, the new memory item's info will replace the existing one,
+        and the values will be connected.
+
+        Args:
+            memory_type: Type of memory to update ('objective' or 'subjective')
+            key: Key for the memory item. Must be one of:
+
+                | Memory Type       | Key                  | Description                                             |
+                |-------------------|----------------------|---------------------------------------------------------|
+                | objective_memory  | nickname             | User's preferred name or alias                          |
+                | objective_memory  | gender               | User's gender (male, female, other)                     |
+                | objective_memory  | personality          | User's personality traits or MBTI type                  |
+                | objective_memory  | birth                | User's birthdate or age information                     |
+                | objective_memory  | education            | User's educational background                           |
+                | objective_memory  | work                 | User's professional history                             |
+                | objective_memory  | achievement          | User's notable accomplishments                          |
+                | objective_memory  | occupation           | User's current job or role                              |
+                | objective_memory  | residence            | User's home location or living situation                |
+                | objective_memory  | location             | User's current geographical location                    |
+                | objective_memory  | income               | User's financial information                            |
+                | objective_memory  | preference           | User's likes and dislikes                               |
+                | objective_memory  | expertise            | User's skills and knowledge areas                       |
+                | objective_memory  | language             | User's language proficiency                             |
+                | objective_memory  | hobby                | User's recreational activities                          |
+                | objective_memory  | goal                 | User's long-term aspirations                            |
+                |-------------------|----------------------|---------------------------------------------------------|
+                | subjective_memory | current_mood         | User's current emotional state                          |
+                | subjective_memory | response_style       | User's preferred interaction style                      |
+                | subjective_memory | language_style       | User's language patterns and preferences                |
+                | subjective_memory | information_density  | User's preference for detail level in responses         |
+                | subjective_memory | interaction_pace     | User's preferred conversation speed and frequency       |
+                | subjective_memory | followed_topic       | Topics the user is currently interested in              |
+                | subjective_memory | current_goal         | User's immediate objectives in the conversation         |
+                | subjective_memory | content_type         | User's preferred field of interest (e.g., technology, finance, etc.)               |
+                | subjective_memory | role_preference      | User's preferred assistant role (e.g., domain expert, translation assistant, etc.) |
+
+            value: Value to store
+            origin_data: Original data that led to this memory
+            confidence_score: Confidence score (0.0 to 1.0)
+            timestamp: Timestamp string, if None current time will be used
+        """
+        if timestamp is None:
+            timestamp = datetime.now()
+
+        memory_item = {
+            "value": value,
+            "info": {
+                "timestamp": timestamp,
+                "confidence_score": confidence_score,
+                "origin_data": origin_data,
+            },
+        }
+
+        if memory_type == "objective":
+            memory_dict = self.objective_memory
+        elif memory_type == "subjective":
+            memory_dict = self.subjective_memory
+        else:
+            raise ValueError(
+                f"Invalid memory_type: {memory_type}. Must be 'objective' or 'subjective'."
+            )
+
+        # Check if key already exists
+        if key in memory_dict:
+            existing_item = memory_dict[key]
+
+            # Connect the values (keep history but present as a connected string)
+            combined_value = f"{existing_item['value']} | {value}"
+
+            # Update the memory item with combined value and new info (using the newest info)
+            memory_dict[key] = {
+                "value": combined_value,
+                "info": memory_item["info"],  # Use the new info
+            }
+        else:
+            # If key doesn't exist, simply add the new memory item
+            memory_dict[key] = memory_item
+
+    def add_qa_batch(
+        self, batch_summary: str, pair_summaries: list[dict], themes: list[str], order: int
+    ) -> None:
+        """
+        Add a batch of Q&A pairs to the scene memory as a single subsection.
+
+        Args:
+            batch_summary: The summary of the entire batch
+            pair_summaries: List of dictionaries, each containing:
+                - question: The summarized question for a single pair
+                - summary: The original dialogue for a single pair
+                - prompt: The prompt used for summarization
+                - time: The extracted time information (if any)
+            themes: List of themes associated with the batch
+            order: Order of the batch in the sequence
+        """
+        qa_subsection = {
+            "subsection": {},
+            "info": {
+                "summary": batch_summary,
+                "label": themes,
+                "origin_data": "",
+                "order": order,
+            },
+        }
+
+        for pair in pair_summaries:
+            qa_subsection["subsection"][pair["question"]] = {
+                "summary": pair["summary"],
+                "sources": pair["prompt"].split("\n\n", 1)[-1],
+                "time": pair.get("time", ""),  # Add time field with default empty string
+            }
+
+        self.scene_memory["qa_pair"]["section"].append(qa_subsection)
+
+    def add_document_chunk_group(
+        self, summary: str, label: list[str], order: int, sub_chunks: list
+    ) -> None:
+        """
+        Add a group of document chunks as a single section with multiple facts in the subsection.
+
+        Args:
+            summary: The summary of the large chunk
+            label: List of theme labels for the large chunk
+            order: Order of the large chunk in the sequence
+            sub_chunks: List of dictionaries containing small chunks information,
+                        each with keys: 'question', 'chunk_text', 'prompt'
+        """
+        doc_section = {
+            "subsection": {},
+            "info": {
+                "summary": summary,
+                "label": label,
+                "origin_data": "",
+                "order": order,
+            },
+        }
+
+        # Add each small chunk as a fact in the subsection
+        for sub_chunk in sub_chunks:
+            question = sub_chunk["question"]
+            doc_section["subsection"][question] = {
+                "summary": sub_chunk["chunk_text"],
+                "sources": sub_chunk["prompt"].split("\n\n", 1)[-1],
+            }
+
+        self.scene_memory["document"]["section"].append(doc_section)
+
+    def process_qa_pair_summaries(self, llm: BaseLLM | None = None) -> None:
+        """
+        Process all qa_pair subsection summaries to generate a section summary.
+
+        Args:
+            llm: Optional LLM instance to generate summary. If None, concatenates subsection summaries.
+        Returns:
+            The generated section summary
+        """
+        all_summaries = []
+        all_labels = set()
+
+        # Collect all subsection summaries and labels
+        for section in self.scene_memory["qa_pair"]["section"]:
+            if "info" in section and "summary" in section["info"]:
+                all_summaries.append(section["info"]["summary"])
+            if "info" in section and "label" in section["info"]:
+                all_labels.update(section["info"]["label"])
+
+        # Generate summary
+        if llm is not None:
+            # Use LLM to generate a coherent summary
+            all_summaries_str = "\n".join(all_summaries)
+            messages = [
+                {
+                    "role": "user",
+                    "content": f"Summarize this text into a concise and objective sentence that captures its main idea. Provide only the required content directly, without including any additional information.\n\n{all_summaries_str}",
+                }
+            ]
+            section_summary = llm.generate(messages)
+        else:
+            # Simple concatenation of summaries
+            section_summary = " ".join(all_summaries)
+
+        # Update the section info
+        self.scene_memory["qa_pair"]["info"]["summary"] = section_summary
+        self.scene_memory["qa_pair"]["info"]["label"] = list(all_labels)
+
+    def process_document_summaries(self, llm=None) -> str:
+        """
+        Process all document subsection summaries to generate a section summary.
+
+        Args:
+            llm: Optional LLM instance to generate summary. If None, concatenates subsection summaries.
+        Returns:
+            The generated section summary
+        """
+        all_summaries = []
+        all_labels = set()
+
+        # Collect all subsection summaries and labels
+        for section in self.scene_memory["document"]["section"]:
+            if "info" in section and "summary" in section["info"]:
+                all_summaries.append(section["info"]["summary"])
+            if "info" in section and "label" in section["info"]:
+                all_labels.update(section["info"]["label"])
+
+        # Generate summary
+        if llm is not None:
+            # Use LLM to generate a coherent summary
+            all_summaries_str = "\n".join(all_summaries)
+            messages = [
+                {
+                    "role": "user",
+                    "content": f"Summarize this text into a concise and objective sentence that captures its main idea. Provide only the required content directly, without including any additional information.\n\n{all_summaries_str}",
+                }
+            ]
+            section_summary = llm.generate(messages)
+        else:
+            # Simple concatenation of summaries
+            section_summary = " ".join(all_summaries)
+
+        # Update the section info
+        self.scene_memory["document"]["info"]["summary"] = section_summary
+        self.scene_memory["document"]["info"]["label"] = list(all_labels)
+
+        return section_summary