MemoryOS 0.0.1__py3-none-any.whl → 0.1.13__py3-none-any.whl

memos/memories/textual/tree_text_memory/retrieve/searcher.py

@@ -0,0 +1,208 @@
+import concurrent.futures
+import json
+
+from datetime import datetime
+
+from memos.embedders.factory import OllamaEmbedder
+from memos.graph_dbs.factory import Neo4jGraphDB
+from memos.llms.factory import OllamaLLM, OpenAILLM
+from memos.memories.textual.item import SearchedTreeNodeTextualMemoryMetadata, TextualMemoryItem
+
+from .internet_retriever_factory import InternetRetrieverFactory
+from .reasoner import MemoryReasoner
+from .recall import GraphMemoryRetriever
+from .reranker import MemoryReranker
+from .task_goal_parser import TaskGoalParser
+
+
+class Searcher:
+    def __init__(
+        self,
+        dispatcher_llm: OpenAILLM | OllamaLLM,
+        graph_store: Neo4jGraphDB,
+        embedder: OllamaEmbedder,
+        internet_retriever: InternetRetrieverFactory | None = None,
+    ):
+        self.graph_store = graph_store
+        self.embedder = embedder
+
+        self.task_goal_parser = TaskGoalParser(dispatcher_llm)
+        self.graph_retriever = GraphMemoryRetriever(self.graph_store, self.embedder)
+        self.reranker = MemoryReranker(dispatcher_llm, self.embedder)
+        self.reasoner = MemoryReasoner(dispatcher_llm)
+
+        # Create internet retriever from config if provided
+        self.internet_retriever = internet_retriever
+
+    def search(
+        self, query: str, top_k: int, info=None, mode: str = "fast", memory_type: str = "All"
+    ) -> list[TextualMemoryItem]:
+        """
+        Search for memories based on a query.
+        User query -> TaskGoalParser -> GraphMemoryRetriever ->
+        MemoryReranker -> MemoryReasoner -> Final output
+        Args:
+            query (str): The query to search for.
+            top_k (int): The number of top results to return.
+            info (dict): Leave a record of memory consumption.
+            mode (str, optional): The mode of the search.
+            - 'fast': Uses a faster search process, sacrificing some precision for speed.
+            - 'fine': Uses a more detailed search process, invoking large models for higher precision, but slower performance.
+            memory_type (str): Type restriction for search.
+            ['All', 'WorkingMemory', 'LongTermMemory', 'UserMemory']
+        Returns:
+            list[TextualMemoryItem]: List of matching memories.
+        """
+
+        # Step 1: Parse task structure into topic, concept, and fact levels
+        context = []
+        if mode == "fine":
+            query_embedding = self.embedder.embed([query])[0]
+            related_node_ids = self.graph_store.search_by_embedding(query_embedding, top_k=top_k)
+            related_nodes = [
+                self.graph_store.get_node(related_node["id"]) for related_node in related_node_ids
+            ]
+
+            context = [related_node["memory"] for related_node in related_nodes]
+            context = list(set(context))
+
+        # Step 1a: Parse task structure into topic, concept, and fact levels
+        parsed_goal = self.task_goal_parser.parse(query, "\n".join(context))
+
+        if parsed_goal.memories:
+            query_embedding = self.embedder.embed(list({query, *parsed_goal.memories}))
+
+        # Step 2a: Working memory retrieval (Path A)
+        def retrieve_from_working_memory():
+            """
+            Direct structure-based retrieval from working memory.
+            """
+            if memory_type not in ["All", "WorkingMemory"]:
+                return []
+
+            working_memory = self.graph_retriever.retrieve(
+                query=query, parsed_goal=parsed_goal, top_k=top_k, memory_scope="WorkingMemory"
+            )
+            # Rerank working_memory results
+            ranked_memories = self.reranker.rerank(
+                query=query,
+                query_embedding=query_embedding[0],
+                graph_results=working_memory,
+                top_k=top_k,
+                parsed_goal=parsed_goal,
+            )
+            return ranked_memories
+
+        # Step 2b: Parallel long-term and user memory retrieval (Path B)
+        def retrieve_ranked_long_term_and_user():
+            """
+            Retrieve from both long-term and user memory, then rank and merge results.
+            """
+            long_term_items = (
+                self.graph_retriever.retrieve(
+                    query=query,
+                    query_embedding=query_embedding,
+                    parsed_goal=parsed_goal,
+                    top_k=top_k * 2,
+                    memory_scope="LongTermMemory",
+                )
+                if memory_type in ["All", "LongTermMemory"]
+                else []
+            )
+            user_items = (
+                self.graph_retriever.retrieve(
+                    query=query,
+                    query_embedding=query_embedding,
+                    parsed_goal=parsed_goal,
+                    top_k=top_k * 2,
+                    memory_scope="UserMemory",
+                )
+                if memory_type in ["All", "UserMemory"]
+                else []
+            )
+
+            # Rerank combined results
+            ranked_memories = self.reranker.rerank(
+                query=query,
+                query_embedding=query_embedding[0],
+                graph_results=long_term_items + user_items,
+                top_k=top_k * 2,
+                parsed_goal=parsed_goal,
+            )
+            return ranked_memories
+
+        # Step 2c: Internet retrieval (Path C)
+        def retrieve_from_internet():
+            """
+            Retrieve information from the internet using Google Custom Search API.
+            """
+            if not self.internet_retriever:
+                return []
+            if memory_type not in ["All"]:
+                return []
+            internet_items = self.internet_retriever.retrieve_from_internet(
+                query=query, top_k=top_k, parsed_goal=parsed_goal
+            )
+
+            # Convert to the format expected by reranker
+            ranked_memories = self.reranker.rerank(
+                query=query,
+                query_embedding=query_embedding[0],
+                graph_results=internet_items,
+                top_k=top_k * 2,
+                parsed_goal=parsed_goal,
+            )
+            return ranked_memories
+
+        # Step 3: Parallel execution of all paths
+        with concurrent.futures.ThreadPoolExecutor(max_workers=3) as executor:
+            future_working = executor.submit(retrieve_from_working_memory)
+            future_hybrid = executor.submit(retrieve_ranked_long_term_and_user)
+            future_internet = executor.submit(retrieve_from_internet)
+
+            working_results = future_working.result()
+            hybrid_results = future_hybrid.result()
+            internet_results = future_internet.result()
+            searched_res = working_results + hybrid_results + internet_results
+
+        # Deduplicate by item.memory, keep higher score
+        deduped_result = {}
+        for item, score in searched_res:
+            mem_key = item.memory
+            if mem_key not in deduped_result or score > deduped_result[mem_key][1]:
+                deduped_result[mem_key] = (item, score)
+
+        searched_res = []
+        for item, score in sorted(deduped_result.values(), key=lambda pair: pair[1], reverse=True)[
+            :top_k
+        ]:
+            new_meta = SearchedTreeNodeTextualMemoryMetadata(
+                **item.metadata.model_dump(), relativity=score
+            )
+            searched_res.append(
+                TextualMemoryItem(id=item.id, memory=item.memory, metadata=new_meta)
+            )
+
+        # Step 4: Reasoning over all retrieved and ranked memory
+        if mode == "fine":
+            searched_res = self.reasoner.reason(
+                query=query,
+                ranked_memories=searched_res,
+                parsed_goal=parsed_goal,
+            )
+
+        # Step 5: Update usage history with current timestamp
+        now_time = datetime.now().isoformat()
+        usage_record = json.dumps(
+            {"time": now_time, "info": info}
+        )  # `info` should be a serializable dict or string
+
+        for item in searched_res:
+            if (
+                hasattr(item, "id")
+                and hasattr(item, "metadata")
+                and hasattr(item.metadata, "usage")
+            ):
+                item.metadata.usage.append(usage_record)
+                self.graph_store.update_node(item.id, {"usage": item.metadata.usage})
+        return searched_res

