ocerebro 0.1.0

package/cerebro/cerebro_setup.py

@@ -0,0 +1,459 @@
+"""Setup Automático do OCerebro
+
+Detecta e configura o Claude Desktop e Claude Code automaticamente.
+"""
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+def find_all_claude_configs() -> dict:
+    """Encontra todas as configurações do Claude (Desktop e Code).
+
+    Returns:
+        dict com chaves "desktop" e "code", cada uma contendo Path | None
+    """
+    result = {"desktop": None, "code": None}
+
+    # Claude Desktop: claude_desktop.json
+    desktop_locations = []
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA", "")
+        desktop_locations.extend([
+            Path(appdata) / "Claude" / "claude_desktop.json",
+            Path.home() / "AppData" / "Roaming" / "Claude" / "claude_desktop.json",
+            Path.home() / ".claude" / "claude_desktop.json",
+        ])
+    elif sys.platform == "darwin":
+        desktop_locations.extend([
+            Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop.json",
+            Path.home() / ".claude" / "claude_desktop.json",
+        ])
+    elif sys.platform == "linux":
+        xdg_config = os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config"))
+        desktop_locations.extend([
+            Path(xdg_config) / "Claude" / "claude_desktop.json",
+            Path.home() / ".claude" / "claude_desktop.json",
+        ])
+
+    # Claude Code: settings.json
+    code_locations = []
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA", "")
+        code_locations.extend([
+            Path(appdata) / "Claude" / "settings.json",
+            Path.home() / "AppData" / "Roaming" / "Claude" / "settings.json",
+        ])
+    elif sys.platform == "darwin":
+        code_locations.extend([
+            Path.home() / "Library" / "Application Support" / "Claude" / "settings.json",
+        ])
+    elif sys.platform == "linux":
+        xdg_config = os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config"))
+        code_locations.extend([
+            Path(xdg_config) / "Claude" / "settings.json",
+        ])
+
+    # Universal (funciona para ambos)
+    universal_claude = Path.home() / ".claude"
+    if universal_claude.exists():
+        if result["desktop"] is None and (universal_claude / "claude_desktop.json").exists():
+            result["desktop"] = universal_claude / "claude_desktop.json"
+        if result["code"] is None and (universal_claude / "settings.json").exists():
+            result["code"] = universal_claude / "settings.json"
+
+    # Encontra primeiro desktop que existe
+    if result["desktop"] is None:
+        for loc in desktop_locations:
+            if loc.exists():
+                result["desktop"] = loc
+                break
+        else:
+            # Nenhum existe, retorna o primeiro para criar
+            result["desktop"] = desktop_locations[0] if desktop_locations else None
+
+    # Encontra primeiro code que existe
+    if result["code"] is None:
+        for loc in code_locations:
+            if loc.exists():
+                result["code"] = loc
+                break
+        else:
+            # Nenhum existe, retorna o primeiro para criar
+            result["code"] = code_locations[0] if code_locations else None
+
+    return result
+
+
+def find_claude_desktop_config() -> Path | None:
+    """Encontra o arquivo claude_desktop.json em várias localizações.
+
+    Legado: use find_all_claude_configs() para suporte completo.
+    """
+    configs = find_all_claude_configs()
+    return configs.get("desktop")
+
+
+def get_ocerebro_path() -> Path:
+    """Retorna o caminho absoluto do OCerebro instalado"""
+    # Tenta encontrar o package instalado
+    import ocerebro
+    ocerebro_path = Path(ocerebro.__file__).parent
+    return ocerebro_path.resolve()
+
+
+def generate_mcp_config(ocerebro_path: Path) -> dict:
+    """Gera configuração MCP para o OCerebro com suporte robusto a paths.
+
+    SECURITY: Não salva API keys no config file.
+    As variáveis de ambiente são herdadas do sistema.
+    Configure no seu shell: ~/.bashrc ou ~/.zshrc
+    """
+
+    # Determina o comando Python
+    python_cmd = sys.executable
+
+    # Estratégia 1: usa python -m ocerebro.mcp (robusto para pip install)
+    mcp_config = {
+        "command": python_cmd,
+        "args": ["-m", "src.mcp.server"],
+        "cwd": str(ocerebro_path.parent),
+    }
+
+    # Estratégia 2: path direto se arquivo existe
+    mcp_server = ocerebro_path / "src" / "mcp" / "server.py"
+    if not mcp_server.exists():
+        mcp_server = ocerebro_path.parent / "src" / "mcp" / "server.py"
+
+    if mcp_server.exists():
+        mcp_config["args"] = [str(mcp_server)]
+
+    # SECURITY: NÃO salvar API keys no config
+    # As variáveis de ambiente são herdadas automaticamente do shell
+    mcp_config["env"] = {}
+
+    return {
+        "mcpServers": {
+            "ocerebro": mcp_config
+        }
+    }
+
+
+def backup_config(config_path: Path) -> Path | None:
+    """Cria backup do arquivo de configuração"""
+    if not config_path.exists():
+        return None
+
+    backup_path = config_path.with_suffix(".json.bak")
+    backup_path.write_text(config_path.read_text(encoding="utf-8"), encoding="utf-8")
+    print(f"[OK] Backup criado: {backup_path}")
+    return backup_path
+
+
+def merge_configs(existing: dict, new: dict) -> dict:
+    """Faz merge das configurações MCP"""
+    result = existing.copy()
+
+    if "mcpServers" not in result:
+        result["mcpServers"] = {}
+
+    # Adiciona/Atualiza servidor ocerebro
+    if "mcpServers" in new:
+        for name, config in new["mcpServers"].items():
+            result["mcpServers"][name] = config
+
+    return result
+
+
+def setup_slash_commands(project_path: Path) -> bool:
+    """Cria slash commands /cerebro no .claude/commands/ do projeto."""
+
+    commands_dir = project_path / ".claude" / "commands"
+    commands_dir.mkdir(parents=True, exist_ok=True)
+
+    # cerebro-dream.md
+    dream_cmd = commands_dir / "cerebro-dream.md"
+    if not dream_cmd.exists():
+        dream_cmd.write_text("""---
+description: Extrair memórias da sessão atual
+---
+Execute: ocerebro dream --since 7 --apply
+Mostre o relatório completo do que foi salvo.
+""", encoding="utf-8")
+        print(f"[OK] Slash command criado: {dream_cmd}")
+
+    # cerebro-status.md
+    status_cmd = commands_dir / "cerebro-status.md"
+    if not status_cmd.exists():
+        status_cmd.write_text("""---
+description: Ver status da memória do projeto
+---
+Execute: ocerebro status
+Liste quantas memórias existem por tipo.
+""", encoding="utf-8")
+        print(f"[OK] Slash command criado: {status_cmd}")
+
+    # cerebro-gc.md
+    gc_cmd = commands_dir / "cerebro-gc.md"
+    if not gc_cmd.exists():
+        gc_cmd.write_text("""---
+description: Limpeza de memórias antigas
+---
+Execute: ocerebro gc --threshold 30
+Mostre o que será arquivado antes de confirmar.
+""", encoding="utf-8")
+        print(f"[OK] Slash command criado: {gc_cmd}")
+
+    return True
+
+
+def setup_claude_desktop() -> bool:
+    """Configura o Claude Desktop ou Claude Code automaticamente."""
+
+    print("=" * 60)
+    print("OCerebro - Setup Automático")
+    print("=" * 60)
+    print()
+
+    # Encontra todas as configurações
+    configs = find_all_claude_configs()
+
+    # Pergunta qual versão o usuário usa
+    print("Qual versão do Claude você usa?")
+    print("  1. Claude Desktop")
+    print("  2. Claude Code (claude.ai/code)")
+    print("  3. Ambos")
+    choice = input("\nEscolha [1/2/3] (padrão: 2): ").strip() or "2"
+
+    # Pega caminho do OCerebro
+    ocerebro_path = get_ocerebro_path()
+    print(f"\nOCerebro instalado: {ocerebro_path}")
+
+    # Gera nova configuração
+    new_config = generate_mcp_config(ocerebro_path)
+
+    configured = []
+
+    # Configura Claude Desktop se escolhido
+    if choice in ["1", "3"]:
+        config_path = configs.get("desktop")
+        if config_path:
+            print(f"\nConfig do Claude Desktop: {config_path}")
+            config_path.parent.mkdir(parents=True, exist_ok=True)
+
+            existing_config = {}
+            if config_path.exists():
+                print(f"Configuração existente encontrada")
+                backup_config(config_path)
+                try:
+                    existing_config = json.loads(config_path.read_text(encoding="utf-8"))
+                except json.JSONDecodeError as e:
+                    print(f"Erro ao ler configuração existente: {e}")
+                    existing_config = {}
+
+            merged_config = merge_configs(existing_config, new_config)
+            config_path.write_text(
+                json.dumps(merged_config, indent=2, ensure_ascii=False),
+                encoding="utf-8"
+            )
+            configured.append("Claude Desktop")
+
+    # Configura Claude Code se escolhido
+    if choice in ["2", "3"]:
+        config_path = configs.get("code")
+        if config_path:
+            print(f"\nConfig do Claude Code: {config_path}")
+            config_path.parent.mkdir(parents=True, exist_ok=True)
+
+            existing_config = {}
+            if config_path.exists():
+                print(f"Configuração existente encontrada")
+                backup_config(config_path)
+                try:
+                    existing_config = json.loads(config_path.read_text(encoding="utf-8"))
+                except json.JSONDecodeError as e:
+                    print(f"Erro ao ler configuração existente: {e}")
+                    existing_config = {}
+
+            merged_config = merge_configs(existing_config, new_config)
+            config_path.write_text(
+                json.dumps(merged_config, indent=2, ensure_ascii=False),
+                encoding="utf-8"
+            )
+            configured.append("Claude Code")
+
+    print()
+    print("[OK] OCerebro configurado em:", ", ".join(configured) if configured else "Nenhum")
+    print()
+    print("⚠️  API keys NÃO foram salvas no config.")
+    print("   Configure no seu shell:")
+    print("   export ANTHROPIC_AUTH_TOKEN=sua-key")
+    print()
+    print("Próximos passos:")
+    print("  1. Reinicie o Claude (Desktop ou Code)")
+    print("  2. As ferramentas do OCerebro estarão disponíveis:")
+    print("     - ocerebro_memory")
+    print("     - ocerebro_search")
+    print("     - ocerebro_checkpoint")
+    print("     - ocerebro_promote")
+    print("     - ocerebro_status")
+    print("     - ocerebro_hooks")
+    print("     - ocerebro_diff")
+    print("     - ocerebro_dream")
+    print("     - ocerebro_remember")
+    print("     - ocerebro_gc")
+    print()
+    print("=" * 60)
+
+    return True
+
+
+def setup_hooks(project_path: Path | None = None) -> bool:
+    """Cria arquivo de exemplo hooks.yaml no projeto"""
+
+    if project_path is None:
+        project_path = Path.cwd()
+
+    hooks_yaml = project_path / "hooks.yaml"
+
+    if hooks_yaml.exists():
+        print(f" hooks.yaml já existe em {project_path}")
+        return False
+
+    example_config = """# OCerebro Hooks Configuration
+# Docs: https://github.com/OARANHA/ocerebro/blob/main/docs/HOOKS_GUIDE.md
+
+hooks:
+  # Exemplo: Notificação de erros críticos
+  - name: error_notification
+    event_type: error
+    module_path: hooks/error_hook.py
+    function: on_error
+    config:
+      notify_severity: ["critical", "high"]
+
+  # Exemplo: Tracker de custo LLM
+  - name: llm_cost_tracker
+    event_type: tool_call
+    event_subtype: llm
+    module_path: hooks/cost_hook.py
+    function: on_llm_call
+    config:
+      monthly_budget: 100.0
+      alert_at_percentage: 80
+"""
+
+    hooks_yaml.write_text(example_config, encoding="utf-8")
+
+    # Cria diretório hooks/ com __init__.py
+    hooks_dir = project_path / "hooks"
+    hooks_dir.mkdir(exist_ok=True)
+    (hooks_dir / "__init__.py").write_text('"""Hooks customizados do projeto"""', encoding="utf-8")
+
+    print(f"[OK] hooks.yaml criado em {project_path}")
+    print(f"[OK] Diretório hooks/ criado")
+
+    return True
+
+
+def setup_ocerebro_dir(project_path: Path | None = None) -> bool:
+    """Cria diretório .ocerebro no projeto.
+
+    SECURITY: Valida path traversal - só permite paths dentro de home ou cwd.
+    """
+
+    if project_path is None:
+        project_path = Path.cwd()
+
+    # Validação de segurança: path deve ser dentro de home ou cwd
+    project_path = project_path.resolve()
+    home = Path.home().resolve()
+    cwd = Path.cwd().resolve()
+
+    if not (str(project_path).startswith(str(home)) or
+            str(project_path).startswith(str(cwd))):
+        print(f"❌ Erro: path '{project_path}' fora do diretório permitido.")
+        print(f"   Permitido: dentro de {home} ou {cwd}")
+        return False
+
+    ocerebro_dir = project_path / ".ocerebro"
+
+    if ocerebro_dir.exists():
+        print(f"[OK] Diretório .ocerebro já existe")
+        return True
+
+    # Cria estrutura
+    (ocerebro_dir / "raw").mkdir(parents=True)
+    (ocerebro_dir / "working").mkdir(parents=True)
+    (ocerebro_dir / "official").mkdir(parents=True)
+    (ocerebro_dir / "index").mkdir(parents=True)
+    (ocerebro_dir / "config").mkdir(parents=True)
+
+    # Cria .gitignore dentro do .ocerebro
+    gitignore = ocerebro_dir / ".gitignore"
+    gitignore.write_text("""# Raw events (muito grandes)
+raw/
+
+# Working drafts (opcional sincronizar)
+working/
+
+# Index databases (regenerado automaticamente)
+index/
+
+# Config local
+config/local.yaml
+""", encoding="utf-8")
+
+    print(f"[OK] Diretório .ocerebro criado em {project_path}")
+    print(f"   - raw/ (eventos brutos)")
+    print(f"   - working/ (rascunhos)")
+    print(f"   - official/ (memória permanente)")
+    print(f"   - index/ (banco de dados)")
+    print(f"   - config/ (configurações)")
+
+    return True
+
+
+def main():
+    """Função principal de setup"""
+
+    if len(sys.argv) > 1:
+        subcommand = sys.argv[1]
+
+        if subcommand == "claude":
+            success = setup_claude_desktop()
+            sys.exit(0 if success else 1)
+
+        elif subcommand == "hooks":
+            project = Path(sys.argv[2]) if len(sys.argv) > 2 else None
+            success = setup_hooks(project)
+            sys.exit(0 if success else 1)
+
+        elif subcommand == "init":
+            project = Path(sys.argv[2]) if len(sys.argv) > 2 else Path.cwd()
+            setup_ocerebro_dir(project)
+            setup_hooks(project)
+            setup_slash_commands(project)
+            print()
+            print("Setup completo! Agora execute:")
+            print("  ocerebro setup claude")
+            sys.exit(0)
+
+        else:
+            print(f"Subcomando desconhecido: {subcommand}")
+            sys.exit(1)
+
+    # Setup completo padrão
+    print("Executando setup completo...")
+    print()
+
+    setup_ocerebro_dir()
+    setup_hooks()
+    setup_claude_desktop()
+
+
+if __name__ == "__main__":
+    main()

