Cursor10x MCP

---

Visão Geral

O Sistema de Memória Cursor10x cria uma camada de memória persistente para assistentes de IA (especificamente Claude), permitindo que eles retenham e recuperem:

• Mensagens recentes e histórico de conversas
• Arquivos ativos atualmente em edição
• Marcos importantes e decisões do projeto
• Requisitos técnicos e especificações
• Sequências cronológicas de ações e eventos (episódios)
• Trechos de código e estruturas do seu repositório
• Conteúdo semanticamente semelhante com base em embeddings vetoriais
• Fragmentos de código relacionados por similaridade semântica
• Estruturas de arquivos com relações entre funções e variáveis

Este sistema de memória preenche a lacuna entre interações de IA sem estado e fluxos de desenvolvimento contínuos, permitindo uma assistência mais produtiva e consciente do contexto.

Arquitetura do Sistema

O sistema de memória é construído sobre quatro componentes principais:

1. Servidor MCP: Implementa o Model Context Protocol para registrar ferramentas e processar solicitações
2. Banco de Dados de Memória: Usa o banco de dados Turso para armazenamento persistente entre sessões
3. Subsistemas de Memória: Organiza a memória em sistemas especializados com propósitos distintos
4. Embeddings Vetoriais: Transforma texto e código em representações numéricas para busca semântica

Tipos de Memória

O sistema implementa quatro tipos complementares de memória:

1. Memória de Curto Prazo (STM)

   • Armazena mensagens recentes e arquivos ativos
   • Fornece contexto imediato para interações atuais
   • Prioriza automaticamente por recência e importância

2. Memória de Longo Prazo (LTM)

   • Armazena informações permanentes do projeto, como marcos e decisões
   • Mantém o contexto arquitetural e de design
   • Preserva informações de alta importância indefinidamente

3. Memória Episódica

   • Registra sequências cronológicas de eventos
   • Mantém relações causais entre ações
   • Fornece contexto temporal para o histórico do projeto

4. Memória Semântica

   • Armazena embeddings vetoriais de mensagens, arquivos e trechos de código
   • Permite recuperação de conteúdo com base em similaridade semântica
   • Indexa automaticamente estruturas de código para recuperação contextual
   • Rastreia relações entre componentes de código
   • Fornece busca por similaridade em todo o repositório

Recursos

• Contexto Persistente: Mantém o contexto de conversa e projeto entre múltiplas sessões
• Armazenamento Baseado em Importância: Prioriza informações com base em níveis de importância configuráveis
• Memória Multidimensional: Combina sistemas de memória de curto prazo, longo prazo, episódica e semântica
• Recuperação Abrangente: Fornece contexto unificado de todos os subsistemas de memória
• Monitoramento de Saúde: Inclui diagnóstico integrado e relatórios de status
• Geração de Banner: Cria banners informativos de contexto para início de conversas
• Persistência em Banco de Dados: Armazena todos os dados de memória no banco de dados Turso com criação automática de esquema
• Embeddings Vetoriais: Cria representações numéricas de texto e código para busca por similaridade
• Armazenamento Vetorial Avançado: Utiliza F32_BLOB e funções vetoriais do Turso para armazenamento eficiente de embeddings
• Busca ANN: Suporta busca por Vizinhos Mais Próximos Aproximados para correspondência rápida por similaridade
• Indexação de Código: Detecta e indexa automaticamente estruturas de código (funções, classes, variáveis)
• Busca Semântica: Encontra conteúdo relacionado com base no significado, não em correspondência exata de texto
• Pontuação de Relevância: Classifica itens de contexto por relevância à consulta atual
• Detecção de Estrutura de Código: Identifica e extrai componentes de código em múltiplas linguagens
• Geração Automática de Embeddings: Cria automaticamente embeddings vetoriais para conteúdo indexado
• Recuperação por Referência Cruzada: Encontra código relacionado em diferentes arquivos e componentes

Instalação

Pré-requisitos

• Node.js 18 ou superior
• Gerenciador de pacotes npm ou yarn
• Conta no banco de dados Turso

Etapas de Configuração

1. Configure o Banco de Dados Turso:

# Install Turso CLI
curl -sSfL https://get.turso.tech/install.sh | bash

# Login to Turso
turso auth login

# Create a database
turso db create cursor10x-mcp

