unique-user-memory 2026.30.0.dev0__tar.gz → 2026.30.0.dev2__tar.gz

{unique_user_memory-2026.30.0.dev0 → unique_user_memory-2026.30.0.dev2}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.3
 Name: unique-user-memory
-Version: 2026.30.0.dev0
+Version: 2026.30.0.dev2
 Summary: 
 Author: Fabian Schläpfer
 Author-email: Fabian Schläpfer <fabian@unique.ch>
 License: Proprietary
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: pydantic>=2.8.2
-Requires-Dist: unique-sdk>=2026.30.0.dev0,<2026.30.0rc0
-Requires-Dist: unique-toolkit>=2026.30.0.dev0,<2026.30.0rc0
+Requires-Dist: unique-sdk>=2026.30.0.dev9,<2026.30.0rc0
+Requires-Dist: unique-toolkit>=2026.30.0.dev22,<2026.30.0rc0
 Requires-Python: >=3.12, <4
 Description-Content-Type: text/markdown
 

{unique_user_memory-2026.30.0.dev0 → unique_user_memory-2026.30.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_user_memory"
-version = "2026.30.0.dev0"
+version = "2026.30.0.dev2"
 description = ""
 authors = [
     { name = "Fabian Schläpfer", email = "fabian@unique.ch" },
@@ -11,8 +11,8 @@ requires-python = ">=3.12,<4"
 dependencies = [
     "jinja2>=3.1.6",
     "pydantic>=2.8.2",
-    "unique-sdk>=2026.30.0.dev0,<2026.30.0rc0",
-    "unique-toolkit>=2026.30.0.dev0,<2026.30.0rc0",
+    "unique-sdk>=2026.30.0.dev9,<2026.30.0rc0",
+    "unique-toolkit>=2026.30.0.dev22,<2026.30.0rc0",
 ]
 
 [dependency-groups]

{unique_user_memory-2026.30.0.dev0 → unique_user_memory-2026.30.0.dev2}/unique_user_memory/config.py

@@ -34,6 +34,22 @@ class UserMemoryConfig(BaseModel):
         le=8000,
         description="Maximum size of the memory profile in tokens.",
     )
+    consolidation_gate_enabled: bool = Field(
+        default=True,
+        description=(
+            "When true, a cheap single-word LLM 'gate' decides whether the turn "
+            "warrants a full memory rewrite before the expensive consolidation "
+            "runs."
+        ),
+    )
+    updating_notice_enabled: bool = Field(
+        default=True,
+        description=(
+            "When true, a transient 'updating context memory' notice is appended to the "
+            "assistant message while the memory rewrite runs, and removed "
+            "again once it completes."
+        ),
+    )
     root_folder: Annotated[str, RJSFMetaTag.SpecialWidget.hidden()] = Field(
         default="user-memory",
         min_length=1,

{unique_user_memory-2026.30.0.dev0 → unique_user_memory-2026.30.0.dev2}/unique_user_memory/tests/test_user_memory.py

@@ -1,3 +1,4 @@
+import asyncio
 from unittest.mock import AsyncMock, MagicMock
 
 import pytest
@@ -17,6 +18,8 @@ from unique_user_memory.user_memory import (
     enforce_token_cap,
     ensure_user_memory_folder,
     fit_user_memory,
+    noop_update_callback,
+    should_consolidate_memory,
     upload_user_memory,
 )
 from unique_user_memory.user_memory_postprocessor import UserMemoryPostprocessor
@@ -166,6 +169,10 @@ async def test_consolidate_user_memory_keeps_existing_on_noop(
         "unique_user_memory.user_memory.LanguageModelService",
         MagicMock(return_value=llm_service),
     )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.should_consolidate_memory",
+        AsyncMock(return_value=True),
+    )
 
     result = await consolidate_user_memory(
         current_memory=current,
@@ -194,6 +201,298 @@ async def test_consolidate_user_memory_keeps_existing_on_malformed_output(
         "unique_user_memory.user_memory.LanguageModelService",
         MagicMock(return_value=llm_service),
     )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.should_consolidate_memory",
+        AsyncMock(return_value=True),
+    )
+
+    result = await consolidate_user_memory(
+        current_memory=current,
+        user_id="user_1",
+        user_message="remember I like concise answers",
+        assistant_message="noted",
+        config=UserMemoryConfig(),
+        language_model=_TEST_LANGUAGE_MODEL,
+        event=MagicMock(),
+        logger=MagicMock(),
+    )
+
+    assert result == current
+
+
+@pytest.mark.asyncio
+async def test_consolidate_user_memory_skips_full_rewrite_when_gate_noop(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    current = empty_profile("user_1")
+    llm_service = MagicMock()
+    llm_service.complete_async = AsyncMock()
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.LanguageModelService",
+        MagicMock(return_value=llm_service),
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.should_consolidate_memory",
+        AsyncMock(return_value=False),
+    )
+
+    result = await consolidate_user_memory(
+        current_memory=current,
+        user_id="user_1",
+        user_message="hello",
+        assistant_message="hi",
+        config=UserMemoryConfig(),
+        language_model=_TEST_LANGUAGE_MODEL,
+        event=MagicMock(),
+        logger=MagicMock(),
+    )
+
+    assert result == current
+    llm_service.complete_async.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_consolidate_user_memory_runs_full_rewrite_when_gate_update(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    current = empty_profile("user_1")
+    rewritten = "# User Memory\n\n## Identity\n- Prefers concise answers"
+    response = MagicMock()
+    response.choices[0].message.content = rewritten
+    llm_service = MagicMock()
+    llm_service.complete_async = AsyncMock(return_value=response)
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.LanguageModelService",
+        MagicMock(return_value=llm_service),
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.should_consolidate_memory",
+        AsyncMock(return_value=True),
+    )
+
+    result = await consolidate_user_memory(
+        current_memory=current,
+        user_id="user_1",
+        user_message="remember I like concise answers",
+        assistant_message="noted",
+        config=UserMemoryConfig(),
+        language_model=_TEST_LANGUAGE_MODEL,
+        event=MagicMock(),
+        logger=MagicMock(),
+    )
+
+    assert result == rewritten
+    llm_service.complete_async.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_consolidate_user_memory_skips_gate_when_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    current = empty_profile("user_1")
+    rewritten = "# User Memory\n\n## Identity\n- Prefers concise answers"
+    response = MagicMock()
+    response.choices[0].message.content = rewritten
+    llm_service = MagicMock()
+    llm_service.complete_async = AsyncMock(return_value=response)
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.LanguageModelService",
+        MagicMock(return_value=llm_service),
+    )
+    gate = AsyncMock(return_value=False)
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.should_consolidate_memory",
+        gate,
+    )
+
+    result = await consolidate_user_memory(
+        current_memory=current,
+        user_id="user_1",
+        user_message="hello",
+        assistant_message="hi",
+        config=UserMemoryConfig(consolidation_gate_enabled=False),
+        language_model=_TEST_LANGUAGE_MODEL,
+        event=MagicMock(),
+        logger=MagicMock(),
+    )
+
+    assert result == rewritten
+    gate.assert_not_awaited()
+    llm_service.complete_async.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_should_consolidate_memory_returns_false_on_noop(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    response = MagicMock()
+    response.choices[0].message.content = "NOOP"
+    llm_service = MagicMock()
+    llm_service.complete_async = AsyncMock(return_value=response)
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.LanguageModelService",
+        MagicMock(return_value=llm_service),
+    )
+
+    result = await should_consolidate_memory(
+        current_memory=empty_profile("user_1"),
+        user_id="user_1",
+        user_message="hello",
+        assistant_message="hi",
+        language_model=_TEST_LANGUAGE_MODEL,
+        event=MagicMock(),
+        logger=MagicMock(),
+    )
+
+    assert result is False
+    assert (
+        llm_service.complete_async.call_args.kwargs["other_options"]["max_tokens"] == 4
+    )
+
+
+@pytest.mark.asyncio
+async def test_should_consolidate_memory_returns_true_on_update(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    response = MagicMock()
+    response.choices[0].message.content = "UPDATE"
+    llm_service = MagicMock()
+    llm_service.complete_async = AsyncMock(return_value=response)
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.LanguageModelService",
+        MagicMock(return_value=llm_service),
+    )
+
+    result = await should_consolidate_memory(
+        current_memory=empty_profile("user_1"),
+        user_id="user_1",
+        user_message="remember I like concise answers",
+        assistant_message="noted",
+        language_model=_TEST_LANGUAGE_MODEL,
+        event=MagicMock(),
+        logger=MagicMock(),
+    )
+
+    assert result is True
+
+
+@pytest.mark.asyncio
+async def test_should_consolidate_memory_falls_back_to_true_on_error(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    llm_service = MagicMock()
+    llm_service.complete_async = AsyncMock(side_effect=RuntimeError("boom"))
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.LanguageModelService",
+        MagicMock(return_value=llm_service),
+    )
+
+    result = await should_consolidate_memory(
+        current_memory=empty_profile("user_1"),
+        user_id="user_1",
+        user_message="hello",
+        assistant_message="hi",
+        language_model=_TEST_LANGUAGE_MODEL,
+        event=MagicMock(),
+        logger=MagicMock(),
+    )
+
+    assert result is True
+
+
+@pytest.mark.asyncio
+async def test_consolidate_user_memory_invokes_update_callbacks_on_rewrite(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    rewritten = "# User Memory\n\n## Identity\n- Prefers concise answers"
+    response = MagicMock()
+    response.choices[0].message.content = rewritten
+    llm_service = MagicMock()
+    llm_service.complete_async = AsyncMock(return_value=response)
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.LanguageModelService",
+        MagicMock(return_value=llm_service),
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.should_consolidate_memory",
+        AsyncMock(return_value=True),
+    )
+    events: list[str] = []
+    on_start = AsyncMock(side_effect=lambda: events.append("start"))
+    on_end = AsyncMock(side_effect=lambda: events.append("end"))
+
+    result = await consolidate_user_memory(
+        current_memory=empty_profile("user_1"),
+        user_id="user_1",
+        user_message="remember I like concise answers",
+        assistant_message="noted",
+        config=UserMemoryConfig(),
+        language_model=_TEST_LANGUAGE_MODEL,
+        event=MagicMock(),
+        logger=MagicMock(),
+        on_update_start=on_start,
+        on_update_end=on_end,
+    )
+
+    assert result == rewritten
+    on_start.assert_awaited_once()
+    on_end.assert_awaited_once()
+    assert events == ["start", "end"]
+
+
+@pytest.mark.asyncio
+async def test_consolidate_user_memory_skips_update_callbacks_on_noop(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    current = empty_profile("user_1")
+    llm_service = MagicMock()
+    llm_service.complete_async = AsyncMock()
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.LanguageModelService",
+        MagicMock(return_value=llm_service),
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.should_consolidate_memory",
+        AsyncMock(return_value=False),
+    )
+    on_start = AsyncMock()
+    on_end = AsyncMock()
+
+    result = await consolidate_user_memory(
+        current_memory=current,
+        user_id="user_1",
+        user_message="hello",
+        assistant_message="hi",
+        config=UserMemoryConfig(),
+        language_model=_TEST_LANGUAGE_MODEL,
+        event=MagicMock(),
+        logger=MagicMock(),
+        on_update_start=on_start,
+        on_update_end=on_end,
+    )
+
+    assert result == current
+    on_start.assert_not_awaited()
+    on_end.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_consolidate_user_memory_invokes_update_end_on_rewrite_error(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    current = empty_profile("user_1")
+    llm_service = MagicMock()
+    llm_service.complete_async = AsyncMock(side_effect=RuntimeError("boom"))
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.LanguageModelService",
+        MagicMock(return_value=llm_service),
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.should_consolidate_memory",
+        AsyncMock(return_value=True),
+    )
+    on_start = AsyncMock()
+    on_end = AsyncMock()
 
     result = await consolidate_user_memory(
         current_memory=current,
@@ -204,9 +503,153 @@ async def test_consolidate_user_memory_keeps_existing_on_malformed_output(
         language_model=_TEST_LANGUAGE_MODEL,
         event=MagicMock(),
         logger=MagicMock(),
+        on_update_start=on_start,
+        on_update_end=on_end,
     )
 
     assert result == current
+    on_start.assert_awaited_once()
+    on_end.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_consolidate_user_memory_invokes_update_end_when_start_cancelled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # on_update_start may show the notice and then be cancelled. CancelledError
+    # is a BaseException (not caught in _set_message_content), so the cleanup
+    # callback must still run to remove the transient notice.
+    current = empty_profile("user_1")
+    llm_service = MagicMock()
+    llm_service.complete_async = AsyncMock()
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.LanguageModelService",
+        MagicMock(return_value=llm_service),
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.should_consolidate_memory",
+        AsyncMock(return_value=True),
+    )
+    on_start = AsyncMock(side_effect=asyncio.CancelledError)
+    on_end = AsyncMock()
+
+    with pytest.raises(asyncio.CancelledError):
+        await consolidate_user_memory(
+            current_memory=current,
+            user_id="user_1",
+            user_message="remember I like concise answers",
+            assistant_message="noted",
+            config=UserMemoryConfig(),
+            language_model=_TEST_LANGUAGE_MODEL,
+            event=MagicMock(),
+            logger=MagicMock(),
+            on_update_start=on_start,
+            on_update_end=on_end,
+        )
+
+    on_start.assert_awaited_once()
+    on_end.assert_awaited_once()
+    llm_service.complete_async.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_user_memory_postprocessor_shows_and_removes_updating_notice(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    updated_memory = "# User Memory\n\n## Identity\n- Updated"
+    original_text = "Here is your answer."
+
+    async def fake_consolidate(*, on_update_start, on_update_end, **kwargs) -> str:  # type: ignore[no-untyped-def]
+        await on_update_start()
+        await on_update_end()
+        return updated_memory
+
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory_postprocessor.consolidate_user_memory",
+        fake_consolidate,
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory_postprocessor.upload_user_memory",
+        AsyncMock(return_value=True),
+    )
+    chat_service = MagicMock()
+    chat_service.modify_assistant_message_async = AsyncMock()
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory_postprocessor.ChatService",
+        MagicMock(return_value=chat_service),
+    )
+    event = MagicMock()
+    event.user_id = "user_1"
+    event.company_id = "company_1"
+    event.payload.user_message.text = "remember this"
+    loop_response = MagicMock()
+    loop_response.message.text = original_text
+    loop_response.message.id = "msg_1"
+    loop_response.message.references = []
+    postprocessor = UserMemoryPostprocessor(
+        config=UserMemoryConfig(),
+        language_model=_TEST_LANGUAGE_MODEL,
+        event=event,
+        state=UserMemoryState(scope_id="scope_1", text=empty_profile("user_1")),
+        logger=MagicMock(),
+        chat_service=chat_service,
+    )
+
+    await postprocessor.run(loop_response)
+
+    calls = chat_service.modify_assistant_message_async.await_args_list
+    assert len(calls) == 2
+    assert calls[0].kwargs["content"].startswith(original_text)
+    assert calls[0].kwargs["content"] != original_text
+    assert calls[0].kwargs["message_id"] == "msg_1"
+    assert calls[1].kwargs["content"] == original_text
+
+
+@pytest.mark.asyncio
+async def test_user_memory_postprocessor_skips_notice_when_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    updated_memory = "# User Memory\n\n## Identity\n- Updated"
+
+    async def fake_consolidate(*, on_update_start, on_update_end, **kwargs) -> str:  # type: ignore[no-untyped-def]
+        assert on_update_start is noop_update_callback
+        assert on_update_end is noop_update_callback
+        return updated_memory
+
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory_postprocessor.consolidate_user_memory",
+        fake_consolidate,
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory_postprocessor.upload_user_memory",
+        AsyncMock(return_value=True),
+    )
+    chat_service = MagicMock()
+    chat_service.modify_assistant_message_async = AsyncMock()
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory_postprocessor.ChatService",
+        MagicMock(return_value=chat_service),
+    )
+    event = MagicMock()
+    event.user_id = "user_1"
+    event.company_id = "company_1"
+    event.payload.user_message.text = "remember this"
+    loop_response = MagicMock()
+    loop_response.message.text = "answer"
+    loop_response.message.id = "msg_1"
+    loop_response.message.references = []
+    postprocessor = UserMemoryPostprocessor(
+        config=UserMemoryConfig(updating_notice_enabled=False),
+        language_model=_TEST_LANGUAGE_MODEL,
+        event=event,
+        state=UserMemoryState(scope_id="scope_1", text=empty_profile("user_1")),
+        logger=MagicMock(),
+        chat_service=chat_service,
+    )
+
+    await postprocessor.run(loop_response)
+
+    chat_service.modify_assistant_message_async.assert_not_awaited()
 
 
 @pytest.mark.asyncio
