MCP Memory Server

Um servidor de protocolo de contexto de modelo (MCP) que fornece funcionalidades de memria persistente para conversas com IA. Este servidor permite que aplicaes de IA criem, gerenciem e consultem entidades e relacionamentos em um grafo de conhecimento persistente.

Incio Rpido

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 observaes
• Relacionamentos: Estabelea e gerencie relacionamentos entre entidades
• Busca Avanada: Procure entidades e relacionamentos por contedo
• Persistncia: Armazenamento JSON simples e confivel
• Compatvel com MCP: Funciona com qualquer cliente MCP (Claude Desktop, etc.)
• Auto-start: Configurao automtica no Windows
• VS Code Integration: Integrao completa com VS Code
• Suite de Testes: Scripts PowerShell para teste e validao
• Dashboard: Interface web para monitoramento

Instalao

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

Configurao

Claude Desktop

Adicione ao seu arquivo de configurao do Claude Desktop (claude_desktop_config.json):

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

Configurao Local

Para desenvolvimento local:

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

Configurao Automtica (Windows)

Execute o script de configurao automtica:

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

# Verificar status
.\quick-status.ps1

# Executar testes
.\run-test.ps1

Uso

Ferramentas Disponveis

O servidor MCP Memory fornece as seguintes ferramentas:

1. Criar Entidades

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

2. Adicionar Observaes

mcp_memory_add_observations({
  observations: [
    {
      entityName: "Joo Silva",
      contents: [
        "Gosta de programao em TypeScript",
        "Tem 5 anos de experincia",
      ],
    },
  ],
});

3. Criar Relacionamentos

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

4. Buscar Ns

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

5. Abrir Ns Especficos

mcp_memory_open_nodes({
  names: ["Joo Silva", "TechCorp"],
});

6. Ler Grafo Completo

mcp_memory_read_graph();

Recursos Disponveis

O servidor tambm expe recursos que podem ser acessados:

• memory://graph - Grafo de conhecimento completo
• memory://entities - Todas as entidades
• memory://relations - Todos os relacionamentos
• memory://stats - Estatsticas 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 memria SQLite
    tools/
       index.ts          # Definies de ferramentas MCP
    resources/
        index.ts          # Definies 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     # Verificao de status
    server-controller.ps1 # Controle do servidor
    auto-start.ps1       # Configurao de auto-start
 .vscode/                 # Configurao VS Code
    tasks.json           # Tarefas do projeto
    settings.json        # Configuraes
    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 Formatao

npm run lint
npm run format

Scripts de Gerenciamento

Windows PowerShell

• .\run-test.ps1 - Executa teste completo de funcionalidades
• .\test-mcp-direct.ps1 - Testa comunicao direta com o servidor
• .\quick-status.ps1 - Verifica status do servidor e dados
• .\server-controller.ps1 - Inicia/para o servidor
• .\auto-start.ps1 - Configura inicializao automtica
• .\test-persistence.ps1 - Monitora persistncia 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 Informaes 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 Informaes

// Buscar por termo especfico
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 implementaes:

Servidor Principal (simple-index.ts)

• JSON: Armazenamento simples e confivel em memory.json
• TypeScript SDK: Implementao do protocolo MCP
• Sincronizao: Operaes sncronas de leitura/escrita
• Simplicidade: Cdigo minimalista e fcil debugging

Servidor Avanado (index.ts)

• SQLite: Para armazenamento mais robusto
• Better SQLite3: Operaes de banco performticas
• UUID: Identificadores nicos
• Zod: Validao de esquemas

Tecnologias Utilizadas

• Node.js: Runtime JavaScript
• TypeScript: Linguagem de programao
• MCP SDK: Protocolo de contexto de modelo
• PowerShell: Scripts de automao Windows
• VS Code: Integrao completa de desenvolvimento

Contribuio

1. Faa um fork do projeto
2. Crie uma branch para sua feature (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanas (git commit -am 'Adicionar nova funcionalidade')
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

Licena

Este projeto est licenciado sob a Licena MIT - veja o arquivo LICENSE para detalhes.

Suporte

Para questes e suporte:

1. Abra uma issue no GitHub
2. Consulte a documentao do MCP em modelcontextprotocol.io
3. Participe das discusses da comunidade MCP

Status Atual

Implementado

• Servidor MCP funcional com persistncia JSON
• Suite completa de testes PowerShell
• Auto-start no Windows
• Integrao total com VS Code
• Scripts de gerenciamento e monitoramento
• Dashboard de status HTML
• Migrao do servidor oficial MCP
• Verificao de persistncia em tempo real

Testado e Validado

• Criao e leitura de entidades
• Relacionamentos entre entidades
• Persistncia em memory.json
• Carregamento automtico na inicializao
• Integrao com Claude Desktop

Roadmap Futuro

• Interface web para visualizao do grafo
• Suporte para importao/exportao de dados
• Integrao com outros formatos de dados
• Mtricas e analytics avanadas
• Backup automtico e recuperao
• Suporte para mltiplos bancos de dados
• API REST para acesso externo
• Clustering e replicao