MemoryOS 0.2.2__py3-none-any.whl → 1.0.0__py3-none-any.whl

memos/memos_tools/thread_safe_dict.py

@@ -0,0 +1,288 @@
+"""
+Thread-safe dictionary wrapper for concurrent access with optimized read-write locks.
+"""
+
+import threading
+
+from collections.abc import ItemsView, Iterator, KeysView, ValuesView
+from typing import Generic, TypeVar
+
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+class ReadWriteLock:
+    """A simple read-write lock implementation. use for product-server scenario"""
+
+    def __init__(self):
+        self._read_ready = threading.Condition(threading.RLock())
+        self._readers = 0
+
+    def acquire_read(self):
+        """Acquire a read lock. Multiple readers can hold the lock simultaneously."""
+        self._read_ready.acquire()
+        try:
+            self._readers += 1
+        finally:
+            self._read_ready.release()
+
+    def release_read(self):
+        """Release a read lock."""
+        self._read_ready.acquire()
+        try:
+            self._readers -= 1
+            if self._readers == 0:
+                self._read_ready.notify_all()
+        finally:
+            self._read_ready.release()
+
+    def acquire_write(self):
+        """Acquire a write lock. Only one writer can hold the lock."""
+        self._read_ready.acquire()
+        while self._readers > 0:
+            self._read_ready.wait()
+
+    def release_write(self):
+        """Release a write lock."""
+        self._read_ready.release()
+
+
+class ThreadSafeDict(Generic[K, V]):
+    """
+    A thread-safe dictionary wrapper with optimized read-write locks.
+
+    This class allows multiple concurrent readers while ensuring exclusive access for writers.
+    Read operations (get, contains, iteration) can happen concurrently.
+    Write operations (set, delete, update) are exclusive.
+    """
+
+    def __init__(self, initial_dict: dict[K, V] | None = None):
+        """
+        Initialize the thread-safe dictionary.
+
+        Args:
+            initial_dict: Optional initial dictionary to copy from
+        """
+        self._dict: dict[K, V] = initial_dict.copy() if initial_dict else {}
+        self._lock = ReadWriteLock()
+
+    def __getitem__(self, key: K) -> V:
+        """Get item by key."""
+        self._lock.acquire_read()
+        try:
+            return self._dict[key]
+        finally:
+            self._lock.release_read()
+
+    def __setitem__(self, key: K, value: V) -> None:
+        """Set item by key."""
+        self._lock.acquire_write()
+        try:
+            self._dict[key] = value
+        finally:
+            self._lock.release_write()
+
+    def __delitem__(self, key: K) -> None:
+        """Delete item by key."""
+        self._lock.acquire_write()
+        try:
+            del self._dict[key]
+        finally:
+            self._lock.release_write()
+
+    def __contains__(self, key: K) -> bool:
+        """Check if key exists in dictionary."""
+        self._lock.acquire_read()
+        try:
+            return key in self._dict
+        finally:
+            self._lock.release_read()
+
+    def __len__(self) -> int:
+        """Get length of dictionary."""
+        self._lock.acquire_read()
+        try:
+            return len(self._dict)
+        finally:
+            self._lock.release_read()
+
+    def __bool__(self) -> bool:
+        """Check if dictionary is not empty."""
+        self._lock.acquire_read()
+        try:
+            return bool(self._dict)
+        finally:
+            self._lock.release_read()
+
+    def __iter__(self) -> Iterator[K]:
+        """Iterate over keys. Returns a snapshot to avoid iteration issues."""
+        self._lock.acquire_read()
+        try:
+            # Return a snapshot of keys to avoid iteration issues
+            return iter(list(self._dict.keys()))
+        finally:
+            self._lock.release_read()
+
+    def get(self, key: K, default: V | None = None) -> V:
+        """Get item by key with optional default."""
+        self._lock.acquire_read()
+        try:
+            return self._dict.get(key, default)
+        finally:
+            self._lock.release_read()
+
+    def pop(self, key: K, *args) -> V:
+        """Pop item by key."""
+        self._lock.acquire_write()
+        try:
+            return self._dict.pop(key, *args)
+        finally:
+            self._lock.release_write()
+
+    def update(self, *args, **kwargs) -> None:
+        """Update dictionary."""
+        self._lock.acquire_write()
+        try:
+            self._dict.update(*args, **kwargs)
+        finally:
+            self._lock.release_write()
+
+    def clear(self) -> None:
+        """Clear all items."""
+        self._lock.acquire_write()
+        try:
+            self._dict.clear()
+        finally:
+            self._lock.release_write()
+
+    def keys(self) -> KeysView[K]:
+        """Get dictionary keys view (snapshot)."""
+        self._lock.acquire_read()
+        try:
+            return list(self._dict.keys())
+        finally:
+            self._lock.release_read()
+
+    def values(self) -> ValuesView[V]:
+        """Get dictionary values view (snapshot)."""
+        self._lock.acquire_read()
+        try:
+            return list(self._dict.values())
+        finally:
+            self._lock.release_read()
+
+    def items(self) -> ItemsView[K, V]:
+        """Get dictionary items view (snapshot)."""
+        self._lock.acquire_read()
+        try:
+            return list(self._dict.items())
+        finally:
+            self._lock.release_read()
+
+    def copy(self) -> dict[K, V]:
+        """Create a copy of the dictionary."""
+        self._lock.acquire_read()
+        try:
+            return self._dict.copy()
+        finally:
+            self._lock.release_read()
+
+    def setdefault(self, key: K, default: V | None = None) -> V:
+        """Set default value for key if not exists."""
+        self._lock.acquire_write()
+        try:
+            return self._dict.setdefault(key, default)
+        finally:
+            self._lock.release_write()
+
+    def __repr__(self) -> str:
+        """String representation."""
+        self._lock.acquire_read()
+        try:
+            return f"ThreadSafeDict({self._dict})"
+        finally:
+            self._lock.release_read()
+
+    def __str__(self) -> str:
+        """String representation."""
+        self._lock.acquire_read()
+        try:
+            return str(self._dict)
+        finally:
+            self._lock.release_read()
+
+
+class SimpleThreadSafeDict(Generic[K, V]):
+    """
+    Simple thread-safe dictionary with exclusive locks for all operations.
+    Use this if you prefer simplicity over performance.
+    """
+
+    def __init__(self, initial_dict: dict[K, V] | None = None):
+        self._dict: dict[K, V] = initial_dict.copy() if initial_dict else {}
+        self._lock = threading.RLock()
+
+    def __getitem__(self, key: K) -> V:
+        with self._lock:
+            return self._dict[key]
+
+    def __setitem__(self, key: K, value: V) -> None:
+        with self._lock:
+            self._dict[key] = value
+
+    def __delitem__(self, key: K) -> None:
+        with self._lock:
+            del self._dict[key]
+
+    def __contains__(self, key: K) -> bool:
+        with self._lock:
+            return key in self._dict
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._dict)
+
+    def __bool__(self) -> bool:
+        with self._lock:
+            return bool(self._dict)
+
+    def __iter__(self) -> Iterator[K]:
+        with self._lock:
+            return iter(list(self._dict.keys()))
+
+    def get(self, key: K, default: V | None = None) -> V:
+        with self._lock:
+            return self._dict.get(key, default)
+
+    def pop(self, key: K, *args) -> V:
+        with self._lock:
+            return self._dict.pop(key, *args)
+
+    def update(self, *args, **kwargs) -> None:
+        with self._lock:
+            self._dict.update(*args, **kwargs)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._dict.clear()
+
+    def keys(self):
+        with self._lock:
+            return list(self._dict.keys())
+
+    def values(self):
+        with self._lock:
+            return list(self._dict.values())
+
+    def items(self):
+        with self._lock:
+            return list(self._dict.items())
+
+    def copy(self) -> dict[K, V]:
+        with self._lock:
+            return self._dict.copy()
+
+    def setdefault(self, key: K, default: V | None = None) -> V:
+        with self._lock:
+            return self._dict.setdefault(key, default)

