feat: mental-models List view + /tags?source=mental_models (#1296)

* feat(api): list mental-model tags via /tags?source=mental_models

Adds a `source` query param to GET /v1/default/banks/{bank_id}/tags so the
same endpoint can list tags from either memory_units (default) or
mental_models. Mental-model tag suggestions previously had no API; the
alternative of a sibling /mental-models/tags route would have shadowed
GET /mental-models/{mental_model_id} for the literal id "tags".

Engine: new list_mental_model_tags method sharing a private
_list_tags_from_table helper with the existing list_tags.

Tests: covers the engine method (basic counts, wildcard) and an HTTP-level
check that source=mental_models reads from mental_models while default
remains memory_units.

* feat(control-plane): mental-models List view with tag filter

Adds a default split-pane "List" view to the Mental Models page (sidebar of
files + content on the right) and a reusable <TagFilterInput> with free-text
entry, debounced suggestions from the server, and chip selection.

Changes:
- Default Mental Models view is "List" (file/folder metaphor); the existing
  card "Dashboard" view stays as a secondary toggle. Old "Table" view removed.
- Sidebar entries show name, source query subtitle, and relative refresh time.
- Tag filtering is server-side via the existing tags/tags_match params on
  /mental-models; suggestions populate from /tags?source=mental_models.
- Memories (data-view) reuse the same TagFilterInput, gaining suggestions
  it didn't have before.
- Adds proxy route for GET /tags (forwards optional source query param).
- TagFilterInput holds the caller's fetchSuggestions in a ref to keep the
  debounce effect from refiring on every render when callers pass an inline
  closure (which would otherwise loop).

Author: nicoloboschi

hindsight-api-slim/hindsight_api/api/http.py

@@ -4323,7 +4323,8 @@ async def api_get_document(
         response_model=ListTagsResponse,
         summary="List tags",
         description="List all unique tags in a memory bank with usage counts. "
-        "Supports wildcard search using '*' (e.g., 'user:*', '*-fred', 'tag*-2'). Case-insensitive.",
+        "Supports wildcard search using '*' (e.g., 'user:*', '*-fred', 'tag*-2'). Case-insensitive. "
+        "Use `source=mental_models` to list tags used on mental models instead of memories.",
         operation_id="list_tags",
         tags=["Memory"],
     )
@@ -4334,6 +4335,10 @@ async def api_list_tags(
             description="Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). "
             "Use '*' as wildcard. Case-insensitive.",
         ),
+        source: Literal["memories", "mental_models"] = Query(
+            default="memories",
+            description="Where to read tags from: 'memories' (memory_units, default) or 'mental_models'.",
+        ),
         limit: int = Query(default=100, description="Maximum number of tags to return"),
         offset: int = Query(default=0, description="Offset for pagination"),
         request_context: RequestContext = Depends(get_request_context),
@@ -4350,17 +4355,27 @@ async def api_list_tags(
         Args:
             bank_id: Memory Bank ID (from path)
             q: Wildcard pattern to filter tags (use '*' as wildcard)
+            source: Tag source — 'memories' (memory_units, default) or 'mental_models'
             limit: Maximum number of tags to return (default: 100)
             offset: Offset for pagination (default: 0)
         """
         try:
-            data = await app.state.memory.list_tags(
-                bank_id=bank_id,
-                pattern=q,
-                limit=limit,
-                offset=offset,
-                request_context=request_context,
-            )
+            if source == "mental_models":
+                data = await app.state.memory.list_mental_model_tags(
+                    bank_id=bank_id,
+                    pattern=q,
+                    limit=limit,
+                    offset=offset,
+                    request_context=request_context,
+                )
+            else:
+                data = await app.state.memory.list_tags(
+                    bank_id=bank_id,
+                    pattern=q,
+                    limit=limit,
+                    offset=offset,
+                    request_context=request_context,
+                )
             return data
         except OperationValidationError as e:
             raise HTTPException(status_code=e.status_code, detail=e.reason)

hindsight-api-slim/hindsight_api/engine/memory_engine.py

@@ -6427,38 +6427,85 @@ async def list_tags(
 
             ctx = BankReadContext(bank_id=bank_id, operation="list_tags", request_context=request_context)
             await self._validate_operation(self._operation_validator.validate_bank_read(ctx))
+        return await self._list_tags_from_table(
+            table="memory_units",
+            bank_id=bank_id,
+            pattern=pattern,
+            limit=limit,
+            offset=offset,
+        )
+
+    async def list_mental_model_tags(
+        self,
+        bank_id: str,
+        *,
+        pattern: str | None = None,
+        limit: int = 100,
+        offset: int = 0,
+        request_context: "RequestContext",
+    ) -> dict[str, Any]:
+        """
+        List all unique tags used on mental models in a bank with usage counts.
+
+        Same wildcard semantics as list_tags. Useful to populate tag autocompletion
+        for UIs filtering mental models by tag.
+        """
+        await self._authenticate_tenant(request_context)
+        if self._operation_validator:
+            from hindsight_api.extensions import BankReadContext
+
+            ctx = BankReadContext(
+                bank_id=bank_id,
+                operation="list_mental_model_tags",
+                request_context=request_context,
+            )
+            await self._validate_operation(self._operation_validator.validate_bank_read(ctx))
+        return await self._list_tags_from_table(
+            table="mental_models",
+            bank_id=bank_id,
+            pattern=pattern,
+            limit=limit,
+            offset=offset,
+        )
+
+    async def _list_tags_from_table(
+        self,
+        *,
+        table: str,
+        bank_id: str,
+        pattern: str | None,
+        limit: int,
+        offset: int,
+    ) -> dict[str, Any]:
         pool = await self._get_pool()
         async with acquire_with_retry(pool) as conn:
             # Build pattern filter if provided (convert * to % for ILIKE)
             pattern_clause = ""
             params: list[Any] = [bank_id]
             if pattern:
-                # Convert wildcard pattern: * -> % for SQL ILIKE
                 sql_pattern = pattern.replace("*", "%")
                 pattern_clause = "AND tag ILIKE $2"
                 params.append(sql_pattern)
 
-            # Get total count of distinct tags matching pattern
             total_row = await conn.fetchrow(
                 f"""
                 SELECT COUNT(DISTINCT tag) as total
-                FROM {fq_table("memory_units")}, unnest(tags) AS tag
+                FROM {fq_table(table)}, unnest(tags) AS tag
                 WHERE bank_id = $1 AND tags IS NOT NULL AND tags != '{{}}'
                 {pattern_clause}
                 """,
                 *params,
             )
             total = total_row["total"] if total_row else 0
 
-            # Get paginated tags with counts, ordered by frequency
             limit_param = len(params) + 1
             offset_param = len(params) + 2
             params.extend([limit, offset])
 
             rows = await conn.fetch(
                 f"""
                 SELECT tag, COUNT(*) as count
-                FROM {fq_table("memory_units")}, unnest(tags) AS tag
+                FROM {fq_table(table)}, unnest(tags) AS tag
                 WHERE bank_id = $1 AND tags IS NOT NULL AND tags != '{{}}'
                 {pattern_clause}
                 GROUP BY tag

hindsight-api-slim/tests/test_tags_visibility.py

@@ -1501,3 +1501,98 @@ async def test_tag_groups_nested_and_containing_or(api_client):
     assert any("Alice" in t and "step 8" in t for t in texts), "Should find Alice step:8"
     assert not any("step 9" in t for t in texts), "Should NOT find step 9"
     assert not any("Bob" in t for t in texts), "Should NOT find Bob"
+
+
+# ============================================================================
+# Tests for list_mental_model_tags API endpoint
+# ============================================================================
+
+
+async def _create_mental_model_via_engine(memory, *, bank_id, name, tags, request_context):
+    """Helper that creates a mental model directly through the engine without an LLM call."""
+    # Ensure the bank exists (mental_models has a FK to banks).
+    await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)
+    return await memory.create_mental_model(
+        bank_id=bank_id,
+        name=name,
+        source_query=f"Source query for {name}",
+        content=f"Content for {name}",
+        tags=tags,
+        request_context=request_context,
+    )
+
+
+@pytest.mark.asyncio
+async def test_list_mental_model_tags_returns_only_mental_model_tags(memory, request_context):
+    """Mental-model tag listing should reflect only mental_models.tags, not memory_units.tags."""
+    bank_id = f"mm_tags_basic_{datetime.now().timestamp()}"
+
+    await _create_mental_model_via_engine(
+        memory, bank_id=bank_id, name="MM A", tags=["topic:alpha", "shared"], request_context=request_context
+    )
+    await _create_mental_model_via_engine(
+        memory, bank_id=bank_id, name="MM B", tags=["topic:beta", "shared"], request_context=request_context
+    )
+    await _create_mental_model_via_engine(
+        memory, bank_id=bank_id, name="MM C", tags=["topic:alpha"], request_context=request_context
+    )
+
+    result = await memory.list_mental_model_tags(bank_id=bank_id, request_context=request_context)
+
+    tags_map = {item["tag"]: item["count"] for item in result["items"]}
+    assert tags_map == {"topic:alpha": 2, "topic:beta": 1, "shared": 2}
+    assert result["total"] == 3
+
+    # Sanity check: the regular list_tags (which queries memory_units) should not see these tags
+    # since no memories exist in this bank.
+    memory_tags = await memory.list_tags(bank_id=bank_id, request_context=request_context)
+    assert memory_tags["items"] == []
+
+
+@pytest.mark.asyncio
+async def test_list_mental_model_tags_with_wildcard(memory, request_context):
+    """Wildcard 'topic:*' should only match mental-model tags with that prefix."""
+    bank_id = f"mm_tags_wildcard_{datetime.now().timestamp()}"
+
+    await _create_mental_model_via_engine(
+        memory, bank_id=bank_id, name="MM 1", tags=["topic:alpha", "user:alice"], request_context=request_context
+    )
+    await _create_mental_model_via_engine(
+        memory, bank_id=bank_id, name="MM 2", tags=["topic:beta"], request_context=request_context
+    )
+    await _create_mental_model_via_engine(
+        memory, bank_id=bank_id, name="MM 3", tags=["session:abc"], request_context=request_context
+    )
+
+    result = await memory.list_mental_model_tags(
+        bank_id=bank_id, pattern="topic:*", request_context=request_context
+    )
+
+    returned = sorted(item["tag"] for item in result["items"])
+    assert returned == ["topic:alpha", "topic:beta"]
+    assert result["total"] == 2
+
+
+@pytest.mark.asyncio
+async def test_list_tags_endpoint_with_source_mental_models(memory, request_context):
+    """`/tags?source=mental_models` returns mental-model tags, not memory_units tags."""
+    bank_id = f"mm_tags_source_{datetime.now().timestamp()}"
+
+    await _create_mental_model_via_engine(
+        memory, bank_id=bank_id, name="MM 1", tags=["alpha"], request_context=request_context
+    )
+
+    app = create_app(memory, initialize_memory=False)
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.get(
+            f"/v1/default/banks/{bank_id}/tags", params={"source": "mental_models"}
+        )
+        assert response.status_code == 200, response.text
+        body = response.json()
+        assert {item["tag"] for item in body["items"]} == {"alpha"}
+
+        # Default source ('memories') must NOT pick up the mental-model tag.
+        default_response = await client.get(f"/v1/default/banks/{bank_id}/tags")
+        assert default_response.status_code == 200, default_response.text
+        assert default_response.json()["items"] == []

hindsight-cli/src/api.rs

@@ -712,7 +712,7 @@ impl ApiClient {
         self.runtime.block_on(async {
             let response = self
                 .client
-                .list_tags(bank_id, limit, offset, q, None)
+                .list_tags(bank_id, limit, offset, q, None, None)
                 .await?;
             Ok(response.into_inner())
         })

hindsight-clients/go/api/openapi.yaml

@@ -1776,7 +1776,9 @@ paths:
   /v1/default/banks/{bank_id}/tags:
     get:
       description: "List all unique tags in a memory bank with usage counts. Supports\
-        \ wildcard search using '*' (e.g., 'user:*', '*-fred', 'tag*-2'). Case-insensitive."
+        \ wildcard search using '*' (e.g., 'user:*', '*-fred', 'tag*-2'). Case-insensitive.\
+        \ Use `source=mental_models` to list tags used on mental models instead of\
+        \ memories."
       operationId: list_tags
       parameters:
       - explode: false
@@ -1797,6 +1799,22 @@ paths:
           nullable: true
           type: string
         style: form
+      - description: "Where to read tags from: 'memories' (memory_units, default)\
+          \ or 'mental_models'."
+        explode: true
+        in: query
+        name: source
+        required: false
+        schema:
+          default: memories
+          description: "Where to read tags from: 'memories' (memory_units, default)\
+            \ or 'mental_models'."
+          enum:
+          - memories
+          - mental_models
+          title: Source
+          type: string
+        style: form
       - description: Maximum number of tags to return
         explode: true
         in: query
@@ -2127,8 +2145,8 @@ paths:
   /v1/default/banks/{bank_id}/profile:
     get:
       deprecated: true
-      description: Get disposition traits and mission for a memory bank. Auto-creates
-        agent with defaults if not exists.
+      description: Get disposition traits and mission for a memory bank. Returns 404
+        if the bank does not exist.
       operationId: get_bank_profile
       parameters:
       - explode: false

hindsight-clients/go/api_banks.go

@@ -1797,7 +1797,7 @@ async def get_bank_profile(
     ) -> BankProfileResponse:
         """(Deprecated) Get memory bank profile
 
-        Get disposition traits and mission for a memory bank. Auto-creates agent with defaults if not exists.
+        Get disposition traits and mission for a memory bank. Returns 404 if the bank does not exist.
 
         :param bank_id: (required)
         :type bank_id: str
@@ -1870,7 +1870,7 @@ async def get_bank_profile_with_http_info(
     ) -> ApiResponse[BankProfileResponse]:
         """(Deprecated) Get memory bank profile
 
-        Get disposition traits and mission for a memory bank. Auto-creates agent with defaults if not exists.
+        Get disposition traits and mission for a memory bank. Returns 404 if the bank does not exist.
 
         :param bank_id: (required)
         :type bank_id: str
@@ -1943,7 +1943,7 @@ async def get_bank_profile_without_preload_content(
     ) -> RESTResponseType:
         """(Deprecated) Get memory bank profile
 
-        Get disposition traits and mission for a memory bank. Auto-creates agent with defaults if not exists.
+        Get disposition traits and mission for a memory bank. Returns 404 if the bank does not exist.
 
         :param bank_id: (required)
         :type bank_id: str