MCP Memory Server - Python Implementation

Uma implementação em Python do servidor de memória MCP para armazenamento e recuperação de grafo de conhecimento, utilizando arquivos JSONL para persistência.

GitHub
1

Documentação

MCP Memory Server - Python Implementation

Um port completo em Python do servidor de memória MCP TypeScript oficial. Este servidor fornece capacidades de armazenamento e recuperação de grafo de conhecimento através do Model Context Protocol (MCP).

⚠️ Compatibilidade de Plataforma

Esta implementação foi desenvolvida e testada exclusivamente em macOS. Embora deva funcionar em outros sistemas Unix-like, nenhum teste foi realizado em Windows, Linux ou outras plataformas. O uso em outras plataformas é por sua conta e risco.

Recursos

  • Gerenciamento Completo de Grafo de Conhecimento: Armazene e gerencie entidades, relações e observações
  • Formato de Arquivo JSONL: Compatível com o formato de arquivo da versão TypeScript
  • 9 Ferramentas MCP: Paridade total de recursos com a implementação original em TypeScript
  • Capacidades de Busca: Consulte entidades por nome, tipo ou conteúdo de observações
  • Exploração de Grafo: Explore conexões e relações entre entidades
  • Configuração de Ambiente: Local de armazenamento personalizável

Configuração do Ambiente de Desenvolvimento

Pré-requisitos

  • Python 3.8 ou superior
  • macOS (plataforma testada)

Configuração do Ambiente Virtual

  1. Crie um ambiente virtual:

    python3 -m venv .venv

  2. Ative o ambiente virtual:

    source .venv/bin/activate

  3. Instale as dependências:

    pip install -r requirements.txt

  4. Desative quando terminar:

    deactivate

Instalação

  1. Clone ou baixe este repositório

  2. Configure o ambiente virtual (veja acima)

  3. Teste a instalação:

    source .venv/bin/activate
python mcp_memory_server.py

    O servidor deve iniciar e aguardar mensagens do protocolo MCP via stdin/stdout.

Configuração

Variáveis de Ambiente

  • MEMORY_FILE_PATH: Caminho para o arquivo de armazenamento de memória (padrão: ./memory.json)

Exemplo:

export MEMORY_FILE_PATH="/path/to/my/memory.json"
source .venv/bin/activate
python mcp_memory_server.py

Configuração do Cliente MCP

Claude Desktop

Adicione esta configuração às configurações do seu Claude Desktop:

{
  "mcpServers": {
    "memory": {
      "command": "python",
      "args": ["/path/to/mcp_memory_server.py"],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/memory.json"
      }
    }
  }
}

Nota: Certifique-se de ativar seu ambiente virtual antes de executar, ou use o caminho completo para o interpretador Python no seu ambiente virtual.

IDE Cursor

  1. Abra as configurações do Cursor IDE
  2. Navegue até a configuração de Servidores MCP
  3. Adicione um novo servidor com:
    • Nome: memory
    • Comando: python
    • Argumentos: ["/path/to/mcp_memory_server.py"]
    • Ambiente: {"MEMORY_FILE_PATH": "/path/to/memory.json"}

AWS Q CLI

Configure o servidor de memória nas configurações MCP do seu AWS Q CLI:

{
  "mcp_servers": {
    "memory": {
      "command": ["python", "/path/to/mcp_memory_server.py"],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/memory.json"
      }
    }
  }
}

Configuração Genérica de Cliente MCP

Para qualquer cliente MCP que suporte servidores baseados em stdio:

{
  "servers": {
    "memory": {
      "command": "python",
      "args": ["/path/to/mcp_memory_server.py"],
      "cwd": "/path/to/server/directory",
      "env": {
        "MEMORY_FILE_PATH": "/path/to/memory.json"
      }
    }
  }
}

Uso com Claude

Para aproveitar ao máximo o servidor de memória, adicione este prompt de sistema ao Claude:

Follow these steps for each interaction:

1. User Identification:
   - You should assume that you are interacting with default_user
   - If you have not identified default_user, proactively try to do so.

2. Memory Retrieval:
   - Always begin your chat by saying only "Remembering..." and retrieve all relevant information from your knowledge graph
   - Always refer to your knowledge graph as your "memory"

3. Memory
   - While conversing with the user, be attentive to any new information that falls into these categories:
     a) Basic Identity (age, gender, location, job title, education level, etc.)
     b) Behaviors (interests, habits, etc.)
     c) Preferences (communication style, preferred language, etc.)
     d) Goals (goals, targets, aspirations, etc.)
     e) Relationships (personal and professional relationships up to 3 degrees of separation)

4. Memory Update:
   - If any new information was gathered during the interaction, update your memory as follows:
     a) Create entities for recurring organizations, people, and significant events
     b) Connect them to the current entities using relations
     c) Store facts about them as observations

Ferramentas Disponíveis