# Get database URL and token
turso db show cursor10x-mcp --url
turso db tokens create cursor10x-mcp

Ou você pode visitar Turso, criar uma conta e prosseguir para criar o banco de dados e obter as credenciais adequadas. O plano gratuito será mais que suficiente para a memória do seu projeto.

2. Configure o Cursor MCP:

Atualize o .cursor/mcp.json no diretório do seu projeto com a URL do banco de dados e o token de autenticação do Turso:

{
  "mcpServers": {
    "cursor10x-mcp": {
      "command": "npx",
      "args": ["cursor10x-mcp"],
      "enabled": true,
      "env": {
        "TURSO_DATABASE_URL": "your-turso-database-url",
        "TURSO_AUTH_TOKEN": "your-turso-auth-token"
      }
    }
  }
}

Documentação das Ferramentas

Ferramentas do Sistema

mcp_cursor10x_initConversation

Inicializa uma conversa armazenando a mensagem do usuário, gerando um banner e recuperando o contexto em uma única operação. Esta ferramenta unificada substitui a necessidade de chamadas separadas de generateBanner, getComprehensiveContext e storeUserMessage no início de cada conversa.

Parâmetros:

• content (string, obrigatório): Conteúdo da mensagem do usuário
• importance (string, opcional): Nível de importância ("low", "medium", "high", "critical"), padrão "low"
• metadata (objeto, opcional): Metadados adicionais para a mensagem

Retorna:

• Objeto com duas seções:
  • display: Contém o banner a ser exibido ao usuário
  • internal: Contém o contexto abrangente para uso do agente

Exemplo:

// Initialize a conversation
const result = await mcp_cursor10x_initConversation({
  content: "I need to implement a login system for my app",
  importance: "medium",
});
// Result: {
//   "status": "ok",
//   "display": {
//     "banner": {
//       "status": "ok",
//       "memory_system": "active",
//       "mode": "turso",
//       "message_count": 42,
//       "active_files_count": 3,
//       "last_accessed": "4/15/2023, 2:30:45 PM"
//     }
//   },
//   "internal": {
//     "context": { ... comprehensive context data ... },
//     "messageStored": true,
//     "timestamp": 1681567845123
//   }
// }

mcp_cursor10x_endConversation

Encerra uma conversa combinando múltiplas operações em uma única chamada: armazenando a mensagem final do assistente, registrando um marco do que foi realizado e registrando um episódio na memória episódica. Esta ferramenta unificada substitui a necessidade de chamadas separadas de storeAssistantMessage, storeMilestone e recordEpisode no final de cada conversa.

Parâmetros:

• content (string, obrigatório): Conteúdo da mensagem final do assistente
• milestone_title (string, obrigatório): Título do marco a ser registrado
• milestone_description (string, obrigatório): Descrição do que foi realizado
• importance (string, opcional): Nível de importância ("low", "medium", "high", "critical"), padrão "medium"
• metadata (objeto, opcional): Metadados adicionais para todos os registros

Retorna:

• Objeto com status e resultados de cada operação

Exemplo:

// End a conversation with finalization steps
const result = await mcp_cursor10x_endConversation({
  content:
    "I've implemented the authentication system with JWT tokens as requested",
  milestone_title: "Authentication Implementation",
  milestone_description:
    "Implemented secure JWT-based authentication with refresh tokens",
  importance: "high",
});
// Result: {
//   "status": "ok",
//   "results": {
//     "assistantMessage": {
//       "stored": true,
//       "timestamp": 1681568500123
//     },
//     "milestone": {
//       "title": "Authentication Implementation",
//       "stored": true,
//       "timestamp": 1681568500123
//     },
//     "episode": {
//       "action": "completion",
//       "stored": true,
//       "timestamp": 1681568500123
//     }
//   }
// }

mcp_cursor10x_checkHealth

Verifica a saúde do sistema de memória e sua conexão com o banco de dados.

Parâmetros:

• Nenhum obrigatório

Retorna:

• Objeto com status de saúde e diagnósticos

Exemplo:

// Check memory system health
const health = await mcp_cursor10x_checkHealth({});
// Result: {
//   "status": "ok",
//   "mode": "turso",
//   "message_count": 42,
//   "active_files_count": 3,
//   "current_directory": "/users/project",
//   "timestamp": "2023-04-15T14:30:45.123Z"
// }

