ocerebro 0.1.0

package/src/forgetting/gc.py

@@ -0,0 +1,296 @@
+"""Garbage collection para memórias do Cerebro.
+
+Replica a lógica de garbage collection do Claude Code:
+- Filtra por mtime do arquivo (última modificação)
+- Nunca remove memórias de tipo 'user' ou 'feedback'
+- Aplica threshold de dias sem acesso para working sessions
+"""
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from src.memdir.scanner import parse_frontmatter
+from src.core.paths import MAX_MEMORY_FILES
+
+
+class GarbageCollector:
+    """
+    Garbage collection para memórias.
+
+    Identifica memórias candidatas para arquivamento ou remoção
+    baseado em policies de forgetting.
+    """
+
+    def __init__(self, config_path: Path):
+        """
+        Inicializa o GarbageCollector.
+
+        Args:
+            config_path: Path para configuração
+        """
+        self.config_path = config_path
+
+    def find_candidates_for_archive(
+        self,
+        memory_dir: Path,
+        days_threshold: int
+    ) -> List[Dict[str, Any]]:
+        """
+        Encontra memórias candidatas para arquivamento.
+
+        Args:
+            memory_dir: Diretório de memória para scan
+            days_threshold: Dias mínimos para arquivar
+
+        Returns:
+            Lista de memórias candidatas
+        """
+        candidates = []
+        now = datetime.now()
+        cutoff_ts = (now.timestamp()) - (days_threshold * 24 * 60 * 60)
+
+        if not memory_dir.exists():
+            return candidates
+
+        # Scan de arquivos .md (excluindo MEMORY.md)
+        for file_path in memory_dir.rglob("*.md"):
+            if file_path.name == "MEMORY.md":
+                continue
+
+            try:
+                # Usa mtime (última modificação) em vez de created_at
+                mtime = file_path.stat().st_mtime
+
+                if mtime < cutoff_ts:
+                    # Verifica tipo no frontmatter
+                    content = file_path.read_text(encoding="utf-8")[:2000]
+                    frontmatter = parse_frontmatter(content)
+                    mem_type = frontmatter.get("type")
+
+                    # Nunca arquiva memórias de tipo 'user' ou 'feedback'
+                    if mem_type in ['user', 'feedback']:
+                        continue
+
+                    candidates.append({
+                        "file_path": str(file_path),
+                        "filename": file_path.name,
+                        "type": mem_type,
+                        "name": frontmatter.get("name"),
+                        "description": frontmatter.get("description"),
+                        "mtime": mtime,
+                        "days_since_modified": int((now.timestamp() - mtime) / (24 * 60 * 60))
+                    })
+            except Exception:
+                # Silenciosamente ignora arquivos com erro
+                continue
+
+        return candidates
+
+    def find_candidates_for_deletion(
+        self,
+        candidates: List[Dict[str, Any]],
+        deletion_threshold_days: int = 30
+    ) -> List[Dict[str, Any]]:
+        """
+        Encontra memórias candidatas para deleção.
+
+        Critérios:
+        - mtime > deletion_threshold_days (mais antigo que threshold)
+        - Tipo NÃO é 'user', 'feedback', ou 'project' com atividade recente
+        - Não está linkada no MEMORY.md
+
+        Args:
+            candidates: Lista de memórias candidatas (do find_candidates_for_archive)
+            deletion_threshold_days: Dias para deleção (default: 30)
+
+        Returns:
+            Lista de memórias candidatas para deleção
+        """
+        deletion_candidates = []
+        now = datetime.now()
+        deletion_cutoff = now.timestamp() - (deletion_threshold_days * 24 * 60 * 60)
+
+        for memory in candidates:
+            mtime = memory.get("mtime", 0)
+            mem_type = memory.get("type")
+
+            # Nunca deleta user ou feedback
+            if mem_type in ['user', 'feedback']:
+                continue
+
+            # Deleta se mtime > threshold
+            if mtime < deletion_cutoff:
+                deletion_candidates.append(memory)
+
+        return deletion_candidates
+
+    def log_gc_event(
+        self,
+        action: str,
+        memory_id: str,
+        reason: str,
+        log_path: Path
+    ) -> None:
+        """
+        Loga evento de GC.
+
+        Args:
+            action: Ação realizada (archive, delete)
+            memory_id: ID da memória
+            reason: Motivo da ação
+            log_path: Path para arquivo de log
+        """
+        timestamp = datetime.now(timezone.utc).isoformat()
+        log_entry = f"{timestamp} | {action} | {memory_id} | {reason}\n"
+
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(log_path, "a", encoding="utf-8") as f:
+            f.write(log_entry)
+
+    def run_gc(
+        self,
+        memory_dir: Path,
+        archive_threshold_days: int = 7,
+        deletion_threshold_days: int = 30,
+        dry_run: bool = True,
+        log_path: Optional[Path] = None
+    ) -> Dict[str, Any]:
+        """
+        Executa garbage collection.
+
+        Args:
+            memory_dir: Diretório de memória para scan
+            archive_threshold_days: Dias para arquivamento (default: 7)
+            deletion_threshold_days: Dias para deleção (default: 30)
+            dry_run: Se True, apenas lista candidatas, não remove
+            log_path: Path para log (opcional)
+
+        Returns:
+            Dicionário com resultados do GC
+        """
+        results = {
+            "archive_candidates": [],
+            "deletion_candidates": [],
+            "archived": [],
+            "deleted": [],
+            "dry_run": dry_run
+        }
+
+        # Passo 1: Encontra candidatas para arquivamento
+        archive_candidates = self.find_candidates_for_archive(
+            memory_dir, archive_threshold_days
+        )
+        results["archive_candidates"] = [c["filename"] for c in archive_candidates]
+
+        # Passo 2: Encontra candidatas para deleção
+        deletion_candidates = self.find_candidates_for_deletion(
+            archive_candidates, deletion_threshold_days
+        )
+        results["deletion_candidates"] = [c["filename"] for c in deletion_candidates]
+
+        # Passo 3: Aplica GC (se não for dry_run)
+        if not dry_run:
+            for candidate in deletion_candidates:
+                try:
+                    file_path = Path(candidate["file_path"])
+                    file_path.unlink()
+                    results["deleted"].append(candidate["filename"])
+
+                    if log_path:
+                        self.log_gc_event(
+                            "delete",
+                            candidate["filename"],
+                            f"GC: {candidate['days_since_modified']} dias sem modificação",
+                            log_path
+                        )
+                except Exception as e:
+                    # Loga erro mas continua
+                    if log_path:
+                        self.log_gc_event("error", candidate["filename"], str(e), log_path)
+
+            # Arquiva as restantes (não deletadas)
+            import shutil
+
+            arquivo_dir = memory_dir / "arquivo"
+            arquivo_dir.mkdir(parents=True, exist_ok=True)
+
+            memory_index = memory_dir / "MEMORY.md"
+
+            for candidate in archive_candidates:
+                if candidate["filename"] not in results["deleted"]:
+                    src_path = Path(candidate["file_path"])
+                    dst_path = arquivo_dir / src_path.name
+                    try:
+                        shutil.move(str(src_path), str(dst_path))
+                        results["archived"].append(candidate["filename"])
+
+                        # Remove referência do MEMORY.md
+                        if memory_index.exists():
+                            lines = memory_index.read_text(encoding="utf-8").splitlines()
+                            updated = [
+                                l for l in lines
+                                if candidate["filename"] not in l
+                            ]
+                            memory_index.write_text(
+                                "\n".join(updated), encoding="utf-8"
+                            )
+
+                        if log_path:
+                            self.log_gc_event(
+                                "archive",
+                                candidate["filename"],
+                                f"GC: {candidate['days_since_modified']} dias sem modificação",
+                                log_path
+                            )
+                    except Exception as e:
+                        if log_path:
+                            self.log_gc_event(
+                                "error", candidate["filename"], str(e), log_path
+                            )
+
+        return results
+
+    def generate_gc_report(self, results: Dict[str, Any]) -> str:
+        """
+        Gera relatório legível do GC.
+
+        Args:
+            results: Dicionário de resultados do run_gc
+
+        Returns:
+            Relatório em markdown
+        """
+        lines = [
+            "# Garbage Collection Report",
+            "",
+            f"**Modo:** {'Dry-run (nenhuma modificação)' if results['dry_run'] else 'Aplicação direta'}",
+            "",
+            "## Resumo",
+            "",
+            f"- Candidatas para arquivamento: {len(results['archive_candidates'])}",
+            f"- Candidatas para deleção: {len(results['deletion_candidates'])}",
+            f"- Arquivadas: {len(results['archived'])}",
+            f"- Deletadas: {len(results['deleted'])}",
+            "",
+        ]
+
+        if results["archive_candidates"]:
+            lines.append("## Candidatas para Arquivamento")
+            lines.append("")
+            for filename in results["archive_candidates"]:
+                lines.append(f"- {filename}")
+            lines.append("")
+
+        if results["deletion_candidates"]:
+            lines.append("## Candidatas para Deleção")
+            lines.append("")
+            for filename in results["deletion_candidates"]:
+                lines.append(f"- {filename}")
+            lines.append("")
+
+        if not results["archive_candidates"] and not results["deletion_candidates"]:
+            lines.append("Nenhuma memória candidata para GC.")
+            lines.append("")
+
+        return "\n".join(lines)

