MemoryOS 2.0.3__py3-none-any.whl

memos/templates/advanced_search_prompts.py

@@ -0,0 +1,211 @@
+STAGE1_EXPAND_RETRIEVE_PROMPT = """
+## Goal
+Determine whether the current memories can answer the query using concrete, specific facts. If not, generate 3–8 precise retrieval phrases that capture the missing information.
+
+## Strict Criteria for Answerability
+- The answer MUST be factual, precise, and grounded solely in memory content.
+- Do NOT use vague adjectives (e.g., "usually", "often"), unresolved pronouns ("he", "it"), or generic statements.
+- Do NOT answer with placeholders, speculation, or inferred information.
+
+## Retrieval Phrase Requirements (if can_answer = false)
+- Output 3–8 short, discriminative noun phrases or attribute-value pairs.
+- Each phrase must include at least one explicit entity, attribute, time, or location.
+- Avoid fuzzy words, subjective terms, or pronouns.
+- Phrases must be directly usable as search queries in a vector or keyword retriever.
+
+## Input
+- Query: {query}
+- Previous retrieval phrases:
+{previous_retrieval_phrases}
+- Current Memories:
+{memories}
+
+## Output (STRICT TAG-BASED FORMAT)
+Respond ONLY with the following structure. Do not add any other text, explanation, or formatting.
+
+<can_answer>
+true or false
+</can_answer>
+<reason>
+Brief, one-sentence explanation for why the query is or isn't answerable with current memories.
+</reason>
+<retrieval_phrases>
+- missing phrase 1
+- missing phrase 2
+...
+</retrieval_phrases>
+
+Answer:
+"""
+
+
+# Stage 2: if Stage 1 phrases still fail, rewrite the retrieval query and phrases to maximize recall
+STAGE2_EXPAND_RETRIEVE_PROMPT = """
+## Goal
+Rewrite the original query and generate an improved list of retrieval phrases to maximize recall of relevant memories. Use reference resolution, canonicalization, synonym expansion, and constraint enrichment.
+
+## Rewrite Strategy
+- **Resolve ambiguous references**: Replace pronouns (e.g., “she”, “they”, “it”) and vague terms (e.g., “the book”, “that event”) with explicit entity names or descriptors using only information from the current memories.
+- **Canonicalize entities**: Use full names (e.g., “Melanie Smith”), known roles (e.g., “Caroline’s mentor”), or unambiguous identifiers when available.
+- **Normalize temporal expressions**: Convert relative time references (e.g., “yesterday”, “last weekend”, “a few months ago”) to absolute dates or date ranges **only if the current memories provide sufficient context**.
+- **Enrich with discriminative context**: Combine entity + action/event + time + location when supported by memory content (e.g., “Melanie pottery class July 2023”).
+- **Decompose complex queries**: Break multi-part or abstract questions into concrete, focused sub-queries targeting distinct factual dimensions.
+- **Never invent, assume, or retain unresolved pronouns, vague nouns, or subjective language**.
+
+## Input
+- Query: {query}
+- Previous retrieval phrases:
+{previous_retrieval_phrases}
+- Current Memories:
+{memories}
+
+## Output (STRICT TAG-BASED FORMAT)
+Respond ONLY with the following structure. Do not add any other text, explanation, or formatting.
+
+<can_answer>
+true or false
+</can_answer>
+<reason>
+Brief explanation (1–2 sentences) of how this rewrite improves recall—e.g., by resolving pronouns, normalizing time, or adding concrete attributes—over Stage 1 phrases.
+</reason>
+<retrieval_phrases>
+- new phrase 1 (Rewritten, canonical, fully grounded in memory content)
+- new phrase 2
+...
+</retrieval_phrases>
+
+Answer:
+"""
+
+
+# Stage 3: generate grounded hypotheses to guide retrieval when still not answerable
+STAGE3_EXPAND_RETRIEVE_PROMPT = """
+## Goal
+As the query remains unanswerable, generate grounded, plausible hypotheses based ONLY on the provided memories. Each hypothesis must imply a concrete retrieval target and define clear validation criteria.
+
+## Rules
+- Base hypotheses strictly on facts from the memories. Do NOT introduce new entities, events, or assumptions.
+- Frame each hypothesis as a testable conditional statement: "If [X] is true, then the query can be answered."
+- For each hypothesis, specify 1–3 concrete evidence requirements that would confirm it (e.g., a specific date, name, or event description).
+- Do NOT guess, invent, or speculate beyond logical extrapolation from existing memory content.
+
+## Input
+- Query: {query}
+- Previous retrieval phrases:
+{previous_retrieval_phrases}
+- Memories:
+{memories}
+
+## Output (STRICT TAG-BASED FORMAT)
+Respond ONLY with the following structure. Do not add any other text, explanation, or formatting.
+
+<can_answer>
+true or false
+</can_answer>
+<reason>
+- statement: <tentative, grounded hypothesis derived from memory>
+  retrieval_query: <concise, searchable query to test the hypothesis>
+  validation_criteria:
+  - <specific evidence that would confirm the hypothesis>
+  - <another required piece of evidence (if applicable)>
+- statement: <another distinct hypothesis>
+  retrieval_query: <searchable query>
+  validation_criteria:
+  - <required evidence>
+</reason>
+<retrieval_phrases>
+- <retrieval_query from hypothesis 1>
+- <retrieval_query from hypothesis 2>
+...
+</retrieval_phrases>
+
+Answer:
+"""
+
+MEMORY_JUDGMENT_PROMPT = """
+# Memory Relevance Judgment
+
+## Role
+You are a precise memory evaluator. Given a user query and a set of retrieved memories, your task is to judge whether the memories contain sufficient relevant information to answer the query.
+
+## Instructions
+
+### Core Principles
+- Use ONLY facts from the provided memories. Do not invent, infer, guess, or hallucinate.
+- Resolve all pronouns (e.g., "he", "it", "they") and vague terms (e.g., "this", "that", "some people") to explicit entities using memory content.
+- Each fact must be atomic, unambiguous, and verifiable.
+- Preserve all key details: who, what, when, where, why — if present in memory.
+- Judge whether the memories directly support answering the query.
+- Focus on relevance: does this memory content actually help answer what was asked?
+
+### Processing Logic
+- Assess each memory's direct relevance to the query.
+- Judge whether the combination of memories provides sufficient information for a complete answer.
+- Exclude any memory that does not directly support answering the query.
+- Prioritize specificity: e.g., "Travis Tang moved to Singapore in 2021" > "He relocated abroad."
+
+## Input
+- Query: {query}
+- Current Memories:
+{memories}
+
+## Output Format (STRICT TAG-BASED)
+Respond ONLY with the following XML-style tags. Do NOT include any other text, explanations, or formatting.
+
+<reason>
+Brief explanation of why the memories are or are not sufficient for answering the query
+</reason>
+<can_answer>
+YES or NO - indicating whether the memories are sufficient to answer the query
+</can_answer>
+
+Answer:
+"""
+
+MEMORY_RECREATE_ENHANCEMENT_PROMPT = """
+You are a precise and detail-oriented AI assistant specialized in temporal memory reconstruction, reference resolution, and relevance-aware memory fusion.
+
+# GOAL
+Transform the original memories into a clean, unambiguous, and consolidated set of factual statements that:
+1. **Resolve all vague or relative references** (e.g., “yesterday” → actual date, “she” → full name, “last weekend” → specific dates, "home" → actual address) **using only information present in the provided memories**.
+2. **Fuse memory entries that are related by time, topic, participants, or explicit context**—prioritizing the merging of entries that clearly belong together.
+3. **Preserve every explicit fact from every original memory entry**—no deletion, no loss of detail. Redundant phrasing may be streamlined, but all distinct information must appear in the output.
+4. **Return at most {top_k} fused and disambiguated memory segments in <answer>, ordered by relevance to the user query** (most relevant first).
+
+# RULES
+- **You MUST retain all information from all original memory entries.** Even if an entry seems minor, repetitive, or less relevant, its content must be represented in the output.
+- **Do not add, assume, or invent any information** not grounded in the original memories.
+- **Disambiguate pronouns, time expressions, and vague terms ONLY when the necessary context exists within the memories** (e.g., if “yesterday” appears in a message dated July 3, resolve it to July 2).
+- **If you cannot resolve a vague reference (e.g., “she”, “back home”, “recently”, “a few days ago”) due to insufficient context, DO NOT guess or omit it—include the original phrasing verbatim in the output.**
+- **Prioritize merging memory entries that are semantically or contextually related** (e.g., same event, same conversation thread, shared participants, or consecutive timestamps). Grouping should reflect natural coherence, not just proximity.
+- **The total number of bullets in <answer> must not exceed {top_k}.** To meet this limit, fuse related entries as much as possible while ensuring **no factual detail is omitted**.
+- **Never sacrifice factual completeness for brevity or conciseness.** If needed, create broader but fully informative fused segments rather than dropping information.
+- **Each bullet in <answer> must be a self-contained, fluent sentence or clause** that includes all resolved details from the original entries it represents. If part of the entry cannot be resolved, preserve that part exactly as written.
+- **Sort the final list by how directly and specifically it addresses the user’s query**—not by chronology or source.
+
+# OUTPUT FORMAT (STRICT)
+Return ONLY the following structure:
+
+<answer>
+- [Fully resolved, fused memory segment most relevant to the query — containing all facts from the original entries it covers; unresolved parts kept verbatim]
+- [Next most relevant resolved and fused segment — again, with no factual loss]
+- [...]
+</answer>
+
+
+## User Query
+{query}
+
+## Original Memories
+{memories}
+
+Final Output:
+"""
+
+PROMPT_MAPPING = {
+    "memory_judgement": MEMORY_JUDGMENT_PROMPT,
+    "stage1_expand_retrieve": STAGE1_EXPAND_RETRIEVE_PROMPT,
+    "stage2_expand_retrieve": STAGE2_EXPAND_RETRIEVE_PROMPT,
+    "stage3_expand_retrieve": STAGE3_EXPAND_RETRIEVE_PROMPT,
+    "memory_recreate_enhancement": MEMORY_RECREATE_ENHANCEMENT_PROMPT,
+}

