@pcircle/memesh 4.0.2 → 4.1.0

package/README.pt.md

@@ -1,10 +1,13 @@
+<!-- translated from README.md @ ab9d25f8d9cb7c78c4cc271717709e2efb4bac76 -->
+<!-- DO NOT edit this file by hand. The maintainer regenerates it from README.md via a private toolkit script (see internal docs). Manual edits will be overwritten on next sync. -->
+
 🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
 
 <p align="center">
   <h1 align="center">MeMesh LLM Memory</h1>
   <p align="center">
-    <strong>A camada de memória de IA universal mais leve.</strong><br />
-    Um único arquivo SQLite. Qualquer LLM. Zero nuvem.
+    <strong>Memória local para Claude Code e agentes de codificação MCP.</strong><br />
+    Um arquivo SQLite. Sem Docker. Sem dependência de nuvem.
   </p>
   <p align="center">
     <a href="https://www.npmjs.com/package/@pcircle/memesh"><img src="https://img.shields.io/npm/v/@pcircle/memesh?style=flat-square&color=3b82f6&label=npm" alt="npm" /></a>
@@ -18,9 +21,11 @@
 
 ## O Problema
 
-Seu AI esquece tudo entre sessões. Cada decisão, cada correção de bug, cada lição aprendida — tudo some. Você explica o mesmo contexto de novo e de novo, o Claude redescobre os mesmos padrões, e o conhecimento de IA da sua equipe volta ao zero toda vez.
+Seu agente de código esquece tudo entre sessões. Toda decisão arquitetônica, correção de bug, teste que falhou e lição conquistada na marra precisa ser re-explicada. Claude Code sempre começa do zero, redescobre restrições antigas e queima contexto em coisas que já deveria saber.
+
+**MeMesh oferece memória local persistente, pesquisável e evolutiva para agentes de código.**
 
-**O MeMesh dá a cada AI uma memória persistente, pesquisável e em constante evolução.**
+Este pacote é a camada de memória local da família de produtos MeMesh. É propositalmente pequeno e open-source: instale via npm, mantenha sua memória em `~/.memesh/knowledge-graph.db` e conecte ao Claude Code ou qualquer cliente compatível com MCP. Produtos de workspace hospedado e sistemas operacionais corporativos devem se manter separados do roadmap e README deste pacote.
 
 ---
 
@@ -32,22 +37,28 @@ Seu AI esquece tudo entre sessões. Cada decisão, cada correção de bug, cada
 npm install -g @pcircle/memesh
 ```
 
-### Passo 2: Seu AI lembra
+### Passo 2: Armazene uma decisão
 
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
 
-### Passo 3: Seu AI recupera
+### Passo 3: Recupere depois
 
 ```bash
 memesh recall "login security"
-# → Encontra "OAuth 2.0 with PKCE" mesmo com palavras diferentes
+# → Encontra "OAuth 2.0 with PKCE" mesmo com palavras de busca diferentes
 ```
 
-**Pronto.** O MeMesh já está lembrando e recuperando memórias entre sessões.
+**É só isso.** MeMesh já está lembrando e recuperando entre sessões.
 
-Abra o painel para explorar sua memória:
+Se quiser verificar a instalação e toda a configuração local de ponta a ponta:
+
+```bash
+memesh doctor
+```
+
+Abra o dashboard para explorar sua memória:
 
 ```bash
 memesh
@@ -58,27 +69,27 @@ memesh
 </p>
 
 <p align="center">
-  <img src="docs/images/dashboard-analytics.png" alt="MeMesh Analytics — entenda o conhecimento do seu AI" width="100%" />
+  <img src="docs/images/dashboard-analytics.png" alt="MeMesh Analytics — score de saúde, timeline, padrões, cobertura de conhecimento" width="100%" />
 </p>
 
 <p align="center">
-  <img src="docs/images/dashboard-graph.png" alt="MeMesh Graph — grafo de conhecimento interativo com filtros de tipo e modo ego" width="100%" />
+  <img src="docs/images/dashboard-graph.png" alt="MeMesh Graph — grafo de conhecimento interativo com filtros por tipo e modo ego" width="100%" />
 </p>
 
 ---
 
-## Para Quem É Isso?
+## Para Quem é Isso?
 
-| Se você é... | O MeMesh ajuda você a... |
+| Se você é... | MeMesh te ajuda a... |
 |---------------|---------------------|
