Mercury-cortex

Mecanismo de conhecimento de IA para desenvolvedores, voltado à descoberta e reutilização de código entre projetos.

Documentação

Mercury-cortex

Um mecanismo de conhecimento local-first para assistentes de codificação com IA.

Ele funciona com qualquer assistente de IA compatível com MCP, incluindo Claude Code, OpenCode, Gemini CLI, Copilot CLI e outros.

Por que Mercury Cortex?

Assistentes de codificação com IA são poderosos, mas não possuem memória persistente. Cada nova conversa começa do zero. Eles não se lembram da arquitetura do seu projeto, de decisões passadas ou dos padrões do código. Isso força você a reexplicar o contexto repetidamente, perdendo tempo e quebrando o fluxo de trabalho.

O Mercury Cortex dá ao seu assistente de IA uma memória persistente. Você registra um projeto uma única vez, e a IA descreve o que está sendo construído, importa esses metadados para um grafo de conhecimento estruturado e fornece esse contexto a qualquer assistente compatível com MCP. Quando você retorna a um projeto após semanas, seu parceiro de IA se lembra de tudo: relações entre arquivos, padrões de código e histórico do projeto.

Conhecimento entre projetos e reuso de código

O grafo de conhecimento não se limita a um único repositório. Cada projeto que você registra contribui com seus metadados para um grafo de conhecimento local, e sua IA pode pesquisar em todos eles de uma só vez. Antes de escrever qualquer código, ela consulta todos os projetos indexados, não apenas o que você está trabalhando no momento, e apresenta implementações existentes com sua localização no código-fonte, propósito, funcionalidades e superfície de API.

Isso torna o reuso uma capacidade de primeira classe, e não uma reflexão tardia:

Comece uma funcionalidade em um repositório totalmente novo, e sua IA já sabe como você resolveu o mesmo problema em um projeto anterior.
Extraia padrões testados, utilitários, componentes e implementações de referência de qualquer código que você tenha indexado, em vez de reescrevê-los do zero.
Pesquise pelo que o código faz, usando termos técnicos, tags de funcionalidades e funções exportadas, em todo o seu espaço de trabalho.
Os resultados apontam de volta para o projeto e arquivo originais, para que sua IA possa ler o código-fonte completo antes de adaptá-lo ao código atual.

O mecanismo roda localmente na sua máquina. Seu código nunca sai do seu dispositivo, e o grafo de conhecimento é construído a partir dos seus arquivos de projeto reais, não de um serviço em nuvem. Conecte-o uma vez, e todas as ferramentas de IA que você usa ganham o mesmo entendimento entre projetos.

Saiba mais →

Instalação

Você pode instalar o mercury-cortex a partir de binários de release pré-compilados ou do código-fonte com Cargo. Os scripts são a opção mais fácil e funcionam em qualquer plataforma.

Binários pré-compilados (Linux, macOS, Windows)

Baixe o release mais recente para sua plataforma e sistema operacional. O script verifica a soma de verificação SHA-256 antes de instalar e nunca executa conteúdo baixado.

Linux e macOS:

curl -fsSL https://raw.githubusercontent.com/mercury-ai-1/mercury-cortex/main/scripts/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/mercury-ai-1/mercury-cortex/main/scripts/install.ps1 | iex

Para instalar uma versão específica do release, fixe-a explicitamente:

VERSION=v0.1.0 sh scripts/install.sh

.\install.ps1 -Version v0.1.0

Os scripts instalam em /usr/local/bin (Unix) ou ~/.local/bin quando o primeiro não é gravável, e em %LOCALAPPDATA%\Programs\mercury-cortex-bin no Windows. Consulte docs/installers.md para detalhes sobre como os instaladores funcionam.

Do código-fonte com Cargo

Instale o release mais recente do crates.io:

cargo install mercury-cortex

Usar o cargo install requer um toolchain Rust, mas compila diretamente do código-fonte, então é uma boa opção se você desenvolve no Mercury Cortex ou quer uma versão mais recente que o último release.

Início Rápido

1. Inicialize o ambiente

Cria o diretório de dados, o banco de dados e aplica as migrações de esquema.

mercury-cortex setup

2. Crie seu perfil

Prompts interativos para seu nome, e-mail e nome do agente.

