unique-user-memory 2026.36.0.dev2__tar.gz → 2026.36.0.dev4__tar.gz

{unique_user_memory-2026.36.0.dev2 → unique_user_memory-2026.36.0.dev4}/PKG-INFO

@@ -1,14 +1,14 @@
 Metadata-Version: 2.3
 Name: unique-user-memory
-Version: 2026.36.0.dev2
+Version: 2026.36.0.dev4
 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.36.0.dev1,<2026.36.0rc0
-Requires-Dist: unique-toolkit>=2026.36.0.dev6,<2026.36.0rc0
+Requires-Dist: unique-sdk>=2026.36.0.dev5,<2026.36.0rc0
+Requires-Dist: unique-toolkit>=2026.36.0.dev12,<2026.36.0rc0
 Requires-Python: >=3.12, <4
 Description-Content-Type: text/markdown
 
@@ -33,7 +33,7 @@ The memory file is intentionally small and structured. It is rewritten as a full
 ## Lifecycle
 
 1. The orchestrator enables memory when `space.allow_user_memory` is true.
-2. The orchestrator emits a **Loading context memory** Step, then `load_user_memory(...)` resolves the pre-provisioned root folder, ensures a private child folder for the current user, and downloads `/user-memory/<user_id>/memory.md` if it exists.
+2. The orchestrator emits a **Loading context memory** Step, then `load_user_memory(...)` resolves the user's private memory folder — canonical `/home-<user_id>/<root_folder>`, falling back to the legacy `/<root_folder>/<user_id>` leaf for not-yet-migrated users, provisioning the home folder if neither exists — and downloads `memory.md` from it if present.
 3. When load returns a `UserMemoryState`, that Step is completed with a **Context memory** detail entry (`type: UserMemory`) that the chat frontend renders as a badge opening Settings → Context Memory. A successful `None` return (soft skip) completes the Step without the entry; a raised exception marks the Step failed.
 4. If memory was loaded, `profile_body(...)` of its text is passed into the agent context for the current turn — the prompt only gets the Markdown body, while the postprocessor keeps the full file because it needs the frontmatter to carry `turn_count` forward.
 5. `UserMemoryPostprocessor` runs after the assistant response.
@@ -43,13 +43,18 @@ The memory file is intentionally small and structured. It is rewritten as a full
 
 ## Storage Model
 
-Memory is stored in Unique content as Markdown:
+Memory is stored in Unique content as Markdown, under each user's own
+root-level home folder (UN-24823):
 
 ```text
-/<root_folder>/<user_id>/memory.md
+/home-<user_id>/<root_folder>/memory.md
 ```
 
-By default, `root_folder` is `user-memory`. The root folder must already exist. The package creates the per-user child folder when needed.
+By default, `root_folder` is `user-memory`. There is no shared root folder —
+each user's home is created by node-ingestion (or, if missing, by this
+package) with an exclusive owner ACL, so memory is never company-writable
+(UN-24764). Users whose memory has not yet been migrated to their home
+folder are still read from the legacy location, `/<root_folder>/<user_id>/memory.md`.
 
 ## Profile Format
 
