MCP Memory Dashboard

Um aplicativo de desktop para gerenciar e interagir com o MCP Memory Service, um sistema de memória semântica construído sobre o Model Context Protocol.

GitHub

Experimente este MCPPatrocinado

Documentação

🚨 OBSOLETO - Este Repositório Não é Mais Necessário! 🚨

⚠️ AVISO IMPORTANTE: Este dashboard independente agora está OBSOLETO!

O MCP Memory Service agora inclui um dashboard embutido com todos os recursos desta versão independente e muito mais!

🎉 O que há de novo?

O MCP Memory Service principal agora oferece:

✅ Dashboard Web Integrado - Sem necessidade de instalação separada

✅ Todos os Recursos Originais - Armazenar, pesquisar, recuperar e gerenciar memórias

✅ Melhor Integração - Acesso direto ao serviço de memória

✅ Configuração Simplificada - Uma instalação, tudo incluído

✅ Desenvolvimento Ativo - Novos recursos adicionados regularmente

🔄 Como Migrar
Atualize seu MCP Memory Service:
git pull origin main
python install.py
Acesse o dashboard embutido:

Inicie o serviço de memória com modo HTTP

Navegue até http://localhost:8000 no seu navegador

Aproveite todos os recursos sem este aplicativo separado!
📦 Por que foi obsoleto?

Para proporcionar uma melhor experiência ao usuário, integramos o dashboard diretamente no serviço de memória. Isso significa:

Menos dependências para gerenciar

Instalação e atualizações mais fáceis

Melhor desempenho e confiabilidade

Fonte única de verdade para todos os recursos

🔗 Comece Agora

Visite o repositório principal para instruções de instalação e uso:

👉 MCP Memory Service

O conteúdo original do README está preservado abaixo para referência histórica.

MCP Memory Dashboard

Um aplicativo desktop profissional para gerenciar e interagir com o MCP Memory Service - um sistema de memória semântica construído sobre o Model Context Protocol (MCP).

🚀 NOVO: Integração ChromaDB Docker de Alto Desempenho

Atualização Importante: Agora suporta acesso direto ao ChromaDB via Docker para desempenho 2-3x mais rápido e zero conflitos de serviço!

⚡ Benefícios do Modo Docker

🚀 2-3x Mais Rápido: Acesso HTTP direto elimina a sobrecarga do MCP (50-150ms vs 200-500ms)
🔄 Zero Conflitos: Elimina a duplicação do serviço MCP que poderia interferir com o Claude Desktop
💾 Zero Perda de Dados: Usa seu banco de dados existente diretamente via montagem de volume
🐳 Gerenciamento Automático: Gerenciamento transparente do ciclo de vida do contêiner Docker
🛡️ Fallback Gracioso: Retorna automaticamente ao MCP tradicional se o Docker estiver indisponível

Configuração Rápida do Docker

Instale o Docker Desktop (se ainda não estiver instalado)
Ative o Modo Docker: Defina VITE_USE_DIRECT_CHROMA_ACCESS=true no seu arquivo .env
Inicie o Dashboard: npm start - o contêiner Docker é gerenciado automaticamente!

📖 Guia Completo de Configuração Docker | 🏗️ Detalhes da Arquitetura Técnica

✨ Recursos

🧠 Gerenciamento de Memórias

Armazenar Memórias: Salve conteúdo com tags e metadados
Pesquisa Semântica: Encontre memórias usando consultas em linguagem natural com botões individuais de exclusão
Recuperação por Tempo: Pesquise memórias por expressões de tempo ("ontem", "semana passada", etc.)
Exclusão Individual de Memórias: Exclua memórias específicas com diálogos de confirmação
Gerenciamento de Tags: Organize e exclua memórias por tags com seleção múltipla
Resultados em Tempo Real: Pesquisa e recuperação instantâneas com pontuações de similaridade

📊 Dashboard e Análises

Estatísticas ao Vivo: Total de memórias, tags únicas, saúde do banco de dados
Monitoramento de Saúde do Banco de Dados: Status de saúde em tempo real (0-100%)
Métricas de Desempenho: Rastreamento do tempo médio real de consulta (1-3 segundos)
Informações de Armazenamento: Tamanho do banco de dados e informações de caminho
Interface de 4 Abas: Abas dedicadas para Armazenar, Pesquisar, Recuperar e Gerenciamento de Tags

