Mercury-cortex

Motor de conocimiento para desarrolladores de IA para descubrimiento y reutilización de código entre proyectos.

Documentación

Mercury-cortex

Un motor de conocimiento local-first para asistentes de codificación con IA.

Funciona con cualquier asistente de IA compatible con MCP, incluidos Claude Code, OpenCode, Gemini CLI, Copilot CLI y otros.

¿Por qué Mercury Cortex?

Los asistentes de codificación con IA son potentes, pero carecen de memoria persistente. Cada nueva conversación comienza desde cero. No recuerdan la arquitectura de tu proyecto, las decisiones pasadas ni los patrones del código base. Esto te obliga a reexplicar el contexto repetidamente, perdiendo tiempo y rompiendo el flujo de trabajo.

Mercury Cortex le da a tu IA una memoria persistente. Registras un proyecto una sola vez, y la IA describe lo que construye, importa esos metadatos a un grafo de conocimiento estructurado y sirve ese contexto a cualquier asistente compatible con MCP. Cuando vuelves a un proyecto después de semanas, tu compañero de IA lo recuerda todo: relaciones entre archivos, patrones de código e historial del proyecto.

Conocimiento entre proyectos y reutilización de código

El grafo de conocimiento no se limita a un único repositorio. Cada proyecto que registras aporta sus metadatos a un único grafo de conocimiento local, y tu IA puede buscar en todos ellos a la vez. Antes de escribir cualquier código, consulta todos los proyectos indexados, no solo el que estás trabajando actualmente, y muestra las implementaciones existentes con su ubicación de origen, propósito, características y superficie de API.

Esto convierte la reutilización en una capacidad de primer nivel y no en una ocurrencia tardía:

Empieza una funcionalidad en un repositorio completamente nuevo, y tu IA ya sabe cómo resolviste el mismo problema en un proyecto anterior.
Extrae patrones probados, utilidades, componentes e implementaciones de referencia de cualquier código base que hayas indexado, en lugar de reescribirlos desde cero.
Busca por lo que hace el código, usando términos técnicos, etiquetas de funcionalidades y funciones exportadas, en todo tu espacio de trabajo.
Los resultados apuntan de vuelta al proyecto y archivo originales, para que tu IA pueda leer el código fuente completo antes de adaptarlo al código base actual.

El motor se ejecuta localmente en tu máquina. Tu código nunca sale de tu dispositivo, y el grafo de conocimiento se construye a partir de tus archivos de proyecto reales, no de un servicio en la nube. Conéctalo una vez, y todas las herramientas de IA que uses obtienen la misma comprensión entre proyectos.

Saber más →

Instalación

Puedes instalar mercury-cortex desde binarios de versión precompilados o desde el código fuente con Cargo. Los scripts son la opción más sencilla y funcionan en cualquier plataforma.

Binarios precompilados (Linux, macOS, Windows)

Descarga la última versión para tu plataforma y sistema operativo. El script verifica la suma de comprobación SHA-256 antes de instalar y nunca ejecuta contenido descargado.

Linux y 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 una versión específica, fíjala explícitamente:

VERSION=v0.1.0 sh scripts/install.sh

.\install.ps1 -Version v0.1.0

Los scripts instalan en /usr/local/bin (Unix) o ~/.local/bin cuando el primero no es escribible, y en %LOCALAPPDATA%\Programs\mercury-cortex-bin en Windows. Consulta docs/installers.md para más detalles sobre cómo funcionan los instaladores.

Desde el código fuente con Cargo

Instala la última versión desde crates.io:

cargo install mercury-cortex

Usar cargo install requiere un toolchain de Rust pero compila directamente desde el código fuente, por lo que es una buena opción si desarrollas en Mercury Cortex o quieres una versión más reciente que la última publicada.

Inicio rápido

1. Inicializa el entorno

Crea el directorio de datos, la base de datos y aplica las migraciones de esquema.

mercury-cortex setup

2. Crea tu perfil