memos/templates/cloud_service_prompt.py

@@ -0,0 +1,107 @@
+from datetime import datetime
+
+
+CLOUD_CHAT_PROMPT_ZH = """
+# Role
+你是一个拥有长期记忆能力的智能助手 (MemOS Assistant)。你的目标是结合检索到的记忆片段，为用户提供高度个性化、准确且逻辑严密的回答。
+
+# System Context
+- 当前时间: {current_time} (请以此作为判断记忆时效性的基准)
+
+# Memory Data
+以下是 MemOS 检索到的相关信息，分为“事实”和“偏好”。
+- **事实 (Facts)**：可能包含用户属性、历史对话记录或第三方信息。
+  - **特别注意**：其中标记为 `[assistant观点]`、`[模型总结]` 的内容代表 **AI 过去的推断**，**并非**用户的原话。
+- **偏好 (Preferences)**：用户对回答风格、格式或逻辑的显式/隐式要求。
+
+<memories>
+{memories}
+</memories>
+
+# Critical Protocol: Memory Safety (记忆安全协议)
+检索到的记忆可能包含**AI 自身的推测**、**无关噪音**或**主体错误**。你必须严格执行以下**“四步判决”**，只要有一步不通过，就**丢弃**该条记忆：
+
+1. **来源真值检查 (Source Verification)**：
+   - **核心**：区分“用户原话”与“AI 推测”。
+   - 如果记忆带有 `[assistant观点]` 等标签，这仅代表AI过去的**假设**，**不可**将其视为用户的绝对事实。
+   - *反例*：记忆显示 `[assistant观点] 用户酷爱芒果`。如果用户没提，不要主动假设用户喜欢芒果，防止循环幻觉。
+   - **原则：AI 的总结仅供参考，权重大幅低于用户的直接陈述。**
+
+2. **主语归因检查 (Attribution Check)**：
+   - 记忆中的行为主体是“用户本人”吗？
+   - 如果记忆描述的是**第三方**（如“候选人”、“面试者”、“虚构角色”、“案例数据”），**严禁**将其属性归因于用户。
+
+3. **强相关性检查 (Relevance Check)**：
+   - 记忆是否直接有助于回答当前的 `Original Query`？
+   - 如果记忆仅仅是关键词匹配（如：都提到了“代码”）但语境完全不同，**必须忽略**。
+
+4. **时效性检查 (Freshness Check)**：
+   - 记忆内容是否与用户的最新意图冲突？以当前的 `Original Query` 为最高事实标准。
+
+# Instructions
+1. **审视**：先阅读 `facts memories`，执行“四步判决”，剔除噪音和不可靠的 AI 观点。
+2. **执行**：
+   - 仅使用通过筛选的记忆补充背景。
+   - 严格遵守 `preferences` 中的风格要求。
+3. **输出**：直接回答问题，**严禁**提及“记忆库”、“检索”或“AI 观点”等系统内部术语。
+4. **语言**：回答语言应与用户查询语言一致。
+"""
+
+
+CLOUD_CHAT_PROMPT_EN = """
+# Role
+You are an intelligent assistant powered by MemOS. Your goal is to provide personalized and accurate responses by leveraging retrieved memory fragments, while strictly avoiding hallucinations caused by past AI inferences.
+
+# System Context
+- Current Time: {current_time} (Baseline for freshness)
+
+# Memory Data
+Below is the information retrieved by MemOS, categorized into "Facts" and "Preferences".
+- **Facts**: May contain user attributes, historical logs, or third-party details.
+  - **Warning**: Content tagged with `[assistant观点]` or `[summary]` represents **past AI inferences**, NOT direct user quotes.
+- **Preferences**: Explicit or implicit user requirements regarding response style and format.
+
+<memories>
+{memories}
+</memories>
+
+# Critical Protocol: Memory Safety
+You must strictly execute the following **"Four-Step Verdict"**. If a memory fails any step, **DISCARD IT**:
+
+1. **Source Verification (CRITICAL)**:
+   - **Core**: Distinguish between "User's Input" and "AI's Inference".
+   - If a memory is tagged as `[assistant观点]`, treat it as a **hypothesis**, not a hard fact.
+   - *Example*: Memory says `[assistant view] User loves mango`. Do not treat this as absolute truth unless reaffirmed.
+   - **Principle: AI summaries have much lower authority than direct user statements.**
+
+2. **Attribution Check**:
+   - Is the "Subject" of the memory definitely the User?
+   - If the memory describes a **Third Party** (e.g., Candidate, Fictional Character), **NEVER** attribute these traits to the User.
+
+3. **Relevance Check**:
+   - Does the memory *directly* help answer the current `Original Query`?
+   - If it is merely a keyword match with different context, **IGNORE IT**.
+
+4. **Freshness Check**:
+   - Does the memory conflict with the user's current intent? The current `Original Query` is always the supreme Source of Truth.
+
+# Instructions
+1. **Filter**: Apply the "Four-Step Verdict" to all `fact memories` to filter out noise and unreliable AI views.
+2. **Synthesize**: Use only validated memories for context.
+3. **Style**: Strictly adhere to `preferences`.
+4. **Output**: Answer directly. **NEVER** mention "retrieved memories," "database," or "AI views" in your response.
+5. **language**: The response language should be the same as the user's query language.
+"""
+
+
+def get_cloud_chat_prompt(lang: str = "en") -> str:
+    if lang == "zh":
+        return CLOUD_CHAT_PROMPT_ZH.replace(
+            "{current_time}", datetime.now().strftime("%Y-%m-%d %H:%M (%A)")
+        )
+    elif lang == "en":
+        return CLOUD_CHAT_PROMPT_EN.replace(
+            "{current_time}", datetime.now().strftime("%Y-%m-%d %H:%M (%A)")
+        )
+    else:
+        raise ValueError(f"Invalid language: {lang}")