package/hooks/__init__.py

@@ -0,0 +1 @@
+"""Hooks customizados do Cerebro - Exemplos de implementação"""

package/hooks/cost_hook.py

@@ -0,0 +1,45 @@
+"""Hook para tracker de custo de LLM"""
+
+from src.core.event_schema import Event
+
+
+def on_llm_call(event: Event, context: dict, config: dict) -> dict:
+    """
+    Trackea custo de chamadas LLM.
+
+    Args:
+        event: Evento de tool_call LLM
+        context: Contexto global
+        config: Configuração do hook
+
+    Returns:
+        Informações de custo
+    """
+    log_cost = config.get("log_cost", True)
+    monthly_budget = config.get("monthly_budget", 100.0)
+    alert_percentage = config.get("alert_at_percentage", 80)
+
+    payload = event.payload
+    model = payload.get("model", "unknown")
+    tokens = payload.get("tokens", {"input": 0, "output": 0})
+    cost = payload.get("cost", 0.0)
+
+    # Atualiza custo acumulado no contexto
+    accumulated = context.get("llm_cost_accumulated", 0.0)
+    context["llm_cost_accumulated"] = accumulated + cost
+
+    result = {
+        "model": model,
+        "tokens": tokens,
+        "current_cost": cost,
+        "accumulated_cost": accumulated + cost,
+        "budget": monthly_budget,
+        "budget_remaining": monthly_budget - (accumulated + cost),
+        "budget_used_percentage": ((accumulated + cost) / monthly_budget) * 100
+    }
+
+    # Alerta se aproximando do limite
+    if result["budget_used_percentage"] >= alert_percentage:
+        result["alert"] = f"Usou {result['budget_used_percentage']:.1f}% do budget mensal"
+
+    return result

