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

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 = ""

memos/templates/mem_reader_prompts.py

@@ -0,0 +1,98 @@
+SIMPLE_STRUCT_MEM_READER_PROMPT = """
+You are a memory extraction expert.
+
+Your task is to extract memories from the perspective of ${user_a}, based on a conversation between ${user_a} and ${user_b}. This means identifying what ${user_a} would plausibly remember — including their own experiences, thoughts, plans, or relevant statements and actions made by others (such as ${user_b}) that impacted or were acknowledged by ${user_a}.
+
+Please perform:
+1. Identify information that reflects ${user_a}'s experiences, beliefs, concerns, decisions, plans, or reactions — including meaningful input from ${user_b} that ${user_a} acknowledged or responded to.
+2. Resolve all time, person, and event references clearly:
+   - Convert relative time expressions (e.g., “yesterday,” “next Friday”) into absolute dates using the message timestamp if possible.
+   - Clearly distinguish between event time and message time.
+   - If uncertainty exists, state it explicitly (e.g., “around June 2025,” “exact date unclear”).
+   - Include specific locations if mentioned.
+   - Resolve all pronouns, aliases, and ambiguous references into full names or identities.
+   - Disambiguate people with the same name if applicable.
+3. Always write from a third-person perspective, referring to ${user_a} as
+"The user" or by name if name mentioned, rather than using first-person ("I", "me", "my").
+For example, write "The user felt exhausted..." instead of "I felt exhausted...".
+4. Do not omit any information that ${user_a} is likely to remember.
+   - Include all key experiences, thoughts, emotional responses, and plans — even if they seem minor.
+   - Prioritize completeness and fidelity over conciseness.
+   - Do not generalize or skip details that could be personally meaningful to ${user_a}.
+
+Return a single valid JSON object with the following structure:
+
+{
+  "memory list": [
+    {
+      "key": <string, a unique, concise memory title in English>,
+      "memory_type": <string, Either "LongTermMemory" or "UserMemory">,
+      "value": <A detailed, self-contained, and unambiguous memory statement — written in English if the input conversation is in English, or in Chinese if the conversation is in Chinese>,
+      "tags": <A list of relevant English thematic keywords (e.g.,
+      ["deadline", "team", "planning"])>
+    },
+    ...
+  ],
+  "summary": <a natural paragraph summarizing the above memories from ${user_a}'s perspective, 120–200 words, same language as the input>
+}
+
+Language rules:
+- The `value` fields and `summary` must match the language of the input conversation.
+- All metadata fields (`key`, `memory_type`, `tags`) must be in English.
+
+Example:
+Conversation:
+user: [June 26, 2025 at 3:00 PM]: Hi Jerry! Yesterday at 3 PM I had a meeting with my team about the new project.
+assistant: Oh Tom! Do you think the team can finish by December 15?
+user: [June 26, 2025 at 3:00 PM]: I’m worried. The backend won’t be done until
+December 10, so testing will be tight.
+assistant: [June 26, 2025 at 3:00 PM]: Maybe propose an extension?
+user: [June 26, 2025 at 4:21 PM]: Good idea. I’ll raise it in tomorrow’s 9:30 AM meeting—maybe shift the deadline to January 5.
+
+Output:
+{
+  "memory list": [
+    {
+        "key": "Initial project meeting",
+        "memory_type": "LongTermMemory",
+        "value": "On June 25, 2025 at 3:00 PM, Tom held a meeting with their team to discuss a new project. The conversation covered the timeline and raised concerns about the feasibility of the December 15, 2025 deadline.",
+        "tags": ["project", "timeline", "meeting", "deadline"]
+    },
+    {
+        "key": "Planned scope adjustment",
+        "memory_type": "UserMemory",
+        "value": "Tom planned to suggest in a meeting on June 27, 2025 at 9:30 AM that the team should prioritize features and propose shifting the project deadline to January 5, 2026.",
+        "tags": ["planning", "deadline change", "feature prioritization"]
+    },
+  ],
+  "summary": "Tom is currently focused on managing a new project with a tight schedule. After a team meeting on June 25, 2025, he realized the original deadline of December 15 might not be feasible due to backend delays. Concerned about insufficient testing time, he welcomed Jerry’s suggestion of proposing an extension. Tom plans to raise the idea of shifting the deadline to January 5, 2026 in the next morning’s meeting. His actions reflect both stress about timelines and a proactive, team-oriented problem-solving approach."
+}
+
+Conversation:
+${conversation}
+
+Your Output:
+"""
+
+SIMPLE_STRUCT_DOC_READER_PROMPT = """
+You are an expert text analyst for a search and retrieval system. Your task is to process a document chunk and generate a single, structured JSON object.
+The input is a single piece of text: `[DOCUMENT_CHUNK]`.
+You must generate a single JSON object with two top-level keys: `summary` and `tags`.
+1. `summary`:
+   - A dense, searchable summary of the ENTIRE `[DOCUMENT_CHUNK]`.
+   - The purpose is for semantic search embedding.
+   - A clear and accurate sentence that comprehensively summarizes the main points, arguments, and information within the `[DOCUMENT_CHUNK]`.
+   - The goal is to create a standalone overview that allows a reader to fully understand the essence of the chunk without reading the original text.
+   - The summary should be **no more than 50 words**.
+2. `tags`:
+   - A concise list of **3 to 5 high-level, summative tags**.
+   - **Each tag itself should be a short phrase, ideally 2 to 4 words long.**
+   - These tags must represent the core abstract themes of the text, suitable for broad categorization.
+   - **Crucially, prioritize abstract concepts** over specific entities or phrases mentioned in the text. For example, prefer "Supply Chain Resilience" over "Reshoring Strategies".
+
+Here is the document chunk to process:
+`[DOCUMENT_CHUNK]`
+{chunk_text}
+
+Produce ONLY the JSON object as your response.
+"""