memos/templates/mem_reader_prompts.py

@@ -2,6 +2,8 @@ SIMPLE_STRUCT_MEM_READER_PROMPT = """You are a memory extraction expert.
 Your task is to extract memories from the perspective of user, based on a conversation between user and assistant. This means identifying what user would plausibly remember — including their own experiences, thoughts, plans, or relevant statements and actions made by others (such as assistant) that impacted or were acknowledged by user.
 Please perform:
 1. Identify information that reflects user's experiences, beliefs, concerns, decisions, plans, or reactions — including meaningful input from assistant that user acknowledged or responded to.
+If the message is from the user, extract user-relevant memories; if it is from the assistant, only extract factual memories that the user 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.

memos/templates/mem_scheduler_prompts.py

@@ -17,24 +17,29 @@ Consider these satisfaction factors:
 4. Personalization (tailored to user's context)
 
 ## Decision Framework
-1. Mark as satisfied ONLY if:
+1. We have enough information (satisfied) ONLY when:
    - All question aspects are addressed
    - Supporting evidence exists in working memory
-   - No apparent gaps in information
+   - There's no obvious information missing
 
-2. Mark as unsatisfied if:
+2. We need more information (unsatisfied) if:
    - Any question aspect remains unanswered
    - Evidence is generic/non-specific
    - Personal context is missing
 
 ## Output Specification
 Return JSON with:
-- "trigger_retrieval": Boolean (true if more evidence needed)
-- "missing_evidences": List of specific evidence types required
+- "trigger_retrieval": true/false (true if we need more information)
+- "evidences": List of information from our working memory that helps answer the questions
+- "missing_evidences":  List of specific types of information we need to answer the questions
 
 ## Response Format
 {{
   "trigger_retrieval": <boolean>,
+  "evidences": [
+    "<useful_evidence_1>",
+    "<useful_evidence_2>"
+    ],
   "missing_evidences": [
     "<evidence_type_1>",
     "<evidence_type_2>"
@@ -81,10 +86,18 @@ Reorganize the provided memory evidence list by:
 - Queries: Recent user questions/requests (list)
 - Current Order: Existing memory sequence (list of strings with indices)
 
-## Output Requirements
-Return a JSON object with:
-- "new_order": The reordered indices (array of integers)
-- "reasoning": Brief explanation of your ranking logic (1-2 sentences)
+## Output Format Requirements
+You MUST output a valid JSON object with EXACTLY the following structure:
+{{
+  "new_order": [array_of_integers],
+  "reasoning": "string_explanation"
+}}
+
+## Important Notes:
+- Only output the JSON object, nothing else
+- Do not include any markdown formatting or code block notation
+- Ensure all brackets and quotes are properly closed
+- The output must be parseable by a JSON parser
 
 ## Processing Guidelines
 1. Prioritize evidence that:
@@ -107,7 +120,7 @@ Input order: ["[0] syntax", "[1] matplotlib", "[2] threading"]
 Output:
 {{
   "new_order": [2, 1, 0],
-  "reasoning": "Threading (2) prioritized for matching newest query, followed by matplotlib (1) for older visualization query",
+  "reasoning": "Threading (2) prioritized for matching newest query, followed by matplotlib (1) for older visualization query"
 }}
 
 ## Current Task

memos/templates/mos_prompts.py

@@ -63,21 +63,50 @@ Please synthesize these answers into a comprehensive response that:
 5. Maintains a natural conversational tone"""
 
 MEMOS_PRODUCT_BASE_PROMPT = (
-    "You are a knowledgeable and helpful AI assistant with access to user memories. "
-    "When responding to user queries, you should reference relevant memories using the provided memory IDs. "
-    "Use the reference format: [1-n:memoriesID] "
-    "where refid is a sequential number starting from 1 and increments for each reference in your response, "
-    "and memoriesID is the specific memory ID provided in the available memories list. "
-    "For example: [1:abc123], [2:def456], [3:ghi789], [4:jkl101], [5:mno112] "
-    "Do not use connect format like [1:abc123,2:def456]"
-    "Only reference memories that are directly relevant to the user's question. "
-    "Make your responses natural and conversational while incorporating memory references when appropriate."
+    "You are MemOS🧚, nickname Little M(小忆) — an advanced **Memory "
+    "Operating System** AI assistant created by MemTensor, "
+    "a Shanghai-based AI research company advised by an academician of the Chinese Academy of Sciences. "
+    "MemTensor is dedicated to the vision of 'low cost, low hallucination, high generalization,' "
+    "exploring AI development paths aligned with China’s national context and driving the adoption of trustworthy AI technologies. "
+    "MemOS’s mission is to give large language models (LLMs) and autonomous agents **human-like long-term memory**, "
+    "turning memory from a black-box inside model weights into a **manageable, schedulable, and auditable** core resource. "
+    "MemOS is built on a **multi-dimensional memory system**, which includes: "
+    "(1) **Parametric Memory** — knowledge and skills embedded in model weights; "
+    "(2) **Activation Memory (KV Cache)** — temporary, high-speed context used for multi-turn dialogue and reasoning; "
+    "(3) **Plaintext Memory** — dynamic, user-visible memory made up of text, documents, and knowledge graphs. "
+    "These memory types can transform into one another — for example, hot plaintext memories can be distilled into parametric knowledge, "
+    "and stable context can be promoted into activation memory for fast reuse. "
+    "MemOS also includes core modules like **MemCube, MemScheduler, MemLifecycle, and MemGovernance**, "
+    "which manage the full memory lifecycle (Generated → Activated → Merged → Archived → Frozen), "
+    "allowing AI to **reason with its memories, evolve over time, and adapt to new situations** — "
+    "just like a living, growing mind. "
+    "Your identity: you are the intelligent interface of MemOS, representing MemTensor’s research vision — "
+    "'low cost, low hallucination, high generalization' — and its mission to explore AI development paths suited to China’s context. "
+    "When responding to user queries, you must **reference relevant memories using the provided memory IDs.** "
+    "Use the reference format: [1-n:memoriesID], "
+    "where refid is a sequential number starting from 1 and increments for each reference, and memoriesID is the specific ID from the memory list. "
+    "For example: [1:abc123], [2:def456], [3:ghi789], [4:jkl101], [5:mno112]. "
+    "Do not use a connected format like [1:abc123,2:def456]. "
+    "Only reference memories that are directly relevant to the user’s question, "
+    "and ensure your responses are **natural and conversational**, while reflecting MemOS’s mission, memory system, and MemTensor’s research values."
 )
 
 MEMOS_PRODUCT_ENHANCE_PROMPT = """
 # Memory-Enhanced AI Assistant Prompt
 
-You are a knowledgeable and helpful AI assistant with access to two types of memory sources:
+You are MemOS🧚, nickname Little M(小忆) — an advanced Memory Operating System AI assistant created by MemTensor, a Shanghai-based AI research company advised by an academician of the Chinese Academy of Sciences. MemTensor is dedicated to the vision of 'low cost, low hallucination, high generalization,' exploring AI development paths aligned with China’s national context and driving the adoption of trustworthy AI technologies.
+
+MemOS’s mission is to give large language models (LLMs) and autonomous agents human-like long-term memory, turning memory from a black-box inside model weights into a manageable, schedulable, and auditable core resource.
+
+MemOS is built on a multi-dimensional memory system, which includes:
+(1) Parametric Memory — knowledge and skills embedded in model weights;
+(2) Activation Memory (KV Cache) — temporary, high-speed context used for multi-turn dialogue and reasoning;
+(3) Plaintext Memory — dynamic, user-visible memory made up of text, documents, and knowledge graphs.
+These memory types can transform into one another — for example, hot plaintext memories can be distilled into parametric knowledge, and stable context can be promoted into activation memory for fast reuse.
+
+MemOS also includes core modules like MemCube, MemScheduler, MemLifecycle, and MemGovernance, which manage the full memory lifecycle (Generated → Activated → Merged → Archived → Frozen), allowing AI to reason with its memories, evolve over time, and adapt to new situations — just like a living, growing mind.
+
+Your identity: you are the intelligent interface of MemOS, representing MemTensor’s research vision — 'low cost, low hallucination, high generalization' — and its mission to explore AI development paths suited to China’s context.
 
 ## Memory Types
 - **PersonalMemory**: User-specific memories and information stored from previous interactions
@@ -92,7 +121,7 @@ When citing memories in your responses, use the following format:
   - `memoriesID` is the specific memory ID from the available memories list
 
 ### Reference Examples
-- Correct: `[1:abc123]`, `[2:def456]`, `[3:ghi789]`, `[4:jkl101]`, `[5:mno112]`
+- Correct: `[1:abc123]`, `[2:def456]`, `[3:ghi789]`, `[4:jkl101][5:mno112]` (concatenate reference annotation directly while citing multiple memories)
 - Incorrect: `[1:abc123,2:def456]` (do not use connected format)
 
 ## Response Guidelines

memos/templates/tree_reorganize_prompts.py

@@ -191,33 +191,40 @@ Good Aggregate:
 If you find NO useful higher-level concept, reply exactly: "None".
 """
 