memos/memories/textual/tree_text_memory/retrieve/task_goal_parser.py

@@ -0,0 +1,68 @@
+import json
+
+from string import Template
+
+from memos.llms.base import BaseLLM
+from memos.memories.textual.tree_text_memory.retrieve.retrieval_mid_structs import ParsedTaskGoal
+from memos.memories.textual.tree_text_memory.retrieve.utils import TASK_PARSE_PROMPT
+
+
+class TaskGoalParser:
+    """
+    Unified TaskGoalParser:
+    - mode == 'fast': directly use origin task_description
+    - mode == 'fine': use LLM to parse structured topic/keys/tags
+    """
+
+    def __init__(self, llm=BaseLLM, mode: str = "fast"):
+        self.llm = llm
+        self.mode = mode
+
+    def parse(self, task_description: str, context: str = "") -> ParsedTaskGoal:
+        """
+        Parse user input into structured semantic layers.
+        Returns:
+            ParsedTaskGoal: object containing topic/concept/fact levels and optional metadata
+        - mode == 'fast': use jieba to split words only
+        - mode == 'fine': use LLM to parse structured topic/keys/tags
+        """
+        if self.mode == "fast":
+            return self._parse_fast(task_description)
+        elif self.mode == "fine":
+            if not self.llm:
+                raise ValueError("LLM not provided for slow mode.")
+            return self._parse_fine(task_description, context)
+        else:
+            raise ValueError(f"Unknown mode: {self.mode}")
+
+    def _parse_fast(self, task_description: str, limit_num: int = 5) -> ParsedTaskGoal:
+        """
+        Fast mode: simple jieba word split.
+        """
+        return ParsedTaskGoal(
+            memories=[task_description], keys=[task_description], tags=[], goal_type="default"
+        )
+
+    def _parse_fine(self, query: str, context: str = "") -> ParsedTaskGoal:
+        """
+        Slow mode: LLM structured parse.
+        """
+        prompt = Template(TASK_PARSE_PROMPT).substitute(task=query.strip(), context=context)
+        response = self.llm.generate(messages=[{"role": "user", "content": prompt}])
+        return self._parse_response(response)
+
+    def _parse_response(self, response: str) -> ParsedTaskGoal:
+        """
+        Parse LLM JSON output safely.
+        """
+        try:
+            response = response.replace("```", "").replace("json", "")
+            response_json = json.loads(response.strip())
+            return ParsedTaskGoal(
+                memories=response_json.get("memories", []),
+                keys=response_json.get("keys", []),
+                tags=response_json.get("tags", []),
+                goal_type=response_json.get("goal_type", "default"),
+            )
+        except Exception as e:
+            raise ValueError(f"Failed to parse LLM output: {e}\nRaw response:\n{response}") from e

