Mercury-cortex

AI developer knowledge engine for cross-project code discovery and reuse.

GitHub

Documentation

Mercury-cortex

A local-first knowledge engine for AI coding assistants.

It works with any MCP-compatible AI assistant, including Claude Code, OpenCode, Gemini CLI, Copilot CLI, and others.

Why Mercury Cortex?

AI coding assistants are powerful, but they lack persistent memory. Every new conversation starts from zero. They do not remember your project's architecture, past decisions, or codebase patterns. This forces you to repeatedly re-explain context, losing time and breaking flow.

Mercury Cortex gives your AI a persistent memory. You register a project once, and the AI describes what it builds, imports that metadata into a structured knowledge graph, and serves that context to any MCP-compatible assistant. When you return to a project after weeks, your AI partner remembers everything: file relationships, code patterns, and project history.

Cross-project knowledge and code reuse

The knowledge graph is not confined to a single repository. Every project you register contributes its metadata to one local knowledge graph, and your AI can search across all of them at once. Before writing any code, it queries every indexed project, not just the one you are currently working in, and surfaces existing implementations with their source location, purpose, features, and API surface.

This makes reuse a first-class capability rather than an afterthought:

Start a feature in a brand-new repository, and your AI already knows how you solved the same problem in a previous project.
Pull battle-tested patterns, utilities, components, and reference implementations out of any codebase you have indexed, instead of rewriting them from scratch.
Search by what the code does, using technical terms, feature tags, and exported functions, across your entire workspace.
The results point back to the original project and file, so your AI can read the full source before adapting it to the current codebase.

The engine runs locally on your machine. Your code never leaves your device, and the knowledge graph is built from your actual project files, not a cloud service. Connect it once, and every AI tool you use gains the same cross-project understanding.

Know more →

Installation

You can install mercury-cortex either from prebuilt release binaries or from source with Cargo. The scripts are the easiest option and work on any platform.

Prebuilt binaries (Linux, macOS, Windows)

Download the latest release for your platform and OS. The script verifies the SHA-256 checksum before installing and never executes downloaded content.

Linux and 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

To install a specific release version, pin it explicitly:

VERSION=v0.1.0 sh scripts/install.sh

.\install.ps1 -Version v0.1.0

The scripts install to /usr/local/bin (Unix) or ~/.local/bin when the former is not writable, and to %LOCALAPPDATA%\Programs\mercury-cortex-bin on Windows. See docs/installers.md for details on how the installers work.

From source with Cargo

Install the latest release from crates.io:

cargo install mercury-cortex

Using cargo install requires a Rust toolchain but builds directly from source, so it is a good option if you develop on Mercury Cortex itself or want a version newer than the latest release.

Quick Start

1. Initialize the environment

Creates the data directory, database, and applies schema migrations.

mercury-cortex setup

2. Create your profile

Interactive prompts for your name, email, and agent name.

mercury-cortex profile

3. Register your project

Registers the current directory and creates .mercury-cortex/ config.

cd my-project
mercury-cortex project

4. Connect your AI tool

Add the MCP server configuration to your AI tool (see Connect Your AI Tool below for tool-specific examples).

5. Start indexing

In your AI chat, type:

mercury-cortex:init

The AI registers the project, analyzes its structure, generates metadata for every file, and imports it into the knowledge graph. After this, your AI has full context of the project. See Workflows for details.

6. Start developing

Once indexing is complete, use mercury-cortex:dev as a prefix to your normal development requests:

mercury-cortex:dev

Create light, dark, and system themes.

The AI searches the knowledge graph before writing code, reuses existing patterns, and updates the index with new files. Use it for any task, including bug fixes, features, and refactoring. See Workflows for details.

Connect Your AI Tool

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

Mercury Cortex provides two workflows (called "prompts" in MCP) that guide your AI through structured tasks. Both are triggered from your AI chat, not from the terminal.

`mercury-cortex:init` (Project Initialization)

When to use: Once, when first setting up a project with Mercury Cortex.

How to use: Type mercury-cortex:init in your AI chat. The AI calls the MCP prompt and follows a 5-step workflow:

Prerequisites and Validation, which verifies the project is registered and the engine is reachable.
Project Analysis, which detects languages, frameworks, and project structure.
.mcignore Refinement, which reviews and updates exclusion patterns (e.g., target/, build/, .env).
Metadata Generation and Import, which generates metadata for source files, writes JSON to .mercury-cortex/temp/, and imports via metadata/import.
Verification and Summary, which confirms the index is populated and reports results.

After initialization, every source file's purpose, features, tags, and exports are searchable by your AI.

`mercury-cortex:dev` (Development Workflow)

When to use: During day-to-day development. Use this alongside your normal prompts, asking it to analyze, implement, or refactor. It will search the knowledge graph before writing code.

How to use: Prefix your normal development requests with 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.

The AI follows a 7-step workflow:

About Mercury Cortex, which reviews available tools and capabilities.
Analyze the Request, which breaks down what you are asking for.
Search Mercury Cortex, which queries the knowledge graph for relevant existing code.
Decide: Reuse, Extend, or Create, which determines whether to reuse existing code, extend it, or write something new.
Implement Changes, which makes the code changes.
Generate and Submit Metadata, which updates the knowledge graph with the new or changed files.
Report, which summarizes what was done.

The dev workflow ensures your AI always searches before writing, reuses before creating, and keeps the knowledge graph current.

MCP Tools Reference

