MCP Memory Server - Extensão VS Code

Extensão VS Code/Cursor que facilita a instalação e configuração do MCP Memory Server, um servidor MCP (Model Context Protocol) que fornece memória infinita com busca semântica para assistentes de IA.

🎯 Funcionalidades

✅ Download automático do JAR do MCP Memory Server
✅ Configuração automática do MCP no Cursor/VSCode
✅ Validação de pré-requisitos (Java instalado e acessível)
✅ Comandos intuitivos para gerenciar a instalação
✅ Detecção automática de Cursor vs VSCode
✅ Interface amigável com mensagens claras
✅ Auto-update via tools MCP - Consumidores diretos podem verificar e instalar atualizações
✅ Memory Explorer — Sidebar para explorar e gerenciar a memória MCP diretamente no VS Code
✅ Suporte a multi-workspace — Seletor de workspace com reconexão automática
✅ Busca semântica com filtros — Busca por metadata com filtros dinâmicos e resultados enriquecidos
✅ Manutenção integrada — Remoção de duplicatas e limpeza de documentos antigos
✅ Config UI — Painel "User Info" para configurar nome, tag e backend de storage
✅ Quick Notes — Criação rápida de notas com metadata automática
✅ Server Status — Status bar e banner com estado do servidor em tempo real

🔍 Memory Explorer

A partir da v1.2.0, a extensão inclui o Memory Explorer — um painel no sidebar que permite explorar e gerenciar toda a memória MCP sem sair do editor.

Abas Disponíveis

Aba	Descrição
Visão Geral	Dashboard com estatísticas (documentos, chunks, tamanho), documentos recentes e info do projeto
Busca	Busca semântica com filtros dinâmicos por metadata (type, tags, project_id, etc.)
Regras	Visualização das regras comportamentais ativas no servidor
Manutenção	Remoção de duplicatas e limpeza de documentos por data com confirmação
Notas	Criação rápida de notas com save/edit/delete e injeção automática de metadata
Status	Versão do servidor, verificação de atualizações e caminho do workspace

Funcionalidades da Busca

Filtros dinâmicos: As chaves de metadata são carregadas diretamente do banco de dados
Resultados enriquecidos: Cada resultado mostra score de relevância e badges de metadata
Abrir no Editor: Documentos podem ser abertos como Markdown com frontmatter de metadata

Server Status e User Info

Painel "User Info": permite configurar nome, tag adicional e selecionar backend de storage com cenários PostgreSQL (Docker, Rede, Cloud)
Server Status Banner: banner no topo do Explorer mostrando estado do servidor (🟢 online / 🟡 iniciando / ⚪ offline) com botão para iniciar/reiniciar
Status Bar: ícone na barra de status com cor dinâmica indicando estado do servidor (verde=running, amarelo=starting, cinza=stopped)

Multi-Workspace

Quando múltiplos projetos estão abertos, o Memory Explorer exibe um seletor de workspace no topo. Ao trocar de workspace, o cliente MCP reconecta automaticamente ao banco correto.

📋 Requisitos

VS Code 1.80.0 ou superior, ou Cursor
Java 21 ou superior instalado e no PATH (ou em locais padrão do sistema)
Conexão com internet (para download inicial do JAR)

🚀 Instalação

Via Marketplace (Recomendado)

Abra o VS Code ou Cursor
Vá para a aba de Extensões (Ctrl+Shift+X ou Cmd+Shift+X)
Pesquise por "MCP Memory Server"
Clique em Instalar

Via VSIX (Manual)

Baixe o arquivo .vsix da página de releases
No VS Code/Cursor, vá em View → Command Palette (Ctrl+Shift+P ou Cmd+Shift+P)
Digite "Install from VSIX..."
Selecione o arquivo .vsix baixado

📖 Como Usar

Primeira Configuração

Após instalar a extensão, o comportamento padrão é:

autoDownload habilitado por padrão (mcpMemoryServer.autoDownload = true):
- Ao ativar o VS Code/Cursor, a extensão verifica se o JAR existe
- Se não existir ou houver nova versão, baixa automaticamente a última versão do JAR com validação SHA256
- Após o download, pode pedir para configurar o MCP automaticamente

Se preferir controlar manualmente, você pode desativar autoDownload nas configurações.

Opção 1: Fluxo Automático (Recomendado)

Deixe mcpMemoryServer.autoDownload habilitado (padrão)
Quando o JAR for baixado/atualizado, a extensão poderá perguntar se deseja configurar automaticamente
Clique em "Configurar Agora" para que a extensão ajuste o MCP no VS Code/Cursor

Opção 2: Configuração Manual