-| **Desenvolvedor usando Claude Code** | Lembrar decisões, padrões e lições entre sessões automaticamente |
-| **Equipe construindo com LLMs** | Compartilhar conhecimento da equipe via exportação/importação, mantendo o contexto de todos alinhado |
-| **Desenvolvedor de agentes de IA** | Dar aos seus agentes memória persistente via MCP, HTTP API ou Python SDK |
-| **Usuário avançado com múltiplas ferramentas de IA** | Uma camada de memória que funciona com Claude, GPT, LLaMA, Ollama ou qualquer cliente MCP |
+| **Um dev usando Claude Code** | Recuperar automaticamente decisões de projeto, lições por arquivo e falhas passadas enquanto trabalha |
+| **Um power user de agentes de código** | Compartilhar uma camada de memória local entre ferramentas compatíveis com MCP |
+| **Uma equipe experimentando workflows de IA para código** | Exportar/importar conhecimento de projeto sem precisar de infraestrutura hospedada |
+| **Um desenvolvedor de agentes** | Adicionar memória local via MCP, HTTP, CLI ou o SDK Python |
 
 ---
 
-## Funciona com Tudo
+## Pensado Primeiro para Agentes de Código
 
 <table>
 <tr>
@@ -88,18 +99,18 @@ memesh
 ```bash
 memesh-mcp
 ```
-Protocolo MCP (configurado automaticamente)
+Ferramentas MCP + hooks do Claude Code
 
 </td>
 <td width="33%" align="center">
 
-**Python / LangChain**
-```python
-from memesh import MeMesh
-m = MeMesh()
-m.recall("auth")
+**Qualquer cliente HTTP**
+```bash
+curl localhost:3737/v1/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query":"auth"}'
 ```
-`pip install memesh`
+`memesh serve` (REST API)
 
 </td>
 <td width="33%" align="center">
@@ -117,103 +128,120 @@ Cole as ferramentas em qualquer chamada de API
 
 ---
 
-## Por que Não Usar Mem0 / Zep?
+## Por Que Não OpenMemory, Cursor Memories, Mem0 Ou Zep?
 
-| | **MeMesh** | Mem0 | Zep |
-|---|---|---|---|
-| **Tempo de instalação** | 5 segundos | 30–60 minutos | 30+ minutos |
-| **Configuração** | `npm i -g` — pronto | Neo4j + VectorDB + chaves de API | Neo4j + config |
-| **Armazenamento** | Arquivo SQLite único | Neo4j + Qdrant | Neo4j |
-| **Funciona offline** | Sim, sempre | Não | Não |
-| **Painel** | Integrado (7 abas + analytics) | Nenhum | Nenhum |
-| **Dependências** | 6 | 20+ | 10+ |
-| **Preço** | Grátis para sempre | Plano gratuito / Pago | Plano gratuito / Pago |
+| | **MeMesh** | OpenMemory | Cursor Memories | Mem0 | Zep / Graphiti |
+|---|---|---|---|---|---|
+| **Melhor para** | Memória local para agentes de código | Memória local/cross-client MCP | Memória de projeto nativa do Cursor | Memória gerenciada de app/agent | Grafos de conhecimento temporal |
+| **Forma de instalar** | `npm install -g @pcircle/memesh` | Fluxo de app local/server | Integrado no Cursor | Cloud API / SDK / MCP | Setup de serviço/framework |
+| **Armazenamento** | Um arquivo SQLite local | Stack de memória local | Regras/memórias gerenciadas pelo Cursor | Stack hospedada ou self-hosted | Banco de dados de grafo |
+| **Requer nuvem** | Não | Não em modo local | Depende de conta Cursor/configurações | Sim para plataforma | Geralmente sim/self-hosted |
+| **Hooks Claude Code** | Primeira classe | Ferramentas MCP | Não | Ferramentas MCP | Não específico para Claude Code |
+| **Dashboard** | Integrado | Integrado | Configurações do Cursor | Dashboard da plataforma | Ferramentas de plataforma/grafo |
+| **Trade-off** | Cunha local simples, não em escala corporativa | Footprint de app local mais amplo | Preso ao Cursor | Plataforma gerenciada forte, menos local-first | Modelo de grafo forte, setup mais pesado |
 
-**O MeMesh abre mão de:** recursos empresariais multi-inquilino em troca de **configuração instantânea, zero infraestrutura e 100% de privacidade**.
+**MeMesh troca infraestrutura gerenciada em escala corporativa por setup local instantâneo, armazenamento inspeionável e hooks de workflow para agentes de código.**
 
 ---
 
-## O que Acontece Automaticamente
+## O Que Acontece Automaticamente no Claude Code
 
-Você não precisa lembrar de tudo manualmente. O MeMesh possui **4 hooks** que capturam conhecimento sem que você precise fazer nada:
+Você não precisa lembrar tudo manualmente. MeMesh tem **6 hooks** que capturam e injetam conhecimento enquanto você trabalha:
 
-| Quando | O que o MeMesh faz |
+| Quando | O que MeMesh faz |
 |------|------------------|
-| **Início de cada sessão** | Carrega suas memórias mais relevantes + avisos proativos de lições passadas |
-| **Após cada `git commit`** | Registra o que você alterou, com estatísticas do diff |
-| **Quando o Claude para** | Captura arquivos editados, erros corrigidos e gera automaticamente lições estruturadas a partir de falhas |
-| **Antes da compactação de contexto** | Salva o conhecimento antes que se perca por limite de contexto |
+| **Início de cada sessão** | Carrega suas memórias mais relevantes + alertas proativos de lições passadas + banner de orquestração de agentes |
+| **Antes de editar arquivos** | Recupera memórias vinculadas ao arquivo ou projeto antes de Claude escrever código |
+| **Antes de comandos bash** | Incentiva Claude a despachar comandos de alta verificabilidade (test, build, lint, migrate, deploy, benchmark) como agentes de background |
+| **Depois de cada `git commit`** | Registra o que você mudou, com estatísticas de diff |
+| **Quando Claude para** | Captura arquivos editados, erros corrigidos e gera automaticamente lições estruturadas de falhas |
+| **Antes da compactação de contexto** | Salva conhecimento antes de ser perdido nos limites de contexto |
 
 > **Desative quando quiser:** `export MEMESH_AUTO_CAPTURE=false`
 
 ---
 
-## Painel
+## Dashboard
 
 7 abas, 11 idiomas, zero dependências externas. Acesse em `http://localhost:3737/dashboard` quando o servidor estiver rodando.
 
 | Aba | O que você vê |