package/src/forgetting/guard_rails.py

@@ -0,0 +1,126 @@
+"""Guard rails para forgetting do Cerebro"""
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict
+import yaml
+
+
+class GuardRails:
+    """
+    Guard rails para políticas de forgetting.
+
+    Implementa regras de:
+    - never_delete: memórias que nunca podem ser deletadas
+    - always_archive: memórias que devem ser arquivadas após período
+    """
+
+    def __init__(self, config_path: Path):
+        """
+        Inicializa o GuardRails.
+
+        Args:
+            config_path: Path para arquivo de configuração YAML
+        """
+        self.config_path = config_path
+        self.config = self._load_config()
+
+    def _load_config(self) -> Dict:
+        """
+        Carrega configuração.
+
+        Returns:
+            Dicionário de configuração
+        """
+        if not self.config_path.exists():
+            return {
+                "never_delete": ["decisions.critical", "errors.severity=high"],
+                "always_archive": {"raw": 30, "working": 90}
+            }
+
+        return yaml.safe_load(self.config_path.read_text())
+
+    def can_delete(self, memory: Dict[str, Any]) -> bool:
+        """
+        Verifica se pode deletar uma memória.
+
+        Args:
+            memory: Dados da memória
+
+        Returns:
+            True se pode deletar, False se está protegida
+        """
+        rules = self.config.get("never_delete", [])
+
+        for rule in rules:
+            if self._matches_rule(memory, rule):
+                return False
+
+        return True
+
+    def _matches_rule(self, memory: Dict[str, Any], rule: str) -> bool:
+        """
+        Verifica se memória corresponde à regra.
+
+        Args:
+            memory: Dados da memória
+            rule: Regra a verificar
+
+        Returns:
+            True se corresponde à regra
+        """
+        if rule == "decisions.critical":
+            return memory.get("type") == "decision" and "critical" in memory.get("tags", [])
+
+        if rule == "errors.severity=high":
+            return memory.get("type") == "error" and memory.get("severity") in ["high", "critical"]
+
+        if rule == "errors.impact=critical":
+            return memory.get("type") == "error" and memory.get("impact") == "critical"
+
+        return False
+
+    def should_archive(self, memory: Dict[str, Any], days_threshold: int) -> bool:
+        """
+        Verifica se deve arquivar uma memória.
+
+        Args:
+            memory: Dados da memória
+            days_threshold: Dias mínimos para arquivar
+
+        Returns:
+            True se deve arquivar
+        """
+        created = memory.get("created_at")
+        if not created:
+            return False
+
+        created_dt = datetime.fromisoformat(created.replace("Z", "+00:00"))
+        days_old = (datetime.now(timezone.utc) - created_dt).days
+
+        return days_old > days_threshold
+
+    def get_archive_threshold(self, layer: str) -> int:
+        """
+        Obtém threshold de arquivamento por camada.
+
+        Args:
+            layer: Nome da camada (raw, working, official)
+
+        Returns:
+            Dias threshold para arquivamento
+        """
+        thresholds = self.config.get("always_archive", {})
+        return thresholds.get(layer, 90)
+
+    def is_protected(self, memory: Dict[str, Any]) -> bool:
+        """
+        Verifica se memória está protegida contra deleção.
+
+        Args:
+            memory: Dados da memória
+
+        Returns:
+            True se está protegida
+        """
+        return not self.can_delete(memory)