memos/memories/textual/tree_text_memory/retrieve/utils.py

@@ -0,0 +1,48 @@
+# Prompt for task parsing
+TASK_PARSE_PROMPT = """
+You are a task parsing expert. Given a user's task instruction, extract the following structured information:
+
+Given a user task instruction and optional related memory context,
+extract the following structured information:
+1. Keys: the high-level keywords directly relevant to the user’s task.
+2. Tags: thematic tags to help categorize and retrieve related memories.
+3. Goal Type: retrieval | qa | generation
+4. Memories: Provide 2–5 short semantic expansions or rephrasings of the task instruction.
+   These are used for improved embedding search coverage.
+   Each should be clear, concise, and meaningful for retrieval.
+
+Task description:
+\"\"\"$task\"\"\"
+
+Context (if any):
+\"\"\"$context\"\"\"
+
+Return strictly in this JSON format:
+{
+  "keys": [...],
+  "tags": [...],
+  "goal_type": "retrieval | qa | generation",
+  "memories": ["...", "...", ...]
+}
+"""
+
+
+REASON_PROMPT = """
+You are a reasoning agent working with a memory system. You will synthesize knowledge from multiple memory cards to construct a meaningful response to the task below.
+
+Task: ${task}
+
+Memory cards (with metadata):
+${detailed_memory_list}
+
+Please perform:
+1. Clustering by theme (topic/concept/fact)
+2. Identify useful chains or connections
+3. Return a curated list of memory card IDs with reasons.
+
+Output in JSON:
+{
+  "selected_ids": [...],
+  "explanation": "..."
+}
+"""

memos/memories/textual/tree_text_memory/retrieve/xinyusearch.py

