memwal 0.1.11.dev13__tar.gz → 0.1.11.dev14__tar.gz

{memwal-0.1.11.dev13 → memwal-0.1.11.dev14}/CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Added
 
 - `get_remember_status(job_id)` on `MemWal` and `MemWalSync` returns `RememberJobStatus` from `GET /api/remember/{job_id}`, accepting 200 and 404 like the TypeScript SDK. (WALM-832, #1096)
+- `RecallParams` accepts `scoring_weights` and `sort`. `recall()` forwards them on `POST /api/recall`. (#1062)
 
 ### Fixed
 

{memwal-0.1.11.dev13 → memwal-0.1.11.dev14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: memwal
-Version: 0.1.11.dev13
+Version: 0.1.11.dev14
 Summary: Python SDK for Walrus Memory — Privacy-first AI memory with Ed25519 signing
 Project-URL: Homepage, https://memory.walrus.xyz
 Project-URL: Documentation, https://memory.walrus.xyz
@@ -246,7 +246,7 @@ Create a new async client.
 | `await remember_bulk(items)` | Accept several background remember jobs |
 | `await wait_for_remember_jobs(job_ids, opts?)` | Poll several remember jobs together |
 | `await remember_bulk_and_wait(items, opts?)` | Store several memories and wait for completion |
-| `await recall(RecallParams(query, limit?, namespace?, max_distance?))` | Search memories, optionally filtering by distance |
+| `await recall(RecallParams(query, limit?, namespace?, max_distance?, scoring_weights?, sort?))` | Search memories, optionally filtering by distance |
 | `await analyze(text, namespace?)` | Extract and store facts |
 | `await ask(question, limit?, namespace?)` | Ask a question answered using memories |
 | `await restore(namespace, limit?)` | Restore a namespace |

{memwal-0.1.11.dev13 → memwal-0.1.11.dev14}/README.md

@@ -207,7 +207,7 @@ Create a new async client.
 | `await remember_bulk(items)` | Accept several background remember jobs |
 | `await wait_for_remember_jobs(job_ids, opts?)` | Poll several remember jobs together |
 | `await remember_bulk_and_wait(items, opts?)` | Store several memories and wait for completion |
-| `await recall(RecallParams(query, limit?, namespace?, max_distance?))` | Search memories, optionally filtering by distance |
+| `await recall(RecallParams(query, limit?, namespace?, max_distance?, scoring_weights?, sort?))` | Search memories, optionally filtering by distance |
 | `await analyze(text, namespace?)` | Extract and store facts |
 | `await ask(question, limit?, namespace?)` | Ask a question answered using memories |
 | `await restore(namespace, limit?)` | Restore a namespace |

{memwal-0.1.11.dev13 → memwal-0.1.11.dev14}/memwal/__init__.py

@@ -128,4 +128,4 @@ __all__ = [
     "RecallManualResult",
 ]
 
-__version__ = "0.1.11.dev13"
+__version__ = "0.1.11.dev14"

{memwal-0.1.11.dev13 → memwal-0.1.11.dev14}/memwal/client.py

@@ -1037,19 +1037,28 @@ class MemWal:
         Returns:
             :class:`RecallResult` with decrypted text results.
         """
+        scoring_weights = None
+        sort = None
         if isinstance(query, RecallParams):
             params = query
             query_text = params.query
             limit = params.limit
             namespace = params.namespace
             max_distance = params.max_distance
+            scoring_weights = params.scoring_weights
+            sort = params.sort
         else:
             query_text = query
-        data = await self._signed_request("POST", "/api/recall", {
+        body = {
             "query": query_text,
             "limit": limit,
             "namespace": namespace or self._namespace,
-        })
+        }
+        if scoring_weights is not None:
+            body["scoring_weights"] = scoring_weights.to_wire()
+        if sort is not None:
+            body["sort"] = sort
+        data = await self._signed_request("POST", "/api/recall", body)
         memories = [
             RecallMemory(
                 blob_id=m["blob_id"],

{memwal-0.1.11.dev13 → memwal-0.1.11.dev14}/memwal/middleware.py

@@ -105,6 +105,54 @@ def _find_last_user_message(messages: Any) -> Optional[str]:
     return None
 
 
+def _is_last_message_user(messages: Any) -> bool:
+    """Return True if the last message in `messages` is a user/human turn."""
+    if not isinstance(messages, (list, tuple)) or not messages:
+        return False
+    last = messages[-1]
+    if isinstance(last, dict):
+        return last.get("role") == "user"
+    if hasattr(last, "type"):
+        return getattr(last, "type") in ("human", "user")
+    if hasattr(last, "role"):
+        return getattr(last, "role") == "user"
+    return False
+
+
+def _user_turn_key(messages: Any) -> Optional[str]:
+    """Identity of the latest user turn: index plus text.
+
+    A tool step keeps the same key, so a cached recall can be re-injected
+    without calling the relayer again.
+    """
+    if not isinstance(messages, (list, tuple)) or not messages:
+        return None
+    text = _find_last_user_message(messages)
+    if not text:
+        return None
+    for i in range(len(messages) - 1, -1, -1):
+        msg = messages[i]
+        is_user = (
+            (isinstance(msg, dict) and msg.get("role") == "user")
+            or getattr(msg, "type", None) in ("human", "user")
+            or (not isinstance(msg, dict) and getattr(msg, "role", None) == "user")
+        )
+        if is_user:
+            return f"{i}\0{text}"
+    return None
+
+
+_RECALL_CACHE_LIMIT = 8
+
+
+def _remember_recall(cache: dict[str, str], key: str, context: str) -> None:
+    """Keep one entry per turn, newest last, and drop the oldest past the cap."""
+    cache.pop(key, None)
+    cache[key] = context
+    while len(cache) > _RECALL_CACHE_LIMIT:
+        cache.pop(next(iter(cache)))
+
+
 def _format_memories(
     memories: List[RecallMemory],
     nonce: Optional[str] = None,
@@ -420,12 +468,65 @@ def with_memwal_langchain(
 
     log = logger.debug if not debug else logger.warning
     pending = _PendingSaves(on_save_error)
+    recall_cache: dict[str, str] = {}
 
     original_agenerate = llm._agenerate
     original_generate = llm._generate
 
+    def _with_memory(messages: List[BaseMessage], memory_context: str) -> List[BaseMessage]:
+        result = list(messages)
+        last_human_idx = -1
+        for i in range(len(result) - 1, -1, -1):
+            if isinstance(result[i], HumanMessage):
+                last_human_idx = i
+                break
+
+        memory_msg = HumanMessage(content=memory_context)
+        if last_human_idx > 0:
+            result.insert(last_human_idx, memory_msg)
+        else:
+            result.insert(0, memory_msg)
+
+        if result and isinstance(result[0], SystemMessage):
+            existing_content = result[0].content
+            if isinstance(existing_content, list):
+                new_content = list(existing_content) + [
+                    {"type": "text", "text": f"\n\n{_UNTRUSTED_MEMORY_SYSTEM_INSTRUCTION}"}
+                ]
+            else:
+                text_str = str(existing_content or "")
+                new_content = f"{text_str}\n\n{_UNTRUSTED_MEMORY_SYSTEM_INSTRUCTION}".strip()
+            if hasattr(result[0], "model_copy"):
+                result[0] = result[0].model_copy(update={"content": new_content})
+            else:
+                result[0] = SystemMessage(
+                    content=new_content,
+                    additional_kwargs=getattr(result[0], "additional_kwargs", {}),
+                    id=getattr(result[0], "id", None),
+                    name=getattr(result[0], "name", None),
+                )
+        else:
+            result.insert(0, SystemMessage(content=_UNTRUSTED_MEMORY_SYSTEM_INSTRUCTION))
+        return result
+
     async def _inject_memories(messages: List[BaseMessage]) -> List[BaseMessage]:
         """Recall memories and inject them without granting system priority."""
+        turn_key = _user_turn_key(messages)
+        # Tool steps reuse this turn, including a recall that matched nothing.
+        # A user message always recalls again, so a later fact is not stuck
+        # behind the first result for the same text.
+        if (
+            turn_key
+            and not _is_last_message_user(messages)
+            and turn_key in recall_cache
+        ):
+            cached = recall_cache[turn_key]
+            if cached:
+                return _with_memory(messages, cached)
+            return messages
+        if not turn_key and not _is_last_message_user(messages):
+            return messages
+
         user_text = _find_last_user_message(messages)
         if not user_text:
             return messages
@@ -437,54 +538,22 @@ def with_memwal_langchain(
                 if (1 - m.distance) >= min_relevance
             ]
             if not relevant:
+                if turn_key:
+                    _remember_recall(recall_cache, turn_key, "")
                 return messages
 
             memory_context = _format_memories(relevant)
+            if turn_key:
+                _remember_recall(recall_cache, turn_key, memory_context)
             log(f"[Walrus Memory] Found {len(relevant)} relevant memories")
-
-            # The fixed trust rule is privileged; recalled bytes are not.
-            result = list(messages)
-            last_human_idx = -1
-            for i in range(len(result) - 1, -1, -1):
-                if isinstance(result[i], HumanMessage):
-                    last_human_idx = i
-                    break
-
-            memory_msg = HumanMessage(content=memory_context)
-            if last_human_idx > 0:
-                result.insert(last_human_idx, memory_msg)
-            else:
-                result.insert(0, memory_msg)
-
-            if result and isinstance(result[0], SystemMessage):
-                existing_content = result[0].content
-                if isinstance(existing_content, list):
-                    new_content = list(existing_content) + [
-                        {"type": "text", "text": f"\n\n{_UNTRUSTED_MEMORY_SYSTEM_INSTRUCTION}"}
-                    ]
-                else:
-                    text_str = str(existing_content or "")
-                    new_content = f"{text_str}\n\n{_UNTRUSTED_MEMORY_SYSTEM_INSTRUCTION}".strip()
-                if hasattr(result[0], "model_copy"):
-                    result[0] = result[0].model_copy(update={"content": new_content})
-                else:
-                    result[0] = SystemMessage(
-                        content=new_content,
-                        additional_kwargs=getattr(result[0], "additional_kwargs", {}),
-                        id=getattr(result[0], "id", None),
-                        name=getattr(result[0], "name", None),
-                    )
-            else:
-                result.insert(0, SystemMessage(content=_UNTRUSTED_MEMORY_SYSTEM_INSTRUCTION))
-
-            return result
+            return _with_memory(messages, memory_context)
         except Exception as e:
             log(f"[Walrus Memory] Memory search failed: {e}")
             return messages
 
     async def _post_analyze(messages: List[BaseMessage]) -> None:
         """Analyze user message for new facts."""
-        if not auto_save:
+        if not auto_save or not _is_last_message_user(messages):
             return
         user_text = _find_last_user_message(messages)
         if user_text:
@@ -495,39 +564,22 @@ def with_memwal_langchain(
                 pending.note_error(e)
 
     async def patched_agenerate(
-        messages: List[List[BaseMessage]], *args: Any, **kwargs: Any
+        messages: List[BaseMessage], *args: Any, **kwargs: Any
     ) -> ChatResult:
-        enriched = []
-        for msg_list in messages:
-            enriched.append(await _inject_memories(msg_list))
-
+        enriched = await _inject_memories(messages)
         result = await original_agenerate(enriched, *args, **kwargs)
-
-        for msg_list in messages:
-            _fire_and_forget(_post_analyze(msg_list), pending)
-
+        _fire_and_forget(_post_analyze(messages), pending)
         return result
 
     def _run_memwal(coro_factory: Callable[[], Any]) -> Any:
-        # Keep httpx clients bound to the short-lived loop that uses them.
         return _run_blocking(lambda: _with_fresh_http_client(memwal, coro_factory()))
 
     def patched_generate(
-        messages: List[List[BaseMessage]], *args: Any, **kwargs: Any
+        messages: List[BaseMessage], *args: Any, **kwargs: Any
     ) -> ChatResult:
-        # Inject via _run_blocking so recall still runs when a loop is already
-        # running (notebooks, async hosts) — the same helper the sync OpenAI
-        # wrapper uses. Passing the messages through untouched there made
-        # Walrus Memory look connected while recall silently never ran.
-        enriched = []
-        for msg_list in messages:
-            enriched.append(_run_memwal(lambda: _inject_memories(msg_list)))
-
+        enriched = _run_memwal(lambda: _inject_memories(messages))
         result = original_generate(enriched, *args, **kwargs)
-
-        for msg_list in messages:
-            _fire_and_forget(_post_analyze(msg_list), pending)
-
+        _fire_and_forget(_post_analyze(messages), pending)
         return result
 
     # Monkey-patch the LLM instance
@@ -626,44 +678,65 @@ def _wrap_async_openai(
 ) -> None:
     """Wrap an async OpenAI client's chat.completions.create."""
     original_create = client.chat.completions.create
-
+    recall_cache: dict[str, str] = {}
     async def patched_create(*args: Any, **kwargs: Any) -> Any:
         messages = kwargs.get("messages") or (args[0] if args else None)
         if messages is None:
             return await original_create(*args, **kwargs)
 
-        # Inject memories
-        user_text = _find_last_user_message(messages)
-        if user_text:
-            try:
-                recall_result = await memwal.recall(user_text, max_memories, namespace)
-                relevant = [
-                    m for m in recall_result.results
-                    if (1 - m.distance) >= min_relevance
-                ]
-                if relevant:
-                    memory_context = _format_memories(relevant)
-                    log(f"[Walrus Memory] Found {len(relevant)} relevant memories")
-                    messages = _inject_openai_memory(list(messages), memory_context)
-                    if "messages" in kwargs:
-                        kwargs["messages"] = messages
-                    elif args:
-                        args = (messages,) + args[1:]
-            except Exception as e:
-                log(f"[Walrus Memory] Memory search failed: {e}")
+        # A tool step reuses this turn's recall, including an empty one.
+        # A user message always recalls again.
+        turn_key = _user_turn_key(messages)
+        if (
+            turn_key
+            and not _is_last_message_user(messages)
+            and turn_key in recall_cache
+        ):
+            cached = recall_cache[turn_key]
+            if cached:
+                messages = _inject_openai_memory(list(messages), cached)
+                if "messages" in kwargs:
+                    kwargs["messages"] = messages
+                elif args:
+                    args = (messages,) + args[1:]
+        elif turn_key:
+            user_text = _find_last_user_message(messages)
+            if user_text:
+                try:
+                    recall_result = await memwal.recall(user_text, max_memories, namespace)
+                    relevant = [
+                        m for m in recall_result.results
+                        if (1 - m.distance) >= min_relevance
+                    ]
+                    if not relevant and turn_key:
+                        _remember_recall(recall_cache, turn_key, "")
+                    if relevant:
+                        memory_context = _format_memories(relevant)
+                        if turn_key:
+                            _remember_recall(recall_cache, turn_key, memory_context)
+                        log(f"[Walrus Memory] Found {len(relevant)} relevant memories")
+                        messages = _inject_openai_memory(list(messages), memory_context)
+                        if "messages" in kwargs:
+                            kwargs["messages"] = messages
+                        elif args:
+                            args = (messages,) + args[1:]
+                except Exception as e:
+                    log(f"[Walrus Memory] Memory search failed: {e}")
 
         result = await original_create(*args, **kwargs)
 
         # Fire-and-forget analyze
-        if auto_save and user_text:
-            async def _analyze() -> None:
-                try:
-                    await memwal.analyze(user_text, namespace)
-                except Exception as e:
-                    log(f"[Walrus Memory] Auto-save failed: {e}")
-                    pending.note_error(e)
-
-            _fire_and_forget(_analyze(), pending)
+        if auto_save and _is_last_message_user(messages):
+            user_text = _find_last_user_message(messages)
+            if user_text:
+                async def _analyze() -> None:
+                    try:
+                        await memwal.analyze(user_text, namespace)
+                    except Exception as e:
+                        log(f"[Walrus Memory] Auto-save failed: {e}")
+                        pending.note_error(e)
+
+                _fire_and_forget(_analyze(), pending)
 
         return result
 
@@ -682,7 +755,7 @@ def _wrap_sync_openai(
 ) -> None:
     """Wrap a sync OpenAI client's chat.completions.create."""
     original_create = client.chat.completions.create
-
+    recall_cache: dict[str, str] = {}
     def _run_memwal(coro_factory: Callable[[], Any]) -> Any:
         # Keep httpx clients bound to the short-lived loop that uses them.
         return _run_blocking(lambda: _with_fresh_http_client(memwal, coro_factory()))
@@ -692,40 +765,60 @@ def _wrap_sync_openai(
         if messages is None:
             return original_create(*args, **kwargs)
 
-        # Inject memories (sync)
-        user_text = _find_last_user_message(messages)
-        if user_text:
-            try:
-                recall_result = _run_memwal(
-                    lambda: memwal.recall(user_text, max_memories, namespace)
-                )
-                relevant = [
-                    m for m in recall_result.results
-                    if (1 - m.distance) >= min_relevance
-                ]
-                if relevant:
-                    memory_context = _format_memories(relevant)
-                    log(f"[Walrus Memory] Found {len(relevant)} relevant memories")
-                    messages = _inject_openai_memory(list(messages), memory_context)
-                    if "messages" in kwargs:
-                        kwargs["messages"] = messages
-                    elif args:
-                        args = (messages,) + args[1:]
-            except Exception as e:
-                log(f"[Walrus Memory] Memory search failed: {e}")
+        # A user message always recalls again.
+        turn_key = _user_turn_key(messages)
+        if (
+            turn_key
+            and not _is_last_message_user(messages)
+            and turn_key in recall_cache
+        ):
+            cached = recall_cache[turn_key]
+            if cached:
+                messages = _inject_openai_memory(list(messages), cached)
+                if "messages" in kwargs:
+                    kwargs["messages"] = messages
+                elif args:
+                    args = (messages,) + args[1:]
+        elif turn_key:
+            user_text = _find_last_user_message(messages)
+            if user_text:
+                try:
+                    recall_result = _run_memwal(
+                        lambda: memwal.recall(user_text, max_memories, namespace)
+                    )
+                    relevant = [
+                        m for m in recall_result.results
+                        if (1 - m.distance) >= min_relevance
+                    ]
+                    if not relevant and turn_key:
+                        _remember_recall(recall_cache, turn_key, "")
+                    if relevant:
+                        memory_context = _format_memories(relevant)
+                        if turn_key:
+                            _remember_recall(recall_cache, turn_key, memory_context)
+                        log(f"[Walrus Memory] Found {len(relevant)} relevant memories")
+                        messages = _inject_openai_memory(list(messages), memory_context)
+                        if "messages" in kwargs:
+                            kwargs["messages"] = messages
+                        elif args:
+                            args = (messages,) + args[1:]
+                except Exception as e:
+                    log(f"[Walrus Memory] Memory search failed: {e}")
 
         result = original_create(*args, **kwargs)
 
         # Fire-and-forget analyze
-        if auto_save and user_text:
-            def _analyze() -> None:
-                try:
-                    _run_memwal(lambda: memwal.analyze(user_text, namespace))
-                except Exception as e:
-                    log(f"[Walrus Memory] Auto-save failed: {e}")
-                    pending.note_error(e)
-
-            pending.spawn_thread(_analyze)
+        if auto_save and _is_last_message_user(messages):
+            user_text = _find_last_user_message(messages)
+            if user_text:
+                def _analyze() -> None:
+                    try:
+                        _run_memwal(lambda: memwal.analyze(user_text, namespace))
+                    except Exception as e:
+                        log(f"[Walrus Memory] Auto-save failed: {e}")
+                        pending.note_error(e)
+
+                pending.spawn_thread(_analyze)
 
         return result
 

{memwal-0.1.11.dev13 → memwal-0.1.11.dev14}/memwal/mock.py

@@ -261,16 +261,28 @@ class MemWalMock:
         namespace: Optional[str] = None,
         max_distance: Optional[float] = None,
     ) -> RecallResult:
+        """Token-overlap recall over the in-memory store.
+
+        ``RecallParams.sort`` is honored: ``"recent"`` keeps the semantic top
+        ``max(min(limit * 5, 50), limit)`` and orders that window newest first,
+        like the relayer. Otherwise results are ordered by token-overlap
+        distance. ``RecallParams.scoring_weights`` is accepted but ignored and
+        does not re-rank; ``distance`` is always token overlap.
+        """
         if isinstance(query, RecallParams):
             limit = query.limit
             namespace = query.namespace
             max_distance = query.max_distance
+            sort = query.sort
             query_text = query.query
         else:
+            sort = None
             query_text = query
         _validate_text(query_text, "query")
         if not isinstance(limit, int) or limit < 0:
             raise ValueError("limit must be a non-negative integer")
+        if sort not in (None, "relevance", "recent"):
+            raise ValueError("sort must be 'relevance' or 'recent'")
         resolved_namespace = namespace or self._namespace
         query_tokens = _tokens(query_text)
         ranked = [
@@ -279,6 +291,11 @@ class MemWalMock:
             if memory.namespace == resolved_namespace
         ]
         ranked.sort(key=lambda item: (item[1], item[0].sequence))
+        if sort == "recent":
+            # Same window as the TypeScript mock and RecallSort::candidate_limit.
+            # A newer memory outside that semantic window must not win.
+            window = max(min(limit * 5, 50), limit)
+            ranked = sorted(ranked[:window], key=lambda item: (-item[0].sequence, item[1]))
         page = ranked[:limit]
         if max_distance is not None:
             page = [item for item in page if item[1] < max_distance]

{memwal-0.1.11.dev13 → memwal-0.1.11.dev14}/memwal/types.py

@@ -108,6 +108,8 @@ class RecallParams:
     limit: int = 10
     namespace: Optional[str] = None
     max_distance: Optional[float] = None
+    scoring_weights: Optional["ScoringWeights"] = None
+    sort: Optional[str] = None
 
 
 @dataclass

{memwal-0.1.11.dev13 → memwal-0.1.11.dev14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "memwal"
-version = "0.1.11.dev13"
+version = "0.1.11.dev14"
 description = "Python SDK for Walrus Memory — Privacy-first AI memory with Ed25519 signing"
 readme = "README.md"
 license = "MIT"

{memwal-0.1.11.dev13 → memwal-0.1.11.dev14}/tests/test_middleware.py

@@ -331,7 +331,7 @@ class TestWithMemWalLangChain:
         captured: list = []
 
         async def _capture_agenerate(messages_batch, *a, **kw):
-            captured.extend(messages_batch)
+            captured.append(messages_batch)
             return ChatResult(
                 generations=[ChatGeneration(message=AIMessage(content="ok"))]
             )
@@ -348,7 +348,7 @@ class TestWithMemWalLangChain:
         smart_llm = with_memwal_langchain(
             llm, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, auto_save=False
         )
-        await smart_llm._agenerate([[HumanMessage("What do I drink?")]])
+        await smart_llm._agenerate([HumanMessage("What do I drink?")])
 
         assert len(captured) == 1
         injected = captured[0]
@@ -372,7 +372,7 @@ class TestWithMemWalLangChain:
         captured: list = []
 
         async def _capture_agenerate(messages_batch, *a, **kw):
-            captured.extend(messages_batch)
+            captured.append(messages_batch)
             return ChatResult(
                 generations=[ChatGeneration(message=AIMessage(content="ok"))]
             )
@@ -395,7 +395,7 @@ class TestWithMemWalLangChain:
             AIMessage(content="Noted!"),
             HumanMessage(content="What do I like?"),
         ]
-        await smart_llm._agenerate([messages])
+        await smart_llm._agenerate(messages)
 
         assert len(captured) == 1
         injected = captured[0]
@@ -424,7 +424,7 @@ class TestWithMemWalLangChain:
         captured: list = []
 
         async def _capture_agenerate(messages_batch, *a, **kw):
-            captured.extend(messages_batch)
+            captured.append(messages_batch)
             return ChatResult(
                 generations=[ChatGeneration(message=AIMessage(content="ok"))]
             )
@@ -445,7 +445,7 @@ class TestWithMemWalLangChain:
             {"type": "text", "text": "Base instructions", "cache_control": {"type": "ephemeral"}}
         ]
         sys_msg = SystemMessage(content=blocks, id="sys-123", additional_kwargs={"source": "test"})
-        await smart_llm._agenerate([[sys_msg, HumanMessage("What do I like?")]])
+        await smart_llm._agenerate([sys_msg, HumanMessage("What do I like?")])
 
         assert len(captured) == 1
         injected = captured[0]
@@ -468,7 +468,7 @@ class TestWithMemWalLangChain:
         captured: list = []
 
         async def _capture_agenerate(messages_batch, *a, **kw):
-            captured.extend(messages_batch)
+            captured.append(messages_batch)
             return ChatResult(
                 generations=[ChatGeneration(message=AIMessage(content="ok"))]
             )
@@ -481,7 +481,7 @@ class TestWithMemWalLangChain:
         smart_llm = with_memwal_langchain(
             llm, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, auto_save=False
         )
-        await smart_llm._agenerate([[HumanMessage("hello")]])
+        await smart_llm._agenerate([HumanMessage("hello")])
 
         injected = captured[0]
         system_msgs = [m for m in injected if isinstance(m, SystemMessage)]
@@ -498,7 +498,7 @@ class TestWithMemWalLangChain:
         captured: list = []
 
         async def _capture_agenerate(messages_batch, *a, **kw):
-            captured.extend(messages_batch)
+            captured.append(messages_batch)
             return ChatResult(
                 generations=[ChatGeneration(message=AIMessage(content="ok"))]
             )
@@ -517,7 +517,7 @@ class TestWithMemWalLangChain:
             llm, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER,
             min_relevance=0.3, auto_save=False
         )
-        await smart_llm._agenerate([[HumanMessage("hello")]])
+        await smart_llm._agenerate([HumanMessage("hello")])
 
         injected = captured[0]
         system_msgs = [m for m in injected if isinstance(m, SystemMessage)]
@@ -538,7 +538,7 @@ class TestWithMemWalLangChain:
             llm, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, auto_save=False
         )
         # Should NOT raise — recall failure is swallowed, LLM still called