package/hooks/coverage_hook.py

@@ -0,0 +1,39 @@
+"""Hook para verificar cobertura de testes"""
+
+from src.core.event_schema import Event
+
+
+def on_test_result(event: Event, context: dict, config: dict) -> dict:
+    """
+    Verifica cobertura de testes após execução.
+
+    Args:
+        event: Evento de resultado de teste
+        context: Contexto global
+        config: Configuração do hook
+
+    Returns:
+        Resultado da verificação
+    """
+    min_coverage = config.get("min_coverage", 80)
+    fail_below = config.get("fail_below_threshold", False)
+
+    payload = event.payload
+    coverage = payload.get("coverage", 0)
+
+    result = {
+        "min_coverage": min_coverage,
+        "actual_coverage": coverage,
+        "passed": coverage >= min_coverage
+    }
+
+    if coverage < min_coverage:
+        msg = f"Cobertura {coverage}% abaixo do mínimo {min_coverage}%"
+        if fail_below:
+            result["action"] = "fail_build"
+            result["message"] = msg
+        else:
+            result["action"] = "warn"
+            result["message"] = msg
+
+    return result

package/hooks/error_hook.py

@@ -0,0 +1,48 @@
+"""Hook para notificação de erros"""
+
+from src.core.event_schema import Event
+
+
+def on_error(event: Event, context: dict, config: dict) -> dict:
+    """
+    Notifica erros críticos.
+
+    Args:
+        event: Evento de erro
+        context: Contexto global
+        config: Configuração do hook
+
+    Returns:
+        Resultado da notificação
+    """
+    notify_severity = config.get("notify_severity", ["critical", "high"])
+    channel = config.get("channel", "slack")
+    include_stacktrace = config.get("include_stacktrace", True)
+
+    payload = event.payload
+    severity = payload.get("severity", "medium")
+    error_type = payload.get("error_type", "Unknown")
+    message = payload.get("message", "")
+
+    result = {
+        "severity": severity,
+        "error_type": error_type,
+        "message": message,
+        "should_notify": severity in notify_severity
+    }
+
+    if result["should_notify"]:
+        notification = {
+            "channel": channel,
+            "title": f"Erro {severity.upper()}: {error_type}",
+            "text": message
+        }
+
+        if include_stacktrace and payload.get("stacktrace"):
+            notification["stacktrace"] = payload["stacktrace"]
+
+        result["notification"] = notification
+        # Aqui integraria com Slack/Teams/etc
+        # send_to_slack(notification)
+
+    return result

