MCP Memory Server

Um servidor de protocolo de contexto de modelo (MCP) que fornece funcionalidades de memória persistente para conversas com IA. Este servidor permite que aplicações de IA criem, gerenciem e consultem entidades e relacionamentos em um grafo de conhecimento persistente.

🚀 Início Rápido

1. Clone e Configure

git clone https://github.com/jessefreitas/mcp_memory.git
cd mcp_memory
npm install
npm run build

2. Inicie o Servidor

# Configurar auto-start (Windows)
.\auto-start.ps1

# OU iniciar manualmente
.\server-controller.ps1

3. Teste a Funcionalidade

# Executar teste completo
.\run-test.ps1

# Verificar status
.\quick-status.ps1

4. Configure Claude Desktop

Adicione ao claude_desktop_config.json:

{
  "mcpServers": {
    "mcp_memory": {
      "command": "node",
      "args": ["./build/simple-index.js"],
      "cwd": "c:\\vscode\\mcp_memory"
    }
  }
}

5. Teste no Claude Desktop

Use o comando: mcp_memory_read_graph

Funcionalidades

📊 Gerenciamento de Entidades: Crie, atualize e exclua entidades com observações
🔗 Relacionamentos: Estabeleça e gerencie relacionamentos entre entidades
🔍 Busca Avançada: Procure entidades e relacionamentos por conteúdo
💾 Persistência: Armazenamento JSON simples e confiável
🎯 Compatível com MCP: Funciona com qualquer cliente MCP (Claude Desktop, etc.)
🚀 Auto-start: Configuração automática no Windows
🔧 VS Code Integration: Integração completa com VS Code
🧪 Suite de Testes: Scripts PowerShell para teste e validação
📊 Dashboard: Interface web para monitoramento

Instalação

Via npm (Recomendado)

npm install -g mcp-memory-server

Desenvolvimento Local

git clone <repository-url>
cd mcp_memory
npm install
npm install typescript --save-dev
npm run build

Configuração

Claude Desktop

Adicione ao seu arquivo de configuração do Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "mcp-memory-server"],
      "env": {
        "MCP_MEMORY_DB_PATH": "./memory.db"
      }
    }
  }
}

Configuração Local

Para desenvolvimento local:

{
  "mcpServers": {
    "mcp_memory": {
      "command": "node",
      "args": ["./build/simple-index.js"],
      "cwd": "c:\\vscode\\mcp_memory"
    }
  }
}

Configuração Automática (Windows)

Execute o script de configuração automática:

# Configurar auto-start
.\auto-start.ps1

# Verificar status
.\quick-status.ps1

# Executar testes
.\run-test.ps1

Uso

Ferramentas Disponíveis

O servidor MCP Memory fornece as seguintes ferramentas:

1. Criar Entidades

mcp_memory_create_entities({
  entities: [
    {
      name: "João Silva",
      entityType: "pessoa",
      observations: [
        "Trabalha como engenheiro de software",
        "Mora em São Paulo",
      ],
    },
  ],
});

2. Adicionar Observações

mcp_memory_add_observations({
  observations: [
    {
      entityName: "João Silva",
      contents: [
        "Gosta de programação em TypeScript",
        "Tem 5 anos de experiência",
      ],
    },
  ],
});

3. Criar Relacionamentos

mcp_memory_create_relations({
  relations: [
    {
      from: "João Silva",
      to: "TechCorp",
      relationType: "trabalha_para",
    },
  ],
});

4. Buscar Nós

mcp_memory_search_nodes({
  query: "engenheiro",
});

5. Abrir Nós Específicos

mcp_memory_open_nodes({
  names: ["João Silva", "TechCorp"],
});

6. Ler Grafo Completo

mcp_memory_read_graph();

Recursos Disponíveis

O servidor também expõe recursos que podem ser acessados:

memory://graph - Grafo de conhecimento completo
memory://entities - Todas as entidades
memory://relations - Todos os relacionamentos
memory://stats - Estatísticas do grafo

Estrutura do Projeto

mcp_memory/
├── src/
│   ├── index.ts              # Servidor MCP original (SQLite)
│   ├── simple-index.ts       # Servidor MCP simplificado (JSON) ⭐
│   ├── memory/
│   │   └── MemoryManager.ts  # Gerenciador de memória SQLite
│   ├── tools/
│   │   └── index.ts          # Definições de ferramentas MCP
│   └── resources/
│       └── index.ts          # Definições de recursos MCP
├── scripts PowerShell/       # Scripts de gerenciamento
│   ├── run-test.ps1         # Teste de funcionalidades
│   ├── test-mcp-direct.ps1  # Teste direto do servidor
│   ├── quick-status.ps1     # Verificação de status
│   ├── server-controller.ps1 # Controle do servidor
│   └── auto-start.ps1       # Configuração de auto-start
├── .vscode/                 # Configuração VS Code
│   ├── tasks.json           # Tarefas do projeto
│   ├── settings.json        # Configurações
│   └── keybindings.json     # Atalhos
├── memory.json              # Dados persistentes
├── package.json
├── tsconfig.json
└── README.md

