diff --git a/src/memos/api/handlers/search_handler.py b/src/memos/api/handlers/search_handler.py index 363e0b253..392c2b601 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,14 @@ 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, + ) -> SearchResponse: """ Main handler for search memories endpoint. @@ -96,44 +104,75 @@ def handle_search_memories(self, search_req: APISearchRequest) -> SearchResponse results = cube_view.search_memories(search_req_local) hooked_results = trigger_hook( H.SEARCH_MEMORY_RESULTS, + hook_context=self._build_search_hook_context(search_req_local), 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=self._build_search_hook_context(search_req_local), + 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=self._build_search_hook_context(search_req_local), + 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=self._build_search_hook_context(search_req_local), + 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=self._build_search_hook_context(search_req_local), + handler=self, + search_req=search_req_local, + error=error, + ) + raise hooked_results = trigger_hook( H.SEARCH_CONTEXT_RENDER, + hook_context=self._build_search_hook_context(search_req_local), handler=self, search_req=search_req_local, results=results, @@ -1036,6 +1075,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..4db01d90f 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,28 +539,57 @@ 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 ) -> list[TextualMemoryItem]: @@ -756,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 @@ -767,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()) 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..67c39aa0f 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,25 @@ 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, + operation_context: dict[str, 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, + 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 5e663c99e..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 @@ -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,15 @@ def process_message(self, message: ScheduleMessageItem): info=info, chat_history=chat_history, user_context=user_context, + 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( @@ -119,6 +128,7 @@ def _process_memories_with_reader( info: dict | None = None, chat_history: list | None = None, user_context: UserContext | 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", @@ -127,6 +137,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 +185,34 @@ 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", + 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, + ) 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, exc_info=True) return @@ -195,7 +230,15 @@ 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", + 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), @@ -403,7 +446,14 @@ 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", + operation_context=operation_context, + 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)) logger.info( "Delete raw/working mem_ids: %s for user_name: %s", delete_ids, @@ -416,15 +466,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", + operation_context=operation_context, + operation_input={ + "memory_ids": delete_ids, + "user_name": user_name, + "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, @@ -512,3 +576,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" 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..89a737663 --- /dev/null +++ b/src/memos/mem_scheduler/task_schedule_modules/operation_observer.py @@ -0,0 +1,103 @@ +from __future__ import annotations + +from contextlib import AbstractContextManager +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() + + +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, + operation_context: dict[str, Any], + operation_input: Mapping[str, Any], + capture_failure: bool = False, + ) -> None: + self._hook_kwargs = { + "operation": operation, + "operation_input": dict(operation_input), + } + cube_id = operation_context.get("cube_id") or operation_context.get("mem_cube_id") + self._hook_context = build_hook_context( + 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), + ) + 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 _attributes(operation_context: dict[str, Any]) -> dict[str, Any]: + attributes = { + "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/multi_mem_cube/single_cube.py b/src/memos/multi_mem_cube/single_cube.py index 0b9829b7f..6f71b0f5d 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 ( @@ -671,6 +675,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, @@ -744,10 +774,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/HOOKS.md b/src/memos/plugins/HOOKS.md new file mode 100644 index 000000000..773004b0c --- /dev/null +++ b/src/memos/plugins/HOOKS.md @@ -0,0 +1,243 @@ +# 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 three 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 | + +--- + +## 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. + +--- + +## 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. + +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 + hook creates its own context. +- **Reader extraction**, **cube writes**, and **scheduler operations** each create a separate + context. 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 +``` + +| 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`, and `operation_input`. + +```text +SchedulerOperationObserver + └─► operation (fine | add | 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` | — | + +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`, `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. | | +| `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. +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 c9b6a0c29..aecb11890 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,28 +265,82 @@ 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 # 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 # threshold / dedup / rerank exception escaped + +# MemReader extraction 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 ``` -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. + +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 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..90b6052a2 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,6 +95,18 @@ 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 — memory 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) @@ -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 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", "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", "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..dffed92ce 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 @@ -16,7 +17,44 @@ 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: + """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, 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 + 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_context: + return callback(**kwargs) + + legacy_kwargs = dict(kwargs) + legacy_kwargs.pop("hook_context") + return callback(**legacy_kwargs) def register_hook(name: str, callback: Callable) -> None: @@ -29,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, @@ -46,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 """ @@ -59,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 = 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: @@ -88,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 cb(**kwargs) + return _invoke_hook_callback(cb, accepts_context, kwargs) except Exception: logger.exception( "Single hook %s callback %s failed", @@ -100,37 +138,87 @@ 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 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 + 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", ) 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): - rv = trigger_hook(f"{name}.before", request=request) + hook_context, args, call_kwargs = prepare_call(self, request, args, kwargs) + before_kwargs = {"request": request} + if context_builder is not None: + before_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 +226,18 @@ 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, args, call_kwargs = prepare_call(self, request, args, kwargs) + before_kwargs = {"request": request} + if context_builder is not None: + before_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_hook_context.py b/tests/api/test_search_hook_context.py new file mode 100644 index 000000000..3a7df0698 --- /dev/null +++ b/tests/api/test_search_hook_context.py @@ -0,0 +1,236 @@ +import inspect + +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_with_distinct_stage_operations(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 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" + 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 + 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) + 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] + + +@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", 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(*_args, **_kwargs): + raise error + + def record_failure(**kwargs): + events.append((H.SEARCH_POST_PROCESS_FAILED, kwargs)) + + 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", {}))) + + 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" + 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/api/test_search_pipeline_hooks.py b/tests/api/test_search_pipeline_hooks.py index befff6b80..bfdad25a0 100644 --- a/tests/api/test_search_pipeline_hooks.py +++ b/tests/api/test_search_pipeline_hooks.py @@ -43,11 +43,11 @@ def test_search_pipeline_hook_specs_are_registered(): assert after_rerank is not None assert after_rerank.pipe_key == "results" - assert after_rerank.params == ["handler", "search_req", "results"] + assert after_rerank.params == ["hook_context", "handler", "search_req", "results"] assert render is not None assert render.pipe_key == "results" - assert render.params == ["handler", "search_req", "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..032a90087 --- /dev/null +++ b/tests/conftest.py @@ -0,0 +1,15 @@ +import pytest + + +@pytest.fixture +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() + try: + yield + finally: + _hooks.clear() + _hooks.update(saved) 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 new file mode 100644 index 000000000..d912f0ab2 --- /dev/null +++ b/tests/mem_reader/test_hook_pipeline.py @@ -0,0 +1,93 @@ +"""MemReader Hook contracts at the extraction boundary.""" + +from types import MethodType + +import pytest + +from memos.mem_reader.simple_struct import SimpleStructMemReader +from memos.plugins.hook_defs import H +from memos.plugins.hooks import register_hook + + +pytestmark = pytest.mark.usefixtures("clean_hooks") + + +def test_extract_after_hook_receives_operation_and_can_replace_result(monkeypatch): + reader = object.__new__(SimpleStructMemReader) + original_result = [["original"]] + plugin_result = [["plugin"]] + scene_data = [{"role": "user", "content": "remember this"}] + info = {"user_id": "alice", "session_id": "session-1"} + captured = {} + + 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, replace_result) + + result = reader.get_memory( + scene_data, + type="chat", + info=info, + mode="fine", + user_name="cube-1", + chat_history=[], + ) + + context = captured.pop("hook_context") + 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 captured == { + "mem_reader": reader, + "scene_data": scene_data, + "type": "chat", + "info": info, + "mode": "fine", + "user_name": "cube-1", + "kwargs": {"chat_history": []}, + "result": original_result, + } + + +def test_extract_failure_hook_reports_and_preserves_original_error(monkeypatch): + reader = object.__new__(SimpleStructMemReader) + error = ValueError("reader failed") + events = [] + + def fake_read_memory(self, *_args, **_kwargs): + raise error + + 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, 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"}, + user_name="cube-1", + ) + + assert exc_info.value is error + 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 new file mode 100644 index 000000000..1d0fa8d97 --- /dev/null +++ b/tests/mem_scheduler/test_operation_observer.py @@ -0,0 +1,265 @@ +"""Scheduler Hook contracts and their MemRead integration points.""" + +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.memories.textual.item import TextualMemoryItem, TreeNodeTextualMemoryMetadata +from memos.memories.textual.tree import TreeTextMemory +from memos.plugins.hook_defs import H, get_hook_spec +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", + "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 {}, + ), + ) + + +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.__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( + 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_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.model_dump(), + ) + + 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", + operation_context={"trace_id": "trace-1", "task_id": "task-1"}, + operation_input={"memory_ids": ["memory-1"]}, + ) as observer: + observer.result(["stored-1"]) + + assert observer.value == ["plugin-result"] + assert captured["operation"] == "add" + 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" + + +def test_scheduler_observer_reports_failure_and_preserves_error(): + error = ValueError("scheduler operation failed") + events = [] + register_hook( + H.SCHEDULER_MEMORY_OPERATION_FAILED, + lambda **kwargs: events.append(("failed", kwargs)), + ) + register_hook( + H.SCHEDULER_MEMORY_OPERATION_AFTER, + lambda **kwargs: events.append(("after", kwargs)), + ) + observer = SchedulerOperationObserver( + source="scheduler.mem_read.fine_transfer_simple_mem", + operation="fine", + operation_context={"trace_id": "trace-1", "mem_cube_id": "cube-1"}, + 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 [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", "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"}] + 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", + lambda: False, + ) + + def record_operation(**kwargs): + events.append(kwargs) + return kwargs["result"] + + register_hook(H.SCHEDULER_MEMORY_OPERATION_AFTER, record_operation) + + handler.process_message(message) + + 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 context.trace_id == "trace-1" + assert context.user_id == "alice" + assert context.session_id == "session-1" + assert context.task_id == task_id + assert context.cube_ids == ("cube-1",) + 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["delete"] == {"memory_ids": [RAW_MEMORY_ID], "user_name": "cube-1"} + 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], + "user_name": "cube-1", + "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 new file mode 100644 index 000000000..f639bec8e --- /dev/null +++ b/tests/multi_mem_cube/test_single_cube_hooks.py @@ -0,0 +1,154 @@ +"""Textual Memory Hook behavior at the SingleCubeView write boundary.""" + +from __future__ import annotations + +import logging + +from importlib import import_module +from unittest.mock import MagicMock + +import pytest + +from memos.plugins.hook_defs import H +from memos.plugins.hooks import register_hook + + +pytestmark = pytest.mark.usefixtures("clean_hooks") + + +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="00000000-0000-0000-0000-000000000001", + 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_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"] + + 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.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") + 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 record(stage): + def callback(**kwargs): + events.append((stage, 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( + _make_add_request( + async_mode="async", + session_id="session-1", + task_id="task-1", + ) + ) + + assert exc_info.value is error + assert [stage for stage, _kwargs in events] == ["failed"] + call = events[0][1] + context = call["hook_context"] + assert context.trace_id == "trace-1" + assert context.user_id == "test_user" + assert context.cube_ids == ("cube_test",) + assert context.source == "cube_view.text_mem.add" + 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..69198cb62 --- /dev/null +++ b/tests/plugins/test_hook_context.py @@ -0,0 +1,325 @@ +"""Public HookContext contracts and context-aware callback behavior.""" + +import asyncio + +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 + + +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 + + +def test_build_hook_context_copies_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, + attributes=attributes, + ) + cube_ids.append("cube-3") + attributes["mode"] = "fast" + + 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_hook_context_is_additive_for_new_and_legacy_callbacks(): + hook_name = "test.hook-context.compatibility" + define_hook( + hook_name, + description="HookContext compatibility", + 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 + + register_hook(hook_name, legacy_callback) + register_hook(hook_name, context_callback) + + result = trigger_hook(hook_name, hook_context=context, result=1) + + assert result == 3 + assert calls == [("legacy", 1), ("context", context, 2)] + + +def test_single_provider_hook_supports_legacy_callback(): + hook_name = "test.single.hook-context" + define_hook( + hook_name, + description="Single-provider HookContext compatibility", + params=["hook_context", "value"], + ) + calls = [] + + def callback(*, value): + calls.append(value) + return value + 1 + + register_hook(hook_name, callback) + + assert trigger_single_hook(hook_name, hook_context=object(), value=1) == 2 + assert calls == [1] + + +def test_hookable_shares_and_reuses_context_for_sync_operation(): + built_context = object() + supplied_context = object() + builder_calls = [] + observed = [] + + def build_context(_handler, request): + builder_calls.append(request) + return built_context + + class Handler: + @hookable("context_sync", context_builder=build_context) + def run(self, request, *, hook_context=None): + observed.append(("operation", hook_context)) + return request + + def before(*, hook_context, **_kwargs): + observed.append(("before", hook_context)) + + def after(*, hook_context, **_kwargs): + observed.append(("after", hook_context)) + + register_hook("context_sync.before", before) + register_hook("context_sync.after", after) + + Handler().run("built") + Handler().run("supplied", hook_context=supplied_context) + + 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_shares_and_reuses_context_for_async_operation(): + built_context = object() + supplied_context = object() + builder_calls = [] + observed = [] + + def build_context(_handler, request): + builder_calls.append(request) + return built_context + + class Handler: + @hookable("context_async", context_builder=build_context) + async def run(self, request, *, hook_context=None): + observed.append(("operation", hook_context)) + return request + + 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), + ] + + +@pytest.mark.parametrize("is_async", [False, True]) +@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): + return request + + def sync_run(self, request): + return request + + class Handler: + 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) 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)