Execute o comando "MCP Memory Server: Baixar JAR" (se quiser controlar o momento do download)
Execute o comando "MCP Memory Server: Configurar"
Confirme a configuração quando solicitado

Comandos Disponíveis

A extensão fornece os seguintes comandos (acessíveis via Command Palette - Ctrl+Shift+P):

MCP Memory Server: Baixar JAR - Baixa o JAR do servidor MCP do GitHub
MCP Memory Server: Configurar - Configura o MCP (no .vscode/settings.json no VS Code ou settings.json global no Cursor)
MCP Memory Server: Validar Instalação - Valida Java, JAR e configuração
MCP Memory Server: Abrir Configurações - Abre as configurações da extensão
MCP Memory Server: Atualizar Explorer - Atualiza os dados do Memory Explorer

Validação

Para verificar se tudo está configurado corretamente:

Execute o comando "MCP Memory Server: Validar Instalação"
A extensão mostrará o status de:
- ✅ Java instalado e versão
- ✅ JAR encontrado
- ✅ Configuração do MCP correta
- ✅ Editor detectado (Cursor ou VSCode)

🐘 Backend PostgreSQL

O MCP Memory Server suporta PostgreSQL + pgvector como backend alternativo ao SQLite, ideal para equipes, ambientes compartilhados ou datasets maiores.

Cenários Suportados

Cenário	Quando usar	Configuração
Docker Local	Desenvolvimento, testes	`host: localhost`, `port: 5432`
PostgreSQL em Rede	Servidor on-premises, equipe compartilhada	`host: <ip-do-servidor>`, `port: 5432`
AWS RDS / Cloud	Produção, alta disponibilidade	`host: <endpoint-rds>`, `port: 5432`, `ssl: true`

Quick Start com Docker

# Na raiz do projeto (onde está o docker-compose.yml)
docker compose up -d

# Verificar
docker compose ps

Em seguida, configure a extensão:

Abra Settings (Ctrl+,)
Busque mcpMemoryServer.storageBackend
Altere de sqlite para postgresql
Preencha postgresql.database, postgresql.user, postgresql.password
Execute o comando MCP Memory: Configurar (Ctrl+Shift+P)

Nota: O PostgreSQL precisa ter a extensão pgvector instalada. A imagem Docker inclusa já vem com pgvector pré-configurado.

Para instruções detalhadas, consulte o Guia de Setup PostgreSQL.

⚙️ Configurações

A extensão oferece as seguintes configurações (acessíveis em Settings):

mcpMemoryServer.path - Caminho para o JAR (se vazio, será baixado automaticamente)
mcpMemoryServer.autoConfigure - Configurar automaticamente após download (padrão: true)
mcpMemoryServer.autoDownload - Baixar automaticamente a última versão do JAR quando a extensão for ativada (padrão: true)
mcpMemoryServer.httpPort - Porta HTTP do servidor MCP para comunicação via REST API (padrão: 3000)
mcpMemoryServer.javaPath - Caminho customizado do Java (se vazio, faz scan automático procurando Java 21+ no PATH e locais padrão)
mcpMemoryServer.jarUrl - URL customizada para download do JAR (se vazio, busca automaticamente a última versão no GitHub via API)
mcpMemoryServer.postgresql.host - Host do servidor PostgreSQL (padrão: localhost)
mcpMemoryServer.postgresql.port - Porta do PostgreSQL (padrão: 5432)
mcpMemoryServer.postgresql.database - Nome do banco de dados (padrão: mcp_memory)
mcpMemoryServer.postgresql.user - Usuário do PostgreSQL (padrão: mcp_user)
mcpMemoryServer.postgresql.password - Senha do PostgreSQL
mcpMemoryServer.postgresql.ssl - Habilitar SSL na conexão (padrão: false)
mcpMemoryServer.postgresql.tsLanguage - Configuração de linguagem para busca textual no PostgreSQL
mcpMemoryServer.storageBackend - Backend de storage: sqlite (padrão) ou postgresql
mcpMemoryServer.user.fullName - Nome completo do usuário, incluído como metadata nos documentos
mcpMemoryServer.user.additionalTag - Tag adicional (ex: team-backend), incluída como metadata
mcpMemoryServer.autoStart - Iniciar servidor automaticamente ao abrir o VS Code (padrão: false)
mcpMemoryServer.passiveCapture.enabled - Captura automática de saves de arquivo (padrão: false)
mcpMemoryServer.passiveCapture.excludePatterns - Glob patterns para excluir da captura passiva

🔧 Troubleshooting

Java não encontrado

Problema: A extensão mostra que Java não está instalado.

Solução:

Instale Java 21 ou superior
Certifique-se de que Java está no PATH do sistema ou em locais padrão (a extensão faz scan automático)
Reinicie o VS Code/Cursor
Execute novamente a validação

Links para download:

JAR não encontrado ou erro 404 no download

Problema: A extensão não encontra o JAR ou o download falha com erro 404.

Nota: A extensão busca automaticamente a última versão disponível no GitHub via API. Se você quiser usar uma versão específica ou um JAR local, configure a URL manualmente nas configurações.

Solução:

Opção 1: Usar JAR Local (Recomendado se você já tem o JAR)

Compile o projeto: mvn clean package
O JAR estará em target/mcp-memory-server-1.0.0.jar
Na extensão, quando aparecer o erro de download, clique em "Usar JAR Local"
Selecione o arquivo target/mcp-memory-server-1.0.0.jar
Ou configure manualmente em Settings → mcpMemoryServer.path

Opção 2: Configurar Caminho Manualmente

Abra Settings (Ctrl+, ou Cmd+,)
Procure por mcpMemoryServer.path
Configure o caminho completo para o JAR (ex: C:/caminho/para/target/mcp-memory-server-1.0.0.jar)

Opção 3: Criar Release no GitHub Se você quiser usar o download automático, crie um release no GitHub com o JAR anexado.

Configuração não aplicada

Problema: A configuração do MCP não está funcionando.

Solução:

Execute o comando "MCP Memory Server: Validar Instalação"
Se a configuração estiver incorreta, execute "MCP Memory Server: Configurar"
Reinicie o VS Code/Cursor após configurar (importante!)

Categoria de tools desabilitada via `--tools`

Problema: O painel Admin & Explorer mostra a mensagem "Categoria de tools desabilitada via --tools (rota /…). Edite o mcp.json ou contate o operador."

