fix(hook): resolve message extraction conflict between memory and RAG hooks

When both StaticLongTermMemoryHook and GenericRAGHook are attached to
the same agent, they interfered with each other's message extraction
logic. Each hook searches for "the last user message" to use as its
query, but since both hooks inject their results as USER role messages
at the end of the message list, one hook could pick up the other hook's
injected message instead of the original user input.

Changes:
- GenericRAGHook: Change injected message name from "user" to
  "retrieved_knowledge" for clear identification; skip messages with
  name "long_term_memory" when extracting user query
- StaticLongTermMemoryHook: Skip messages with name "retrieved_knowledge"
  when extracting user query
- Add tests to verify hook interference is resolved

Closes #1403

Author: hexly666

agentscope-core/src/main/java/io/agentscope/core/memory/StaticLongTermMemoryHook.java

@@ -263,14 +263,20 @@ private Mono<PostCallEvent> handlePostCall(PostCallEvent event) {
      *
      * <p>Scans the message list from end to start to find the most recent user message,
      * which is typically the current query that should be used for memory retrieval.
+     * Skips messages injected by other hooks (e.g., GenericRAGHook with name "retrieved_knowledge").
      *
      * @param messages the message list
-     * @return the last user message, or null if none found
+     * @return the index of the last user message, or -1 if none found
      */
     private int extractLastUserMessageIndex(List<Msg> messages) {
         for (int i = messages.size() - 1; i >= 0; i--) {
             Msg msg = messages.get(i);
             if (msg.getRole() == MsgRole.USER) {
+                // Skip messages injected by other hooks (e.g., RAG knowledge)
+                String name = msg.getName();
+                if ("retrieved_knowledge".equals(name)) {
+                    continue;
+                }
                 return i;
             }
         }

agentscope-core/src/main/java/io/agentscope/core/rag/GenericRAGHook.java

@@ -145,11 +145,9 @@ private Mono<PreCallEvent> handlePreCall(PreCallEvent event) {
                             if (retrievedDocs == null || retrievedDocs.isEmpty()) {
                                 return Mono.just(event);
                             }
-                            List<Msg> enhancedMessages = new ArrayList<>();
-                            // Build enhanced messages with knowledge context
-                            Msg enhancedMessage = createEnhancedMessages(retrievedDocs);
-                            enhancedMessages.addAll(inputMessages);
-                            enhancedMessages.add(enhancedMessage);
+                            List<Msg> enhancedMessages = new ArrayList<>(inputMessages);
+                            // Build enhanced message with knowledge context
+                            enhancedMessages.add(createEnhancedMessage(retrievedDocs));
                             event.setInputMessages(enhancedMessages);
                             return Mono.just(event);
                         })
@@ -165,7 +163,8 @@ private Mono<PreCallEvent> handlePreCall(PreCallEvent event) {
      * Extracts query text from message list.
      *
      * <p>Finds the last user message as the query source (not just the last message, which could be
-     * ASSISTANT or TOOL in ReAct loops).
+     * ASSISTANT or TOOL in ReAct loops). Skips messages injected by other hooks (e.g.,
+     * StaticLongTermMemoryHook with name "long_term_memory").
      *
      * @param messages the message list
      * @return the extracted query text, or empty string if no user message found
@@ -175,11 +174,15 @@ private String extractQueryFromMessages(List<Msg> messages) {
             return "";
         }
 
-        // Find the last user message (not just the last message, which could be
-        // ASSISTANT or TOOL in ReAct loops)
+        // Find the last user message, skipping hook-injected messages
         for (int i = messages.size() - 1; i >= 0; i--) {
             Msg msg = messages.get(i);
             if (msg.getRole() == MsgRole.USER) {
+                // Skip messages injected by other hooks (e.g., long-term memory)
+                String name = msg.getName();
+                if ("long_term_memory".equals(name)) {
+                    continue;
+                }
                 return msg.getTextContent();
             }
         }
@@ -189,16 +192,18 @@ private String extractQueryFromMessages(List<Msg> messages) {
     /**
      * Creates enhanced message list with knowledge context injected.
      *
-     * <p>The knowledge is injected as a system message at the beginning of the message list.
+     * <p>The knowledge is injected as a user message appended to the end of the message list.
+     * The message uses a distinct name "retrieved_knowledge" so that other hooks can identify
+     * and skip it when extracting the original user query.
      *
      * @param retrievedDocs the retrieved documents
-     * @return the enhanced message list with knowledge context
+     * @return the enhanced message with knowledge context
      */
-    private Msg createEnhancedMessages(List<Document> retrievedDocs) {
+    private Msg createEnhancedMessage(List<Document> retrievedDocs) {
         String knowledgeContent = buildKnowledgeContent(retrievedDocs);
 
         return Msg.builder()
-                .name("user")
+                .name("retrieved_knowledge")
                 .role(MsgRole.USER)
                 .content(TextBlock.builder().text(knowledgeContent).build())
                 .build();

agentscope-core/src/test/java/io/agentscope/core/memory/StaticLongTermMemoryHookTest.java

@@ -338,4 +338,47 @@ void testOnEventWithPostCallEventAsyncRecordEmptyMemory() {
 
         verify(mockLongTermMemory, never()).record(anyList());
     }
+
+    @Test
+    void testOnEventSkipsRAGInjectedMessage() {
+        // Simulate GenericRAGHook having already injected a "retrieved_knowledge" message
+        List<Msg> inputMessages = new ArrayList<>();
+        inputMessages.add(
+                Msg.builder()
+                        .role(MsgRole.USER)
+                        .content(TextBlock.builder().text("What is the refund policy?").build())
+                        .build());
+        inputMessages.add(
+                Msg.builder()
+                        .role(MsgRole.USER)
+                        .name("retrieved_knowledge")
+                        .content(
+                                TextBlock.builder()
+                                        .text("<retrieved_knowledge>...</retrieved_knowledge>")
+                                        .build())
+                        .build());
+
+        PreCallEvent event = new PreCallEvent(mockAgent, inputMessages);
+
+        when(mockLongTermMemory.retrieve(any(Msg.class)))
+                .thenReturn(Mono.just("User prefers dark mode"));
+
+        StepVerifier.create(hook.onEvent(event))
+                .assertNext(
+                        resultEvent -> {
+                            List<Msg> messages = resultEvent.getInputMessages();
+                            assertEquals(3, messages.size());
+                            // The retrieval should use the original user message, not the RAG
+                            // message
+                            assertEquals(
+                                    "What is the refund policy?", messages.get(0).getTextContent());
+                            assertEquals("retrieved_knowledge", messages.get(1).getName());
+                            assertEquals(MsgRole.USER, messages.get(2).getRole());
+                            assertTrue(
+                                    messages.get(2)
+                                            .getTextContent()
+                                            .contains("<long_term_memory>"));
+                        })
+                .verifyComplete();
+    }
 }

agentscope-extensions/agentscope-extensions-rag-simple/src/test/java/io/agentscope/core/rag/hook/GenericRAGHookTest.java

@@ -162,6 +162,9 @@ void testHandlePreCallEvent() {
                             assertEquals(MsgRole.USER, enhancedMessages.get(0).getRole());
                             // Second message should be user message with knowledge retrieval
                             assertEquals(MsgRole.USER, enhancedMessages.get(1).getRole());
+                            // Name should be "retrieved_knowledge" to distinguish from real user
+                            // messages
+                            assertEquals("retrieved_knowledge", enhancedMessages.get(1).getName());
                             assertTrue(
                                     enhancedMessages
                                             .get(1)
@@ -321,6 +324,45 @@ void testFormatKnowledgeContent() {
                 .verifyComplete();
     }
 
+    @Test
+    @DisplayName("Should skip long_term_memory injected messages when extracting query")
+    void testSkipLongTermMemoryInjectedMessage() {
+        // Simulate StaticLongTermMemoryHook having already injected a "long_term_memory" message
+        Document doc = createDocument("doc1", "Refund policy: 30 days return");
+        knowledge.addDocuments(List.of(doc)).block();
+
+        List<Msg> inputMessages = new ArrayList<>();
+        inputMessages.add(
+                Msg.builder()
+                        .role(MsgRole.USER)
+                        .content(TextBlock.builder().text("What is the refund policy?").build())
+                        .build());
+        inputMessages.add(
+                Msg.builder()
+                        .role(MsgRole.USER)
+                        .name("long_term_memory")
+                        .content(
+                                TextBlock.builder()
+                                        .text("<long_term_memory>...</long_term_memory>")
+                                        .build())
+                        .build());
+
+        PreCallEvent event = new PreCallEvent(mockAgent, inputMessages);
+
+        StepVerifier.create(hook.onEvent(event))
+                .assertNext(
+                        result -> {
+                            List<Msg> messages = result.getInputMessages();
+                            // Should have original user msg + long_term_memory + RAG knowledge
+                            assertEquals(3, messages.size());
+                            // The RAG hook should use the original user query, not the memory
+                            // message
+                            assertEquals("retrieved_knowledge", messages.get(2).getName());
+                            assertTrue(messages.get(2).getTextContent().contains("knowledge base"));
+                        })
+                .verifyComplete();
+    }
+
     /**
      * Creates a test document.
      */