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

{unique_user_memory-2026.36.0.dev3 → 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.dev3
+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.dev3 → 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.dev3 → unique_user_memory-2026.36.0.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_user_memory"
-version = "2026.36.0.dev3"
+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.dev3 → 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.dev3 → unique_user_memory-2026.36.0.dev4}/unique_user_memory/tests/test_user_memory.py

@@ -1167,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,
@@ -1188,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(
@@ -1204,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",
@@ -1216,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,
@@ -1240,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",
@@ -1252,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",
@@ -1294,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",
@@ -1307,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"}]}
     )
-    add_access.assert_awaited_once_with(
+    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,
+    )
+
+    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.dev3 → 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:
@@ -416,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,
-        )
-        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,
+            folder_path,
         )
         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(