@pcircle/memesh 4.0.3 → 4.1.0

package/README.pt.md

@@ -1,110 +1,284 @@
+<!-- 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>Camada de memória local para Claude Code e agentes de código compatíveis com MCP.</strong><br />
-    Um arquivo SQLite. Sem Docker. Sem depender de 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>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-22c55e?style=flat-square" alt="MIT" /></a>
+    <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-22c55e?style=flat-square" alt="Node" /></a>
+    <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-a855f7?style=flat-square" alt="MCP" /></a>
   </p>
 </p>
 
-> Este README em português é uma versão resumida. Para a documentação mais completa e atualizada, use o [English README](README.md).
+---
 
-## Qual problema ele resolve?
+## O Problema
 
-Agentes de código costumam perder o contexto entre sessões. Decisões de arquitetura, correções importantes, erros já resolvidos e restrições do projeto acabam sendo explicados de novo e de novo.
+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.
 
-**O MeMesh mantém esse conhecimento no seu ambiente local, com busca, inspeção e reaproveitamento ao longo do trabalho.**
+**MeMesh oferece memória local persistente, pesquisável e evolutiva para agentes de código.**
 
-Este pacote npm é a versão local do plugin / package do MeMesh. Ele não é o produto de workspace em nuvem nem uma plataforma enterprise completa.
+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.
 
-## Comece em 60 segundos
+---
 
-### 1. Instale
+## Comece em 60 Segundos
+
+### Passo 1: Instale
 
 ```bash
 npm install -g @pcircle/memesh
 ```
 
-### 2. Salve uma decisão
+### Passo 2: Armazene uma decisão
 
 ```bash
 memesh remember --name "auth-decision" --type "decision" --obs "Use OAuth 2.0 with PKCE"
 ```
 
-### 3. Recupere depois
+### 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
+```
+
+**É só isso.** MeMesh já está lembrando e recuperando entre sessões.
+
+Se quiser verificar a instalação e toda a configuração local de ponta a ponta:
+
+```bash
+memesh doctor
 ```
 
-Abra o dashboard:
+Abra o dashboard para explorar sua memória:
 
 ```bash
 memesh
 ```
 
-## Para quem ele foi feito?
+<p align="center">
+  <img src="docs/images/dashboard-search.png" alt="MeMesh Search — encontre qualquer memória instantaneamente" width="100%" />
+</p>
+
+<p align="center">
+  <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 por tipo e modo ego" width="100%" />
+</p>
+
+---
+
+## Para Quem é Isso?
+
+| Se você é... | MeMesh te ajuda a... |
+|---------------|---------------------|
+| **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 |
+
+---
+
+## Pensado Primeiro para Agentes de Código
+
+<table>
+<tr>
+<td width="33%" align="center">
+
+**Claude Code / Desktop**
+```bash
+memesh-mcp
+```
+Ferramentas MCP + hooks do Claude Code
+
+</td>
+<td width="33%" align="center">
+
+**Qualquer cliente HTTP**
+```bash
+curl localhost:3737/v1/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query":"auth"}'
+```
+`memesh serve` (REST API)
+
+</td>
+<td width="33%" align="center">
+
+**Qualquer LLM (formato OpenAI)**
+```bash
+memesh export-schema \
+  --format openai
+```
+Cole as ferramentas em qualquer chamada de API
+
+</td>
+</tr>
+</table>
+
+---
 
-- Desenvolvedores que usam Claude Code e querem manter contexto entre sessões
-- Usuários avançados que querem compartilhar a mesma memória local entre agentes MCP
-- Pequenas equipes AI-native que querem trocar conhecimento via export / import
-- Desenvolvedores de agents que querem integrar memória local via CLI, HTTP ou MCP
+## Por Que Não OpenMemory, Cursor Memories, Mem0 Ou Zep?
 
-## Por que usar o MeMesh?
+| | **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 |
 
-- Local-first: os dados ficam no seu próprio arquivo SQLite
-- Instalação leve: `npm install -g` e pronto
-- Integração direta: suporta CLI, HTTP e MCP
-- Bom encaixe com Claude Code: hooks ajudam a trazer contexto no fluxo de trabalho
-- Transparência: o dashboard permite ver e organizar a memória
-- Limite de confiança mais seguro: memórias importadas continuam pesquisáveis, mas não entram automaticamente nos hooks do Claude sem revisão ou novo salvamento local
+**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 ele faz automaticamente no Claude Code?
+---
 
-Hoje o MeMesh ajuda em 5 momentos:
+## O Que Acontece Automaticamente no Claude Code
 
-- no início da sessão, carrega memórias relevantes e lições já conhecidas
-- antes de editar arquivos, busca memórias relacionadas ao arquivo ou ao projeto
-- depois de `git commit`, registra o que foi alterado
-- no fim da sessão, organiza correções, erros e lessons learned
-- antes do compact de contexto, salva o que não deveria se perder
+Você não precisa lembrar tudo manualmente. MeMesh tem **6 hooks** que capturam e injetam conhecimento enquanto você trabalha:
 
-## O que existe no dashboard?
+| Quando | O que MeMesh faz |
+|------|------------------|
+| **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 |
 
-O dashboard tem 7 abas e suporte a 11 idiomas:
+> **Desative quando quiser:** `export MEMESH_AUTO_CAPTURE=false`
 
-- Search: buscar memórias
-- Browse: listar memórias
-- Analytics: acompanhar saúde e tendências
-- Graph: ver relações de conhecimento
-- Lessons: revisar lições aprendidas
-- Manage: arquivar e restaurar memórias
-- Settings: configurar provedor de LLM e idioma
+---
 
-## O que é o Smart Mode?
+## Dashboard
 
-O MeMesh funciona offline por padrão. Se você configurar uma API key de LLM, pode habilitar recursos extras, como:
+7 abas, 11 idiomas, zero dependências externas. Acesse em `http://localhost:3737/dashboard` quando o servidor estiver rodando.
 