🔧 Operações do Banco de Dados

Otimização do Banco de Dados: Limpe e otimize índices vetoriais
Criação de Backup: Crie backups com carimbo de data/hora e feedback detalhado (caminho do arquivo, tamanho, carimbo de data/hora)
Verificações de Saúde: Valide a integridade e o desempenho do banco de dados
Auto-inicialização: Configuração e ajuste contínuos do ChromaDB
Sistema de Backup Real: Compressão completa em tar.gz com notificações de sucesso

🏷️ Gerenciamento Aprimorado de Tags

Exclusão de Múltiplas Tags: Selecione e exclua várias tags simultaneamente
Seleção Visual de Tags: Chips de tags interativos com funcionalidade de adicionar/remover
Opções Flexíveis de Exclusão: Suporte para exclusão de tags únicas e múltiplas
Consistência de API: Interface consistente com a funcionalidade de pesquisa
Avisos Claros: Entenda a lógica OU vs E para operações de tags

⏰ Sistema de Recuperação por Tempo

Filtros Rápidos: Botões de um clique para [Hoje] [Ontem] [Semana Passada] [Mês Passado] [Últimos 3 Meses]
Linguagem Natural: Expressões de tempo em texto livre como "há 2 dias", "verão passado"
Processamento Inteligente: Combina filtragem por tempo com pesquisa semântica quando apropriado
Aba Dedicada: Interface separada de "Recuperar por Tempo" para consultas temporais

🎨 Experiência do Usuário

Indicadores de Carregamento: Feedback visual durante a inicialização do banco de dados
Rastreamento de Progresso: Atualizações de status passo a passo durante a inicialização
Interface Profissional: Aplicativo desktop limpo e moderno baseado em Electron
Atalhos de Teclado: F12 ou Ctrl+Shift+I para ferramentas de desenvolvedor
Design Responsivo: Layout adaptativo para diferentes tamanhos de janela
Feedback Rico: Mensagens detalhadas de sucesso/erro com notificações dispensáveis
Recursos de Segurança: Diálogos de confirmação para operações destrutivas

🚀 Início Rápido

Pré-requisitos

Node.js (v16 ou superior)
Python (v3.10 ou superior) com gerenciador de pacotes UV
MCP Memory Service (instalação compatível)

Instalação

Clone o repositório:

git clone https://github.com/yourusername/mcp-memory-dashboard.git
cd mcp-memory-dashboard

Instale as dependências:
```
npm install
```

Configure as variáveis de ambiente: Crie um arquivo .env na raiz do projeto:

macOS/Linux:

# Basic Configuration
VITE_MEMORY_SERVICE_PATH="/path/to/mcp-memory-service"
VITE_MEMORY_CHROMA_PATH="/Users/yourusername/Library/Application Support/mcp-memory/chroma_db"
VITE_MEMORY_BACKUPS_PATH="/Users/yourusername/Library/Application Support/mcp-memory/backups"
VITE_CLAUDE_CONFIG_PATH="/Users/yourusername/Library/Application Support/Claude/claude_desktop_config.json"

# 🚀 NEW: Docker ChromaDB Mode (High Performance)
VITE_USE_DIRECT_CHROMA_ACCESS=true   # Enable Docker mode for 2-3x faster performance
# VITE_USE_DIRECT_CHROMA_ACCESS=false  # Traditional MCP mode (stable fallback)

Windows:

# Basic Configuration
VITE_MEMORY_SERVICE_PATH="C:\path\to\mcp-memory-service"
VITE_MEMORY_CHROMA_PATH="C:\Users\%USERNAME%\AppData\Local\mcp-memory\chroma_db"
VITE_MEMORY_BACKUPS_PATH="C:\Users\%USERNAME%\AppData\Local\mcp-memory\backups"
VITE_CLAUDE_CONFIG_PATH="C:\Users\%USERNAME%\AppData\Roaming\Claude\claude_desktop_config.json"