mcp_cursor10x_getMemoryStats

Recupera estatísticas detalhadas sobre o sistema de memória.

Parâmetros:

• Nenhum obrigatório

Retorna:

• Objeto com estatísticas abrangentes de memória

Exemplo:

// Get memory statistics
const stats = await mcp_cursor10x_getMemoryStats({});
// Result: {
//   "status": "ok",
//   "stats": {
//     "message_count": 42,
//     "active_file_count": 3,
//     "milestone_count": 7,
//     "decision_count": 12,
//     "requirement_count": 15,
//     "episode_count": 87,
//     "oldest_memory": "2023-03-10T09:15:30.284Z",
//     "newest_memory": "2023-04-15T14:30:45.123Z"
//   }
// }

mcp_cursor10x_getComprehensiveContext

Recupera um contexto unificado de todos os subsistemas de memória, combinando memória de curto prazo, longo prazo e episódica.

Parâmetros:

• Nenhum obrigatório

Retorna:

• Objeto com contexto consolidado de todos os sistemas de memória

Exemplo:

// Get comprehensive context
const context = await mcp_cursor10x_getComprehensiveContext({});
// Result: {
//   "status": "ok",
//   "context": {
//     "shortTerm": {
//       "recentMessages": [...],
//       "activeFiles": [...]
//     },
//     "longTerm": {
//       "milestones": [...],
//       "decisions": [...],
//       "requirements": [...]
//     },
//     "episodic": {
//       "recentEpisodes": [...]
//     },
//     "system": {
//       "healthy": true,
//       "timestamp": "2023-04-15T14:30:45.123Z"
//     }
//   }
// }

Ferramentas de Memória de Curto Prazo

mcp_cursor10x_storeUserMessage

Armazena uma mensagem do usuário no sistema de memória de curto prazo.

Parâmetros:

• content (string, obrigatório): Conteúdo da mensagem
• importance (string, opcional): Nível de importância ("low", "medium", "high", "critical"), padrão "low"
• metadata (objeto, opcional): Metadados adicionais para a mensagem

Retorna:

• Objeto com status e timestamp

Exemplo:

// Store a user message
const result = await mcp_cursor10x_storeUserMessage({
  content: "We need to implement authentication for our API",
  importance: "high",
  metadata: {
    topic: "authentication",
    priority: 1,
  },
});
// Result: {
//   "status": "ok",
//   "timestamp": 1681567845123
// }

mcp_cursor10x_storeAssistantMessage

Armazena uma mensagem do assistente no sistema de memória de curto prazo.

Parâmetros:

• content (string, obrigatório): Conteúdo da mensagem
• importance (string, opcional): Nível de importância ("low", "medium", "high", "critical"), padrão "low"
• metadata (objeto, opcional): Metadados adicionais para a mensagem

Retorna:

• Objeto com status e timestamp

Exemplo:

// Store an assistant message
const result = await mcp_cursor10x_storeAssistantMessage({
  content: "I recommend implementing JWT authentication with refresh tokens",
  importance: "medium",
  metadata: {
    topic: "authentication",
    contains_recommendation: true,
  },
});
// Result: {
//   "status": "ok",
//   "timestamp": 1681567870456
// }

mcp_cursor10x_trackActiveFile

Rastreia um arquivo ativo que está sendo acessado ou modificado pelo usuário.

Parâmetros:

• filename (string, obrigatório): Caminho do arquivo sendo rastreado
• action (string, obrigatório): Ação executada no arquivo (open, edit, close, etc.)
• metadata (objeto, opcional): Metadados adicionais para o evento de rastreamento

Retorna:

• Objeto com status, nome do arquivo, ação e timestamp

Exemplo:

// Track an active file
const result = await mcp_cursor10x_trackActiveFile({
  filename: "src/auth/jwt.js",
  action: "edit",
  metadata: {
    changes: "Added refresh token functionality",
  },
});
// Result: {
//   "status": "ok",
//   "filename": "src/auth/jwt.js",
//   "action": "edit",
//   "timestamp": 1681567900789
// }

mcp_cursor10x_getRecentMessages

Recupera mensagens recentes da memória de curto prazo.

Parâmetros:

• limit (número, opcional): Número máximo de mensagens a recuperar, padrão 10
• importance (string, opcional): Filtrar por nível de importância