mercury-cortex profile

3. Registre seu projeto

Registra o diretório atual e cria a configuração .mercury-cortex/.

cd my-project
mercury-cortex project

4. Conecte sua ferramenta de IA

Adicione a configuração do servidor MCP à sua ferramenta de IA (veja Conecte Sua Ferramenta de IA abaixo para exemplos específicos por ferramenta).

5. Comece a indexar

No chat da sua IA, digite:

mercury-cortex:init

A IA registra o projeto, analisa sua estrutura, gera metadados para cada arquivo e os importa para o grafo de conhecimento. Depois disso, sua IA tem contexto completo do projeto. Consulte Workflows para detalhes.

6. Comece a desenvolver

Assim que a indexação estiver concluída, use mercury-cortex:dev como prefixo para suas solicitações normais de desenvolvimento:

mercury-cortex:dev

Create light, dark, and system themes.

A IA pesquisa o grafo de conhecimento antes de escrever código, reutiliza padrões existentes e atualiza o índice com novos arquivos. Use para qualquer tarefa, incluindo correções de bugs, funcionalidades e refatoração. Consulte Workflows para detalhes.

Conecte Sua Ferramenta de IA

OpenCode

{
  "mcp": {
    "mercury-cortex": {
      "type": "local",
      "command": ["mercury-cortex", "mcp", "serve"],
      "enabled": true
    }
  }
}

Claude Code

{
  "mcpServers": {
    "mercury-cortex": {
      "command": "mercury-cortex",
      "args": ["mcp", "serve"]
    }
  }
}

Codex

[mcp_servers.mercury-cortex]
command = "mercury-cortex"
args = ["mcp", "serve"]

Google Antigravity

{
  "mcpServers": {
    "mercury-cortex": {
      "command": "mercury-cortex",
      "args": ["mcp", "serve"]
    }
  }
}

Workflows

O Mercury Cortex fornece dois workflows (chamados de "prompts" no MCP) que guiam sua IA por tarefas estruturadas. Ambos são acionados pelo chat da sua IA, não pelo terminal.

`mercury-cortex:init` (Inicialização de Projeto)

Quando usar: Uma vez, ao configurar um projeto com o Mercury Cortex pela primeira vez.

Como usar: Digite mercury-cortex:init no chat da sua IA. A IA chama o prompt MCP e segue um workflow de 5 etapas:

Pré-requisitos e Validação, que verifica se o projeto está registrado e se o mecanismo está acessível.
Análise do Projeto, que detecta linguagens, frameworks e estrutura do projeto.
Refinamento do .mcignore, que revisa e atualiza os padrões de exclusão (por exemplo, target/, build/, .env).
Geração e Importação de Metadados, que gera metadados para arquivos de código-fonte, grava JSON em .mercury-cortex/temp/ e importa via metadata/import.
Verificação e Resumo, que confirma que o índice está populado e relata os resultados.

Após a inicialização, o propósito, as funcionalidades, as tags e as exportações de cada arquivo de código-fonte são pesquisáveis pela sua IA.

`mercury-cortex:dev` (Workflow de Desenvolvimento)

Quando usar: Durante o desenvolvimento do dia a dia. Use junto com seus prompts normais, pedindo para analisar, implementar ou refatorar. Ele pesquisará o grafo de conhecimento antes de escrever código.

Como usar: Prefixe suas solicitações normais de desenvolvimento com mercury-cortex:dev:

mercury-cortex:dev

Create light, dark, and system themes.

mercury-cortex:dev

Refactor the auth middleware to support JWT tokens.

mercury-cortex:dev

Fix the race condition in the connection pool.

A IA segue um workflow de 7 etapas:

Sobre o Mercury Cortex, que revisa as ferramentas e capacidades disponíveis.
Analisar a Solicitação, que detalha o que você está pedindo.
Pesquisar no Mercury Cortex, que consulta o grafo de conhecimento em busca de código existente relevante.
Decidir: Reutilizar, Estender ou Criar, que determina se deve reutilizar código existente, estendê-lo ou escrever algo novo.
Implementar Mudanças, que faz as alterações de código.
Gerar e Enviar Metadados, que atualiza o grafo de conhecimento com os arquivos novos ou alterados.
Relatar, que resume o que foi feito.