-|-----|---------------|
+|-----|-------------|
 | **Search** | Busca full-text + similaridade vetorial em todas as memórias |
-| **Browse** | Lista paginada de todas as entidades com arquivamento/restauração |
-| **Analytics** | Pontuação de Saúde da Memória (0-100), timeline de 30 dias, métricas de valor, cobertura de conhecimento, sugestões de limpeza, seus padrões de trabalho |
-| **Graph** | Grafo de conhecimento interativo dirigido por força com filtros de tipo, busca, modo ego, heatmap de recência |
-| **Lessons** | Lições estruturadas de falhas passadas (erro, causa raiz, correção, prevenção) |
-| **Manage** | Arquivar e restaurar entidades |
-| **Settings** | Configuração do provedor LLM, seletor de idioma |
+| **Browse** | Lista paginada de todas as entidades com archive/restore |
+| **Analytics** | Memory Health Score (0-100), timeline de 30 dias, métricas de valor, cobertura de conhecimento, sugestões de limpeza, seus padrões de trabalho |
+| **Graph** | Grafo de conhecimento interativo force-directed com filtros por tipo, busca, modo ego, heatmap de recência |
+| **Lessons** | Lições estruturadas de falhas passadas (erro, causa raiz, fix, prevenção) |
+| **Manage** | Archive e restore de entidades |
+| **Settings** | Config do provedor LLM, seletor de idioma instantâneo |
 
 ---
 
 ## Funcionalidades Inteligentes
 
-**🧠 Busca Inteligente** — Pesquise "login security" e encontre memórias sobre "OAuth PKCE". O MeMesh expande consultas com termos relacionados usando o LLM configurado.
+**🧠 Busca Inteligente** — Busque "login security" e encontre memórias sobre "OAuth PKCE". MeMesh expande queries com termos relacionados usando seu LLM configurado.
 
-**📊 Classificação por Pontuação** — Resultados classificados por relevância (35%) + recência de uso (25%) + frequência (20%) + confiança (15%) + se a informação ainda é atual (5%).
+**📊 Ranking Pontuado** — Resultados ranqueados por relevância (30%) + recência (25%) + frequência (15%) + confiança (15%) + impacto de recall (10%) + validade temporal (5%).
 
-**🔄 Evolução do Conhecimento** — As decisões mudam. `forget` arquiva memórias antigas (nunca deleta). Relações `supersedes` conectam o antigo ao novo. Seu AI sempre vê a versão mais recente.
+**🔄 Evolução de Conhecimento** — Decisões mudam. `forget` arquiva memórias antigas (nunca deleta). Relações `supersedes` vinculam antigas → novas. Sua IA sempre vê a versão mais recente.
 
-**⚠️ Detecção de Conflitos** — Se você tiver duas memórias que se contradizem, o MeMesh avisa.
+**⚠️ Detecção de Conflitos** — Se você tem duas memórias que se contradizem, MeMesh te avisa.
 
 **📦 Compartilhamento em Equipe** — `memesh export > team-knowledge.json` → compartilhe com sua equipe → `memesh import team-knowledge.json`