package/hooks/expensive_hook.py

@@ -0,0 +1,41 @@
+"""Hook para log de operações custosas"""
+
+import time
+from src.core.event_schema import Event
+
+
+def on_expensive_operation(event: Event, context: dict, config: dict) -> dict:
+    """
+    Log de operações custosas.
+
+    Args:
+        event: Evento de tool_call bash
+        context: Contexto global
+        config: Configuração do hook
+
+    Returns:
+        Informações da operação
+    """
+    log_threshold = config.get("log_threshold_seconds", 5)
+    alert_threshold = config.get("alert_threshold_seconds", 30)
+
+    payload = event.payload
+    command = payload.get("command", "unknown")
+    duration = payload.get("duration", 0)
+
+    result = {
+        "command": command,
+        "duration": duration,
+        "logged": False,
+        "alerted": False
+    }
+
+    if duration >= log_threshold:
+        result["logged"] = True
+        result["log_message"] = f"Operação lenta: {command} ({duration:.2f}s)"
+
+        if duration >= alert_threshold:
+            result["alerted"] = True
+            result["alert_message"] = f"ALERT: {command} levou {duration:.2f}s"
+
+    return result

package/hooks/global_logger.py

@@ -0,0 +1,32 @@
+"""Hook para log global de eventos"""
+
+from src.core.event_schema import Event
+
+
+def on_any_event(event: Event, context: dict, config: dict) -> dict:
+    """
+    Log genérico para todos os eventos.
+
+    Args:
+        event: Qualquer evento
+        context: Contexto global
+        config: Configuração do hook
+
+    Returns:
+        Informações do log
+    """
+    log_level = config.get("log_level", "info")
+    exclude_subtypes = config.get("exclude_subtypes", [])
+
+    # Pula subtipos excluídos
+    if event.subtype in exclude_subtypes:
+        return {"skipped": True, "reason": f"subtype {event.subtype} excluído"}
+
+    return {
+        "logged": True,
+        "log_level": log_level,
+        "event_type": event.event_type.value,
+        "subtype": event.subtype,
+        "project": event.project,
+        "session_id": event.session_id
+    }