Preguntas interactivas para tu nombre, correo electrónico y nombre del agente.

mercury-cortex profile

3. Registra tu proyecto

Registra el directorio actual y crea la configuración de .mercury-cortex/.

cd my-project
mercury-cortex project

4. Conecta tu herramienta de IA

Añade la configuración del servidor MCP a tu herramienta de IA (consulta Conecta tu herramienta de IA más abajo para ver ejemplos específicos por herramienta).

5. Empieza a indexar

En tu chat de IA, escribe:

mercury-cortex:init

La IA registra el proyecto, analiza su estructura, genera metadatos para cada archivo y los importa al grafo de conocimiento. Después de esto, tu IA tiene el contexto completo del proyecto. Consulta Flujos de trabajo para más detalles.

6. Empieza a desarrollar

Una vez completada la indexación, usa mercury-cortex:dev como prefijo para tus solicitudes de desarrollo habituales:

mercury-cortex:dev

Create light, dark, and system themes.

La IA busca en el grafo de conocimiento antes de escribir código, reutiliza patrones existentes y actualiza el índice con archivos nuevos. Úsalo para cualquier tarea, incluidos correcciones de errores, funcionalidades y refactorizaciones. Consulta Flujos de trabajo para más detalles.

Conecta tu herramienta 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"]
    }
  }
}

Flujos de trabajo

Mercury Cortex proporciona dos flujos de trabajo (llamados "prompts" en MCP) que guían a tu IA a través de tareas estructuradas. Ambos se activan desde tu chat de IA, no desde la terminal.

`mercury-cortex:init` (Inicialización de proyecto)

Cuándo usarlo: Una vez, al configurar por primera vez un proyecto con Mercury Cortex.

Cómo usarlo: Escribe mercury-cortex:init en tu chat de IA. La IA llama al prompt de MCP y sigue un flujo de trabajo de 5 pasos:

Prerrequisitos y validación, que verifica que el proyecto está registrado y que el motor es accesible.
Análisis del proyecto, que detecta lenguajes, frameworks y estructura del proyecto.
Refinamiento de .mcignore, que revisa y actualiza los patrones de exclusión (p. ej., target/, build/, .env).
Generación e importación de metadatos, que genera metadatos para los archivos de código fuente, escribe JSON en .mercury-cortex/temp/ e importa mediante metadata/import.
Verificación y resumen, que confirma que el índice está poblado y reporta los resultados.

Después de la inicialización, el propósito, las características, las etiquetas y las exportaciones de cada archivo de código fuente son buscables por tu IA.

`mercury-cortex:dev` (Flujo de trabajo de desarrollo)

Cuándo usarlo: Durante el desarrollo diario. Úsalo junto con tus prompts habituales, pidiéndole que analice, implemente o refactorice. Buscará en el grafo de conocimiento antes de escribir código.

Cómo usarlo: Antepón mercury-cortex:dev a tus solicitudes de desarrollo habituales:

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.

La IA sigue un flujo de trabajo de 7 pasos:

Acerca de Mercury Cortex, que revisa las herramientas y capacidades disponibles.
Analizar la solicitud, que desglosa lo que estás pidiendo.
Buscar en Mercury Cortex, que consulta el grafo de conocimiento en busca de código existente relevante.
Decidir: reutilizar, extender o crear, que determina si reutilizar código existente, extenderlo o escribir algo nuevo.
Implementar cambios, que realiza los cambios de código.
Generar y enviar metadatos, que actualiza el grafo de conocimiento con los archivos nuevos o modificados.
Informar, que resume lo que se hizo.

El flujo de trabajo de desarrollo garantiza que tu IA siempre busque antes de escribir, reutilice antes de crear y mantenga el grafo de conocimiento actualizado.

Referencia de herramientas MCP