Retorna:

• Objeto com status e array de mensagens

Exemplo:

// Get recent high importance messages
const messages = await mcp_cursor10x_getRecentMessages({
  limit: 5,
  importance: "high",
});
// Result: {
//   "status": "ok",
//   "messages": [
//     {
//       "id": 42,
//       "role": "user",
//       "content": "We need to implement authentication for our API",
//       "created_at": "2023-04-15T14:30:45.123Z",
//       "importance": "high",
//       "metadata": {"topic": "authentication", "priority": 1}
//     },
//     ...
//   ]
// }

mcp_cursor10x_getActiveFiles

Recupera arquivos ativos da memória de curto prazo.

Parâmetros:

• limit (número, opcional): Número máximo de arquivos a recuperar, padrão 10

Retorna:

• Objeto com status e array de arquivos ativos

Exemplo:

// Get recent active files
const files = await mcp_cursor10x_getActiveFiles({
  limit: 3,
});
// Result: {
//   "status": "ok",
//   "files": [
//     {
//       "id": 15,
//       "filename": "src/auth/jwt.js",
//       "last_accessed": "2023-04-15T14:30:45.123Z",
//       "metadata": {"changes": "Added refresh token functionality"}
//     },
//     ...
//   ]
// }

Ferramentas de Memória de Longo Prazo

mcp_cursor10x_storeMilestone

Armazena um marco do projeto na memória de longo prazo.

Parâmetros:

• title (string, obrigatório): Título do marco
• description (string, obrigatório): Descrição do marco
• importance (string, opcional): Nível de importância, padrão "medium"
• metadata (objeto, opcional): Metadados adicionais para o marco

Retorna:

• Objeto com status, título e timestamp

Exemplo:

// Store a project milestone
const result = await mcp_cursor10x_storeMilestone({
  title: "Authentication System Implementation",
  description:
    "Implemented JWT authentication with refresh tokens and proper error handling",
  importance: "high",
  metadata: {
    version: "1.0.0",
    files_affected: ["src/auth/jwt.js", "src/middleware/auth.js"],
  },
});
// Result: {
//   "status": "ok",
//   "title": "Authentication System Implementation",
//   "timestamp": 1681568000123
// }

mcp_cursor10x_storeDecision

Armazena uma decisão do projeto na memória de longo prazo.

Parâmetros:

• title (string, obrigatório): Título da decisão
• content (string, obrigatório): Conteúdo da decisão
• reasoning (string, opcional): Racional por trás da decisão
• importance (string, opcional): Nível de importância, padrão "medium"
• metadata (objeto, opcional): Metadados adicionais para a decisão

Retorna:

• Objeto com status, título e timestamp

Exemplo:

// Store a project decision
const result = await mcp_cursor10x_storeDecision({
  title: "JWT for Authentication",
  content: "Use JWT tokens for API authentication with refresh token rotation",
  reasoning:
    "JWTs provide stateless authentication with good security and performance characteristics",
  importance: "high",
  metadata: {
    alternatives_considered: ["Session-based auth", "OAuth2"],
    decision_date: "2023-04-15",
  },
});
// Result: {
//   "status": "ok",
//   "title": "JWT for Authentication",
//   "timestamp": 1681568100456
// }

mcp_cursor10x_storeRequirement

Armazena um requisito do projeto na memória de longo prazo.

Parâmetros:

• title (string, obrigatório): Título do requisito
• content (string, obrigatório): Conteúdo do requisito
• importance (string, opcional): Nível de importância, padrão "medium"
• metadata (objeto, opcional): Metadados adicionais para o requisito

Retorna:

• Objeto com status, título e timestamp

Exemplo:

// Store a project requirement
const result = await mcp_cursor10x_storeRequirement({
  title: "Secure Authentication",
  content:
    "System must implement secure authentication with password hashing, rate limiting, and token rotation",
  importance: "critical",
  metadata: {
    source: "security audit",
    compliance: ["OWASP Top 10", "GDPR"],
  },
});
// Result: {
//   "status": "ok",
//   "title": "Secure Authentication",
//   "timestamp": 1681568200789
// }

Ferramentas de Memória Episódica

mcp_cursor10x_recordEpisode

Registra um episódio (ação) na memória episódica.

Parâmetros:

• actor (string, obrigatório): Ator que executa a ação (usuário, assistente, sistema)
• action (string, obrigatório): Tipo de ação executada
• content (string, obrigatório): Conteúdo ou detalhes da ação
• importance (string, opcional): Nível de importância, padrão "low"
• context (string, opcional): Contexto para o episódio

Retorna:

• Objeto com status, ator, ação e timestamp

Exemplo:

// Record an episode
const result = await mcp_cursor10x_recordEpisode({
  actor: "assistant",
  action: "implementation",
  content: "Created JWT authentication middleware with token verification",
  importance: "medium",
  context: "authentication",
});
// Result: {
//   "status": "ok",
//   "actor": "assistant",
//   "action": "implementation",
//   "timestamp": 1681568300123
// }

mcp_cursor10x_getRecentEpisodes

Recupera episódios recentes da memória episódica.

Parâmetros:

• limit (número, opcional): Número máximo de episódios a recuperar, padrão 10
• context (string, opcional): Filtrar por contexto

Retorna:

• Objeto com status e array de episódios

Exemplo:

// Get recent episodes in the authentication context
const episodes = await mcp_cursor10x_getRecentEpisodes({
  limit: 5,
  context: "authentication",
});
// Result: {
//   "status": "ok",
//   "episodes": [
//     {
//       "id": 87,
//       "actor": "assistant",
//       "action": "implementation",
//       "content": "Created JWT authentication middleware with token verification",
//       "timestamp": "2023-04-15T14:45:00.123Z",
//       "importance": "medium",
//       "context": "authentication"
//     },
//     ...
//   ]
// }

Ferramentas de Memória Baseada em Vetores

mcp_cursor10x_manageVector

Ferramenta unificada para gerenciar embeddings vetoriais com operações de armazenar, buscar, atualizar e excluir.

Parâmetros:

• operation (string, obrigatório): Operação a executar ("store", "search", "update", "delete")
• contentId (número, opcional): ID do conteúdo que este vetor representa (para store, update, delete)
• contentType (string, opcional): Tipo de conteúdo ("message", "file", "snippet", etc.)
• vector (array, opcional): Dados do vetor como array de números (para store, update) ou vetor de consulta (para search)
• vectorId (número, opcional): ID do vetor a atualizar ou excluir
• limit (número, opcional): Número máximo de resultados para operação de busca, padrão 10
• threshold (número, opcional): Limiar de similaridade para operação de busca, padrão 0.7
• metadata (objeto, opcional): Informações adicionais sobre o vetor

Retorna:

• Objeto com status e resultados da operação

Exemplo:

// Store a vector embedding
const result = await mcp_cursor10x_manageVector({
  operation: "store",
  contentId: 42,
  contentType: "message",
  vector: [0.1, 0.2, 0.3, ...], // 128-dimensional vector
  metadata: {
    topic: "authentication",
    language: "en"
  }
});
// Result: {
//   "status": "ok",
//   "operation": "store",
//   "vectorId": 15,
//   "timestamp": 1681570000123
// }

// Search for similar vectors
const searchResult = await mcp_cursor10x_manageVector({
  operation: "search",
  vector: [0.1, 0.2, 0.3, ...], // query vector
  contentType: "snippet", // optional filter
  limit: 5,
  threshold: 0.8
});
// Result: {
//   "status": "ok",
//   "operation": "search",
//   "results": [
//     {
//       "vectorId": 10,
//       "contentId": 30,
//       "contentType": "snippet",
//       "similarity": 0.92,
//       "metadata": { ... }
//     },
//     ...
//   ]
// }

Esquema do Banco de Dados

O sistema de memória cria e mantém automaticamente as seguintes tabelas do banco de dados:

• messages: Armazena mensagens de usuário e assistente

  • id: Identificador único
  • timestamp: Timestamp de criação
  • role: Papel da mensagem (usuário/assistente)
  • content: Conteúdo da mensagem
  • importance: Nível de importância
  • archived: Se a mensagem está arquivada

• active_files: Rastreia atividade de arquivos

  • id: Identificador único
  • filename: Caminho para o arquivo
  • action: Última ação executada
  • last_accessed: Timestamp do último acesso

• milestones: Registra marcos do projeto

  • id: Identificador único
  • title: Título do marco
  • description: Descrição detalhada
  • timestamp: Timestamp de criação
  • importance: Nível de importância