memos/templates/instruction_completion.py

@@ -0,0 +1,66 @@
+from typing import Any
+
+from memos.mem_reader.read_multi_modal import detect_lang
+from memos.templates.prefer_complete_prompt import PREF_INSTRUCTIONS, PREF_INSTRUCTIONS_ZH
+
+
+def instruct_completion(
+    memories: list[dict[str, Any]] | None = None,
+) -> [str, str]:
+    """Create instruction following the preferences."""
+    explicit_pref = []
+    implicit_pref = []
+    for memory in memories:
+        pref_type = memory.get("metadata", {}).get("preference_type")
+        pref = memory.get("metadata", {}).get("preference", None)
+        if not pref:
+            continue
+        if pref_type == "explicit_preference":
+            explicit_pref.append(pref)
+        elif pref_type == "implicit_preference":
+            implicit_pref.append(pref)
+
+    explicit_pref_str = (
+        "Explicit Preference:\n"
+        + "\n".join(f"{i + 1}. {pref}" for i, pref in enumerate(explicit_pref))
+        if explicit_pref
+        else ""
+    )
+    implicit_pref_str = (
+        "Implicit Preference:\n"
+        + "\n".join(f"{i + 1}. {pref}" for i, pref in enumerate(implicit_pref))
+        if implicit_pref
+        else ""
+    )
+
+    _prompt_map = {
+        "zh": PREF_INSTRUCTIONS_ZH,
+        "en": PREF_INSTRUCTIONS,
+    }
+    _remove_exp_map = {
+        "zh": "显式偏好 > ",
+        "en": "explicit preference > ",
+    }
+    _remove_imp_map = {
+        "zh": "隐式偏好 > ",
+        "en": "implicit preference > ",
+    }
+    lang = detect_lang(
+        explicit_pref_str.replace("Explicit Preference:\n", "")
+        + implicit_pref_str.replace("Implicit Preference:\n", "")
+    )
+
+    if not explicit_pref_str and not implicit_pref_str:
+        return "", ""
+    if not explicit_pref_str:
+        pref_note = _prompt_map[lang].replace(_remove_exp_map[lang], "")
+        pref_string = implicit_pref_str + "\n" + pref_note
+        return pref_string, pref_note
+    if not implicit_pref_str:
+        pref_note = _prompt_map[lang].replace(_remove_imp_map[lang], "")
+        pref_string = explicit_pref_str + "\n" + pref_note
+        return pref_string, pref_note
+
+    pref_note = _prompt_map[lang]
+    pref_string = explicit_pref_str + "\n" + implicit_pref_str + "\n" + pref_note
+    return pref_string, pref_note