@@ -0,0 +1,335 @@
+"""Xinyu Search API retriever for tree text memory."""
+
+import json
+import uuid
+
+from datetime import datetime
+
+import requests
+
+from memos.embedders.factory import OllamaEmbedder
+from memos.log import get_logger
+from memos.memories.textual.item import TextualMemoryItem, TreeNodeTextualMemoryMetadata
+
+
+logger = get_logger(__name__)
+
+
+class XinyuSearchAPI:
+    """Xinyu Search API Client"""
+
+    def __init__(self, access_key: str, search_engine_id: str, max_results: int = 20):
+        """
+        Initialize Xinyu Search API client
+
+        Args:
+            access_key: Xinyu API access key
+            max_results: Maximum number of results to retrieve
+        """
+        self.access_key = access_key
+        self.max_results = max_results
+
+        # API configuration
+        self.config = {"url": search_engine_id}
+
+        self.headers = {
+            "User-Agent": "PostmanRuntime/7.39.0",
+            "Content-Type": "application/json",
+            "Accept": "*/*",
+            "Accept-Encoding": "gzip, deflate, br",
+            "Connection": "keep-alive",
+            "token": access_key,
+        }
+
+    def query_detail(self, body: dict | None = None, detail: bool = True) -> list[dict]:
+        """
+        Query Xinyu search API for detailed results
+
+        Args:
+            body: Search parameters
+            detail: Whether to get detailed results
+
+        Returns:
+            List of search results
+        """
+        res = []
+        try:
+            url = self.config["url"]
+
+            params = json.dumps(body)
+            resp = requests.request("POST", url, headers=self.headers, data=params)
+            res = json.loads(resp.text)["results"]
+
+            # If detail interface, return online part
+            if "search_type" in body:
+                res = res["online"]
+
+            if not detail:
+                for res_i in res:
+                    res_i["summary"] = "「SUMMARY」" + res_i.get("summary", "")
+
+        except Exception:
+            import traceback
+
+            logger.error(f"xinyu search error: {traceback.format_exc()}")
+        return res
+
+    def search(self, query: str, max_results: int | None = None) -> list[dict]:
+        """
+        Execute search request
+
+        Args:
+            query: Search query
+            max_results: Maximum number of results to return
+
+        Returns:
+            List of search results
+        """
+        if max_results is None:
+            max_results = self.max_results
+
+        body = {
+            "search_type": ["online"],
+            "online_search": {
+                "max_entries": max_results,
+                "cache_switch": False,
+                "baidu_field": {"switch": True, "mode": "relevance", "type": "page"},
+                "bing_field": {"switch": False, "mode": "relevance", "type": "page_web"},
+                "sogou_field": {"switch": False, "mode": "relevance", "type": "page"},
+            },
+            "request_id": "memos" + str(uuid.uuid4()),
+            "queries": query,
+        }
+
+        return self.query_detail(body)
+
+
+class XinyuSearchRetriever:
+    """Xinyu Search retriever that converts search results to TextualMemoryItem format"""
+
+    def __init__(
+        self,
+        access_key: str,
+        search_engine_id: str,
+        embedder: OllamaEmbedder,
+        max_results: int = 20,
+    ):
+        """
+        Initialize Xinyu search retriever
+
+        Args:
+            access_key: Xinyu API access key
+            embedder: Embedder instance for generating embeddings
+            max_results: Maximum number of results to retrieve
+        """
+        self.xinyu_api = XinyuSearchAPI(access_key, search_engine_id, max_results=max_results)
+        self.embedder = embedder
+
+    def retrieve_from_internet(
+        self, query: str, top_k: int = 10, parsed_goal=None
+    ) -> list[TextualMemoryItem]:
+        """
+        Retrieve information from Xinyu search and convert to TextualMemoryItem format
+
+        Args:
+            query: Search query
+            top_k: Number of results to return
+            parsed_goal: Parsed task goal (optional)
+
+        Returns:
+            List of TextualMemoryItem
+        """
+        # Get search results
+        search_results = self.xinyu_api.search(query, max_results=top_k)
+
+        # Convert to TextualMemoryItem format
+        memory_items = []
+
+        for _, result in enumerate(search_results):
+            # Extract basic information from Xinyu response format
+            title = result.get("title", "")
+            content = result.get("content", "")
+            summary = result.get("summary", "")
+            url = result.get("url", "")
+            publish_time = result.get("publish_time", "")
+            if publish_time:
+                try:
+                    publish_time = datetime.strptime(publish_time, "%Y-%m-%d %H:%M:%S").strftime(
+                        "%Y-%m-%d"
+                    )
+                except Exception as e:
+                    logger.error(f"xinyu search error: {e}")
+                    publish_time = datetime.now().strftime("%Y-%m-%d")
+            else:
+                publish_time = datetime.now().strftime("%Y-%m-%d")
+            source = result.get("source", "")
+            site = result.get("site", "")
+            if site:
+                site = site.split("|")[0]
+
+            # Combine memory content
+            memory_content = (
+                f"Title: {title}\nSummary: {summary}\nContent: {content[:200]}...\nSource: {url}"
+            )
+
+            # Create metadata
+            metadata = TreeNodeTextualMemoryMetadata(
+                user_id=None,
+                session_id=None,
+                status="activated",
+                type="fact",  # Search results are usually factual information
+                memory_time=publish_time,
+                source="web",
+                confidence=85.0,  # Confidence level for search information
+                entities=self._extract_entities(title, content, summary),
+                tags=self._extract_tags(title, content, summary, parsed_goal),
+                visibility="public",
+                memory_type="LongTermMemory",  # Search results as working memory
+                key=title,
+                sources=[url] if url else [],
+                embedding=self.embedder.embed([memory_content])[0],
+                created_at=datetime.now().isoformat(),
+                usage=[],
+                background=f"Xinyu search result from {site or source}",
+            )
+            # Create TextualMemoryItem
+            memory_item = TextualMemoryItem(
+                id=str(uuid.uuid4()), memory=memory_content, metadata=metadata
+            )
+
+            memory_items.append(memory_item)
+
+        return memory_items
+
+    def _extract_entities(self, title: str, content: str, summary: str) -> list[str]:
+        """
+        Extract entities from title, content and summary
+
+        Args:
+            title: Article title
+            content: Article content
+            summary: Article summary
+
+        Returns:
+            List of extracted entities
+        """
+        # Simple entity extraction - can be enhanced with NER
+        text = f"{title} {content} {summary}"
+        entities = []
+
+        # Extract potential entities (simple approach)
+        # This can be enhanced with proper NER models
+        words = text.split()
+        for word in words:
+            if len(word) > 2 and word[0].isupper():
+                entities.append(word)
+
+        return list(set(entities))[:10]  # Limit to 10 entities
+
+    def _extract_tags(self, title: str, content: str, summary: str, parsed_goal=None) -> list[str]:
+        """
+        Extract tags from title, content and summary
+
+        Args:
+            title: Article title
+            content: Article content
+            summary: Article summary
+            parsed_goal: Parsed task goal (optional)
+
+        Returns:
+            List of extracted tags
+        """
+        tags = []
+
+        # Add source-based tags
+        tags.append("xinyu_search")
+        tags.append("news")
+
+        # Add content-based tags
+        text = f"{title} {content} {summary}".lower()
+
+        # Simple keyword-based tagging
+        keywords = {
+            "economy": [
+                "economy",
+                "GDP",
+                "growth",
+                "production",
+                "industry",
+                "investment",
+                "consumption",
+                "market",
+                "trade",
+                "finance",
+            ],
+            "politics": [
+                "politics",
+                "government",
+                "policy",
+                "meeting",
+                "leader",
+                "election",
+                "parliament",
+                "ministry",
+            ],
+            "technology": [
+                "technology",
+                "tech",
+                "innovation",
+                "digital",
+                "internet",
+                "AI",
+                "artificial intelligence",
+                "software",
+                "hardware",
+            ],
+            "sports": [
+                "sports",
+                "game",
+                "athlete",
+                "olympic",
+                "championship",
+                "tournament",
+                "team",
+                "player",
+            ],
+            "culture": [
+                "culture",
+                "education",
+                "art",
+                "history",
+                "literature",
+                "music",
+                "film",
+                "museum",
+            ],
+            "health": [
+                "health",
+                "medical",
+                "pandemic",
+                "hospital",
+                "doctor",
+                "medicine",
+                "disease",
+                "treatment",
+            ],
+            "environment": [
+                "environment",
+                "ecology",
+                "pollution",
+                "green",
+                "climate",
+                "sustainability",
+                "renewable",
+            ],
+        }
+
+        for category, words in keywords.items():
+            if any(word in text for word in words):
+                tags.append(category)
+
+        # Add goal-based tags if available
+        if parsed_goal and hasattr(parsed_goal, "tags"):
+            tags.extend(parsed_goal.tags)
+
+        return list(set(tags))[:15]  # Limit to 15 tags