@@ -106,7 +111,7 @@ config = UserMemoryConfig(
 | `use_orchestrator_language_model` | `True` | When true, consolidation and load-time token capping use the model the orchestrator passes in and `language_model` is ignored. Set to `False` to use the configured `language_model` for both. |
 | `language_model` | `DEFAULT_GPT_4o` | Model used to consolidate the latest turn and to tokenize `memory.md` at load time when `use_orchestrator_language_model` is `False`. |
 | `max_tokens` | `2000` | Maximum profile size. Must be between 500 and 8000 tokens. |
-| `root_folder` | `user-memory` | Root KB folder that contains per-user memory folders. |
+| `root_folder` | `user-memory` | Subfolder name under each user's home folder (`/home-<user_id>/<root_folder>`) that holds the memory profile; also read as a legacy fallback at `/<root_folder>/<user_id>`. |
 
 ## Integration
 

{unique_user_memory-2026.36.0.dev2 → unique_user_memory-2026.36.0.dev4}/README.md

@@ -19,7 +19,7 @@ The memory file is intentionally small and structured. It is rewritten as a full
 ## Lifecycle
 
 1. The orchestrator enables memory when `space.allow_user_memory` is true.
-2. The orchestrator emits a **Loading context memory** Step, then `load_user_memory(...)` resolves the pre-provisioned root folder, ensures a private child folder for the current user, and downloads `/user-memory/<user_id>/memory.md` if it exists.
+2. The orchestrator emits a **Loading context memory** Step, then `load_user_memory(...)` resolves the user's private memory folder — canonical `/home-<user_id>/<root_folder>`, falling back to the legacy `/<root_folder>/<user_id>` leaf for not-yet-migrated users, provisioning the home folder if neither exists — and downloads `memory.md` from it if present.
 3. When load returns a `UserMemoryState`, that Step is completed with a **Context memory** detail entry (`type: UserMemory`) that the chat frontend renders as a badge opening Settings → Context Memory. A successful `None` return (soft skip) completes the Step without the entry; a raised exception marks the Step failed.
 4. If memory was loaded, `profile_body(...)` of its text is passed into the agent context for the current turn — the prompt only gets the Markdown body, while the postprocessor keeps the full file because it needs the frontmatter to carry `turn_count` forward.
 5. `UserMemoryPostprocessor` runs after the assistant response.
@@ -29,13 +29,18 @@ The memory file is intentionally small and structured. It is rewritten as a full
 
 ## Storage Model
 
-Memory is stored in Unique content as Markdown:
+Memory is stored in Unique content as Markdown, under each user's own
+root-level home folder (UN-24823):
 
 ```text
-/<root_folder>/<user_id>/memory.md
+/home-<user_id>/<root_folder>/memory.md
 ```
 
-By default, `root_folder` is `user-memory`. The root folder must already exist. The package creates the per-user child folder when needed.
+By default, `root_folder` is `user-memory`. There is no shared root folder —
+each user's home is created by node-ingestion (or, if missing, by this
+package) with an exclusive owner ACL, so memory is never company-writable
+(UN-24764). Users whose memory has not yet been migrated to their home
+folder are still read from the legacy location, `/<root_folder>/<user_id>/memory.md`.
 
 ## Profile Format
 
@@ -92,7 +97,7 @@ config = UserMemoryConfig(
 | `use_orchestrator_language_model` | `True` | When true, consolidation and load-time token capping use the model the orchestrator passes in and `language_model` is ignored. Set to `False` to use the configured `language_model` for both. |
 | `language_model` | `DEFAULT_GPT_4o` | Model used to consolidate the latest turn and to tokenize `memory.md` at load time when `use_orchestrator_language_model` is `False`. |
 | `max_tokens` | `2000` | Maximum profile size. Must be between 500 and 8000 tokens. |
-| `root_folder` | `user-memory` | Root KB folder that contains per-user memory folders. |
+| `root_folder` | `user-memory` | Subfolder name under each user's home folder (`/home-<user_id>/<root_folder>`) that holds the memory profile; also read as a legacy fallback at `/<root_folder>/<user_id>`. |
 
 ## Integration
 

{unique_user_memory-2026.36.0.dev2 → unique_user_memory-2026.36.0.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_user_memory"
-version = "2026.36.0.dev2"
+version = "2026.36.0.dev4"
 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.36.0.dev1,<2026.36.0rc0",
-    "unique-toolkit>=2026.36.0.dev6,<2026.36.0rc0",
+    "unique-sdk>=2026.36.0.dev5,<2026.36.0rc0",
+    "unique-toolkit>=2026.36.0.dev12,<2026.36.0rc0",
 ]
 
 [dependency-groups]

{unique_user_memory-2026.36.0.dev2 → unique_user_memory-2026.36.0.dev4}/unique_user_memory/config.py

@@ -16,34 +16,28 @@ class UserMemoryConfig(BaseModel):
     use_orchestrator_language_model: bool = Field(
         default=True,
         description=(
-            "When true, post-turn memory consolidation uses the orchestrator's "
-            "language model and the configured 'language_model' is ignored. "
-            "When false, the configured 'language_model' is used."
+            "Use the orchestrator's language model to update memory. "
+            "Turn off to use the language model configured below instead."
         ),
     )
     language_model: LMI = Field(
         default=LanguageModelInfo.from_name(DEFAULT_LANGUAGE_MODEL),
-        description=(
-            "The language model used for post-turn memory consolidation when "
-            "'Use Orchestrator Language Model' is false."
-        ),
+        description="Language model used to update memory when the orchestrator's model is not used.",
     )
     max_tokens: Annotated[int, RJSFMetaTag.SpecialWidget.hidden()] = Field(
         default=2000,
         ge=500,
         le=8000,
-        description="Maximum size of the memory profile in tokens.",
+        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."
-        ),
+        description="Skip memory updates for turns that add no new information, to save cost.",
     )
     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.",