Herramienta	Descripción
`cortex/info`	Versión del motor y estado
`project/open`	Abrir un proyecto en el motor
`project/close`	Cerrar el proyecto activo
`project/status`	Estado actual del proyecto
`project/register`	Registrar un nuevo proyecto
`project/update`	Guardar metadatos de proyecto generados por IA
`project/update_mcignore`	Añadir patrones de exclusión a `.mcignore`
`search/code`	Buscar metadatos de archivos indexados
`metadata/import`	Importar metadatos generados por IA en espera
`index/paths`	Indexar rutas de archivos del proyecto
`file/metadata`	Obtener metadatos de un archivo
`workflow/session`	Iniciar una sesión de flujo de trabajo
`workflow/step`	Ejecutar un paso del flujo de trabajo

Referencia de CLI

Comando	Descripción
`mercury-cortex setup`	Inicializar el entorno global, la base de datos y el esquema
`mercury-cortex migration`	Ejecutar migraciones de esquema de la base de datos
`mercury-cortex profile`	Crear o actualizar el perfil de usuario
`mercury-cortex project`	Registrar el directorio del proyecto actual
`mercury-cortex mcp serve`	Iniciar el servidor MCP sobre stdio
`mercury-cortex mcp stop`	Detener todos los procesos del servidor MCP en ejecución
`mercury-cortex daemon serve`	Iniciar el daemon con servidor IPC en socket Unix
`mercury-cortex daemon stop`	Detener el daemon en ejecución
`mercury-cortex db backup`	Crear una copia de seguridad de la base de datos con marca de tiempo
`mercury-cortex db list`	Listar las copias de seguridad disponibles de la base de datos
`mercury-cortex db restore`	Restaurar la base de datos desde una copia de seguridad
`mercury-cortex db reset`	Limpiar todas las tablas del esquema
`mercury-cortex db export`	Exportar datos de tablas a archivos JSON
`mercury-cortex version`	Imprimir versión, información de compilación y hash de commit

Consulta docs/commands.md para la referencia completa de comandos con banderas, argumentos y ejemplos.

Estructura del proyecto

`.mercury-cortex/`

Directorio de configuración por proyecto:

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

`AGENTS.md` / `CLAUDE.md`

Archivos de instrucciones opcionales a nivel de proyecto que los asistentes de IA leen para comprender las convenciones de tu proyecto.

Arquitectura

Mercury Cortex se compone de estos componentes:

Runtime coordina el motor, el estado del proyecto y el IPC
Engine gestiona las operaciones del grafo de conocimiento (consulta mercury-cortex-core)
Servidor MCP implementa el Protocolo de Contexto de Modelo sobre stdio
Servidor IPC es el daemon de socket Unix para la comunicación entre procesos
Base de datos es SurrealDB con almacenamiento de archivos local

Para los detalles internos de la biblioteca principal, consulta mercury-cortex-core.

Características y visión

Disponible hoy

Motor de conocimiento local-first. Tu código nunca sale de tu máquina. El grafo de conocimiento se construye a partir de tus archivos de proyecto reales, almacenados en una base de datos local de SurrealDB.
Servidor MCP. Implementa el Protocolo de Contexto de Modelo sobre stdio, conectando tu asistente de IA al grafo de conocimiento. Funciona con OpenCode, Claude Code, Codex, Gemini CLI y otras herramientas compatibles con MCP.
Flujos de trabajo de IA. Dos flujos de trabajo integrados guían a tu IA a través de tareas estructuradas:
- mercury-cortex:init, una configuración de proyecto de una sola vez: registra el proyecto, analiza la estructura, genera metadatos para cada archivo y los importa al grafo de conocimiento.
- mercury-cortex:dev, para el desarrollo diario: busca en el grafo de conocimiento antes de escribir código, reutiliza patrones existentes y mantiene el índice actualizado.
Registro de proyectos. Registra cualquier directorio de proyecto con un solo comando. Crea la configuración de .mercury-cortex/, los patrones de .mcignore y los archivos de instrucciones de IA.
Importación de metadatos. La IA genera metadatos estructurados (propósito, características, etiquetas, exportaciones) para los archivos de código fuente y los importa al grafo de conocimiento mediante metadata/import.
Búsqueda semántica. Busca metadatos de archivos indexados por propósito, características, lenguaje o framework, no solo por nombres de archivo.
Gestión de la base de datos. Haz copias de seguridad, restaura, reinicia y exporta tu grafo de conocimiento con los comandos de mercury-cortex db.
CLI. Interfaz de línea de comandos completa para configuración, gestión de perfiles, registro de proyectos, control del servidor MCP, gestión del daemon y operaciones de base de datos. Consulta docs/commands.md para la referencia completa.