O workflow de desenvolvimento garante que sua IA sempre pesquise antes de escrever, reutilize antes de criar e mantenha o grafo de conhecimento atualizado.

Referência de Ferramentas MCP

Ferramenta	Descrição
`cortex/info`	Versão e status do mecanismo
`project/open`	Abrir um projeto no mecanismo
`project/close`	Fechar o projeto ativo
`project/status`	Estado atual do projeto
`project/register`	Registrar um novo projeto
`project/update`	Salvar metadados de projeto gerados por IA
`project/update_mcignore`	Adicionar padrões de exclusão a `.mcignore`
`search/code`	Pesquisar metadados de arquivos indexados
`metadata/import`	Importar metadados gerados por IA em estágio
`index/paths`	Indexar caminhos de arquivos do projeto
`file/metadata`	Obter metadados de arquivo
`workflow/session`	Iniciar uma sessão de workflow
`workflow/step`	Executar uma etapa do workflow

Referência da CLI

Comando	Descrição
`mercury-cortex setup`	Inicializar ambiente global, banco de dados e esquema
`mercury-cortex migration`	Executar migrações de esquema do banco de dados
`mercury-cortex profile`	Criar ou atualizar perfil de usuário
`mercury-cortex project`	Registrar o diretório atual do projeto
`mercury-cortex mcp serve`	Iniciar servidor MCP via stdio
`mercury-cortex mcp stop`	Parar todos os processos do servidor MCP em execução
`mercury-cortex daemon serve`	Iniciar daemon com servidor IPC em socket Unix
`mercury-cortex daemon stop`	Parar o daemon em execução
`mercury-cortex db backup`	Criar um backup do banco de dados com timestamp
`mercury-cortex db list`	Listar backups disponíveis do banco de dados
`mercury-cortex db restore`	Restaurar o banco de dados a partir de um backup
`mercury-cortex db reset`	Limpar todas as tabelas do esquema
`mercury-cortex db export`	Exportar dados de tabelas para arquivos JSON
`mercury-cortex version`	Imprimir versão, informações de build e hash do commit

Consulte docs/commands.md para a referência completa de comandos com flags, argumentos e exemplos.

Estrutura do Projeto

`.mercury-cortex/`

Diretório de configuração por projeto:

.mercury-cortex/
  config.json     # Project-specific settings
  .mcignore       # Files to exclude from indexing
  temp/           # Staged AI-generated metadata for import

`AGENTS.md` / `CLAUDE.md`

Arquivos opcionais de instruções em nível de projeto que os assistentes de IA leem para entender as convenções do seu projeto.

Arquitetura

O Mercury Cortex é construído em torno destes componentes:

Runtime coordena o mecanismo, o estado do projeto e o IPC
Engine lida com operações do grafo de conhecimento (veja mercury-cortex-core)
Servidor MCP implementa o Model Context Protocol via stdio
Servidor IPC é o daemon de socket Unix para comunicação entre processos
Banco de dados é o SurrealDB com armazenamento local de arquivos

Para os detalhes internos da biblioteca principal, consulte mercury-cortex-core.

Funcionalidades e Visão

Disponível Hoje

Mecanismo de conhecimento local-first. Seu código nunca sai da sua máquina. O grafo de conhecimento é construído a partir dos seus arquivos de projeto reais, armazenados em um banco de dados SurrealDB local.
Servidor MCP. Implementa o Model Context Protocol via stdio, conectando seu assistente de IA ao grafo de conhecimento. Funciona com OpenCode, Claude Code, Codex, Gemini CLI e outras ferramentas compatíveis com MCP.
Workflows de IA. Dois workflows integrados guiam sua IA por tarefas estruturadas:
- mercury-cortex:init, uma configuração única de projeto: registra o projeto, analisa a estrutura, gera metadados para cada arquivo e os importa para o grafo de conhecimento.
- mercury-cortex:dev, para o desenvolvimento do dia a dia: pesquisa o grafo de conhecimento antes de escrever código, reutiliza padrões existentes e mantém o índice atualizado.
Registro de projetos. Registre qualquer diretório de projeto com um único comando. Cria a configuração .mercury-cortex/, padrões .mcignore e arquivos de instrução para IA.
Importação de metadados. A IA gera metadados estruturados (propósito, funcionalidades, tags, exportações) para arquivos de código-fonte e os importa para o grafo de conhecimento via metadata/import.
Pesquisa semântica. Pesquise metadados de arquivos indexados por propósito, funcionalidades, linguagem ou framework, não apenas por nomes de arquivo.
Gerenciamento de banco de dados. Faça backup, restaure, redefina e exporte seu grafo de conhecimento com comandos mercury-cortex db.
CLI. Interface de linha de comando completa para configuração, gerenciamento de perfil, registro de projetos, controle do servidor MCP, gerenciamento de daemon e operações de banco de dados. Consulte docs/commands.md para a referência completa.