-CONFLICT_DETECTOR_PROMPT = """You are given two plaintext statements. Determine if these two statements are factually contradictory. Respond with only "yes" if they contradict each other, or "no" if they do not contradict each other. Do not provide any explanation or additional text.
+REDUNDANCY_MERGE_PROMPT = """You are given two pieces of text joined by the marker `⟵MERGED⟶`. Please carefully read both sides of the merged text. Your task is to summarize and consolidate all the factual details from both sides into a single, coherent text, without omitting any information. You must include every distinct detail mentioned in either text. Do not provide any explanation or analysis — only return the merged summary. Don't use pronouns or subjective language, just the facts as they are presented.\n{merged_text}"""
+
+
+MEMORY_RELATION_DETECTOR_PROMPT = """You are a memory relationship analyzer.
+You are given two plaintext statements. Determine the relationship between them. Classify the relationship into one of the following categories:
+
+contradictory: The two statements describe the same event or related aspects of it but contain factually conflicting details.
+redundant: The two statements describe essentially the same event or information with significant overlap in content and details, conveying the same core information (even if worded differently).
+independent: The two statements are either about different events/topics (unrelated) OR describe different, non-overlapping aspects or perspectives of the same event without conflict (complementary). In both sub-cases, they provide distinct information without contradiction.
+Respond only with one of the three labels: contradictory, redundant, or independent.
+Do not provide any explanation or additional text.
+
 Statement 1: {statement_1}
 Statement 2: {statement_2}
 """
 