# 🚀 NEW: Docker ChromaDB Mode (High Performance)
VITE_USE_DIRECT_CHROMA_ACCESS=true   # Enable Docker mode for 2-3x faster performance
# VITE_USE_DIRECT_CHROMA_ACCESS=false  # Traditional MCP mode (stable fallback)

Inicie o aplicativo:
```
npm start
```

🪟 Notas Específicas para Windows

Configuração de Caminhos

Use barras invertidas duplas (\\) ou barras normais (/) nos caminhos
A variável de ambiente %USERNAME% resolve automaticamente para seu nome de usuário do Windows
A configuração do Claude Desktop é armazenada em AppData\Roaming\Claude\
Os dados de memória são armazenados em AppData\Local\mcp-memory\

Política de Execução do PowerShell

Se você encontrar erros de execução de script, pode ser necessário habilitar a execução de scripts:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Caminhos Comuns do Windows

Configuração do Claude: C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json
Banco de Dados de Memória: C:\Users\<username>\AppData\Local\mcp-memory\chroma_db
Backups: C:\Users\<username>\AppData\Local\mcp-memory\backups

⚙️ Configuração

Configuração do MCP Memory Service

Certifique-se de que seu MCP Memory Service esteja configurado corretamente na configuração do Claude Desktop:

macOS/Linux:

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["--directory", "/path/to/mcp-memory-service", "run", "memory"],
      "env": {
        "MCP_MEMORY_CHROMA_PATH": "/Users/yourusername/Library/Application Support/mcp-memory/chroma_db",
        "MCP_MEMORY_BACKUPS_PATH": "/Users/yourusername/Library/Application Support/mcp-memory/backups"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\mcp-memory-service", "run", "memory"],
      "env": {
        "MCP_MEMORY_CHROMA_PATH": "C:\\Users\\yourusername\\AppData\\Local\\mcp-memory\\chroma_db",
        "MCP_MEMORY_BACKUPS_PATH": "C:\\Users\\yourusername\\AppData\\Local\\mcp-memory\\backups"
      }
    }
  }
}

Variáveis de Ambiente