-- query expansion
-- extração automática mais útil
-- organização e compressão mais inteligentes
+| Aba | O que você vê |
+|-----|-------------|
+| **Search** | Busca full-text + similaridade vetorial em todas as memórias |
+| **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 |
 
-Sem API key, o núcleo do produto continua funcionando normalmente.
+---
 
-## Leia mais
+## Funcionalidades Inteligentes
 
-- Funcionalidades completas, comparações, API e release notes: [English README](README.md)
-- Guia de integrações: [docs/platforms/README.md](docs/platforms/README.md)
-- Referência de API: [docs/api/API_REFERENCE.md](docs/api/API_REFERENCE.md)
+**🧠 Busca Inteligente** — Busque "login security" e encontre memórias sobre "OAuth PKCE". MeMesh expande queries com termos relacionados usando seu LLM configurado.
 
-## Desenvolvimento e verificação
+**📊 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 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ê 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**
+
+---
+
+## Desbloqueie Smart Mode (Opcional)
+
+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 Settings do dashboard (setup visual):
+
+```bash
+memesh  # abre dashboard → aba Settings
+```
+
+| | Level 0 (padrão) | Level 1 (Smart Mode) |
+|---|---|---|
+| **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 9 Ferramentas de Memória
+
+| Ferramenta | O que faz |
+|------|-------------|
+| `remember` | Armazena conhecimento com observações, relações e tags |
+| `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 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` |
+
+---
+
+## Arquitetura
+
+```
+                    ┌─────────────────┐
+                    │   Core Engine   │
+                    │  (8 operations) │
+                    └────────┬────────┘
+           ┌─────────────────┼─────────────────┐
+           │                 │                 │
+     CLI (memesh)    HTTP API (serve)    MCP (memesh-mcp)
+           │                 │                 │
+           └─────────────────┼─────────────────┘
+                             │
+                    SQLite + FTS5 + sqlite-vec
+                    (~/.memesh/knowledge-graph.db)
+```
+
+Core é agnóstico a framework. A mesma lógica roda de terminal, HTTP ou MCP.
+
+---
+
+## Contribuindo
 
 ```bash
 git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
-cd memesh-llm-memory
-npm install
-npm run build
-npm test
+cd memesh-llm-memory && npm install && npm run build
+npm test             # 489 tests
+npm run test:e2e-dashboard
 ```
+
+Dashboard: `cd dashboard && npm install && npm run dev`
+
+---
+
+<p align="center">
+  <strong>MIT</strong> — Feito por <a href="https://pcircle.ai">PCIRCLE AI</a>
+</p>