Desenvolvimento

Executar em Modo de Desenvolvimento

npm run dev

Construir o Projeto

npm run build

Executar Testes

npm test

Linting e Formatação

npm run lint
npm run format

Scripts de Gerenciamento

Windows PowerShell

.\run-test.ps1 - Executa teste completo de funcionalidades
.\test-mcp-direct.ps1 - Testa comunicação direta com o servidor
.\quick-status.ps1 - Verifica status do servidor e dados
.\server-controller.ps1 - Inicia/para o servidor
.\auto-start.ps1 - Configura inicialização automática
.\test-persistence.ps1 - Monitora persistência em tempo real

VS Code

Ctrl+Shift+P → "MCP: Start Server" - Iniciar servidor
Ctrl+Shift+P → "MCP: Test Memory" - Executar testes
Ctrl+Shift+P → "MCP: Check Status" - Verificar status
F5 - Executar em modo debug

Exemplos de Uso

Exemplo 1: Gerenciar Informações de Contato

// Criar uma pessoa
await mcp_memory_create_entities({
  entities: [
    {
      name: "Ana Costa",
      entityType: "pessoa",
      observations: ["Email: ana@example.com", "Telefone: (11) 99999-9999"],
    },
  ],
});

// Criar uma empresa
await mcp_memory_create_entities({
  entities: [
    {
      name: "Startup XYZ",
      entityType: "empresa",
      observations: ["Startup de tecnologia", "Fundada em 2023"],
    },
  ],
});

// Criar relacionamento
await mcp_memory_create_relations({
  relations: [
    {
      from: "Ana Costa",
      to: "Startup XYZ",
      relationType: "fundadora",
    },
  ],
});

Exemplo 2: Buscar Informações

// Buscar por termo específico
const resultado = await mcp_memory_search_nodes({
  query: "startup",
});

// Obter detalhes completos
const entidades = await mcp_memory_open_nodes({
  names: ["Ana Costa", "Startup XYZ"],
});

Arquitetura

O MCP Memory Server oferece duas implementações:

Servidor Principal (simple-index.ts) ⭐

JSON: Armazenamento simples e confiável em memory.json
TypeScript SDK: Implementação do protocolo MCP
Sincronização: Operações síncronas de leitura/escrita
Simplicidade: Código minimalista e fácil debugging

Servidor Avançado (index.ts)

SQLite: Para armazenamento mais robusto
Better SQLite3: Operações de banco performáticas
UUID: Identificadores únicos
Zod: Validação de esquemas

Tecnologias Utilizadas

Node.js: Runtime JavaScript
TypeScript: Linguagem de programação
MCP SDK: Protocolo de contexto de modelo
PowerShell: Scripts de automação Windows
VS Code: Integração completa de desenvolvimento

Contribuição

Faça um fork do projeto
Crie uma branch para sua feature (git checkout -b feature/nova-funcionalidade)
Commit suas mudanças (git commit -am 'Adicionar nova funcionalidade')
Push para a branch (git push origin feature/nova-funcionalidade)
Abra um Pull Request

Licença

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

Suporte

Para questões e suporte:

Abra uma issue no GitHub
Consulte a documentação do MCP em modelcontextprotocol.io
Participe das discussões da comunidade MCP

Status Atual ✅

Implementado

✅ Servidor MCP funcional com persistência JSON
✅ Suite completa de testes PowerShell
✅ Auto-start no Windows
✅ Integração total com VS Code
✅ Scripts de gerenciamento e monitoramento
✅ Dashboard de status HTML
✅ Migração do servidor oficial MCP
✅ Verificação de persistência em tempo real

Testado e Validado

✅ Criação e leitura de entidades
✅ Relacionamentos entre entidades
✅ Persistência em memory.json
✅ Carregamento automático na inicialização
✅ Integração com Claude Desktop

Roadmap Futuro

Interface web para visualização do grafo
Suporte para importação/exportação de dados
Integração com outros formatos de dados
Métricas e analytics avançadas
Backup automático e recuperação
Suporte para múltiplos bancos de dados
API REST para acesso externo
Clustering e replicação