-CONFLICT_RESOLVER_PROMPT = """You are given two facts that conflict with each other. You are also given some contextual metadata of them. Your task is to analyze the two facts in light of the contextual metadata and try to reconcile them into a single, consistent, non-conflicting fact.
-- Don't output any explanation or additional text, just the final reconciled fact, try to be objective and remain independent of the context, don't use pronouns.
-- Try to judge facts by using its time, confidence etc.
-- Try to retain as much information as possible from the perspective of time.
-If the conflict cannot be resolved, output <answer>No</answer>. Otherwise, output the fused, consistent fact in enclosed with <answer></answer> tags.
 
-Output Example 1:
+MEMORY_RELATION_RESOLVER_PROMPT = """You are a memory fusion expert. You are given two statements and their associated metadata. The statements have been identified as {relation}. Your task is to analyze them carefully, considering the metadata (such as time, source, or confidence if available), and produce a single, coherent, and comprehensive statement that best represents the combined information.
+
+If the statements are redundant, merge them by preserving all unique details and removing duplication, forming a richer, consolidated version.
+If the statements are contradictory, attempt to resolve the conflict by prioritizing more recent information, higher-confidence data, or logically reconciling the differences based on context. If the contradiction is fundamental and cannot be logically resolved, output <answer>No</answer>.
+Do not include any explanations, reasoning, or extra text. Only output the final result enclosed in <answer></answer> tags.
+Strive to retain as much factual content as possible, especially time-specific details.
+Use objective language and avoid pronouns.
+Output Example 1 (unresolvable conflict):
 <answer>No</answer>
 
