# Vulcanus

Keeps project context in a Git-versioned Markdown vault. Your coding agent recalls rules and decisions via MCP without reading endless logs.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: sunsatosolutions
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/sunsatosolutions/Vulcanus
- Updated: 2026-10-19
- HTML: https://affpapa.org/en/nevibecode/mcp/vulcanus

## What it does

Vulcanus replaces oversized instruction files with an organized Markdown knowledge base tracked by Git. Instead of parsing the entire project memory on every query, an assistant reads the Recall Map, opens a concise Capsule note, and navigates into specific decisions or rules only when needed. It can also generate the initial vault structure directly from previous chat exports of Claude Code, Cursor, Codex, or ChatGPT.

The tool requires Node.js version 22.12 or higher. Keep in mind that project visibility tags like `private` act as agent instructions rather than cryptographic access control. The `vulcanus doctor` command verifies internal links, keeping stale references from quietly breaking context retrieval.

Everything runs locally on your machine with no third-party accounts. Global installation ensures that repository skills and MCP commands locate the executable inside your system `PATH`.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add vulcanus -- npx -y @sunsato/vulcanus
```

### Codex

**Platform CLI**
```bash
codex mcp add vulcanus -- npx -y @sunsato/vulcanus
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "vulcanus": {
            "command": "npx",
            "args": [
                "-y",
                "@sunsato/vulcanus"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "vulcanus": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@sunsato/vulcanus"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add vulcanus npx -y @sunsato/vulcanus
```

## When to use it
- maintain architectural decisions across fresh agent coding sessions
- split project constraints into modular Markdown notes
- extract context from Cursor, Codex, or ChatGPT conversation dumps
- validate internal links across the memory vault with vulcanus doctor

## Example prompts
- Recall the architectural decisions and constraints for this project
- Run vulcanus stats to check token reduction in the current vault
- Verify all project capsule links and report missing references

## Similar
- [self-improvement](https://affpapa.org/en/nevibecode/skills/self-improvement.md) — skill · 2000 installs
- [sayou](https://affpapa.org/en/nevibecode/mcp/sayou.md) — MCP server · ★ 28
- [context-mem](https://affpapa.org/en/nevibecode/mcp/context-mem.md) — MCP server · ★ 19
- [git-context-controller](https://affpapa.org/en/nevibecode/skills/git-context-controller.md) — skill · 82 installs
- [context-sync](https://affpapa.org/en/nevibecode/mcp/context-sync.md) — MCP server · ★ 189
- [hipocampus](https://affpapa.org/en/nevibecode/plugins/hipocampus.md) — plugin · ★ 211

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md