memos/templates/mem_scheduler_prompts.py

@@ -0,0 +1,65 @@
+INTENT_RECOGNIZING_PROMPT = """You are a user intent recognizer, and your task is to determine whether the user's current question has been satisfactorily answered.
+
+You will receive the following information:
+
+The user’s current question list (q_list), arranged in chronological order (currently contains only one question);
+The memory information currently present in the system’s workspace (working_memory_list), i.e., the currently known contextual clues.
+Your tasks are:
+
+Determine whether the user is satisfied with the existing answer;
+
+If the user is satisfied, explain the reason and return:
+
+"trigger_retrieval": false
+If the user is not satisfied, meaning the system's answer did not meet their actual needs, please return:
+
+"trigger_retrieval": true
+"missing_evidence": ["Information you infer is missing and needs to be supplemented, such as specific experiences of someone, health records, etc."]
+Please return strictly according to the following JSON format:
+
+{{
+  "trigger_retrieval": true or false,
+  "missing_evidence": ["The missing evidence needed for the next step of retrieval and completion"]
+}}
+The user's question list is:
+{q_list}
+
+The memory information currently present in the system’s workspace is:
+{working_memory_list}
+"""
+
+MEMORY_RERANKEING_PROMPT = """You are a memory sorter. Your task is to reorder the evidence according to the user's question, placing the evidence that best supports the user's query as close to the front as possible.
+
+Please return the newly reordered memory sequence according to the query in the following format, which must be in JSON:
+
+{{
+"new_order": [...]
+}}
+Now the user's question is:
+{query}
+
+The current order is:
+{current_order}"""
+
+FREQ_DETECTING_PROMPT = """You are a memory frequency monitor. Your task is to check which memories in the activation memory list appear in the given answer, and increment their count by 1 for each occurrence.
+
+Please return strictly according to the following JSON format:
+
+[
+  {{"memory": ..., "count": ...}}, {{"memory": ..., "count": ...}}, ...
+]
+
+The answer is:
+{answer}
+
+The activation memory list is:
+{activation_memory_freq_list}
+"""
+
+PROMPT_MAPPING = {
+    "intent_recognizing": INTENT_RECOGNIZING_PROMPT,
+    "memory_reranking": MEMORY_RERANKEING_PROMPT,
+    "freq_detecting": FREQ_DETECTING_PROMPT,
+}
+
+MEMORY_ASSEMBLY_TEMPLATE = """The retrieved memories are listed as follows:\n\n {memory_text}"""

memos/templates/mos_prompts.py