-        await smart_llm._agenerate([[HumanMessage("will this work?")]])
+        await smart_llm._agenerate([HumanMessage("will this work?")])
 
     @respx.mock
     async def test_auto_save_triggers_analyze(self) -> None:
@@ -554,7 +554,7 @@ class TestWithMemWalLangChain:
         smart_llm = with_memwal_langchain(
             llm, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, auto_save=True
         )
-        await smart_llm._agenerate([[HumanMessage("store this")]])
+        await smart_llm._agenerate([HumanMessage("store this")])
 
         # Give fire-and-forget task time to run
         await asyncio.sleep(0.05)
@@ -572,7 +572,7 @@ class TestWithMemWalLangChain:
         smart_llm = with_memwal_langchain(
             llm, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, auto_save=False
         )
-        await smart_llm._agenerate([[SystemMessage("only system")]])
+        await smart_llm._agenerate([SystemMessage("only system")])
         assert not recall_route.called
 
     def _capturing_generate(self, captured: list):
@@ -581,7 +581,7 @@ class TestWithMemWalLangChain:
         from langchain_core.outputs import ChatGeneration, ChatResult
 
         def _generate(messages_batch, *a, **kw):
-            captured.extend(messages_batch)
+            captured.append(messages_batch)
             return ChatResult(
                 generations=[ChatGeneration(message=AIMessage(content="ok"))]
             )