Visão de Longo Prazo

O Mercury Cortex foi projetado para evoluir de um mecanismo de conhecimento pessoal com IA para uma plataforma de conhecimento de IA em nível organizacional. A visão de longo prazo inclui:

Compartilhamento de conhecimento organizacional. As equipes compartilham um grafo de conhecimento comum entre repositórios, para que a IA de cada desenvolvedor tenha acesso ao mesmo conhecimento institucional.
Colaboração multiagente. Vários agentes de IA trabalham juntos em tarefas compartilhadas, coordenando-se por meio do grafo de conhecimento para evitar conflitos e duplicações.
Comunicação entre IAs. Assistentes de IA em diferentes projetos ou sessões descobrem e referenciam o trabalho uns dos outros por meio do grafo de conhecimento.
Descoberta de propriedade do conhecimento. Identifique automaticamente quem escreveu o quê, quem mantém quais módulos e onde a expertise está na organização.
Conhecimento entre projetos em escala. O grafo unificado já conecta arquivos, módulos e padrões em todos os projetos registrados; isso escala conforme mais projetos e equipes aderem, estendendo a reutilização além de um único desenvolvedor.
Compartilhamento de contexto entre agentes de IA. Agentes de IA passam contexto uns aos outros por meio do grafo de conhecimento, mantendo a continuidade entre sessões e ferramentas.
Detecção inteligente de propriedade de código. Detecte automaticamente propriedade de código, limites de responsabilidade e relações de dependência em todo o codebase.
Rede de conhecimento da equipe. Uma rede de grafos de conhecimento de projetos que destaca padrões, decisões e convenções relevantes em toda a equipe.

Essas capacidades representam a visão de longo prazo do Mercury Cortex e não fazem parte da versão atual.

Desenvolvimento

# Requires Rust 1.85+ (edition 2024)
# Core library must be a sibling directory
git clone https://github.com/mercury-ai-1/mercury-cortex.git
git clone https://github.com/mercury-ai-1/mercury-cortex-core.git ../mercury-cortex-core

cargo build
cargo test
cargo clippy -- -D warnings

Consulte CONTRIBUTING.md para obter detalhes.

Segurança

Consulte SECURITY.md para obter informações sobre como relatar vulnerabilidades e o modelo de ameaças.

Contribuição

Consulte CONTRIBUTING.md para configuração de desenvolvimento, fluxo de trabalho e diretrizes.

Mercury-cortex

Documentação

Por que Mercury Cortex?

Conhecimento entre projetos e reuso de código

Instalação

Binários pré-compilados (Linux, macOS, Windows)

Do código-fonte com Cargo

Início Rápido

1. Inicialize o ambiente

2. Crie seu perfil

3. Registre seu projeto

4. Conecte sua ferramenta de IA

5. Comece a indexar

6. Comece a desenvolver

Conecte Sua Ferramenta de IA

OpenCode

Claude Code

Codex

Google Antigravity

Workflows

mercury-cortex:init (Inicialização de Projeto)

mercury-cortex:dev (Workflow de Desenvolvimento)

Referência de Ferramentas MCP

Referência da CLI

Estrutura do Projeto

.mercury-cortex/

AGENTS.md / CLAUDE.md

Arquitetura

Funcionalidades e Visão

Disponível Hoje

Visão de Longo Prazo

Desenvolvimento

Segurança

Contribuição

Licença

`mercury-cortex:init` (Inicialização de Projeto)

`mercury-cortex:dev` (Workflow de Desenvolvimento)

`.mercury-cortex/`

`AGENTS.md` / `CLAUDE.md`