fenix-mcp 0.1.0__py3-none-any.whl

fenix_mcp/application/tools/productivity.py

@@ -0,0 +1,220 @@
+# SPDX-License-Identifier: MIT
+"""Productivity tool implementation (TODO operations)."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, Iterable, List, Optional
+
+from pydantic import Field
+
+from fenix_mcp.application.presenters import text
+from fenix_mcp.application.tool_base import Tool, ToolRequest
+from fenix_mcp.domain.productivity import ProductivityService
+from fenix_mcp.infrastructure.context import AppContext
+
+
+class TodoAction(str, Enum):
+    def __new__(cls, value: str, description: str):
+        obj = str.__new__(cls, value)
+        obj._value_ = value
+        obj.description = description
+        return obj
+
+    CREATE = ("todo_create", "Cria um novo TODO.")
+    LIST = ("todo_list", "Lista TODOs com filtros opcionais.")
+    GET = ("todo_get", "Obtém detalhes de um TODO pelo ID.")
+    UPDATE = ("todo_update", "Atualiza campos de um TODO existente.")
+    DELETE = ("todo_delete", "Remove um TODO pelo ID.")
+    STATS = ("todo_stats", "Retorna estatísticas agregadas de TODOs.")
+    SEARCH = ("todo_search", "Busca TODOs por termo textual.")
+    OVERDUE = ("todo_overdue", "Lista TODOs atrasados.")
+    UPCOMING = ("todo_upcoming", "Lista TODOs com vencimento próximo.")
+    CATEGORIES = ("todo_categories", "Lista categorias registradas.")
+    TAGS = ("todo_tags", "Lista tags registradas.")
+    HELP = ("todo_help", "Mostra as ações suportadas e seus usos.")
+
+    @classmethod
+    def choices(cls) -> List[str]:
+        return [member.value for member in cls]
+
+    @classmethod
+    def formatted_help(cls) -> str:
+        lines = [
+            "| **Ação** | **Descrição** |",
+            "| --- | --- |",
+        ]
+        for member in cls:
+            lines.append(f"| `{member.value}` | {member.description} |")
+        return "\n".join(lines)
+
+
+ACTION_FIELD_DESCRIPTION = (
+    "Ação de produtividade (TODO). Escolha um dos valores: "
+    + ", ".join(f"`{member.value}` ({member.description.rstrip('.')})." for member in TodoAction)
+)
+
+
+class ProductivityRequest(ToolRequest):
+    action: TodoAction = Field(description=ACTION_FIELD_DESCRIPTION)
+    id: Optional[str] = Field(default=None, description="Identificador do item TODO.")
+    title: Optional[str] = Field(default=None, description="Título do TODO (obrigatório em create).")
+    content: Optional[str] = Field(default=None, description="Conteúdo em Markdown (obrigatório em create).")
+    status: Optional[str] = Field(default="pending", description="Status do TODO.")
+    priority: Optional[str] = Field(default="medium", description="Prioridade do TODO.")
+    category: Optional[str] = Field(default=None, description="Categoria opcional.")
+    tags: Optional[List[str]] = Field(default=None, description="Lista de tags.")
+    due_date: Optional[str] = Field(default=None, description="Data de vencimento do TODO (ISO).")
+    limit: int = Field(default=20, ge=1, le=100, description="Limite de resultados em list/search.")
+    offset: int = Field(default=0, ge=0, description="Offset de paginação.")
+    query: Optional[str] = Field(default=None, description="Termo de busca.")
+    days: Optional[int] = Field(default=None, ge=1, le=30, description="Janela de dias para upcoming.")
+
+
+class ProductivityTool(Tool):
+    name = "productivity"
+    description = "Operações de produtividade do Fênix Cloud (TODOs)."
+    request_model = ProductivityRequest
+
+    def __init__(self, context: AppContext):
+        self._context = context
+        self._service = ProductivityService(context.api_client, context.logger)
+
+    async def run(self, payload: ProductivityRequest, context: AppContext):
+        action = payload.action
+        if action is TodoAction.HELP:
+            return await self._handle_help()
+        if action is TodoAction.CREATE:
+            return await self._handle_create(payload)
+        if action is TodoAction.LIST:
+            return await self._handle_list(payload)
+        if action is TodoAction.GET:
+            return await self._handle_get(payload)
+        if action is TodoAction.UPDATE:
+            return await self._handle_update(payload)
+        if action is TodoAction.DELETE:
+            return await self._handle_delete(payload)
+        if action is TodoAction.STATS:
+            return await self._handle_stats()
+        if action is TodoAction.SEARCH:
+            return await self._handle_search(payload)
+        if action is TodoAction.OVERDUE:
+            return await self._handle_overdue()
+        if action is TodoAction.UPCOMING:
+            return await self._handle_upcoming(payload)
+        if action is TodoAction.CATEGORIES:
+            return await self._handle_categories()
+        if action is TodoAction.TAGS:
+            return await self._handle_tags()
+        return text(
+            "❌ Ação inválida para productivity.\n\nEscolha um dos valores:\n"
+            + "\n".join(f"- `{value}`" for value in TodoAction.choices())
+        )
+
+    async def _handle_create(self, payload: ProductivityRequest):
+        if not payload.title or not payload.content or not payload.due_date:
+            return text("❌ Forneça título, conteúdo e due_date para criar um TODO.")
+        todo = await self._service.create_todo(
+            title=payload.title,
+            content=payload.content,
+            status=payload.status or "pending",
+            priority=payload.priority or "medium",
+            category=payload.category,
+            tags=payload.tags or [],
+            due_date=payload.due_date,
+        )
+        return text(self._format_single(todo, header="✅ TODO criado com sucesso!"))
+
+    async def _handle_list(self, payload: ProductivityRequest):
+        todos = await self._service.list_todos(
+            limit=payload.limit,
+            offset=payload.offset,
+            status=payload.status,
+            priority=payload.priority,
+            category=payload.category,
+        )
+        if not todos:
+            return text("📋 Nenhum TODO encontrado.")
+        body = "\n\n".join(ProductivityService.format_todo(todo) for todo in todos)
+        return text(f"📋 **TODOs ({len(todos)}):**\n\n{body}")
+
+    async def _handle_get(self, payload: ProductivityRequest):
+        if not payload.id:
+            return text("❌ Informe o ID para consultar um TODO.")
+        todo = await self._service.get_todo(payload.id)
+        return text(self._format_single(todo, header="📋 TODO encontrado"))
+
+    async def _handle_update(self, payload: ProductivityRequest):
+        if not payload.id:
+            return text("❌ Informe o ID para atualizar um TODO.")
+        fields = {
+            "title": payload.title,
+            "content": payload.content,
+            "status": payload.status,
+            "priority": payload.priority,
+            "category": payload.category,
+            "tags": payload.tags,
+            "due_date": payload.due_date,
+        }
+        todo = await self._service.update_todo(payload.id, **fields)
+        return text(self._format_single(todo, header="✅ TODO atualizado"))
+
+    async def _handle_delete(self, payload: ProductivityRequest):
+        if not payload.id:
+            return text("❌ Informe o ID para excluir um TODO.")
+        await self._service.delete_todo(payload.id)
+        return text(f"🗑️ TODO {payload.id} removido com sucesso.")
+
+    async def _handle_stats(self):
+        stats = await self._service.stats()
+        lines = ["📊 **Estatísticas de TODOs**"]
+        for key, value in (stats or {}).items():
+            lines.append(f"- {key}: {value}")
+        return text("\n".join(lines))
+
+    async def _handle_search(self, payload: ProductivityRequest):
+        if not payload.query:
+            return text("❌ Informe um termo de busca (query).")
+        todos = await self._service.search(payload.query, limit=payload.limit, offset=payload.offset)
+        if not todos:
+            return text("🔍 Nenhum TODO encontrado para a busca.")
+        body = "\n\n".join(ProductivityService.format_todo(todo) for todo in todos)
+        return text(f"🔍 **Resultados da busca ({len(todos)}):**\n\n{body}")
+
+    async def _handle_overdue(self):
+        todos = await self._service.overdue()
+        if not todos:
+            return text("✅ Sem TODOs atrasados no momento.")
+        body = "\n\n".join(ProductivityService.format_todo(todo) for todo in todos)
+        return text(f"⏰ **TODOs atrasados ({len(todos)}):**\n\n{body}")
+
+    async def _handle_upcoming(self, payload: ProductivityRequest):
+        todos = await self._service.upcoming(days=payload.days)
+        if not todos:
+            return text("📅 Nenhum TODO previsto para o período informado.")
+        body = "\n\n".join(ProductivityService.format_todo(todo) for todo in todos)
+        header = f"📅 TODOs programados ({len(todos)}):"
+        if payload.days:
+            header += f" próximos {payload.days} dias"
+        return text(f"{header}\n\n{body}")
+
+    async def _handle_categories(self):
+        categories = await self._service.categories()
+        if not categories:
+            return text("🏷️ Nenhuma categoria registrada ainda.")
+        body = "\n".join(f"- {category}" for category in categories)
+        return text(f"🏷️ **Categorias utilizadas:**\n{body}")
+
+    async def _handle_tags(self):
+        tags = await self._service.tags()
+        if not tags:
+            return text("🔖 Nenhuma tag registrada ainda.")
+        body = "\n".join(f"- {tag}" for tag in tags)
+        return text(f"🔖 **Tags utilizadas:**\n{body}")
+
+    async def _handle_help(self):
+        return text("📚 **Ações disponíveis para productivity**\n\n" + TodoAction.formatted_help())
+
+    @staticmethod
+    def _format_single(todo: Dict[str, Any], *, header: str) -> str:
+        return "\n".join([header, "", ProductivityService.format_todo(todo)])

fenix_mcp/application/tools/user_config.py

@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: MIT
+"""User configuration tool implementation."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Dict, List, Optional
+
+from pydantic import Field
+
+from fenix_mcp.application.presenters import text
+from fenix_mcp.application.tool_base import Tool, ToolRequest
+from fenix_mcp.domain.user_config import UserConfigService, _strip_none
+from fenix_mcp.infrastructure.context import AppContext
+
+
+class UserConfigAction(str, Enum):
+    def __new__(cls, value: str, description: str):
+        obj = str.__new__(cls, value)
+        obj._value_ = value
+        obj.description = description
+        return obj
+
+    CREATE = ("create", "Cria um novo user core document.")
+    LIST = ("list", "Lista documentos com paginação opcional.")
+    GET = ("get", "Obtém detalhes de um documento específico.")
+    UPDATE = ("update", "Atualiza campos de um documento existente.")
+    DELETE = ("delete", "Remove um documento.")
+    HELP = ("help", "Mostra as ações disponíveis e seus usos.")
+
+    @classmethod
+    def choices(cls) -> List[str]:
+        return [member.value for member in cls]
+
+    @classmethod
+    def formatted_help(cls) -> str:
+        lines = [
+            "| **Ação** | **Descrição** |",
+            "| --- | --- |",
+        ]
+        for member in cls:
+            lines.append(f"| `{member.value}` | {member.description} |")
+        return "\n".join(lines)
+
+
+ACTION_FIELD_DESCRIPTION = (
+    "Ação a executar. Escolha um dos valores: "
+    + ", ".join(f"`{member.value}` ({member.description.rstrip('.')})." for member in UserConfigAction)
+)
+
+
+class UserConfigRequest(ToolRequest):
+    action: UserConfigAction = Field(description=ACTION_FIELD_DESCRIPTION)
+    id: Optional[str] = Field(default=None, description="ID do documento.")
+    name: Optional[str] = Field(default=None, description="Nome do documento.")
+    content: Optional[str] = Field(default=None, description="Conteúdo em Markdown/JSON.")
+    mode_id: Optional[str] = Field(default=None, description="ID do modo associado.")
+    is_default: Optional[bool] = Field(default=None, description="Marca o documento como padrão.")
+    limit: int = Field(default=20, ge=1, le=100, description="Limite para listagem.")
+    offset: int = Field(default=0, ge=0, description="Offset para listagem.")
+    return_content: Optional[bool] = Field(default=None, description="Retorna conteúdo completo.")
+
+
+class UserConfigTool(Tool):
+    name = "user_config"
+    description = "Gerencia documentos de configuração do usuário (Core Documents)."
+    request_model = UserConfigRequest
+
+    def __init__(self, context: AppContext):
+        self._context = context
+        self._service = UserConfigService(context.api_client)
+
+    async def run(self, payload: UserConfigRequest, context: AppContext):
+        action = payload.action
+        if action is UserConfigAction.HELP:
+            return await self._handle_help()
+        if action is UserConfigAction.CREATE:
+            if not payload.name or not payload.content:
+                return text("❌ Informe name e content para criar o documento.")
+            doc = await self._service.create(
+                _strip_none(
+                    {
+                        "name": payload.name,
+                        "content": payload.content,
+                        "mode_id": payload.mode_id,
+                        "is_default": payload.is_default,
+                    }
+                )
+            )
+            return text(_format_doc(doc, header="✅ Documento criado"))
+
+        if action is UserConfigAction.LIST:
+            docs = await self._service.list(
+                limit=payload.limit,
+                offset=payload.offset,
+                returnContent=payload.return_content,
+            )
+            if not docs:
+                return text("📂 Nenhum documento encontrado.")
+            body = "\n\n".join(_format_doc(doc) for doc in docs)
+            return text(f"📂 **Documentos ({len(docs)}):**\n\n{body}")
+
+        if action is UserConfigAction.GET:
+            if not payload.id:
+                return text("❌ Informe o ID do documento.")
+            doc = await self._service.get(
+                payload.id,
+                returnContent=payload.return_content,
+            )
+            return text(_format_doc(doc, header="📂 Detalhes do documento"))
+
+        if action is UserConfigAction.UPDATE:
+            if not payload.id:
+                return text("❌ Informe o ID do documento para atualizar.")
+            data = _strip_none(
+                {
+                    "name": payload.name,
+                    "content": payload.content,
+                    "mode_id": payload.mode_id,
+                    "is_default": payload.is_default,
+                }
+            )
+            doc = await self._service.update(payload.id, data)
+            return text(_format_doc(doc, header="✅ Documento atualizado"))
+
+        if action is UserConfigAction.DELETE:
+            if not payload.id:
+                return text("❌ Informe o ID do documento." )
+            await self._service.delete(payload.id)
+            return text(f"🗑️ Documento {payload.id} removido.")
+
+        return text(
+            "❌ Ação de user_config não suportada.\n\nEscolha um dos valores:\n"
+            + "\n".join(f"- `{value}`" for value in UserConfigAction.choices())
+        )
+
+    async def _handle_help(self):
+        return text("📚 **Ações disponíveis para user_config**\n\n" + UserConfigAction.formatted_help())
+
+
+def _format_doc(doc: Dict[str, Any], header: Optional[str] = None) -> str:
+    lines: List[str] = []
+    if header:
+        lines.append(header)
+        lines.append("")
+    lines.extend(
+        [
+            f"📂 **{doc.get('name', 'Sem nome')}**",
+            f"ID: {doc.get('id', 'N/A')}",
+            f"Default: {doc.get('is_default', False)}",
+        ]
+    )
+    if doc.get("mode_id"):
+        lines.append(f"Modo associado: {doc['mode_id']}")
+    if doc.get("content") and len(doc["content"]) <= 400:
+        lines.append("")
+        lines.append(doc["content"])
+    return "\n".join(lines)