Variável	Descrição	Exemplo macOS/Linux	Exemplo Windows
`VITE_MEMORY_SERVICE_PATH`	Caminho para o MCP Memory Service	`/path/to/mcp-memory-service`	`C:\path\to\mcp-memory-service`
`VITE_MEMORY_CHROMA_PATH`	Diretório do banco de dados ChromaDB	`~/Library/Application Support/mcp-memory/chroma_db`	`C:\Users\%USERNAME%\AppData\Local\mcp-memory\chroma_db`
`VITE_MEMORY_BACKUPS_PATH`	Diretório de armazenamento de backups	`~/Library/Application Support/mcp-memory/backups`	`C:\Users\%USERNAME%\AppData\Local\mcp-memory\backups`
`VITE_CLAUDE_CONFIG_PATH`	Arquivo de configuração do Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`	`C:\Users\%USERNAME%\AppData\Roaming\Claude\claude_desktop_config.json`
`VITE_USE_DIRECT_CHROMA_ACCESS`	🚀 NOVO: Ativar modo ChromaDB Docker	`true` (Docker) / `false` (MCP)	`true` (Docker) / `false` (MCP)

🐳 Comparação entre Modo Docker e Modo MCP

Recurso	Modo Docker (`true`)	Modo MCP (`false`)
Desempenho	2-3x mais rápido (50-150ms)	Padrão (200-500ms)
Conflitos de Serviço	Nenhum (elimina duplicação)	Possíveis (conflitos MCP)
Requisitos	Docker Desktop necessário	Python + UV necessários
Migração de Dados	Nenhuma (usa banco existente)	Nenhuma (usa banco existente)
Confiabilidade	Reinício automático, monitoramento de saúde	Depende do serviço MCP
Fallback	Fallback automático para MCP	N/A (é o fallback)

🎯 Uso

Armazenando Memórias

Navegue até a aba Armazenar Memória
Digite seu conteúdo na área de texto
Adicione tags separadas por vírgulas (opcional)
Clique em Armazenar para salvar

Pesquisando Memórias

Navegue até a aba Pesquisar Memórias
Digite sua consulta de pesquisa
Clique em Pesquisar para encontrar memórias relevantes
Os resultados mostram conteúdo, tags, pontuações de similaridade e botões individuais de exclusão (🗑️)
Clique no botão de exclusão em qualquer memória para exclusão individual com confirmação

Recuperação por Tempo

Navegue até a aba Recuperar por Tempo
Filtros Rápidos: Clique nos botões predefinidos ([Hoje] [Ontem] [Semana Passada] [Mês Passado] [Últimos 3 Meses])
Texto Livre: Digite expressões de tempo personalizadas como "há 2 dias", "verão passado", "esta manhã"
Clique em Recuperar para encontrar memórias desse período
Os resultados incluem botões individuais de exclusão e pontuações de similaridade quando aplicável

Gerenciando Tags

Navegue até a aba Gerenciamento de Tags
Digite as tags uma a uma no campo de entrada e pressione Enter ou clique em "Adicionar Tag"
As tags selecionadas aparecem como chips visuais com botões de remoção (×)
Remova tags indesejadas clicando no × de cada chip
Clique em Excluir [N] Tags para remover todas as memórias que contenham qualquer uma das tags selecionadas
Use Limpar Seleção para remover todas as tags selecionadas sem excluir
⚠️ Aviso: Usa lógica OU - memórias com QUALQUER tag selecionada serão excluídas

Operações do Banco de Dados

Atualizar Estatísticas: Clique no ícone de configurações para recarregar as estatísticas e ver os tempos reais de consulta
Otimizar Banco de Dados: Clique no ícone de atualização para otimizar o desempenho
Criar Backup: Clique no ícone de salvar para criar um backup com carimbo de data/hora e feedback detalhado
- A mensagem de sucesso mostra: caminho do arquivo, tamanho em MB, carimbo de data/hora e notificação dispensável
- Exemplo: "✅ Backup criado com sucesso! 📁 Local: /caminho/para/backup_20250607_143025.tar.gz 📊 Tamanho: 2.4 MB"

🏗️ Arquitetura Técnica

Frontend

Framework: React 18 com TypeScript
Desktop: Electron para aplicativo desktop multiplataforma
Estilização: Tailwind CSS com componentes personalizados
Ícones: Biblioteca de ícones Lucide React
Build: Vite para desenvolvimento e build rápidos

Integração Backend

Protocolo: Model Context Protocol (MCP) via stdin/stdout
Comunicação: JSON-RPC 2.0 para chamadas de ferramentas
Serviço de Memória: Servidor MCP baseado em Python com ChromaDB
Banco de Dados Vetorial: ChromaDB para capacidades de pesquisa semântica

Componentes Principais

Cliente do Serviço de Memória: Gerencia a comunicação MCP
Interface do Dashboard: Componentes de UI baseados em React
Processo Principal do Electron: Gerenciamento do aplicativo desktop
Scripts de Pré-carregamento: Exposição segura da API ao renderizador

🛠️ Desenvolvimento

Modo de Desenvolvimento

npm run dev

Inicia tanto o servidor de desenvolvimento Vite quanto o Electron em modo de desenvolvimento com recarga automática.

Build para Produção

npm run build

Cria build de produção otimizado no diretório dist/.

Scripts Disponíveis

npm start - Build e execução da versão de produção
npm run dev - Iniciar servidor de desenvolvimento
npm run build - Build para produção
npm run electron:preview - Executar Electron com arquivos compilados

🐛 Solução de Problemas

Problemas Comuns

🐳 Problemas com Modo Docker (VITE_USE_DIRECT_CHROMA_ACCESS=true)

Mensagem "Docker não disponível"

Instale o Docker Desktop em https://www.docker.com/products/docker-desktop
Certifique-se de que o Docker Desktop esteja em execução (o ícone deve estar visível na bandeja do sistema)
O sistema retorna automaticamente ao modo MCP se o Docker estiver indisponível

Mensagem "Usando porta alternativa 8001"

A porta 8000 está ocupada por outro serviço
O sistema usa automaticamente portas alternativas (8001, 8002, etc.)
Isso é comportamento normal e não afeta a funcionalidade Inicialização mais lenta no primeiro uso com o modo Docker
A primeira execução baixa a imagem Docker do ChromaDB (uma única vez, ~100MB)
As inicializações seguintes são mais rápidas que o modo MCP
O progresso é exibido nos logs do console

Problemas de saúde do contêiner

O sistema reinicia automaticamente contêineres não saudáveis
Verifique o Docker Desktop para o status do contêiner
Reinicialização manual: docker restart mcp-memory-chromadb

🔄 Problemas no Modo MCP (VITE_USE_DIRECT_CHROMA_ACCESS=false)

O aplicativo exibe "Falha ao conectar ao serviço de memória"

Verifique se o MCP Memory Service está instalado e acessível
Confirme que o VITE_MEMORY_SERVICE_PATH aponta para o diretório correto
Garanta que o gerenciador de pacotes UV esteja instalado (pip install uv)

As operações do painel estão lentas

A primeira execução requer a inicialização do ChromaDB (10-30 segundos)
As operações subsequentes são mais rápidas (2-5 segundos)
Este é o comportamento esperado para operações de banco de dados vetorial

O gerenciamento aprimorado de tags não está funcionando

Certifique-se de estar usando o MCP Memory Service v1.1.0+ com as correções do Issue 5
Verifique se a funcionalidade aprimorada delete_by_tag está disponível
Verifique os logs do console (F12) para mensagens de compatibilidade da API

Estatísticas mostrando 0 apesar de ter memórias

Aguarde a conclusão da inicialização completa do painel
Verifique se o caminho do ChromaDB tem permissões adequadas de leitura/gravação
Tente clicar no botão de atualizar estatísticas

Ferramentas de desenvolvedor abrindo automaticamente

As ferramentas de desenvolvedor estão desabilitadas por padrão
Use F12 ou Ctrl+Shift+I para alternar quando necessário

Notas de Desempenho

Inicialização inicial: 10-30 segundos para a inicialização do ChromaDB
Operações de memória: 2-10 segundos dependendo do tamanho do banco de dados
Recuperação de estatísticas: 3-5 segundos para bancos de dados grandes com rastreamento de tempo de consulta real
Operações de busca: 1-3 segundos com resultados em tempo real e métricas de precisão
Operações de recall: 1-3 segundos para filtragem baseada em tempo
Criação de backup: 2-10 segundos criando arquivos tar.gz compactados
Exclusão individual: Quase instantânea com diálogos de confirmação

Solução de Problemas de Novos Recursos (v1.2.0)

Botões de exclusão individual não aparecendo

Certifique-se de que as memórias tenham IDs válidos (atualize os resultados da busca, se necessário)
Verifique se você está usando a versão mais recente do serviço de memória
A exclusão individual requer o serviço de memória v1.2.0+

Recall baseado em tempo não funcionando

Tente expressões mais simples primeiro: "hoje", "ontem", "semana passada"
Expressões de tempo complexas podem exigir frases exatas
Verifique os logs do console (F12) para erros de análise de tempo

Feedback de backup não aparecendo

Verifique se o diretório de backup tem permissões de gravação
Confirme se a variável de ambiente do caminho de backup está definida corretamente
Bancos de dados grandes podem levar mais tempo para backup (o progresso é exibido)

Tempos de consulta ainda mostrando 0

Realize algumas buscas para preencher o cálculo da média
O rastreamento do tempo de consulta requer pelo menos uma operação de busca
Reinicie o aplicativo se as métricas não atualizarem

Obtendo Ajuda

Verifique os logs do console (F12) para mensagens de erro detalhadas
Confirme se todas as variáveis de ambiente estão definidas corretamente
Garanta que o MCP Memory Service esteja funcionando de forma independente
Verifique as permissões de arquivo para os diretórios de banco de dados e backup

🤝 Contribuindo

Aceitamos contribuições! Por favor:

Faça um fork do repositório
Crie um branch de recurso (git checkout -b feature/amazing-feature)
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Diretrizes de Desenvolvimento

Siga as melhores práticas de TypeScript
Adicione tratamento de erros adequado
Inclua comentários JSDoc para funções complexas
Teste com builds de desenvolvimento e produção
Garanta compatibilidade entre plataformas

📄 Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

🙏 Agradecimentos

Anthropic pela especificação do Model Context Protocol
ChromaDB pela base do banco de dados vetorial
Comunidades React & Electron pela excelente documentação
Claude pela assistência no desenvolvimento e depuração

📈 Histórico de Versões

v1.3.0 (Atual) - 🚀 Principal: Integração Docker ChromaDB

✅ Modo Docker ChromaDB: Integração de contêiner Docker de alto desempenho com gerenciamento automático
✅ Melhoria de Desempenho de 2-3x: O acesso HTTP direto elimina a sobrecarga do MCP (tempos de resposta de 50-150ms)
✅ Resolução de Conflitos MCP: Elimina a duplicação de serviços que interferia no Claude Desktop
✅ Zero Migração de Dados: O volume montado preserva todas as memórias existentes instantaneamente
✅ Fallback Gracioso: Fallback automático para o modo MCP se o Docker não estiver disponível
✅ Gerenciamento do Ciclo de Vida do Contêiner: Monitoramento de saúde, reinicialização automática, desligamento gracioso
✅ Resolução de Conflitos de Porta: Seleção automática de porta com portas de fallback
✅ Documentação Abrangente: Guias de configuração completos e documentação técnica
✅ Pronto para Produção: Suíte de testes completa com validação de integração Docker
🔧 Técnico: Resolve as Issues #11 (duplicação MCP) e #12 (limitação do cliente JS) do GitHub

v1.2.0 - Melhorias de UX e Resolução da Issue #2

✅ Rastreamento de Tempo de Consulta Real: Exibe tempos médios reais de consulta (1-3 segundos) em vez de 0
✅ Sistema de Backup Completo: Backups tar.gz reais com feedback detalhado (caminho, tamanho, timestamp)
✅ Exclusão Individual de Memória: Botões de exclusão (🗑️) em cada memória com diálogos de confirmação
✅ Recall Baseado em Tempo: Nova aba "Recall por Tempo" com botões de filtro rápido e linguagem natural
✅ Interface de 4 Abas: Armazenar → Buscar → Recall → Gerenciamento de Tags para melhor organização
✅ UX Aprimorada: Notificações ricas, mensagens de sucesso dispensáveis e atualizações em tempo real
✅ Recursos de Segurança: Diálogos de confirmação para operações destrutivas
✅ Métricas de Desempenho: Medição de tempo de consulta real e sistema de média

v1.1.0 - Gerenciamento Aprimorado de Tags (Resolução da Issue #5)

✅ Exclusão de Múltiplas Tags: Selecione e exclua várias tags simultaneamente
✅ Interface Visual de Tags: Chips de tags interativos com funcionalidade de adicionar/remover
✅ UX Aprimorada: Interface consistente com funcionalidade de busca
✅ Consistência da API: Ambiguidade da função delete_tag resolvida (Issue 5)
✅ Compatibilidade Retroativa: Toda a funcionalidade existente preservada
✅ Avisos Melhorados: Explicações claras da lógica OR vs AND
✅ Melhor Tratamento de Erros: Feedback e validação aprimorados para o usuário

v1.0.0 - Funcionalidade Principal

✅ Integração completa com o MCP Memory Service
✅ Operações CRUD completas para memórias
✅ Estatísticas em tempo real e monitoramento de saúde
✅ Ferramentas de backup e otimização de banco de dados
✅ Aplicativo desktop profissional com Electron
✅ Interface de painel responsiva
✅ Compatibilidade entre plataformas (macOS, Windows, Linux)
✅ Tratamento abrangente de erros e recuperação

Características de Desempenho

Capacidade de memória: Suporta milhares de memórias com busca semântica
Velocidade de busca: 1-3 segundos para consultas semânticas (agora rastreadas com precisão)
Velocidade de recall: 1-3 segundos para consultas baseadas em tempo com métricas reais
Tamanho do banco de dados: Escala eficientemente com o armazenamento vetorial do ChromaDB
Tempo de inicialização: 10-30 segundos inicial, 2-5 segundos subsequente
Criação de backup: 2-10 segundos dependendo do tamanho do banco de dados

Feito com ❤️ para o ecossistema MCP