@@ -607,7 +607,7 @@ class TestWithMemWalLangChain:
         smart_llm = with_memwal_langchain(
             llm, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, auto_save=False
         )
-        smart_llm._generate([[HumanMessage("What do I drink?")]])
+        smart_llm._generate([HumanMessage("What do I drink?")])
 
         assert recall_route.called
         assert any("User loves coffee" in m.content for m in captured[0])
@@ -641,7 +641,7 @@ class TestWithMemWalLangChain:
         # An async test body is itself a running loop -- the exact condition
         # that used to disable injection.
         assert asyncio.get_running_loop().is_running()
-        smart_llm._generate([[HumanMessage("What do I drink?")]])
+        smart_llm._generate([HumanMessage("What do I drink?")])
 
         assert recall_route.called, "recall was skipped inside a running loop"
         assert len(captured) == 1
@@ -671,6 +671,109 @@ class TestWithMemWalLangChain:
         assert callable(smart_llm.memwal_flush)
         assert callable(smart_llm.memwal_flush_sync)
 
+    @respx.mock
+    async def test_tool_steps_do_not_retrigger_recall_or_analyze(self) -> None:
+        """LangChain tool messages do not retrigger recall or auto-save."""
+        from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
+        from langchain_core.outputs import ChatGeneration, ChatResult
+        _mock_seal_session_prereqs()
+        llm = self._make_llm()
+        captured: list = []
+
+        async def _capture(batch, *args, **kwargs):
+            captured.append(batch)
+            return ChatResult(generations=[ChatGeneration(message=AIMessage(content="ok"))])
+
+        llm._agenerate = _capture
+        recall_route = respx.post(_RECALL_URL).mock(return_value=_mock_recall([
+            {"blob_id": "b1", "text": "User lives in Lisbon", "distance": 0.05}
+        ]))
+        analyze_route = respx.post(_ANALYZE_URL).mock(return_value=_mock_analyze())
+
+        smart = with_memwal_langchain(
+            llm, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, auto_save=True
+        )
+
+        messages = [HumanMessage(content="What is the weather?")]
+        await smart._agenerate(messages)
+        await smart.memwal_flush()
+
+        assert recall_route.call_count == 1
+        assert analyze_route.call_count == 1
+
+        messages.extend([
+            AIMessage(content="", tool_calls=[{"name": "weather", "args": {}, "id": "1"}]),
+            ToolMessage(content="Sunny 20C", tool_call_id="1"),
+        ])
+        await smart._agenerate(messages)
+        await smart.memwal_flush()
+
+        assert recall_route.call_count == 1, "recall must NOT be called again on tool step"
+        assert analyze_route.call_count == 1, "analyze must NOT be called again on tool step"
+        assert any(
+            "User lives in Lisbon" in getattr(message, "content", "")
+            for message in captured[-1]
+        )
+        # Step 3: Next user turn starts
+        messages.extend([
+            AIMessage(content="It is sunny!"),
+            HumanMessage(content="Thanks!"),
+        ])
+        await smart._agenerate(messages)
+        await smart.memwal_flush()
+
+        assert recall_route.call_count == 2
+        assert analyze_route.call_count == 2
+
+    @respx.mock
+    async def test_same_user_text_recalls_again(self) -> None:
+        """A later user turn with the same text must not reuse the first recall."""
+        from langchain_core.messages import AIMessage, HumanMessage
+        from langchain_core.outputs import ChatGeneration, ChatResult
+        _mock_seal_session_prereqs()
+        llm = self._make_llm()
+
+        async def _ok(batch, *args, **kwargs):
+            return ChatResult(generations=[ChatGeneration(message=AIMessage(content="ok"))])
+
+        llm._agenerate = _ok
+        recall_route = respx.post(_RECALL_URL).mock(return_value=_mock_recall([
+            {"blob_id": "b1", "text": "User lives in Lisbon", "distance": 0.05}
+        ]))
+        smart = with_memwal_langchain(
+            llm, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, auto_save=False
+        )
+        await smart._agenerate([HumanMessage(content="what's my name?")])
+        await smart._agenerate([HumanMessage(content="what's my name?")])
+        assert recall_route.call_count == 2
+
+    @respx.mock
+    async def test_empty_recall_is_reused_on_the_tool_step(self) -> None:
+        """A recall with no relevant hit is cached, so the tool step does not call again."""
+        from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
+        from langchain_core.outputs import ChatGeneration, ChatResult
+        _mock_seal_session_prereqs()
+        llm = self._make_llm()
+
+        async def _ok(batch, *args, **kwargs):
+            return ChatResult(generations=[ChatGeneration(message=AIMessage(content="ok"))])
+
+        llm._agenerate = _ok
+        recall_route = respx.post(_RECALL_URL).mock(return_value=_mock_recall([
+            {"blob_id": "b1", "text": "unrelated", "distance": 0.99}
+        ]))
+        smart = with_memwal_langchain(
+            llm, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, auto_save=False
+        )
+        messages = [HumanMessage(content="What is the weather?")]
+        await smart._agenerate(messages)
+        messages.extend([
+            AIMessage(content="", tool_calls=[{"name": "weather", "args": {}, "id": "1"}]),
+            ToolMessage(content="Sunny", tool_call_id="1"),
+        ])
+        await smart._agenerate(messages)
+        assert recall_route.call_count == 1
+
 
 # ============================================================
 # OpenAI middleware tests
