roampal-core

O ciclo principal é idêntico — ambas as plataformas injetam contexto, capturam trocas e avaliam resultados. O mecanismo de entrega difere:

O Claude Code solicita que o LLM principal avalie cada troca por meio da ferramenta score_memories. O OpenCode nunca se autoavalia — um sidecar independente (uma chamada de API separada) revisa cada troca como terceiro, eliminando o viés de autoavaliação. A ferramenta score_memories não é registrada no OpenCode. A avaliação é desabilitada por padrão até que você a configure explicitamente via roampal sidecar setup. Durante a configuração, o Roampal detecta modelos locais (Ollama, LM Studio, etc.) e permite que você escolha um modelo de avaliação. Os modelos gratuitos Zen estão disponíveis como uma opção explícita de adesão para usuários sem modelo local ou chave de API — eles roteiam pelo proxy do OpenCode, que pode registrar dados. Um modelo barato ou local funciona muito bem — a avaliação não precisa de um modelo poderoso.

v0.6.0: Ciclo de vida do servidor + vinculação de perfil por diretório + rede de segurança de deduplicação. O monolito de 4.700 linhas roampal/cli.py agora é um pacote roampal/cli/ dividido em módulos por domínio, protegido por snapshots de saída dourada, invariantes de tabela de despacho e uma suíte de equivalência byte-idêntica. Mudanças visíveis ao usuário por cima: roteamento de perfil por solicitação (hooks/MCP/plugin sempre nomeiam seu perfil; um nome não registrado agora falha explicitamente com um 404 "Crie primeiro" em vez de gravar silenciosamente no armazenamento padrão); roampal profile switch não mata mais o servidor em execução (cada sessão capta o novo perfil na próxima troca); servidores gerados rodam com isolamento -E [-P] e um cwd neutro (um projeto contendo um diretório roampal/ local não pode mais ocultar a instalação — e instalações no site do usuário, por exemplo, Python da Microsoft Store, funcionam novamente — um rascunho anterior desse endurecimento de spawn usava o sinalizador isolado -I, que também oculta o diretório de pacotes do site do usuário); status relata uma porta pendurada como parada, não como erro; servidores compartilhados se aposentam após 30 minutos ociosos (um roampal start em primeiro plano é isento); e roampal start --profile X sobrevive ao respawn ocioso por meio de um pino de lançamento persistido. Novos roampal profile bind <name> / unbind fixam um diretório (e seus subdiretórios) a um perfil — "este projeto sempre usa o perfil X" é um comando em vez de editar manualmente o JSON de env. Um teste de guarda de regressão de deduplicação (3 fatos distintos pelo caminho real store_memory_bank, mais vetores de modelo real gravados e um controle negativo que recria o regime quebrado v0.5.9 de ambas as maneiras) faz qualquer troca futura de embedder ou mudança de constante de distância falhar na suíte no primeiro toque, em vez de colapsar silenciosamente as gravações. Correção de privacidade (OpenCode): desde v0.3.7, o plugin do OpenCode enviava o texto da troca para Zen (opencode.ai) sempre que nenhum modelo de avaliação era escolhido — inclusive após "Skip" e roampal sidecar disable — quebrando a regra v0.5.3 de "nada sai da sua máquina sem uma escolha explícita", que só havia sido aplicada no lado do servidor. A v0.6.0 a aplica no plugin: Zen apenas após adesão explícita, e nenhuma chamada de avaliação até que um modelo seja escolhido. Se você usa OpenCode e nunca escolheu um modelo de avaliação, a avaliação agora está desligada até você executar roampal sidecar setup (ou --list para escolher sem o menu). Sem mudança de RAM — a pegada v0.5.9 e o estado do modelo são mantidos inalterados.

v0.5.9: Correção de pegada de memória + atualização de embedder/reranker + observabilidade de falhas — acionada por uma falha MemoryError rastreada até o arena de memória da CPU do ONNX Runtime que nunca libera buffers de rascunho por forma, agravada por arquivos de modelo FP16 que são convertidos para FP32 no carregamento. Desabilita o arena e o cache de padrão de memória em ambos os modelos, muda o embedder para sua própria exportação INT8 medida (mesmo modelo mpnet — a atualização planejada para e5-base foi adiada para v0.6.0 depois que um portão de precisão detectou uma regressão de guarda de quase-duplicatas) e o cross-encoder para sua própria exportação INT8, e compartilha uma sessão de cross-encoder entre todos os perfis em vez de uma por perfil. A pegada de processo medida cai de ~2.355MB para ~484MB em isolamento (~5x), e a busca fica mais rápida nos caminhos de embed e rerank, em vez de trocar memória por latência. Uma re-embed em segundo plano, por coleção, migra vetores existentes para o novo embedder automaticamente no primeiro início — nunca bloqueando o cliente MCP, nunca misturando famílias de modelos dentro de uma coleção. Também adiciona registro em arquivo, tratamento de MemoryError/ExceptionGroup, um heartbeat RSS e um endpoint /api/status para que o próximo incidente como este deixe um rastro, e estados degradados (embedder inativo, reranker inativo, migração em andamento) sejam exibidos ao usuário em vez de retornar silenciosamente um resultado vazio.

