ocerebro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OARANHA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,288 @@
+# OCerebro 🧠
+
+**Sistema de Memória para Agentes (Claude Code/MCP)**
+
+OCerebro dá memória persistente e capacidade de aprendizado para o Claude Code. Ele captura automaticamente todo o contexto das sessões, consolida em memória estruturada e permite busca semântica com sqlite-vec.
+
+---
+
+## ✨ Funcionalidades
+
+- 📦 **Memória Automática 3 Camadas**: Raw → Working → Official
+- 🔍 **Busca Híbrida**: Texto (FTS5) + Semântica (sqlite-vec ANN)
+- 🤖 **MCP Server**: 6 ferramentas para Claude Code
+- 🎣 **Hooks Customizáveis**: Extensível via YAML
+- 📊 **RFM Scoring**: Relevância temporal e importância
+- 🛡️ **Guard Rails**: Proteções para não deletar importante
+- 💾 **SQLite Nativo**: Zero dependências externas, zero infra
+
+---
+
+## 🚀 Instalação Rápida
+
+### Pré-requisitos
+
+- Python 3.10+
+- Claude Desktop (opcional, para integração MCP)
+
+### Passo 1: Instalar
+
+```bash
+pip install ocerebro
+```
+
+Ou instale localmente:
+
+```bash
+git clone https://github.com/OARANHA/ocerebro.git
+cd ocerebro
+pip install .
+```
+
+### Passo 2: Setup Automático
+
+```bash
+# Em seu projeto
+ocerebro init
+
+# Configura Claude Desktop automaticamente
+ocerebro setup claude
+```
+
+**Pronto!** Reinicie o Claude Desktop e as ferramentas estarão disponíveis.
+
+---
+
+## 📖 Uso
+
+### No Terminal
+
+```bash
+# Ver status do sistema
+ocerebro status
+
+# Ver memória de um projeto
+ocerebro memory meu-projeto
+
+# Buscar por texto
+ocerebro search "autenticação JWT"
+
+# Criar checkpoint manual
+ocerebro checkpoint meu-projeto --reason "antes de refatorar"
+
+# Promover decisão para official
+ocerebro promote meu-projeto sess_abc123
+```
+
+### No Claude Code (MCP)
+
+Com o MCP Server configurado, você tem acesso a:
+
+| Ferramenta | Descrição |
+|------------|-----------|
+| `cerebro_memory` | Gera MEMORY.md do projeto |
+| `cerebro_search` | Busca memórias por texto/embedding |
+| `cerebro_checkpoint` | Cria checkpoint da sessão atual |
+| `cerebro_promote` | Promove draft para decisão official |
+| `cerebro_status` | Status do sistema |
+| `cerebro_hooks` | Gerencia hooks customizados |
+| `cerebro_diff` | Análise diferencial de memória entre períodos |
+
+---
+
+## 🏗️ Arquitetura
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Claude Code                          │
+│                         ↓                               │
+│                    MCP Server                           │
+└─────────────────────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────┐
+│                      OCerebro                           │
+│                                                         │
+│  Raw (JSONL) → Working (YAML) → Official (Markdown)    │
+│       ↓              ↓              ↓                   │
+│  Eventos →  Extração →  Rascunhos →  Memória          │
+│                  ↓              ↓                       │
+│           sqlite-vec ←  Busca Híbrida                  │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📁 Estrutura do Projeto
+
+No seu projeto, o OCerebro cria:
+
+```
+meu-projeto/
+  .ocerebro/
+    raw/           ← Eventos brutos (JSONL)
+    working/       ← Rascunhos YAML
+    official/      ← Memória permanente (Markdown)
+    index/         ← Banco de dados (metadata + embeddings)
+    config/        ← Configurações
+    MEMORY.md      ← Memória ativa (gerado automaticamente)
+```
+
+---
+
+## 🎣 Hooks Customizados
+
+Crie automações com hooks:
+
+### Exemplo: `hooks.yaml`
+
+```yaml
+hooks:
+  - name: notificar_erro
+    event_type: error
+    module_path: hooks/error_hook.py
+    function: on_error
+    config:
+      notify_severity: ["critical", "high"]
+
+  - name: track_custo_llm
+    event_type: tool_call
+    event_subtype: llm
+    module_path: hooks/cost_hook.py
+    function: on_llm_call
+    config:
+      monthly_budget: 100.0
+```
+
+**Documentação completa:** [docs/HOOKS_GUIDE.md](docs/HOOKS_GUIDE.md)
+
+---
+
+## 🔧 Configuração Manual (MCP)
+
+Se o setup automático não funcionar, edite `claude_desktop.json`:
+
+### Windows
+```
+%APPDATA%\Claude\claude_desktop.json
+```
+
+### macOS
+```
+~/Library/Application Support/Claude/claude_desktop.json
+```
+
+### Linux
+```
+~/.config/Claude/claude_desktop.json
+```
+
+**Conteúdo:**
+
+```json
+{
+  "mcpServers": {
+    "ocerebro": {
+      "command": "python",
+      "args": ["/caminho/para/ocerebro/src/mcp/server.py"],
+      "cwd": "/caminho/para/ocerebro"
+    }
+  }
+}
+```
+
+---
+
+## 🧪 Testes
+
+```bash
+# Instalar dependências de teste
+pip install -e ".[test]"
+
+# Rodar testes
+pytest
+
+# Com coverage
+pytest --cov=src
+```
+
+**Status:** 133 testes passando ✅
+
+---
+
+## 📊 Estatísticas
+
+| Métrica | Valor |
+|---------|-------|
+| Testes | 133 passing |
+| Linhas de código | ~7.700 |
+| Commits | 25+ |
+| Ferramentas MCP | 6 |
+| Tipos de evento | 8+ |
+
+---
+
+## 🤝 Contribuindo
+
+1. Fork o repositório
+2. Crie uma branch (`git checkout -b feature/minha-feature`)
+3. Commit (`git commit -m 'feat: adiciona nova feature'`)
+4. Push (`git push origin feature/minha-feature`)
+5. Abra um Pull Request
+
+---
+
+## 📝 Changelog
+
+### v0.1.0 (2026-04-01)
+
+- ✅ Arquitetura 3 camadas (Raw → Working → Official)
+- ✅ Extractor e Promoter
+- ✅ EmbeddingsDB + QueryEngine (busca híbrida com sqlite-vec)
+- ✅ CLI completa
+- ✅ MCP Server (6 ferramentas)
+- ✅ Hooks customizados via YAML
+- ✅ 133 testes passing
+
+---
+
+## 📚 Documentação
+
+- [Guia de Hooks](docs/HOOKS_GUIDE.md)
+- [Spec de Design](docs/superpowers/specs/2026-03-31-cerebro-design.md)
+- [Plano de Implementação](docs/superpowers/plans/2026-03-31-cerebro-implementacao.md)
+
+---
+
+## 🙋 FAQ
+
+**O OCerebro funciona sem o Claude Desktop?**
+Sim! A CLI funciona independentemente. O MCP Server é opcional.
+
+**Posso sincronizar memória entre computadores?**
+Sim! Use Git para sincronizar `official/` e `config/`.
+
+**O que acontece se deletar `.ocerebro/`?**
+Você perde a memória local. Se tiver `official/` em backup, pode recuperar.
+
+**Funciona em Linux/Mac/Windows?**
+Sim! Testado em todas as plataformas.
+
+---
+
+## 📄 Licença
+
+MIT License - veja [LICENSE](LICENSE) para detalhes.
+
+---
+
+## 🌟 Créditos
+
+Criado por [@OARANHA](https://github.com/OARANHA)
+
+Feito com ❤️ para a comunidade Claude Code.
+
+---
+
+**Stars:** ⭐ 0 | **Forks:** 🍴 0
+
+[Reportar bug](https://github.com/OARANHA/ocerebro/issues) • [Pedir feature](https://github.com/OARANHA/ocerebro/issues)

package/bin/ocerebro.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * OCerebro CLI - Node.js wrapper
+ *
+ * Este script chama a CLI Python do OCerebro.
+ * Usa CommonJS para compatibilidade máxima.
+ */
+
+const { execSync, spawn } = require('child_process');
+const path = require('path');
+
+// Determina o comando Python e valida versão
+function getPythonCmd() {
+    const candidates = [];
+
+    // Tenta python primeiro
+    try {
+        execSync('python --version', { stdio: 'ignore' });
+        candidates.push('python');
+    } catch {
+        // Tenta python3
+        try {
+            execSync('python3 --version', { stdio: 'ignore' });
+            candidates.push('python3');
+        } catch {
+            console.error('Erro: Python não encontrado. Por favor instale Python 3.10+');
+            process.exit(1);
+        }
+    }
+
+    // Valida versão do Python
+    for (const cmd of candidates) {
+        try {
+            const versionOutput = execSync(`${cmd} --version`, {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'pipe']
+            });
+            const match = versionOutput.match(/Python (\d+)\.(\d+)/);
+            if (match) {
+                const major = parseInt(match[1]);
+                const minor = parseInt(match[2]);
+                if (major < 3 || (major === 3 && minor < 10)) {
+                    console.error(`❌ Python ${major}.${minor} detectado.`);
+                    console.error('   OCerebro requer Python 3.10+');
+                    console.error('   Baixe em: https://python.org');
+                    process.exit(1);
+                }
+                return cmd;
+            }
+        } catch (err) {
+            continue;
+        }
+    }
+
+    // Fallback para o primeiro candidato
+    return candidates[0];
+}
+
+// Encontra o caminho do pacote ocerebro
+function getOcerebroPath(pythonCmd) {
+    try {
+        // Tenta encontrar via pip show
+        const output = execSync(`${pythonCmd} -m pip show ocerebro`, { encoding: 'utf-8' });
+        const match = output.match(/Location: (.+)/);
+        if (match) {
+            return path.join(match[1].trim(), 'ocerebro');
+        }
+    } catch {
+        // Se não estiver instalado via pip, usa path relativo
+        return path.join(__dirname, '..');
+    }
+    return path.join(__dirname, '..');
+}
+
+// Argumentos da linha de comando
+const args = process.argv.slice(2);
+
+// Comando principal (chamado UMA única vez)
+const pythonCmd = getPythonCmd();
+const ocerebroPath = getOcerebroPath(pythonCmd);
+const cliScript = path.join(ocerebroPath, 'src', 'cli', 'main.py');
+
+// Executa a CLI Python
+const pythonArgs = [cliScript, ...args];
+
+const proc = spawn(pythonCmd, pythonArgs, {
+    stdio: 'inherit',
+    cwd: process.cwd()
+});
+
+proc.on('close', (code) => {
+    process.exit(code);
+});
+
+proc.on('error', (err) => {
+    console.error('Erro ao executar OCerebro:', err.message);
+    process.exit(1);
+});

package/cerebro/__init__.py

@@ -0,0 +1,7 @@
+"""Cerebro - Sistema de Memória para Agentes de Código
+
+Módulo principal do package cerebro-memory.
+"""
+
+__version__ = "0.1.0"
+__author__ = "OARANHA"

package/cerebro/__main__.py

@@ -0,0 +1,19 @@
+"""Permite executar como: python -m cerebro setup
+
+Comandos:
+    python -m cerebro setup          - Setup completo
+    python -m cerebro setup claude   - Configura Claude Desktop
+    python -m cerebro setup init     - Cria .ocerebro/ e hooks.yaml
+"""
+
+import sys
+from pathlib import Path
+
+# Adiciona parent ao path para imports
+parent_path = Path(__file__).parent.parent
+sys.path.insert(0, str(parent_path))
+
+from cerebro.cerebro_setup import main
+
+if __name__ == "__main__":
+    main()