@@ -882,6 +985,112 @@ class TestWithMemWalOpenAI:
         system_msgs = [m for m in captured if isinstance(m, dict) and m.get("role") == "system"]
         assert len(system_msgs) == 0
 
+    @respx.mock
+    async def test_tool_execution_steps_do_not_retrigger_recall_or_analyze(self) -> None:
+        """Tool response messages (role: tool) do not retrigger recall or auto-save."""
+        _mock_seal_session_prereqs()
+        client = self._make_async_client()
+        captured: list = []
+
+        async def _capture(*args, **kwargs):
+            captured.append(kwargs.get("messages"))
+            return MagicMock()
+
+        client.chat.completions.create = _capture
+        recall_route = respx.post(_RECALL_URL).mock(return_value=_mock_recall([
+            {"blob_id": "b1", "text": "User lives in Lisbon", "distance": 0.05}
+        ]))
+        analyze_route = respx.post(_ANALYZE_URL).mock(return_value=_mock_analyze())
+
+        smart = with_memwal_openai(
+            client, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, auto_save=True
+        )
+
+        messages = [{"role": "user", "content": "What is the weather in Lisbon?"}]
+        await smart.chat.completions.create(model="gpt-4o", messages=messages)
+        await smart.memwal_flush()
+
+        assert recall_route.call_count == 1
+        assert analyze_route.call_count == 1
+
+        messages.extend([
+            {
+                "role": "assistant",
+                "tool_calls": [{"id": "call_1", "function": {"name": "get_weather"}}],
+            },
+            {"role": "tool", "tool_call_id": "call_1", "content": "22C sunny"},
+        ])
+        await smart.chat.completions.create(model="gpt-4o", messages=messages)
+        await smart.memwal_flush()
+
+        assert recall_route.call_count == 1, "recall must NOT be called again on tool step"
+        assert analyze_route.call_count == 1, "analyze must NOT be called again on tool step"
+        assert any(
+            isinstance(message, dict) and "User lives in Lisbon" in str(message.get("content", ""))
+            for message in captured[-1]
+        )
+        # Step 3: Next user turn starts
+        messages.extend([
+            {"role": "assistant", "content": "It is 22C and sunny in Lisbon."},
+            {"role": "user", "content": "And in Porto?"},
+        ])
+        await smart.chat.completions.create(model="gpt-4o", messages=messages)
+        await smart.memwal_flush()
+
+        assert recall_route.call_count == 2
+        assert analyze_route.call_count == 2
+
+    @respx.mock
+    async def test_same_user_text_recalls_again(self) -> None:
+        _mock_seal_session_prereqs()
+        client = self._make_async_client()
+        recall_route = respx.post(_RECALL_URL).mock(return_value=_mock_recall([
+            {"blob_id": "b1", "text": "User lives in Lisbon", "distance": 0.05}
+        ]))
+        smart = with_memwal_openai(
+            client, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, auto_save=False
+        )
+        await smart.chat.completions.create(
+            model="gpt-4o", messages=[{"role": "user", "content": "what's my name?"}]
+        )
+        await smart.chat.completions.create(
+            model="gpt-4o", messages=[{"role": "user", "content": "what's my name?"}]
+        )
+        assert recall_route.call_count == 2
+
+    @respx.mock
+    async def test_empty_recall_is_reused_on_the_tool_step(self) -> None:
+        _mock_seal_session_prereqs()
+        client = self._make_async_client()
+        recall_route = respx.post(_RECALL_URL).mock(return_value=_mock_recall([
+            {"blob_id": "b1", "text": "unrelated", "distance": 0.99}
+        ]))
+        smart = with_memwal_openai(
+            client, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, auto_save=False
+        )
+        messages = [{"role": "user", "content": "hello"}]
+        await smart.chat.completions.create(model="gpt-4o", messages=messages)
+        messages = messages + [{"role": "tool", "tool_call_id": "1", "content": "ok"}]
+        await smart.chat.completions.create(model="gpt-4o", messages=messages)
+        assert recall_route.call_count == 1
+
+    @respx.mock
+    def test_sync_empty_recall_is_reused_on_the_tool_step(self) -> None:
+        _mock_seal_session_prereqs()
+        client = self._make_sync_client()
+        recall_route = respx.post(_RECALL_URL).mock(return_value=_mock_recall([
+            {"blob_id": "b1", "text": "unrelated", "distance": 0.99}
+        ]))
+        smart = with_memwal_openai(
+            client, key=_KEY_HEX, account_id=_ACCOUNT_ID, server_url=_SERVER, auto_save=False
+        )
+        messages = [{"role": "user", "content": "hello"}]
+        smart.chat.completions.create(model="gpt-4o", messages=messages)
+        messages = messages + [{"role": "tool", "tool_call_id": "1", "content": "ok"}]
+        smart.chat.completions.create(model="gpt-4o", messages=messages)
+        assert recall_route.call_count == 1
+
+
     @respx.mock
     def test_sync_client_wraps_create(self) -> None:
         """Sync OpenAI client wrapper is applied correctly."""

