# Vulcanus

> Vulcanus is an open-source CLI (MIT, npm package `@sunsato/vulcanus`) that builds and validates an AI-readable second brain: a Git-versioned vault of linked Markdown that a person and their coding agents both read. It serves the vault over MCP, so Claude Code, Cursor, Codex, or any MCP client can `recall` a project's memory instead of starting every session cold.

Vulcanus replaces an ever-growing `CLAUDE.md` or `AGENTS.md` with layered, scoped memory. An agent reads the Recall Map, then the one project Capsule its task needs, and goes deeper into Decisions, Rules, or Context only when it needs authority or detail. `vulcanus doctor` validates that every link resolves and every project is reachable, so stale memory fails loudly. A decision that changes is marked, not deleted: `supersedes::` and `superseded-by::` fields link the new decision to the one it replaced, and `valid-until::` lets one expire. It runs locally: no account, and no automatic network call beyond an optional once-a-day version check. Requires Node 22.12 or newer. Made by Sunsato.

Quick start:

```bash
npm install -g @sunsato/vulcanus
vulcanus
claude mcp add vulcanus -- vulcanus serve
```

Install it globally: `vulcanus serve`, the generated skills, and the commit hook all run the `vulcanus` command from PATH.

## Docs

- [Full documentation](https://vulcanus.sunsato.com/llms-full.txt): the README in one Markdown file, served from the same release as this page
- [README](https://raw.githubusercontent.com/sunsatosolutions/Vulcanus/main/README.md): install, commands, vault structure, import, MCP server, validation, decision lifecycle, and editing safety
- [Token budget](https://raw.githubusercontent.com/sunsatosolutions/Vulcanus/main/docs/token-budget.md): how much a scoped recall saves compared with reading the whole vault, and what that measurement does not prove
- [Changelog](https://raw.githubusercontent.com/sunsatosolutions/Vulcanus/main/CHANGELOG.md): what changed in each release

## What it creates

- `AGENTS.md` / `CLAUDE.md`: the protocol agents follow in the vault
- `vulcanus.json`: the manifest the whole vault is derived and validated from
- `00_System/`: Index, Recall Map, Admin Profile, Rules, Update Format
- One cluster per project: Capsule (compressed must-remember summary), Hub, Context, Decisions, Rules, plus optional Architecture, Flow, Visual Direction, and Content Guidelines
- `.claude/skills/` and `.agents/skills/`: skills for Claude Code, Codex, Cursor, and Gemini CLI

## MCP tools (`vulcanus serve`)

- `recall`: a project's Capsule plus the read-next list, with a staleness warning when the Capsule is older than the notes beneath it, and the decisions and rules that are superseded or expired
- `search`: layer-aware text search; Capsule and Recall Map hits rank first, memory that is no longer current ranks last
- `list_projects`: names, statuses, trigger words, and capsule paths
- `append_decision` / `append_rule`: record a confirmed decision or standing rule; with `supersedes`, also mark the one it replaces
- `update_capsule`: replace one named section of a Capsule, never the whole file
- `vault_status` / `doctor`: health summary and full structural validation

## Commands

- `vulcanus init`: create a vault, or add memory to an existing Obsidian vault
- `vulcanus import`: propose projects, and the decisions and rules you already stated, from ChatGPT, Claude.ai, Claude Code, Codex, Gemini CLI, or Cursor history, or a Markdown folder; read locally, only your own messages, and nothing reaches the vault until you accept it
- `vulcanus doctor`, `status`, `stats`: validate the vault (including superseded and expired decisions), summarize its health, measure its token budget
- `vulcanus add project`, `project remove|rename|archive`: manage projects and their links
- `vulcanus agents`, `skills`, `hooks install|uninstall`: make agents use the vault and block commits of a broken graph
- `vulcanus update`, `sync`: upgrade the vault to a newer CLI; validate, commit, and push
- `vulcanus completion bash|zsh|fish|pwsh`: print a shell completion script

## Optional

- [GitHub repository](https://github.com/sunsatosolutions/Vulcanus)
- [npm package](https://www.npmjs.com/package/@sunsato/vulcanus)
- [Glama MCP listing](https://glama.ai/mcp/servers/sunsatosolutions/Vulcanus)
- [Sunsato](https://sunsato.com)