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

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

@@ -0,0 +1,158 @@
+import concurrent.futures
+
+from memos.embedders.factory import OllamaEmbedder
+from memos.graph_dbs.neo4j import Neo4jGraphDB
+from memos.memories.textual.item import TextualMemoryItem
+from memos.memories.textual.tree_text_memory.retrieve.retrieval_mid_structs import ParsedTaskGoal
+
+
+class GraphMemoryRetriever:
+    """
+    Unified memory retriever that combines both graph-based and vector-based retrieval logic.
+    """
+
+    def __init__(self, graph_store: Neo4jGraphDB, embedder: OllamaEmbedder):
+        self.graph_store = graph_store
+        self.embedder = embedder
+
+    def retrieve(
+        self,
+        query: str,
+        parsed_goal: ParsedTaskGoal,
+        top_k: int,
+        memory_scope: str,
+        query_embedding: list[list[float]] | None = None,
+    ) -> list[TextualMemoryItem]:
+        """
+        Perform hybrid memory retrieval:
+        - Run graph-based lookup from dispatch plan.
+        - Run vector similarity search from embedded query.
+        - Merge and return combined result set.
+
+        Args:
+            query (str): Original task query.
+            parsed_goal (dict): parsed_goal.
+            top_k (int): Number of candidates to return.
+            memory_scope (str): One of ['working', 'long_term', 'user'].
+            query_embedding(list of embedding): list of embedding of query
+
+        Returns:
+            list: Combined memory items.
+        """
+        if memory_scope not in ["WorkingMemory", "LongTermMemory", "UserMemory"]:
+            raise ValueError(f"Unsupported memory scope: {memory_scope}")
+
+        if memory_scope == "WorkingMemory":
+            # For working memory, retrieve all entries (no filtering)
+            working_memories = self.graph_store.get_all_memory_items(scope="WorkingMemory")
+            return [TextualMemoryItem.from_dict(record) for record in working_memories]
+
+        # Step 1: Structured graph-based retrieval
+        graph_results = self._graph_recall(parsed_goal, memory_scope)
+
+        # Step 2: Vector similarity search
+        vector_results = self._vector_recall(query_embedding, memory_scope, top_k)
+
+        # Step 3: Merge and deduplicate results
+        combined = {item.id: item for item in graph_results + vector_results}
+
+        # Debug: 打印在 graph_results 中但不在 combined 中的 id
+        graph_ids = {item.id for item in graph_results}
+        combined_ids = set(combined.keys())
+        lost_ids = graph_ids - combined_ids
+
+        if lost_ids:
+            print(
+                f"[DEBUG] The following nodes were in graph_results but missing in combined: {lost_ids}"
+            )
+
+        return list(combined.values())
+
+    def _graph_recall(
+        self, parsed_goal: ParsedTaskGoal, memory_scope: str
+    ) -> list[TextualMemoryItem]:
+        """
+        Perform structured node-based retrieval from Neo4j.
+        - keys must match exactly (n.key IN keys)
+        - tags must overlap with at least 2 input tags
+        - scope filters by memory_type if provided
+        """
+        candidate_ids = set()
+
+        # 1) key-based OR branch
+        if parsed_goal.keys:
+            key_filters = [
+                {"field": "key", "op": "in", "value": parsed_goal.keys},
+                {"field": "memory_type", "op": "=", "value": memory_scope},
+            ]
+            key_ids = self.graph_store.get_by_metadata(key_filters)
+            candidate_ids.update(key_ids)
+
+        # 2) tag-based OR branch
+        if parsed_goal.tags:
+            tag_filters = [
+                {"field": "tags", "op": "contains", "value": parsed_goal.tags},
+                {"field": "memory_type", "op": "=", "value": memory_scope},
+            ]
+            tag_ids = self.graph_store.get_by_metadata(tag_filters)
+            candidate_ids.update(tag_ids)
+
+        # No matches → return empty
+        if not candidate_ids:
+            return []
+
+        # Load nodes and post-filter
+        node_dicts = self.graph_store.get_nodes(list(candidate_ids))
+
+        final_nodes = []
+        for node in node_dicts:
+            meta = node.get("metadata", {})
+            node_key = meta.get("key")
+            node_tags = meta.get("tags", []) or []
+
+            keep = False
+            # key equals to node_key
+            if parsed_goal.keys and node_key in parsed_goal.keys:
+                keep = True
+            # overlap tags more than 2
+            elif parsed_goal.tags:
+                overlap = len(set(node_tags) & set(parsed_goal.tags))
+                if overlap >= 2:
+                    keep = True
+            if keep:
+                final_nodes.append(TextualMemoryItem.from_dict(node))
+        return final_nodes
+
+    def _vector_recall(
+        self,
+        query_embedding: list[list[float]],
+        memory_scope: str,
+        top_k: int = 20,
+        max_num: int = 5,
+    ) -> list[TextualMemoryItem]:
+        """
+        # TODO: tackle with post-filter and pre-filter(5.18+) better.
+        Perform vector-based similarity retrieval using query embedding.
+        """
+        all_matches = []
+
+        def search_single(vec):
+            return (
+                self.graph_store.search_by_embedding(vector=vec, top_k=top_k, scope=memory_scope)
+                or []
+            )
+
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            futures = [executor.submit(search_single, vec) for vec in query_embedding[:max_num]]
+            for future in concurrent.futures.as_completed(futures):
+                result = future.result()
+                all_matches.extend(result)
+
+        if not all_matches:
+            return []
+
+        # Step 3: Extract matched IDs and retrieve full nodes
+        unique_ids = set({r["id"] for r in all_matches})
+        node_dicts = self.graph_store.get_nodes(list(unique_ids))
+
+        return [TextualMemoryItem.from_dict(record) for record in node_dicts]

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

