unique-user-memory 2026.24.0__tar.gz

unique_user_memory-2026.24.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.3
+Name: unique-user-memory
+Version: 2026.24.0
+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.24.0
+Requires-Dist: unique-toolkit>=2026.24.0
+Requires-Python: >=3.12, <4
+Description-Content-Type: text/markdown
+
+# Unique User Memory
+
+Postprocessor package for persistent per-user memory in Unique AI.

unique_user_memory-2026.24.0/README.md

@@ -0,0 +1,3 @@
+# Unique User Memory
+
+Postprocessor package for persistent per-user memory in Unique AI.

unique_user_memory-2026.24.0/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+name = "unique_user_memory"
+version = "2026.24.0"
+description = ""
+authors = [
+    { name = "Fabian Schläpfer", email = "fabian@unique.ch" },
+]
+readme = "README.md"
+license = { text = "Proprietary" }
+requires-python = ">=3.12,<4"
+dependencies = [
+    "jinja2>=3.1.6",
+    "pydantic>=2.8.2",
+    "unique-sdk>=2026.24.0",
+    "unique-toolkit>=2026.24.0",
+]
+
+[dependency-groups]
+dev = []
+
+[build-system]
+requires = ["uv_build>=0.7.19,<0.8"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+
+[tool.uv]
+exclude-newer = "2 weeks"
+constraint-dependencies = ["lxml>=5.0.0"]
+
+[tool.uv.exclude-newer-package]
+"unique-sdk" = false
+"unique-toolkit" = false
+
+[tool.uv.sources]
+unique-sdk = { workspace = true }
+unique-toolkit = { workspace = true }
+
+[tool.poe.tasks]
+lint = "ruff check ."
+lint-fix = "ruff check . --fix"
+format = "ruff format ."
+test = "pytest"
+typecheck = "basedpyright"
+depcheck = "deptry ."
+coverage = "pytest --cov=unique_user_memory --cov-report=term-missing"
+ci-typecheck = { shell = "bash $(git rev-parse --show-toplevel)/.github/scripts/dev.sh typecheck" }
+ci-coverage = { shell = "bash $(git rev-parse --show-toplevel)/.github/scripts/dev.sh coverage" }
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers --import-mode=importlib"
+asyncio_mode = "auto"
+markers = [
+    "ai: AI-authored or AI-generated tests",
+    "asyncio: asyncio tests",
+    "integration: integration tests that require API access or credentials",
+    "serial: tests that must run serially",
+    "unit: unit tests",
+    "verified: AI-generated tests with human verification",
+]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]
+
+[tool.deptry]
+known_first_party = ["unique_user_memory"]
+extend_exclude = ["unique_user_memory/tests"]
+
+[tool.deptry.per_rule_ignores]
+DEP002 = ["unique-sdk", "unique-toolkit"]
+DEP003 = ["unique_sdk", "unique_toolkit"]
+
+[tool.basedpyright]
+typeCheckingMode = "standard"
+include = ["unique_user_memory"]
+exclude = ["**/tests/**", "**/test_*.py"]
+
+[tool.ruff]
+target-version = "py311"
+
+[tool.ruff.lint]
+extend-select = ["I"]

unique_user_memory-2026.24.0/unique_user_memory/__init__.py

@@ -0,0 +1,4 @@
+from unique_user_memory.config import UserMemoryConfig
+from unique_user_memory.user_memory_postprocessor import UserMemoryPostprocessor
+
+__all__ = ["UserMemoryConfig", "UserMemoryPostprocessor"]

unique_user_memory-2026.24.0/unique_user_memory/config.py

@@ -0,0 +1,32 @@
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+from unique_toolkit._common.pydantic.rjsf_tags import RJSFMetaTag
+from unique_toolkit._common.validators import LMI
+from unique_toolkit.agentic.tools.config import get_configuration_dict
+from unique_toolkit.language_model.default_language_model import DEFAULT_GPT_4o
+from unique_toolkit.language_model.infos import LanguageModelInfo
+
+
+class UserMemoryConfig(BaseModel):
+    model_config = get_configuration_dict()
+
+    enabled: Annotated[bool, RJSFMetaTag.SpecialWidget.hidden()] = Field(
+        default=False,
+        description="Whether to enable persistent per-user memory.",
+    )
+    language_model: LMI = Field(
+        default=LanguageModelInfo.from_name(DEFAULT_GPT_4o),
+        description="The language model used for post-turn memory consolidation.",
+    )
+    max_tokens: int = Field(
+        default=2000,
+        ge=500,
+        le=8000,
+        description="Maximum size of the memory profile in tokens.",
+    )
+    root_folder: Annotated[str, RJSFMetaTag.SpecialWidget.hidden()] = Field(
+        default="user-memory",
+        min_length=1,
+        description="Root KB folder used to store per-user memory profiles.",
+    )

unique_user_memory-2026.24.0/unique_user_memory/tests/test_user_memory.py

