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

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/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)

memos/vec_dbs/qdrant.py

@@ -0,0 +1,292 @@
+from typing import Any
+
+from qdrant_client import QdrantClient
+from qdrant_client.http import models
+from qdrant_client.http.models import (
+    Distance,
+    FieldCondition,
+    Filter,
+    MatchValue,
+    PointStruct,
+    VectorParams,
+)
+
+from memos.configs.vec_db import QdrantVecDBConfig
+from memos.log import get_logger
+from memos.vec_dbs.base import BaseVecDB
+from memos.vec_dbs.item import VecDBItem
+
+
+logger = get_logger(__name__)
+
+
+class QdrantVecDB(BaseVecDB):
+    """Qdrant vector database implementation."""
+
+    def __init__(self, config: QdrantVecDBConfig):
+        """Initialize the Qdrant vector database and the collection."""
+        self.config = config
+
+        # If both host and port are None, we are running in local mode
+        if self.config.host is None and self.config.port is None:
+            logger.warning(
+                "Qdrant is running in local mode (host and port are both None). "
+                "In local mode, there may be race conditions during concurrent reads/writes. "
+                "It is strongly recommended to deploy a standalone Qdrant server "
+                "(e.g., via Docker: https://qdrant.tech/documentation/quickstart/)."
+            )
+
+        self.client = QdrantClient(
+            host=self.config.host, port=self.config.port, path=self.config.path
+        )
+        self.create_collection()
+
+    def create_collection(self) -> None:
+        """Create a new collection with specified parameters."""
+
+        if self.collection_exists(self.config.collection_name):
+            collection_info = self.client.get_collection(self.config.collection_name)
+            logger.warning(
+                f"Collection '{self.config.collection_name}' (vector dimension: {collection_info.config.params.vectors.size}) already exists. Skipping creation."
+            )
+
+            return
+
+        # Map string distance metric to Qdrant Distance enum
+        distance_map = {
+            "cosine": Distance.COSINE,
+            "euclidean": Distance.EUCLID,
+            "dot": Distance.DOT,
+        }
+
+        self.client.create_collection(
+            collection_name=self.config.collection_name,
+            vectors_config=VectorParams(
+                size=self.config.vector_dimension,
+                distance=distance_map[self.config.distance_metric],
+            ),
+        )
+
+        logger.info(
+            f"Collection '{self.config.collection_name}' created with {self.config.vector_dimension} dimensions."
+        )
+
+    def list_collections(self) -> list[str]:
+        """List all collections."""
+        collections = self.client.get_collections()
+        return [collection.name for collection in collections.collections]
+
+    def delete_collection(self, name: str) -> None:
+        """Delete a collection."""
+        self.client.delete_collection(collection_name=name)
+
+    def collection_exists(self, name: str) -> bool:
+        """Check if a collection exists."""
+        try:
+            self.client.get_collection(collection_name=name)
+            return True
+        except Exception:
+            return False
+
+    def search(
+        self, query_vector: list[float], top_k: int, filter: dict[str, Any] | None = None
+    ) -> list[VecDBItem]:
+        """
+        Search for similar items in the database.
+
+        Args:
+            query_vector: Single vector to search
+            top_k: Number of results to return
+            filter: Payload filters
+
+        Returns:
+            List of search results with distance scores and payloads.
+        """
+        qdrant_filter = self._dict_to_filter(filter) if filter else None
+        response = self.client.search(
+            collection_name=self.config.collection_name,
+            query_vector=query_vector,
+            limit=top_k,
+            query_filter=qdrant_filter,
+            with_vectors=True,
+            with_payload=True,
+        )
+        logger.info(f"Qdrant search completed with {len(response)} results.")
+        return [
+            VecDBItem(
+                id=point.id,
+                vector=point.vector,
+                payload=point.payload,
+                score=point.score,
+            )
+            for point in response
+        ]
+
+    def _dict_to_filter(self, filter_dict: dict[str, Any]) -> Filter:
+        """Convert a dictionary filter to a Qdrant Filter object."""
+        conditions = []
+
+        for field, value in filter_dict.items():
+            # Simple exact match for now
+            # TODO: Extend this to support more complex conditions
+            conditions.append(FieldCondition(key=field, match=MatchValue(value=value)))
+
+        return Filter(must=conditions)
+
+    def get_by_id(self, id: str) -> VecDBItem | None:
+        """Get a single item by ID."""
+        response = self.client.retrieve(
+            collection_name=self.config.collection_name,
+            ids=[id],
+            with_payload=True,
+            with_vectors=True,
+        )
+
+        if not response:
+            return None
+
+        point = response[0]
+        return VecDBItem(
+            id=point.id,
+            vector=point.vector,
+            payload=point.payload,
+        )
+
+    def get_by_ids(self, ids: list[str]) -> list[VecDBItem]:
+        """Get multiple items by their IDs."""
+        response = self.client.retrieve(
+            collection_name=self.config.collection_name,
+            ids=ids,
+            with_payload=True,
+            with_vectors=True,
+        )
+
+        if not response:
+            return []
+
+        return [
+            VecDBItem(
+                id=point.id,
+                vector=point.vector,
+                payload=point.payload,
+            )
+            for point in response
+        ]
+
+    def get_by_filter(self, filter: dict[str, Any], scroll_limit: int = 100) -> list[VecDBItem]:
+        """
+        Retrieve all items that match the given filter criteria.
+
+        Args:
+            filter: Payload filters to match against stored items
+            scroll_limit: Maximum number of items to retrieve per scroll request
+
+        Returns:
+            List of items including vectors and payload that match the filter
+        """
+        qdrant_filter = self._dict_to_filter(filter) if filter else None
+        all_points = []
+        offset = None
+
+        # Use scroll to paginate through all matching points
+        while True:
+            points, offset = self.client.scroll(
+                collection_name=self.config.collection_name,
+                limit=scroll_limit,
+                scroll_filter=qdrant_filter,
+                offset=offset,
+                with_vectors=True,
+                with_payload=True,
+            )
+
+            if not points:
+                break
+
+            all_points.extend(points)
+
+            # Update offset for next iteration
+            if offset is None:
+                break
+
+        logger.info(f"Qdrant retrieve by filter completed with {len(all_points)} results.")
+        return [
+            VecDBItem(
+                id=point.id,
+                vector=point.vector,
+                payload=point.payload,
+            )
+            for point in all_points
+        ]
+
+    def get_all(self, scroll_limit=100) -> list[VecDBItem]:
+        """Retrieve all items in the vector database."""
+        return self.get_by_filter({}, scroll_limit=scroll_limit)
+
+    def count(self, filter: dict[str, Any] | None = None) -> int:
+        """Count items in the database, optionally with filter."""
+        qdrant_filter = None
+        if filter:
+            qdrant_filter = self._dict_to_filter(filter)
+
+        response = self.client.count(
+            collection_name=self.config.collection_name, count_filter=qdrant_filter
+        )
+
+        return response.count
+
+    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
+        """
+        points = []
+        for item in data:
+            if isinstance(item, dict):
+                item = item.copy()
+                item = VecDBItem.from_dict(item)
+            point = PointStruct(id=item.id, vector=item.vector, payload=item.payload)
+            points.append(point)
+
+        self.client.upsert(collection_name=self.config.collection_name, points=points)
+
+    def update(self, id: str, data: VecDBItem | dict[str, Any]) -> None:
+        """Update an item in the vector database."""
+
+        if isinstance(data, dict):
+            data = data.copy()
+            data = VecDBItem.from_dict(data)
+
+        if data.vector:
+            # For vector updates (with or without payload), use upsert with the same ID
+            self.client.upsert(
+                collection_name=self.config.collection_name,
+                points=[PointStruct(id=id, vector=data.vector, payload=data.payload)],
+            )
+        else:
+            # For payload-only updates
+            self.client.set_payload(
+                collection_name=self.config.collection_name, payload=data.payload, points=[id]
+            )
+
+    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.
+        """
+        # Qdrant's upsert operation already handles this logic
+        self.add(data)
+
+    def delete(self, ids: list[str]) -> None:
+        """Delete items from the vector database."""
+        point_ids: list[str | int] = ids
+        self.client.delete(
+            collection_name=self.config.collection_name,
+            points_selector=models.PointIdsList(points=point_ids),
+        )