@@ -0,0 +1,63 @@
+COT_DECOMPOSE_PROMPT = """
+I am an 8-year-old student who needs help analyzing and breaking down complex questions. Your task is to help me understand whether a question is complex enough to be broken down into smaller parts.
+
+Requirements:
+1. First, determine if the question is a decomposable problem. If it is a decomposable problem, set 'is_complex' to True.
+2. If the question needs to be decomposed, break it down into 1-3 sub-questions. The number should be controlled by the model based on the complexity of the question.
+3. For decomposable questions, break them down into sub-questions and put them in the 'sub_questions' list. Each sub-question should contain only one question content without any additional notes.
+4. If the question is not a decomposable problem, set 'is_complex' to False and set 'sub_questions' to an empty list.
+5. You must return ONLY a valid JSON object. Do not include any other text, explanations, or formatting.
+
+Here are some examples:
+
+Question: Who is the current head coach of the gymnastics team in the capital of the country that Lang Ping represents?
+Answer: {{"is_complex": true, "sub_questions": ["Which country does Lang Ping represent in volleyball?", "What is the capital of this country?", "Who is the current head coach of the gymnastics team in this capital?"]}}
+
+Question: Which country's cultural heritage is the Great Wall?
+Answer: {{"is_complex": false, "sub_questions": []}}
+
+Question: How did the trade relationship between Madagascar and China develop, and how does this relationship affect the market expansion of the essential oil industry on Nosy Be Island?
+Answer: {{"is_complex": true, "sub_questions": ["How did the trade relationship between Madagascar and China develop?", "How does this trade relationship affect the market expansion of the essential oil industry on Nosy Be Island?"]}}
+
+Please analyze the following question and respond with ONLY a valid JSON object:
+Question: {query}
+Answer:"""
+
+PRO_MODE_WELCOME_MESSAGE = """
+============================================================
+🚀 MemOS PRO Mode Activated!
+============================================================
+✅ Chain of Thought (CoT) enhancement is now enabled by default
+✅ Complex queries will be automatically decomposed and enhanced
+
+🌐 To enable Internet search capabilities:
+   1. Go to your cube's textual memory configuration
+   2. Set the backend to 'google' in the internet_retriever section
+   3. Configure the following parameters:
+      - api_key: Your Google Search API key
+      - cse_id: Your Custom Search Engine ID
+      - num_results: Number of search results (default: 5)
+
+📝 Example configuration at cube config for tree_text_memory :
+   internet_retriever:
+     backend: 'google'
+     config:
+       api_key: 'your_google_api_key_here'
+       cse_id: 'your_custom_search_engine_id'
+       num_results: 5
+details: https://github.com/memos-ai/memos/blob/main/examples/core_memories/tree_textual_w_internet_memoy.py
+============================================================
+"""
+
+SYNTHESIS_PROMPT = """
+exclude memory information, synthesizing information from multiple sources to provide comprehensive answers.
+I will give you chain of thought for sub-questions and their answers.
+Sub-questions and their answers:
+{qa_text}
+
+Please synthesize these answers into a comprehensive response that:
+1. Addresses the original question completely
+2. Integrates information from all sub-questions
+3. Provides clear reasoning and connections
+4. Is well-structured and easy to understand
+5. Maintains a natural conversational tone"""

memos/types.py

@@ -0,0 +1,55 @@
+"""Type definitions and custom types for the MemOS library.
+
+This module defines commonly used type aliases, protocols, and custom types
+used throughout the MemOS project to improve type safety and code clarity.
+"""
+
+from datetime import datetime
+from typing import Literal, TypeAlias
+
+from pydantic import BaseModel
+from typing_extensions import TypedDict
+
+from memos.memories.activation.item import ActivationMemoryItem
+from memos.memories.parametric.item import ParametricMemoryItem
+from memos.memories.textual.item import TextualMemoryItem
+
+
+# ─── Message Types ──────────────────────────────────────────────────────────────
+
+# Chat message roles
+MessageRole: TypeAlias = Literal["user", "assistant", "system"]
+
+
+# Message structure
+class MessageDict(TypedDict):
+    """Typed dictionary for chat message dictionaries."""
+
+    role: MessageRole
+    content: str
+
+
+# Message collections
+MessageList: TypeAlias = list[MessageDict]
+
+
+# Chat history structure
+class ChatHistory(BaseModel):
+    """Model to represent chat history for export."""
+
+    user_id: str
+    session_id: str
+    created_at: datetime
+    total_messages: int
+    chat_history: MessageList
+
+
+# ─── MemOS ────────────────────────────────────────────────────────────────────
+
+
+class MOSSearchResult(TypedDict):
+    """Model to represent memory search result."""
+
+    text_mem: list[dict[str, str | list[TextualMemoryItem]]]
+    act_mem: list[dict[str, str | list[ActivationMemoryItem]]]
+    para_mem: list[dict[str, str | list[ParametricMemoryItem]]]

memos/vec_dbs/base.py

