From 7fcb14025d9d4b1e0a148dba37d621af1f6126ec Mon Sep 17 00:00:00 2001 From: qzs Date: Fri, 4 Sep 2026 23:00:57 +0800 Subject: [PATCH 1/9] refactor(hooks): replace hook events with hook context --- src/memos/api/handlers/search_handler.py | 119 +++++-- src/memos/mem_reader/simple_struct.py | 101 ++++-- .../task_schedule_modules/base_handler.py | 26 +- .../handlers/mem_read_handler.py | 112 +++++-- .../operation_observer.py | 111 +++++++ src/memos/multi_mem_cube/single_cube.py | 63 +++- src/memos/plugins/README.md | 26 ++ src/memos/plugins/__init__.py | 13 +- src/memos/plugins/base.py | 2 +- src/memos/plugins/hook_context.py | 47 +++ src/memos/plugins/hook_defs.py | 122 ++++++- src/memos/plugins/hooks.py | 96 +++++- tests/api/test_search_pipeline_hooks.py | 183 +++++++++- tests/mem_reader/test_hook_pipeline.py | 121 +++++++ .../mem_scheduler/test_operation_observer.py | 150 +++++++++ .../multi_mem_cube/test_single_cube_hooks.py | 142 ++++++++ tests/plugins/test_hook_context.py | 312 ++++++++++++++++++ 17 files changed, 1639 insertions(+), 107 deletions(-) create mode 100644 src/memos/mem_scheduler/task_schedule_modules/operation_observer.py create mode 100644 src/memos/plugins/hook_context.py create mode 100644 tests/mem_reader/test_hook_pipeline.py create mode 100644 tests/mem_scheduler/test_operation_observer.py create mode 100644 tests/multi_mem_cube/test_single_cube_hooks.py create mode 100644 tests/plugins/test_hook_context.py diff --git a/src/memos/api/handlers/search_handler.py b/src/memos/api/handlers/search_handler.py index 363e0b253..c95a89270 100644 --- a/src/memos/api/handlers/search_handler.py +++ b/src/memos/api/handlers/search_handler.py @@ -15,6 +15,7 @@ from memos.api.handlers.base_handler import BaseHandler, HandlerDependencies from memos.api.handlers.formatters_handler import rerank_knowledge_mem from memos.api.product_models import APISearchRequest, SearchResponse +from memos.context.context import get_current_trace_id from memos.dream.contextualization import CONTEXT_MEMORY_TYPE from memos.log import get_logger, summarize_search_request, summarize_search_results from memos.memories.textual.tree_text_memory.retrieve.retrieve_utils import ( @@ -23,6 +24,7 @@ from memos.multi_mem_cube.composite_cube import CompositeCubeView from memos.multi_mem_cube.single_cube import SingleCubeView from memos.multi_mem_cube.views import MemCubeView +from memos.plugins.hook_context import HookContext, build_hook_context from memos.plugins.hook_defs import H from memos.plugins.hooks import hookable, trigger_hook @@ -65,8 +67,16 @@ def __init__(self, dependencies: HandlerDependencies): "naive_mem_cube", "mem_scheduler", "searcher", "deepsearch_agent" ) - @hookable("search") - def handle_search_memories(self, search_req: APISearchRequest) -> SearchResponse: + @hookable( + "search", + context_builder=lambda handler, request: handler._build_search_hook_context(request), + ) + def handle_search_memories( + self, + search_req: APISearchRequest, + *, + hook_context: HookContext | None = None, + ) -> SearchResponse: """ Main handler for search memories endpoint. @@ -75,6 +85,8 @@ def handle_search_memories(self, search_req: APISearchRequest) -> SearchResponse Args: search_req: Search request containing query and parameters + hook_context: Internal correlation context shared by all Hooks for + this search operation. A context is created when omitted. Returns: SearchResponse with formatted results @@ -86,6 +98,8 @@ def handle_search_memories(self, search_req: APISearchRequest) -> SearchResponse # Use deepcopy to avoid modifying the original request object search_req_local = copy.deepcopy(search_req) + if hook_context is None: + hook_context = self._build_search_hook_context(search_req_local) # Expand top_k for deduplication (5x to ensure enough candidates) if search_req_local.dedup in ("sim", "mmr"): @@ -94,46 +108,78 @@ def handle_search_memories(self, search_req: APISearchRequest) -> SearchResponse # Search and deduplicate cube_view = self._build_cube_view(search_req_local) results = cube_view.search_memories(search_req_local) + hooked_results = trigger_hook( H.SEARCH_MEMORY_RESULTS, + hook_context=hook_context, handler=self, search_req=search_req_local, results=results, ) if hooked_results is not None: results = hooked_results - if not search_req_local.relativity: - search_req_local.relativity = 0 - self.logger.info(f"[SearchHandler] Relativity filter: {search_req_local.relativity}") - results = self._apply_relativity_threshold(results, search_req_local.relativity) - - if search_req_local.dedup == "sim": - results = self._dedup_text_memories(results, search_req.top_k) - self._strip_embeddings(results) - elif search_req_local.dedup == "mmr": - pref_top_k = getattr(search_req_local, "pref_top_k", 6) - results = self._mmr_dedup_text_memories(results, search_req.top_k, pref_top_k) - self._strip_embeddings(results) - - text_mem = results["text_mem"] - results["text_mem"] = rerank_knowledge_mem( - self.reranker, - query=search_req.query, - text_mem=text_mem, - top_k=search_req_local.top_k, - file_mem_proportion=0.5, - ) - hooked_results = trigger_hook( - H.SEARCH_RESULTS_AFTER_RERANK, - handler=self, - search_req=search_req_local, - results=results, - ) - if hooked_results is not None: - results = hooked_results + try: + if not search_req_local.relativity: + search_req_local.relativity = 0 + self.logger.info(f"[SearchHandler] Relativity filter: {search_req_local.relativity}") + results = self._apply_relativity_threshold(results, search_req_local.relativity) + hooked_results = trigger_hook( + H.SEARCH_RESULTS_AFTER_THRESHOLD, + hook_context=hook_context, + handler=self, + search_req=search_req_local, + results=results, + ) + if hooked_results is not None: + results = hooked_results + + if search_req_local.dedup == "sim": + results = self._dedup_text_memories(results, search_req.top_k) + self._strip_embeddings(results) + elif search_req_local.dedup == "mmr": + pref_top_k = getattr(search_req_local, "pref_top_k", 6) + results = self._mmr_dedup_text_memories(results, search_req.top_k, pref_top_k) + self._strip_embeddings(results) + hooked_results = trigger_hook( + H.SEARCH_RESULTS_AFTER_DEDUP, + hook_context=hook_context, + handler=self, + search_req=search_req_local, + results=results, + ) + if hooked_results is not None: + results = hooked_results + + text_mem = results["text_mem"] + results["text_mem"] = rerank_knowledge_mem( + self.reranker, + query=search_req.query, + text_mem=text_mem, + top_k=search_req_local.top_k, + file_mem_proportion=0.5, + ) + hooked_results = trigger_hook( + H.SEARCH_RESULTS_AFTER_RERANK, + hook_context=hook_context, + handler=self, + search_req=search_req_local, + results=results, + ) + if hooked_results is not None: + results = hooked_results + except Exception as error: + trigger_hook( + H.SEARCH_POST_PROCESS_FAILED, + hook_context=hook_context, + handler=self, + search_req=search_req_local, + error=error, + ) + raise hooked_results = trigger_hook( H.SEARCH_CONTEXT_RENDER, + hook_context=hook_context, handler=self, search_req=search_req_local, results=results, @@ -1036,6 +1082,17 @@ def _resolve_cube_ids(self, search_req: APISearchRequest) -> list[str]: return [search_req.user_id] + def _build_search_hook_context(self, search_req: APISearchRequest) -> HookContext: + mode = search_req.mode.value if hasattr(search_req.mode, "value") else str(search_req.mode) + return build_hook_context( + source="api.search", + trace_id=get_current_trace_id(), + user_id=search_req.user_id, + session_id=search_req.session_id or "default_session", + cube_ids=self._resolve_cube_ids(search_req), + attributes={"mode": mode}, + ) + def _build_cube_view(self, search_req: APISearchRequest, searcher=None) -> MemCubeView: cube_ids = self._resolve_cube_ids(search_req) searcher_to_use = searcher if searcher is not None else self.searcher diff --git a/src/memos/mem_reader/simple_struct.py b/src/memos/mem_reader/simple_struct.py index 2804bac23..14521cf47 100644 --- a/src/memos/mem_reader/simple_struct.py +++ b/src/memos/mem_reader/simple_struct.py @@ -13,10 +13,13 @@ from memos.chunkers import ChunkerFactory from memos.configs.llm import LLMConfigFactory from memos.configs.mem_reader import SimpleStructMemReaderConfig -from memos.context.context import ContextThreadPoolExecutor +from memos.context.context import ContextThreadPoolExecutor, get_current_trace_id from memos.embedders.factory import EmbedderFactory from memos.llms.factory import LLMFactory from memos.mem_reader.base import BaseMemReader +from memos.plugins.hook_context import HookContext, build_hook_context +from memos.plugins.hook_defs import H +from memos.plugins.hooks import trigger_hook if TYPE_CHECKING: @@ -476,6 +479,33 @@ def _process_transfer_chat_data( return chat_read_nodes + def _build_extract_hook_data( + self, + scene_data: SceneDataInput, + type: str, + info: dict[str, Any], + mode: str, + user_name: str | None, + kwargs: dict[str, Any], + ) -> tuple[dict[str, Any], HookContext]: + hook_input = { + "mem_reader": self, + "scene_data": scene_data, + "type": type, + "info": info, + "mode": mode, + "user_name": user_name, + "kwargs": kwargs, + } + return hook_input, build_hook_context( + trace_id=get_current_trace_id(), + user_id=info.get("user_id") if isinstance(info, dict) else None, + session_id=info.get("session_id") if isinstance(info, dict) else None, + cube_ids=[user_name] if user_name else None, + source="mem_reader.extract", + attributes={"mode": mode, "type": type}, + ) + def get_memory( self, scene_data: SceneDataInput, @@ -509,27 +539,56 @@ def get_memory( Raises: ValueError: If scene_data is empty or if info dictionary is missing required fields """ - if not scene_data: - raise ValueError("scene_data is empty") - - # Validate info dictionary format - if not isinstance(info, dict): - raise ValueError("info must be a dictionary") - - required_fields = {"user_id", "session_id"} - missing_fields = required_fields - set(info.keys()) - if missing_fields: - raise ValueError(f"info dictionary is missing required fields: {missing_fields}") - - if not all(isinstance(info[field], str) for field in required_fields): - raise ValueError("user_id and session_id must be strings") - - # Backward compatibility, after coercing scene_data, we only tackle - # with standard scene_data type: MessagesType - standard_scene_data = coerce_scene_data(scene_data, type) - return self._read_memory( - standard_scene_data, type, info, mode, user_name=user_name, **kwargs + # Build Hook business arguments and correlation context. + hook_input, hook_context = self._build_extract_hook_data( + scene_data, + type, + info, + mode, + user_name, + kwargs, + ) + + try: + if not scene_data: + raise ValueError("scene_data is empty") + + # Validate info dictionary format + if not isinstance(info, dict): + raise ValueError("info must be a dictionary") + + required_fields = {"user_id", "session_id"} + missing_fields = required_fields - set(info.keys()) + if missing_fields: + raise ValueError(f"info dictionary is missing required fields: {missing_fields}") + + if not all(isinstance(info[field], str) for field in required_fields): + raise ValueError("user_id and session_id must be strings") + + # Backward compatibility, after coercing scene_data, we only tackle + # with standard scene_data type: MessagesType + standard_scene_data = coerce_scene_data(scene_data, type) + result = self._read_memory( + standard_scene_data, type, info, mode, user_name=user_name, **kwargs + ) + except Exception as error: + trigger_hook( + H.MEM_READER_EXTRACT_FAILED, + hook_context=hook_context, + **hook_input, + error=error, + ) + raise + + hook_result = trigger_hook( + H.MEM_READER_EXTRACT_AFTER, + hook_context=hook_context, + **hook_input, + result=result, ) + if hook_result is not None: + result = hook_result + return result def rewrite_memories( self, messages: list[dict], memory_list: list[TextualMemoryItem], user_only: bool = True diff --git a/src/memos/mem_scheduler/task_schedule_modules/base_handler.py b/src/memos/mem_scheduler/task_schedule_modules/base_handler.py index 603b038e1..438c30a0b 100644 --- a/src/memos/mem_scheduler/task_schedule_modules/base_handler.py +++ b/src/memos/mem_scheduler/task_schedule_modules/base_handler.py @@ -1,9 +1,12 @@ from __future__ import annotations from abc import abstractmethod -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, Any from memos.log import get_logger +from memos.mem_scheduler.task_schedule_modules.operation_observer import ( + SchedulerOperationObserver, +) from memos.mem_scheduler.utils.misc_utils import group_messages_by_user_and_mem_cube @@ -34,6 +37,27 @@ def validate_and_log_messages(self, messages: list[ScheduleMessageItem], label: def handle_exception(self, e: Exception, message: str = "Error processing messages") -> None: logger.error(f"{message}: {e}", exc_info=True) + def observe_operation( + self, + operation_name: str, + *, + operation: str, + target: str, + operation_context: Any, + operation_input: dict[str, Any], + capture_failure: bool = False, + ) -> SchedulerOperationObserver: + """Expose a scheduler operation through the standard plugin Hook contract.""" + source = f"scheduler.{self.expected_task_label}.{operation_name}" + return SchedulerOperationObserver( + source=source, + operation=operation, + target=target, + operation_context=operation_context, + operation_input=operation_input, + capture_failure=capture_failure, + ) + def process_grouped_messages( self, messages: list[ScheduleMessageItem], diff --git a/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py b/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py index 90ace633c..a61744785 100644 --- a/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py +++ b/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py @@ -6,7 +6,7 @@ import traceback from datetime import datetime, timezone -from typing import TYPE_CHECKING +from typing import TYPE_CHECKING, Any from memos.context.context import ContextThreadPoolExecutor from memos.log import get_logger @@ -96,6 +96,7 @@ def process_message(self, message: ScheduleMessageItem): info=info, chat_history=chat_history, user_context=user_context, + operation_context=message, ) logger.info( @@ -119,6 +120,7 @@ def _process_memories_with_reader( info: dict | None = None, chat_history: list | None = None, user_context: UserContext | None = None, + operation_context: Any | None = None, ) -> None: logger.info( "[DIAGNOSTIC] mem_read_handler._process_memories_with_reader called. mem_ids: %s, user_id: %s, mem_cube_id: %s, task_id: %s", @@ -127,6 +129,12 @@ def _process_memories_with_reader( mem_cube_id, task_id, ) + operation_context = operation_context or { + "task_id": task_id, + "label": MEM_READ_TASK_LABEL, + "user_id": user_id, + "cube_id": mem_cube_id, + } kb_log_content: list[dict] = [] try: mem_reader = self.scheduler_context.get_mem_reader() @@ -169,15 +177,26 @@ def _process_memories_with_reader( is_upload_skill = info.pop("is_upload_skill", False) try: - processed_memories = mem_reader.fine_transfer_simple_mem( - memory_items, - type="chat", - custom_tags=custom_tags, - user_name=user_name, - chat_history=chat_history, - user_context=user_context, - is_upload_skill=is_upload_skill, - ) + with self.observe_operation( + "fine_transfer_simple_mem", + operation="fine", + target="textual_memory", + operation_context=operation_context, + operation_input={"memories": memory_items, "type": "chat"}, + capture_failure=True, + ) as observation: + observation.result( + mem_reader.fine_transfer_simple_mem( + memory_items, + type="chat", + custom_tags=custom_tags, + user_name=user_name, + chat_history=chat_history, + user_context=user_context, + is_upload_skill=is_upload_skill, + ) + ) + processed_memories = observation.value except Exception as e: logger.warning("%s: Fail to transfer mem: %s", e, memory_items) processed_memories = [] @@ -195,7 +214,16 @@ def _process_memories_with_reader( for memory in flattened_memories if memory.metadata.memory_type != "RawFileMemory" ] - enhanced_mem_ids = text_mem.add(mem_group, user_name=user_name) + with self.observe_operation( + "add_enhanced_memories", + operation="add", + target="textual_memory", + operation_context=operation_context, + operation_input={"memories": mem_group, "user_name": user_name}, + capture_failure=True, + ) as observation: + observation.result(text_mem.add(mem_group, user_name=user_name)) + enhanced_mem_ids = observation.value logger.info( "Added %s enhanced memories: %s", len(enhanced_mem_ids), @@ -244,11 +272,21 @@ def _process_memories_with_reader( ) for old_id in old_ids: try: - mem_reader.graph_db.update_node( - str(old_id), - {"status": "archived"}, - user_name=user_name, - ) + with self.observe_operation( + "archive_merged_memories", + operation="archive", + target="textual_memory", + operation_context=operation_context, + operation_input={"memory_ids": [str(old_id)]}, + capture_failure=True, + ) as observation: + observation.result( + mem_reader.graph_db.update_node( + str(old_id), + {"status": "archived"}, + user_name=user_name, + ) + ) logger.info( "[Scheduler] Archived merged_from memory: %s", old_id, @@ -405,7 +443,15 @@ def _process_memories_with_reader( if delete_ids: try: if getattr(mem_reader, "memory_version_switch", "off") != "on": - text_mem.delete(delete_ids, user_name=user_name) + with self.observe_operation( + "remove_memories", + operation="delete", + target="textual_memory", + operation_context=operation_context, + operation_input={"memory_ids": delete_ids}, + capture_failure=True, + ) as observation: + observation.result(text_mem.delete(delete_ids, user_name=user_name)) logger.info( "Delete raw/working mem_ids: %s for user_name: %s", delete_ids, @@ -418,15 +464,29 @@ def _process_memories_with_reader( for memory_list in processed_memories: flattened_memories.extend(memory_list) allowed_types = ["UserMemory", "LongTermMemory"] - text_mem.soft_delete( - delete_ids, - user_name, - [ - mem.id - for mem in flattened_memories - if mem.metadata.memory_type in allowed_types - ], - ) + preserved_memory_ids = [ + mem.id + for mem in flattened_memories + if mem.metadata.memory_type in allowed_types + ] + with self.observe_operation( + "remove_memories", + operation="soft_delete", + target="textual_memory", + operation_context=operation_context, + operation_input={ + "memory_ids": delete_ids, + "preserved_memory_ids": preserved_memory_ids, + }, + capture_failure=True, + ) as observation: + observation.result( + text_mem.soft_delete( + delete_ids, + user_name, + preserved_memory_ids, + ) + ) logger.info( "Soft delete raw/working mem_ids: %s for user_name: %s", delete_ids, diff --git a/src/memos/mem_scheduler/task_schedule_modules/operation_observer.py b/src/memos/mem_scheduler/task_schedule_modules/operation_observer.py new file mode 100644 index 000000000..7a151d4ab --- /dev/null +++ b/src/memos/mem_scheduler/task_schedule_modules/operation_observer.py @@ -0,0 +1,111 @@ +from __future__ import annotations + +from collections.abc import Mapping +from contextlib import AbstractContextManager +from typing import Any + +from memos.plugins.hook_context import build_hook_context +from memos.plugins.hook_defs import H +from memos.plugins.hooks import trigger_hook + + +_MISSING = object() + + +class SchedulerOperationObserver(AbstractContextManager["SchedulerOperationObserver"]): + """Observe one Handler operation without changing its exception semantics. + + Usage: + with SchedulerOperationObserver(...) as observer: + result = perform_operation() + observer.result(result) + """ + + def __init__( + self, + *, + source: str, + operation: str, + target: str, + operation_context: Any, + operation_input: Mapping[str, Any], + capture_failure: bool = False, + ) -> None: + self._hook_kwargs = { + "operation": operation, + "target": target, + "operation_input": dict(operation_input), + } + cube_id = self._context_value(operation_context, "cube_id") or self._context_value( + operation_context, "mem_cube_id" + ) + self._hook_context = build_hook_context( + trace_id=self._context_value(operation_context, "trace_id"), + user_id=self._context_value(operation_context, "user_id"), + session_id=self._context_value(operation_context, "session_id"), + task_id=self._context_value(operation_context, "task_id"), + cube_ids=[str(cube_id)] if cube_id else None, + source=source, + attributes=self._attributes(operation_context), + ) + self._capture_failure = capture_failure + self._result: Any = _MISSING + self._failed = False + + def __enter__(self) -> SchedulerOperationObserver: + return self + + def __exit__(self, exc_type, exc_value, traceback) -> bool: + if exc_value is not None: + if self._capture_failure: + self.failed(exc_value) + return False + + if not self._failed and self._result is not _MISSING: + hook_result = trigger_hook( + H.SCHEDULER_MEMORY_OPERATION_AFTER, + hook_context=self._hook_context, + **self._hook_kwargs, + result=self._result, + ) + if hook_result is not None: + self._result = hook_result + return False + + def result(self, value: Any) -> Any: + """Record and return the operation result for concise call sites.""" + self._result = value + return value + + @property + def value(self) -> Any: + """Return the result after successful Hook pipeline processing.""" + return None if self._result is _MISSING else self._result + + def failed(self, error: BaseException) -> None: + """Emit the failure Hook once at an existing exception boundary.""" + if self._failed: + return + self._failed = True + trigger_hook( + H.SCHEDULER_MEMORY_OPERATION_FAILED, + hook_context=self._hook_context, + **self._hook_kwargs, + error=error, + ) + + @staticmethod + def _context_value(operation_context: Any, name: str) -> Any: + if isinstance(operation_context, Mapping): + return operation_context.get(name) + return getattr(operation_context, name, None) + + @classmethod + def _attributes(cls, operation_context: Any) -> dict[str, Any]: + attributes = { + "scheduler_item_id": cls._context_value(operation_context, "scheduler_item_id") + or cls._context_value(operation_context, "item_id"), + "redis_message_id": cls._context_value(operation_context, "redis_message_id"), + "label": cls._context_value(operation_context, "label"), + } + return {key: value for key, value in attributes.items() if value is not None} diff --git a/src/memos/multi_mem_cube/single_cube.py b/src/memos/multi_mem_cube/single_cube.py index 27399259a..8d78adbff 100644 --- a/src/memos/multi_mem_cube/single_cube.py +++ b/src/memos/multi_mem_cube/single_cube.py @@ -12,6 +12,7 @@ format_memory_item, post_process_textual_mem, ) +from memos.context.context import get_current_trace_id from memos.log import get_logger, summarize_search_request, summarize_search_results from memos.mem_reader.utils import parse_keep_filter_response from memos.mem_scheduler.schemas.message_schemas import ScheduleMessageItem @@ -22,6 +23,9 @@ ) from memos.memories.textual.item import TextualMemoryItem from memos.multi_mem_cube.views import MemCubeView +from memos.plugins.hook_context import HookContext, build_hook_context +from memos.plugins.hook_defs import H +from memos.plugins.hooks import trigger_hook from memos.search import resolve_filter_for_cube, search_text_memories from memos.templates.mem_reader_prompts import PROMPT_MAPPING from memos.types.general_types import ( @@ -658,6 +662,32 @@ def add_before_search( self.logger.error(f"[add_before_search] LLM execution error: {e}") return memory_list + def _build_text_memory_add_hook_data( + self, + *, + add_req: APIADDRequest, + user_context: UserContext, + text_memory: Any, + memories: list[TextualMemoryItem], + session_id: str, + sync_mode: str, + extract_mode: str, + ) -> tuple[dict[str, Any], HookContext]: + hook_input = { + "text_memory": text_memory, + "memories": memories, + "kwargs": {"user_name": user_context.mem_cube_id}, + } + return hook_input, build_hook_context( + trace_id=get_current_trace_id(), + user_id=add_req.user_id, + session_id=session_id, + task_id=add_req.task_id, + cube_ids=[self.cube_id], + source="cube_view.text_mem.add", + attributes={"sync_mode": sync_mode, "extract_mode": extract_mode}, + ) + @timed def _process_text_mem( self, @@ -731,10 +761,37 @@ def _process_text_mem( # Stage 3: write_db with timed_stage("add", "write_db", cube_id=self.cube_id) as ts_db: - mem_ids_local: list[str] = self.naive_mem_cube.text_mem.add( - mem_group, - user_name=user_context.mem_cube_id, + text_memory = self.naive_mem_cube.text_mem + hook_input, hook_context = self._build_text_memory_add_hook_data( + add_req=add_req, + user_context=user_context, + text_memory=text_memory, + memories=mem_group, + session_id=target_session_id, + sync_mode=sync_mode, + extract_mode=extract_mode, + ) + + try: + mem_ids_local: list[str] = text_memory.add( + mem_group, user_name=user_context.mem_cube_id + ) + except Exception as error: + trigger_hook( + H.TEXT_MEMORY_ADD_FAILED, + hook_context=hook_context, + **hook_input, + error=error, + ) + raise + hook_result = trigger_hook( + H.TEXT_MEMORY_ADD_AFTER, + hook_context=hook_context, + **hook_input, + result=mem_ids_local, ) + if hook_result is not None: + mem_ids_local = hook_result self.logger.info( f"Added {len(mem_ids_local)} memories for user {add_req.user_id} " diff --git a/src/memos/plugins/README.md b/src/memos/plugins/README.md index c9b6a0c29..859fe76d7 100644 --- a/src/memos/plugins/README.md +++ b/src/memos/plugins/README.md @@ -269,8 +269,16 @@ H.ADD_AFTER H.SEARCH_BEFORE H.SEARCH_AFTER H.SEARCH_MEMORY_RESULTS +H.SEARCH_RESULTS_AFTER_THRESHOLD +H.SEARCH_RESULTS_AFTER_DEDUP +H.SEARCH_RESULTS_AFTER_RERANK +H.SEARCH_CONTEXT_RENDER +H.SEARCH_POST_PROCESS_FAILED H.MEM_READER_PRE_EXTRACT H.MEMORY_ITEMS_AFTER_FINE_EXTRACT +H.MEM_READER_EXTRACT_AFTER +H.TEXT_MEMORY_ADD_AFTER +H.SCHEDULER_MEMORY_OPERATION_AFTER H.DREAM_EXECUTE ``` @@ -278,6 +286,24 @@ Hook callbacks receive keyword arguments. Some Hooks define a `pipe_key`; when a callback returns a non-`None` value, that value replaces the named argument for later callbacks and for the caller. +`hook_context` is additive correlation metadata, not a separate event model. +Context-aware callbacks can declare it explicitly or accept `**kwargs`. Legacy +callbacks with an exact signature remain compatible: the runtime omits only an +unsupported `hook_context` argument and still invokes the callback once. New +callbacks should accept `**kwargs` so later additive metadata remains backward +compatible. + +All Search Hooks triggered for one request—from `SEARCH_BEFORE` through +`SEARCH_AFTER`, including result and post-processing Hooks—receive the same +`HookContext` instance and `operation_id`. + +The MemReader extraction, Textual Memory add, and successful Scheduler +operation Hooks pipe their `result` value. Their matching failure Hooks are +notifications and therefore do not define a `pipe_key`. + +`SEARCH_POST_PROCESS_FAILED` reports a result post-processing error that +continues to propagate to the Search API caller. + For example, `add.after` can replace `result`: ```python diff --git a/src/memos/plugins/__init__.py b/src/memos/plugins/__init__.py index 0a0f8cde3..213c8ed9f 100644 --- a/src/memos/plugins/__init__.py +++ b/src/memos/plugins/__init__.py @@ -1,15 +1,26 @@ from memos.plugins.base import MemOSPlugin +from memos.plugins.hook_context import ( + HookContext, + build_hook_context, +) from memos.plugins.hook_defs import H, HookSpec, all_hook_specs, define_hook, get_hook_spec -from memos.plugins.hooks import hookable, register_hook, register_hooks, trigger_hook +from memos.plugins.hooks import ( + hookable, + register_hook, + register_hooks, + trigger_hook, +) from memos.plugins.manager import PluginManager, plugin_manager __all__ = [ "H", + "HookContext", "HookSpec", "MemOSPlugin", "PluginManager", "all_hook_specs", + "build_hook_context", "define_hook", "get_hook_spec", "hookable", diff --git a/src/memos/plugins/base.py b/src/memos/plugins/base.py index 24d356bbf..ad494a6f1 100644 --- a/src/memos/plugins/base.py +++ b/src/memos/plugins/base.py @@ -15,7 +15,7 @@ class MemOSPlugin: """MemOS plugin base class. - Provides three unified registration methods. Plugin developers need only + Provides unified registration methods. Plugin developers need only inherit from this class and register capabilities via self.register_* in init_app. diff --git a/src/memos/plugins/hook_context.py b/src/memos/plugins/hook_context.py new file mode 100644 index 000000000..7b6f3637c --- /dev/null +++ b/src/memos/plugins/hook_context.py @@ -0,0 +1,47 @@ +"""Execution context shared by related plugin Hook calls.""" + +from __future__ import annotations + +# Keep this import available for runtime inspection of the public annotations. +from collections.abc import Mapping # noqa: TC003 +from dataclasses import dataclass, field +from typing import Any +from uuid import uuid4 + + +@dataclass(frozen=True, slots=True) +class HookContext: + """Correlation metadata for one Hook-observable operation.""" + + trace_id: str | None = None + user_id: str | None = None + session_id: str | None = None + task_id: str | None = None + cube_ids: tuple[str, ...] = () + operation_id: str | None = None + source: str | None = None + attributes: Mapping[str, Any] = field(default_factory=dict) + + +def build_hook_context( + *, + source: str, + trace_id: str | None = None, + user_id: str | None = None, + session_id: str | None = None, + task_id: str | None = None, + cube_ids: list[str] | tuple[str, ...] | None = None, + operation_id: str | None = None, + attributes: Mapping[str, Any] | None = None, +) -> HookContext: + """Build correlation metadata at a business-operation boundary.""" + return HookContext( + trace_id=trace_id, + user_id=user_id, + session_id=session_id, + task_id=task_id, + cube_ids=tuple(cube_ids or ()), + operation_id=operation_id or uuid4().hex, + source=source, + attributes=dict(attributes or {}), + ) diff --git a/src/memos/plugins/hook_defs.py b/src/memos/plugins/hook_defs.py index f955da0af..87375e942 100644 --- a/src/memos/plugins/hook_defs.py +++ b/src/memos/plugins/hook_defs.py @@ -74,8 +74,11 @@ class H: # Search extension point before core threshold/dedup/rerank processing. SEARCH_MEMORY_RESULTS = "search.memory_results" + SEARCH_RESULTS_AFTER_THRESHOLD = "search.results.after_threshold" + SEARCH_RESULTS_AFTER_DEDUP = "search.results.after_dedup" SEARCH_RESULTS_AFTER_RERANK = "search.results.after_rerank" SEARCH_CONTEXT_RENDER = "search.context.render" + SEARCH_POST_PROCESS_FAILED = "search.post_process.failed" # Custom Hook (manually triggered via trigger_hook) ADD_MEMORIES_POST_PROCESS = "add.memories.post_process" @@ -92,9 +95,21 @@ class H: # dream — single-provider business hook DREAM_EXECUTE = "dream.execute" + # textual memory — write boundary + TEXT_MEMORY_ADD_AFTER = "text_memory.add.after" + TEXT_MEMORY_ADD_FAILED = "text_memory.add.failed" + + # scheduler — memory operation boundaries inside task handlers + SCHEDULER_MEMORY_OPERATION_AFTER = "scheduler.memory.operation.after" + SCHEDULER_MEMORY_OPERATION_FAILED = "scheduler.memory.operation.failed" + + # mem_reader — generic extension point before LLM extraction + MEM_READER_EXTRACT_AFTER = "mem_reader.extract.after" + MEM_READER_EXTRACT_FAILED = "mem_reader.extract.failed" + # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -# CE custom Hook declarations (@hookable-generated ones need not be declared here) +# CE Hook declarations # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ define_hook( @@ -111,30 +126,67 @@ class H: pipe_key="prompt", ) +define_hook( + H.SEARCH_BEFORE, + description="Before search executes; can modify request", + params=["hook_context", "request"], + pipe_key="request", +) + +define_hook( + H.SEARCH_AFTER, + description="After search executes; can modify result", + params=["hook_context", "request", "result"], + pipe_key="result", +) + define_hook( H.SEARCH_MEMORY_RESULTS, description=( "Allow plugins to merge additional search result buckets before core " "threshold, deduplication, and reranking." ), - params=["handler", "search_req", "results"], + params=["hook_context", "handler", "search_req", "results"], + pipe_key="results", +) + +define_hook( + H.SEARCH_RESULTS_AFTER_THRESHOLD, + description="Allow plugins to observe or update search results after threshold filtering.", + params=["hook_context", "handler", "search_req", "results"], + pipe_key="results", +) + +define_hook( + H.SEARCH_RESULTS_AFTER_DEDUP, + description="Allow plugins to observe or update search results after deduplication.", + params=["hook_context", "handler", "search_req", "results"], pipe_key="results", ) define_hook( H.SEARCH_RESULTS_AFTER_RERANK, description="Allow plugins to update search results after core rerank and before rendering.", - params=["handler", "search_req", "results"], + params=["hook_context", "handler", "search_req", "results"], pipe_key="results", ) define_hook( H.SEARCH_CONTEXT_RENDER, description="Render final search context after retrieval, rerank, and result-level plugins.", - params=["handler", "search_req", "results"], + params=["hook_context", "handler", "search_req", "results"], pipe_key="results", ) +define_hook( + H.SEARCH_POST_PROCESS_FAILED, + description=( + "Observe a failure during core search result processing: " + "threshold filtering, deduplication, or reranking" + ), + params=["hook_context", "handler", "search_req", "error"], +) + define_hook( H.MEMORY_ITEMS_AFTER_FINE_EXTRACT, description="Post-process memory items after mem_reader fine extraction completes", @@ -183,3 +235,65 @@ class H: "scheduler_context", ], ) + +# Operation-boundary Hooks. Their business data remains explicit in the +# normal Hook keyword-argument contract; HookContext only carries correlation +# metadata. +define_hook( + H.TEXT_MEMORY_ADD_AFTER, + description="Observe or replace CubeView Textual Memory output after add returns", + params=["hook_context", "text_memory", "memories", "kwargs", "result"], + pipe_key="result", +) + +define_hook( + H.TEXT_MEMORY_ADD_FAILED, + description="Observe CubeView Textual Memory input and output after add fails", + params=["hook_context", "text_memory", "memories", "kwargs", "error"], +) + +define_hook( + H.SCHEDULER_MEMORY_OPERATION_AFTER, + description="Observe or replace a successful Scheduler memory operation result", + params=["hook_context", "operation", "target", "operation_input", "result"], + pipe_key="result", +) + +define_hook( + H.SCHEDULER_MEMORY_OPERATION_FAILED, + description="Observe a failed Scheduler memory operation and its error", + params=["hook_context", "operation", "target", "operation_input", "error"], +) + +define_hook( + H.MEM_READER_EXTRACT_AFTER, + description="Observe or replace MemReader output after extraction completes", + params=[ + "hook_context", + "mem_reader", + "scene_data", + "type", + "info", + "mode", + "user_name", + "kwargs", + "result", + ], + pipe_key="result", +) + +define_hook( + H.MEM_READER_EXTRACT_FAILED, + description="Observe MemReader extraction input and propagated error after processing fails", + params=[ + "hook_context", + "mem_reader", + "scene_data", + "type", + "info", + "mode", + "user_name", + "kwargs", + "error", + ], +) diff --git a/src/memos/plugins/hooks.py b/src/memos/plugins/hooks.py index d5b64ce82..4128da3b7 100644 --- a/src/memos/plugins/hooks.py +++ b/src/memos/plugins/hooks.py @@ -3,6 +3,7 @@ from __future__ import annotations import asyncio +import inspect import logging from collections import defaultdict @@ -19,6 +20,43 @@ _hooks: dict[str, list[Callable]] = defaultdict(list) +def _accepts_hook_context(callback: Callable) -> bool: + """Return whether a callback accepts the additive ``hook_context`` keyword.""" + try: + parameters = inspect.signature(callback).parameters.values() + except (TypeError, ValueError): + return False + + return any( + parameter.kind is inspect.Parameter.VAR_KEYWORD + or ( + parameter.name == "hook_context" + and parameter.kind + in { + inspect.Parameter.POSITIONAL_OR_KEYWORD, + inspect.Parameter.KEYWORD_ONLY, + } + ) + for parameter in parameters + ) + + +def _invoke_hook_callback(callback: Callable, kwargs: dict[str, Any]) -> Any: + """Invoke one callback while preserving legacy exact-signature Hooks. + + ``hook_context`` is additive framework metadata. Older callbacks that use + an exact keyword-only signature continue to receive the original business + arguments; context-aware callbacks and callbacks with ``**kwargs`` receive + the complete contract. + """ + if "hook_context" not in kwargs or _accepts_hook_context(callback): + return callback(**kwargs) + + legacy_kwargs = dict(kwargs) + legacy_kwargs.pop("hook_context") + return callback(**legacy_kwargs) + + def register_hook(name: str, callback: Callable) -> None: """Register a hook callback. Undeclared hook names will log a warning.""" from memos.plugins.hook_defs import get_hook_spec @@ -61,7 +99,7 @@ def trigger_hook(name: str, **kwargs: Any) -> Any: for cb in _hooks.get(name, []): try: - rv = cb(**kwargs) + rv = _invoke_hook_callback(cb, kwargs) if pipe_key is not None and rv is not None: kwargs[pipe_key] = rv except Exception: @@ -90,7 +128,7 @@ def trigger_single_hook(name: str, **kwargs: Any) -> Any: cb = callbacks[0] try: - return cb(**kwargs) + return _invoke_hook_callback(cb, kwargs) except Exception: logger.exception( "Single hook %s callback %s failed", @@ -100,25 +138,37 @@ def trigger_single_hook(name: str, **kwargs: Any) -> Any: raise -def hookable(name: str): +def hookable( + name: str, + *, + context_builder: Callable[[Any, Any], Any] | None = None, +): """Decorator: automatically triggers name.before / name.after hook before and after the method. Auto-declares before/after Hooks (idempotent); no need to manually define_hook in hook_defs.py. Supports piped return values: before can modify request, after can modify result. + When ``context_builder`` is provided, one context is built before the first + Hook and passed to both Hooks and the decorated method as ``hook_context``. Compatible with both sync and async methods. """ from memos.plugins.hook_defs import define_hook + before_params = ["request"] + after_params = ["request", "result"] + if context_builder is not None: + before_params.insert(0, "hook_context") + after_params.insert(0, "hook_context") + define_hook( f"{name}.before", description=f"Before {name} executes; can modify request", - params=["request"], + params=before_params, pipe_key="request", ) define_hook( f"{name}.after", description=f"After {name} executes; can modify result", - params=["request", "result"], + params=after_params, pipe_key="result", ) @@ -127,10 +177,22 @@ def decorator(func): @wraps(func) async def async_wrapper(self, request, *args, **kwargs): - rv = trigger_hook(f"{name}.before", request=request) + hook_context = kwargs.get("hook_context") + if hook_context is None and context_builder is not None: + hook_context = context_builder(self, request) + before_kwargs = {"request": request} + call_kwargs = dict(kwargs) + if context_builder is not None: + before_kwargs["hook_context"] = hook_context + call_kwargs["hook_context"] = hook_context + + rv = trigger_hook(f"{name}.before", **before_kwargs) request = rv if rv is not None else request - result = await func(self, request, *args, **kwargs) - rv = trigger_hook(f"{name}.after", request=request, result=result) + result = await func(self, request, *args, **call_kwargs) + after_kwargs = {"request": request, "result": result} + if context_builder is not None: + after_kwargs["hook_context"] = hook_context + rv = trigger_hook(f"{name}.after", **after_kwargs) result = rv if rv is not None else result return result @@ -138,10 +200,22 @@ async def async_wrapper(self, request, *args, **kwargs): @wraps(func) def sync_wrapper(self, request, *args, **kwargs): - rv = trigger_hook(f"{name}.before", request=request) + hook_context = kwargs.get("hook_context") + if hook_context is None and context_builder is not None: + hook_context = context_builder(self, request) + before_kwargs = {"request": request} + call_kwargs = dict(kwargs) + if context_builder is not None: + before_kwargs["hook_context"] = hook_context + call_kwargs["hook_context"] = hook_context + + rv = trigger_hook(f"{name}.before", **before_kwargs) request = rv if rv is not None else request - result = func(self, request, *args, **kwargs) - rv = trigger_hook(f"{name}.after", request=request, result=result) + result = func(self, request, *args, **call_kwargs) + after_kwargs = {"request": request, "result": result} + if context_builder is not None: + after_kwargs["hook_context"] = hook_context + rv = trigger_hook(f"{name}.after", **after_kwargs) result = rv if rv is not None else result return result diff --git a/tests/api/test_search_pipeline_hooks.py b/tests/api/test_search_pipeline_hooks.py index befff6b80..329a03350 100644 --- a/tests/api/test_search_pipeline_hooks.py +++ b/tests/api/test_search_pipeline_hooks.py @@ -1,6 +1,20 @@ +import pytest + +from memos.api.handlers.base_handler import HandlerDependencies from memos.api.handlers.formatters_handler import rerank_knowledge_mem +from memos.api.handlers.search_handler import SearchHandler from memos.api.product_models import APISearchRequest +from memos.multi_mem_cube.single_cube import SingleCubeView +from memos.plugins.hook_context import HookContext from memos.plugins.hook_defs import H, get_hook_spec +from memos.plugins.hooks import _hooks, register_hook + + +@pytest.fixture(autouse=True) +def _reset_registered_hooks(): + _hooks.clear() + yield + _hooks.clear() def _memory(memory_id: str, memory: str, memory_type: str = "LongTermMemory") -> dict: @@ -27,6 +41,39 @@ def _file_memory(memory_id: str, memory: str, source_content: str) -> dict: } +def _empty_search_results() -> dict: + return { + "text_mem": [], + "act_mem": [], + "para_mem": [], + "pref_mem": [], + "pref_note": "", + "tool_mem": [], + "skill_mem": [], + } + + +def _search_handler(results: dict | None = None) -> tuple[SearchHandler, SingleCubeView]: + handler = SearchHandler( + HandlerDependencies( + naive_mem_cube=object(), + mem_scheduler=object(), + searcher=object(), + deepsearch_agent=object(), + ) + ) + cube_view = SingleCubeView.__new__(SingleCubeView) + search_results = results if results is not None else _empty_search_results() + cube_view.search_memories = lambda _request: search_results + # Preserve the existing _build_cube_view(search_req) call contract. + handler._build_cube_view = lambda _search_req: cube_view + return handler, cube_view + + +def _raise(error: Exception): + raise error + + def test_search_request_passes_context_format_through_to_plugins(): req = APISearchRequest( user_id="user", @@ -38,16 +85,136 @@ def test_search_request_passes_context_format_through_to_plugins(): def test_search_pipeline_hook_specs_are_registered(): - after_rerank = get_hook_spec(H.SEARCH_RESULTS_AFTER_RERANK) - render = get_hook_spec(H.SEARCH_CONTEXT_RENDER) + for hook_name in (H.SEARCH_RESULTS_AFTER_RERANK, H.SEARCH_CONTEXT_RENDER): + spec = get_hook_spec(hook_name) + assert spec is not None + assert spec.pipe_key == "results" + assert spec.params == ["hook_context", "handler", "search_req", "results"] + + +@pytest.mark.parametrize( + ("hook_name", "params", "pipe_key"), + [ + (H.SEARCH_BEFORE, ["hook_context", "request"], "request"), + (H.SEARCH_AFTER, ["hook_context", "request", "result"], "result"), + ( + H.SEARCH_MEMORY_RESULTS, + ["hook_context", "handler", "search_req", "results"], + "results", + ), + ( + H.SEARCH_RESULTS_AFTER_THRESHOLD, + ["hook_context", "handler", "search_req", "results"], + "results", + ), + ( + H.SEARCH_RESULTS_AFTER_DEDUP, + ["hook_context", "handler", "search_req", "results"], + "results", + ), + ( + H.SEARCH_POST_PROCESS_FAILED, + ["hook_context", "handler", "search_req", "error"], + None, + ), + ], +) +def test_search_hook_specs_match_trigger_contracts(hook_name, params, pipe_key): + spec = get_hook_spec(hook_name) + + assert spec is not None + assert spec.params == params + assert spec.pipe_key == pipe_key + + +def test_search_success_hooks_run_in_order_and_share_one_context(monkeypatch): + events: list[tuple[str, dict]] = [] + handler, cube_view = _search_handler() + search_req = APISearchRequest( + user_id="user", + query="query", + session_id="session-1", + readable_cube_ids=["cube-1", "cube-2", "cube-1"], + ) + monkeypatch.setattr( + "memos.api.handlers.search_handler.get_current_trace_id", + lambda: "trace-1", + ) + + def record(hook_name): + def callback(**kwargs): + events.append((hook_name, kwargs)) + + return callback + + ordered_hooks = [ + H.SEARCH_BEFORE, + H.SEARCH_MEMORY_RESULTS, + H.SEARCH_RESULTS_AFTER_THRESHOLD, + H.SEARCH_RESULTS_AFTER_DEDUP, + H.SEARCH_RESULTS_AFTER_RERANK, + H.SEARCH_CONTEXT_RENDER, + H.SEARCH_AFTER, + ] + for hook_name in ordered_hooks: + register_hook(hook_name, record(hook_name)) + + handler.handle_search_memories(search_req) + + assert [name for name, _kwargs in events] == ordered_hooks + contexts = [kwargs["hook_context"] for _name, kwargs in events] + assert all(context is contexts[0] for context in contexts) + context = contexts[0] + assert isinstance(context, HookContext) + assert context.trace_id == "trace-1" + assert context.user_id == "user" + assert context.session_id == "session-1" + assert context.cube_ids == ("cube-1", "cube-2") + assert context.source == "api.search" + assert context.attributes == {"mode": "fast"} + assert context.operation_id is not None + assert not hasattr(cube_view, "search_hook_context") + - assert after_rerank is not None - assert after_rerank.pipe_key == "results" - assert after_rerank.params == ["handler", "search_req", "results"] +def test_search_context_render_hook_can_replace_results(): + handler, _cube_view = _search_handler() + search_req = APISearchRequest(user_id="user", query="query") + + def render(*, results, **_kwargs): + return {**results, "rendered_by_plugin": True} + + register_hook(H.SEARCH_CONTEXT_RENDER, render) + + response = handler.handle_search_memories(search_req) + + assert response.data["rendered_by_plugin"] is True + + +def test_search_post_processing_failure_triggers_only_post_process_hook(monkeypatch): + error = RuntimeError("post processing failed") + post_process_failures = [] + handler, _cube_view = _search_handler() + handler._apply_relativity_threshold = lambda _results, _relativity: _raise(error) + search_req = APISearchRequest(user_id="user", query="query") + monkeypatch.setattr( + "memos.api.handlers.search_handler.get_current_trace_id", + lambda: "trace-1", + ) + + register_hook( + H.SEARCH_POST_PROCESS_FAILED, + lambda **kwargs: post_process_failures.append(kwargs), + ) + with pytest.raises(RuntimeError, match="post processing failed"): + handler.handle_search_memories(search_req) - assert render is not None - assert render.pipe_key == "results" - assert render.params == ["handler", "search_req", "results"] + assert len(post_process_failures) == 1 + assert post_process_failures[0]["error"] is error + context = post_process_failures[0]["hook_context"] + assert isinstance(context, HookContext) + assert context.trace_id == "trace-1" + assert context.user_id == "user" + assert context.operation_id is not None def test_rerank_knowledge_mem_preserves_conversation_sources_by_default(): diff --git a/tests/mem_reader/test_hook_pipeline.py b/tests/mem_reader/test_hook_pipeline.py new file mode 100644 index 000000000..986fcffda --- /dev/null +++ b/tests/mem_reader/test_hook_pipeline.py @@ -0,0 +1,121 @@ +"""MemReader success/failure Hook contracts and result piping.""" + +from __future__ import annotations + +from types import MethodType +from uuid import UUID + +import pytest + +from memos.mem_reader.simple_struct import SimpleStructMemReader +from memos.plugins.hook_context import HookContext +from memos.plugins.hook_defs import H +from memos.plugins.hooks import _hooks, register_hook + + +@pytest.fixture(autouse=True) +def _reset_registered_hooks(): + _hooks.clear() + yield + _hooks.clear() + + +def test_extract_after_hook_can_replace_reader_result(): + reader = object.__new__(SimpleStructMemReader) + original_result = [["original"]] + plugin_result = [["plugin"]] + + def fake_read_memory(self, *args, **kwargs): + return original_result + + reader._read_memory = MethodType(fake_read_memory, reader) + register_hook(H.MEM_READER_EXTRACT_AFTER, lambda **_kwargs: plugin_result) + + result = reader.get_memory( + [{"role": "user", "content": "remember this"}], + type="chat", + info={"user_id": "alice", "session_id": "session-1"}, + ) + + assert result == plugin_result + + +def test_extract_after_hook_receives_context_and_business_values(monkeypatch): + reader = object.__new__(SimpleStructMemReader) + result = [["memory"]] + scene_data = [{"role": "user", "content": "remember this"}] + info = {"user_id": "alice", "session_id": "session-1"} + captured = {} + + def fake_read_memory(self, *args, **kwargs): + return result + + reader._read_memory = MethodType(fake_read_memory, reader) + monkeypatch.setattr("memos.mem_reader.simple_struct.get_current_trace_id", lambda: "trace-1") + register_hook(H.MEM_READER_EXTRACT_AFTER, lambda **kwargs: captured.update(kwargs)) + + actual = reader.get_memory( + scene_data, + type="chat", + info=info, + mode="fine", + user_name="cube-1", + chat_history=[], + ) + + assert actual is result + context = captured.pop("hook_context") + assert isinstance(context, HookContext) + assert context.trace_id == "trace-1" + assert context.user_id == "alice" + assert context.session_id == "session-1" + assert context.cube_ids == ("cube-1",) + assert context.source == "mem_reader.extract" + assert context.attributes == {"mode": "fine", "type": "chat"} + assert context.operation_id is not None + assert UUID(context.operation_id).hex == context.operation_id + assert captured == { + "mem_reader": reader, + "scene_data": scene_data, + "type": "chat", + "info": info, + "mode": "fine", + "user_name": "cube-1", + "kwargs": {"chat_history": []}, + "result": result, + } + + +def test_extract_failure_hook_preserves_original_error_and_skips_after(monkeypatch): + reader = object.__new__(SimpleStructMemReader) + error = ValueError("reader failed") + failed_events = [] + after_events = [] + + def fake_read_memory(self, *args, **kwargs): + raise error + + def on_failed(**kwargs): + failed_events.append(kwargs) + raise RuntimeError("plugin failed") + + reader._read_memory = MethodType(fake_read_memory, reader) + monkeypatch.setattr("memos.mem_reader.simple_struct.get_current_trace_id", lambda: "trace-1") + register_hook(H.MEM_READER_EXTRACT_FAILED, on_failed) + register_hook(H.MEM_READER_EXTRACT_AFTER, lambda **kwargs: after_events.append(kwargs)) + + with pytest.raises(ValueError, match="reader failed") as exc_info: + reader.get_memory( + [{"role": "user", "content": "remember this"}], + type="chat", + info={"user_id": "alice", "session_id": "session-1"}, + mode="fast", + user_name="cube-1", + ) + + assert exc_info.value is error + assert len(failed_events) == 1 + assert failed_events[0]["error"] is error + assert failed_events[0]["hook_context"].source == "mem_reader.extract" + assert failed_events[0]["hook_context"].operation_id is not None + assert after_events == [] diff --git a/tests/mem_scheduler/test_operation_observer.py b/tests/mem_scheduler/test_operation_observer.py new file mode 100644 index 000000000..b8513e5d5 --- /dev/null +++ b/tests/mem_scheduler/test_operation_observer.py @@ -0,0 +1,150 @@ +"""Scheduler operation Hook contracts at existing exception boundaries.""" + +from __future__ import annotations + +from uuid import UUID + +import pytest + +from memos.mem_scheduler.task_schedule_modules.operation_observer import ( + SchedulerOperationObserver, +) +from memos.plugins.hook_context import HookContext +from memos.plugins.hook_defs import H +from memos.plugins.hooks import _hooks, register_hook + + +@pytest.fixture(autouse=True) +def _reset_registered_hooks(): + _hooks.clear() + yield + _hooks.clear() + + +def test_scheduler_observer_emits_context_and_business_values_as_hook_kwargs(): + captured = {} + register_hook( + H.SCHEDULER_MEMORY_OPERATION_AFTER, + lambda **kwargs: captured.update(kwargs), + ) + + with SchedulerOperationObserver( + source="scheduler.mem_read.add_enhanced_memories", + operation="add", + target="textual_memory", + operation_context={"trace_id": "trace-1", "task_id": "task-1"}, + operation_input={"memory_ids": ["memory-1"]}, + ) as observer: + observer.result(["stored-1"]) + + assert isinstance(captured["hook_context"], HookContext) + assert captured["hook_context"].trace_id == "trace-1" + assert captured["operation"] == "add" + assert captured["target"] == "textual_memory" + assert captured["operation_input"] == {"memory_ids": ["memory-1"]} + assert captured["result"] == ["stored-1"] + assert "event" not in captured + + +def test_scheduler_observer_failure_hook_preserves_original_error_and_skips_after(): + error = ValueError("scheduler operation failed") + failed_events = [] + after_events = [] + + def on_failed(**kwargs): + failed_events.append(kwargs) + raise RuntimeError("plugin failed") + + register_hook(H.SCHEDULER_MEMORY_OPERATION_FAILED, on_failed) + register_hook( + H.SCHEDULER_MEMORY_OPERATION_AFTER, + lambda **kwargs: after_events.append(kwargs), + ) + observer = SchedulerOperationObserver( + source="scheduler.mem_read.fine_transfer_simple_mem", + operation="fine", + target="textual_memory", + operation_context={ + "trace_id": "trace-1", + "user_id": "alice", + "session_id": "session-1", + "task_id": "task-1", + "mem_cube_id": "cube-1", + "item_id": "item-1", + "label": "mem_read", + }, + operation_input={"memory_ids": ["memory-1"]}, + capture_failure=True, + ) + + with pytest.raises(ValueError, match="scheduler operation failed") as exc_info, observer: + raise error + + assert exc_info.value is error + assert len(failed_events) == 1 + event = failed_events[0] + context = event["hook_context"] + assert isinstance(context, HookContext) + assert context.trace_id == "trace-1" + assert context.user_id == "alice" + assert context.session_id == "session-1" + assert context.task_id == "task-1" + assert context.cube_ids == ("cube-1",) + assert context.source == "scheduler.mem_read.fine_transfer_simple_mem" + assert context.attributes == {"scheduler_item_id": "item-1", "label": "mem_read"} + assert context.operation_id is not None + assert UUID(context.operation_id).hex == context.operation_id + assert event["operation"] == "fine" + assert event["target"] == "textual_memory" + assert event["operation_input"] == {"memory_ids": ["memory-1"]} + assert event["error"] is error + assert after_events == [] + assert observer.value is None + + +def test_scheduler_observer_emits_explicit_failure_only_once(): + failed_events = [] + after_events = [] + error = ValueError("scheduler operation failed") + + register_hook( + H.SCHEDULER_MEMORY_OPERATION_FAILED, + lambda **kwargs: failed_events.append(kwargs), + ) + register_hook( + H.SCHEDULER_MEMORY_OPERATION_AFTER, + lambda **kwargs: after_events.append(kwargs), + ) + + with SchedulerOperationObserver( + source="scheduler.mem_read.remove_memories", + operation="delete", + target="textual_memory", + operation_context={"trace_id": "trace-1"}, + operation_input={"memory_ids": ["memory-1"]}, + ) as observer: + observer.failed(error) + observer.failed(error) + observer.result(None) + + assert len(failed_events) == 1 + assert failed_events[0]["error"] is error + assert after_events == [] + + +def test_scheduler_observer_exposes_piped_result_after_successful_exit(): + register_hook( + H.SCHEDULER_MEMORY_OPERATION_AFTER, + lambda **_kwargs: ["plugin-result"], + ) + + with SchedulerOperationObserver( + source="scheduler.mem_read.add_enhanced_memories", + operation="add", + target="textual_memory", + operation_context={"trace_id": "trace-1"}, + operation_input={}, + ) as observer: + observer.result(["original-result"]) + + assert observer.value == ["plugin-result"] diff --git a/tests/multi_mem_cube/test_single_cube_hooks.py b/tests/multi_mem_cube/test_single_cube_hooks.py new file mode 100644 index 000000000..b384157ba --- /dev/null +++ b/tests/multi_mem_cube/test_single_cube_hooks.py @@ -0,0 +1,142 @@ +"""Textual Memory Hook behavior at the SingleCubeView write boundary.""" + +from __future__ import annotations + +import logging +import uuid + +from importlib import import_module +from unittest.mock import MagicMock + +import pytest + +from memos.plugins.hook_context import HookContext +from memos.plugins.hook_defs import H +from memos.plugins.hooks import _hooks, register_hook + + +@pytest.fixture(autouse=True) +def _reset_registered_hooks(): + _hooks.clear() + yield + _hooks.clear() + + +def _make_add_request(**overrides): + from memos.api.product_models import APIADDRequest + + values = { + "user_id": "test_user", + "messages": [ + {"role": "user", "content": "remember this"}, + {"role": "assistant", "content": "ok"}, + ], + **overrides, + } + return APIADDRequest(**values) + + +@pytest.fixture +def single_cube_view(): + # Initialize handlers before importing SingleCubeView to avoid the existing + # handlers/single_cube import cycle when this file runs in isolation. + import_module("memos.api.handlers") + from memos.memories.textual.item import ( + TextualMemoryItem, + TreeNodeTextualMemoryMetadata, + ) + from memos.multi_mem_cube.single_cube import SingleCubeView + + memory = TextualMemoryItem( + id=str(uuid.uuid4()), + memory="hello world", + metadata=TreeNodeTextualMemoryMetadata( + user_id="u1", + session_id="s1", + memory_type="WorkingMemory", + sources=[], + info={}, + ), + ) + mem_reader = MagicMock() + mem_reader.get_memory.return_value = [[memory]] + mem_reader.save_rawfile = False + text_memory = MagicMock() + text_memory.add.return_value = [memory.id] + text_memory.mode = "async" + mem_cube = MagicMock() + mem_cube.text_mem = text_memory + + view = SingleCubeView( + cube_id="cube_test", + naive_mem_cube=mem_cube, + mem_reader=mem_reader, + mem_scheduler=MagicMock(), + logger=logging.getLogger("test.single_cube.hooks"), + searcher=None, + feedback_server=None, + ) + return view, memory + + +def test_text_memory_after_hook_can_replace_memory_ids(single_cube_view): + view, _memory = single_cube_view + register_hook(H.TEXT_MEMORY_ADD_AFTER, lambda **_kwargs: ["plugin-memory-id"]) + + results = view.add_memories(_make_add_request(async_mode="async")) + + assert results[0]["memory_id"] == "plugin-memory-id" + submitted_message = view.mem_scheduler.submit_messages.call_args.kwargs["messages"][0] + assert submitted_message.mem_cube_id == "cube_test" + assert submitted_message.content == '["plugin-memory-id"]' + + +def test_text_memory_failure_hook_preserves_original_error_and_skips_after( + single_cube_view, + monkeypatch, +): + view, memory = single_cube_view + error = ValueError("text memory add failed") + failed_calls = [] + after_calls = [] + view.naive_mem_cube.text_mem.add.side_effect = error + monkeypatch.setattr( + "memos.multi_mem_cube.single_cube.get_current_trace_id", + lambda: "trace-1", + ) + + def on_failed(**kwargs): + failed_calls.append(kwargs) + raise RuntimeError("plugin failed") + + register_hook(H.TEXT_MEMORY_ADD_FAILED, on_failed) + register_hook(H.TEXT_MEMORY_ADD_AFTER, lambda **kwargs: after_calls.append(kwargs)) + + with pytest.raises(ValueError, match="text memory add failed") as exc_info: + view.add_memories( + _make_add_request( + async_mode="async", + session_id="session-1", + task_id="task-1", + ) + ) + + assert exc_info.value is error + assert after_calls == [] + assert len(failed_calls) == 1 + call = failed_calls[0] + context = call["hook_context"] + assert isinstance(context, HookContext) + assert context.trace_id == "trace-1" + assert context.user_id == "test_user" + assert context.session_id == "session-1" + assert context.task_id == "task-1" + assert context.cube_ids == ("cube_test",) + assert context.source == "cube_view.text_mem.add" + assert context.attributes == {"sync_mode": "async", "extract_mode": "fast"} + assert context.operation_id is not None + assert call["text_memory"] is view.naive_mem_cube.text_mem + assert call["memories"] == [memory] + assert call["kwargs"] == {"user_name": "cube_test"} + assert call["error"] is error + view.mem_scheduler.submit_messages.assert_not_called() diff --git a/tests/plugins/test_hook_context.py b/tests/plugins/test_hook_context.py new file mode 100644 index 000000000..c1fdad0bd --- /dev/null +++ b/tests/plugins/test_hook_context.py @@ -0,0 +1,312 @@ +"""HookContext values, callback compatibility, and @hookable propagation.""" + +from __future__ import annotations + +import asyncio + +from collections.abc import Mapping +from typing import Any, get_type_hints +from uuid import UUID + +import pytest + +from memos.plugins.hook_context import HookContext, build_hook_context +from memos.plugins.hook_defs import H, define_hook, get_hook_spec +from memos.plugins.hooks import ( + _hooks, + hookable, + register_hook, + trigger_hook, + trigger_single_hook, +) + + +@pytest.fixture(autouse=True) +def _reset_registered_hooks(): + _hooks.clear() + yield + _hooks.clear() + + +def test_hook_context_type_hints_are_runtime_resolvable(): + hints = get_type_hints(HookContext) + + assert hints["attributes"] == Mapping[str, Any] + assert hints["operation_id"] == str | None + + +def test_build_hook_context_populates_correlation_metadata(): + cube_ids = ["cube-1", "cube-2"] + attributes = {"mode": "fine"} + + context = build_hook_context( + source="mem_reader.extract", + trace_id="trace-1", + user_id="user-1", + session_id="session-1", + task_id="task-1", + cube_ids=cube_ids, + operation_id="operation-1", + attributes=attributes, + ) + cube_ids.append("cube-3") + attributes["mode"] = "mutated" + + assert context == HookContext( + trace_id="trace-1", + user_id="user-1", + session_id="session-1", + task_id="task-1", + cube_ids=("cube-1", "cube-2"), + operation_id="operation-1", + source="mem_reader.extract", + attributes={"mode": "fine"}, + ) + + +def test_build_hook_context_generates_unique_operation_ids(): + first = build_hook_context(source="text_memory.add") + second = build_hook_context(source="text_memory.add") + + assert first.operation_id is not None + assert second.operation_id is not None + assert UUID(first.operation_id).hex == first.operation_id + assert UUID(second.operation_id).hex == second.operation_id + assert first.operation_id != second.operation_id + + +def test_context_aware_hook_specs_match_trigger_contracts(): + expected = { + H.TEXT_MEMORY_ADD_AFTER: ( + ["hook_context", "text_memory", "memories", "kwargs", "result"], + "result", + ), + H.TEXT_MEMORY_ADD_FAILED: ( + ["hook_context", "text_memory", "memories", "kwargs", "error"], + None, + ), + H.SCHEDULER_MEMORY_OPERATION_AFTER: ( + ["hook_context", "operation", "target", "operation_input", "result"], + "result", + ), + H.SCHEDULER_MEMORY_OPERATION_FAILED: ( + ["hook_context", "operation", "target", "operation_input", "error"], + None, + ), + H.MEM_READER_EXTRACT_AFTER: ( + [ + "hook_context", + "mem_reader", + "scene_data", + "type", + "info", + "mode", + "user_name", + "kwargs", + "result", + ], + "result", + ), + H.MEM_READER_EXTRACT_FAILED: ( + [ + "hook_context", + "mem_reader", + "scene_data", + "type", + "info", + "mode", + "user_name", + "kwargs", + "error", + ], + None, + ), + } + + for hook_name, (params, pipe_key) in expected.items(): + spec = get_hook_spec(hook_name) + assert spec is not None + assert spec.params == params + assert spec.pipe_key == pipe_key + + +def test_hook_context_is_omitted_only_for_legacy_exact_signature_callbacks(): + hook_name = "test.hook-context.compat" + define_hook( + hook_name, + description="hook context compatibility test", + params=["hook_context", "result"], + pipe_key="result", + ) + context = object() + calls = [] + + def legacy_callback(*, result): + calls.append(("legacy", result)) + return result + 1 + + def context_callback(*, hook_context, result): + calls.append(("context", hook_context, result)) + return result + 1 + + def kwargs_callback(*, result, **kwargs): + calls.append(("kwargs", kwargs["hook_context"], result)) + return result + 1 + + register_hook(hook_name, legacy_callback) + register_hook(hook_name, context_callback) + register_hook(hook_name, kwargs_callback) + + result = trigger_hook(hook_name, hook_context=context, result=1) + + assert result == 4 + assert calls == [ + ("legacy", 1), + ("context", context, 2), + ("kwargs", context, 3), + ] + + +def test_hook_callback_type_error_is_not_retried(): + hook_name = "test.hook-context.type-error" + define_hook( + hook_name, + description="hook callback type error test", + params=["hook_context", "value"], + ) + calls = [] + + def callback(*, hook_context, value): + calls.append((hook_context, value)) + raise TypeError("raised inside callback") + + register_hook(hook_name, callback) + + trigger_hook(hook_name, hook_context="context", value="value") + + assert calls == [("context", "value")] + + +def test_trigger_single_hook_supports_legacy_exact_signature(): + hook_name = "test.single.hook-context" + define_hook( + hook_name, + description="single hook context compatibility test", + params=["hook_context", "value"], + ) + + def handler(*, value): + return value + 1 + + register_hook(hook_name, handler) + + result = trigger_single_hook(hook_name, hook_context=object(), value=1) + + assert result == 2 + + +def test_hookable_shares_context_with_sync_operation_and_legacy_callback(): + context = object() + calls = [] + + class Handler: + @hookable( + "context_sync", + context_builder=lambda _self, _request: context, + ) + def run(self, request, *, hook_context=None): + calls.append(("operation", hook_context, request)) + return f"processed:{request}" + + def legacy_before(*, request): + calls.append(("legacy_before", request)) + + def context_before(*, hook_context, request): + calls.append(("context_before", hook_context, request)) + + def context_after(*, hook_context, request, result): + calls.append(("context_after", hook_context, request, result)) + + register_hook("context_sync.before", legacy_before) + register_hook("context_sync.before", context_before) + register_hook("context_sync.after", context_after) + + result = Handler().run("request") + + assert result == "processed:request" + assert calls == [ + ("legacy_before", "request"), + ("context_before", context, "request"), + ("operation", context, "request"), + ("context_after", context, "request", "processed:request"), + ] + before_spec = get_hook_spec("context_sync.before") + after_spec = get_hook_spec("context_sync.after") + assert before_spec is not None + assert after_spec is not None + assert before_spec.params == ["hook_context", "request"] + assert after_spec.params == [ + "hook_context", + "request", + "result", + ] + + +def test_hookable_reuses_explicit_context_without_calling_builder(): + supplied_context = object() + builder_calls = [] + observed_contexts = [] + + def build_context(_self, request): + builder_calls.append(request) + return object() + + class Handler: + @hookable("explicit_context", context_builder=build_context) + def run(self, request, *, hook_context=None): + observed_contexts.append(hook_context) + return request + + def observe_context(*, hook_context, **_kwargs): + observed_contexts.append(hook_context) + + register_hook("explicit_context.before", observe_context) + register_hook("explicit_context.after", observe_context) + + result = Handler().run("request", hook_context=supplied_context) + + assert result == "request" + assert builder_calls == [] + assert observed_contexts == [supplied_context] * 3 + + +def test_hookable_shares_context_with_async_operation(): + context = object() + calls = [] + + class Handler: + @hookable( + "context_async", + context_builder=lambda _self, _request: context, + ) + async def run(self, request, *, hook_context=None): + calls.append(("operation", hook_context, request)) + return "async_result" + + def on_before(*, hook_context, request): + calls.append(("before", hook_context, request)) + + def on_after(*, hook_context, request, result): + calls.append(("after", hook_context, request, result)) + + register_hook("context_async.before", on_before) + register_hook("context_async.after", on_after) + + result = asyncio.run(Handler().run("request")) + + assert result == "async_result" + assert calls == [ + ("before", context, "request"), + ("operation", context, "request"), + ("after", context, "request", "async_result"), + ] From 16f00d771b4215add48070587ebb036c27c36b81 Mon Sep 17 00:00:00 2001 From: qzs Date: Thu, 15 Oct 2026 20:35:06 +0800 Subject: [PATCH 2/9] fix(mem-reader): preserve input order in concurrent fine transfer --- src/memos/mem_reader/simple_struct.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/memos/mem_reader/simple_struct.py b/src/memos/mem_reader/simple_struct.py index 14521cf47..4db01d90f 100644 --- a/src/memos/mem_reader/simple_struct.py +++ b/src/memos/mem_reader/simple_struct.py @@ -815,7 +815,7 @@ def fine_transfer_simple_mem( if not input_memories: return [] - memory_list = [] + memory_list = [[] for _ in input_memories] if type == "chat": processing_func = self._process_transfer_chat_data @@ -826,15 +826,15 @@ def fine_transfer_simple_mem( # Process Q&A pairs concurrently with context propagation with ContextThreadPoolExecutor() as executor: - futures = [ - executor.submit(processing_func, scene_data_info, custom_tags, **kwargs) - for scene_data_info in input_memories - ] + futures = { + executor.submit(processing_func, scene_data_info, custom_tags, **kwargs): index + for index, scene_data_info in enumerate(input_memories) + } for future in concurrent.futures.as_completed(futures): try: res_memory = future.result() if res_memory is not None: - memory_list.append(res_memory) + memory_list[futures[future]] = res_memory except Exception as e: logger.error(f"Task failed with exception: {e}") logger.error(traceback.format_exc()) From 1378dec559c6621aa2e84f6f299381a36cfcd208 Mon Sep 17 00:00:00 2001 From: qzs Date: Thu, 15 Oct 2026 20:36:05 +0800 Subject: [PATCH 3/9] feat(hooks): expose fine-transfer result grouping --- .../handlers/mem_read_handler.py | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py b/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py index a61744785..2e343bb07 100644 --- a/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py +++ b/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py @@ -182,7 +182,11 @@ def _process_memories_with_reader( operation="fine", target="textual_memory", operation_context=operation_context, - operation_input={"memories": memory_items, "type": "chat"}, + operation_input={ + "memories": memory_items, + "type": "chat", + "result_grouping": self._fine_transfer_result_grouping(mem_reader), + }, capture_failure=True, ) as observation: observation.result( @@ -574,3 +578,18 @@ def _try_submit_organize_task( ) except Exception as e: logger.error("Failed to enqueue MEM_ORGANIZE task: %s", e, exc_info=True) + + def _fine_transfer_result_grouping(self, mem_reader: Any) -> str: + """Describe known transfer implementations at the observation boundary.""" + + from memos.mem_reader.multi_modal_struct import MultiModalStructMemReader + from memos.mem_reader.simple_struct import SimpleStructMemReader + + # Match the bound implementation so inherited methods work, while overrides + # with a different grouping contract remain unknown. + transfer = getattr(mem_reader.fine_transfer_simple_mem, "__func__", None) + if transfer is MultiModalStructMemReader.fine_transfer_simple_mem: + return "batch" + if transfer is SimpleStructMemReader.fine_transfer_simple_mem: + return "per_input" + return "unknown" From a57c5e13f34cd4aaa6a924805a7e6702979b5ecd Mon Sep 17 00:00:00 2001 From: Chen Jiang Date: Thu, 15 Oct 2026 20:50:50 +0800 Subject: [PATCH 4/9] test(hooks): streamline contracts and cover reader integration Port the reviewed Hook-only tests from smartcomment-integration. Keep upstream Search tests intact apart from required hook_context assertions, and isolate new behavior tests with an opt-in fixture. Cover Reader grouping/order and all five MemRead operation sites. Validation on feat/add-more-plugin-hooks: 49 targeted tests passed; related regression: 266 passed, 1 skipped. Individual test files, Ruff, staged pre-commit, and diff checks passed. Full make test stopped after 180 seconds at the existing Ollama network request. --- tests/api/test_search_hook_context.py | 178 +++++++++ tests/api/test_search_pipeline_hooks.py | 183 +--------- tests/conftest.py | 11 + tests/mem_reader/test_fine_transfer_order.py | 44 +++ tests/mem_reader/test_hook_pipeline.py | 84 ++--- tests/mem_scheduler/test_mem_read_grouping.py | 132 +++++++ .../mem_scheduler/test_operation_observer.py | 296 ++++++++++----- .../multi_mem_cube/test_single_cube_hooks.py | 70 ++-- tests/plugins/test_hook_context.py | 338 ++++++------------ 9 files changed, 746 insertions(+), 590 deletions(-) create mode 100644 tests/api/test_search_hook_context.py create mode 100644 tests/conftest.py create mode 100644 tests/mem_reader/test_fine_transfer_order.py create mode 100644 tests/mem_scheduler/test_mem_read_grouping.py diff --git a/tests/api/test_search_hook_context.py b/tests/api/test_search_hook_context.py new file mode 100644 index 000000000..a5d39b3e8 --- /dev/null +++ b/tests/api/test_search_hook_context.py @@ -0,0 +1,178 @@ +import pytest + +from memos.api.handlers.base_handler import HandlerDependencies +from memos.api.handlers.search_handler import SearchHandler +from memos.api.product_models import APISearchRequest +from memos.plugins.hook_context import HookContext +from memos.plugins.hook_defs import H +from memos.plugins.hooks import register_hook + + +pytestmark = pytest.mark.usefixtures("clean_hooks") + + +def _empty_search_results() -> dict: + return { + "text_mem": [], + "act_mem": [], + "para_mem": [], + "pref_mem": [], + "pref_note": "", + "tool_mem": [], + "skill_mem": [], + } + + +class _CubeView: + def __init__(self, results: dict): + self.results = results + self.request = None + + def search_memories(self, request): + self.request = request + return self.results + + +def _search_handler() -> tuple[SearchHandler, _CubeView]: + handler = SearchHandler( + HandlerDependencies( + naive_mem_cube=object(), + mem_scheduler=object(), + searcher=object(), + deepsearch_agent=object(), + ) + ) + cube_view = _CubeView(_empty_search_results()) + handler._build_cube_view = lambda _search_req: cube_view + return handler, cube_view + + +def test_search_success_hooks_run_in_order_and_share_context(monkeypatch): + events = [] + result_hook_calls = [] + handler, cube_view = _search_handler() + search_req = APISearchRequest( + user_id="user", + query="original query", + session_id="session-1", + readable_cube_ids=["cube-1", "cube-2", "cube-1"], + ) + monkeypatch.setattr( + "memos.api.handlers.search_handler.get_current_trace_id", + lambda: "trace-1", + ) + + def replace_request(*, hook_context, request): + events.append((H.SEARCH_BEFORE, hook_context)) + return request.model_copy(update={"query": "hooked query"}) + + def record_results(hook_name): + def callback(*, hook_context, **kwargs): + events.append((hook_name, hook_context)) + result_hook_calls.append(kwargs) + + return callback + + def replace_response(*, hook_context, result, **_kwargs): + events.append((H.SEARCH_AFTER, hook_context)) + return result.model_copy(update={"message": "hooked response"}) + + result_hooks = [ + H.SEARCH_MEMORY_RESULTS, + H.SEARCH_RESULTS_AFTER_THRESHOLD, + H.SEARCH_RESULTS_AFTER_DEDUP, + H.SEARCH_RESULTS_AFTER_RERANK, + H.SEARCH_CONTEXT_RENDER, + ] + register_hook(H.SEARCH_BEFORE, replace_request) + for hook_name in result_hooks: + register_hook(hook_name, record_results(hook_name)) + register_hook(H.SEARCH_AFTER, replace_response) + + response = handler.handle_search_memories(search_req) + + assert [name for name, _context in events] == [ + H.SEARCH_BEFORE, + *result_hooks, + H.SEARCH_AFTER, + ] + contexts = [context for _name, context in events] + assert all(context is contexts[0] for context in contexts) + context = contexts[0] + assert isinstance(context, HookContext) + assert context.trace_id == "trace-1" + assert context.user_id == "user" + assert context.session_id == "session-1" + assert context.cube_ids == ("cube-1", "cube-2") + assert context.source == "api.search" + assert context.attributes == {"mode": "fast"} + assert context.operation_id + assert cube_view.request.query == "hooked query" + assert all(call["handler"] is handler for call in result_hook_calls) + assert all(call["search_req"] is cube_view.request for call in result_hook_calls) + assert response.message == "hooked response" + + +@pytest.mark.parametrize( + "hook_name", + [ + H.SEARCH_MEMORY_RESULTS, + H.SEARCH_RESULTS_AFTER_THRESHOLD, + H.SEARCH_RESULTS_AFTER_DEDUP, + H.SEARCH_RESULTS_AFTER_RERANK, + H.SEARCH_CONTEXT_RENDER, + ], +) +def test_search_result_hooks_replace_memories_in_response(hook_name): + handler, _cube_view = _search_handler() + memory = { + "id": "plugin-memory", + "memory": "Remember tea", + "metadata": {"relativity": 1.0, "memory_type": "LongTermMemory"}, + } + + def replace_memories(*, results, **_kwargs): + return {**results, "text_mem": [{"cube_id": "cube-1", "memories": [memory]}]} + + register_hook(hook_name, replace_memories) + + response = handler.handle_search_memories( + APISearchRequest(user_id="user", query="drink", dedup="no") + ) + + assert response.data["text_mem"][0]["memories"] == [memory] + + +def test_search_post_processing_failure_triggers_only_failure_hook(monkeypatch): + error = RuntimeError("post processing failed") + events = [] + handler, _cube_view = _search_handler() + search_req = APISearchRequest(user_id="user", query="query") + monkeypatch.setattr( + "memos.api.handlers.search_handler.get_current_trace_id", + lambda: "trace-1", + ) + + def fail_post_processing(_results, _relativity): + raise error + + def record_failure(**kwargs): + events.append((H.SEARCH_POST_PROCESS_FAILED, kwargs)) + + handler._apply_relativity_threshold = fail_post_processing + register_hook(H.SEARCH_POST_PROCESS_FAILED, record_failure) + register_hook(H.SEARCH_CONTEXT_RENDER, lambda **_kwargs: events.append(("render", {}))) + register_hook(H.SEARCH_AFTER, lambda **_kwargs: events.append(("after", {}))) + + with pytest.raises(RuntimeError, match="post processing failed") as exc_info: + handler.handle_search_memories(search_req) + + assert exc_info.value is error + assert [name for name, _kwargs in events] == [H.SEARCH_POST_PROCESS_FAILED] + failure = events[0][1] + assert failure["error"] is error + assert failure["handler"] is handler + assert failure["search_req"].query == "query" + context = failure["hook_context"] + assert context.trace_id == "trace-1" + assert context.user_id == "user" diff --git a/tests/api/test_search_pipeline_hooks.py b/tests/api/test_search_pipeline_hooks.py index 329a03350..bfdad25a0 100644 --- a/tests/api/test_search_pipeline_hooks.py +++ b/tests/api/test_search_pipeline_hooks.py @@ -1,20 +1,6 @@ -import pytest - -from memos.api.handlers.base_handler import HandlerDependencies from memos.api.handlers.formatters_handler import rerank_knowledge_mem -from memos.api.handlers.search_handler import SearchHandler from memos.api.product_models import APISearchRequest -from memos.multi_mem_cube.single_cube import SingleCubeView -from memos.plugins.hook_context import HookContext from memos.plugins.hook_defs import H, get_hook_spec -from memos.plugins.hooks import _hooks, register_hook - - -@pytest.fixture(autouse=True) -def _reset_registered_hooks(): - _hooks.clear() - yield - _hooks.clear() def _memory(memory_id: str, memory: str, memory_type: str = "LongTermMemory") -> dict: @@ -41,39 +27,6 @@ def _file_memory(memory_id: str, memory: str, source_content: str) -> dict: } -def _empty_search_results() -> dict: - return { - "text_mem": [], - "act_mem": [], - "para_mem": [], - "pref_mem": [], - "pref_note": "", - "tool_mem": [], - "skill_mem": [], - } - - -def _search_handler(results: dict | None = None) -> tuple[SearchHandler, SingleCubeView]: - handler = SearchHandler( - HandlerDependencies( - naive_mem_cube=object(), - mem_scheduler=object(), - searcher=object(), - deepsearch_agent=object(), - ) - ) - cube_view = SingleCubeView.__new__(SingleCubeView) - search_results = results if results is not None else _empty_search_results() - cube_view.search_memories = lambda _request: search_results - # Preserve the existing _build_cube_view(search_req) call contract. - handler._build_cube_view = lambda _search_req: cube_view - return handler, cube_view - - -def _raise(error: Exception): - raise error - - def test_search_request_passes_context_format_through_to_plugins(): req = APISearchRequest( user_id="user", @@ -85,136 +38,16 @@ def test_search_request_passes_context_format_through_to_plugins(): def test_search_pipeline_hook_specs_are_registered(): - for hook_name in (H.SEARCH_RESULTS_AFTER_RERANK, H.SEARCH_CONTEXT_RENDER): - spec = get_hook_spec(hook_name) - assert spec is not None - assert spec.pipe_key == "results" - assert spec.params == ["hook_context", "handler", "search_req", "results"] - - -@pytest.mark.parametrize( - ("hook_name", "params", "pipe_key"), - [ - (H.SEARCH_BEFORE, ["hook_context", "request"], "request"), - (H.SEARCH_AFTER, ["hook_context", "request", "result"], "result"), - ( - H.SEARCH_MEMORY_RESULTS, - ["hook_context", "handler", "search_req", "results"], - "results", - ), - ( - H.SEARCH_RESULTS_AFTER_THRESHOLD, - ["hook_context", "handler", "search_req", "results"], - "results", - ), - ( - H.SEARCH_RESULTS_AFTER_DEDUP, - ["hook_context", "handler", "search_req", "results"], - "results", - ), - ( - H.SEARCH_POST_PROCESS_FAILED, - ["hook_context", "handler", "search_req", "error"], - None, - ), - ], -) -def test_search_hook_specs_match_trigger_contracts(hook_name, params, pipe_key): - spec = get_hook_spec(hook_name) - - assert spec is not None - assert spec.params == params - assert spec.pipe_key == pipe_key - - -def test_search_success_hooks_run_in_order_and_share_one_context(monkeypatch): - events: list[tuple[str, dict]] = [] - handler, cube_view = _search_handler() - search_req = APISearchRequest( - user_id="user", - query="query", - session_id="session-1", - readable_cube_ids=["cube-1", "cube-2", "cube-1"], - ) - monkeypatch.setattr( - "memos.api.handlers.search_handler.get_current_trace_id", - lambda: "trace-1", - ) - - def record(hook_name): - def callback(**kwargs): - events.append((hook_name, kwargs)) - - return callback - - ordered_hooks = [ - H.SEARCH_BEFORE, - H.SEARCH_MEMORY_RESULTS, - H.SEARCH_RESULTS_AFTER_THRESHOLD, - H.SEARCH_RESULTS_AFTER_DEDUP, - H.SEARCH_RESULTS_AFTER_RERANK, - H.SEARCH_CONTEXT_RENDER, - H.SEARCH_AFTER, - ] - for hook_name in ordered_hooks: - register_hook(hook_name, record(hook_name)) - - handler.handle_search_memories(search_req) - - assert [name for name, _kwargs in events] == ordered_hooks - contexts = [kwargs["hook_context"] for _name, kwargs in events] - assert all(context is contexts[0] for context in contexts) - context = contexts[0] - assert isinstance(context, HookContext) - assert context.trace_id == "trace-1" - assert context.user_id == "user" - assert context.session_id == "session-1" - assert context.cube_ids == ("cube-1", "cube-2") - assert context.source == "api.search" - assert context.attributes == {"mode": "fast"} - assert context.operation_id is not None - assert not hasattr(cube_view, "search_hook_context") - + after_rerank = get_hook_spec(H.SEARCH_RESULTS_AFTER_RERANK) + render = get_hook_spec(H.SEARCH_CONTEXT_RENDER) -def test_search_context_render_hook_can_replace_results(): - handler, _cube_view = _search_handler() - search_req = APISearchRequest(user_id="user", query="query") - - def render(*, results, **_kwargs): - return {**results, "rendered_by_plugin": True} - - register_hook(H.SEARCH_CONTEXT_RENDER, render) - - response = handler.handle_search_memories(search_req) - - assert response.data["rendered_by_plugin"] is True - - -def test_search_post_processing_failure_triggers_only_post_process_hook(monkeypatch): - error = RuntimeError("post processing failed") - post_process_failures = [] - handler, _cube_view = _search_handler() - handler._apply_relativity_threshold = lambda _results, _relativity: _raise(error) - search_req = APISearchRequest(user_id="user", query="query") - monkeypatch.setattr( - "memos.api.handlers.search_handler.get_current_trace_id", - lambda: "trace-1", - ) - - register_hook( - H.SEARCH_POST_PROCESS_FAILED, - lambda **kwargs: post_process_failures.append(kwargs), - ) - with pytest.raises(RuntimeError, match="post processing failed"): - handler.handle_search_memories(search_req) + assert after_rerank is not None + assert after_rerank.pipe_key == "results" + assert after_rerank.params == ["hook_context", "handler", "search_req", "results"] - assert len(post_process_failures) == 1 - assert post_process_failures[0]["error"] is error - context = post_process_failures[0]["hook_context"] - assert isinstance(context, HookContext) - assert context.trace_id == "trace-1" - assert context.user_id == "user" - assert context.operation_id is not None + assert render is not None + assert render.pipe_key == "results" + assert render.params == ["hook_context", "handler", "search_req", "results"] def test_rerank_knowledge_mem_preserves_conversation_sources_by_default(): diff --git a/tests/conftest.py b/tests/conftest.py new file mode 100644 index 000000000..509111b2b --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,11 @@ +import pytest + + +@pytest.fixture +def clean_hooks(): + """Keep Hook registrations isolated for tests that opt into this fixture.""" + from memos.plugins.hooks import _hooks + + _hooks.clear() + yield + _hooks.clear() diff --git a/tests/mem_reader/test_fine_transfer_order.py b/tests/mem_reader/test_fine_transfer_order.py new file mode 100644 index 000000000..2beacfbe2 --- /dev/null +++ b/tests/mem_reader/test_fine_transfer_order.py @@ -0,0 +1,44 @@ +"""Fine-transfer groups retain their input index when tasks finish out of order.""" + +from types import SimpleNamespace + +import pytest + +from memos.mem_reader.simple_struct import SimpleStructMemReader + + +@pytest.mark.parametrize("failed_result", [None, ValueError("synthetic failure")]) +def test_fine_transfer_keeps_failed_slots_and_input_order(monkeypatch, failed_result): + monkeypatch.setattr( + "memos.mem_reader.simple_struct.concurrent.futures.as_completed", + lambda futures: iter(reversed(list(futures))), + ) + + def process(source, custom_tags, **kwargs): + if source == "missing": + if isinstance(failed_result, Exception): + raise failed_result + return failed_result + return [source + "-enhanced"] + + reader = SimpleNamespace(_process_transfer_chat_data=process) + result = SimpleStructMemReader.fine_transfer_simple_mem( + reader, ["first", "missing", "last"], "chat" + ) + assert result == [["first-enhanced"], [], ["last-enhanced"]] + + +def test_multimodal_fine_transfer_returns_one_group_for_the_batch(): + from memos.mem_reader.multi_modal_struct import MultiModalStructMemReader + + sources = ["first", "last"] + enhanced = ["combined-enhanced"] + + def process(memories, custom_tags, **kwargs): + assert memories is sources + return enhanced + + reader = SimpleNamespace(_process_transfer_multi_modal_data=process) + result = MultiModalStructMemReader.fine_transfer_simple_mem(reader, sources, "chat") + assert result == [enhanced] + assert result[0] is enhanced diff --git a/tests/mem_reader/test_hook_pipeline.py b/tests/mem_reader/test_hook_pipeline.py index 986fcffda..d912f0ab2 100644 --- a/tests/mem_reader/test_hook_pipeline.py +++ b/tests/mem_reader/test_hook_pipeline.py @@ -1,60 +1,37 @@ -"""MemReader success/failure Hook contracts and result piping.""" - -from __future__ import annotations +"""MemReader Hook contracts at the extraction boundary.""" from types import MethodType -from uuid import UUID import pytest from memos.mem_reader.simple_struct import SimpleStructMemReader -from memos.plugins.hook_context import HookContext from memos.plugins.hook_defs import H -from memos.plugins.hooks import _hooks, register_hook +from memos.plugins.hooks import register_hook -@pytest.fixture(autouse=True) -def _reset_registered_hooks(): - _hooks.clear() - yield - _hooks.clear() +pytestmark = pytest.mark.usefixtures("clean_hooks") -def test_extract_after_hook_can_replace_reader_result(): +def test_extract_after_hook_receives_operation_and_can_replace_result(monkeypatch): reader = object.__new__(SimpleStructMemReader) original_result = [["original"]] plugin_result = [["plugin"]] - - def fake_read_memory(self, *args, **kwargs): - return original_result - - reader._read_memory = MethodType(fake_read_memory, reader) - register_hook(H.MEM_READER_EXTRACT_AFTER, lambda **_kwargs: plugin_result) - - result = reader.get_memory( - [{"role": "user", "content": "remember this"}], - type="chat", - info={"user_id": "alice", "session_id": "session-1"}, - ) - - assert result == plugin_result - - -def test_extract_after_hook_receives_context_and_business_values(monkeypatch): - reader = object.__new__(SimpleStructMemReader) - result = [["memory"]] scene_data = [{"role": "user", "content": "remember this"}] info = {"user_id": "alice", "session_id": "session-1"} captured = {} - def fake_read_memory(self, *args, **kwargs): - return result + def fake_read_memory(self, *_args, **_kwargs): + return original_result + + def replace_result(**kwargs): + captured.update(kwargs) + return plugin_result reader._read_memory = MethodType(fake_read_memory, reader) monkeypatch.setattr("memos.mem_reader.simple_struct.get_current_trace_id", lambda: "trace-1") - register_hook(H.MEM_READER_EXTRACT_AFTER, lambda **kwargs: captured.update(kwargs)) + register_hook(H.MEM_READER_EXTRACT_AFTER, replace_result) - actual = reader.get_memory( + result = reader.get_memory( scene_data, type="chat", info=info, @@ -63,17 +40,13 @@ def fake_read_memory(self, *args, **kwargs): chat_history=[], ) - assert actual is result context = captured.pop("hook_context") - assert isinstance(context, HookContext) + assert result == plugin_result assert context.trace_id == "trace-1" assert context.user_id == "alice" assert context.session_id == "session-1" assert context.cube_ids == ("cube-1",) assert context.source == "mem_reader.extract" - assert context.attributes == {"mode": "fine", "type": "chat"} - assert context.operation_id is not None - assert UUID(context.operation_id).hex == context.operation_id assert captured == { "mem_reader": reader, "scene_data": scene_data, @@ -82,40 +55,39 @@ def fake_read_memory(self, *args, **kwargs): "mode": "fine", "user_name": "cube-1", "kwargs": {"chat_history": []}, - "result": result, + "result": original_result, } -def test_extract_failure_hook_preserves_original_error_and_skips_after(monkeypatch): +def test_extract_failure_hook_reports_and_preserves_original_error(monkeypatch): reader = object.__new__(SimpleStructMemReader) error = ValueError("reader failed") - failed_events = [] - after_events = [] + events = [] - def fake_read_memory(self, *args, **kwargs): + def fake_read_memory(self, *_args, **_kwargs): raise error - def on_failed(**kwargs): - failed_events.append(kwargs) - raise RuntimeError("plugin failed") + def record(stage): + def callback(**kwargs): + events.append((stage, kwargs)) + + return callback reader._read_memory = MethodType(fake_read_memory, reader) monkeypatch.setattr("memos.mem_reader.simple_struct.get_current_trace_id", lambda: "trace-1") - register_hook(H.MEM_READER_EXTRACT_FAILED, on_failed) - register_hook(H.MEM_READER_EXTRACT_AFTER, lambda **kwargs: after_events.append(kwargs)) + register_hook(H.MEM_READER_EXTRACT_FAILED, record("failed")) + register_hook(H.MEM_READER_EXTRACT_AFTER, record("after")) with pytest.raises(ValueError, match="reader failed") as exc_info: reader.get_memory( [{"role": "user", "content": "remember this"}], type="chat", info={"user_id": "alice", "session_id": "session-1"}, - mode="fast", user_name="cube-1", ) assert exc_info.value is error - assert len(failed_events) == 1 - assert failed_events[0]["error"] is error - assert failed_events[0]["hook_context"].source == "mem_reader.extract" - assert failed_events[0]["hook_context"].operation_id is not None - assert after_events == [] + assert [stage for stage, _kwargs in events] == ["failed"] + failure = events[0][1] + assert failure["error"] is error + assert failure["hook_context"].source == "mem_reader.extract" diff --git a/tests/mem_scheduler/test_mem_read_grouping.py b/tests/mem_scheduler/test_mem_read_grouping.py new file mode 100644 index 000000000..c6d0e003d --- /dev/null +++ b/tests/mem_scheduler/test_mem_read_grouping.py @@ -0,0 +1,132 @@ +"""Fine-transfer Hooks describe the actual Reader result grouping.""" + +from types import SimpleNamespace +from unittest.mock import Mock + +import pytest + +from memos.mem_reader.multi_modal_struct import MultiModalStructMemReader +from memos.mem_reader.simple_struct import SimpleStructMemReader +from memos.mem_reader.strategy_struct import StrategyStructMemReader +from memos.mem_scheduler.task_schedule_modules.handlers.mem_read_handler import ( + MemReadMessageHandler, +) +from memos.memories.textual.item import TextualMemoryItem, TreeNodeTextualMemoryMetadata +from memos.plugins.hook_defs import H +from memos.plugins.hooks import register_hook + + +class CustomTransferReader(SimpleStructMemReader): + def fine_transfer_simple_mem(self, *args, **kwargs): + return self.transfer_result + + +@pytest.fixture +def captured_operations(clean_hooks): + captured = [] + register_hook(H.SCHEDULER_MEMORY_OPERATION_AFTER, lambda **kwargs: captured.append(kwargs)) + return captured + + +def memory(text): + return TextualMemoryItem( + memory=text, + metadata=TreeNodeTextualMemoryMetadata(memory_type="LongTermMemory"), + ) + + +@pytest.mark.parametrize( + "reader_class,expected_grouping", + [ + (SimpleStructMemReader, "per_input"), + (StrategyStructMemReader, "per_input"), + (MultiModalStructMemReader, "batch"), + (CustomTransferReader, "unknown"), + ], +) +def test_scheduler_hook_reports_reader_grouping_without_changing_results( + monkeypatch, captured_operations, reader_class, expected_grouping +): + sources = [memory("first"), memory("missing"), memory("last")] + enhanced = [memory("first enhanced"), memory("last enhanced")] + reader = object.__new__(reader_class) + reader.save_rawfile = False + reader.graph_db = None + reader.memory_version_switch = "off" + reader.transfer_result = [enhanced] + + def process(source, custom_tags, **kwargs): + if source is sources[1]: + return None + return [enhanced[0] if source is sources[0] else enhanced[1]] + + reader._process_transfer_chat_data = process + reader._process_transfer_multi_modal_data = lambda *args, **kwargs: enhanced + monkeypatch.setattr( + "memos.mem_reader.simple_struct.concurrent.futures.as_completed", + lambda futures: iter(reversed(list(futures))), + ) + text_mem = Mock() + text_mem.get.side_effect = sources + text_mem.add.return_value = [item.id for item in enhanced] + text_mem.memory_manager.reorganizer.is_reorganize = False + handler = MemReadMessageHandler( + SimpleNamespace(get_mem_reader=lambda: reader, services=Mock(), get_mem_cube=Mock()) + ) + handler._process_memories_with_reader( + mem_ids=[item.id for item in sources], + user_id="test-user", + mem_cube_id="test-cube", + text_mem=text_mem, + user_name="test-cube", + operation_context={ + "trace_id": "test-trace", + "user_id": "test-user", + "cube_id": "test-cube", + }, + ) + + transfer = next( + event + for event in captured_operations + if event["hook_context"].source == "scheduler.mem_read.fine_transfer_simple_mem" + ) + assert transfer["operation_input"]["result_grouping"] == expected_grouping + assert transfer["operation_input"]["memories"] == sources + if reader_class in (SimpleStructMemReader, StrategyStructMemReader): + assert transfer["result"] == [[enhanced[0]], [], [enhanced[1]]] + else: + assert transfer["result"] == [enhanced] + text_mem.add.assert_called_once_with(enhanced, user_name="test-cube") + text_mem.delete.assert_called_once_with([item.id for item in sources], user_name="test-cube") + text_mem.memory_manager.remove_and_refresh_memory.assert_called_once_with(user_name="test-cube") + + +def test_scheduler_failed_hook_keeps_grouping_and_original_error(captured_operations): + error = ValueError("synthetic transfer failure") + reader = CustomTransferReader.__new__(CustomTransferReader) + + def fail(*args, **kwargs): + raise error + + reader.fine_transfer_simple_mem = fail + failed = [] + register_hook(H.SCHEDULER_MEMORY_OPERATION_FAILED, lambda **kwargs: failed.append(kwargs)) + text_mem = Mock() + text_mem.get.return_value = memory("source") + handler = MemReadMessageHandler(SimpleNamespace(get_mem_reader=lambda: reader)) + handler._process_memories_with_reader( + mem_ids=[text_mem.get.return_value.id], + user_id="test-user", + mem_cube_id="test-cube", + text_mem=text_mem, + user_name="test-cube", + ) + assert len(failed) == 1 + assert failed[0]["error"] is error + assert failed[0]["operation_input"]["result_grouping"] == "unknown" + assert all( + event["hook_context"].source != "scheduler.mem_read.fine_transfer_simple_mem" + for event in captured_operations + ) + text_mem.add.assert_not_called() diff --git a/tests/mem_scheduler/test_operation_observer.py b/tests/mem_scheduler/test_operation_observer.py index b8513e5d5..6b4beaa5e 100644 --- a/tests/mem_scheduler/test_operation_observer.py +++ b/tests/mem_scheduler/test_operation_observer.py @@ -1,33 +1,126 @@ -"""Scheduler operation Hook contracts at existing exception boundaries.""" +"""Scheduler Hook contracts and their MemRead integration points.""" -from __future__ import annotations - -from uuid import UUID +from unittest.mock import MagicMock import pytest +from memos.mem_scheduler.schemas.message_schemas import ScheduleMessageItem +from memos.mem_scheduler.task_schedule_modules.handlers.mem_read_handler import ( + MemReadMessageHandler, +) from memos.mem_scheduler.task_schedule_modules.operation_observer import ( SchedulerOperationObserver, ) -from memos.plugins.hook_context import HookContext +from memos.memories.textual.item import TextualMemoryItem, TreeNodeTextualMemoryMetadata from memos.plugins.hook_defs import H -from memos.plugins.hooks import _hooks, register_hook +from memos.plugins.hooks import register_hook + + +pytestmark = pytest.mark.usefixtures("clean_hooks") + +RAW_MEMORY_ID = "00000000-0000-0000-0000-000000000001" +ENHANCED_MEMORY_ID = "00000000-0000-0000-0000-000000000002" +SCHEDULER_ITEM_ID = "00000000-0000-0000-0000-000000000003" +OPERATION_SOURCE = { + "fine": "fine_transfer_simple_mem", + "add": "add_enhanced_memories", + "archive": "archive_merged_memories", + "delete": "remove_memories", + "soft_delete": "remove_memories", +} + + +def _memory(memory_id, memory_type, *, merged_from=None): + return TextualMemoryItem( + id=memory_id, + memory=f"{memory_type} content", + metadata=TreeNodeTextualMemoryMetadata( + user_id="alice", + session_id="session-1", + memory_type=memory_type, + sources=[], + info={"merged_from": merged_from} if merged_from else {}, + ), + ) -@pytest.fixture(autouse=True) -def _reset_registered_hooks(): - _hooks.clear() - yield - _hooks.clear() +def _mem_read_dependencies(memory_version_switch): + raw_memory = _memory(RAW_MEMORY_ID, "WorkingMemory") + enhanced_memory = _memory( + ENHANCED_MEMORY_ID, + "LongTermMemory", + merged_from=RAW_MEMORY_ID, + ) + reader = MagicMock() + reader.fine_transfer_simple_mem.return_value = [[enhanced_memory]] + reader.save_rawfile = False + reader.memory_version_switch = memory_version_switch + + text_memory = MagicMock() + text_memory.get.return_value = raw_memory + text_memory.add.return_value = [ENHANCED_MEMORY_ID] + text_memory.memory_manager.reorganizer.is_reorganize = False + + scheduler_context = MagicMock() + scheduler_context.get_mem_reader.return_value = reader + scheduler_context.services.create_event_log.return_value = MagicMock() + + message = ScheduleMessageItem( + item_id=SCHEDULER_ITEM_ID, + user_id="alice", + trace_id="trace-1", + mem_cube_id="cube-1", + session_id="session-1", + label="mem_read", + content=f'["{RAW_MEMORY_ID}"]', + user_name="cube-1", + task_id="task-1", + ) + return MemReadMessageHandler(scheduler_context), reader, text_memory, message -def test_scheduler_observer_emits_context_and_business_values_as_hook_kwargs(): - captured = {} - register_hook( - H.SCHEDULER_MEMORY_OPERATION_AFTER, - lambda **kwargs: captured.update(kwargs), + +def test_mem_read_handler_uses_replaced_transfer_results_and_stored_ids(monkeypatch): + handler, _reader, text_memory, message = _mem_read_dependencies("off") + replacement = _memory("00000000-0000-0000-0000-000000000004", "LongTermMemory") + stored_id = "00000000-0000-0000-0000-000000000005" + text_memory.memory_manager.reorganizer.is_reorganize = True + monkeypatch.setattr( + "memos.mem_scheduler.task_schedule_modules.handlers.mem_read_handler.is_playground_api", + lambda: False, ) + def replace_result(*, operation, result, **_kwargs): + if operation == "fine": + return [[replacement]] + if operation == "add": + return [stored_id] + return result + + register_hook(H.SCHEDULER_MEMORY_OPERATION_AFTER, replace_result) + handler._process_memories_with_reader( + mem_ids=[RAW_MEMORY_ID], + user_id="alice", + mem_cube_id="cube-1", + text_mem=text_memory, + user_name="cube-1", + operation_context=message, + ) + + text_memory.add.assert_called_once_with([replacement], user_name="cube-1") + submitted = handler.scheduler_context.services.submit_messages.call_args.args[0] + assert submitted[0].content == f'["{stored_id}"]' + + +def test_scheduler_observer_pipes_result_and_exposes_operation_contract(): + captured = {} + + def replace_result(**kwargs): + captured.update(kwargs) + return ["plugin-result"] + + register_hook(H.SCHEDULER_MEMORY_OPERATION_AFTER, replace_result) + with SchedulerOperationObserver( source="scheduler.mem_read.add_enhanced_memories", operation="add", @@ -37,42 +130,30 @@ def test_scheduler_observer_emits_context_and_business_values_as_hook_kwargs(): ) as observer: observer.result(["stored-1"]) - assert isinstance(captured["hook_context"], HookContext) - assert captured["hook_context"].trace_id == "trace-1" + assert observer.value == ["plugin-result"] assert captured["operation"] == "add" assert captured["target"] == "textual_memory" assert captured["operation_input"] == {"memory_ids": ["memory-1"]} assert captured["result"] == ["stored-1"] - assert "event" not in captured + assert captured["hook_context"].source == "scheduler.mem_read.add_enhanced_memories" -def test_scheduler_observer_failure_hook_preserves_original_error_and_skips_after(): +def test_scheduler_observer_reports_failure_and_preserves_error(): error = ValueError("scheduler operation failed") - failed_events = [] - after_events = [] - - def on_failed(**kwargs): - failed_events.append(kwargs) - raise RuntimeError("plugin failed") - - register_hook(H.SCHEDULER_MEMORY_OPERATION_FAILED, on_failed) + events = [] + register_hook( + H.SCHEDULER_MEMORY_OPERATION_FAILED, + lambda **kwargs: events.append(("failed", kwargs)), + ) register_hook( H.SCHEDULER_MEMORY_OPERATION_AFTER, - lambda **kwargs: after_events.append(kwargs), + lambda **kwargs: events.append(("after", kwargs)), ) observer = SchedulerOperationObserver( source="scheduler.mem_read.fine_transfer_simple_mem", operation="fine", target="textual_memory", - operation_context={ - "trace_id": "trace-1", - "user_id": "alice", - "session_id": "session-1", - "task_id": "task-1", - "mem_cube_id": "cube-1", - "item_id": "item-1", - "label": "mem_read", - }, + operation_context={"trace_id": "trace-1", "mem_cube_id": "cube-1"}, operation_input={"memory_ids": ["memory-1"]}, capture_failure=True, ) @@ -81,70 +162,87 @@ def on_failed(**kwargs): raise error assert exc_info.value is error - assert len(failed_events) == 1 - event = failed_events[0] - context = event["hook_context"] - assert isinstance(context, HookContext) - assert context.trace_id == "trace-1" - assert context.user_id == "alice" - assert context.session_id == "session-1" - assert context.task_id == "task-1" - assert context.cube_ids == ("cube-1",) - assert context.source == "scheduler.mem_read.fine_transfer_simple_mem" - assert context.attributes == {"scheduler_item_id": "item-1", "label": "mem_read"} - assert context.operation_id is not None - assert UUID(context.operation_id).hex == context.operation_id - assert event["operation"] == "fine" - assert event["target"] == "textual_memory" - assert event["operation_input"] == {"memory_ids": ["memory-1"]} - assert event["error"] is error - assert after_events == [] - assert observer.value is None - - -def test_scheduler_observer_emits_explicit_failure_only_once(): - failed_events = [] - after_events = [] - error = ValueError("scheduler operation failed") - - register_hook( - H.SCHEDULER_MEMORY_OPERATION_FAILED, - lambda **kwargs: failed_events.append(kwargs), - ) - register_hook( - H.SCHEDULER_MEMORY_OPERATION_AFTER, - lambda **kwargs: after_events.append(kwargs), + assert [stage for stage, _kwargs in events] == ["failed"] + failure = events[0][1] + assert failure["error"] is error + assert failure["hook_context"].cube_ids == ("cube-1",) + + +@pytest.mark.parametrize( + ("memory_version_switch", "expected_operations"), + [ + ("off", ["fine", "add", "archive", "delete"]), + ("on", ["fine", "add", "soft_delete"]), + ], +) +def test_mem_read_handler_exposes_each_memory_operation( + memory_version_switch, + expected_operations, + monkeypatch, +): + handler, reader, text_memory, message = _mem_read_dependencies(memory_version_switch) + events = [] + monkeypatch.setattr( + "memos.mem_scheduler.task_schedule_modules.handlers.mem_read_handler.is_playground_api", + lambda: False, ) - with SchedulerOperationObserver( - source="scheduler.mem_read.remove_memories", - operation="delete", - target="textual_memory", - operation_context={"trace_id": "trace-1"}, - operation_input={"memory_ids": ["memory-1"]}, - ) as observer: - observer.failed(error) - observer.failed(error) - observer.result(None) - - assert len(failed_events) == 1 - assert failed_events[0]["error"] is error - assert after_events == [] + def record_operation(**kwargs): + events.append(kwargs) + return kwargs["result"] + register_hook(H.SCHEDULER_MEMORY_OPERATION_AFTER, record_operation) -def test_scheduler_observer_exposes_piped_result_after_successful_exit(): - register_hook( - H.SCHEDULER_MEMORY_OPERATION_AFTER, - lambda **_kwargs: ["plugin-result"], + handler._process_memories_with_reader( + mem_ids=[RAW_MEMORY_ID], + user_id="alice", + mem_cube_id="cube-1", + text_mem=text_memory, + user_name="cube-1", + task_id="task-1", + operation_context=message, ) - with SchedulerOperationObserver( - source="scheduler.mem_read.add_enhanced_memories", - operation="add", - target="textual_memory", - operation_context={"trace_id": "trace-1"}, - operation_input={}, - ) as observer: - observer.result(["original-result"]) - - assert observer.value == ["plugin-result"] + assert [event["operation"] for event in events] == expected_operations + assert [event["hook_context"].source for event in events] == [ + f"scheduler.mem_read.{OPERATION_SOURCE[operation]}" for operation in expected_operations + ] + for event in events: + context = event["hook_context"] + assert event["target"] == "textual_memory" + assert context.trace_id == "trace-1" + assert context.user_id == "alice" + assert context.session_id == "session-1" + assert context.task_id == "task-1" + assert context.cube_ids == ("cube-1",) + assert context.attributes["scheduler_item_id"] == SCHEDULER_ITEM_ID + assert context.attributes["label"] == "mem_read" + + inputs = {event["operation"]: event["operation_input"] for event in events} + assert inputs["fine"]["memories"][0].id == RAW_MEMORY_ID + assert inputs["fine"]["type"] == "chat" + assert inputs["add"]["memories"][0].id == ENHANCED_MEMORY_ID + assert inputs["add"]["user_name"] == "cube-1" + + if memory_version_switch == "off": + assert inputs["archive"] == {"memory_ids": [RAW_MEMORY_ID]} + assert inputs["delete"] == {"memory_ids": [RAW_MEMORY_ID]} + reader.graph_db.update_node.assert_called_once_with( + RAW_MEMORY_ID, + {"status": "archived"}, + user_name="cube-1", + ) + text_memory.delete.assert_called_once_with([RAW_MEMORY_ID], user_name="cube-1") + text_memory.soft_delete.assert_not_called() + else: + assert inputs["soft_delete"] == { + "memory_ids": [RAW_MEMORY_ID], + "preserved_memory_ids": [ENHANCED_MEMORY_ID], + } + reader.graph_db.update_node.assert_not_called() + text_memory.delete.assert_not_called() + text_memory.soft_delete.assert_called_once_with( + [RAW_MEMORY_ID], + "cube-1", + [ENHANCED_MEMORY_ID], + ) diff --git a/tests/multi_mem_cube/test_single_cube_hooks.py b/tests/multi_mem_cube/test_single_cube_hooks.py index b384157ba..f639bec8e 100644 --- a/tests/multi_mem_cube/test_single_cube_hooks.py +++ b/tests/multi_mem_cube/test_single_cube_hooks.py @@ -3,23 +3,17 @@ from __future__ import annotations import logging -import uuid from importlib import import_module from unittest.mock import MagicMock import pytest -from memos.plugins.hook_context import HookContext from memos.plugins.hook_defs import H -from memos.plugins.hooks import _hooks, register_hook +from memos.plugins.hooks import register_hook -@pytest.fixture(autouse=True) -def _reset_registered_hooks(): - _hooks.clear() - yield - _hooks.clear() +pytestmark = pytest.mark.usefixtures("clean_hooks") def _make_add_request(**overrides): @@ -48,7 +42,7 @@ def single_cube_view(): from memos.multi_mem_cube.single_cube import SingleCubeView memory = TextualMemoryItem( - id=str(uuid.uuid4()), + id="00000000-0000-0000-0000-000000000001", memory="hello world", metadata=TreeNodeTextualMemoryMetadata( user_id="u1", @@ -79,15 +73,38 @@ def single_cube_view(): return view, memory -def test_text_memory_after_hook_can_replace_memory_ids(single_cube_view): - view, _memory = single_cube_view - register_hook(H.TEXT_MEMORY_ADD_AFTER, lambda **_kwargs: ["plugin-memory-id"]) +def test_text_memory_after_hook_observes_write_and_replaces_memory_ids(single_cube_view): + view, memory = single_cube_view + captured = {} + + def replace_memory_ids(**kwargs): + captured.update(kwargs) + return ["plugin-memory-id"] - results = view.add_memories(_make_add_request(async_mode="async")) + register_hook(H.TEXT_MEMORY_ADD_AFTER, replace_memory_ids) + + results = view.add_memories( + _make_add_request( + async_mode="async", + session_id="session-1", + task_id="task-1", + ) + ) assert results[0]["memory_id"] == "plugin-memory-id" + context = captured.pop("hook_context") + assert context.user_id == "test_user" + assert context.session_id == "session-1" + assert context.task_id == "task-1" + assert context.cube_ids == ("cube_test",) + assert context.source == "cube_view.text_mem.add" + assert captured == { + "text_memory": view.naive_mem_cube.text_mem, + "memories": [memory], + "kwargs": {"user_name": "cube_test"}, + "result": [memory.id], + } submitted_message = view.mem_scheduler.submit_messages.call_args.kwargs["messages"][0] - assert submitted_message.mem_cube_id == "cube_test" assert submitted_message.content == '["plugin-memory-id"]' @@ -97,20 +114,21 @@ def test_text_memory_failure_hook_preserves_original_error_and_skips_after( ): view, memory = single_cube_view error = ValueError("text memory add failed") - failed_calls = [] - after_calls = [] + events = [] view.naive_mem_cube.text_mem.add.side_effect = error monkeypatch.setattr( "memos.multi_mem_cube.single_cube.get_current_trace_id", lambda: "trace-1", ) - def on_failed(**kwargs): - failed_calls.append(kwargs) - raise RuntimeError("plugin failed") + def record(stage): + def callback(**kwargs): + events.append((stage, kwargs)) - register_hook(H.TEXT_MEMORY_ADD_FAILED, on_failed) - register_hook(H.TEXT_MEMORY_ADD_AFTER, lambda **kwargs: after_calls.append(kwargs)) + return callback + + register_hook(H.TEXT_MEMORY_ADD_FAILED, record("failed")) + register_hook(H.TEXT_MEMORY_ADD_AFTER, record("after")) with pytest.raises(ValueError, match="text memory add failed") as exc_info: view.add_memories( @@ -122,19 +140,13 @@ def on_failed(**kwargs): ) assert exc_info.value is error - assert after_calls == [] - assert len(failed_calls) == 1 - call = failed_calls[0] + assert [stage for stage, _kwargs in events] == ["failed"] + call = events[0][1] context = call["hook_context"] - assert isinstance(context, HookContext) assert context.trace_id == "trace-1" assert context.user_id == "test_user" - assert context.session_id == "session-1" - assert context.task_id == "task-1" assert context.cube_ids == ("cube_test",) assert context.source == "cube_view.text_mem.add" - assert context.attributes == {"sync_mode": "async", "extract_mode": "fast"} - assert context.operation_id is not None assert call["text_memory"] is view.naive_mem_cube.text_mem assert call["memories"] == [memory] assert call["kwargs"] == {"user_name": "cube_test"} diff --git a/tests/plugins/test_hook_context.py b/tests/plugins/test_hook_context.py index c1fdad0bd..ad06e2f98 100644 --- a/tests/plugins/test_hook_context.py +++ b/tests/plugins/test_hook_context.py @@ -1,41 +1,44 @@ -"""HookContext values, callback compatibility, and @hookable propagation.""" - -from __future__ import annotations +"""Public HookContext contracts and context-aware callback behavior.""" import asyncio -from collections.abc import Mapping -from typing import Any, get_type_hints -from uuid import UUID - import pytest -from memos.plugins.hook_context import HookContext, build_hook_context +from memos.plugins.hook_context import build_hook_context from memos.plugins.hook_defs import H, define_hook, get_hook_spec -from memos.plugins.hooks import ( - _hooks, - hookable, - register_hook, - trigger_hook, - trigger_single_hook, +from memos.plugins.hooks import hookable, register_hook, trigger_hook, trigger_single_hook + + +pytestmark = pytest.mark.usefixtures("clean_hooks") + + +@pytest.mark.parametrize( + ("hook_name", "pipe_key"), + [ + (H.SEARCH_BEFORE, "request"), + (H.SEARCH_AFTER, "result"), + (H.SEARCH_MEMORY_RESULTS, "results"), + (H.SEARCH_RESULTS_AFTER_THRESHOLD, "results"), + (H.SEARCH_RESULTS_AFTER_DEDUP, "results"), + (H.SEARCH_RESULTS_AFTER_RERANK, "results"), + (H.SEARCH_CONTEXT_RENDER, "results"), + (H.SEARCH_POST_PROCESS_FAILED, None), + (H.TEXT_MEMORY_ADD_AFTER, "result"), + (H.TEXT_MEMORY_ADD_FAILED, None), + (H.SCHEDULER_MEMORY_OPERATION_AFTER, "result"), + (H.SCHEDULER_MEMORY_OPERATION_FAILED, None), + (H.MEM_READER_EXTRACT_AFTER, "result"), + (H.MEM_READER_EXTRACT_FAILED, None), + ], ) +def test_integration_hook_specs_are_registered(hook_name, pipe_key): + spec = get_hook_spec(hook_name) + assert spec is not None + assert spec.pipe_key == pipe_key -@pytest.fixture(autouse=True) -def _reset_registered_hooks(): - _hooks.clear() - yield - _hooks.clear() - - -def test_hook_context_type_hints_are_runtime_resolvable(): - hints = get_type_hints(HookContext) - assert hints["attributes"] == Mapping[str, Any] - assert hints["operation_id"] == str | None - - -def test_build_hook_context_populates_correlation_metadata(): +def test_build_hook_context_copies_correlation_metadata(): cube_ids = ["cube-1", "cube-2"] attributes = {"mode": "fine"} @@ -46,95 +49,26 @@ def test_build_hook_context_populates_correlation_metadata(): session_id="session-1", task_id="task-1", cube_ids=cube_ids, - operation_id="operation-1", attributes=attributes, ) cube_ids.append("cube-3") - attributes["mode"] = "mutated" + attributes["mode"] = "fast" - assert context == HookContext( - trace_id="trace-1", - user_id="user-1", - session_id="session-1", - task_id="task-1", - cube_ids=("cube-1", "cube-2"), - operation_id="operation-1", - source="mem_reader.extract", - attributes={"mode": "fine"}, - ) + assert context.trace_id == "trace-1" + assert context.user_id == "user-1" + assert context.session_id == "session-1" + assert context.task_id == "task-1" + assert context.cube_ids == ("cube-1", "cube-2") + assert context.source == "mem_reader.extract" + assert context.attributes == {"mode": "fine"} + assert context.operation_id -def test_build_hook_context_generates_unique_operation_ids(): - first = build_hook_context(source="text_memory.add") - second = build_hook_context(source="text_memory.add") - - assert first.operation_id is not None - assert second.operation_id is not None - assert UUID(first.operation_id).hex == first.operation_id - assert UUID(second.operation_id).hex == second.operation_id - assert first.operation_id != second.operation_id - - -def test_context_aware_hook_specs_match_trigger_contracts(): - expected = { - H.TEXT_MEMORY_ADD_AFTER: ( - ["hook_context", "text_memory", "memories", "kwargs", "result"], - "result", - ), - H.TEXT_MEMORY_ADD_FAILED: ( - ["hook_context", "text_memory", "memories", "kwargs", "error"], - None, - ), - H.SCHEDULER_MEMORY_OPERATION_AFTER: ( - ["hook_context", "operation", "target", "operation_input", "result"], - "result", - ), - H.SCHEDULER_MEMORY_OPERATION_FAILED: ( - ["hook_context", "operation", "target", "operation_input", "error"], - None, - ), - H.MEM_READER_EXTRACT_AFTER: ( - [ - "hook_context", - "mem_reader", - "scene_data", - "type", - "info", - "mode", - "user_name", - "kwargs", - "result", - ], - "result", - ), - H.MEM_READER_EXTRACT_FAILED: ( - [ - "hook_context", - "mem_reader", - "scene_data", - "type", - "info", - "mode", - "user_name", - "kwargs", - "error", - ], - None, - ), - } - - for hook_name, (params, pipe_key) in expected.items(): - spec = get_hook_spec(hook_name) - assert spec is not None - assert spec.params == params - assert spec.pipe_key == pipe_key - - -def test_hook_context_is_omitted_only_for_legacy_exact_signature_callbacks(): - hook_name = "test.hook-context.compat" +def test_hook_context_is_additive_for_new_and_legacy_callbacks(): + hook_name = "test.hook-context.compatibility" define_hook( hook_name, - description="hook context compatibility test", + description="HookContext compatibility", params=["hook_context", "result"], pipe_key="result", ) @@ -149,164 +83,106 @@ def context_callback(*, hook_context, result): calls.append(("context", hook_context, result)) return result + 1 - def kwargs_callback(*, result, **kwargs): - calls.append(("kwargs", kwargs["hook_context"], result)) - return result + 1 - register_hook(hook_name, legacy_callback) register_hook(hook_name, context_callback) - register_hook(hook_name, kwargs_callback) result = trigger_hook(hook_name, hook_context=context, result=1) - assert result == 4 - assert calls == [ - ("legacy", 1), - ("context", context, 2), - ("kwargs", context, 3), - ] - - -def test_hook_callback_type_error_is_not_retried(): - hook_name = "test.hook-context.type-error" - define_hook( - hook_name, - description="hook callback type error test", - params=["hook_context", "value"], - ) - calls = [] - - def callback(*, hook_context, value): - calls.append((hook_context, value)) - raise TypeError("raised inside callback") - - register_hook(hook_name, callback) - - trigger_hook(hook_name, hook_context="context", value="value") - - assert calls == [("context", "value")] + assert result == 3 + assert calls == [("legacy", 1), ("context", context, 2)] -def test_trigger_single_hook_supports_legacy_exact_signature(): +def test_single_provider_hook_supports_legacy_callback(): hook_name = "test.single.hook-context" define_hook( hook_name, - description="single hook context compatibility test", + description="Single-provider HookContext compatibility", params=["hook_context", "value"], ) + calls = [] - def handler(*, value): + def callback(*, value): + calls.append(value) return value + 1 - register_hook(hook_name, handler) + register_hook(hook_name, callback) - result = trigger_single_hook(hook_name, hook_context=object(), value=1) + assert trigger_single_hook(hook_name, hook_context=object(), value=1) == 2 + assert calls == [1] - assert result == 2 +def test_hookable_shares_and_reuses_context_for_sync_operation(): + built_context = object() + supplied_context = object() + builder_calls = [] + observed = [] -def test_hookable_shares_context_with_sync_operation_and_legacy_callback(): - context = object() - calls = [] + def build_context(_handler, request): + builder_calls.append(request) + return built_context class Handler: - @hookable( - "context_sync", - context_builder=lambda _self, _request: context, - ) + @hookable("context_sync", context_builder=build_context) def run(self, request, *, hook_context=None): - calls.append(("operation", hook_context, request)) - return f"processed:{request}" - - def legacy_before(*, request): - calls.append(("legacy_before", request)) + observed.append(("operation", hook_context)) + return request - def context_before(*, hook_context, request): - calls.append(("context_before", hook_context, request)) + def before(*, hook_context, **_kwargs): + observed.append(("before", hook_context)) - def context_after(*, hook_context, request, result): - calls.append(("context_after", hook_context, request, result)) + def after(*, hook_context, **_kwargs): + observed.append(("after", hook_context)) - register_hook("context_sync.before", legacy_before) - register_hook("context_sync.before", context_before) - register_hook("context_sync.after", context_after) + register_hook("context_sync.before", before) + register_hook("context_sync.after", after) - result = Handler().run("request") + Handler().run("built") + Handler().run("supplied", hook_context=supplied_context) - assert result == "processed:request" - assert calls == [ - ("legacy_before", "request"), - ("context_before", context, "request"), - ("operation", context, "request"), - ("context_after", context, "request", "processed:request"), - ] - before_spec = get_hook_spec("context_sync.before") - after_spec = get_hook_spec("context_sync.after") - assert before_spec is not None - assert after_spec is not None - assert before_spec.params == ["hook_context", "request"] - assert after_spec.params == [ - "hook_context", - "request", - "result", + assert builder_calls == ["built"] + assert observed == [ + ("before", built_context), + ("operation", built_context), + ("after", built_context), + ("before", supplied_context), + ("operation", supplied_context), + ("after", supplied_context), ] -def test_hookable_reuses_explicit_context_without_calling_builder(): +def test_hookable_shares_and_reuses_context_for_async_operation(): + built_context = object() supplied_context = object() builder_calls = [] - observed_contexts = [] + observed = [] - def build_context(_self, request): + def build_context(_handler, request): builder_calls.append(request) - return object() + return built_context class Handler: - @hookable("explicit_context", context_builder=build_context) - def run(self, request, *, hook_context=None): - observed_contexts.append(hook_context) - return request - - def observe_context(*, hook_context, **_kwargs): - observed_contexts.append(hook_context) - - register_hook("explicit_context.before", observe_context) - register_hook("explicit_context.after", observe_context) - - result = Handler().run("request", hook_context=supplied_context) - - assert result == "request" - assert builder_calls == [] - assert observed_contexts == [supplied_context] * 3 - - -def test_hookable_shares_context_with_async_operation(): - context = object() - calls = [] - - class Handler: - @hookable( - "context_async", - context_builder=lambda _self, _request: context, - ) + @hookable("context_async", context_builder=build_context) async def run(self, request, *, hook_context=None): - calls.append(("operation", hook_context, request)) - return "async_result" - - def on_before(*, hook_context, request): - calls.append(("before", hook_context, request)) - - def on_after(*, hook_context, request, result): - calls.append(("after", hook_context, request, result)) - - register_hook("context_async.before", on_before) - register_hook("context_async.after", on_after) - - result = asyncio.run(Handler().run("request")) + observed.append(("operation", hook_context)) + return request - assert result == "async_result" - assert calls == [ - ("before", context, "request"), - ("operation", context, "request"), - ("after", context, "request", "async_result"), + def observe(stage): + def callback(*, hook_context, **_kwargs): + observed.append((stage, hook_context)) + + return callback + + register_hook("context_async.before", observe("before")) + register_hook("context_async.after", observe("after")) + + assert asyncio.run(Handler().run("built")) == "built" + assert asyncio.run(Handler().run("supplied", hook_context=supplied_context)) == "supplied" + assert builder_calls == ["built"] + assert observed == [ + ("before", built_context), + ("operation", built_context), + ("after", built_context), + ("before", supplied_context), + ("operation", supplied_context), + ("after", supplied_context), ] From a070ac5a9935eb358212e6d52f04d75ceccdafa6 Mon Sep 17 00:00:00 2001 From: qzs Date: Fri, 16 Oct 2026 14:51:34 +0800 Subject: [PATCH 5/9] docs(plugins): clarify hook documentation and comments --- src/memos/plugins/README.md | 18 +----------------- src/memos/plugins/hook_defs.py | 4 ++-- src/memos/plugins/hooks.py | 2 +- 3 files changed, 4 insertions(+), 20 deletions(-) diff --git a/src/memos/plugins/README.md b/src/memos/plugins/README.md index 859fe76d7..3832bca1e 100644 --- a/src/memos/plugins/README.md +++ b/src/memos/plugins/README.md @@ -286,23 +286,7 @@ Hook callbacks receive keyword arguments. Some Hooks define a `pipe_key`; when a callback returns a non-`None` value, that value replaces the named argument for later callbacks and for the caller. -`hook_context` is additive correlation metadata, not a separate event model. -Context-aware callbacks can declare it explicitly or accept `**kwargs`. Legacy -callbacks with an exact signature remain compatible: the runtime omits only an -unsupported `hook_context` argument and still invokes the callback once. New -callbacks should accept `**kwargs` so later additive metadata remains backward -compatible. - -All Search Hooks triggered for one request—from `SEARCH_BEFORE` through -`SEARCH_AFTER`, including result and post-processing Hooks—receive the same -`HookContext` instance and `operation_id`. - -The MemReader extraction, Textual Memory add, and successful Scheduler -operation Hooks pipe their `result` value. Their matching failure Hooks are -notifications and therefore do not define a `pipe_key`. - -`SEARCH_POST_PROCESS_FAILED` reports a result post-processing error that -continues to propagate to the Search API caller. +`hook_context` is additive correlation metadata. Context-aware callbacks can declare it explicitly or accept `**kwargs`. Legacy callbacks with an exact signature remain compatible: the runtime omits only an unsupported `hook_context` argument and still invokes the callback once. New callbacks should accept `**kwargs` so later additive metadata remains backward compatible. For example, `add.after` can replace `result`: diff --git a/src/memos/plugins/hook_defs.py b/src/memos/plugins/hook_defs.py index 87375e942..95cc493f6 100644 --- a/src/memos/plugins/hook_defs.py +++ b/src/memos/plugins/hook_defs.py @@ -109,7 +109,7 @@ class H: # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ -# CE Hook declarations +# CE custom Hook declarations (@hookable-generated ones need not be declared here) # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ define_hook( @@ -237,7 +237,7 @@ class H: ) # Operation-boundary Hooks. Their business data remains explicit in the -# normal Hook keyword-argument contract; HookContext only carries correlation +# normal keyword-argument contract. HookContext only carries correlation # metadata. define_hook( H.TEXT_MEMORY_ADD_AFTER, diff --git a/src/memos/plugins/hooks.py b/src/memos/plugins/hooks.py index 4128da3b7..084f0b66b 100644 --- a/src/memos/plugins/hooks.py +++ b/src/memos/plugins/hooks.py @@ -46,7 +46,7 @@ def _invoke_hook_callback(callback: Callable, kwargs: dict[str, Any]) -> Any: ``hook_context`` is additive framework metadata. Older callbacks that use an exact keyword-only signature continue to receive the original business - arguments; context-aware callbacks and callbacks with ``**kwargs`` receive + arguments. Context-aware callbacks and callbacks with ``**kwargs`` receive the complete contract. """ if "hook_context" not in kwargs or _accepts_hook_context(callback): From 2cbb3a8685c50b5f440fdf186ffbcde23c035136 Mon Sep 17 00:00:00 2001 From: qzs Date: Fri, 16 Oct 2026 17:16:03 +0800 Subject: [PATCH 6/9] docs(plugins): clarify hook documentation in README.md and HOOKS.md --- src/memos/plugins/HOOKS.md | 290 ++++++++++++++++++++++++++++++++++++ src/memos/plugins/README.md | 66 ++++++-- 2 files changed, 344 insertions(+), 12 deletions(-) create mode 100644 src/memos/plugins/HOOKS.md diff --git a/src/memos/plugins/HOOKS.md b/src/memos/plugins/HOOKS.md new file mode 100644 index 000000000..c28a63b9b --- /dev/null +++ b/src/memos/plugins/HOOKS.md @@ -0,0 +1,290 @@ +# Pipeline Hook Reference + +Use this reference when implementing a plugin that observes or modifies MemOS +search, extraction, or memory operations. For plugin registration and lifecycle, +start with the [plugin guide](README.md#using-hooks). + +Hook names and keyword parameters are declared in [hook_defs.py](hook_defs.py). +The runtime lives in [hooks.py](hooks.py). + +--- + +## How hooks work + +Every hook falls into one of two patterns: + +| Pattern | Return value matters? | API | Exception handling | +| --- | --- | --- | --- | +| **Pipeline hook** — has a `pipe_key` | Yes — non-`None` replaces that argument for subsequent callbacks | `trigger_hook` | Logged and swallowed; later callbacks still run | +| **Observer hook** — no `pipe_key` | No | `trigger_hook` | Logged and swallowed | +| **Single-provider hook** | Returned directly to caller | `trigger_single_hook` | Re-raised | + +Memory-version and Dream business hooks use the single-provider API; their declarations +are in [hook_defs.py](hook_defs.py). All hooks documented below use `trigger_hook`. + +### Quick example + +```python +from memos.plugins import H + +class MyPlugin(BasePlugin): + def on_enable(self): + # Observe results without changing them + self.register_hook(H.SEARCH_AFTER, self._on_search_done) + + # Replace results mid-pipeline + self.register_hook(H.SEARCH_RESULTS_AFTER_RERANK, self._rerank) + + def _on_search_done(self, request, result, **kwargs): + print(f"Search for '{request.query}' returned {len(result.memories)} results") + + def _rerank(self, results, **kwargs): + # pipe_key=results — return non-None to propagate the change + for bucket in results.values(): + bucket.sort(key=lambda m: my_score(m), reverse=True) + return results +``` + +--- + +## Registering callbacks + +- Call `self.register_hook(H.NAME, callback)` **once** per plugin lifecycle. Registration is + additive — calling it twice registers the callback twice. +- Callbacks run synchronously, in registration order. `@hookable`-decorated handlers support + async, but hook callbacks themselves are not awaited. +- Accept `**kwargs` in any callback to stay forward-compatible when a hook gains new arguments. + +--- + +## Pipeline callbacks (`pipe_key` present) + +The `pipe_key` column tells you which argument a return value replaces: + +- **Return a non-`None` value** → replaces that argument for all later callbacks and the caller. +- **Return `None`** → keeps the current value unchanged. +- `False`, `[]`, `{}`, and `0` are all **replacements** — only `None` means "pass-through". + +Because arguments are live objects, in-place mutations are visible to later callbacks even when +your callback returns `None`. Return a copy when isolation is needed, and preserve the shape +downstream code expects. + +--- + +## Observer callbacks (no `pipe_key`) + +Return values are ignored. These hooks are for side effects only — logging, metrics, +notifications, etc. The same live-object caveat applies: mutating an argument in-place +is visible downstream even though the callback's return is discarded. + +--- + +## Exception handling + +`trigger_hook` logs any `Exception` raised by a callback and continues to subsequent +callbacks. Mutations made before the exception are **not** rolled back. A crashing observer +does not, by itself, fail the business operation. + +The single-provider API (`trigger_single_hook`) propagates exceptions — see each hook's +documentation for which API it uses. + +--- + +## HookContext + +Context-aware hooks receive `hook_context` alongside their business arguments. +It carries correlation metadata, not the request, result, or exception payload. + +| Field | Meaning | +| --- | --- | +| `trace_id` | Trace identifier available at the operation boundary. | +| `user_id` | User identifier from the request, reader input, or scheduler message. | +| `session_id` | Session identifier when available. Search uses `default_session` when omitted. | +| `task_id` | Task identifier when available. | +| `cube_ids` | Tuple of relevant cube identifiers; empty when unavailable. | +| `operation_id` | UUID hex string identifying one observed operation. | +| `source` | Integration point that created the context; see the tables below. | +| `attributes` | Integration-specific metadata such as mode or scheduler item ID. | + +Fields unavailable at a boundary are `None`. Treat the context as read-only — the +dataclass is frozen, but `attributes` is not deeply immutable. The builder copies the +outer attributes mapping and converts cube IDs to a tuple. + +### Receiving `hook_context` in your callback + +Declare `hook_context` as a keyword parameter, or pull it from `**kwargs`: + +```python +# Option A — explicit parameter +def my_callback(self, results, hook_context, **kwargs): + print(hook_context.trace_id) + +# Option B — via kwargs (useful when the same handler is registered on hooks +# both with and without context) +def my_callback(self, results, **kwargs): + ctx = kwargs.get("hook_context") # None if hook does not provide it +``` + +The runtime omits `hook_context` when the callback's signature accepts neither form. +Hooks that do **not** provide context will never pass it, even if you declare the parameter. + +### Context scope + +- All hooks in one **search** invocation share the same context object. It is built before + `search.before`, so replacing the request does not rebuild the context. Use the callback's + `request` argument for the current business input. +- **Reader extraction**, **cube writes**, and **scheduler operations** each create a separate + context. Do not assume they share an `operation_id`; use `trace_id` or `task_id` for + broader correlation. + +--- + +## Search pipeline + +The successful `SearchHandler.handle_search_memories` path is: + +```text +search.before + └─► retrieval + └─► search.memory_results + └─► threshold filtering ──► search.results.after_threshold + └─► deduplication ──► search.results.after_dedup + └─► reranking ──► search.results.after_rerank + └─► search.context.render + └─► SearchResponse construction + └─► search.after +``` + +Every hook receives `hook_context`. Context source: `api.search`; attributes contain `mode`. + +| Constant / Hook name | Additional arguments | `pipe_key` | Typical use | +| --- | --- | --- | --- | +| `H.SEARCH_BEFORE` / `search.before` | `request` | `request` | Rewrite the query or inject filters before retrieval. | +| `H.SEARCH_MEMORY_RESULTS` / `search.memory_results` | `handler`, `search_req`, `results` | `results` | Inspect or augment raw retrieval output. | +| `H.SEARCH_RESULTS_AFTER_THRESHOLD` / `search.results.after_threshold` | `handler`, `search_req`, `results` | `results` | Remove or re-score results after score filtering. | +| `H.SEARCH_RESULTS_AFTER_DEDUP` / `search.results.after_dedup` | `handler`, `search_req`, `results` | `results` | Post-dedup cleanup; runs even when no dedup mode is selected. | +| `H.SEARCH_RESULTS_AFTER_RERANK` / `search.results.after_rerank` | `handler`, `search_req`, `results` | `results` | Apply a custom final ranking. | +| `H.SEARCH_CONTEXT_RENDER` / `search.context.render` | `handler`, `search_req`, `results` | `results` | Last chance to modify the result dictionary before response construction. | +| `H.SEARCH_AFTER` / `search.after` | `request`, `result` | `result` | Post-process or log the final `SearchResponse`. | +| `H.SEARCH_POST_PROCESS_FAILED` / `search.post_process.failed` | `handler`, `search_req`, `error` | — | Observe an exception escaping threshold/dedup/reranking. | + +**Argument notes:** +- `request` at `search.before` and `search.after` is an `APISearchRequest`. The `search.after` + hook receives the request *after* any `search.before` replacement. +- Intermediate hooks receive `search_req` (the handler's working copy, which may include + internal adjustments such as expanded `top_k` for deduplication) and `results` (the + result-bucket dictionary). When returning a replacement, preserve its required buckets and + item structures. + +--- + +## MemReader extraction + +These hooks wrap `SimpleStructMemReader.get_memory`, including subclasses that inherit +that implementation. + +```text +get_memory() + └─► validation + input coercion + _read_memory() + ├─► [success] mem_reader.extract.after + └─► [failure] mem_reader.extract.failed ──► exception re-raised +``` + +Both hooks receive `hook_context`, `mem_reader`, `scene_data`, `type`, `info`, `mode`, +`user_name`, and `kwargs`. + +| Constant / Hook name | Additional argument | Timing | `pipe_key` | +| --- | --- | --- | --- | +| `H.MEM_READER_EXTRACT_AFTER` / `mem_reader.extract.after` | `result` | After validation, input coercion, and `_read_memory` return successfully. | `result` | +| `H.MEM_READER_EXTRACT_FAILED` / `mem_reader.extract.failed` | `error` | When validation, input coercion, or `_read_memory` raises an exception. | — | + +- `scene_data` is the raw input passed to `get_memory`, before coercion. +- `kwargs` is the dictionary of extra reader arguments. +- `result` has the shape `list[list[TextualMemoryItem]]`. +- The failure hook observes the original exception, which is then re-raised. + +Context: source `mem_reader.extract`; user/session IDs from `info`; cube IDs from +`user_name` when supplied; attributes contain `mode` and `type`. + +--- + +## Textual memory writes + +These hooks surround the `text_memory.add` call in `SingleCubeView._process_text_mem`. + +```text +_process_text_mem() + └─► text_memory.add(memories, user_name=...) + ├─► [success] text_memory.add.after + └─► [failure] text_memory.add.failed ──► exception re-raised +``` + +Both hooks receive `hook_context`, `text_memory`, `memories`, and `kwargs`. +- `memories` is the group submitted to the backend, excluding `RawFileMemory` items. +- `kwargs` contains the `user_name` for the write. + +| Constant / Hook name | Additional argument | Timing | `pipe_key` | +| --- | --- | --- | --- | +| `H.TEXT_MEMORY_ADD_AFTER` / `text_memory.add.after` | `result` | After the backend add call returns. | `result` | +| `H.TEXT_MEMORY_ADD_FAILED` / `text_memory.add.failed` | `error` | When the backend add call raises an exception. | — | + +- The success `result` is a list of stored memory IDs. A replacement is consumed by subsequent + processing, including scheduling and response construction — keep IDs consistent with the + stored memories. +- Backend exceptions are re-raised after observation. + +Context: source `cube_view.text_mem.add`; attributes contain `sync_mode` and `extract_mode`; +user, session, task, and cube metadata come from the add operation. + +--- + +## Scheduler memory operations + +`MemReadMessageHandler` observes selected operations through `SchedulerOperationObserver`. +Both hooks receive `hook_context`, `operation`, `target`, and `operation_input`. + +```text +SchedulerOperationObserver + └─► operation (fine | add | archive | delete | soft_delete) + ├─► [success] scheduler.memory.operation.after + └─► [failure] scheduler.memory.operation.failed +``` + +| Constant / Hook name | Additional argument | `pipe_key` | +| --- | --- | --- | +| `H.SCHEDULER_MEMORY_OPERATION_AFTER` / `scheduler.memory.operation.after` | `result` | `result` | +| `H.SCHEDULER_MEMORY_OPERATION_FAILED` / `scheduler.memory.operation.failed` | `error` | — | + +For the current MemRead integration, `target` is `textual_memory`. Context source has the +prefix `scheduler.mem_read.` followed by the operation suffix below. + +| `operation` | Source suffix | `operation_input` keys | Successful result | Notes | +| --- | --- | --- | --- | --- | +| `fine` | `fine_transfer_simple_mem` | `memories`, `type`, `result_grouping` | Nested reader output; replacements consumed before flattening and storage. | See [Fine-transfer result grouping](#fine-transfer-result-grouping). | +| `add` | `add_enhanced_memories` | `memories`, `user_name` | Stored IDs; replacements consumed by subsequent processing. | | +| `archive` | `archive_merged_memories` | `memory_ids` | Backend update return value; handler does not consume a replacement. | May emit one observation per merged memory. | +| `delete` | `remove_memories` | `memory_ids` | Backend delete return value; handler does not consume a replacement. | | +| `soft_delete` | `remove_memories` | `memory_ids`, `preserved_memory_ids` | Backend soft-delete return value; handler does not consume a replacement. | | + +Context attributes include available `scheduler_item_id`, `redis_message_id`, and `label`. + +The observer emits a success hook only after the operation block exits successfully — a +recorded `None` is still a successful result. Failure is reported at most once per observer. +These operations run only when the corresponding handler branch executes. + +### Fine-transfer result grouping + +Check `operation_input["result_grouping"]` on `fine` operations before matching output +groups to input memories: + +| Value | Interpretation | +| --- | --- | +| `per_input` | One group per input, in input order (built-in `SimpleStructMemReader`). A worker exception or `None` result leaves an empty group at that position. Empty input → `[]`. | +| `batch` | One group for the entire batch (built-in `MultiModalStructMemReader`). Not one-to-one with inputs — **do not zip**. Empty input → `[]`. | +| `unknown` | Implementation not recognized (e.g. a method override). Do not assume positional correspondence. | + +The label describes the reader's contract, not your plugin's replacement. Preserve the +original grouping in a replacement so downstream callbacks can interpret it consistently. + +Inheriting a recognized built-in method preserves its grouping label. An override receives +`unknown`, even if it belongs to a subclass of a built-in reader. diff --git a/src/memos/plugins/README.md b/src/memos/plugins/README.md index 3832bca1e..41904d293 100644 --- a/src/memos/plugins/README.md +++ b/src/memos/plugins/README.md @@ -27,6 +27,7 @@ src/memos/plugins/ ├── base.py # MemOSPlugin base class ├── manager.py # Plugin discovery, loading, and initialization ├── hooks.py # Hook registration and trigger runtime +├── hook_context.py # Operation correlation metadata ├── hook_defs.py # Core Hook declarations and constants └── component_bootstrap.py # Runtime component context bootstrap helpers ``` @@ -264,38 +265,79 @@ Core Hook names are defined in `memos.plugins.hook_defs.H`. Common extension points include: ```python +# Memory add H.ADD_BEFORE H.ADD_AFTER + +# Search pipeline H.SEARCH_BEFORE H.SEARCH_AFTER H.SEARCH_MEMORY_RESULTS -H.SEARCH_RESULTS_AFTER_THRESHOLD -H.SEARCH_RESULTS_AFTER_DEDUP -H.SEARCH_RESULTS_AFTER_RERANK +H.SEARCH_RESULTS_AFTER_THRESHOLD # after score threshold filtering +H.SEARCH_RESULTS_AFTER_DEDUP # after deduplication +H.SEARCH_RESULTS_AFTER_RERANK # after reranking H.SEARCH_CONTEXT_RENDER -H.SEARCH_POST_PROCESS_FAILED +H.SEARCH_POST_PROCESS_FAILED # threshold / dedup / rerank exception escaped + +# MemReader extraction H.MEM_READER_PRE_EXTRACT H.MEMORY_ITEMS_AFTER_FINE_EXTRACT H.MEM_READER_EXTRACT_AFTER + +# Textual memory writes H.TEXT_MEMORY_ADD_AFTER + +# Scheduler operations H.SCHEDULER_MEMORY_OPERATION_AFTER + +# Dream H.DREAM_EXECUTE ``` -Hook callbacks receive keyword arguments. Some Hooks define a `pipe_key`; when a -callback returns a non-`None` value, that value replaces the named argument for -later callbacks and for the caller. +Hook callbacks receive keyword arguments and run synchronously in registration +order. Some Hooks define a `pipe_key`; when a callback returns a non-`None` value, +that value replaces the named argument for later callbacks and for the caller. +Return `None` to leave the current value unchanged. -`hook_context` is additive correlation metadata. Context-aware callbacks can declare it explicitly or accept `**kwargs`. Legacy callbacks with an exact signature remain compatible: the runtime omits only an unsupported `hook_context` argument and still invokes the callback once. New callbacks should accept `**kwargs` so later additive metadata remains backward compatible. +Some Hooks carry a `hook_context` argument with operation correlation metadata +(trace, user, session, task, and cube IDs). Declare `hook_context` as a keyword +parameter to access it, or read it from `**kwargs`. The runtime silently omits +`hook_context` for callbacks that accept neither — existing callbacks with a +fixed signature stay compatible. Always include `**kwargs` in new callbacks so +future additive arguments do not require a signature change. -For example, `add.after` can replace `result`: +For example, a plugin can observe a search operation and cap its requested result +count through the `search.before` request pipeline: ```python -def on_add_after(*, request, result, **kwargs): - result.metadata["handled_by"] = "foo" - return result +from memos.log import get_logger +from memos.plugins import H, MemOSPlugin + + +logger = get_logger(__name__) + + +def on_search_before(*, hook_context, request, **kwargs): + logger.info("Search operation: %s", hook_context.operation_id) + return request.model_copy(update={"top_k": min(request.top_k, 20)}) + + +class SearchLimitPlugin(MemOSPlugin): + name = "search_limit" + + def on_load(self) -> None: + self.register_hook(H.SEARCH_BEFORE, on_search_before) ``` +Expose the plugin through an entry point as described in +[Registering a Plugin](#registering-a-plugin). The callback above changes the +request's `top_k`; subsequent pipeline stages and plugins still control the final +response. + +For trigger order, keyword parameters, replacement rules, failure boundaries, +`HookContext` fields, and so on, see the +[Pipeline Hook Reference](HOOKS.md). + ### Defining Plugin-Owned Hooks Plugins may define their own Hook names when they need internal extension From ad2ff52ba042f4edd29f454f731ed70b3c9b3173 Mon Sep 17 00:00:00 2001 From: qzs Date: Mon, 19 Oct 2026 17:05:33 +0800 Subject: [PATCH 7/9] refactor(hooks): simplify scheduler operation contracts - Normalize scheduler context to dictionaries and remove target parameter - Include reader and deletion arguments in operation inputs - Remove archive observations and redundant search context initialization - Update hook documentation and regression tests --- src/memos/api/handlers/search_handler.py | 3 - .../task_schedule_modules/base_handler.py | 4 +- .../handlers/mem_read_handler.py | 36 +++++------ .../operation_observer.py | 38 +++++------ src/memos/plugins/HOOKS.md | 63 +++---------------- src/memos/plugins/README.md | 3 + src/memos/plugins/hook_defs.py | 6 +- .../mem_scheduler/test_operation_observer.py | 54 +++++++++------- 8 files changed, 75 insertions(+), 132 deletions(-) diff --git a/src/memos/api/handlers/search_handler.py b/src/memos/api/handlers/search_handler.py index c95a89270..a94318a7e 100644 --- a/src/memos/api/handlers/search_handler.py +++ b/src/memos/api/handlers/search_handler.py @@ -98,8 +98,6 @@ def handle_search_memories( # Use deepcopy to avoid modifying the original request object search_req_local = copy.deepcopy(search_req) - if hook_context is None: - hook_context = self._build_search_hook_context(search_req_local) # Expand top_k for deduplication (5x to ensure enough candidates) if search_req_local.dedup in ("sim", "mmr"): @@ -108,7 +106,6 @@ def handle_search_memories( # Search and deduplicate cube_view = self._build_cube_view(search_req_local) results = cube_view.search_memories(search_req_local) - hooked_results = trigger_hook( H.SEARCH_MEMORY_RESULTS, hook_context=hook_context, diff --git a/src/memos/mem_scheduler/task_schedule_modules/base_handler.py b/src/memos/mem_scheduler/task_schedule_modules/base_handler.py index 438c30a0b..67c39aa0f 100644 --- a/src/memos/mem_scheduler/task_schedule_modules/base_handler.py +++ b/src/memos/mem_scheduler/task_schedule_modules/base_handler.py @@ -42,8 +42,7 @@ def observe_operation( operation_name: str, *, operation: str, - target: str, - operation_context: Any, + operation_context: dict[str, Any], operation_input: dict[str, Any], capture_failure: bool = False, ) -> SchedulerOperationObserver: @@ -52,7 +51,6 @@ def observe_operation( return SchedulerOperationObserver( source=source, operation=operation, - target=target, operation_context=operation_context, operation_input=operation_input, capture_failure=capture_failure, diff --git a/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py b/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py index f203c2346..743627d19 100644 --- a/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py +++ b/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py @@ -96,7 +96,7 @@ def process_message(self, message: ScheduleMessageItem): info=info, chat_history=chat_history, user_context=user_context, - operation_context=message, + operation_context=message.model_dump(), ) logger.info( @@ -120,7 +120,7 @@ def _process_memories_with_reader( info: dict | None = None, chat_history: list | None = None, user_context: UserContext | None = None, - operation_context: Any | None = None, + operation_context: dict | None = None, ) -> None: logger.info( "[DIAGNOSTIC] mem_read_handler._process_memories_with_reader called. mem_ids: %s, user_id: %s, mem_cube_id: %s, task_id: %s", @@ -180,11 +180,15 @@ def _process_memories_with_reader( with self.observe_operation( "fine_transfer_simple_mem", operation="fine", - target="textual_memory", operation_context=operation_context, operation_input={ "memories": memory_items, "type": "chat", + "custom_tags": custom_tags, + "user_name": user_name, + "chat_history": chat_history, + "user_context": user_context, + "is_upload_skill": is_upload_skill, "result_grouping": self._fine_transfer_result_grouping(mem_reader), }, capture_failure=True, @@ -221,7 +225,6 @@ def _process_memories_with_reader( with self.observe_operation( "add_enhanced_memories", operation="add", - target="textual_memory", operation_context=operation_context, operation_input={"memories": mem_group, "user_name": user_name}, capture_failure=True, @@ -276,21 +279,11 @@ def _process_memories_with_reader( ) for old_id in old_ids: try: - with self.observe_operation( - "archive_merged_memories", - operation="archive", - target="textual_memory", - operation_context=operation_context, - operation_input={"memory_ids": [str(old_id)]}, - capture_failure=True, - ) as observation: - observation.result( - mem_reader.graph_db.update_node( - str(old_id), - {"status": "archived"}, - user_name=user_name, - ) - ) + mem_reader.graph_db.update_node( + str(old_id), + {"status": "archived"}, + user_name=user_name, + ) logger.info( "[Scheduler] Archived merged_from memory: %s", old_id, @@ -450,9 +443,8 @@ def _process_memories_with_reader( with self.observe_operation( "remove_memories", operation="delete", - target="textual_memory", operation_context=operation_context, - operation_input={"memory_ids": delete_ids}, + operation_input={"memory_ids": delete_ids, "user_name": user_name}, capture_failure=True, ) as observation: observation.result(text_mem.delete(delete_ids, user_name=user_name)) @@ -476,10 +468,10 @@ def _process_memories_with_reader( with self.observe_operation( "remove_memories", operation="soft_delete", - target="textual_memory", operation_context=operation_context, operation_input={ "memory_ids": delete_ids, + "user_name": user_name, "preserved_memory_ids": preserved_memory_ids, }, capture_failure=True, diff --git a/src/memos/mem_scheduler/task_schedule_modules/operation_observer.py b/src/memos/mem_scheduler/task_schedule_modules/operation_observer.py index 7a151d4ab..89a737663 100644 --- a/src/memos/mem_scheduler/task_schedule_modules/operation_observer.py +++ b/src/memos/mem_scheduler/task_schedule_modules/operation_observer.py @@ -1,14 +1,17 @@ from __future__ import annotations -from collections.abc import Mapping from contextlib import AbstractContextManager -from typing import Any +from typing import TYPE_CHECKING, Any from memos.plugins.hook_context import build_hook_context from memos.plugins.hook_defs import H from memos.plugins.hooks import trigger_hook +if TYPE_CHECKING: + from collections.abc import Mapping + + _MISSING = object() @@ -26,24 +29,20 @@ def __init__( *, source: str, operation: str, - target: str, - operation_context: Any, + operation_context: dict[str, Any], operation_input: Mapping[str, Any], capture_failure: bool = False, ) -> None: self._hook_kwargs = { "operation": operation, - "target": target, "operation_input": dict(operation_input), } - cube_id = self._context_value(operation_context, "cube_id") or self._context_value( - operation_context, "mem_cube_id" - ) + cube_id = operation_context.get("cube_id") or operation_context.get("mem_cube_id") self._hook_context = build_hook_context( - trace_id=self._context_value(operation_context, "trace_id"), - user_id=self._context_value(operation_context, "user_id"), - session_id=self._context_value(operation_context, "session_id"), - task_id=self._context_value(operation_context, "task_id"), + trace_id=operation_context.get("trace_id"), + user_id=operation_context.get("user_id"), + session_id=operation_context.get("session_id"), + task_id=operation_context.get("task_id"), cube_ids=[str(cube_id)] if cube_id else None, source=source, attributes=self._attributes(operation_context), @@ -95,17 +94,10 @@ def failed(self, error: BaseException) -> None: ) @staticmethod - def _context_value(operation_context: Any, name: str) -> Any: - if isinstance(operation_context, Mapping): - return operation_context.get(name) - return getattr(operation_context, name, None) - - @classmethod - def _attributes(cls, operation_context: Any) -> dict[str, Any]: + def _attributes(operation_context: dict[str, Any]) -> dict[str, Any]: attributes = { - "scheduler_item_id": cls._context_value(operation_context, "scheduler_item_id") - or cls._context_value(operation_context, "item_id"), - "redis_message_id": cls._context_value(operation_context, "redis_message_id"), - "label": cls._context_value(operation_context, "label"), + "scheduler_item_id": operation_context.get("scheduler_item_id") + or operation_context.get("item_id"), + "label": operation_context.get("label"), } return {key: value for key, value in attributes.items() if value is not None} diff --git a/src/memos/plugins/HOOKS.md b/src/memos/plugins/HOOKS.md index c28a63b9b..6a3276507 100644 --- a/src/memos/plugins/HOOKS.md +++ b/src/memos/plugins/HOOKS.md @@ -11,7 +11,7 @@ The runtime lives in [hooks.py](hooks.py). ## How hooks work -Every hook falls into one of two patterns: +Every hook falls into one of three patterns: | Pattern | Return value matters? | API | Exception handling | | --- | --- | --- | --- | @@ -19,32 +19,6 @@ Every hook falls into one of two patterns: | **Observer hook** — no `pipe_key` | No | `trigger_hook` | Logged and swallowed | | **Single-provider hook** | Returned directly to caller | `trigger_single_hook` | Re-raised | -Memory-version and Dream business hooks use the single-provider API; their declarations -are in [hook_defs.py](hook_defs.py). All hooks documented below use `trigger_hook`. - -### Quick example - -```python -from memos.plugins import H - -class MyPlugin(BasePlugin): - def on_enable(self): - # Observe results without changing them - self.register_hook(H.SEARCH_AFTER, self._on_search_done) - - # Replace results mid-pipeline - self.register_hook(H.SEARCH_RESULTS_AFTER_RERANK, self._rerank) - - def _on_search_done(self, request, result, **kwargs): - print(f"Search for '{request.query}' returned {len(result.memories)} results") - - def _rerank(self, results, **kwargs): - # pipe_key=results — return non-None to propagate the change - for bucket in results.values(): - bucket.sort(key=lambda m: my_score(m), reverse=True) - return results -``` - --- ## Registering callbacks @@ -71,25 +45,6 @@ downstream code expects. --- -## Observer callbacks (no `pipe_key`) - -Return values are ignored. These hooks are for side effects only — logging, metrics, -notifications, etc. The same live-object caveat applies: mutating an argument in-place -is visible downstream even though the callback's return is discarded. - ---- - -## Exception handling - -`trigger_hook` logs any `Exception` raised by a callback and continues to subsequent -callbacks. Mutations made before the exception are **not** rolled back. A crashing observer -does not, by itself, fail the business operation. - -The single-provider API (`trigger_single_hook`) propagates exceptions — see each hook's -documentation for which API it uses. - ---- - ## HookContext Context-aware hooks receive `hook_context` alongside their business arguments. @@ -241,11 +196,11 @@ user, session, task, and cube metadata come from the add operation. ## Scheduler memory operations `MemReadMessageHandler` observes selected operations through `SchedulerOperationObserver`. -Both hooks receive `hook_context`, `operation`, `target`, and `operation_input`. +Both hooks receive `hook_context`, `operation`, and `operation_input`. ```text SchedulerOperationObserver - └─► operation (fine | add | archive | delete | soft_delete) + └─► operation (fine | add | delete | soft_delete) ├─► [success] scheduler.memory.operation.after └─► [failure] scheduler.memory.operation.failed ``` @@ -255,18 +210,14 @@ SchedulerOperationObserver | `H.SCHEDULER_MEMORY_OPERATION_AFTER` / `scheduler.memory.operation.after` | `result` | `result` | | `H.SCHEDULER_MEMORY_OPERATION_FAILED` / `scheduler.memory.operation.failed` | `error` | — | -For the current MemRead integration, `target` is `textual_memory`. Context source has the -prefix `scheduler.mem_read.` followed by the operation suffix below. +Context source has the prefix `scheduler.mem_read.` followed by the operation suffix below. | `operation` | Source suffix | `operation_input` keys | Successful result | Notes | | --- | --- | --- | --- | --- | -| `fine` | `fine_transfer_simple_mem` | `memories`, `type`, `result_grouping` | Nested reader output; replacements consumed before flattening and storage. | See [Fine-transfer result grouping](#fine-transfer-result-grouping). | +| `fine` | `fine_transfer_simple_mem` | `memories`, `type`, `custom_tags`, `user_name`, `chat_history`, `user_context`, `is_upload_skill`, `result_grouping` | Nested reader output; replacements consumed before flattening and storage. | See [Fine-transfer result grouping](#fine-transfer-result-grouping). | | `add` | `add_enhanced_memories` | `memories`, `user_name` | Stored IDs; replacements consumed by subsequent processing. | | -| `archive` | `archive_merged_memories` | `memory_ids` | Backend update return value; handler does not consume a replacement. | May emit one observation per merged memory. | -| `delete` | `remove_memories` | `memory_ids` | Backend delete return value; handler does not consume a replacement. | | -| `soft_delete` | `remove_memories` | `memory_ids`, `preserved_memory_ids` | Backend soft-delete return value; handler does not consume a replacement. | | - -Context attributes include available `scheduler_item_id`, `redis_message_id`, and `label`. +| `delete` | `remove_memories` | `memory_ids`, `user_name` | Backend delete return value; handler does not consume a replacement. | | +| `soft_delete` | `remove_memories` | `memory_ids`, `user_name`, `preserved_memory_ids` | Backend soft-delete return value; handler does not consume a replacement. | | The observer emits a success hook only after the operation block exits successfully — a recorded `None` is still a successful result. Failure is reported at most once per observer. diff --git a/src/memos/plugins/README.md b/src/memos/plugins/README.md index 41904d293..aecb11890 100644 --- a/src/memos/plugins/README.md +++ b/src/memos/plugins/README.md @@ -283,12 +283,15 @@ H.SEARCH_POST_PROCESS_FAILED # threshold / dedup / rerank exception escape H.MEM_READER_PRE_EXTRACT H.MEMORY_ITEMS_AFTER_FINE_EXTRACT H.MEM_READER_EXTRACT_AFTER +H.MEM_READER_EXTRACT_FAILED # Textual memory writes H.TEXT_MEMORY_ADD_AFTER +H.TEXT_MEMORY_ADD_FAILED # Scheduler operations H.SCHEDULER_MEMORY_OPERATION_AFTER +H.SCHEDULER_MEMORY_OPERATION_FAILED # Dream H.DREAM_EXECUTE diff --git a/src/memos/plugins/hook_defs.py b/src/memos/plugins/hook_defs.py index 95cc493f6..90b6052a2 100644 --- a/src/memos/plugins/hook_defs.py +++ b/src/memos/plugins/hook_defs.py @@ -103,7 +103,7 @@ class H: SCHEDULER_MEMORY_OPERATION_AFTER = "scheduler.memory.operation.after" SCHEDULER_MEMORY_OPERATION_FAILED = "scheduler.memory.operation.failed" - # mem_reader — generic extension point before LLM extraction + # mem_reader — memory extraction MEM_READER_EXTRACT_AFTER = "mem_reader.extract.after" MEM_READER_EXTRACT_FAILED = "mem_reader.extract.failed" @@ -255,14 +255,14 @@ class H: define_hook( H.SCHEDULER_MEMORY_OPERATION_AFTER, description="Observe or replace a successful Scheduler memory operation result", - params=["hook_context", "operation", "target", "operation_input", "result"], + params=["hook_context", "operation", "operation_input", "result"], pipe_key="result", ) define_hook( H.SCHEDULER_MEMORY_OPERATION_FAILED, description="Observe a failed Scheduler memory operation and its error", - params=["hook_context", "operation", "target", "operation_input", "error"], + params=["hook_context", "operation", "operation_input", "error"], ) define_hook( diff --git a/tests/mem_scheduler/test_operation_observer.py b/tests/mem_scheduler/test_operation_observer.py index 6b4beaa5e..52c24a0a1 100644 --- a/tests/mem_scheduler/test_operation_observer.py +++ b/tests/mem_scheduler/test_operation_observer.py @@ -12,7 +12,8 @@ SchedulerOperationObserver, ) from memos.memories.textual.item import TextualMemoryItem, TreeNodeTextualMemoryMetadata -from memos.plugins.hook_defs import H +from memos.memories.textual.tree import TreeTextMemory +from memos.plugins.hook_defs import H, get_hook_spec from memos.plugins.hooks import register_hook @@ -24,7 +25,6 @@ OPERATION_SOURCE = { "fine": "fine_transfer_simple_mem", "add": "add_enhanced_memories", - "archive": "archive_merged_memories", "delete": "remove_memories", "soft_delete": "remove_memories", } @@ -58,12 +58,14 @@ def _mem_read_dependencies(memory_version_switch): reader.memory_version_switch = memory_version_switch text_memory = MagicMock() + text_memory.__class__ = TreeTextMemory text_memory.get.return_value = raw_memory text_memory.add.return_value = [ENHANCED_MEMORY_ID] text_memory.memory_manager.reorganizer.is_reorganize = False scheduler_context = MagicMock() scheduler_context.get_mem_reader.return_value = reader + scheduler_context.get_mem_cube.return_value.text_mem = text_memory scheduler_context.services.create_event_log.return_value = MagicMock() message = ScheduleMessageItem( @@ -104,7 +106,7 @@ def replace_result(*, operation, result, **_kwargs): mem_cube_id="cube-1", text_mem=text_memory, user_name="cube-1", - operation_context=message, + operation_context=message.model_dump(), ) text_memory.add.assert_called_once_with([replacement], user_name="cube-1") @@ -124,7 +126,6 @@ def replace_result(**kwargs): with SchedulerOperationObserver( source="scheduler.mem_read.add_enhanced_memories", operation="add", - target="textual_memory", operation_context={"trace_id": "trace-1", "task_id": "task-1"}, operation_input={"memory_ids": ["memory-1"]}, ) as observer: @@ -132,7 +133,7 @@ def replace_result(**kwargs): assert observer.value == ["plugin-result"] assert captured["operation"] == "add" - assert captured["target"] == "textual_memory" + assert set(captured) == set(get_hook_spec(H.SCHEDULER_MEMORY_OPERATION_AFTER).params) assert captured["operation_input"] == {"memory_ids": ["memory-1"]} assert captured["result"] == ["stored-1"] assert captured["hook_context"].source == "scheduler.mem_read.add_enhanced_memories" @@ -152,7 +153,6 @@ def test_scheduler_observer_reports_failure_and_preserves_error(): observer = SchedulerOperationObserver( source="scheduler.mem_read.fine_transfer_simple_mem", operation="fine", - target="textual_memory", operation_context={"trace_id": "trace-1", "mem_cube_id": "cube-1"}, operation_input={"memory_ids": ["memory-1"]}, capture_failure=True, @@ -165,22 +165,29 @@ def test_scheduler_observer_reports_failure_and_preserves_error(): assert [stage for stage, _kwargs in events] == ["failed"] failure = events[0][1] assert failure["error"] is error + assert set(failure) == set(get_hook_spec(H.SCHEDULER_MEMORY_OPERATION_FAILED).params) assert failure["hook_context"].cube_ids == ("cube-1",) @pytest.mark.parametrize( ("memory_version_switch", "expected_operations"), [ - ("off", ["fine", "add", "archive", "delete"]), + ("off", ["fine", "add", "delete"]), ("on", ["fine", "add", "soft_delete"]), ], ) +@pytest.mark.parametrize("task_id", ["task-1", None]) def test_mem_read_handler_exposes_each_memory_operation( memory_version_switch, expected_operations, + task_id, monkeypatch, ): handler, reader, text_memory, message = _mem_read_dependencies(memory_version_switch) + message.task_id = task_id + message.redis_message_id = "synthetic-redis-id" + message.info = {"custom_tags": ["synthetic-tag"], "is_upload_skill": True} + message.chat_history = [{"role": "user", "content": "synthetic history"}] events = [] monkeypatch.setattr( "memos.mem_scheduler.task_schedule_modules.handlers.mem_read_handler.is_playground_api", @@ -193,15 +200,7 @@ def record_operation(**kwargs): register_hook(H.SCHEDULER_MEMORY_OPERATION_AFTER, record_operation) - handler._process_memories_with_reader( - mem_ids=[RAW_MEMORY_ID], - user_id="alice", - mem_cube_id="cube-1", - text_mem=text_memory, - user_name="cube-1", - task_id="task-1", - operation_context=message, - ) + handler.process_message(message) assert [event["operation"] for event in events] == expected_operations assert [event["hook_context"].source for event in events] == [ @@ -209,24 +208,34 @@ def record_operation(**kwargs): ] for event in events: context = event["hook_context"] - assert event["target"] == "textual_memory" assert context.trace_id == "trace-1" assert context.user_id == "alice" assert context.session_id == "session-1" - assert context.task_id == "task-1" + assert context.task_id == task_id assert context.cube_ids == ("cube-1",) - assert context.attributes["scheduler_item_id"] == SCHEDULER_ITEM_ID - assert context.attributes["label"] == "mem_read" + assert context.attributes == {"scheduler_item_id": SCHEDULER_ITEM_ID, "label": "mem_read"} inputs = {event["operation"]: event["operation_input"] for event in events} assert inputs["fine"]["memories"][0].id == RAW_MEMORY_ID assert inputs["fine"]["type"] == "chat" + fine_input = inputs["fine"] + reader.fine_transfer_simple_mem.assert_called_once_with( + fine_input["memories"], + type=fine_input["type"], + custom_tags=fine_input["custom_tags"], + user_name=fine_input["user_name"], + chat_history=fine_input["chat_history"], + user_context=fine_input["user_context"], + is_upload_skill=fine_input["is_upload_skill"], + ) + assert fine_input["custom_tags"] == ["synthetic-tag"] + assert fine_input["chat_history"] == message.chat_history + assert fine_input["is_upload_skill"] is True assert inputs["add"]["memories"][0].id == ENHANCED_MEMORY_ID assert inputs["add"]["user_name"] == "cube-1" if memory_version_switch == "off": - assert inputs["archive"] == {"memory_ids": [RAW_MEMORY_ID]} - assert inputs["delete"] == {"memory_ids": [RAW_MEMORY_ID]} + assert inputs["delete"] == {"memory_ids": [RAW_MEMORY_ID], "user_name": "cube-1"} reader.graph_db.update_node.assert_called_once_with( RAW_MEMORY_ID, {"status": "archived"}, @@ -237,6 +246,7 @@ def record_operation(**kwargs): else: assert inputs["soft_delete"] == { "memory_ids": [RAW_MEMORY_ID], + "user_name": "cube-1", "preserved_memory_ids": [ENHANCED_MEMORY_ID], } reader.graph_db.update_node.assert_not_called() From 30b0ec9493f3bdb77b929292494c665730f5514f Mon Sep 17 00:00:00 2001 From: qzs Date: Wed, 21 Oct 2026 14:47:53 +0800 Subject: [PATCH 8/9] refactor(hooks): simplify search hook context --- src/memos/api/handlers/search_handler.py | 16 ++---- src/memos/plugins/HOOKS.md | 9 +-- src/memos/plugins/hooks.py | 9 ++- tests/api/test_search_hook_context.py | 70 ++++++++++++++++++++++-- tests/plugins/test_hook_context.py | 23 ++++++++ 5 files changed, 102 insertions(+), 25 deletions(-) diff --git a/src/memos/api/handlers/search_handler.py b/src/memos/api/handlers/search_handler.py index a94318a7e..392c2b601 100644 --- a/src/memos/api/handlers/search_handler.py +++ b/src/memos/api/handlers/search_handler.py @@ -74,8 +74,6 @@ def __init__(self, dependencies: HandlerDependencies): def handle_search_memories( self, search_req: APISearchRequest, - *, - hook_context: HookContext | None = None, ) -> SearchResponse: """ Main handler for search memories endpoint. @@ -85,8 +83,6 @@ def handle_search_memories( Args: search_req: Search request containing query and parameters - hook_context: Internal correlation context shared by all Hooks for - this search operation. A context is created when omitted. Returns: SearchResponse with formatted results @@ -108,7 +104,7 @@ def handle_search_memories( results = cube_view.search_memories(search_req_local) hooked_results = trigger_hook( H.SEARCH_MEMORY_RESULTS, - hook_context=hook_context, + hook_context=self._build_search_hook_context(search_req_local), handler=self, search_req=search_req_local, results=results, @@ -122,7 +118,7 @@ def handle_search_memories( results = self._apply_relativity_threshold(results, search_req_local.relativity) hooked_results = trigger_hook( H.SEARCH_RESULTS_AFTER_THRESHOLD, - hook_context=hook_context, + hook_context=self._build_search_hook_context(search_req_local), handler=self, search_req=search_req_local, results=results, @@ -139,7 +135,7 @@ def handle_search_memories( self._strip_embeddings(results) hooked_results = trigger_hook( H.SEARCH_RESULTS_AFTER_DEDUP, - hook_context=hook_context, + hook_context=self._build_search_hook_context(search_req_local), handler=self, search_req=search_req_local, results=results, @@ -157,7 +153,7 @@ def handle_search_memories( ) hooked_results = trigger_hook( H.SEARCH_RESULTS_AFTER_RERANK, - hook_context=hook_context, + hook_context=self._build_search_hook_context(search_req_local), handler=self, search_req=search_req_local, results=results, @@ -167,7 +163,7 @@ def handle_search_memories( except Exception as error: trigger_hook( H.SEARCH_POST_PROCESS_FAILED, - hook_context=hook_context, + hook_context=self._build_search_hook_context(search_req_local), handler=self, search_req=search_req_local, error=error, @@ -176,7 +172,7 @@ def handle_search_memories( hooked_results = trigger_hook( H.SEARCH_CONTEXT_RENDER, - hook_context=hook_context, + hook_context=self._build_search_hook_context(search_req_local), handler=self, search_req=search_req_local, results=results, diff --git a/src/memos/plugins/HOOKS.md b/src/memos/plugins/HOOKS.md index 6a3276507..e2895e14d 100644 --- a/src/memos/plugins/HOOKS.md +++ b/src/memos/plugins/HOOKS.md @@ -85,11 +85,10 @@ Hooks that do **not** provide context will never pass it, even if you declare th ### Context scope -- All hooks in one **search** invocation share the same context object. It is built before - `search.before`, so replacing the request does not rebuild the context. Use the callback's - `request` argument for the current business input. +- **Search** builds a context for `search.before` and `search.after`. Each intermediate + hook creates its own context. - **Reader extraction**, **cube writes**, and **scheduler operations** each create a separate - context. Do not assume they share an `operation_id`; use `trace_id` or `task_id` for + context. Use `trace_id` or `task_id` for broader correlation. --- @@ -110,8 +109,6 @@ search.before └─► search.after ``` -Every hook receives `hook_context`. Context source: `api.search`; attributes contain `mode`. - | Constant / Hook name | Additional arguments | `pipe_key` | Typical use | | --- | --- | --- | --- | | `H.SEARCH_BEFORE` / `search.before` | `request` | `request` | Rewrite the query or inject filters before retrieval. | diff --git a/src/memos/plugins/hooks.py b/src/memos/plugins/hooks.py index 084f0b66b..f3dc6a67d 100644 --- a/src/memos/plugins/hooks.py +++ b/src/memos/plugins/hooks.py @@ -148,7 +148,8 @@ def hookable( Auto-declares before/after Hooks (idempotent); no need to manually define_hook in hook_defs.py. Supports piped return values: before can modify request, after can modify result. When ``context_builder`` is provided, one context is built before the first - Hook and passed to both Hooks and the decorated method as ``hook_context``. + Hook and passed to both Hooks as ``hook_context``. It is also passed to the + decorated method when that method accepts it. Compatible with both sync and async methods. """ from memos.plugins.hook_defs import define_hook @@ -184,7 +185,8 @@ async def async_wrapper(self, request, *args, **kwargs): call_kwargs = dict(kwargs) if context_builder is not None: before_kwargs["hook_context"] = hook_context - call_kwargs["hook_context"] = hook_context + if _accepts_hook_context(func): + call_kwargs["hook_context"] = hook_context rv = trigger_hook(f"{name}.before", **before_kwargs) request = rv if rv is not None else request @@ -207,7 +209,8 @@ def sync_wrapper(self, request, *args, **kwargs): call_kwargs = dict(kwargs) if context_builder is not None: before_kwargs["hook_context"] = hook_context - call_kwargs["hook_context"] = hook_context + if _accepts_hook_context(func): + call_kwargs["hook_context"] = hook_context rv = trigger_hook(f"{name}.before", **before_kwargs) request = rv if rv is not None else request diff --git a/tests/api/test_search_hook_context.py b/tests/api/test_search_hook_context.py index a5d39b3e8..3a7df0698 100644 --- a/tests/api/test_search_hook_context.py +++ b/tests/api/test_search_hook_context.py @@ -1,3 +1,5 @@ +import inspect + import pytest from memos.api.handlers.base_handler import HandlerDependencies @@ -47,7 +49,7 @@ def _search_handler() -> tuple[SearchHandler, _CubeView]: return handler, cube_view -def test_search_success_hooks_run_in_order_and_share_context(monkeypatch): +def test_search_success_hooks_run_in_order_with_distinct_stage_operations(monkeypatch): events = [] result_hook_calls = [] handler, cube_view = _search_handler() @@ -97,7 +99,8 @@ def replace_response(*, hook_context, result, **_kwargs): H.SEARCH_AFTER, ] contexts = [context for _name, context in events] - assert all(context is contexts[0] for context in contexts) + assert contexts[-1] is contexts[0] + assert len({context.operation_id for context in contexts}) == 6 context = contexts[0] assert isinstance(context, HookContext) assert context.trace_id == "trace-1" @@ -107,6 +110,13 @@ def replace_response(*, hook_context, result, **_kwargs): assert context.source == "api.search" assert context.attributes == {"mode": "fast"} assert context.operation_id + for stage_context in contexts[1:-1]: + assert stage_context.source == "api.search" + assert stage_context.operation_id != context.operation_id + assert stage_context.attributes == {"mode": "fast"} + assert stage_context.attributes is not context.attributes + for field in ("trace_id", "user_id", "session_id", "task_id", "cube_ids"): + assert getattr(stage_context, field) == getattr(context, field) assert cube_view.request.query == "hooked query" assert all(call["handler"] is handler for call in result_hook_calls) assert all(call["search_req"] is cube_view.request for call in result_hook_calls) @@ -143,23 +153,42 @@ def replace_memories(*, results, **_kwargs): assert response.data["text_mem"][0]["memories"] == [memory] -def test_search_post_processing_failure_triggers_only_failure_hook(monkeypatch): +@pytest.mark.parametrize("failed_stage", ["threshold", "dedup", "rerank"]) +def test_search_post_processing_failure_identifies_the_failed_operation(monkeypatch, failed_stage): error = RuntimeError("post processing failed") events = [] handler, _cube_view = _search_handler() - search_req = APISearchRequest(user_id="user", query="query") + search_req = APISearchRequest(user_id="user", query="query", dedup="sim") + observed_contexts = [] + register_hook( + H.SEARCH_BEFORE, lambda **kwargs: observed_contexts.append(kwargs["hook_context"]) + ) + for name in ( + H.SEARCH_MEMORY_RESULTS, + H.SEARCH_RESULTS_AFTER_THRESHOLD, + H.SEARCH_RESULTS_AFTER_DEDUP, + H.SEARCH_RESULTS_AFTER_RERANK, + ): + register_hook(name, lambda **kwargs: observed_contexts.append(kwargs["hook_context"])) monkeypatch.setattr( "memos.api.handlers.search_handler.get_current_trace_id", lambda: "trace-1", ) - def fail_post_processing(_results, _relativity): + def fail_post_processing(*_args, **_kwargs): raise error def record_failure(**kwargs): events.append((H.SEARCH_POST_PROCESS_FAILED, kwargs)) - handler._apply_relativity_threshold = fail_post_processing + if failed_stage == "threshold": + handler._apply_relativity_threshold = fail_post_processing + elif failed_stage == "dedup": + handler._dedup_text_memories = fail_post_processing + else: + monkeypatch.setattr( + "memos.api.handlers.search_handler.rerank_knowledge_mem", fail_post_processing + ) register_hook(H.SEARCH_POST_PROCESS_FAILED, record_failure) register_hook(H.SEARCH_CONTEXT_RENDER, lambda **_kwargs: events.append(("render", {}))) register_hook(H.SEARCH_AFTER, lambda **_kwargs: events.append(("after", {}))) @@ -176,3 +205,32 @@ def record_failure(**kwargs): context = failure["hook_context"] assert context.trace_id == "trace-1" assert context.user_id == "user" + assert context.source == "api.search" + assert context.attributes == {"mode": "fast"} + assert context.operation_id not in {prior.operation_id for prior in observed_contexts} + + +def test_search_handler_does_not_accept_hook_context(): + assert list(inspect.signature(SearchHandler.handle_search_memories).parameters) == [ + "self", + "search_req", + ] + + +def test_search_stage_operations_stay_isolated_between_searches_in_one_trace(monkeypatch): + handler, _cube_view = _search_handler() + monkeypatch.setattr( + "memos.api.handlers.search_handler.get_current_trace_id", lambda: "one-trace" + ) + contexts = [] + for name in ( + H.SEARCH_BEFORE, + H.SEARCH_RESULTS_AFTER_THRESHOLD, + H.SEARCH_RESULTS_AFTER_DEDUP, + H.SEARCH_RESULTS_AFTER_RERANK, + ): + register_hook(name, lambda **kwargs: contexts.append(kwargs["hook_context"])) + for query in ("first", "second"): + handler.handle_search_memories(APISearchRequest(user_id="user", query=query)) + assert len({context.operation_id for context in contexts}) == 8 + assert all(context.attributes == {"mode": "fast"} for context in contexts) diff --git a/tests/plugins/test_hook_context.py b/tests/plugins/test_hook_context.py index ad06e2f98..453c80fd2 100644 --- a/tests/plugins/test_hook_context.py +++ b/tests/plugins/test_hook_context.py @@ -186,3 +186,26 @@ def callback(*, hook_context, **_kwargs): ("operation", supplied_context), ("after", supplied_context), ] + + +@pytest.mark.parametrize("is_async", [False, True]) +def test_hookable_supports_method_without_context_parameter(is_async): + context = build_hook_context(source="test") + observed = [] + + async def async_run(self, request): + return request + + def sync_run(self, request): + return request + + class Handler: + run = hookable("without_context", context_builder=lambda _self, _request: context)( + async_run if is_async else sync_run + ) + + for name in ("without_context.before", "without_context.after"): + register_hook(name, lambda **kwargs: observed.append(kwargs["hook_context"])) + result = Handler().run("request") + assert (asyncio.run(result) if is_async else result) == "request" + assert observed == [context, context] From a33c8b0e8ed0b129061f74a43246b5e25380529a Mon Sep 17 00:00:00 2001 From: qzs Date: Tue, 17 Nov 2026 17:41:03 +0800 Subject: [PATCH 9/9] fix(plugins): handle hook context arguments and cache signatures --- .../handlers/mem_read_handler.py | 10 +- src/memos/plugins/HOOKS.md | 5 + src/memos/plugins/hooks.py | 61 ++++++--- tests/conftest.py | 8 +- .../mem_scheduler/test_operation_observer.py | 7 + tests/plugins/test_hook_context.py | 126 +++++++++++++++++- tests/test_hook_fixture.py | 24 ++++ 7 files changed, 211 insertions(+), 30 deletions(-) create mode 100644 tests/test_hook_fixture.py diff --git a/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py b/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py index 9a4a93a2b..9c6528791 100644 --- a/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py +++ b/src/memos/mem_scheduler/task_schedule_modules/handlers/mem_read_handler.py @@ -96,7 +96,15 @@ def process_message(self, message: ScheduleMessageItem): info=info, chat_history=chat_history, user_context=user_context, - operation_context=message.model_dump(), + operation_context={ + "item_id": message.item_id, + "trace_id": message.trace_id, + "user_id": user_id, + "session_id": message.session_id, + "task_id": message.task_id, + "label": message.label, + "cube_id": mem_cube_id, + }, ) logger.info( diff --git a/src/memos/plugins/HOOKS.md b/src/memos/plugins/HOOKS.md index e2895e14d..773004b0c 100644 --- a/src/memos/plugins/HOOKS.md +++ b/src/memos/plugins/HOOKS.md @@ -83,6 +83,11 @@ def my_callback(self, results, **kwargs): The runtime omits `hook_context` when the callback's signature accepts neither form. Hooks that do **not** provide context will never pass it, even if you declare the parameter. +For `@hookable(..., context_builder=...)`, an explicit non-`None` context is reused, +including when passed positionally to the decorated method. An omitted or `None` +context is built automatically. Methods that do not accept `hook_context` receive +only their business arguments; their hooks still receive the context. + ### Context scope - **Search** builds a context for `search.before` and `search.after`. Each intermediate diff --git a/src/memos/plugins/hooks.py b/src/memos/plugins/hooks.py index f3dc6a67d..dffed92ce 100644 --- a/src/memos/plugins/hooks.py +++ b/src/memos/plugins/hooks.py @@ -17,7 +17,7 @@ logger = logging.getLogger(__name__) -_hooks: dict[str, list[Callable]] = defaultdict(list) +_hooks: dict[str, list[tuple[Callable, bool]]] = defaultdict(list) def _accepts_hook_context(callback: Callable) -> bool: @@ -41,7 +41,7 @@ def _accepts_hook_context(callback: Callable) -> bool: ) -def _invoke_hook_callback(callback: Callable, kwargs: dict[str, Any]) -> Any: +def _invoke_hook_callback(callback: Callable, accepts_context: bool, kwargs: dict[str, Any]) -> Any: """Invoke one callback while preserving legacy exact-signature Hooks. ``hook_context`` is additive framework metadata. Older callbacks that use @@ -49,7 +49,7 @@ def _invoke_hook_callback(callback: Callable, kwargs: dict[str, Any]) -> Any: arguments. Context-aware callbacks and callbacks with ``**kwargs`` receive the complete contract. """ - if "hook_context" not in kwargs or _accepts_hook_context(callback): + if "hook_context" not in kwargs or accepts_context: return callback(**kwargs) legacy_kwargs = dict(kwargs) @@ -67,7 +67,7 @@ def register_hook(name: str, callback: Callable) -> None: name, getattr(callback, "__qualname__", repr(callback)), ) - _hooks[name].append(callback) + _hooks[name].append((callback, _accepts_hook_context(callback))) logger.debug( "Hook registered: %s -> %s", name, @@ -84,7 +84,7 @@ def register_hooks(names: list[str], callback: Callable) -> None: def trigger_hook(name: str, **kwargs: Any) -> Any: """Trigger a hook, invoking all registered callbacks in order. - - Zero overhead when no callbacks are registered + - No callback inspection when triggering hooks - Undeclared hook names will log a warning and be skipped - pipe_key is auto-fetched from HookSpec, supports piped return value passing """ @@ -97,9 +97,9 @@ def trigger_hook(name: str, **kwargs: Any) -> Any: pipe_key = spec.pipe_key - for cb in _hooks.get(name, []): + for cb, accepts_context in _hooks.get(name, []): try: - rv = _invoke_hook_callback(cb, kwargs) + rv = _invoke_hook_callback(cb, accepts_context, kwargs) if pipe_key is not None and rv is not None: kwargs[pipe_key] = rv except Exception: @@ -126,9 +126,9 @@ def trigger_single_hook(name: str, **kwargs: Any) -> Any: if len(callbacks) > 1: raise RuntimeError(f"Multiple plugins registered single-provider hook: {name}") - cb = callbacks[0] + cb, accepts_context = callbacks[0] try: - return _invoke_hook_callback(cb, kwargs) + return _invoke_hook_callback(cb, accepts_context, kwargs) except Exception: logger.exception( "Single hook %s callback %s failed", @@ -174,19 +174,43 @@ def hookable( ) def decorator(func): + signature = inspect.signature(func) + accepts_context = _accepts_hook_context(func) + context_parameter = signature.parameters.get("hook_context") + if context_parameter is not None and context_parameter.kind in { + inspect.Parameter.VAR_POSITIONAL, + inspect.Parameter.VAR_KEYWORD, + }: + context_parameter = None + + def prepare_call(self, request, args, kwargs): + hook_context = kwargs.get("hook_context") + bound = None + if context_parameter is not None: + bound = signature.bind_partial(self, request, *args, **kwargs) + hook_context = bound.arguments.get("hook_context") + if hook_context is None and context_builder is not None: + hook_context = context_builder(self, request) + + call_kwargs = dict(kwargs) + if bound is not None and context_builder is not None: + bound.arguments["hook_context"] = hook_context + bound.apply_defaults() + args, call_kwargs = bound.args[2:], bound.kwargs + elif not accepts_context: + call_kwargs.pop("hook_context", None) + elif context_builder is not None: + call_kwargs["hook_context"] = hook_context + return hook_context, args, call_kwargs + if asyncio.iscoroutinefunction(func): @wraps(func) async def async_wrapper(self, request, *args, **kwargs): - hook_context = kwargs.get("hook_context") - if hook_context is None and context_builder is not None: - hook_context = context_builder(self, request) + hook_context, args, call_kwargs = prepare_call(self, request, args, kwargs) before_kwargs = {"request": request} - call_kwargs = dict(kwargs) if context_builder is not None: before_kwargs["hook_context"] = hook_context - if _accepts_hook_context(func): - call_kwargs["hook_context"] = hook_context rv = trigger_hook(f"{name}.before", **before_kwargs) request = rv if rv is not None else request @@ -202,15 +226,10 @@ async def async_wrapper(self, request, *args, **kwargs): @wraps(func) def sync_wrapper(self, request, *args, **kwargs): - hook_context = kwargs.get("hook_context") - if hook_context is None and context_builder is not None: - hook_context = context_builder(self, request) + hook_context, args, call_kwargs = prepare_call(self, request, args, kwargs) before_kwargs = {"request": request} - call_kwargs = dict(kwargs) if context_builder is not None: before_kwargs["hook_context"] = hook_context - if _accepts_hook_context(func): - call_kwargs["hook_context"] = hook_context rv = trigger_hook(f"{name}.before", **before_kwargs) request = rv if rv is not None else request diff --git a/tests/conftest.py b/tests/conftest.py index 509111b2b..032a90087 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -6,6 +6,10 @@ def clean_hooks(): """Keep Hook registrations isolated for tests that opt into this fixture.""" from memos.plugins.hooks import _hooks + saved = {name: list(callbacks) for name, callbacks in _hooks.items()} _hooks.clear() - yield - _hooks.clear() + try: + yield + finally: + _hooks.clear() + _hooks.update(saved) diff --git a/tests/mem_scheduler/test_operation_observer.py b/tests/mem_scheduler/test_operation_observer.py index 52c24a0a1..1d0fa8d97 100644 --- a/tests/mem_scheduler/test_operation_observer.py +++ b/tests/mem_scheduler/test_operation_observer.py @@ -188,6 +188,13 @@ def test_mem_read_handler_exposes_each_memory_operation( message.redis_message_id = "synthetic-redis-id" message.info = {"custom_tags": ["synthetic-tag"], "is_upload_skill": True} message.chat_history = [{"role": "user", "content": "synthetic history"}] + monkeypatch.setattr( + ScheduleMessageItem, + "model_dump", + MagicMock( + side_effect=AssertionError("Correlation metadata must not dump message payloads") + ), + ) events = [] monkeypatch.setattr( "memos.mem_scheduler.task_schedule_modules.handlers.mem_read_handler.is_playground_api", diff --git a/tests/plugins/test_hook_context.py b/tests/plugins/test_hook_context.py index 453c80fd2..69198cb62 100644 --- a/tests/plugins/test_hook_context.py +++ b/tests/plugins/test_hook_context.py @@ -4,6 +4,7 @@ import pytest +from memos.plugins import hooks from memos.plugins.hook_context import build_hook_context from memos.plugins.hook_defs import H, define_hook, get_hook_spec from memos.plugins.hooks import hookable, register_hook, trigger_hook, trigger_single_hook @@ -189,8 +190,11 @@ def callback(*, hook_context, **_kwargs): @pytest.mark.parametrize("is_async", [False, True]) -def test_hookable_supports_method_without_context_parameter(is_async): +@pytest.mark.parametrize("with_builder", [False, True]) +@pytest.mark.parametrize("supplied", ["omitted", "keyword", "none"]) +def test_hookable_supports_method_without_context_parameter(is_async, with_builder, supplied): context = build_hook_context(source="test") + supplied_context = object() observed = [] async def async_run(self, request): @@ -200,12 +204,122 @@ def sync_run(self, request): return request class Handler: - run = hookable("without_context", context_builder=lambda _self, _request: context)( - async_run if is_async else sync_run - ) + run = hookable( + "without_context", + context_builder=(lambda _self, _request: context) if with_builder else None, + )(async_run if is_async else sync_run) for name in ("without_context.before", "without_context.after"): + register_hook(name, lambda **kwargs: observed.append(kwargs.get("hook_context"))) + kwargs = ( + {} + if supplied == "omitted" + else {"hook_context": supplied_context if supplied == "keyword" else None} + ) + result = Handler().run("request", **kwargs) + assert (asyncio.run(result) if is_async else result) == "request" + expected = (supplied_context if supplied == "keyword" else context) if with_builder else None + assert observed == [expected, expected] + + +@pytest.mark.parametrize("is_async", [False, True]) +@pytest.mark.parametrize("positional_only", [False, True]) +@pytest.mark.parametrize("supplied", ["positional", "none", "omitted"]) +def test_hookable_reuses_positional_context(is_async, positional_only, supplied): + built_context = object() + supplied_context = object() + observed = [] + + def run(self, request, marker="marker", hook_context=None): + return request, marker, hook_context + + def positional_run(self, request, marker="marker", hook_context=None, /): + return request, marker, hook_context + + async def async_run(self, request, marker="marker", hook_context=None): + return request, marker, hook_context + + async def async_positional_run(self, request, marker="marker", hook_context=None, /): + return request, marker, hook_context + + operation = positional_run if positional_only else run + if is_async: + operation = async_positional_run if positional_only else async_run + + class Handler: + run = hookable("positional_context", context_builder=lambda *_: built_context)(operation) + + for name in ("positional_context.before", "positional_context.after"): register_hook(name, lambda **kwargs: observed.append(kwargs["hook_context"])) + args = ( + () + if supplied == "omitted" + else ("marker", supplied_context if supplied == "positional" else None) + ) + result = Handler().run("request", *args) + expected = supplied_context if supplied == "positional" else built_context + assert (asyncio.run(result) if is_async else result) == ("request", "marker", expected) + assert observed == [expected, expected] + + +@pytest.mark.parametrize("is_async", [False, True]) +def test_hook_signatures_are_inspected_only_during_setup(monkeypatch, is_async): + context = object() + calls = [] + + class LegacyCallback: + __hash__ = None + + def __call__(self, *, request): + calls.append(request) + return request + + def sync_run(self, request, *, hook_context=None): + return hook_context + + async def async_run(self, request, *, hook_context=None): + return hook_context + + class Handler: + run = hookable("cached_context", context_builder=lambda *_: context)( + async_run if is_async else sync_run + ) + + register_hook("cached_context.before", LegacyCallback()) + register_hook("cached_context.after", lambda **kwargs: kwargs["result"]) + define_hook("cached_single", description="Signature caching", params=["request"]) + register_hook("cached_single", LegacyCallback()) + + def unexpected_inspection(*_args, **_kwargs): + pytest.fail("Hook invocation must not inspect callback signatures") + + monkeypatch.setattr(hooks.inspect, "signature", unexpected_inspection) + for _ in range(2): + result = Handler().run("request") + assert (asyncio.run(result) if is_async else result) is context + assert ( + trigger_single_hook("cached_single", request="single", hook_context=context) == "single" + ) + assert calls == ["request", "single", "request", "single"] + hooks._hooks.clear() + result = Handler().run("without callbacks") + assert (asyncio.run(result) if is_async else result) is context + + +@pytest.mark.parametrize("is_async", [False, True]) +def test_hookable_builds_required_context_parameter(is_async): + context = object() + + def sync_run(self, request, *, hook_context): + return hook_context + + async def async_run(self, request, *, hook_context): + return hook_context + + class Handler: + run = hookable("required_context", context_builder=lambda *_: context)( + async_run if is_async else sync_run + ) + result = Handler().run("request") - assert (asyncio.run(result) if is_async else result) == "request" - assert observed == [context, context] + assert (asyncio.run(result) if is_async else result) is context diff --git a/tests/test_hook_fixture.py b/tests/test_hook_fixture.py new file mode 100644 index 000000000..e04a8faeb --- /dev/null +++ b/tests/test_hook_fixture.py @@ -0,0 +1,24 @@ +import pytest + +from memos.plugins.hook_defs import define_hook +from memos.plugins.hooks import _hooks, register_hook + + +@pytest.fixture +def existing_hooks(): + saved = {name: list(callbacks) for name, callbacks in _hooks.items()} + define_hook("fixture.existing", description="Existing registration", params=[]) + register_hook("fixture.existing", lambda: None) + expected = {name: list(callbacks) for name, callbacks in _hooks.items()} + try: + yield + assert dict(_hooks) == expected + finally: + _hooks.clear() + _hooks.update(saved) + + +def test_clean_hooks_restores_existing_registrations(existing_hooks, request): + request.getfixturevalue("clean_hooks") + assert not _hooks + register_hook("fixture.existing", lambda: None)