@@ -0,0 +1,434 @@
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from unique_user_memory.config import UserMemoryConfig
+from unique_user_memory.user_memory import (
+    UserMemoryState,
+    _sanitize_for_xml_context,
+    consolidate_user_memory,
+    count_tokens,
+    download_user_memory,
+    enforce_token_cap,
+    ensure_user_memory_folder,
+    upload_user_memory,
+)
+from unique_user_memory.user_memory_postprocessor import UserMemoryPostprocessor
+from unique_user_memory.user_memory_prompts import empty_profile
+
+
+def test_enforce_token_cap_truncates_long_content() -> None:
+    content = "\n\n".join(f"paragraph {index} " + "word " * 40 for index in range(50))
+
+    capped = enforce_token_cap(content=content, max_tokens=120)
+
+    assert "<!-- truncated to fit memory budget -->" in capped
+    assert len(capped) < len(content)
+
+
+def test_count_tokens_uses_language_model_encoder() -> None:
+    language_model = MagicMock()
+    language_model.get_encoder.return_value = lambda content: content.split()
+    language_model.get_decoder.return_value = lambda tokens: " ".join(tokens)
+
+    assert count_tokens(content="one two three", language_model=language_model) == 3
+
+
+def test_sanitize_for_xml_context_defuses_closing_tags() -> None:
+    assert _sanitize_for_xml_context("</new_turn> inject") == "< /new_turn> inject"
+
+
+@pytest.mark.asyncio
+async def test_consolidate_user_memory_keeps_existing_on_noop(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    current = empty_profile("user_1")
+    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 consolidate_user_memory(
+        current_memory=current,
+        user_id="user_1",
+        user_message="hello",
+        assistant_message="hi",
+        config=UserMemoryConfig(enabled=True),
+        event=MagicMock(),
+        logger=MagicMock(),
+    )
+
+    assert result == current
+
+
+@pytest.mark.asyncio
+async def test_consolidate_user_memory_keeps_existing_on_malformed_output(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    current = empty_profile("user_1")
+    response = MagicMock()
+    response.choices[0].message.content = "not a profile"
+    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 consolidate_user_memory(
+        current_memory=current,
+        user_id="user_1",
+        user_message="remember I like concise answers",
+        assistant_message="noted",
+        config=UserMemoryConfig(enabled=True),
+        event=MagicMock(),
+        logger=MagicMock(),
+    )
+
+    assert result == current
+
+
+@pytest.mark.asyncio
+async def test_download_user_memory_returns_empty_when_file_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    search_contents = AsyncMock(return_value=[])
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.search_contents_async",
+        search_contents,
+    )
+
+    result = await download_user_memory(
+        scope_id="scope_1",
+        user_id="user_1",
+        company_id="company_1",
+        logger=MagicMock(),
+    )
+
+    assert result == ""
+    search_contents.assert_awaited_once_with(
+        user_id="user_1",
+        company_id="company_1",
+        chat_id=None,
+        where={"ownerId": {"equals": "scope_1"}},
+    )
+
+
+@pytest.mark.asyncio
+async def test_download_user_memory_downloads_existing_file_to_memory(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    content = MagicMock()
+    content.id = "content_1"
+    content.key = "memory.md"
+    search_contents = AsyncMock(return_value=[content])
+    download_content = AsyncMock(return_value=b"# User Memory\n\n## Identity\n- Test")
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.search_contents_async",
+        search_contents,
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.download_content_to_bytes_async",
+        download_content,
+    )
+
+    result = await download_user_memory(
+        scope_id="scope_1",
+        user_id="user_1",
+        company_id="company_1",
+        logger=MagicMock(),
+    )
+
+    assert result == "# User Memory\n\n## Identity\n- Test"
+    search_contents.assert_awaited_once_with(
+        user_id="user_1",
+        company_id="company_1",
+        chat_id=None,
+        where={"ownerId": {"equals": "scope_1"}},
+    )
+    download_content.assert_awaited_once_with(
+        user_id="user_1",
+        company_id="company_1",
+        content_id="content_1",
+        chat_id=None,
+    )
+
+
+@pytest.mark.asyncio
+async def test_ensure_user_memory_folder_returns_existing_user_folder(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    get_info = AsyncMock(
+        side_effect=[
+            {"id": "scope_root"},
+            {"id": "scope_user"},
+        ]
+    )
+    create_paths = AsyncMock()
+    add_access = AsyncMock()
+    get_groups = AsyncMock()
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.unique_sdk.Folder.get_info_async",
+        get_info,
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.unique_sdk.Folder.create_paths_async",
+        create_paths,
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.unique_sdk.Folder.add_access_async",
+        add_access,
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.unique_sdk.Group.get_groups_async",
+        get_groups,
+    )
+
+    result = await ensure_user_memory_folder(
+        user_id="user_1",
+        company_id="company_1",
+        root_folder="user-memory",
+        logger=MagicMock(),
+    )
+
+    assert result == "scope_user"
+    get_info.assert_any_await(
+        user_id="user_1",
+        company_id="company_1",
+        folderPath="/user-memory",
+    )
+    get_info.assert_any_await(
+        user_id="user_1",
+        company_id="company_1",
+        folderPath="/user-memory/user_1",
+    )
+    create_paths.assert_not_awaited()
+    get_groups.assert_not_awaited()
+    add_access.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_ensure_user_memory_folder_creates_private_user_folder_under_root(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    get_info = AsyncMock(
+        side_effect=[
+            {"id": "scope_root"},
+            RuntimeError("missing user folder"),
+        ]
+    )
+    create_paths = AsyncMock(return_value={"createdFolders": [{"id": "scope_user"}]})
+    add_access = AsyncMock()
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.unique_sdk.Folder.get_info_async",
+        get_info,
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.unique_sdk.Folder.create_paths_async",
+        create_paths,
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.unique_sdk.Folder.add_access_async",
+        add_access,
+    )
+
+    result = await ensure_user_memory_folder(
+        user_id="user_1",
+        company_id="company_1",
+        root_folder="user-memory",
+        logger=MagicMock(),
+    )
+
+    assert result == "scope_user"
+    create_paths.assert_awaited_once_with(
+        user_id="user_1",
+        company_id="company_1",
+        parentScopeId="scope_root",
+        relativePaths=["user_1"],
+        inheritAccess=False,
+    )
+    add_access.assert_awaited_once_with(
+        user_id="user_1",
+        company_id="company_1",
+        scopeId="scope_user",
+        scopeAccesses=[
+            {"entityId": "user_1", "type": "READ", "entityType": "USER"},
+            {"entityId": "user_1", "type": "WRITE", "entityType": "USER"},
+        ],
+        applyToSubScopes=True,
+    )
+
+
+@pytest.mark.asyncio
+async def test_ensure_user_memory_folder_returns_none_when_access_grant_fails_after_create(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    get_info = AsyncMock(
+        side_effect=[
+            {"id": "scope_root"},
+            RuntimeError("missing user folder"),
+        ]
+    )
+    create_paths = AsyncMock(return_value={"createdFolders": [{"id": "scope_user"}]})
+    grant_error = RuntimeError("grant failed")
+    add_access = AsyncMock(side_effect=grant_error)
+    logger = MagicMock()
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.unique_sdk.Folder.get_info_async",
+        get_info,
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.unique_sdk.Folder.create_paths_async",
+        create_paths,
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.unique_sdk.Folder.add_access_async",
+        add_access,
+    )
+
+    result = await ensure_user_memory_folder(
+        user_id="user_1",
+        company_id="company_1",
+        root_folder="user-memory",
+        logger=logger,
+    )
+
+    assert result is None
+    create_paths.assert_awaited_once_with(
+        user_id="user_1",
+        company_id="company_1",
+        parentScopeId="scope_root",
+        relativePaths=["user_1"],
+        inheritAccess=False,
+    )
+    add_access.assert_awaited_once_with(
+        user_id="user_1",
+        company_id="company_1",
+        scopeId="scope_user",
+        scopeAccesses=[
+            {"entityId": "user_1", "type": "READ", "entityType": "USER"},
+            {"entityId": "user_1", "type": "WRITE", "entityType": "USER"},
+        ],
+        applyToSubScopes=True,
+    )
+    logger.warning.assert_called_with(
+        "[user-memory] failed to grant read/write access on scope %s "
+        "for user %s: [%s] %s",
+        "scope_user",
+        "user_1",
+        "RuntimeError",
+        grant_error,
+    )
+
+
+@pytest.mark.asyncio
+async def test_upload_user_memory_writes_hidden_skip_ingestion_file(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    upload_content = AsyncMock()
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.upload_content_from_bytes_async",
+        upload_content,
+    )
+
+    result = await upload_user_memory(
+        scope_id="scope_1",
+        content="# User Memory\n\n## Identity\n- Test",
+        user_id="user_1",
+        company_id="company_1",
+        logger=MagicMock(),
+    )
+
+    assert result is True
+    upload_content.assert_awaited_once()
+    assert upload_content.call_args.kwargs["content"] == (
+        b"# User Memory\n\n## Identity\n- Test"
+    )
+    assert upload_content.call_args.kwargs["content_name"] == "memory.md"
+    assert upload_content.call_args.kwargs["mime_type"] == "text/markdown"
+    assert upload_content.call_args.kwargs["scope_id"] == "scope_1"
+    assert upload_content.call_args.kwargs["ingestion_config"] == {
+        "uniqueIngestionMode": "SKIP_INGESTION",
+        "hideInChat": True,
+    }
+
+
+@pytest.mark.asyncio
+async def test_user_memory_postprocessor_logs_success_when_upload_succeeds(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    updated_memory = "# User Memory\n\n## Identity\n- Updated"
+    consolidate = AsyncMock(return_value=updated_memory)
+    upload = AsyncMock(return_value=True)
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory_postprocessor.consolidate_user_memory",
+        consolidate,
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory_postprocessor.upload_user_memory",
+        upload,
+    )
+    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 = "noted"
+    logger = MagicMock()
+    postprocessor = UserMemoryPostprocessor(
+        config=UserMemoryConfig(enabled=True),
+        event=event,
+        state=UserMemoryState(scope_id="scope_1", text=empty_profile("user_1")),
+        logger=logger,
+    )
+
+    await postprocessor.run(loop_response)
+
+    upload.assert_awaited_once_with(
+        scope_id="scope_1",
+        content=updated_memory,
+        user_id="user_1",
+        company_id="company_1",
+        logger=logger,
+    )
+    logger.info.assert_any_call("[user-memory] memory updated and uploaded")
+
+
+@pytest.mark.asyncio
+async def test_user_memory_postprocessor_does_not_log_success_when_upload_fails(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    updated_memory = "# User Memory\n\n## Identity\n- Updated"
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory_postprocessor.consolidate_user_memory",
+        AsyncMock(return_value=updated_memory),
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory_postprocessor.upload_user_memory",
+        AsyncMock(return_value=False),
+    )
+    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 = "noted"
+    logger = MagicMock()
+    postprocessor = UserMemoryPostprocessor(
+        config=UserMemoryConfig(enabled=True),
+        event=event,
+        state=UserMemoryState(scope_id="scope_1", text=empty_profile("user_1")),
+        logger=logger,
+    )
+
+    await postprocessor.run(loop_response)
+
+    assert all(
+        call.args != ("[user-memory] memory updated and uploaded",)
+        for call in logger.info.call_args_list
+    )
+    logger.warning.assert_any_call("[user-memory] memory update was not uploaded")

unique_user_memory-2026.24.0/unique_user_memory/user_memory.py

@@ -0,0 +1,548 @@
+import re
+from dataclasses import dataclass
+from logging import Logger
+
+import unique_sdk
+from unique_toolkit.app import ChatEvent
+from unique_toolkit.content.functions import (
+    download_content_to_bytes_async,
+    search_contents_async,
+    upload_content_from_bytes_async,
+)
+from unique_toolkit.language_model import (
+    DEFAULT_GPT_4o,
+    LanguageModelMessages,
+    LanguageModelService,
+    LanguageModelSystemMessage,
+    LanguageModelUserMessage,
+    TypeDecoder,
+    TypeEncoder,
+)
+from unique_toolkit.language_model.infos import LanguageModelInfo
+
+from unique_user_memory.config import UserMemoryConfig
+from unique_user_memory.user_memory_prompts import (
+    SECTION_HEADINGS,
+    consolidation_system_prompt,
+    consolidation_user_prompt,
+    empty_profile,
+)
+
+MEMORY_FILENAME = "memory.md"
+MIME_TYPE = "text/markdown"
+_LLM_OUTPUT_HEADROOM_TOKENS = 200
+_TRUNCATION_MARKER = "\n\n<!-- truncated to fit memory budget -->"
+_DEFAULT_LANGUAGE_MODEL = LanguageModelInfo.from_name(DEFAULT_GPT_4o)
+_FRONTMATTER_RE = re.compile(r"^---\n.*?\n---\n", re.DOTALL)
+
+
+@dataclass(frozen=True)
+class UserMemoryState:
+    scope_id: str
+    text: str
+
+
+def _get_model_tokenizer(
+    *,
+    language_model: LanguageModelInfo,
+) -> tuple[TypeEncoder, TypeDecoder]:
+    model_info = language_model or _DEFAULT_LANGUAGE_MODEL
+    return model_info.get_encoder(), model_info.get_decoder()
+
+
+def _count_tokens(
+    *,
+    content: str,
+    encode: TypeEncoder,
+) -> int:
+    if not content:
+        return 0
+    return len(encode(content))
+
+
+def count_tokens(
+    *,
+    content: str,
+    language_model: LanguageModelInfo = _DEFAULT_LANGUAGE_MODEL,
+) -> int:
+    encode, _ = _get_model_tokenizer(language_model=language_model)
+    return _count_tokens(content=content, encode=encode)
+
+
+def enforce_token_cap(
+    *,
+    content: str,
+    max_tokens: int,
+    language_model: LanguageModelInfo = _DEFAULT_LANGUAGE_MODEL,
+) -> str:
+    if not content:
+        return content
+
+    encode, decode = _get_model_tokenizer(language_model=language_model)
+
+    if _count_tokens(content=content, encode=encode) <= max_tokens:
+        return content
+
+    marker_tokens = _count_tokens(content=_TRUNCATION_MARKER, encode=encode)
+    target = max(0, max_tokens - marker_tokens)
+    paragraphs = content.split("\n\n")
+    accepted: list[str] = []
+    running = 0
+    for paragraph in paragraphs:
+        paragraph_tokens = _count_tokens(content=paragraph + "\n\n", encode=encode)
+        if running + paragraph_tokens > target:
+            break
+        accepted.append(paragraph)
+        running += paragraph_tokens
+
+    if accepted:
+        truncated = "\n\n".join(accepted)
+    else:
+        truncated = decode(encode(content)[:target])
+
+    result = truncated.rstrip() + _TRUNCATION_MARKER
+    shrink = target
+    while _count_tokens(content=result, encode=encode) > max_tokens and shrink > 0:
+        shrink -= 1
+        body = decode(encode(result)[:shrink]).rstrip()
+        result = body + _TRUNCATION_MARKER
+
+    if _count_tokens(content=result, encode=encode) > max_tokens:
+        result = decode(encode(result)[:max_tokens])
+
+    return result
+
+
+async def load_user_memory(
+    *,
+    event: ChatEvent,
+    config: UserMemoryConfig,
+    logger: Logger,
+) -> UserMemoryState | None:
+    user_id = event.user_id
+    company_id = event.company_id
+    if not user_id or not company_id:
+        logger.warning("[user-memory] empty user_id/company_id - skipping memory load")
+        return None
+
+    scope_id = await ensure_user_memory_folder(
+        user_id=user_id,
+        company_id=company_id,
+        root_folder=config.root_folder,
+        logger=logger,
+    )
+    if scope_id is None:
+        logger.info("[user-memory] folder ensure failed - running without memory")
+        return None
+
+    text = await download_user_memory(
+        scope_id=scope_id,
+        user_id=user_id,
+        company_id=company_id,
+        logger=logger,
+    )
+    return UserMemoryState(
+        scope_id=scope_id,
+        text=enforce_token_cap(
+            content=text,
+            max_tokens=config.max_tokens,
+            language_model=config.language_model,
+        ),
+    )
+
+
+async def ensure_user_memory_folder(
+    *,
+    user_id: str,
+    company_id: str,
+    root_folder: str,
+    logger: Logger,
+) -> str | None:
+    root_scope_id = await _resolve_root_folder(
+        user_id=user_id,
+        company_id=company_id,
+        root_folder=root_folder,
+        logger=logger,
+    )
+    if root_scope_id is None:
+        return None
+
+    user_folder_path = f"/{root_folder.strip('/')}/{user_id}"
+    scope_id: str | None = None
+    try:
+        info = await unique_sdk.Folder.get_info_async(
+            user_id=user_id,
+            company_id=company_id,
+            folderPath=user_folder_path,
+        )
+        return info.get("id")
+    except Exception:
+        logger.warning("[user-memory] user memory folder not found - creating new one")
+
+    try:
+        created = await unique_sdk.Folder.create_paths_async(
+            user_id=user_id,
+            company_id=company_id,
+            parentScopeId=root_scope_id,
+            relativePaths=[user_id],
+            inheritAccess=False,
+        )
+    except Exception as exc:
+        logger.warning(
+            "[user-memory] failed to create user folder %s: [%s] %s",
+            user_folder_path,
+            type(exc).__name__,
+            exc,
+        )
+        return None
+
+    created_folders = (created or {}).get("createdFolders", []) or []
+    if len(created_folders) > 1:
+        logger.warning(
+            "[user-memory] create_paths returned %d folders for %s, "
+            "expected exactly 1; using the first one",
+            len(created_folders),
+            user_folder_path,
+        )
+    scope_id = created_folders[0].get("id") if created_folders else None
+    if not scope_id:
+        logger.warning(
+            "[user-memory] create_paths returned no folder id for %s",
+            user_folder_path,
+        )
+        return None
+
+    try:
+        await unique_sdk.Folder.add_access_async(
+            user_id=user_id,
+            company_id=company_id,
+            scopeId=scope_id,
+            scopeAccesses=[
+                {
+                    "entityId": user_id,
+                    "type": "READ",
+                    "entityType": "USER",
+                },
+                {
+                    "entityId": user_id,
+                    "type": "WRITE",
+                    "entityType": "USER",
+                },
+            ],
+            applyToSubScopes=True,
+        )
+    except Exception as exc:
+        logger.warning(
+            "[user-memory] failed to grant read/write access on scope %s "
+            "for user %s: [%s] %s",
+            scope_id,
+            user_id,
+            type(exc).__name__,
+            exc,
+        )
+        return None
+
+    return scope_id
+
+
+async def _resolve_root_folder(
+    *,
+    user_id: str,
+    company_id: str,
+    root_folder: str,
+    logger: Logger,
+) -> str | None:
+    root_path = f"/{root_folder.strip('/')}"
+    try:
+        root_info = await unique_sdk.Folder.get_info_async(
+            user_id=user_id,
+            company_id=company_id,
+            folderPath=root_path,
+        )
+    except Exception as exc:
+        logger.warning(
+            "[user-memory] failed to resolve pre-provisioned root folder %s: [%s] %s",
+            root_path,
+            type(exc).__name__,
+            exc,
+        )
+        return None
+
+    root_scope_id = root_info.get("id")
+    if not root_scope_id:
+        logger.warning(
+            "[user-memory] root folder lookup returned no id for %s",
+            root_path,
+        )
+        return None
+
+    return root_scope_id
+
+
+async def download_user_memory(
+    *,
+    scope_id: str,
+    user_id: str,
+    company_id: str,
+    logger: Logger,
+) -> str:
+    try:
+        contents = await search_contents_async(
+            user_id=user_id,
+            company_id=company_id,
+            chat_id=None,
+            where={"ownerId": {"equals": scope_id}},
+        )
+    except Exception as exc:
+        logger.warning(
+            "[user-memory] failed to list contents in scope %s: [%s] %s",
+            scope_id,
+            type(exc).__name__,
+            exc,
+        )
+        return ""
+
+    memory_content = next(
+        (content for content in contents if (content.key or "") == MEMORY_FILENAME),
+        None,
+    )
+    if memory_content is None:
+        logger.debug(
+            "[user-memory] no %s in scope %s - first turn for this user",
+            MEMORY_FILENAME,
+            scope_id,
+        )
+        return ""
+
+    try:
+        content_bytes = await download_content_to_bytes_async(
+            user_id=user_id,
+            company_id=company_id,
+            content_id=memory_content.id,
+            chat_id=None,
+        )
+        text = content_bytes.decode("utf-8", errors="replace")
+        logger.info(
+            "[user-memory] downloaded %s (%d bytes) from scope %s",
+            MEMORY_FILENAME,
+            len(content_bytes),
+            scope_id,
+        )
+        return text
+    except Exception as exc:
+        logger.warning(
+            "[user-memory] failed to download %s from scope %s: [%s] %s",
+            MEMORY_FILENAME,
+            scope_id,
+            type(exc).__name__,
+            exc,
+        )
+        return ""
+
+
+async def upload_user_memory(
+    *,
+    scope_id: str,
+    content: str,
+    user_id: str,
+    company_id: str,
+    logger: Logger,
+) -> bool:
+    if not content.strip():
+        logger.warning(
+            "[user-memory] refusing to upload empty memory file to scope %s",
+            scope_id,
+        )
+        return False
+
+    try:
+        await upload_content_from_bytes_async(
+            user_id=user_id,
+            company_id=company_id,
+            content=content.encode("utf-8"),
+            content_name=MEMORY_FILENAME,
+            mime_type=MIME_TYPE,
+            scope_id=scope_id,
+            ingestion_config={
+                "uniqueIngestionMode": "SKIP_INGESTION",
+                "hideInChat": True,
+            },
+        )
+        logger.info(
+            "[user-memory] uploaded %s (%d bytes) to scope %s",
+            MEMORY_FILENAME,
+            len(content.encode("utf-8")),
+            scope_id,
+        )
+        return True
+    except Exception as exc:
+        logger.error(
+            "[user-memory] upload failed for scope %s: [%s] %s",
+            scope_id,
+            type(exc).__name__,
+            exc,
+            exc_info=True,
+        )
+        return False
+
+
+async def consolidate_user_memory(
+    *,
+    current_memory: str,
+    user_id: str,
+    user_message: str,
+    assistant_message: str,
+    config: UserMemoryConfig,
+    event: ChatEvent,
+    logger: Logger,
+) -> str:
+    safe_current = enforce_token_cap(
+        content=current_memory,
+        max_tokens=config.max_tokens,
+        language_model=config.language_model,
+    )
+    logger.info(
+        "[user-memory] consolidating turn - existing_memory_tokens=%d | "
+        "user_msg_chars=%d | assistant_msg_chars=%d",
+        count_tokens(content=safe_current, language_model=config.language_model),
+        len(user_message or ""),
+        len(assistant_message or ""),
+    )
+
+    if not (user_message or "").strip() and not (assistant_message or "").strip():
+        return safe_current or enforce_token_cap(
+            content=empty_profile(user_id),
+            max_tokens=config.max_tokens,
+            language_model=config.language_model,
+        )
+
+    if not safe_current.strip():
+        safe_current = empty_profile(user_id)
+
+    try:
+        llm_service = LanguageModelService(event)
+    except Exception as exc:
+        logger.error(
+            "[user-memory] cannot construct LanguageModelService: [%s] %s",
+            type(exc).__name__,
+            exc,
+        )
+        return safe_current
+
+    messages = LanguageModelMessages(
+        [
+            LanguageModelSystemMessage(
+                content=consolidation_system_prompt(config.max_tokens)
+            ),
+            LanguageModelUserMessage(
+                content=consolidation_user_prompt(
+                    user_id=user_id,
+                    existing_memory=safe_current,
+                    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=config.language_model.name,
+            other_options={
+                "max_tokens": config.max_tokens + _LLM_OUTPUT_HEADROOM_TOKENS,
+            },
+        )
+    except Exception as exc:
+        logger.warning(
+            "[user-memory] consolidation LLM call failed (model=%s): [%s] %s",
+            config.language_model.name,
+            type(exc).__name__,
+            exc,
+        )
+        return safe_current
+
+    try:
+        raw = response.choices[0].message.content or ""
+    except Exception as exc:
+        logger.warning(
+            "[user-memory] could not extract content from LLM response: [%s] %s",
+            type(exc).__name__,
+            exc,
+        )
+        return safe_current
+
+    if not isinstance(raw, str):
+        logger.warning(
+            "[user-memory] LLM returned non-string content (%s)",
+            type(raw).__name__,
+        )
+        return safe_current
+
+    if raw.strip().upper() == "NOOP":
+        logger.info("[user-memory] consolidation NOOP - keeping existing memory")
+        return safe_current
+
+    candidate = _strip_code_fences(raw).strip()
+    if not _is_well_formed_profile(candidate):
+        logger.warning(
+            "[user-memory] LLM output did not look like a profile (%d chars)",
+            len(candidate),
+        )
+        return safe_current
+
+    capped = enforce_token_cap(
+        content=candidate,
+        max_tokens=config.max_tokens,
+        language_model=config.language_model,
+    )
+    if (
+        safe_current
+        and _FRONTMATTER_RE.sub("", capped).strip()
+        == _FRONTMATTER_RE.sub("", safe_current).strip()
+    ):
+        logger.debug("[user-memory] memory body unchanged - skipping update")
+        return safe_current
+
+    logger.info(
+        "[user-memory] consolidation produced %d tokens (cap=%d)",
+        count_tokens(content=capped, language_model=config.language_model),
+        config.max_tokens,
+    )
+    return capped
+
+
+def _sanitize_for_xml_context(text: str) -> str:
+    return text.replace("</", "< /")
+
+
+def _is_well_formed_profile(content: str) -> bool:
+    if not content or len(content.strip()) < 20:
+        return False
+    if _FRONTMATTER_RE.match(content):
+        return True
+    return "## Identity" in content or "# User Memory" in content
+
+
+def _strip_code_fences(text: str) -> str:
+    stripped = text.strip()
+    if not stripped.startswith("```"):
+        return text
+    lines = stripped.splitlines()
+    if len(lines) >= 3 and lines[-1].strip() == "```":
+        return "\n".join(lines[1:-1])
+    return text
+
+
+def looks_empty_profile(content: str) -> bool:
+    if not content:
+        return True
+    return content.count("_(empty)_") >= len(SECTION_HEADINGS)
+
+
+def prompt_section(memory: str | None) -> str:
+    if not memory or not memory.strip():
+        return ""
+    return memory.strip()

unique_user_memory-2026.24.0/unique_user_memory/user_memory_postprocessor.py

@@ -0,0 +1,71 @@
+from logging import Logger
+
+from unique_toolkit.agentic.postprocessor.postprocessor_manager import Postprocessor
+from unique_toolkit.app.schemas import ChatEvent
+from unique_toolkit.language_model.schemas import LanguageModelStreamResponse
+
+from unique_user_memory.config import UserMemoryConfig
+from unique_user_memory.user_memory import (
+    UserMemoryState,
+    consolidate_user_memory,
+    upload_user_memory,
+)
+
+
+class UserMemoryPostprocessor(Postprocessor):
+    def __init__(
+        self,
+        *,
+        config: UserMemoryConfig,
+        event: ChatEvent,
+        state: UserMemoryState,
+        logger: Logger,
+    ) -> None:
+        super().__init__(name="UserMemoryPostprocessor")
+        self._config = config
+        self._event = event
+        self._state = state
+        self._logger = logger
+        self._new_memory: str | None = None
+
+    async def run(self, loop_response: LanguageModelStreamResponse) -> None:
+        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
+
+        self._new_memory = await consolidate_user_memory(
+            current_memory=self._state.text,
+            user_id=user_id,
+            user_message=self._event.payload.user_message.text or "",
+            assistant_message=loop_response.message.text or "",
+            config=self._config,
+            event=self._event,
+            logger=self._logger,
+        )
+
+        if self._new_memory == self._state.text:
+            self._logger.debug("[user-memory] consolidation NOOP - skipping upload")
+            return
+
+        uploaded = await upload_user_memory(
+            scope_id=self._state.scope_id,
+            content=self._new_memory,
+            user_id=user_id,
+            company_id=company_id,
+            logger=self._logger,
+        )
+        if not uploaded:
+            self._logger.warning("[user-memory] memory update was not uploaded")
+            return
+
+        self._logger.info("[user-memory] memory updated and uploaded")
+
+    def apply_postprocessing_to_response(
+        self, loop_response: LanguageModelStreamResponse
+    ) -> bool:
+        return False
+
+    async def remove_from_text(self, text: str) -> str:
+        return text

unique_user_memory-2026.24.0/unique_user_memory/user_memory_prompts.py

@@ -0,0 +1,185 @@
+from datetime import datetime, timezone
+
+from jinja2 import Template
+
+SECTION_HEADINGS: tuple[str, ...] = (
+    "Identity",
+    "Communication Preferences",
+    "Work Context",
+    "Skills & Expertise",
+    "Recent Topics",
+    "Open Questions / Follow-ups",
+)
+
+_EMPTY_PROFILE_TEMPLATE = """\
+---
+user_id: {{ user_id }}
+schema_version: 1
+last_updated: {{ timestamp }}
+turn_count: 0
+---
+
+# User Memory
+
+{% for heading in section_headings -%}
+## {{ heading }}
+_(empty)_
+{% if not loop.last %}
+{% endif %}
+{% endfor -%}
+"""
+
+
+def empty_profile(user_id: str) -> str:
+    timestamp = datetime.now(timezone.utc).isoformat(timespec="seconds")
+    return Template(_EMPTY_PROFILE_TEMPLATE).render(
+        user_id=user_id,
+        timestamp=timestamp,
+        section_headings=SECTION_HEADINGS,
+    )
+
+
+_CONSOLIDATION_SYSTEM_PROMPT_TEMPLATE = """\
+You are a memory-consolidation engine for the Unique AI platform.
+
+Your sole job is to maintain a structured Markdown profile of an end
+user, distilled from their conversations with AI assistants. The profile
+is read on every future turn and shapes how the assistant addresses,
+helps, and remembers the user. It is therefore a high-leverage artefact:
+small mistakes in extraction compound across every future conversation.
+
+# Inputs
+
+You receive two XML blocks:
+
+1. `<existing_memory>` - the current profile file (Markdown, with YAML
+   frontmatter). May be empty on the user's first turn.
+2. `<new_turn>` - the most recent user message and the assistant's
+   reply, prefixed with `user:` and `assistant:`.
+
+# Output
+
+Return the complete, rewritten profile file as Markdown - frontmatter
+followed by the body. Do NOT emit a diff. Do NOT wrap the output in
+``` fences. Do NOT add commentary before or after the file.
+
+The body MUST contain exactly these section headings, in this order, even
+when a section is empty (use the literal string `_(empty)_` as a placeholder):
+
+{{ section_list }}
+
+# Operations
+
+For each candidate fact in `<new_turn>`, decide one of:
+
+- ADD - the fact is new and stable enough to remember (preferences,
+  identity attributes, ongoing projects, skills, dated topics). Add it as
+  a bullet in the most appropriate section.
+- UPDATE - the fact refines or supersedes an existing bullet. Edit
+  the existing bullet in place; do not add a duplicate.
+- DELETE - the new turn explicitly contradicts or invalidates an
+  existing bullet that is not worth keeping as history. Remove it.
+- NOOP - the new turn contains no facts about the user (small talk,
+  factual questions, code requests, abstract discussion). Output the
+  single word `NOOP` and nothing else. The caller keeps the existing
+  memory unchanged and skips the write entirely.
+
+Prefer UPDATE over ADD when in doubt - duplication is the most common
+failure mode of memory systems.
+
+# What to extract
+
+ADD/UPDATE for facts that are:
+
+- Stable - true beyond the current chat (name, role, employer,
+  team, timezone, language, technical stack, recurring projects).
+- Preference-shaped - communication style, formatting, depth,
+  tone, language, expertise level, examples preferred over theory.
+- Contextual but durable - current focus areas, active projects,
+  multi-week goals, deadlines mentioned by the user.
+- Hand-offs - explicit "let's revisit X later", "remind me about
+  Y", "I'll come back to Z" go into "Open Questions / Follow-ups".
+
+NEVER extract:
+
+- Sensitive credentials, API keys, passwords, OTPs, payment info,
+  health-record details, government IDs. If the user pastes any of
+  these, ignore the value entirely.
+- Information about other named individuals beyond the immediate
+  professional context.
+- Transient turn-level state: one-off factual answers, code snippets,
+  error messages, file contents, search results.
+- Anything stated as third-party information or retrieved context.
+
+# Token budget - STRICT
+
+The complete file MUST be <= {{ max_tokens }} tokens.
+When approaching the budget, drop content in this priority order:
+
+1. Oldest entries in Recent Topics.
+2. Resolved or stale entries in Open Questions / Follow-ups.
+3. Fold low-signal Work Context bullets into a one-line summary.
+4. Fold low-signal Skills & Expertise bullets into broader categories.
+5. Identity and Communication Preferences - never drop, only tighten.
+
+# Current date and time
+
+The current UTC date and time is **{{ now_datetime }}**. You do NOT know the date from any other source - always use this supplied value. Never guess or infer the date.
+
+# Frontmatter rules
+
+- Preserve `user_id` and `schema_version` from `<existing_memory>` exactly.
+- Set `last_updated` to the supplied current UTC timestamp ({{ now_datetime }}).
+- Increment `turn_count` by 1.
+- If `<existing_memory>` is empty, initialize with `schema_version: 1`,
+  `turn_count: 1`, and the user_id supplied in the user message.
+
+# Style
+
+- Use `-` markdown bullets, no nesting beyond two levels.
+- Keep bullets short.
+- For dated entries in Recent Topics, prefix with `YYYY-MM-DD HH:MM UTC:`
+  using the supplied current date and time ({{ now_datetime }}).
+- No emojis in section headings.
+"""
+
+
+def consolidation_system_prompt(max_tokens: int) -> str:
+    section_list = "\n".join(f"- ## {heading}" for heading in SECTION_HEADINGS)
+    now = datetime.now(timezone.utc)
+    return Template(_CONSOLIDATION_SYSTEM_PROMPT_TEMPLATE).render(
+        max_tokens=max_tokens,
+        section_list=section_list,
+        now_datetime=now.strftime("%Y-%m-%d %H:%M UTC"),
+    )
+
+
+_CONSOLIDATION_USER_PROMPT_TEMPLATE = """\
+User ID: {{ user_id }}
+
+<existing_memory>
+{{ existing_memory }}
+</existing_memory>
+
+<new_turn>
+user: {{ user_message }}
+assistant: {{ assistant_message }}
+</new_turn>
+
+Return the complete rewritten profile file now.
+"""
+
+
+def consolidation_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(_CONSOLIDATION_USER_PROMPT_TEMPLATE).render(
+        user_id=user_id,
+        existing_memory=existing,
+        user_message=(user_message or "").strip(),
+        assistant_message=(assistant_message or "").strip(),
+    )