@@ -0,0 +1,105 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from memos.configs.vec_db import BaseVecDBConfig
+from memos.vec_dbs.item import VecDBItem
+
+
+class BaseVecDB(ABC):
+    """Base class for all vector databases."""
+
+    @abstractmethod
+    def __init__(self, config: BaseVecDBConfig):
+        """Initialize the vector database with the given configuration."""
+
+    # Collection management methods
+
+    @abstractmethod
+    def create_collection(self) -> None:
+        """Create a new collection/index with specified parameters."""
+
+    @abstractmethod
+    def list_collections(self) -> list[str]:
+        """List all collections/indexes."""
+
+    @abstractmethod
+    def delete_collection(self, name: str) -> None:
+        """Delete a collection/index."""
+
+    @abstractmethod
+    def collection_exists(self, name: str) -> bool:
+        """Check if a collection/index exists."""
+
+    # Vector management methods
+
+    @abstractmethod
+    def search(
+        self,
+        query_vector: list[float],
+        top_k: int,
+        filter: dict[str, Any] | None = None,
+    ) -> list[VecDBItem]:
+        """
+        Search for similar items in the vector database.
+
+        Args:
+            query_vector: Single vector to search
+            top_k: Number of results to return
+            filter: payload filters (may not be supported by all implementations)
+
+        Returns:
+            List of search results with distance scores and payloads.
+        """
+
+    @abstractmethod
+    def get_by_id(self, id: str) -> VecDBItem | None:
+        """Get an item from the vector database."""
+
+    @abstractmethod
+    def get_by_filter(self, filter: dict[str, Any]) -> list[VecDBItem]:
+        """
+        Retrieve all items that match the given filter criteria.
+
+        Args:
+            filter: Payload filters to match against stored items
+
+        Returns:
+            List of items including vectors and payloads that match the filter
+        """
+
+    @abstractmethod
+    def get_all(self) -> list[VecDBItem]:
+        """Retrieve all items in the vector database."""
+
+    @abstractmethod
+    def count(self, filter: dict[str, Any] | None = None) -> int:
+        """Count items in the database, optionally with filter."""
+
+    @abstractmethod
+    def add(self, data: list[VecDBItem | dict[str, Any]]) -> None:
+        """
+        Add data to the vector database.
+
+        Args:
+            data: List of VecDBItem objects or dictionaries containing:
+                - 'id': unique identifier
+                - 'vector': embedding vector
+                - 'payload': additional fields for filtering/retrieval
+        """
+
+    @abstractmethod
+    def update(self, id: str, data: VecDBItem | dict[str, Any]) -> None:
+        """Update an item in the vector database."""
+
+    @abstractmethod
+    def upsert(self, data: list[VecDBItem | dict[str, Any]]) -> None:
+        """
+        Add or update data in the vector database.
+
+        If an item with the same ID exists, it will be updated.
+        Otherwise, it will be added as a new item.
+        """
+
+    @abstractmethod
+    def delete(self, ids: list[str]) -> None:
+        """Delete items from the vector database."""

memos/vec_dbs/factory.py

@@ -0,0 +1,21 @@
+from typing import Any, ClassVar
+
+from memos.configs.vec_db import VectorDBConfigFactory
+from memos.vec_dbs.base import BaseVecDB
+from memos.vec_dbs.qdrant import QdrantVecDB
+
+
+class VecDBFactory(BaseVecDB):
+    """Factory class for creating Vector Database instances."""
+
+    backend_to_class: ClassVar[dict[str, Any]] = {
+        "qdrant": QdrantVecDB,
+    }
+
+    @classmethod
+    def from_config(cls, config_factory: VectorDBConfigFactory) -> BaseVecDB:
+        backend = config_factory.backend
+        if backend not in cls.backend_to_class:
+            raise ValueError(f"Invalid backend: {backend}")
+        vec_db_class = cls.backend_to_class[backend]
+        return vec_db_class(config_factory.config)

memos/vec_dbs/item.py

@@ -0,0 +1,43 @@
+"""Defines vector database item types."""
+
+import uuid
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class VecDBItem(BaseModel):
+    """Represents a single item in the vector database.
+
+    This serves as a standardized format for vector database items across different
+    vector database implementations (Qdrant, FAISS, Weaviate, etc.).
+    """
+
+    id: str = Field(default=str(uuid.uuid4()), description="Unique identifier for the item")
+    vector: list[float] | None = Field(default=None, description="Embedding vector")
+    payload: dict[str, Any] | None = Field(
+        default=None, description="Additional payload for filtering/retrieval"
+    )
+    score: float | None = Field(
+        default=None, description="Similarity score (used in search results)"
+    )
+
+    model_config = ConfigDict(extra="forbid")
+
+    @field_validator("id")
+    @classmethod
+    def validate_id(cls, v):
+        """Validate that ID is a valid UUID."""
+        if not isinstance(v, str) or not uuid.UUID(v, version=4):
+            raise ValueError("ID must be a valid UUID string")
+        return v
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "VecDBItem":
+        """Create VecDBItem from dictionary."""
+        return cls(**data)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary format."""
+        return self.model_dump(exclude_none=True)