@@ -0,0 +1,111 @@
+import numpy as np
+
+from memos.embedders.factory import OllamaEmbedder
+from memos.llms.factory import OllamaLLM, OpenAILLM
+from memos.memories.textual.item import TextualMemoryItem
+from memos.memories.textual.tree_text_memory.retrieve.retrieval_mid_structs import ParsedTaskGoal
+
+
+def batch_cosine_similarity(
+    query_vec: list[float], candidate_vecs: list[list[float]]
+) -> list[float]:
+    """
+    Compute cosine similarity between a single query vector and multiple candidate vectors using NumPy.
+
+    Args:
+        query_vec (list[float]): The query embedding.
+        candidate_vecs (list[list[float]]): A list of memory embeddings.
+
+    Returns:
+        list[float]: Cosine similarity scores for each candidate.
+    """
+    query = np.array(query_vec)
+    candidates = np.array(candidate_vecs)
+
+    # Normalize query and candidates
+    query_norm = np.linalg.norm(query)
+    candidates_norm = np.linalg.norm(candidates, axis=1)
+
+    # Compute dot products
+    dot_products = np.dot(candidates, query)
+
+    # Avoid division by zero
+    eps = 1e-10
+    similarities = dot_products / (candidates_norm * query_norm + eps)
+
+    return similarities.tolist()
+
+
+class MemoryReranker:
+    """
+    Rank retrieved memory cards by structural priority and contextual similarity.
+    """
+
+    def __init__(self, llm: OpenAILLM | OllamaLLM, embedder: OllamaEmbedder):
+        self.llm = llm
+        self.embedder = embedder
+
+        # Structural priority weights
+        self.level_weights = {
+            "topic": 1.0,
+            "concept": 1.0,
+            "fact": 1.0,
+        }
+
+    def rerank(
+        self,
+        query: str,
+        query_embedding: list[float],
+        graph_results: list,
+        top_k: int,
+        parsed_goal: ParsedTaskGoal,
+    ) -> list[tuple[TextualMemoryItem, float]]:
+        """
+        Rerank memory items by relevance to task.
+
+        Args:
+            query (str): Original task.
+            query_embedding(list[float]): embedding of query
+            graph_results (list): Combined retrieval results.
+            top_k (int): Number of top results to return.
+            parsed_goal (dict): Structured task representation.
+
+        Returns:
+            list(tuple): Ranked list of memory items with similarity score.
+        """
+        # Step 1: Filter out items without embeddings
+        items_with_embeddings = [item for item in graph_results if item.metadata.embedding]
+        embeddings = [item.metadata.embedding for item in items_with_embeddings]
+
+        if not embeddings:
+            return graph_results[:top_k]
+
+        # Step 2: Compute cosine similarities
+        similarity_scores = batch_cosine_similarity(query_embedding, embeddings)
+
+        # Step 3: Apply structural weight boost
+        def get_weight(item: TextualMemoryItem) -> float:
+            level = item.metadata.background
+            return self.level_weights.get(level, 1.0)
+
+        weighted_scores = [
+            sim * get_weight(item)
+            for sim, item in zip(similarity_scores, items_with_embeddings, strict=False)
+        ]
+
+        # Step 4: Sort by weighted score
+        sorted_items = sorted(
+            zip(items_with_embeddings, weighted_scores, strict=False),
+            key=lambda pair: pair[1],
+            reverse=True,
+        )
+
+        # Step 5: Return top-k items with fallback
+        top_items = sorted_items[:top_k]
+
+        if len(top_items) < top_k:
+            selected_items = [item for item, _ in top_items]
+            remaining = [(item, -1.0) for item in graph_results if item not in selected_items]
+            top_items.extend(remaining[: top_k - len(top_items)])
+
+        return top_items  # list of (item, score)

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