Visión a largo plazo

Mercury Cortex está diseñado para evolucionar de un motor de conocimiento personal con IA a una plataforma de conocimiento de IA para toda la organización. La visión a largo plazo incluye:

Compartición de conocimiento organizacional. Los equipos comparten un grafo de conocimiento común entre repositorios, de modo que la IA de cada desarrollador tenga acceso al mismo conocimiento institucional.
Colaboración multi-agente. Múltiples agentes de IA trabajan juntos en tareas compartidas, coordinándose a través del grafo de conocimiento para evitar conflictos y duplicaciones.
Comunicación de IA a IA. Los asistentes de IA en diferentes proyectos o sesiones descubren y referencian mutuamente su trabajo mediante el grafo de conocimiento.
Descubrimiento de propiedad del conocimiento. Identifica automáticamente quién escribió qué, quién mantiene qué módulos y dónde reside la experiencia en la organización.
Conocimiento entre proyectos a escala. El grafo unificado ya conecta archivos, módulos y patrones de todos los proyectos registrados; esto escala a medida que se incorporan más proyectos y equipos, extendiendo la reutilización más allá de un único desarrollador.
Compartición de contexto entre agentes de IA. Los agentes de IA se pasan contexto entre sí a través del grafo de conocimiento, manteniendo la continuidad en sesiones y herramientas.
Detección inteligente de propiedad de código. Detecta automáticamente la propiedad del código, los límites de responsabilidad y las relaciones de dependencia en todo el código base.
Red de conocimiento del equipo. Una red de grafos de conocimiento de proyectos que saca a la luz patrones, decisiones y convenciones relevantes en todo el equipo.

Estas capacidades representan la visión a largo plazo de Mercury Cortex y no forman parte de la versión actual.

Desarrollo

# 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 obtener detalles.

Seguridad

Consulte SECURITY.md para obtener información sobre cómo reportar vulnerabilidades y el modelo de amenazas.

Contribuciones

Consulte CONTRIBUTING.md para la configuración de desarrollo, el flujo de trabajo y las pautas.

Licencia

Apache-2.0. Derechos de autor 2026 Mercury Cortex Contributors. Consulte LICENSE para obtener detalles.

Mercury-cortex

Documentación

¿Por qué Mercury Cortex?

Conocimiento entre proyectos y reutilización de código

Instalación

Binarios precompilados (Linux, macOS, Windows)

Desde el código fuente con Cargo

Inicio rápido

1. Inicializa el entorno

2. Crea tu perfil

3. Registra tu proyecto

4. Conecta tu herramienta de IA

5. Empieza a indexar

6. Empieza a desarrollar

Conecta tu herramienta de IA

OpenCode

Claude Code

Codex

Google Antigravity

Flujos de trabajo

mercury-cortex:init (Inicialización de proyecto)

mercury-cortex:dev (Flujo de trabajo de desarrollo)

Referencia de herramientas MCP

Referencia de CLI

Estructura del proyecto

.mercury-cortex/

AGENTS.md / CLAUDE.md

Arquitectura

Características y visión

Disponible hoy

Visión a largo plazo

Desarrollo

Seguridad

Contribuciones

Licencia

`mercury-cortex:init` (Inicialización de proyecto)

`mercury-cortex:dev` (Flujo de trabajo de desarrollo)

`.mercury-cortex/`

`AGENTS.md` / `CLAUDE.md`