package/src/hooks/__init__.py

@@ -0,0 +1,11 @@
+"""Hooks do Cerebro: captura de eventos"""
+from .core_captures import CoreCaptures
+from .custom_loader import HooksLoader, HookRunner, HookConfig, create_sample_hooks_config
+
+__all__ = [
+    "CoreCaptures",
+    "HooksLoader",
+    "HookRunner",
+    "HookConfig",
+    "create_sample_hooks_config"
+]

package/src/hooks/core_captures.py

@@ -0,0 +1,170 @@
+"""Captura de eventos core do Cerebro"""
+
+from typing import Any, Dict, Optional
+from pathlib import Path
+from src.core.jsonl_storage import JSONLStorage
+from src.core.event_schema import Event, EventType, EventOrigin
+from src.hooks.custom_loader import HooksLoader, HookRunner
+
+
+class CoreCaptures:
+    """
+    Captura de eventos core do Cerebro.
+
+    Fornece métodos para capturar:
+    - Tool calls (chamadas de ferramentas)
+    - Git events (eventos do git)
+    - Test results (resultados de testes)
+    - Errors (erros críticos)
+
+    Hooks customizados são executados automaticamente após cada captura.
+    """
+
+    def __init__(
+        self,
+        storage: JSONLStorage,
+        project: str,
+        session_id: str,
+        hooks_config_path: Optional[Path] = None
+    ):
+        """
+        Inicializa o CoreCaptures.
+
+        Args:
+            storage: Instância do JSONLStorage
+            project: Nome do projeto
+            session_id: ID da sessão
+            hooks_config_path: Path para hooks.yaml (opcional)
+        """
+        self.storage = storage
+        self.project = project
+        self.session_id = session_id
+
+        # Inicializa hooks loader e runner
+        if hooks_config_path is None:
+            hooks_config_path = Path("hooks.yaml")
+
+        self.hooks_loader = HooksLoader(hooks_config_path)
+        self.hooks_runner = HookRunner(self.hooks_loader, context={
+            "project": project,
+            "session_id": session_id
+        })
+
+    def _create_event(
+        self,
+        event_type: EventType,
+        subtype: str,
+        payload: Dict[str, Any],
+        tags: list = None
+    ) -> Event:
+        """
+        Cria e persiste evento, executando hooks customizados.
+
+        Args:
+            event_type: Tipo do evento
+            subtype: Subtipo do evento
+            payload: Dados do evento
+            tags: Tags opcionais
+
+        Returns:
+            Evento criado
+        """
+        event = Event(
+            project=self.project,
+            origin=EventOrigin.CLAUDE_CODE,
+            event_type=event_type,
+            subtype=subtype,
+            payload=payload,
+            tags=tags or [],
+            session_id=self.session_id
+        )
+        self.storage.append(event)
+
+        # Executa hooks customizados para este evento
+        self.hooks_runner.execute(event)
+
+        return event
+
+    def tool_call(self, tool: str, call_data: Dict[str, Any], result: Dict[str, Any]) -> Event:
+        """
+        Captura tool call.
+
+        Args:
+            tool: Nome da ferramenta
+            call_data: Dados da chamada
+            result: Resultado da execução
+
+        Returns:
+            Evento capturado
+        """
+        return self._create_event(
+            EventType.TOOL_CALL,
+            tool,
+            {
+                "call": call_data,
+                "result": result
+            }
+        )
+
+    def git_event(self, action: str, data: Dict[str, Any]) -> Event:
+        """
+        Captura git event.
+
+        Args:
+            action: Ação do git (commit, branch, merge, etc)
+            data: Dados do evento
+
+        Returns:
+            Evento capturado
+        """
+        return self._create_event(
+            EventType.GIT_EVENT,
+            action,
+            data
+        )
+
+    def test_result(self, test_type: str, test_name: str, status: str, duration: float, error: str = None) -> Event:
+        """
+        Captura test result.
+
+        Args:
+            test_type: Tipo de teste (unit, integration, e2e)
+            test_name: Nome do teste
+            status: Status (pass, fail, skip)
+            duration: Duração em segundos
+            error: Mensagem de erro (opcional)
+
+        Returns:
+            Evento capturado
+        """
+        payload = {
+            "test_name": test_name,
+            "status": status,
+            "duration": duration
+        }
+        if error:
+            payload["error"] = error
+
+        return self._create_event(
+            EventType.TEST_RESULT,
+            test_type,
+            payload
+        )
+
+    def error(self, error_type: str, context: Dict[str, Any]) -> Event:
+        """
+        Captura erro.
+
+        Args:
+            error_type: Tipo do erro
+            context: Contexto do erro
+
+        Returns:
+            Evento capturado
+        """
+        return self._create_event(
+            EventType.ERROR,
+            error_type,
+            context,
+            tags=["error", "critical"]
+        )