@@ -0,0 +1,13 @@
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ParsedTaskGoal:
+    """
+    Goal structure for both Fast & LLM.
+    """
+
+    memories: list[str] = field(default_factory=list)
+    keys: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+    goal_type: str | None = None  # e.g., 'default', 'explanation', etc.

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

@@ -0,0 +1,166 @@
+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 .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,
+    ):
+        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)
+
+    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
+        parsed_goal = self.task_goal_parser.parse(query)
+
+        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 3: Parallel execution of both paths
+        with concurrent.futures.ThreadPoolExecutor(max_workers=2) as executor:
+            future_working = executor.submit(retrieve_from_working_memory)
+            future_hybrid = executor.submit(retrieve_ranked_long_term_and_user)
+
+            working_results = future_working.result()
+            hybrid_results = future_hybrid.result()
+            searched_res = working_results + hybrid_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)
+        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) -> ParsedTaskGoal:
+        """
+        Slow mode: LLM structured parse.
+        """
+        prompt = Template(TASK_PARSE_PROMPT).substitute(task=query.strip(), 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/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)

memos/parsers/markitdown.py

@@ -0,0 +1,22 @@
+from markitdown import MarkItDown
+
+from memos.configs.parser import MarkItDownParserConfig
+from memos.log import get_logger
+from memos.parsers.base import BaseParser
+
+
+logger = get_logger(__name__)
+
+
+class MarkItDownParser(BaseParser):
+    """MarkItDown Parser class."""
+
+    def __init__(self, config: MarkItDownParserConfig):
+        self.config = config
+
+    def parse(self, file_path: str) -> str:
+        """Parse the file at the given path and return its content as a MarkDown string."""
+        md = MarkItDown(enable_plugins=False)
+        result = md.convert(file_path)
+
+        return result.text_content

memos/settings.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+
+MEMOS_DIR = Path.cwd() / ".memos"
+DEBUG = False
+
+# "memos" or "memos.submodules" ... to filter logs from specific packages
+LOG_FILTER_TREE_PREFIX = ""