@@ -496,16 +939,19 @@ async def test_user_memory_postprocessor_logs_success_when_upload_succeeds(
     loop_response = MagicMock()
     loop_response.message.text = "noted"
     logger = MagicMock()
+    chat_service = MagicMock()
     postprocessor = UserMemoryPostprocessor(
         config=UserMemoryConfig(),
         language_model=_TEST_LANGUAGE_MODEL,
         event=event,
         state=UserMemoryState(scope_id="scope_1", text=empty_profile("user_1")),
         logger=logger,
+        chat_service=chat_service,
     )
 
-    await postprocessor.run(loop_response)
+    updated = await postprocessor.run(loop_response)
 
+    assert updated is True
     upload.assert_awaited_once_with(
         scope_id="scope_1",
         content=updated_memory,
@@ -538,16 +984,19 @@ async def test_user_memory_postprocessor_does_not_log_success_when_upload_fails(
     loop_response = MagicMock()
     loop_response.message.text = "noted"
     logger = MagicMock()
+    chat_service = MagicMock()
     postprocessor = UserMemoryPostprocessor(
         config=UserMemoryConfig(),
         language_model=_TEST_LANGUAGE_MODEL,
         event=event,
         state=UserMemoryState(scope_id="scope_1", text=empty_profile("user_1")),
         logger=logger,
+        chat_service=chat_service,
     )
 
-    await postprocessor.run(loop_response)
+    updated = await postprocessor.run(loop_response)
 
+    assert updated is False
     assert all(
         call.args != ("[user-memory] memory updated and uploaded successfully",)
         for call in logger.info.call_args_list

{unique_user_memory-2026.30.0.dev0 → unique_user_memory-2026.30.0.dev2}/unique_user_memory/user_memory.py

@@ -1,4 +1,5 @@
 import re
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from logging import Logger
 
@@ -28,11 +29,27 @@ from unique_user_memory.user_memory_prompts import (
     consolidation_system_prompt,
     consolidation_user_prompt,
     empty_profile,
+    memory_gate_system_prompt,
+    memory_gate_user_prompt,
 )
 
 MEMORY_FILENAME = "memory.md"
 MIME_TYPE = "text/markdown"
 _LLM_OUTPUT_HEADROOM_TOKENS = 200
+
+
+async def noop_update_callback() -> None:
+    """Default update hook that does nothing.
+
+    Used as the default for ``on_update_start`` / ``on_update_end`` so callers
+    that do not need update notifications can be awaited unconditionally.
+    """
+    return None
+
+
+# The gate only ever replies with the single word UPDATE or NOOP; a tiny
+# output budget keeps the common (NOOP) path cheap and fast.
+_GATE_MAX_TOKENS = 4
 # When condensing an oversized profile, aim below the hard cap so the LLM
 # output leaves headroom and the hard-cut safety net rarely has to fire.
 _CONDENSE_TARGET_RATIO = 0.9
@@ -551,6 +568,91 @@ async def upload_user_memory(
         return False
 
 
+async def should_consolidate_memory(
+    *,
+    current_memory: str,
+    user_id: str,
+    user_message: str,
+    assistant_message: str,
+    language_model: LanguageModelInfo,
+    event: ChatEvent,
+    logger: Logger,
+) -> bool:
+    """Cheaply decide whether the turn warrants a full memory rewrite.
+
+    Runs a focused LLM call capped at a few output tokens that answers
+    ``UPDATE`` or ``NOOP``. Returns ``False`` only on an explicit ``NOOP``
+    so the caller can skip the expensive full-profile regeneration. Any
+    error (or ambiguous output) falls back to ``True`` so behaviour stays
+    identical to the pre-gate path.
+    """
+    try:
+        llm_service = LanguageModelService(event)
+    except Exception as exc:
+        logger.warning(
+            "[user-memory] cannot construct LanguageModelService for gate: [%s] %s",
+            type(exc).__name__,
+            exc,
+        )
+        return True
+
+    messages = LanguageModelMessages(
+        [
+            LanguageModelSystemMessage(content=memory_gate_system_prompt()),
+            LanguageModelUserMessage(
+                content=memory_gate_user_prompt(
+                    user_id=user_id,
+                    existing_memory=current_memory,
+                    user_message=_sanitize_for_xml_context(user_message or ""),
+                    assistant_message=_sanitize_for_xml_context(
+                        assistant_message or ""
+                    ),
+                )
+            ),
+        ]
+    )
+
+    try:
+        response = await llm_service.complete_async(
+            messages=messages,
+            model_name=language_model.name,
+            other_options={"max_tokens": _GATE_MAX_TOKENS},
+        )
+    except Exception as exc:
+        logger.warning(
+            "[user-memory] gate LLM call failed (model=%s): [%s] %s",
+            language_model.name,
+            type(exc).__name__,
+            exc,
+        )
+        return True
+
+    try:
+        raw = response.choices[0].message.content or ""
+    except Exception as exc:
+        logger.warning(
+            "[user-memory] could not extract content from gate response: [%s] %s",
+            type(exc).__name__,
+            exc,
+        )
+        return True
+
+    if not isinstance(raw, str):
+        logger.warning(
+            "[user-memory] gate returned non-string content (%s)",
+            type(raw).__name__,
+        )
+        return True
+
+    decision = raw.strip().upper()
+    if decision.startswith("NOOP"):
+        logger.info("[user-memory] gate decided NOOP - skipping consolidation")
+        return False
+
+    logger.info("[user-memory] gate decided UPDATE - consolidating")
+    return True
+
+
 async def consolidate_user_memory(
     *,
     current_memory: str,
@@ -561,7 +663,17 @@ async def consolidate_user_memory(
     language_model: LanguageModelInfo,
     event: ChatEvent,
     logger: Logger,
+    on_update_start: Callable[[], Awaitable[None]] = noop_update_callback,
+    on_update_end: Callable[[], Awaitable[None]] = noop_update_callback,
 ) -> str:
+    """Consolidate the latest turn into the user's memory profile.
+
+    When the (optional) gate decides the turn is worth remembering, the
+    expensive full-profile rewrite runs. ``on_update_start`` is awaited
+    just before that slow rewrite begins and ``on_update_end`` right after
+    it finishes (even on failure), so a caller can surface a transient
+    "updating memory" notice to the user only while real work happens.
+    """
     safe_current = enforce_token_cap(
         content=current_memory,
         max_tokens=config.max_tokens,
@@ -582,6 +694,44 @@ async def consolidate_user_memory(
             language_model=language_model,
         )
 
+    if config.consolidation_gate_enabled and not await should_consolidate_memory(
+        current_memory=safe_current,
+        user_id=user_id,
+        user_message=user_message,
+        assistant_message=assistant_message,
+        language_model=language_model,
+        event=event,
+        logger=logger,
+    ):
+        return safe_current
+
+    try:
+        await on_update_start()
+        return await _rewrite_user_memory(
+            safe_current=safe_current,
+            user_id=user_id,
+            user_message=user_message,
+            assistant_message=assistant_message,
+            config=config,
+            language_model=language_model,
+            event=event,
+            logger=logger,
+        )
+    finally:
+        await on_update_end()
+
+
+async def _rewrite_user_memory(
+    *,
+    safe_current: str,
+    user_id: str,
+    user_message: str,
+    assistant_message: str,
+    config: UserMemoryConfig,
+    language_model: LanguageModelInfo,
+    event: ChatEvent,
+    logger: Logger,
+) -> str:
     if not safe_current.strip():
         safe_current = empty_profile(user_id)
 

{unique_user_memory-2026.30.0.dev0 → unique_user_memory-2026.30.0.dev2}/unique_user_memory/user_memory_postprocessor.py

@@ -1,7 +1,10 @@
+from collections.abc import Awaitable, Callable
 from logging import Logger
 
 from unique_toolkit.agentic.postprocessor.postprocessor_manager import Postprocessor
 from unique_toolkit.app.schemas import ChatEvent
+from unique_toolkit.chat.service import ChatService
+from unique_toolkit.content.schemas import ContentReference
 from unique_toolkit.language_model.default_language_model import (
     DEFAULT_LANGUAGE_MODEL,
 )
@@ -12,9 +15,14 @@ from unique_user_memory.config import UserMemoryConfig
 from unique_user_memory.user_memory import (
     UserMemoryState,
     consolidate_user_memory,
+    noop_update_callback,
     upload_user_memory,
 )
 
+# Transient marker appended to the assistant message while the (slow) memory
+# rewrite runs; removed again once consolidation finishes.
+_UPDATING_NOTICE = "\n\n---\n\n🧠 _Updating context memory…_"
+
 
 class UserMemoryPostprocessor(Postprocessor):
     def __init__(
@@ -27,6 +35,7 @@ class UserMemoryPostprocessor(Postprocessor):
         event: ChatEvent,
         state: UserMemoryState,
         logger: Logger,
+        chat_service: ChatService,
     ) -> None:
         super().__init__(name="UserMemoryPostprocessor")
         self._config = config
@@ -39,13 +48,45 @@ class UserMemoryPostprocessor(Postprocessor):
         self._state = state
         self._logger = logger
         self._new_memory: str | None = None
+        self._chat_service: ChatService = chat_service
+
+    async def run(self, loop_response: LanguageModelStreamResponse) -> bool:
+        """Consolidate and upload user memory for this turn.
 
-    async def run(self, loop_response: LanguageModelStreamResponse) -> None:
+        Returns True if the memory profile changed and was uploaded, False
+        otherwise (no user/company, NOOP consolidation, or failed upload).
+        """
         self._logger.info("[user-memory] running postprocessor")
         user_id = self._event.user_id
         company_id = self._event.company_id
         if not user_id or not company_id:
-            return
+            return False
+
+        on_update_start: Callable[[], Awaitable[None]] = noop_update_callback
+        on_update_end: Callable[[], Awaitable[None]] = noop_update_callback
+        if self._config.updating_notice_enabled:
+            original_text = loop_response.message.text or ""
+            message_id = loop_response.message.id
+            references = loop_response.message.references
+
+            async def _on_update_start() -> None:
+                await self._set_message_content(
+                    content=original_text + _UPDATING_NOTICE,
+                    message_id=message_id,
+                    references=references,
+                    action="show updating notice",
+                )
+
+            async def _on_update_end() -> None:
+                await self._set_message_content(
+                    content=original_text,
+                    message_id=message_id,
+                    references=references,
+                    action="remove updating notice",
+                )
+
+            on_update_start = _on_update_start
+            on_update_end = _on_update_end
 
         self._new_memory = await consolidate_user_memory(
             current_memory=self._state.text,
@@ -56,11 +97,13 @@ class UserMemoryPostprocessor(Postprocessor):
             language_model=self._language_model,
             event=self._event,
             logger=self._logger,
+            on_update_start=on_update_start,
+            on_update_end=on_update_end,
         )
 
         if self._new_memory == self._state.text:
             self._logger.debug("[user-memory] consolidation NOOP - skipping upload")
-            return
+            return False
 
         uploaded = await upload_user_memory(
             scope_id=self._state.scope_id,
@@ -71,9 +114,32 @@ class UserMemoryPostprocessor(Postprocessor):
         )
         if not uploaded:
             self._logger.warning("[user-memory] memory update was not uploaded")
-            return
+            return False
 
         self._logger.info("[user-memory] memory updated and uploaded successfully")
+        return True
+
+    async def _set_message_content(
+        self,
+        *,
+        content: str,
+        message_id: str | None,
+        references: list[ContentReference] | None,
+        action: str,
+    ) -> None:
+        try:
+            await self._chat_service.modify_assistant_message_async(
+                content=content,
+                message_id=message_id,
+                references=references,
+            )
+        except Exception as exc:
+            self._logger.warning(
+                "[user-memory] failed to %s: [%s] %s",
+                action,
+                type(exc).__name__,
+                exc,
+            )
 
     def apply_postprocessing_to_response(
         self, loop_response: LanguageModelStreamResponse

{unique_user_memory-2026.30.0.dev0 → unique_user_memory-2026.30.0.dev2}/unique_user_memory/user_memory_prompts.py

@@ -291,3 +291,85 @@ def consolidation_user_prompt(
         user_message=(user_message or "").strip(),
         assistant_message=(assistant_message or "").strip(),
     )
+
+
+_GATE_SYSTEM_PROMPT_TEMPLATE = """\
+You are the decision gate for a user-memory system on the Unique AI
+platform. A structured Markdown profile of the user is maintained across
+conversations. Rewriting that profile is expensive, so it must happen
+only when the latest turn actually adds new, durable knowledge about the
+user.
+
+# Inputs
+
+1. `<existing_memory>` - the current profile (may be empty on the first turn).
+2. `<new_turn>` - the most recent user message and the assistant's reply.
+
+# Your task
+
+Reply with EXACTLY ONE uppercase word and nothing else:
+
+- `UPDATE` - the new turn contains at least one durable fact about the
+  user that is NOT already captured in `<existing_memory>`, or that
+  changes/contradicts something already stored.
+- `NOOP` - otherwise. Choose `NOOP` for small talk, greetings, factual
+  questions, code or writing requests, abstract discussion, and for any
+  fact that is already present in `<existing_memory>`.
+
+Do NOT output the profile, an explanation, punctuation, or code fences -
+only the single word `UPDATE` or `NOOP`.
+
+# What counts as a durable fact (lean UPDATE)
+
+- Stable attributes: name, role, employer, team, timezone, language,
+  technical stack, recurring projects.
+- Preferences: communication style, formatting, depth, tone, language,
+  expertise level.
+- Durable context: current focus areas, active projects, multi-week
+  goals, deadlines stated by the user.
+- Explicit hand-offs: "remind me about X", "let's revisit Y later".
+
+# What NEVER justifies UPDATE (lean NOOP)
+
+- Credentials, API keys, passwords, payment or health details, IDs.
+- Facts about other people beyond the immediate professional context.
+- Transient turn state: one-off answers, code snippets, error messages,
+  file contents, search results.
+- Anything stated as third-party or retrieved context.
+- Facts already captured in `<existing_memory>`.
+"""
+
+
+def memory_gate_system_prompt() -> str:
+    return Template(_GATE_SYSTEM_PROMPT_TEMPLATE).render()
+
+
+_GATE_USER_PROMPT_TEMPLATE = """\
+User ID: {{ user_id }}
+
+<existing_memory>
+{{ existing_memory }}
+</existing_memory>
+
+<new_turn>
+user: {{ user_message }}
+assistant: {{ assistant_message }}
+</new_turn>
+
+Reply with the single word UPDATE or NOOP now.
+"""
+
+
+def memory_gate_user_prompt(
+    user_id: str,
+    existing_memory: str,
+    user_message: str,
+    assistant_message: str,
+) -> str:
+    existing = existing_memory.strip() or "(empty - this is the user's first turn)"
+    return Template(_GATE_USER_PROMPT_TEMPLATE).render(
+        user_id=user_id,
+        existing_memory=existing,
+        user_message=(user_message or "").strip(),
+        assistant_message=(assistant_message or "").strip(),
+    )