O servidor fornece 9 ferramentas MCP com compatibilidade exata com a versão TypeScript:

1. create_entities

Crie novas entidades no grafo de conhecimento.

Entrada:

{
  "entities": [
    {
      "name": "John Doe",
      "entityType": "person",
      "observations": ["Software engineer", "Lives in San Francisco"]
    }
  ]
}

2. create_relations

Crie relações entre entidades.

Entrada:

{
  "relations": [
    {
      "from": "John Doe",
      "to": "Acme Corp",
      "relationType": "works_at"
    }
  ]
}

3. add_observations

Adicione novas observações a entidades existentes.

Entrada:

{
  "additions": [
    {
      "entityName": "John Doe",
      "observations": ["Enjoys hiking", "Plays guitar"]
    }
  ]
}

4. delete_entities

Exclua entidades e suas relações associadas.

Entrada:

{
  "names": ["John Doe", "Jane Smith"]
}

5. delete_relations

Exclua relações específicas.

Entrada:

{
  "relations": [
    {
      "from": "John Doe",
      "to": "Acme Corp",
      "relationType": "works_at"
    }
  ]
}

6. delete_observations

Remova observações específicas de entidades.

Entrada:

{
  "deletions": [
    {
      "entityName": "John Doe",
      "observations": ["Old observation to remove"]
    }
  ]
}

7. read_graph

Recupere o grafo de conhecimento completo.

Entrada: Nenhuma

Saída: Grafo completo com todas as entidades e relações.

8. search_nodes

Busque entidades por string de consulta.

Entrada:

{
  "query": "software engineer"
}

Saída: Entidades que correspondem à consulta e suas interconexões.

9. open_nodes

Obtenha entidades específicas e suas conexões.

Entrada:

{
  "names": ["John Doe", "Acme Corp"]
}

Saída: Entidades solicitadas, além de entidades conectadas e todas as relações relevantes.

Formato de Arquivo

O servidor usa o formato JSONL (JSON Lines) para armazenamento, com cada linha contendo uma entidade ou relação:

{"type": "entity", "name": "John Doe", "entityType": "person", "observations": ["Software engineer"]}
{"type": "relation", "from": "John Doe", "to": "Acme Corp", "relationType": "works_at"}

Este formato é totalmente compatível com a versão TypeScript, permitindo migrar arquivos de memória existentes.

Teste Direto do Servidor

Você pode testar o servidor diretamente sem um cliente MCP:

  1. Inicie o servidor:

    source .venv/bin/activate
python mcp_memory_server.py

  2. Envie mensagens do protocolo MCP via stdin. O servidor espera mensagens JSON-RPC 2.0 seguindo a especificação MCP.

Tratamento de Erros

O servidor inclui tratamento abrangente de erros para:

  • JSON malformado em arquivos de memória
  • Campos obrigatórios ausentes
  • Erros de I/O de arquivo
  • Parâmetros de ferramenta inválidos
  • Proteção contra acesso concorrente

Performance

O servidor é otimizado para:

  • Grafos com centenas de entidades
  • Busca eficiente em nomes, tipos e observações de entidades
  • I/O de arquivo rápido com uso mínimo de memória
  • Segurança de acesso concorrente

Registro de Logs

O servidor registra eventos importantes para auxiliar na depuração:

  • Inicialização e configuração do servidor
  • Operações de carregamento e salvamento do grafo
  • Condições de erro e avisos
  • Resultados da execução de ferramentas

Compatibilidade

Esta implementação Python fornece:

  • Compatibilidade funcional: Funciona com arquivos memory.json existentes da versão TypeScript
  • Compatibilidade de ferramentas: Todas as 9 ferramentas funcionam de forma idêntica à versão TypeScript
  • Compatibilidade de formato de arquivo: Pode ler/gravar o mesmo formato JSONL
  • Compatibilidade de clientes: Funciona com Claude Desktop, Cursor IDE, AWS Q CLI e outros clientes MCP

Desenvolvimento

Estrutura do Projeto

mcp-memory-server-py/
├── mcp_memory_server.py          # Main server implementation
├── requirements.txt              # Python dependencies
├── README.md                     # This documentation

Contribuindo

Ao contribuir com este projeto:

  1. Mantenha a compatibilidade com a versão TypeScript
  2. Siga as melhores práticas de Python e PEP 8
  3. Adicione tratamento abrangente de erros
  4. Atualize a documentação para quaisquer alterações
  5. Teste em macOS (plataforma principal suportada)

Licença

Esta implementação segue a mesma licença do servidor de memória MCP TypeScript original.

Suporte

Para problemas, bugs ou solicitações de recursos, consulte a documentação original do servidor de memória MCP e adapte as soluções para esta implementação Python.

Lembre-se: Esta implementação foi desenvolvida e testada apenas em macOS. O uso em outras plataformas pode exigir testes e modificações adicionais.