# Vulcanus

> Vulcanus is a free MCP server for knowledge and memory. Local memory vault for coding agents: layered Markdown, Git history and a validity check. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** CLI, macOS, Windows, Linux
- **Website:** https://vulcanus.sunsato.com
- **Repository:** https://github.com/sunsatosolutions/vulcanus
- **MCP Registry name:** io.github.sunsatosolutions/vulcanus
- **Categories:** knowledge and memory, developer tools
- **Listing updated:** 2026-11-15

## About

Vulcanus generates a Git-versioned vault of linked Markdown that Claude Code, Cursor, Codex and other agents can recall project by project. After a few setup questions it writes a routing layer, an operator profile, an agent protocol and a cluster per project, then validates that every link resolves and every project is reachable. If you already keep an Obsidian vault, it adds the structure there.

The design aims at token economy. An agent reads a Recall Map, then one project's Capsule, and opens Context, Decisions or Rules only when needed. The README reports that a task-scoped recall read 59 percent less than the whole vault on its demo, and the vulcanus stats command measures this on your own vault. Unconfirmed facts go under Needs Confirmation, and a changed decision names what it replaced.

It can seed the vault from history in ChatGPT exports, Claude data and Claude Code, Codex, Cursor and Gemini CLI sessions, read locally, with only the projects you tick becoming notes. Vault text can be in English, Turkish, German or Spanish. It needs Node 22.12 or newer, runs locally with no account, and must be installed globally so agents can reach the vulcanus command.

## Features

- **Layered recall:** Recall Map, Capsule, then deeper notes opened only when needed.
- **Validated graph:** The doctor command checks links and project reachability.
- **Git history:** Every change is a commit, and replaced decisions are marked.
- **History import:** Seeds notes from ChatGPT, Claude and coding-agent session history.
- **Explicit uncertainty:** Unconfirmed items live under Needs Confirmation.
- **Four vault languages:** English, Turkish, German or Spanish content.

## Good for

- Stop re-explaining architecture to a coding agent
- Keep decisions and rules where agents recall them
- Turn old chat history into project notes
- Add agent memory to an existing Obsidian vault

## Install

### Claude Code (Terminal)

```sh
claude mcp add vulcanus -- npx -y @sunsato/vulcanus
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "vulcanus": {
      "command": "npx",
      "args": [
        "-y",
        "@sunsato/vulcanus"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "vulcanus": {
      "command": "npx",
      "args": [
        "-y",
        "@sunsato/vulcanus"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "vulcanus": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@sunsato/vulcanus"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "vulcanus": {
      "command": "npx",
      "args": [
        "-y",
        "@sunsato/vulcanus"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "vulcanus": {
      "command": "npx",
      "args": [
        "-y",
        "@sunsato/vulcanus"
      ]
    }
  }
}
```

## Tools

- `recall`: Recall a project from the vault.

## FAQ

### Does it need an account?

No. It runs locally, with only an optional once-a-day version check.

### What do I need?

Node 22.12 or newer and a global npm install of @sunsato/vulcanus.

### How do I connect it to Claude Code?

Run claude mcp add vulcanus -- vulcanus serve.

### Can it use my chat history?

Yes, it can read exports and local sessions from several tools, and only the names you tick become notes.

### Is Vulcanus free?

Yes. Vulcanus is free to use.

### How do I add Vulcanus to Claude Code?

Run this command in your terminal: claude mcp add vulcanus -- npx -y @sunsato/vulcanus

### What are the best alternatives to Vulcanus?

The closest alternatives to Vulcanus are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/vulcanus