fenix_mcp/domain/initialization.py

@@ -0,0 +1,180 @@
+# SPDX-License-Identifier: MIT
+"""Domain helpers for initialization operations."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from fenix_mcp.infrastructure.fenix_api.client import FenixApiClient
+
+
+@dataclass(slots=True)
+class InitializationData:
+    profile: Optional[Dict[str, Any]]
+    core_documents: List[Dict[str, Any]]
+    user_documents: List[Dict[str, Any]]
+    recent_memories: List[Dict[str, Any]]
+
+
+class InitializationService:
+    """Fetch and format initialization data from the Fênix API."""
+
+    def __init__(self, api_client: FenixApiClient, logger):
+        self._api = api_client
+        self._logger = logger
+
+    async def gather_data(self, *, include_user_docs: bool, limit: int) -> InitializationData:
+        profile = await self._safe_call(self._api.get_profile)
+        core_docs = await self._safe_call(
+            self._api.list_core_documents,
+            return_content=True,
+        )
+        if self._logger:
+            self._logger.debug("Core docs response", extra={"core_docs": core_docs})
+        user_docs: List[Dict[str, Any]] = []
+        if include_user_docs:
+            user_docs = await self._safe_call(
+                self._api.list_user_core_documents,
+                return_content=True,
+            ) or []
+            if self._logger:
+                self._logger.debug("User docs response", extra={"user_docs": user_docs})
+        memories = await self._safe_call(
+            self._api.list_memories,
+            include_content=True,
+            include_metadata=False,
+            limit=3,
+            offset=0,
+            sortBy="created_at",
+            sortOrder="desc",
+        )
+        if self._logger:
+            self._logger.debug("Memories response", extra={"memories": memories})
+
+        return InitializationData(
+            profile=profile,
+            core_documents=self._extract_items(core_docs, "coreDocuments"),
+            user_documents=self._extract_items(user_docs, "userCoreDocuments"),
+            recent_memories=self._extract_items(memories, "memories"),
+        )
+
+    async def _safe_call(self, func, *args, **kwargs):
+        try:
+            return await asyncio.to_thread(func, *args, **kwargs)
+        except Exception as exc:  # pragma: no cover - defensive logging path
+            self._logger.warning("Initialization API call failed: %s", exc)
+            return None
+
+    @staticmethod
+    def _extract_items(payload: Any, key: str) -> List[Dict[str, Any]]:
+        if payload is None:
+            return []
+        if isinstance(payload, list):
+            return [item for item in payload if isinstance(item, dict)]
+        if isinstance(payload, dict):
+            value = payload.get(key) or payload.get("data")
+            if isinstance(value, list):
+                return [item for item in value if isinstance(item, dict)]
+        return []
+
+    @staticmethod
+    def build_existing_user_summary(data: InitializationData, include_user_docs: bool) -> str:
+        profile = data.profile or {}
+        user_info = profile.get("user") or {}
+        tenant_info = profile.get("tenant") or {}
+        core_count = len(data.core_documents)
+        user_count = len(data.user_documents)
+        memories_count = len(data.recent_memories)
+
+        lines = [
+            "✅ **Fênix Cloud inicializado com sucesso!**",
+        ]
+
+        if user_info:
+            lines.append(
+                f"- Usuário: {user_info.get('name') or 'Desconhecido'} "
+                f"(ID: {user_info.get('id', 'N/A')})"
+            )
+        if tenant_info:
+            lines.append(f"- Organização: {tenant_info.get('name', 'N/A')}")
+
+        lines.append(f"- Documentos principais carregados: {core_count}")
+
+        if include_user_docs:
+            lines.append(f"- Documentos pessoais carregados: {user_count}")
+
+        lines.append(f"- Memórias recentes disponíveis: {memories_count}")
+
+        if core_count:
+            preview = ", ".join(
+                doc.get("name", doc.get("title", "sem título")) for doc in data.core_documents[:5]
+            )
+            lines.append(f"- Exemplos de documentos principais: {preview}")
+
+        if include_user_docs and user_count:
+            preview = ", ".join(doc.get("name", "sem título") for doc in data.user_documents[:5])
+            lines.append(f"- Exemplos de documentos pessoais: {preview}")
+
+        if memories_count:
+            preview = ", ".join(mem.get("title", "sem título") for mem in data.recent_memories[:3])
+            lines.append(f"- Memórias recentes: {preview}")
+
+        lines.append("")
+        lines.append(
+            "Agora você pode usar as ferramentas de produtividade, conhecimento e inteligência para continuar."
+        )
+        return "\n".join(lines)
+
+    @staticmethod
+    def build_new_user_prompt(data: InitializationData) -> str:
+        profile = data.profile or {}
+        user_name = (profile.get("user") or {}).get("name") or "Bem-vindo(a)"
+
+        questions = [
+            "Qual é o foco principal do seu trabalho atualmente?",
+            "Quais são seus objetivos para as próximas semanas?",
+            "Existem tarefas ou projetos que gostaria de priorizar?",
+            "Como você prefere organizar suas rotinas ou checklists?",
+            "Quais são os principais blocos de conhecimento que precisa acessar rapidamente?",
+            "Há regras ou procedimentos que precisam ser seguidos com frequência?",
+            "Que tipo de memória ou registro você consulta com frequência?",
+            "Quais ferramentas ou integrações externas são essenciais no seu dia a dia?",
+            "O que significaria sucesso para você utilizando o Fênix?",
+        ]
+
+        body = [
+            f"👋 **{user_name}, bem-vindo(a) ao Fênix Cloud!**",
+            "",
+            "Notamos que você ainda não tem documentos pessoais configurados. "
+            "Vamos criar uma experiência personalizada para você.",
+            "",
+            "Responda às perguntas abaixo para que possamos preparar modos, regras e documentos alinhados às suas necessidades:",
+            "",
+        ]
+
+        body.extend(f"{idx + 1}. {question}" for idx, question in enumerate(questions))
+        body.extend(
+            [
+                "",
+                "Envie as respostas no formato:",
+                "```",
+                'initialize action=setup answers=["resposta 1", "resposta 2", ..., "resposta 9"]',
+                "```",
+                "",
+                "Com base nisso, sugerirei documentos, regras e rotinas para você utilizar.",
+            ]
+        )
+
+        return "\n".join(body)
+
+    @staticmethod
+    def validate_setup_answers(answers: List[str]) -> Optional[str]:
+        if not answers:
+            return "Envie uma lista com 9 respostas para processarmos o setup."
+        if len(answers) != 9:
+            return f"Esperado receber 9 respostas, mas recebi {len(answers)}."
+        if not all(isinstance(answer, str) and answer.strip() for answer in answers):
+            return "Todas as respostas devem ser textos preenchidos."
+        return None

fenix_mcp/domain/intelligence.py

@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: MIT
+"""Domain helpers for intelligence (memory) operations."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Optional
+
+from fenix_mcp.infrastructure.fenix_api.client import FenixApiClient
+
+
+@dataclass(slots=True)
+class IntelligenceService:
+    api: FenixApiClient
+    logger: Any
+
+    async def smart_create_memory(
+        self,
+        *,
+        title: str,
+        content: str,
+        context: Optional[str],
+        source: Optional[str],
+        importance: str,
+        tags: Optional[Iterable[str]] = None,
+    ) -> Dict[str, Any]:
+        metadata_parts: List[str] = []
+        if context:
+            metadata_parts.append(f"Contexto: {context}")
+        if source:
+            metadata_parts.append(f"Fonte: {source}")
+
+        payload = {
+            "title": title,
+            "content": content,
+            "metadata": "\n".join(metadata_parts) if metadata_parts else None,
+            "priority_score": _importance_to_priority(importance),
+            "tags": list(tags) if tags else None,
+        }
+        return await self._call(self.api.smart_create_memory, _strip_none(payload))
+
+    async def query_memories(self, **filters: Any) -> List[Dict[str, Any]]:
+        params = _strip_none(filters)
+        include_content = bool(params.pop("content", True))
+        include_metadata = bool(params.pop("metadata", False))
+        return await self._call(
+            self.api.list_memories,
+            include_content=include_content,
+            include_metadata=include_metadata,
+            **params,
+        ) or []
+
+    async def similar_memories(
+        self, *, content: str, threshold: float, max_results: int
+    ) -> List[Dict[str, Any]]:
+        payload = {
+            "content": content,
+            "threshold": threshold,
+        }
+        result = await self._call(self.api.find_similar_memories, _strip_none(payload)) or []
+        if isinstance(result, list) and max_results:
+            return result[:max_results]
+        return result
+
+    async def consolidate_memories(
+        self, *, memory_ids: Iterable[str], strategy: str
+    ) -> Dict[str, Any]:
+        payload = {
+            "memoryIds": list(memory_ids),
+            "strategy": strategy,
+        }
+        return await self._call(self.api.consolidate_memories, payload)
+
+    async def priority_memories(self, *, limit: int) -> List[Dict[str, Any]]:
+        params = {
+            "limit": limit,
+            "sortBy": "priority_score",
+            "sortOrder": "desc",
+        }
+        return await self._call(
+            self.api.list_memories,
+            include_content=False,
+            include_metadata=False,
+            **params,
+        ) or []
+
+    async def analytics(self, *, time_range: str, group_by: str) -> Dict[str, Any]:
+        memories = await self.query_memories(limit=200, timeRange=time_range, groupBy=group_by)
+        summary: Dict[str, Any] = {
+            "total_memories": len(memories),
+            "by_group": {},
+        }
+        group_key = group_by
+        for memory in memories:
+            key = memory.get(group_key) or memory.get("metadata") or "N/A"
+            summary["by_group"][key] = summary["by_group"].get(key, 0) + 1
+        return summary
+
+    async def update_memory(self, memory_id: str, **fields: Any) -> Dict[str, Any]:
+        payload = _strip_none(fields)
+        if "importance" in payload:
+            payload["priority_score"] = _importance_to_priority(payload.pop("importance"))
+        mapping = {
+            "documentation_item_id": "documentationItemId",
+            "mode_id": "modeId",
+            "rule_id": "ruleId",
+            "work_item_id": "workItemId",
+            "sprint_id": "sprintId",
+        }
+        for old_key, new_key in mapping.items():
+            if old_key in payload:
+                payload[new_key] = payload.pop(old_key)
+        return await self._call(self.api.update_memory, memory_id, payload)
+
+    async def _call(self, func, *args, **kwargs):
+        return await asyncio.to_thread(func, *args, **kwargs)
+
+
+def _importance_to_priority(importance: Optional[str]) -> float:
+    mapping = {
+        "low": 0.2,
+        "medium": 0.5,
+        "high": 0.7,
+        "critical": 0.9,
+    }
+    if importance is None:
+        return 0.5
+    return mapping.get(importance.lower(), 0.5)
+
+
+def _strip_none(data: Dict[str, Any]) -> Dict[str, Any]:
+    return {key: value for key, value in data.items() if value not in (None, "")}