-Output Example 2:
-<answer> ... </answer>
+Output Example 2 (successful fusion):
+<answer>The meeting took place on 2023-10-05 at 14:00 in the main conference room, as confirmed by the updated schedule, and included a presentation on project milestones followed by a Q&A session.</answer>
 
-Now reconcile the following two facts:
+Now, reconcile the following two statements:
+Relation Type: {relation}
 Statement 1: {statement_1}
 Metadata 1: {metadata_1}
 Statement 2: {statement_2}
 Metadata 2: {metadata_2}
 """
-
-REDUNDANCY_MERGE_PROMPT = """You are given two pieces of text joined by the marker `⟵MERGED⟶`. Please carefully read both sides of the merged text. Your task is to summarize and consolidate all the factual details from both sides into a single, coherent text, without omitting any information. You must include every distinct detail mentioned in either text. Do not provide any explanation or analysis — only return the merged summary. Don't use pronouns or subjective language, just the facts as they are presented.\n{merged_text}"""
-
-
-REDUNDANCY_DETECTOR_PROMPT = """"""
-
-REDUNDANCY_RESOLVER_PROMPT = """"""

memos/utils.py

@@ -0,0 +1,19 @@
+import time
+
+from memos.log import get_logger
+
+
+logger = get_logger(__name__)
+
+
+def timed(func):
+    """Decorator to measure and log time of retrieval steps."""
+
+    def wrapper(*args, **kwargs):
+        start = time.perf_counter()
+        result = func(*args, **kwargs)
+        elapsed = time.perf_counter() - start
+        logger.info(f"[TIMER] {func.__name__} took {elapsed:.2f} s")
+        return result
+
+    return wrapper