feat(altk_evolve): entity sharing — public/private visibility (#201)

* fix(tests): resolve 2 failing platform integration tests
- Fixed test_uninstall_prunes_evolve_only_hook_groups by adding empty group pruning logic to _remove_user_prompt_hook in install.sh
- Fixed test_skips_symlinked_entities by correcting test expectations - symlinks exist in git clones but are filtered by retrieve script
- Added RETRIEVE_SCRIPT constant to test_sync.py for cleaner test code
* fix(formatting): apply ruff formatting to mcp_server and entity sharing tests
* fix(mcp): verify ownership before publish/unpublish entity
* fix(mcp): enforce owner_id on public create, consistent limits, ownership mismatch tests
* chore: remove unused imports in evolve_client.py

Author: visahak

README.md

@@ -106,10 +106,12 @@ npx @modelcontextprotocol/inspector@latest http://127.0.0.1:8201/sse --cli --met
 ```
 
 **Available tools:**
-- `get_entities(task: str, entity_type: str)`: Get relevant entities for a specific task, filtered by type (e.g., 'guideline', 'policy').
-- `get_guidelines(task: str)`: Get relevant guidelines for a specific task (backward compatibility alias).
-- `save_trajectory(trajectory_data: str, task_id: str | None)`: Save a conversation trajectory and generate new guidelines.
-- `create_entity(content: str, entity_type: str, metadata: str | None, enable_conflict_resolution: bool)`: Create a single entity in the namespace.
+- `get_entities(task: str, entity_type: str = "guideline", include_public: bool = False)`: Get relevant entities for a specific task. Set `include_public=True` to merge in public entities from all other namespaces; those results are annotated with `[public: {owner_id}]`.
+- `get_guidelines(task: str)`: Get relevant guidelines for a specific task (backward compatibility alias for `get_entities`).
+- `save_trajectory(trajectory_data: str, task_id: str | None, owner_id: str | None)`: Save a conversation trajectory and generate new guidelines.
+- `create_entity(content: str, entity_type: str, metadata: str | None, enable_conflict_resolution: bool, owner_id: str | None, visibility: str = "private")`: Create a single entity. Pass `visibility="public"` and `owner_id` to make it immediately discoverable by other namespaces.
+- `publish_entity(entity_id: str, user_id: str | None)`: Make an entity publicly visible to all namespaces. Records the caller as owner and stamps `published_at`.
+- `unpublish_entity(entity_id: str, user_id: str | None = None)`: Revert an entity to private visibility. Ownership is enforced server-side: if the entity has an `owner_id`, `user_id` must match it.
 - `delete_entity(entity_id: str)`: Delete a specific entity by its ID.
 
 ### Filter Migration Note
@@ -123,6 +125,7 @@ Existing integrations that stored custom fields in entity metadata should update
 - **Proactive**: Learns how to recognize problems and their solutions, and generates guidelines that get automatically applied to new tasks.
 - **Conflict Resolution**: Update existing guidelines when new information contradicts them.
 - **On Command**: An array of tools to manage guidelines whether in the agent or through a CLI
+- **Sharing**: Publish individual entities so other agents can discover and retrieve them across namespaces.
 
 ## Architecture
 Evolve is built on a modular architecture which forms a feedback loop, taking conversation traces (trajectories) from an agent, extracting key insights into a database, feeding it back into the agent.
@@ -133,6 +136,46 @@ _Lite Mode omits the Interaction layer. All activity is performed in-agent_
   <img src="docs/assets/architecture-wide-light.svg" alt="Architecture" width="480">
 </picture>
 
+## Entity Sharing
+
+Evolve supports sharing entities across namespaces using a simple public/private visibility model.
+
+**Visibility** is stored in each entity's metadata and is private by default. Existing entities without a `visibility` field are unaffected.
+
+| Metadata field | Description |
+|---|---|
+| `owner_id` | User ID who created or last published the entity |
+| `visibility` | `"private"` (default) or `"public"` |
+| `published_at` | ISO-8601 timestamp of the most recent publish |
+
+### MCP Tools
+
+**Publishing an entity:**
+```python
+publish_entity(entity_id="42", user_id="alice")
+```
+Sets `visibility=public` and records the owner and publish timestamp.
+
+**Unpublishing:**
+```python
+unpublish_entity(entity_id="42", user_id="alice")
+```
+Reverts the entity to private. The entity stays in its namespace — only its visibility changes.
+
+**Retrieving public entities from all namespaces:**
+```python
+get_entities(task="write safer code", include_public=True)
+```
+Merges results from the caller's namespace with public entities from all other namespaces. Public results are annotated with `[public: {owner_id}]`.
+
+**Creating an entity with visibility:**
+```python
+create_entity(content="...", entity_type="guideline", visibility="public", owner_id="alice")
+```
+
+### What's deferred (Phase 1C)
+REST API endpoints (`GET /api/entities/public`, publish/unpublish routes) and UI controls are not yet implemented.
+
 ## Guideline Provenance
 Evolve automatically tracks the origin of every guideline it generates or stores. Every guideline entity contains `metadata` identifying its source:
 - `creation_mode`: Identifies how the guideline was created (`auto-phoenix` via trace observability, `auto-mcp` via trajectory saving tools, or `manual`).

altk_evolve/backend/base.py

@@ -80,6 +80,33 @@ def _post_update(self, namespace_id: str) -> None:
         """Hook called after all entity mutations are complete. No-op by default."""
         pass
 
+    def patch_entity(self, namespace_id: str, entity_id: str, entity_type: str, content_str: str, timestamp: int, metadata: dict) -> None:
+        """Update an existing entity in-place (fetch-merge-write helper).
+
+        Backends that require pre-loaded state before calling _update_entity
+        (e.g. filesystem) must override this method.
+        """
+        self._update_entity(namespace_id, entity_id, entity_type, content_str, timestamp, metadata)
+
+    def update_entity_metadata(self, namespace_id: str, entity_id: str, metadata_patch: dict) -> RecordedEntity:
+        """Merge metadata_patch into an entity's metadata without touching content.
+
+        The default implementation fetches via search_entities, merges, then calls patch_entity.
+        DB-backed backends should override with a native atomic update.
+        """
+        from altk_evolve.utils.utils import serialize_content
+
+        results = self.search_entities(namespace_id, filters={"id": entity_id}, limit=1)
+        if not results:
+            from altk_evolve.schema.exceptions import EvolveException
+
+            raise EvolveException(f"Entity '{entity_id}' not found in namespace '{namespace_id}'")
+        entity = results[0]
+        merged = {**(entity.metadata or {}), **metadata_patch}
+        timestamp = int(entity.created_at.timestamp())
+        self.patch_entity(namespace_id, entity_id, entity.type, serialize_content(entity.content), timestamp, merged)
+        return RecordedEntity(**{**entity.model_dump(), "metadata": merged})
+
     def update_entities(
         self,
         namespace_id: str,

altk_evolve/backend/filesystem.py

@@ -168,6 +168,19 @@ def _post_update(self, namespace_id: str) -> None:
         self._save_namespace_data(namespace_id, self._active_data)
         self._active_data = None
 
+    def patch_entity(self, namespace_id: str, entity_id: str, entity_type: str, content_str: str, timestamp: int, metadata: dict) -> None:
+        """Override to load namespace data, call _update_entity, then persist."""
+        if not entity_id:
+            raise ValueError(f"entity_id must be a non-empty string, got {entity_id!r}")
+        with self._lock:
+            self._active_data = self._load_namespace_data(namespace_id)
+            try:
+                self._update_entity(namespace_id, entity_id, entity_type, content_str, timestamp, metadata)
+                self._post_update(namespace_id)
+            except Exception:
+                self._active_data = None
+                raise
+
     def update_entities(
         self,
         namespace_id: str,

altk_evolve/backend/milvus.py

@@ -290,6 +290,29 @@ def _update_entity(self, namespace_id: str, entity_id: str, entity_type: str, co
     def _delete_entity(self, namespace_id: str, entity_id: str) -> None:
         self.delete_entity_by_id(namespace_id=namespace_id, entity_id=entity_id)
 
+    def update_entity_metadata(self, namespace_id: str, entity_id: str, metadata_patch: dict) -> RecordedEntity:
+        try:
+            entity_id_int = int(entity_id)
+        except ValueError:
+            raise EvolveException(f"Invalid entity ID '{entity_id}': must be numeric.")
+        self._validate_namespace(namespace_id)
+        results = self.milvus.query(
+            collection_name=namespace_id,
+            filter=f"id == {entity_id_int}",
+            output_fields=["id", "type", "content", "created_at", "metadata"],
+            limit=1,
+        )
+        if not results:
+            raise EvolveException(f"Entity '{entity_id}' not found in namespace '{namespace_id}'")
+        entity = parse_milvus_entity(results[0])
+        merged = {**(entity.metadata or {}), **metadata_patch}
+        timestamp = int(entity.created_at.timestamp())
+        from altk_evolve.utils.utils import serialize_content
+
+        self._update_entity(namespace_id, entity_id, entity.type, serialize_content(entity.content), timestamp, merged)
+        self._post_update(namespace_id)
+        return RecordedEntity(**{**entity.model_dump(), "metadata": merged})
+
     def _post_update(self, namespace_id: str) -> None:
         self.milvus.flush(namespace_id)
         self.milvus.load_collection(namespace_id)

altk_evolve/backend/postgres.py

@@ -277,6 +277,25 @@ def _update_entity(self, namespace_id: str, entity_id: str, entity_type: str, co
     def _delete_entity(self, namespace_id: str, entity_id: str) -> None:
         self.delete_entity_by_id(namespace_id=namespace_id, entity_id=entity_id)
 
+    def update_entity_metadata(self, namespace_id: str, entity_id: str, metadata_patch: dict) -> RecordedEntity:
+        try:
+            entity_id_int = int(entity_id)
+        except ValueError:
+            raise EvolveException(f"Invalid entity ID '{entity_id}': must be numeric.")
+        self._validate_namespace(namespace_id)
+        table = self._table_name(namespace_id)
+        with self.conn.cursor(row_factory=_entity_row_factory) as cur:
+            cur.execute(
+                sql.SQL(
+                    "UPDATE {table} SET metadata = metadata || %s::jsonb WHERE id = %s RETURNING id, type, content, created_at, metadata"
+                ).format(table=sql.Identifier(table)),
+                (json.dumps(metadata_patch), entity_id_int),
+            )
+            results = cur.fetchall()
+        if not results:
+            raise EvolveException(f"Entity '{entity_id}' not found in namespace '{namespace_id}'")
+        return results[0]
+
     # ── search / delete ──────────────────────────────────────────────
 
     def search_entities(

altk_evolve/frontend/client/evolve_client.py

@@ -86,6 +86,48 @@ def delete_entity_by_id(self, namespace_id: str, entity_id: str) -> None:
         """Delete a specific entity by its ID."""
         self.backend.delete_entity_by_id(namespace_id, entity_id)
 
+    def get_entity_by_id(self, namespace_id: str, entity_id: str) -> RecordedEntity | None:
+        """Fetch a single entity by its ID. Returns None if not found."""
+        results = self.search_entities(namespace_id, filters={"id": entity_id}, limit=1)
+        return results[0] if results else None
+
+    def patch_entity_metadata(self, namespace_id: str, entity_id: str, metadata_updates: dict) -> RecordedEntity:
+        """Merge metadata_updates into an entity without touching content or ID."""
+        return self.backend.update_entity_metadata(namespace_id, entity_id, metadata_updates)
+
+    def get_public_entities(
+        self,
+        query: str | None = None,
+        entity_type: str | None = None,
+        limit: int = 100,
+        exclude_namespace_ids: list[str] | None = None,
+    ) -> list[RecordedEntity]:
+        """Search for public entities across all namespaces.
+
+        Args:
+            query: Optional semantic search query.
+            entity_type: Optional type filter (e.g. 'guideline').
+            limit: Maximum total results to return.
+            exclude_namespace_ids: Namespace IDs to skip (e.g. the caller's own
+                namespace whose entities are already returned via a private search).
+        """
+        if limit <= 0:
+            return []
+
+        excluded = set(exclude_namespace_ids or [])
+        all_results: list[RecordedEntity] = []
+        for ns in self.search_namespaces(limit=1000):
+            if ns.id in excluded:
+                continue
+            remaining = limit - len(all_results)
+            if remaining <= 0:
+                break
+            filters: dict = {"metadata.visibility": "public"}
+            if entity_type:
+                filters["type"] = entity_type
+            all_results.extend(self.search_entities(ns.id, query=query, filters=filters, limit=remaining))
+        return all_results
+
     def cluster_guidelines(self, namespace_id: str, threshold: float | None = None, limit: int = 10000) -> list[list[RecordedEntity]]:
         """Cluster guideline entities by task description similarity.