Causa: O servidor foi iniciado com --tools=<lista> omitindo a categoria que o painel está consultando. As categorias atualmente gateadas via REST são core, maintenance, rules e project (as rotas de /server/* ficam sempre ativas).

Solução:

Localize o mcp.json (~/.cursor/mcp.json ou .vscode/mcp.json).
No bloco args, remova ou ajuste o --tools=<lista> para incluir a categoria necessária — ou use --tools=all (default) para liberar tudo.
Reinicie o servidor (MCP Memory: Restart Server).

Diferenças entre Cursor e VSCode

A extensão detecta automaticamente qual editor está sendo usado:

Cursor: Configuração global em ~/.cursor/mcp.json usando mcpServers (funciona para todos os projetos)
VSCode: Configuração por workspace:
- Versões >= 1.102: .vscode/mcp.json usando mcpServers (formato novo)
- Versões < 1.102: .vscode/settings.json usando mcp.servers (formato antigo)

Importante: No VS Code, cada projeto precisa ser configurado individualmente. Quando você abrir um novo projeto, a extensão detectará se há configuração e poderá pedir para configurar novamente.

📝 O que a Extensão Faz

A extensão automatiza os seguintes passos que normalmente seriam feitos manualmente:

Download do JAR - Busca automaticamente a última versão no GitHub via API e baixa o JAR
Validação de Java - Verifica se Java está instalado e na versão correta (21+)
Scan Automático de Java - Se não configurado, procura automaticamente Java 21+ no PATH e locais padrão do sistema
Configuração do MCP - Adiciona a configuração no local apropriado:
- Cursor: No ~/.cursor/mcp.json usando mcpServers (funciona para todos os projetos)
- VS Code:
  - Versões >= 1.102: No .vscode/mcp.json usando mcpServers (formato novo)
  - Versões < 1.102: No .vscode/settings.json usando mcp.servers (formato antigo)
Exemplo de configuração (VS Code >= 1.102 - .vscode/mcp.json):
```
{
  "mcpServers": {
    "memory": {
      "command": "java",
      "args": [
        "-jar",
        "C:/caminho/para/mcp-memory-server.jar",
        "--workspace",
        "${workspaceFolder}"
      ]
    }
  }
}
```
Exemplo de configuração (VS Code < 1.102 - .vscode/settings.json):
```
{
  "mcp.servers": {
    "memory": {
      "command": "java",
      "args": [
        "-jar",
        "C:/caminho/para/mcp-memory-server.jar",
        "--workspace",
        "${workspaceFolder}"
      ]
    }
  }
}
```
Exemplo de configuração (Cursor - ~/.cursor/mcp.json):
```
{
  "mcpServers": {
    "memory": {
      "command": "java",
      "args": [
        "-jar",
        "C:/caminho/para/mcp-memory-server.jar",
        "--workspace",
        "${workspaceFolder}"
      ]
    }
  }
}
```
Nota importante: No Cursor, a variável ${workspaceFolder} é expandida automaticamente mesmo em configuração global, diferentemente do VS Code que só expande em configuração de workspace.

� Auto-Update (Consumidores Diretos)

Para consumidores diretos do MCP Memory Server (OpenClaw, clientes MCP genéricos), o servidor oferece ferramentas de auto-atualização:

Tools Disponíveis

Tool	Descrição
`check_update`	Verifica se há nova versão disponível no GitHub Releases
`update`	Baixa e instala a nova versão automaticamente

Exemplo de Uso

// Verificar atualização
{ "name": "check_update" }
// Resposta: { "hasUpdate": true, "currentVersion": "1.0.2", "latestVersion": "1.0.3" }

// Executar atualização
{ "name": "update" }
// Resposta: { "success": true, "message": "Update to 1.0.3 in progress. Server will restart." }

Comportamento

check_update - Consulta a API do GitHub para verificar a versão mais recente
update - Se houver atualização:
- Faz backup do JAR atual (.backup)
- Baixa o novo JAR com validação SHA256
- Cria marker file .mcp-memory-update para reconexão do cliente
- Reinicia o servidor com exit code 42

Reconexão Automática

Clientes compatíveis (como OpenClaw) detectam o marker file e reconectam automaticamente após a atualização.

🚀 Releasing

A extensão usa release-it com @release-it/conventional-changelog para automatizar bump de versão, geração de CHANGELOG e criação de tag.

Workflow

Commits seguem Conventional Commits:
- feat(extension): ... → bump minor
- fix(extension): ... → bump patch
- feat(extension)!: ... ou body com BREAKING CHANGE: → bump major

Quando pronto pra release, na pasta mcp-memory-server-extension/:

# Dry-run primeiro (não muda nada)
npm run release:dry

# Release real (bump + CHANGELOG + commit + tag + push)
npm run release

release-it:
- calcula novo version baseado nos commits desde a última tag
- atualiza package.json + CHANGELOG.md
- cria commit chore(extension): release vX.Y.Z
- cria tag ext-v X.Y.Z e faz push
O push da tag ext-v* dispara o workflow .github/workflows/publish-extension.yml que publica no VS Code Marketplace e Open VSX automaticamente.

Pré-requisitos

Working tree limpo na branch main
Secrets configurados no repo: VSCE_PAT (Marketplace) e OVSX_PAT (Open VSX)

Migração para 2.x (BREAKING)

A config mcpMemoryServer.postgresql.password foi removida do schema na v2.0.0. A senha PostgreSQL agora vive exclusivamente no VS Code SecretStorage (criptografada pelo keychain do SO). A migração é automática no primeiro start — valores legados em settings.json são movidos para SecretStorage. Se você ainda tiver a entrada antiga em settings.json, o VS Code mostrará "Unknown configuration setting": é seguro deletá-la manualmente; o valor já foi migrado.

�🔗 Links Úteis

📄 Licença

MIT License - Veja o arquivo LICENSE para detalhes.

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, abra uma issue ou pull request no repositório de releases.

📧 Suporte

Se você encontrar problemas ou tiver dúvidas:

Verifique a seção Troubleshooting
Abra uma issue no GitHub
Consulte a documentação completa

Desenvolvido com ❤️ para facilitar o uso do MCP Memory Server

MCP Memory Server

Allan Santos

MCP Memory Server - Extensão VS Code

🎯 Funcionalidades

🔍 Memory Explorer

Abas Disponíveis

Funcionalidades da Busca

Server Status e User Info

Multi-Workspace

📋 Requisitos

🚀 Instalação

Via Marketplace (Recomendado)

Via VSIX (Manual)

📖 Como Usar

Primeira Configuração

Opção 1: Fluxo Automático (Recomendado)

Opção 2: Configuração Manual

Comandos Disponíveis

Validação

🐘 Backend PostgreSQL

Cenários Suportados

Quick Start com Docker

⚙️ Configurações

🔧 Troubleshooting

Java não encontrado

JAR não encontrado ou erro 404 no download

Configuração não aplicada

Categoria de tools desabilitada via --tools

Diferenças entre Cursor e VSCode

📝 O que a Extensão Faz

� Auto-Update (Consumidores Diretos)

Tools Disponíveis

Exemplo de Uso

Comportamento

Reconexão Automática

🚀 Releasing

Workflow

Pré-requisitos

Migração para 2.x (BREAKING)

�🔗 Links Úteis

📄 Licença

🤝 Contribuindo

📧 Suporte

Categoria de tools desabilitada via `--tools`