memos/parsers/base.py

@@ -0,0 +1,15 @@
+from abc import ABC, abstractmethod
+
+from memos.configs.parser import BaseParserConfig
+
+
+class BaseParser(ABC):
+    """Base class for all parsers."""
+
+    @abstractmethod
+    def __init__(self, config: BaseParserConfig):
+        """Initialize the parser with the given configuration."""
+
+    @abstractmethod
+    def parse(self, file_path: str) -> str:
+        """Parse the file at the given path and return its content as a string."""

memos/parsers/factory.py

@@ -0,0 +1,19 @@
+from typing import Any, ClassVar
+
+from memos.configs.parser import ParserConfigFactory
+from memos.parsers.base import BaseParser
+from memos.parsers.markitdown import MarkItDownParser
+
+
+class ParserFactory(BaseParser):
+    """Factory class for creating Parser instances."""
+
+    backend_to_class: ClassVar[dict[str, Any]] = {"markitdown": MarkItDownParser}
+
+    @classmethod
+    def from_config(cls, config_factory: ParserConfigFactory) -> BaseParser:
+        backend = config_factory.backend
+        if backend not in cls.backend_to_class:
+            raise ValueError(f"Invalid backend: {backend}")
+        parser_class = cls.backend_to_class[backend]
+        return parser_class(config_factory.config)