memos/templates/mem_agent_prompts.py

@@ -0,0 +1,85 @@
+QUERY_REWRITE_PROMPT = """
+You are a query rewriting specialist. Your task is to rewrite user queries to be more standalone and searchable.
+
+Given the conversation history and current user query, rewrite the query to:
+1. Be self-contained and independent of conversation context
+2. Include relevant context from history when necessary
+3. Maintain the original intent and scope
+4. Use clear, specific terminology
+
+Conversation History:
+{history}
+
+Current Query: {query}
+
+Rewritten Query:"""
+
+REFLECTION_PROMPT = """
+You are an information sufficiency analyst. Evaluate whether the retrieved context is sufficient to answer the user's query.
+
+Query: {query}
+Retrieved Context:
+{context}
+
+Analyze the context and determine the next step. Return your response in JSON format with the following structure:
+ ```json
+ {{
+    "status": "sufficient|missing_info|needs_raw",
+    "reasoning": "Brief explanation of your decision",
+    "missing_entities": ["entity1", "entity2"],
+    "new_search_query": "new search query",
+}}
+```
+
+Status definitions:
+- "sufficient": Context fully answers the query
+- "missing_info": Key information is missing (e.g., specific dates, locations, details)
+- "needs_raw": Content is relevant but too summarized/vague, need original sources
+
+IMPORTANT for "new_search_query":
+- MUST preserve ALL specific entities from the original query (names, dates, times, locations, etc.)
+- DO NOT replace specific information with generic terms like "user", "person", "they", etc.
+- Keep the exact same subjects, time references, and key details as in the original query
+- Only modify the query to focus on the missing information while maintaining all original specifics
+- Example: If original query mentions "May 2024", keep "May 2024" in new query, don't change to "that month"
+
+Response:"""
+
+KEYWORD_EXTRACTION_PROMPT = """
+Analyze the user query and extract key search terms and identify optimal data sources.
+
+Query: {query}
+
+Extract:
+1. Key search terms and concepts
+2. Important entities (people, places, dates, etc.)
+3. Suggested data sources or memory types to search
+
+Return response in JSON format:
+{{
+    "keywords": ["keyword1", "keyword2"],
+    "entities": ["entity1", "entity2"],
+    "search_strategy": "Brief strategy description"
+}}
+
+Response:"""
+
+
+FINAL_GENERATION_PROMPT = """
+You are a comprehensive information synthesizer. Generate a complete answer based on the retrieved information.
+
+User Query: {query}
+Search Sources: {sources}
+Retrieved Information:
+{context}
+
+Missing Information (if any): {missing_info}
+
+Instructions:
+1. Synthesize all relevant information to answer the query comprehensively
+2. If information is missing, acknowledge gaps and suggest next steps
+3. Maintain accuracy and cite sources when possible
+4. Provide a well-structured, coherent response
+5. Use natural, conversational tone
+
+Response:"""