+        # Name used under the user's own home folder (UN-24823); also read
+        # as a legacy fallback for users not yet migrated (UN-24896).
+        description="Folder used to store the user's memory profile.",
     )

{unique_user_memory-2026.36.0.dev2 → unique_user_memory-2026.36.0.dev4}/unique_user_memory/tests/test_user_memory.py

@@ -26,6 +26,7 @@ from unique_user_memory.config import UserMemoryConfig
 from unique_user_memory.user_memory import (
     UserMemoryState,
     _gate_max_tokens,
+    _is_well_formed_profile,
     _sanitize_for_xml_context,
     condense_user_memory,
     consolidate_user_memory,
@@ -41,6 +42,7 @@ from unique_user_memory.user_memory import (
 from unique_user_memory.user_memory_message_log import UserMemoryMessageLogger
 from unique_user_memory.user_memory_postprocessor import UserMemoryPostprocessor
 from unique_user_memory.user_memory_prompts import (
+    condensation_system_prompt,
     consolidation_system_prompt,
     empty_profile,
     memory_gate_system_prompt,
@@ -49,6 +51,23 @@ from unique_user_memory.user_memory_prompts import (
 _TEST_LANGUAGE_MODEL = LanguageModelInfo.from_name(DEFAULT_LANGUAGE_MODEL)
 
 
+def _complete_profile_body(
+    identity: str = "- Prefers concise answers",
+    *,
+    legacy_title: bool = False,
+) -> str:
+    sections = (
+        f"## Identity\n{identity}",
+        "## Communication Preferences\n_(empty)_",
+        "## Work Context\n_(empty)_",
+        "## Skills & Expertise\n_(empty)_",
+        "## Follow-ups\n_(empty)_",
+        "## Recent Topics\n_(empty)_",
+    )
+    body = "\n\n".join(sections)
+    return f"# User Memory\n\n{body}" if legacy_title else body
+
+
 def _chat_event() -> ChatEvent:
     return ChatEvent(
         id="event_1",
@@ -111,6 +130,59 @@ def test_recent_topics_is_last_section_and_deduplicated() -> None:
     assert "do NOT also log that same information" in consolidation_prompt
 
 
+@pytest.mark.ai
+def test_generated_profile_templates_start_with_identity_without_document_title() -> (
+    None
+):
+    """Purpose: Verify new profile output omits the obsolete document-level title.
+    Why this matters: Persistent memory should expose only its meaningful H2 sections.
+    Setup summary: Render empty and LLM prompts, then assert the required start format.
+    """
+    profile = empty_profile("user_1")
+    prompts = (
+        consolidation_system_prompt(2000),
+        condensation_system_prompt(
+            max_tokens=2000,
+            current_tokens=2200,
+            target_tokens=1800,
+        ),
+    )
+
+    assert profile_body(profile).startswith("## Identity")
+    assert "# User Memory" not in profile
+    assert all("starting with\n`## Identity`" in prompt for prompt in prompts)
+    assert all(
+        "Do NOT add a document-level `# User Memory` title" in prompt
+        for prompt in prompts
+    )
+
+
+@pytest.mark.ai
+@pytest.mark.parametrize("legacy_title", [False, True])
+def test_well_formed_profile_accepts_current_and_legacy_complete_profiles(
+    legacy_title: bool,
+) -> None:
+    """Purpose: Verify validation supports titleless output and stored legacy profiles.
+    Why this matters: New rewrites must migrate format without breaking old memories.
+    Setup summary: Validate complete profiles with and without the former H1 title.
+    """
+    assert _is_well_formed_profile(_complete_profile_body(legacy_title=legacy_title))
+
+
+@pytest.mark.ai
+def test_well_formed_profile_rejects_missing_required_section() -> None:
+    """Purpose: Verify rewritten profiles retain every required H2 section.
+    Why this matters: A rewrite must not silently erase a category of user memory.
+    Setup summary: Remove Work Context from a complete profile and validate rejection.
+    """
+    profile = _complete_profile_body().replace(
+        "## Work Context\n_(empty)_\n\n",
+        "",
+    )
+
+    assert not _is_well_formed_profile(profile)
+
+
 def test_profile_body_strips_frontmatter() -> None:
     # The orchestrator renders this into the system prompt, where the
     # bookkeeping fields are noise for the model.
@@ -190,7 +262,7 @@ async def test_fit_user_memory_condenses_before_hard_cut(
         f"- fact number {index} that is fairly wordy about the user"
         for index in range(400)
     )
-    condensed = "# User Memory\n\n## Identity\n- concise summary of the user"
+    condensed = _complete_profile_body("- concise summary of the user")
     condense = AsyncMock(return_value=condensed)
     monkeypatch.setattr(
         "unique_user_memory.user_memory.condense_user_memory",
@@ -264,10 +336,11 @@ async def test_condense_user_memory_accepts_frontmatter_output(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     """Accept legacy LLM output while returning only the condensed profile body."""
-    condensed = "# User Memory\n\n## Identity\n- concise summary"
+    condensed = _complete_profile_body("- concise summary")
     response = MagicMock()
     response.choices[0].message.content = (
-        "---\nuser_id: stale-user\nturn_count: 99\n---\n\n" + condensed
+        "---\nuser_id: stale-user\nturn_count: 99\n---\n\n"
+        + _complete_profile_body("- concise summary", legacy_title=True)
     )
     llm_service = MagicMock()
     llm_service.complete_async = AsyncMock(return_value=response)
@@ -296,8 +369,8 @@ async def test_user_memory_llm_paths_forward_event_attribution(
     Why this matters: Every user-memory ModelUsage row must link to its chat.
     Setup summary: Exercise all shared service paths and inspect toolkit calls.
     """
-    rewritten = "# User Memory\n\n## Identity\n- Prefers concise answers"
-    condensed = "# User Memory\n\n## Identity\n- Concise"
+    rewritten = _complete_profile_body()
+    condensed = _complete_profile_body("- Concise")
     complete_async = AsyncMock(
         side_effect=[
             _completion_response("UPDATE"),
@@ -462,7 +535,7 @@ 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"
+    rewritten = _complete_profile_body()
     response = MagicMock()
     response.choices[0].message.content = rewritten
     llm_service = MagicMock()
@@ -498,7 +571,7 @@ async def test_consolidate_user_memory_runs_full_rewrite_when_gate_update(
 async def test_consolidate_user_memory_adds_frontmatter_to_llm_body(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    rewritten = "# User Memory\n\n## Identity\n- Prefers concise answers"
+    rewritten = _complete_profile_body()
     response = MagicMock()
     response.choices[0].message.content = rewritten
     llm_service = MagicMock()
@@ -534,10 +607,11 @@ async def test_consolidate_user_memory_replaces_llm_frontmatter(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     """Strip untrusted legacy metadata before assembling the updated profile."""
-    rewritten = "# User Memory\n\n## Identity\n- Prefers concise answers"
+    rewritten = _complete_profile_body()
     response = MagicMock()
     response.choices[0].message.content = (
-        "---\nuser_id: stale-user\nturn_count: 99\n---\n\n" + rewritten
+        "---\nuser_id: stale-user\nturn_count: 99\n---\n\n"
+        + _complete_profile_body(legacy_title=True)
     )
     llm_service = MagicMock()
     llm_service.complete_async = AsyncMock(return_value=response)
@@ -572,7 +646,7 @@ 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"
+    rewritten = _complete_profile_body()
     response = MagicMock()
     response.choices[0].message.content = rewritten
     llm_service = MagicMock()
@@ -729,7 +803,7 @@ async def test_should_consolidate_memory_falls_back_to_true_on_error(
 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"
+    rewritten = _complete_profile_body()
     response = MagicMock()
     response.choices[0].message.content = rewritten
     llm_service = MagicMock()
@@ -1093,19 +1167,34 @@ async def test_download_user_memory_downloads_existing_file_to_memory(
     )
 
 
+class _FakeSdkError(Exception):
+    """Stands in for unique_sdk's HTTP error hierarchy in folder-lookup tests.
+
+    Only the ``http_status`` attribute that ``_is_folder_not_found`` inspects
+    matters here; using the real ``unique_sdk`` error classes would tie these
+    tests to their exact constructor signatures for no benefit.
+    """
+
+    def __init__(self, *, http_status: int) -> None:
+        super().__init__(f"http_status={http_status}")
+        self.http_status = http_status
+
+
+def _not_found_error() -> Exception:
+    return _FakeSdkError(http_status=404)
+
+
+def _server_error() -> Exception:
+    return _FakeSdkError(http_status=500)
+
+
 @pytest.mark.asyncio
-async def test_ensure_user_memory_folder_returns_existing_user_folder(
+async def test_ensure_user_memory_folder_returns_existing_home_folder(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    get_info = AsyncMock(
-        side_effect=[
-            {"id": "scope_root"},
-            {"id": "scope_user"},
-        ]
-    )
+    """A fresh user with an already-provisioned home resolves without creating."""
+    get_info = AsyncMock(return_value={"id": "scope_home"})
     create_paths = AsyncMock()
-    add_access = AsyncMock()
-    get_groups = AsyncMock()
     monkeypatch.setattr(
         "unique_user_memory.user_memory.unique_sdk.Folder.get_info_async",
         get_info,
@@ -1114,13 +1203,42 @@ async def test_ensure_user_memory_folder_returns_existing_user_folder(
         "unique_user_memory.user_memory.unique_sdk.Folder.create_paths_async",
         create_paths,
     )
+
+    result = await ensure_user_memory_folder(
+        user_id="user_1",
+        company_id="company_1",
+        root_folder="user-memory",
+        logger=MagicMock(),
+    )
+
+    assert result == "scope_home"
+    get_info.assert_awaited_once_with(
+        user_id="user_1",
+        company_id="company_1",
+        folderPath="/home-user_1/user-memory",
+    )
+    create_paths.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_ensure_user_memory_folder_falls_back_to_legacy_leaf_when_not_migrated(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A user whose memory still lives at the legacy shared-root leaf stays readable."""
+    get_info = AsyncMock(
+        side_effect=[
+            _not_found_error(),
+            {"id": "scope_legacy"},
+        ]
+    )
+    create_paths = AsyncMock()
     monkeypatch.setattr(
-        "unique_user_memory.user_memory.unique_sdk.Folder.add_access_async",
-        add_access,
+        "unique_user_memory.user_memory.unique_sdk.Folder.get_info_async",
+        get_info,
     )
     monkeypatch.setattr(
-        "unique_user_memory.user_memory.unique_sdk.Group.get_groups_async",
-        get_groups,
+        "unique_user_memory.user_memory.unique_sdk.Folder.create_paths_async",
+        create_paths,
     )
 
     result = await ensure_user_memory_folder(
@@ -1130,11 +1248,11 @@ async def test_ensure_user_memory_folder_returns_existing_user_folder(
         logger=MagicMock(),
     )
 
-    assert result == "scope_user"
+    assert result == "scope_legacy"
     get_info.assert_any_await(
         user_id="user_1",
         company_id="company_1",
-        folderPath="/user-memory",
+        folderPath="/home-user_1/user-memory",
     )
     get_info.assert_any_await(
         user_id="user_1",
@@ -1142,22 +1260,28 @@ async def test_ensure_user_memory_folder_returns_existing_user_folder(
         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(
+async def test_ensure_user_memory_folder_creates_home_when_neither_location_exists(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
-    get_info = AsyncMock(
-        side_effect=[
-            {"id": "scope_root"},
-            RuntimeError("missing user folder"),
-        ]
+    """A brand-new user with no folder yet gets a home folder provisioned.
+
+    create_paths creates every missing segment of a nested path and returns
+    them parent-first (regression guard for the bug where the parent
+    `/home-<userId>` folder's id was returned instead of the leaf
+    `/home-<userId>/user-memory` folder's id).
+    """
+    get_info = AsyncMock(side_effect=[_not_found_error(), _not_found_error()])
+    create_paths = AsyncMock(
+        return_value={
+            "createdFolders": [
+                {"id": "scope_home_parent"},
+                {"id": "scope_new_home_leaf"},
+            ]
+        }
     )
-    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,
@@ -1166,10 +1290,6 @@ async def test_ensure_user_memory_folder_creates_private_user_folder_under_root(
         "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",
@@ -1178,39 +1298,53 @@ async def test_ensure_user_memory_folder_creates_private_user_folder_under_root(
         logger=MagicMock(),
     )
 
-    assert result == "scope_user"
+    assert result == "scope_new_home_leaf"
     create_paths.assert_awaited_once_with(
         user_id="user_1",
         company_id="company_1",
-        parentScopeId="scope_root",
-        relativePaths=["user_1"],
+        paths=["/home-user_1/user-memory"],
         inheritAccess=False,
     )
-    add_access.assert_awaited_once_with(
+
+
+@pytest.mark.asyncio
+async def test_ensure_user_memory_folder_returns_none_when_home_creation_fails(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    get_info = AsyncMock(side_effect=[_not_found_error(), _not_found_error()])
+    create_paths = AsyncMock(side_effect=RuntimeError("create failed"))
+    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,
+    )
+
+    result = await ensure_user_memory_folder(
         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,
+        root_folder="user-memory",
+        logger=MagicMock(),
     )
 
+    assert result is None
+
 
 @pytest.mark.asyncio
-async def test_ensure_user_memory_folder_returns_none_when_access_grant_fails_after_create(
+async def test_ensure_user_memory_folder_does_not_provision_on_unverified_lookup_failure(
     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)
+    """A non-404 lookup error must never be treated as 'absent, safe to create'.
+
+    Regression guard for the UN-24896 defect shape: silently treating any
+    lookup failure as "not found" and provisioning a new home would risk
+    creating an empty home that shadows a real, still-readable memory.md
+    once the transient error clears.
+    """
+    get_info = AsyncMock(side_effect=[_server_error(), _not_found_error()])
+    create_paths = AsyncMock()
     logger = MagicMock()
     monkeypatch.setattr(
         "unique_user_memory.user_memory.unique_sdk.Folder.get_info_async",
@@ -1220,10 +1354,6 @@ async def test_ensure_user_memory_folder_returns_none_when_access_grant_fails_af
         "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",
@@ -1233,32 +1363,43 @@ async def test_ensure_user_memory_folder_returns_none_when_access_grant_fails_af
     )
 
     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,
+    create_paths.assert_not_awaited()
+    logger.warning.assert_any_call(
+        "[user-memory] no memory folder resolved and at least one lookup "
+        "failed - running without memory instead of provisioning"
+    )
+
+
+@pytest.mark.asyncio
+async def test_ensure_user_memory_folder_never_resolves_shared_root_path(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Regression guard: the retired shared `/user-memory` root (UN-24764/UN-24823)
+    must never be looked up or (re-)created by this function."""
+    get_info = AsyncMock(side_effect=[_not_found_error(), _not_found_error()])
+    create_paths = AsyncMock(
+        return_value={"createdFolders": [{"id": "scope_new_home"}]}
+    )
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.unique_sdk.Folder.get_info_async",
+        get_info,
     )
-    add_access.assert_awaited_once_with(
+    monkeypatch.setattr(
+        "unique_user_memory.user_memory.unique_sdk.Folder.create_paths_async",
+        create_paths,
+    )
+
+    await ensure_user_memory_folder(
         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,
+        root_folder="user-memory",
+        logger=MagicMock(),
     )
 
+    looked_up_paths = {call.kwargs["folderPath"] for call in get_info.await_args_list}
+    assert "/user-memory" not in looked_up_paths
+    assert create_paths.await_args.kwargs["paths"] == ["/home-user_1/user-memory"]
+
 
 @pytest.mark.asyncio
 async def test_upload_user_memory_writes_hidden_skip_ingestion_file(

{unique_user_memory-2026.36.0.dev2 → unique_user_memory-2026.36.0.dev4}/unique_user_memory/user_memory.py

@@ -43,6 +43,11 @@ from unique_user_memory.user_memory_prompts import (
 MEMORY_FILENAME = "memory.md"
 MIME_TYPE = "text/markdown"
 _LLM_OUTPUT_HEADROOM_TOKENS = 200
+# Mirrors node-ingestion's scope.utils USER_HOME_SCOPE_PREFIX (UN-24823): the
+# shared, company-writable `/user-memory` root was retired in favour of a
+# per-user root-level home folder. See conduct/runner/user_memory.py in the
+# monorepo for the reference implementation this mirrors (UN-24896).
+USER_HOME_FOLDER_PREFIX = "home-"
 
 
 async def noop_update_callback() -> None:
@@ -69,6 +74,8 @@ _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)
 _TURN_COUNT_RE = re.compile(r"^turn_count:\s*(\d+)\s*$", re.MULTILINE)
+_LEGACY_PROFILE_TITLE_RE = re.compile(r"^# User Memory[ \t]*(?:\n+|$)")
+_H2_HEADING_RE = re.compile(r"^## (.+?)[ \t]*$", re.MULTILINE)
 
 
 def profile_body(content: str) -> str:
@@ -286,7 +293,7 @@ async def condense_user_memory(
         )
         return None
 
-    candidate = profile_body(_strip_code_fences(raw))
+    candidate = _without_legacy_profile_title(profile_body(_strip_code_fences(raw)))
     if not _is_well_formed_profile(candidate):
         logger.warning(
             "[user-memory] condense output did not look like a profile (%d chars)",
@@ -414,132 +421,154 @@ async def load_user_memory(
     )
 
 
-async def ensure_user_memory_folder(
+def _home_memory_folder_path(*, user_id: str, root_folder: str) -> str:
+    """Canonical memory location post-UN-24823: `/home-<userId>/<root_folder>`."""
+    return f"/{USER_HOME_FOLDER_PREFIX}{user_id}/{root_folder.strip('/')}"
+
+
+def _legacy_memory_folder_path(*, user_id: str, root_folder: str) -> str:
+    """Pre-UN-24823 location (`/<root_folder>/<userId>`), read during rollout."""
+    return f"/{root_folder.strip('/')}/{user_id}"
+
+
+def _is_folder_not_found(exc: Exception) -> bool:
+    """True only for a genuine 404 from the folder-info endpoint."""
+    status = getattr(exc, "http_status", None)
+    code = getattr(exc, "code", None)
+    return status == 404 or code == 404 or code == "404"
+
+
+async def _resolve_existing_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
+) -> tuple[str | None, bool]:
+    """Look up the user's memory folder: canonical home first, legacy second.
+
+    Mirrors conduct/runner/user_memory.py::_resolve_existing_memory_folder in
+    the monorepo (UN-24896/UN-24823). Returns ``(scope_id, lookup_failed)``:
+    a resolved folder always wins; when neither location resolves,
+    ``lookup_failed`` distinguishes a verified absence (both lookups 404 -
+    safe to provision the home) from an unverified one (some other error -
+    the caller must not provision, or it risks creating an empty home that
+    orphans a real, still-legacy ``memory.md``).
+    """
+    lookup_failed = False
+    for folder_path in (
+        _home_memory_folder_path(user_id=user_id, root_folder=root_folder),
+        _legacy_memory_folder_path(user_id=user_id, root_folder=root_folder),
+    ):
+        try:
+            info = await unique_sdk.Folder.get_info_async(
+                user_id=user_id,
+                company_id=company_id,
+                folderPath=folder_path,
+            )
+        except Exception as exc:
+            if _is_folder_not_found(exc):
+                continue
+            logger.warning(
+                "[user-memory] memory folder lookup failed for %s: [%s] %s",
+                folder_path,
+                type(exc).__name__,
+                exc,
+            )
+            lookup_failed = True
+            continue
+        # A missing id (e.g. a 200 with an empty body) falls through to the
+        # next location the same way a 404 does.
+        scope_id = (info or {}).get("id")
+        if scope_id:
+            logger.debug(
+                "[user-memory] resolved existing memory folder %s", folder_path
+            )
+            return scope_id, False
 
-    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,
+    if lookup_failed:
+        logger.warning(
+            "[user-memory] no memory folder resolved and at least one lookup "
+            "failed - running without memory instead of provisioning"
         )
-        return info.get("id")
-    except Exception:
-        logger.warning("[user-memory] user memory folder not found - creating new one")
+    return None, lookup_failed
+
 
+async def _create_home_memory_folder(
+    *,
+    user_id: str,
+    company_id: str,
+    root_folder: str,
+    logger: Logger,
+) -> str | None:
+    """Provision `/home-<userId>/<root_folder>` with one idempotent call.
+
+    node-ingestion creates the caller's root-level home with an exclusive
+    owner ACL and repairs the ACL to owner-only on every pass (UN-24823).
+    There is no shared parent folder, so - unlike the retired shared-root
+    model - no separate access grant is needed here.
+    """
+    folder_path = _home_memory_folder_path(user_id=user_id, root_folder=root_folder)
     try:
         created = await unique_sdk.Folder.create_paths_async(
             user_id=user_id,
             company_id=company_id,
-            parentScopeId=root_scope_id,
-            relativePaths=[user_id],
+            paths=[folder_path],
             inheritAccess=False,
         )
     except Exception as exc:
         logger.warning(
-            "[user-memory] failed to create user folder %s: [%s] %s",
-            user_folder_path,
+            "[user-memory] failed to ensure memory folder %s: [%s] %s",
+            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
+    # create_paths returns every newly-created segment, parent first (e.g. the
+    # home folder itself, then the memory subfolder if both were missing) -
+    # the leaf we actually want is always the last entry, never the first.
+    scope_id = created_folders[-1].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,
+            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(
+async def ensure_user_memory_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
+    """Resolve the user's memory folder, creating the home if needed (UN-24823).
 
-    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,
-        )
+    Read-before-provision, mirroring node-chat/conduct: an existing folder
+    (canonical home, falling back to the legacy shared-root leaf for
+    not-yet-migrated users) always wins, and the home is only provisioned
+    when both locations are genuinely absent.
+    """
+    scope_id, lookup_failed = await _resolve_existing_memory_folder(
+        user_id=user_id,
+        company_id=company_id,
+        root_folder=root_folder,
+        logger=logger,
+    )
+    if scope_id is not None:
+        return scope_id
+    if lookup_failed:
         return None
-
-    return root_scope_id
+    return await _create_home_memory_folder(
+        user_id=user_id,
+        company_id=company_id,
+        root_folder=root_folder,
+        logger=logger,
+    )
 
 
 async def download_user_memory(
@@ -906,7 +935,9 @@ async def _rewrite_user_memory(
         logger.info("[user-memory] consolidation NOOP - keeping existing memory")
         return safe_current
 
-    candidate_body = profile_body(_strip_code_fences(raw))
+    candidate_body = _without_legacy_profile_title(
+        profile_body(_strip_code_fences(raw))
+    )
     if not _is_well_formed_profile(candidate_body):
         logger.warning(
             "[user-memory] LLM output did not look like a profile (%d chars)",
@@ -947,7 +978,14 @@ def _sanitize_for_xml_context(text: str) -> str:
 def _is_well_formed_profile(content: str) -> bool:
     if not content or len(content.strip()) < 20:
         return False
-    return content.startswith("# User Memory") and "## Identity" in content
+    body = _without_legacy_profile_title(content.strip())
+    headings = tuple(_H2_HEADING_RE.findall(body))
+    return body.startswith("## Identity") and headings == SECTION_HEADINGS
+
+
+def _without_legacy_profile_title(content: str) -> str:
+    """Remove the former document title while preserving the H2 profile body."""
+    return _LEGACY_PROFILE_TITLE_RE.sub("", content.strip(), count=1).lstrip()
 
 
 def _strip_code_fences(text: str) -> str:

{unique_user_memory-2026.36.0.dev2 → unique_user_memory-2026.36.0.dev4}/unique_user_memory/user_memory_prompts.py

@@ -19,8 +19,6 @@ last_updated: {{ timestamp }}
 turn_count: 0
 ---
 
-# User Memory
-
 {% for heading in section_headings -%}
 ## {{ heading }}
 _(empty)_
@@ -60,8 +58,9 @@ You receive two XML blocks:
 # Output
 
 Return the complete, rewritten Markdown profile body, starting with
-`# User Memory`. Do NOT emit a diff. Do NOT wrap the output in
-``` fences. Do NOT add commentary before or after the body.
+`## Identity`. Do NOT add a document-level `# User Memory` title. Do NOT
+emit a diff. Do NOT wrap the output in ``` fences. Do NOT add commentary
+before or after the body.
 
 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):
@@ -256,8 +255,8 @@ fact about the user. This is lossy compression, not deletion of meaning.
 # Output
 
 Return the complete rewritten profile body, starting with
-`# User Memory`. Do NOT emit a diff, or commentary,
-and do NOT wrap the output in ``` fences.
+`## Identity`. Do NOT add a document-level `# User Memory` title. Do NOT
+emit a diff or commentary, and do NOT wrap the output in ``` fences.
 """