Tool	Description
`cortex/info`	Engine version and status
`project/open`	Open a project in the engine
`project/close`	Close the active project
`project/status`	Current project state
`project/register`	Register a new project
`project/update`	Save AI-generated project metadata
`project/update_mcignore`	Append ignore patterns to `.mcignore`
`search/code`	Search indexed file metadata
`metadata/import`	Import staged AI-generated metadata
`index/paths`	Index project file paths
`file/metadata`	Get file metadata
`workflow/session`	Start a workflow session
`workflow/step`	Execute a workflow step

CLI Reference

Command	Description
`mercury-cortex setup`	Initialize global environment, DB, and schema
`mercury-cortex migration`	Run database schema migrations
`mercury-cortex profile`	Create or update user profile
`mercury-cortex project`	Register the current project directory
`mercury-cortex mcp serve`	Start MCP server over stdio
`mercury-cortex mcp stop`	Stop all running MCP server processes
`mercury-cortex daemon serve`	Start daemon with IPC server on Unix socket
`mercury-cortex daemon stop`	Stop the running daemon
`mercury-cortex db backup`	Create a timestamped database backup
`mercury-cortex db list`	List available database backups
`mercury-cortex db restore`	Restore the database from a backup
`mercury-cortex db reset`	Clear all schema tables
`mercury-cortex db export`	Export table data to JSON files
`mercury-cortex version`	Print version, build info, and commit hash

See docs/commands.md for the full commands reference with flags, arguments, and examples.

Project Layout

`.mercury-cortex/`

Per-project configuration directory:

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

`AGENTS.md` / `CLAUDE.md`

Optional project-level instruction files that AI assistants read to understand your project conventions.

Architecture

Mercury Cortex is built around these components:

Runtime coordinates the engine, project state, and IPC
Engine handles knowledge graph operations (see mercury-cortex-core)
MCP Server implements the Model Context Protocol over stdio
IPC Server is the Unix socket daemon for process communication
Database is SurrealDB with local file storage

For the core library internals, see mercury-cortex-core.

Features & Vision

Available Today

Local-first knowledge engine. Your code never leaves your machine. The knowledge graph is built from your actual project files, stored in a local SurrealDB database.
MCP server. Implements the Model Context Protocol over stdio, connecting your AI assistant to the knowledge graph. Works with OpenCode, Claude Code, Codex, Gemini CLI, and other MCP-compatible tools.
AI workflows. Two built-in workflows guide your AI through structured tasks:
- mercury-cortex:init, a one-time project setup: registers the project, analyzes structure, generates metadata for every file, and imports it into the knowledge graph.
- mercury-cortex:dev, for day-to-day development: searches the knowledge graph before writing code, reuses existing patterns, and keeps the index current.
Project registration. Register any project directory with a single command. Creates .mercury-cortex/ config, .mcignore patterns, and AI instruction files.
Metadata import. The AI generates structured metadata (purpose, features, tags, exports) for source files and imports it into the knowledge graph via metadata/import.
Semantic search. Search indexed file metadata by purpose, features, language, or framework, not just by filenames.
Database management. Backup, restore, reset, and export your knowledge graph with mercury-cortex db commands.
CLI. Full command-line interface for setup, profile management, project registration, MCP server control, daemon management, and database operations. See docs/commands.md for the complete reference.

Long-Term Vision

Mercury Cortex is designed to evolve from a personal AI knowledge engine into an organization-wide AI knowledge platform. The long-term vision includes:

Organization knowledge sharing. Teams share a common knowledge graph across repositories, so every developer's AI has access to the same institutional knowledge.
Multi-agent collaboration. Multiple AI agents work together on shared tasks, coordinating through the knowledge graph to avoid conflicts and duplication.
AI-to-AI communication. AI assistants in different projects or sessions discover and reference each other's work through the knowledge graph.
Knowledge ownership discovery. Automatically identify who wrote what, who maintains which modules, and where expertise lives in the organization.
Cross-project knowledge at scale. The unified graph already connects files, modules, and patterns across all registered projects; this scales as more projects and teams join, extending reuse beyond a single developer.
Context sharing between AI agents. AI agents pass context to each other through the knowledge graph, maintaining continuity across sessions and tools.
Intelligent code ownership detection. Automatically detect code ownership, responsibility boundaries, and dependency relationships across the codebase.
Team knowledge network. A network of project knowledge graphs that surfaces relevant patterns, decisions, and conventions across the entire team.

These capabilities represent the long-term vision of Mercury Cortex and are not part of the current release.

Development

# 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

See CONTRIBUTING.md for details.

Security

See SECURITY.md for information about reporting vulnerabilities and the threat model.

Contributing

See CONTRIBUTING.md for development setup, workflow, and guidelines.

Mercury-cortex

Documentation

Why Mercury Cortex?

Cross-project knowledge and code reuse

Installation

Prebuilt binaries (Linux, macOS, Windows)

From source with Cargo

Quick Start

1. Initialize the environment

2. Create your profile

3. Register your project

4. Connect your AI tool

5. Start indexing

6. Start developing

Connect Your AI Tool

OpenCode

Claude Code

Codex

Google Antigravity

Workflows

mercury-cortex:init (Project Initialization)

mercury-cortex:dev (Development Workflow)

MCP Tools Reference

CLI Reference

Project Layout

.mercury-cortex/

AGENTS.md / CLAUDE.md

Architecture

Features & Vision

Available Today

Long-Term Vision

Development

Security

Contributing

License

`mercury-cortex:init` (Project Initialization)

`mercury-cortex:dev` (Development Workflow)

`.mercury-cortex/`

`AGENTS.md` / `CLAUDE.md`