v0.5.8: Versão de resiliência a falhas — habilita WAL do SQLite + durabilidade FULL no catálogo ChromaDB para que terminações forçadas (conflitos de porta no Windows, mortes de processos externos, queda de energia) não corrompam ou esvaziem mais o banco de dados. Reescreve SessionManager.mark_scored() para realizar uma substituição atômica de arquivo temporário, garantindo que a transcrição JSONL sobreviva a uma falha no meio da gravação. Também inclui 16 novos testes automatizados cobrindo ambas as correções, corrige dívida de teste pré-existente que deixava a suíte completa vermelha no Windows e adiciona ferramentas de desenvolvimento (pytest-timeout, pytest-forked, build, twine). Nenhuma migração de dados é necessária; o WAL é aplicado no próximo início do servidor.

v0.5.7: Coleta de lixo na inicialização para o _completion_state.json do hook MCP. O arquivo acumulava uma entrada por conversation_id já visto sem limpeza, gerando amplificação de I/O em cada gravação e deixando sinalizadores scored_this_turn=True presos que podiam envenenar o fallback de avaliação entre sessões. A nova passagem _cleanup_completion_state descarta entradas com mais de 30 dias ou sem transcrição correspondente, impõe um teto rígido de 500 entradas e grava atomicamente. O TTL da transcrição JSONL foi aumentado de 7 → 30 dias para permanecer em sincronia com o TTL do arquivo de estado. Acompanha o Roampal Desktop v0.3.3.

v0.5.6: Versão de endurecimento — fecha lacunas de cobertura restantes da auditoria de verificação v0.5.5.x. Varredura fantasma após limpeza arquivada, limpeza automática sob pressão de capacidade, observabilidade de deduplicação, permissões de exclusão endurecidas, testes de ciclo arquivar-depois-adicionar, alinhamento do prompt do sidecar com o benchmark, fila de avaliação assíncrona (repetição adiada por sessão), reescrita de qualidade da definição de ferramenta MCP (TDQS), autodetecção do OpenCode Go no assistente de configuração do sidecar e correção da extração do nome do usuário.

v0.5.5.2: Hotfix — a instalação do plugin no Windows agora verifica se a cópia foi bem-sucedida (verificação de tamanho pós-cópia + fallback manual de leitura/gravação para interferência do OneDrive/antivírus). Também instala em %APPDATA%\opencode\plugins como fallback, já que alguns aplicativos Electron resolvem caminhos de configuração de forma diferente no Windows. Corrige casos restantes do problema #11, onde roampal init --force relatava sucesso, mas o plugin estava vazio ou no diretório errado.

v0.5.5.1: Hotfix — o OpenCode Desktop agora alterna corretamente os perfis quando você troca de projeto na interface (problema #10). O plugin lê o directory da sessão ativa via client.session.get() em vez de armazenar em cache o perfil no carregamento do módulo, para que um plugin singleton em um espaço de trabalho multiprojeto ainda atinja o perfil certo por mensagem. Também: roampal init --force agora realmente sobrescreve o arquivo do plugin do OpenCode (problema #11), com erros mais claros quando o Desktop segura um bloqueio de arquivo.

v0.5.5: Exclusão suave para memory_bank — a exclusão rígida do ChromaDB não remove realmente os vetores do HNSW, causando correspondências fantasma de deduplicação que bloqueiam novas memórias após exclusão pela interface. Substituída por atualização de metadados status=archived mais filtro de status em todos os caminhos de consulta/deduplicação. Também: mutex de avaliação → fila assíncrona (elimina solicitações descartadas), correção de contaminação de resumo do sidecar (cercamento de delimitador).

v0.5.4: A vinculação de perfil agora é por solicitação, não por processo. Cada cliente (servidor MCP, plugin do OpenCode, hooks Python para Claude Code / Cursor) envia um cabeçalho X-Roampal-Profile para que um único servidor FastAPI possa atender vários perfis simultaneamente. Corrige o problema #7, onde o ROAMPAL_PROFILE por projeto do OpenCode Desktop em opencode.json era ignorado porque o FastAPI singleton vinculava o perfil uma vez na inicialização.

v0.5.3: A avaliação por sidecar agora exige configuração explícita (sem fallback automático para Zen ou localhost). Modelos locais pequenos (qwen2.5:3b, etc.) que retornam arrays JSON simples em vez de respostas no formato OpenAI são tratados de forma transparente via tolerância de forma no lado do servidor.

┌─────────────────────────────────────────────────────────┐
│  pip install roampal && roampal init                    │
│    Claude Code: hooks + MCP → ~/.claude/                │
│    OpenCode:    plugin + MCP → ~/.config/opencode/      │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  HTTP Hook Server (port 27182)                          │
│    Auto-started on first use, self-heals on failure     │
│    Manual control: roampal start / roampal stop         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  User types message                                     │
│    → Hook/plugin calls HTTP server for context          │
│    → AI sees relevant memories, responds                │
│    → Exchange stored, scored (hooks or sidecar)         │
└─────────────────────────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────┐
│  Single-Writer Backend                                  │
│    FastAPI → UnifiedMemorySystem → ChromaDB             │
│    All clients share one server, isolated by session    │
└─────────────────────────────────────────────────────────┘

Veja dev/docs/ para detalhes técnicos completos.

• Reinicie o Claude Code (hooks carregam na inicialização)
• Verifique o servidor HTTP: curl http://127.0.0.1:27182/api/health

• Verifique se ~/.claude.json tem a entrada MCP roampal-core com o caminho correto do Python
• Verifique o painel de saída do Claude Code para erros de MCP

• Certifique-se de ter executado roampal init --opencode
• Verifique se o servidor iniciou automaticamente: curl http://127.0.0.1:27182/api/health
• Se não, inicie manualmente: roampal start

Isso é esperado. O Roampal tem autocura — se o servidor HTTP parar de responder, ele é reiniciado e tentado novamente automaticamente.