• decisions: Armazena decisões do projeto

  • id: Identificador único
  • title: Título da decisão
  • content: Conteúdo da decisão
  • reasoning: Racional da decisão
  • timestamp: Timestamp de criação
  • importance: Nível de importância

• requirements: Mantém requisitos do projeto

  • id: Identificador único
  • title: Título do requisito
  • content: Conteúdo do requisito
  • timestamp: Timestamp de criação
  • importance: Nível de importância

• episodes: Registra ações e eventos

  • id: Identificador único
  • timestamp: Timestamp de criação
  • actor: Ator que executa a ação
  • action: Tipo de ação
  • content: Detalhes da ação
  • importance: Nível de importância
  • context: Contexto da ação

• vectors: Armazena embeddings vetoriais para busca semântica

  • id: Identificador único
  • content_id: ID do conteúdo referenciado
  • content_type: Tipo de conteúdo (message, file, snippet)
  • vector: Representação binária do vetor de embedding
  • metadata: Metadados adicionais para o vetor

• code_files: Rastreia arquivos de código indexados

  • id: Identificador único
  • file_path: Caminho para o arquivo
  • language: Linguagem de programação
  • last_indexed: Timestamp da última indexação
  • metadata: Metadados adicionais do arquivo

• code_snippets: Armazena estruturas de código extraídas

  • id: Identificador único
  • file_id: Referência ao arquivo pai
  • start_line: Número da linha inicial
  • end_line: Número da linha final
  • symbol_type: Tipo de estrutura de código (função, classe, variável)
  • content: Conteúdo do trecho de código

Fluxos de Trabalho de Exemplo

Início de Conversa Otimizado

// Initialize conversation with a single tool call
// This replaces the need for three separate calls at the start of the conversation
const result = await mcp_cursor10x_initConversation({
  content: "I need help implementing authentication in my React app",
  importance: "high",
});

// Display the banner to the user
console.log("Memory System Status:", result.display.banner);

// Use the context internally (do not show to user)
const context = result.internal.context;
// Use context for more informed assistance

Iniciando uma Nova Sessão (Método Alternativo)

// Generate a memory banner at the start
mcp_cursor10x_generateBanner({});

// Get comprehensive context
mcp_cursor10x_getComprehensiveContext({});

// Store the user message
mcp_cursor10x_storeUserMessage({
  content: "I need help with authentication",
  importance: "high",
});

Rastreando Atividade do Usuário

// Track an active file
await mcp_cursor10x_trackActiveFile({
  filename: "src/auth/jwt.js",
  action: "edit",
});

Solução de Problemas

Problemas Comuns

1. Problemas de Conexão com o Banco de Dados

   • Verifique se a URL do banco de dados Turso e o token de autenticação estão corretos
   • Verifique a conectividade de rede com o serviço Turso
   • Verifique se as configurações do firewall permitem a conexão

2. Dados Ausentes

   • Verifique se os dados foram armazenados com nível de importância adequado
   • Verifique os parâmetros da consulta de recuperação (limite, filtros)
   • Verifique a saúde do banco de dados com mcp_cursor10x_checkHealth()

3. Problemas de Desempenho

   • Monitore as estatísticas de memória com mcp_cursor10x_getMemoryStats()
   • Considere arquivar dados antigos se o banco de dados crescer demais
   • Otimize a recuperação usando filtros mais específicos

Etapas de Diagnóstico

1. Verifique a saúde do sistema:

   const health = await mcp_cursor10x_checkHealth({});
   console.log("System Health:", health);
   

2. Verifique as estatísticas de memória:

   const stats = await mcp_cursor10x_getMemoryStats({});
   console.log("Memory Stats:", stats);
   

3. Gere um banner de status:

   const banner = await mcp_cursor10x_generateBanner({});
   console.log("Memory Banner:", banner);
   

Níveis de Importância

Ao armazenar itens na memória, use níveis de importância adequados:

• low: Informações gerais, operações rotineiras, conversas do dia a dia
• medium: Contexto útil, itens de trabalho padrão, recursos regulares
• high: Decisões críticas, recursos principais, elementos importantes de arquitetura
• critical: Arquitetura central, preocupações de segurança, problemas de integridade de dados

Licença

MIT