cognee 1.1.0.dev0__tar.gz → 1.1.0.dev1__tar.gz

cognee-1.1.0.dev1/.env.example

@@ -0,0 +1,11 @@
+# Deprecated: use .env.template as the canonical environment template.
+#
+# To configure Cognee, copy .env.template to .env and fill in the values you need:
+#
+#   cp .env.template .env
+#
+# This file is kept for backwards compatibility with older setup instructions.
+
+LLM_API_KEY="your_api_key"
+LLM_MODEL="openai/gpt-5-mini"
+LLM_PROVIDER="openai"

{cognee-1.1.0.dev0 → cognee-1.1.0.dev1}/CONTRIBUTING.md

@@ -99,7 +99,7 @@ git checkout -b feature/your-feature-name
 
 ### Running Tests
 
-Rename `.env.example` into `.env` and provide your OPENAI_API_KEY as LLM_API_KEY
+Copy `.env.template` to `.env` and provide your OPENAI_API_KEY as LLM_API_KEY
 
 ```shell
 uv run python cognee/tests/test_library.py
@@ -107,7 +107,7 @@ uv run python cognee/tests/test_library.py
 
 ### Running Simple Example
 
-Rename `.env.example` into `.env` and provide your OPENAI_API_KEY as LLM_API_KEY
+Copy `.env.template` to `.env` and provide your OPENAI_API_KEY as LLM_API_KEY
 
 Make sure to run ```shell uv sync ``` in the root cloned folder or set up a virtual environment to run cognee
 
@@ -122,7 +122,7 @@ uv run python examples/python/simple_example.py
 
 ### Running Simple Example
 
-Change .env.example into .env and provide your OPENAI_API_KEY as LLM_API_KEY
+Copy `.env.template` to `.env` and provide your OPENAI_API_KEY as LLM_API_KEY
 
 Make sure to run ```shell uv sync ``` in the root cloned folder or set up a virtual environment to run cognee
 

{cognee-1.1.0.dev0 → cognee-1.1.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cognee
-Version: 1.1.0.dev0
+Version: 1.1.0.dev1
 Summary: Cognee - is a library for enriching LLM context with a semantic layer for better understanding and reasoning.
 Project-URL: Homepage, https://www.cognee.ai
 Project-URL: Repository, https://github.com/topoteretes/cognee
@@ -132,6 +132,9 @@ Provides-Extra: llama-cpp
 Requires-Dist: llama-cpp-python[server]<1.0.0,>=0.3.0; extra == 'llama-cpp'
 Provides-Extra: llama-index
 Requires-Dist: llama-index-core<0.15,>=0.14.20; extra == 'llama-index'
+Provides-Extra: mistral
+Requires-Dist: mistral-common<2,>=1.5.2; extra == 'mistral'
+Requires-Dist: mistralai<2,>=1.9.10; extra == 'mistral'
 Provides-Extra: monitoring
 Requires-Dist: langfuse<3,>=2.32.0; extra == 'monitoring'
 Requires-Dist: opentelemetry-api<2,>=1.20.0; extra == 'monitoring'
@@ -380,26 +383,6 @@ export COGNEE_API_KEY="ck_..."
 
 The plugin hooks into Claude Code's lifecycle — `SessionStart` initializes memory, `PostToolUse` captures actions, `UserPromptSubmit` injects relevant context, `PreCompact` preserves memory across context resets, and `SessionEnd` bridges session data into the permanent graph.
 
-### Hermes Agent
-
-Enable Cognee as the memory provider in [Hermes Agent](https://github.com/NousResearch/hermes-agent) for session-aware knowledge graph memory with auto-routing recall.
-
-**Setup:**
-
-```yaml
-# ~/.hermes/config.yaml
-memory:
-  provider: cognee
-```
-
-```bash
-export LLM_API_KEY="your-openai-key"
-hermes  # start chatting — session memory and graph persistence are automatic
-```
-
-Or run `hermes memory setup` and select Cognee. For Cognee Cloud, set `COGNEE_SERVICE_URL` and `COGNEE_API_KEY` in `~/.hermes/.env`.
-
-
 ### Connect to Cognee Cloud
 
 Point any Python agent at a managed Cognee instance — all SDK calls route to the cloud:

{cognee-1.1.0.dev0 → cognee-1.1.0.dev1}/README.md

@@ -203,26 +203,6 @@ export COGNEE_API_KEY="ck_..."
 
 The plugin hooks into Claude Code's lifecycle — `SessionStart` initializes memory, `PostToolUse` captures actions, `UserPromptSubmit` injects relevant context, `PreCompact` preserves memory across context resets, and `SessionEnd` bridges session data into the permanent graph.
 
-### Hermes Agent
-
-Enable Cognee as the memory provider in [Hermes Agent](https://github.com/NousResearch/hermes-agent) for session-aware knowledge graph memory with auto-routing recall.
-
-**Setup:**
-
-```yaml
-# ~/.hermes/config.yaml
-memory:
-  provider: cognee
-```
-
-```bash
-export LLM_API_KEY="your-openai-key"
-hermes  # start chatting — session memory and graph persistence are automatic
-```
-
-Or run `hermes memory setup` and select Cognee. For Cognee Cloud, set `COGNEE_SERVICE_URL` and `COGNEE_API_KEY` in `~/.hermes/.env`.
-
-
 ### Connect to Cognee Cloud
 
 Point any Python agent at a managed Cognee instance — all SDK calls route to the cloud:

{cognee-1.1.0.dev0 → cognee-1.1.0.dev1}/cognee/api/v1/llm/routers/get_llm_router.py

@@ -1,6 +1,7 @@
 import json
 from typing import Any, Dict, List, Annotated
 
+import litellm
 from fastapi import APIRouter, Depends, File, UploadFile as UF, Form
 from fastapi.responses import JSONResponse
 from pydantic import Field
@@ -8,6 +9,7 @@ from pydantic import ConfigDict, ValidationError
 
 from cognee import __version__ as cognee_version
 from cognee.api.DTO import InDTO, OutDTO
+from cognee.infrastructure.llm import get_llm_config
 from cognee.infrastructure.llm.LLMGateway import LLMGateway
 from cognee.infrastructure.llm.prompts import render_prompt
 from cognee.infrastructure.loaders import get_loader_engine
@@ -24,17 +26,129 @@ import tempfile
 
 logger = get_logger("api.llm")
 
+# Maximum characters of sample text sent to the LLM for schema inference.
+# Keeps the prompt well within typical context windows while providing
+# enough material for the model to identify entity types and relationships.
+_INFER_SCHEMA_MAX_CHARS = 12_000
+
 # NOTE: Needed because of: https://github.com/fastapi/fastapi/discussions/14975
 #       Once issue is resolved on Swagger side it can be removed.
 UploadFile = Annotated[UF, WithJsonSchema({"type": "string", "format": "binary"})]
 
 _ALLOWED_LLM_PARAMS = {"temperature", "max_tokens", "top_p", "seed"}
+_TOKEN_BUDGET_SAFETY_MARGIN = 512
 
 
 def _safe_params(params: dict) -> dict:
     return {k: v for k, v in params.items() if k in _ALLOWED_LLM_PARAMS}
 
 
+def _sample_text(text: str, max_chars: int = _INFER_SCHEMA_MAX_CHARS) -> str:
+    """Return a representative sample of *text* that fits within *max_chars*.
+
+    Strategy depends on how much larger the text is than the budget:
+    - ≤ max_chars: return as-is.
+    - ≤ 2× max_chars: take beginning and end (two sections).
+    - > 2× max_chars: take beginning, middle, and end (three sections).
+
+    This avoids near-duplicate content when the text is only slightly
+    over the limit.
+    """
+    if len(text) <= max_chars:
+        return text
+
+    separator = "\n\n[...]\n\n"
+    sep_budget = len(separator)
+
+    if len(text) <= max_chars * 2:
+        # Two sections: beginning + end — no overlap possible.
+        half = (max_chars - sep_budget) // 2
+        return text[:half].rstrip() + separator + text[-half:].lstrip()
+
+    # Three sections: beginning, middle, end.
+    chunk = (max_chars - sep_budget * 2) // 3
+    mid_start = (len(text) - chunk) // 2
+
+    return (
+        text[:chunk].rstrip()
+        + separator
+        + text[mid_start : mid_start + chunk].strip()
+        + separator
+        + text[-chunk:].lstrip()
+    )
+
+
+def _count_tokens(text: str, model: str) -> int | None:
+    try:
+        return litellm.token_counter(model=model, text=text)
+    except Exception:
+        return None
+
+
+def _model_aware_sample_text(
+    text: str,
+    model: str,
+    system_prompt: str,
+    user_prompt_prefix: str,
+    requested_max_tokens: int,
+) -> str:
+    """
+    Return sampled text sized for model context budget.
+
+    Falls back to the static character sampler when model metadata or token counting
+    is unavailable.
+    """
+    try:
+        llm_config = get_llm_config()
+        model_info = litellm.get_model_info(
+            model,
+            custom_llm_provider=llm_config.llm_provider or None,
+            api_base=llm_config.llm_endpoint or None,
+        )
+
+        max_input_tokens = model_info.get("max_input_tokens") or model_info.get("max_tokens")
+        max_output_tokens = model_info.get("max_output_tokens") or model_info.get("max_tokens")
+        if not max_input_tokens:
+            return _sample_text(text)
+
+        output_budget = min(requested_max_tokens, max_output_tokens or requested_max_tokens)
+        prompt_overhead = (_count_tokens(system_prompt, model) or 0) + (
+            _count_tokens(user_prompt_prefix, model) or 0
+        )
+
+        available_input_tokens = max_input_tokens - output_budget - prompt_overhead
+        available_input_tokens -= _TOKEN_BUDGET_SAFETY_MARGIN
+
+        if available_input_tokens <= 0:
+            logger.warning(
+                "Infer schema prompt budget exhausted for model %s. Falling back to %s chars.",
+                model,
+                _INFER_SCHEMA_MAX_CHARS,
+            )
+            return _sample_text(text)
+
+        full_text_tokens = _count_tokens(text, model)
+        if full_text_tokens is None:
+            return _sample_text(text)
+        if full_text_tokens <= available_input_tokens:
+            return text
+
+        chars_per_token = len(text) / max(full_text_tokens, 1)
+        sample_max_chars = max(500, int(available_input_tokens * chars_per_token * 0.95))
+        sample = _sample_text(text, max_chars=sample_max_chars)
+
+        for _ in range(4):
+            sample_tokens = _count_tokens(sample, model)
+            if sample_tokens is None or sample_tokens <= available_input_tokens:
+                break
+            sample_max_chars = max(500, int(sample_max_chars * 0.8))
+            sample = _sample_text(text, max_chars=sample_max_chars)
+
+        return sample
+    except Exception:
+        return _sample_text(text)
+
+
 @asynccontextmanager
 async def upload_to_temp_path(upload: UploadFile):
     """
@@ -134,7 +248,7 @@ def get_llm_router() -> APIRouter:
             return JSONResponse(status_code=400, content={"error": str(error)})
         except Exception as error:
             logger.error("LLM custom prompt generation request failed")
-            return JSONResponse(status_code=409, content={"error": str(error)})
+            return JSONResponse(status_code=500, content={"error": str(error)})
 
     @router.post("/infer-schema", response_model=InferSchemaResponseDTO)
     @log_usage(function_name="POST /v1/llm/infer-schema", log_type="api_endpoint")
@@ -189,17 +303,30 @@ def get_llm_router() -> APIRouter:
             if text:
                 file_contents.append(text)
 
-            file_contents_text = "\n\n".join(file_contents)
-
-            user_prompt = render_prompt(
-                "infer_schema_user.txt",
-                {"SAMPLE_TEXT": file_contents_text},
-            )
-
             system_prompt = render_prompt(
                 "infer_schema_system.txt",
                 {},
             )
+            user_prompt_prefix = render_prompt(
+                "infer_schema_user.txt",
+                {"SAMPLE_TEXT": ""},
+            )
+
+            file_contents_text = "\n\n".join(file_contents)
+            requested_max_tokens = int(
+                parameters_dict.get("max_tokens", get_llm_config().llm_max_completion_tokens)
+            )
+            sample = _model_aware_sample_text(
+                text=file_contents_text,
+                model=get_llm_config().llm_model,
+                system_prompt=system_prompt,
+                user_prompt_prefix=user_prompt_prefix,
+                requested_max_tokens=requested_max_tokens,
+            )
+            user_prompt = render_prompt(
+                "infer_schema_user.txt",
+                {"SAMPLE_TEXT": sample},
+            )
 
             llm_output = await LLMGateway.acreate_structured_output(
                 text_input=user_prompt,
@@ -228,6 +355,6 @@ def get_llm_router() -> APIRouter:
             )
         except Exception as error:
             logger.error("LLM schema inference failed: %s", error)
-            return JSONResponse(status_code=409, content={"error": str(error)})
+            return JSONResponse(status_code=500, content={"error": str(error)})
 
     return router

{cognee-1.1.0.dev0 → cognee-1.1.0.dev1}/cognee/api/v1/permissions/routers/get_permissions_router.py

@@ -86,6 +86,49 @@ def get_permissions_router() -> APIRouter:
             status_code=200, content={"message": "Permission assigned to principal"}
         )
 
+    @permissions_router.delete("/datasets/{principal_id}")
+    async def revoke_datasets_permission_from_principal(
+        permission_name: str,
+        dataset_ids: List[UUID],
+        principal_id: UUID,
+        user: User = Depends(get_authenticated_user),
+    ):
+        """
+        Revoke permission on datasets from a principal (user or role).
+
+        ## Path Parameters
+        - **principal_id** (UUID): The UUID of the principal to revoke permission from
+
+        ## Request Parameters
+        - **permission_name** (str): The name of the permission to revoke (e.g., "read", "write", "delete")
+        - **dataset_ids** (List[UUID]): List of dataset UUIDs to revoke permission on
+        """
+        send_telemetry(
+            "Permissions API Endpoint Invoked",
+            user.id,
+            additional_properties={
+                "endpoint": f"DELETE /v1/permissions/datasets/{str(principal_id)}",
+                "dataset_ids": str(dataset_ids),
+                "principal_id": str(principal_id),
+                "cognee_version": cognee_version,
+            },
+        )
+
+        from cognee.modules.users.permissions.methods import (
+            authorized_revoke_permission_on_datasets,
+        )
+
+        await authorized_revoke_permission_on_datasets(
+            principal_id,
+            [dataset_id for dataset_id in dataset_ids],
+            permission_name,
+            user.id,
+        )
+
+        return JSONResponse(
+            status_code=200, content={"message": "Permission revoked from principal"}
+        )
+
     @permissions_router.post("/roles")
     async def create_role(role_name: str, user: User = Depends(get_authenticated_user)):
         """
@@ -129,6 +172,34 @@ def get_permissions_router() -> APIRouter:
             },
         )
 
+    @permissions_router.delete("/roles/{role_id}")
+    async def delete_role_endpoint(role_id: UUID, user: User = Depends(get_authenticated_user)):
+        """
+        Delete a role and all its associations.
+
+        Removes all user-role memberships and ACL entries for this role,
+        then deletes the role. The authenticated user must be able to manage
+        users in the tenant.
+
+        ## Path Parameters
+        - **role_id** (UUID): The UUID of the role to delete
+        """
+        send_telemetry(
+            "Permissions API Endpoint Invoked",
+            user.id,
+            additional_properties={
+                "endpoint": f"DELETE /v1/permissions/roles/{str(role_id)}",
+                "role_id": str(role_id),
+                "cognee_version": cognee_version,
+            },
+        )
+
+        from cognee.modules.users.roles.methods import delete_role as delete_role_method
+
+        await delete_role_method(role_id=role_id, owner_id=user.id)
+
+        return JSONResponse(status_code=200, content={"message": "Role deleted"})
+
     @permissions_router.post("/users/{user_id}/roles")
     async def add_user_to_role(
         user_id: UUID, role_id: UUID, user: User = Depends(get_authenticated_user)
@@ -172,6 +243,40 @@ def get_permissions_router() -> APIRouter:
 
         return JSONResponse(status_code=200, content={"message": "User added to role"})
 
+    @permissions_router.delete("/users/{user_id}/roles")
+    async def remove_user_from_role_endpoint(
+        user_id: UUID, role_id: UUID, user: User = Depends(get_authenticated_user)
+    ):
+        """
+        Remove a user from a role.
+
+        The authenticated user must be able to manage users in the tenant.
+
+        ## Path Parameters
+        - **user_id** (UUID): The UUID of the user to remove from the role
+
+        ## Request Parameters
+        - **role_id** (UUID): The UUID of the role to remove the user from
+        """
+        send_telemetry(
+            "Permissions API Endpoint Invoked",
+            user.id,
+            additional_properties={
+                "endpoint": f"DELETE /v1/permissions/users/{str(user_id)}/roles",
+                "user_id": str(user_id),
+                "role_id": str(role_id),
+                "cognee_version": cognee_version,
+            },
+        )
+
+        from cognee.modules.users.roles.methods import (
+            remove_user_from_role as remove_user_from_role_method,
+        )
+
+        await remove_user_from_role_method(user_id=user_id, role_id=role_id, owner_id=user.id)
+
+        return JSONResponse(status_code=200, content={"message": "User removed from role"})
+
     @permissions_router.post("/users/{user_id}/tenants")
     async def add_user_to_tenant(
         user_id: UUID, tenant_id: UUID, user: User = Depends(get_authenticated_user)

{cognee-1.1.0.dev0 → cognee-1.1.0.dev1}/cognee/infrastructure/databases/graph/graph_db_interface.py

@@ -41,6 +41,7 @@ class GraphDBInterface(ABC):
 
     @abstractmethod
     async def is_empty(self) -> bool:
+        """Return True when the graph contains no nodes."""
         logger.warning("is_empty() is not implemented")
         return True
 
@@ -109,6 +110,27 @@ class GraphDBInterface(ABC):
         """
         raise NotImplementedError
 
+    async def remove_belongs_to_set_tags(
+        self,
+        tags: List[str],
+        node_ids: Optional[List[str]] = None,
+    ) -> None:
+        """
+        Remove the given tag names from every node's `belongs_to_set` property
+        array. Keeps the property consistent with the additive
+        `belongs_to_set` edges after a NodeSet or its containing dataset is
+        deleted.
+
+        When `node_ids` is provided, the detag only applies to nodes whose
+        id appears in the list — used to reconcile shared nodes that lose
+        membership in one dataset without disturbing unrelated nodes that
+        legitimately still carry the tag.
+
+        Default no-op; only Neo4j overrides this today. Other
+        list-property-storing adapters are free to implement it later.
+        """
+        return None
+
     @abstractmethod
     async def get_node(self, node_id: str) -> Optional[NodeData]:
         """

{cognee-1.1.0.dev0 → cognee-1.1.0.dev1}/cognee/infrastructure/databases/graph/neo4j_driver/adapter.py

@@ -65,6 +65,7 @@ class Neo4jAdapter(GraphDBInterface):
         graph_database_allow_anonymous: bool = False,
         driver: Optional[Any] = None,
     ):
+        """Initialize the Neo4j driver from the given connection params and optional auth."""
         # Only use auth if both username and password are provided
         auth = None
 
@@ -114,6 +115,7 @@ class Neo4jAdapter(GraphDBInterface):
             yield session
 
     async def is_empty(self) -> bool:
+        """Return True if the graph contains no nodes."""
         query = """
         RETURN EXISTS {
         MATCH (n)
@@ -200,10 +202,18 @@ class Neo4jAdapter(GraphDBInterface):
         """
         serialized_properties = self.serialize_properties(node.model_dump())
 
+        # Capture the existing belongs_to_set before `+=` overwrites it, then
+        # write back the union so a DataPoint cognified into multiple datasets
+        # retains every dataset tag on its node property (edges are already
+        # additive; this keeps the property consistent with them).
         query = dedent(
             f"""MERGE (node: `{BASE_LABEL}`{{id: $node_id}})
-                ON CREATE SET node += $properties, node.updated_at = timestamp()
-                ON MATCH SET node += $properties, node.updated_at = timestamp()
+                WITH node, apoc.coll.toSet(
+                    coalesce(node.belongs_to_set, [])
+                    + coalesce($properties.belongs_to_set, [])
+                ) AS merged_belongs_to_set
+                SET node += $properties, node.updated_at = timestamp()
+                SET node.belongs_to_set = merged_belongs_to_set
                 WITH node, $node_label AS label
                 CALL apoc.create.addLabels(node, [label]) YIELD node AS labeledNode
                 RETURN ID(labeledNode) AS internal_id, labeledNode.id AS nodeId"""
@@ -233,28 +243,110 @@ class Neo4jAdapter(GraphDBInterface):
 
             - None: None
         """
+        # Capture the existing belongs_to_set before `+=` overwrites it, then
+        # write back the union so the property on a shared DataPoint reflects
+        # every dataset that cognified it (consistent with the additive
+        # belongs_to_set edges). See add_node for the single-node variant.
         query = f"""
         UNWIND $nodes AS node
         MERGE (n: `{BASE_LABEL}`{{id: node.node_id}})
-        ON CREATE SET n += node.properties, n.updated_at = timestamp()
-        ON MATCH SET n += node.properties, n.updated_at = timestamp()
+        WITH n, node, apoc.coll.toSet(
+            coalesce(n.belongs_to_set, [])
+            + coalesce(node.properties.belongs_to_set, [])
+        ) AS merged_belongs_to_set
+        SET n += node.properties, n.updated_at = timestamp()
+        SET n.belongs_to_set = merged_belongs_to_set
         WITH n, node.label AS label
         CALL apoc.create.addLabels(n, [label]) YIELD node AS labeledNode
         RETURN ID(labeledNode) AS internal_id, labeledNode.id AS nodeId
         """
 
-        nodes = [
-            {
-                "node_id": str(node.id),
-                "label": type(node).__name__,
-                "properties": self.serialize_properties(dict(node)),
-            }
-            for node in nodes
-        ]
+        # Dedup by node_id within the batch — UNWIND on a list with
+        # duplicates yields the same `n` twice, and each pass recomputes
+        # merged_belongs_to_set from the pre-SET state. The second SET then
+        # overwrites the first, losing any tag only seen on the first
+        # duplicate. Collapsing duplicates here (union of tags kept) avoids
+        # the race and matches the batch-dedup already done in PGVector.
+        deduped: Dict[str, Dict[str, Any]] = {}
+        for node in nodes:
+            key = str(node.id)
+            props = self.serialize_properties(dict(node))
+            existing_entry = deduped.get(key)
+            if existing_entry:
+                existing_tags = existing_entry["properties"].get("belongs_to_set") or []
+                incoming_tags = props.get("belongs_to_set") or []
+                if existing_tags or incoming_tags:
+                    merged = list(dict.fromkeys(list(existing_tags) + list(incoming_tags)))
+                    props["belongs_to_set"] = merged
+                existing_entry["properties"] = props
+                existing_entry["label"] = type(node).__name__
+            else:
+                deduped[key] = {
+                    "node_id": key,
+                    "label": type(node).__name__,
+                    "properties": props,
+                }
 
-        results = await self.query(query, dict(nodes=nodes))
+        results = await self.query(query, dict(nodes=list(deduped.values())))
         return results
 
+    async def remove_belongs_to_set_tags(
+        self,
+        tags: List[str],
+        node_ids: Optional[List[str]] = None,
+    ) -> None:
+        """
+        Strip the given tag names from every node's `belongs_to_set`
+        property array AND delete the matching `belongs_to_set` edges
+        to surviving NodeSet nodes whose `name` is one of the tags.
+
+        Used to reconcile surviving shared nodes after a dataset or its
+        NodeSet is deleted. When the NodeSet node itself is hard-deleted
+        upstream, no edges survive — this call is a no-op on the edge
+        side. When the NodeSet survives (scoped detag for shared slugs),
+        the edge from the detagged node to that NodeSet is stale and
+        must be dropped so the graph and the property stay in sync.
+
+        When `node_ids` is provided, the update is restricted to nodes
+        whose `id` is in the list — used when a shared node must lose
+        one dataset's tag while the dataset itself (and its other
+        members) remains.
+        """
+        if not tags:
+            return None
+
+        if node_ids is not None and not node_ids:
+            return None
+
+        id_filter = "AND n.id IN $node_ids" if node_ids is not None else ""
+        node_scope_clause = "WHERE n.id IN $node_ids" if node_ids is not None else ""
+        edge_scope_keyword = "AND" if node_ids is not None else "WHERE"
+        # Single Cypher statement → single transaction. Two independent
+        # phases bridged by `WITH count(*)`: first strip the property on
+        # matching nodes, then match `belongs_to_set` edges to NodeSets
+        # whose name is being removed and delete them. The bridge keeps
+        # the phases sequenced (so phase 2 sees the post-SET graph) but
+        # decouples their match sets — an edge to a stale NodeSet is
+        # pruned even if the source node didn't carry the tag in its
+        # property array. If phase 2 fails, the whole transaction rolls
+        # back and the property is untouched — retry is safe.
+        query = f"""
+        MATCH (n: `{BASE_LABEL}`)
+        WHERE any(tag IN $tags WHERE tag IN coalesce(n.belongs_to_set, []))
+        {id_filter}
+        SET n.belongs_to_set = [x IN n.belongs_to_set WHERE NOT x IN $tags]
+        WITH count(*) AS _bridge
+        MATCH (n: `{BASE_LABEL}`)-[r:belongs_to_set]->(ns:NodeSet)
+        {node_scope_clause}
+        {edge_scope_keyword} ns.name IN $tags
+        DELETE r
+        """
+        params: Dict[str, Any] = {"tags": list(tags)}
+        if node_ids is not None:
+            params["node_ids"] = [str(nid) for nid in node_ids]
+        await self.query(query, params)
+        return None
+
     async def extract_node(self, node_id: str):
         """
         Retrieve a single node from the database by its ID.
@@ -828,6 +920,7 @@ class Neo4jAdapter(GraphDBInterface):
         return {str(r["edge_object_id"]) for r in results if r.get("edge_object_id") is not None}
 
     async def get_node_feedback_weights(self, node_ids: List[str]) -> Dict[str, float]:
+        """Return each node's `feedback_weight` property, defaulting to 0.5 when unset."""
         if not node_ids:
             return {}
         valid_node_ids = [nid for nid in node_ids if isinstance(nid, str) and nid]
@@ -848,6 +941,7 @@ class Neo4jAdapter(GraphDBInterface):
     async def set_node_feedback_weights(
         self, node_feedback_weights: Dict[str, float]
     ) -> Dict[str, bool]:
+        """Persist `feedback_weight` per node; returns a map of node_id → updated bool."""
         if not node_feedback_weights:
             return {}
         node_ids = list(node_feedback_weights.keys())
@@ -858,6 +952,7 @@ class Neo4jAdapter(GraphDBInterface):
         return {nid: (nid in updated_ids) for nid in node_ids}
 
     async def get_edge_feedback_weights(self, edge_object_ids: List[str]) -> Dict[str, float]:
+        """Return each edge's `feedback_weight` property, defaulting to 0.5 when unset."""
         if not edge_object_ids:
             return {}
         valid_edge_ids = [eid for eid in edge_object_ids if isinstance(eid, str) and eid]
@@ -882,6 +977,7 @@ class Neo4jAdapter(GraphDBInterface):
     async def set_edge_feedback_weights(
         self, edge_feedback_weights: Dict[str, float]
     ) -> Dict[str, bool]:
+        """Persist `feedback_weight` per edge; returns a map of edge_object_id → updated bool."""
         if not edge_feedback_weights:
             return {}
         edge_ids = list(edge_feedback_weights.keys())