{memwal-0.1.11.dev13 → memwal-0.1.11.dev14}/tests/test_mock.py

@@ -46,6 +46,37 @@ async def test_mock_remember_and_recall_are_deterministic_and_offline(monkeypatc
     assert recalled.results[1].created_at == "2026-01-01T00:00:02.000Z"
 
 
+
+@pytest.mark.asyncio
+async def test_mock_recall_sort_recent_is_not_relevance_order():
+    mock = MemWalMock.create(namespace="user-a")
+    await mock.remember_and_wait("I prefer coffee in the morning")
+    await mock.remember_and_wait("I drink tea at night")
+
+    recent = await mock.recall(RecallParams(query="I", sort="recent"))
+    assert [memory.text for memory in recent.results] == [
+        "I drink tea at night",
+        "I prefer coffee in the morning",
+    ]
+
+    with pytest.raises(ValueError, match="sort"):
+        await mock.recall(RecallParams(query="I", sort="newest"))
+
+
+@pytest.mark.asyncio
+async def test_mock_recall_sort_recent_stays_inside_the_semantic_window():
+    mock = MemWalMock.create(namespace="user-a")
+    for i in range(6):
+        await mock.remember_and_wait(f"same fact {i}")
+    recent = await mock.recall(RecallParams(query="same fact", limit=1, sort="recent"))
+    assert recent.results[0].text == "same fact 4"
+
+    wide = MemWalMock.create(namespace="user-a")
+    for i in range(51):
+        await wide.remember_and_wait(f"same fact {i}")
+    first = await wide.recall(RecallParams(query="same fact", limit=11, sort="recent"))
+    assert first.results[0].text == "same fact 49"
+
 @pytest.mark.asyncio
 async def test_mock_isolates_namespaces_and_honors_max_distance():
     mock = MemWalMock.create()

memwal-0.1.11.dev14/tests/test_recall_weights.py

@@ -0,0 +1,42 @@
+import pytest
+
+from memwal import MemWal, RecallParams, ScoringWeights
+
+
+class CaptureMemWal(MemWal):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.captured = []
+
+    async def _ensure_compatible_relayer(self):
+        return {
+            "apiVersion": "1.0.0",
+            "relayerVersion": "capture",
+            "minSupportedSdk": {"python": "0.0.0"},
+        }
+
+    async def _signed_request(
+        self, method, path, body, accepted_statuses=(200,), include_seal_session=True,
+    ):
+        self.captured.append((method, path, body))
+        return {"results": [], "total": 0}
+
+
+@pytest.mark.asyncio
+async def test_recall_forwards_scoring_weights_and_sort():
+    client = CaptureMemWal.create(
+        key="11" * 32,
+        account_id="0x" + "ab" * 32,
+        server_url="https://relayer.example",
+    )
+    await client.recall(RecallParams(
+        query="food allergies",
+        scoring_weights=ScoringWeights(recency=1.0),
+        sort="recent",
+    ))
+    method, path, body = client.captured[0]
+    assert method == "POST"
+    assert path == "/api/recall"
+    assert body["scoring_weights"] == {"recency": 1.0}
+    assert body["sort"] == "recent"
+    await client.close()