+Bundles importados permanecem pesquisáveis, mas MeMesh não injeta automaticamente memórias importadas nos hooks do Claude até você revisar ou re-armazená-las localmente.
+
+---
+
+## Exemplos de Uso
+
+> "MeMesh lembrou que escolhemos PKCE em vez de implicit flow há três semanas. Quando pedi ao Claude sobre auth de novo, ele já sabia — sem need de re-explicar."
+> — **Dev solo, construindo um SaaS**
+
+> "Exportamos a memória da equipe toda sexta e importamos segunda. O Claude de todo mundo começa a semana sabendo o que a equipe aprendeu na semana passada."
+> — **Startup com 3 pessoas, base de conhecimento compartilhada**
+
+> "O dashboard mostrou que 90% das minhas memórias eram logs de sessão auto-gerados. Comecei a usar `remember` deliberadamente para decisões arquitetônicas. Game changer."
+> — **Dev que descobriu a aba Analytics**
 
 ---
 
-## Ative o Modo Inteligente (Opcional)
+## Desbloqueie Smart Mode (Opcional)
 
-O MeMesh funciona completamente offline por padrão. Adicione uma chave de API de LLM para desbloquear buscas mais inteligentes:
+MeMesh funciona offline por padrão. Adicione uma chave de API de LLM apenas se quiser query expansion, extração mais inteligente e compressão:
 
 ```bash
 memesh config set llm.provider anthropic
 memesh config set llm.api-key sk-ant-...
 ```
 
-Ou use a aba Configurações do painel (configuração visual):
+Ou use a aba Settings do dashboard (setup visual):
 
 ```bash
-memesh  # abre o painel → aba Configurações
+memesh  # abre dashboard → aba Settings
 ```
 
-| | Nível 0 (padrão) | Nível 1 (Modo Inteligente) |
+| | Level 0 (padrão) | Level 1 (Smart Mode) |
 |---|---|---|
-| **Busca** | Correspondência de palavras-chave FTS5 | + Expansão de consulta por LLM (~97% de recall) |
-| **Captura automática** | Padrões baseados em regras | + LLM extrai decisões e lições |
-| **Compressão** | Não disponível | `consolidate` comprime memórias longas |
-| **Custo** | Grátis, sem chave de API | ~$0,0001 por busca (Haiku) |
+| **Busca** | Correspondência de keywords FTS5 | + query expansion de LLM (~97% recall) |
+| **Auto-capture** | Padrões baseados em regras | + LLM extrai decisões & lições |
+| **Compressão** | Não disponível | `consolidate` comprime memórias verbosas |
+| **Custo** | Grátis, sem chave de API | ~$0.0001 por busca (Haiku) |
 
 ---
 
-## Todas as 8 Ferramentas de Memória
+## Todas as 9 Ferramentas de Memória
 
 | Ferramenta | O que faz |
 |------|-------------|
 | `remember` | Armazena conhecimento com observações, relações e tags |
-| `recall` | Busca inteligente com pontuação multifatorial e expansão de consulta por LLM |
-| `forget` | Arquivamento suave (nunca deleta) ou remoção de observações específicas |
-| `consolidate` | Compressão de memórias longas com auxílio de LLM |
+| `recall` | Busca inteligente com scoring multi-fator e query expansion com LLM |
+| `forget` | Soft-archive (nunca deleta) ou remove observações específicas |
+| `consolidate` | Compressão com LLM de memórias verbosas |
 | `export` | Compartilha memórias como JSON entre projetos ou membros da equipe |
-| `import` | Importa memórias com estratégias de mesclagem (pular / sobrescrever / anexar) |
-| `learn` | Registra lições estruturadas a partir de erros (erro, causa raiz, correção, prevenção) |
-| `user_patterns` | Analisa seus padrões de trabalho — agenda, ferramentas, pontos fortes, áreas de aprendizado |
+| `import` | Importa memórias com estratégias de merge (skip / overwrite / append) |
+| `learn` | Registra lições estruturadas de erros (erro, causa raiz, fix, prevenção) |
+| `user_patterns` | Analisa seus padrões de trabalho — schedule, ferramentas, pontos fortes, áreas de aprendizado |
+| `verify_agent_work` | Persiste um relatório de verificação para trabalho de background-agent; reality-checks mudanças de arquivo declaradas contra `git diff` |
 
 ---
 
@@ -234,7 +262,7 @@ memesh  # abre o painel → aba Configurações
                     (~/.memesh/knowledge-graph.db)
 ```
 
-O núcleo é independente de framework. A mesma lógica é executada a partir do terminal, HTTP ou MCP.
+Core é agnóstico a framework. A mesma lógica roda de terminal, HTTP ou MCP.
 
 ---
 
@@ -243,10 +271,11 @@ O núcleo é independente de framework. A mesma lógica é executada a partir do
 ```bash
 git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
 cd memesh-llm-memory && npm install && npm run build
-npm test -- --run    # 413 tests
+npm test             # 489 tests
+npm run test:e2e-dashboard
 ```
 
-Painel: `cd dashboard && npm install && npm run dev`
+Dashboard: `cd dashboard && npm install && npm run dev`
 
 ---