Vulcanus

Your coding agent starts every session cold. You re-explain the architecture, repeat decisions you already made, and watch it break a rule you set last week. The context lives in your head and in a scrollback buffer that is already gone.

Vulcanus fixes that at the source. It builds an AI-readable second brain — a Git-versioned vault of linked Markdown that you and your agents both read — and serves it over MCP, so an agent can recall a project instead of guessing at it.

npx @sunsato/vulcanus

You answer a few questions, and Vulcanus writes the whole vault — routing layer, operator profile, agent protocol, and one memory cluster per project — then validates that the graph actually holds together. Already keep an Obsidian vault? It adds the memory structure to that vault instead of creating a separate one.

Requires Node 22.12 or newer. Nothing leaves your machine: no account, no network call beyond an optional once-a-day version check.

A Sunsato product · vulcanus.sunsato.com

Why a vault and not a prompt

A CLAUDE.md that grows forever is the thing this replaces. It gets read in full on every task, it drifts out of date silently, and nothing checks that what it claims is still true.

A vault is layered instead, so recall is scoped: an agent reads the Recall Map, then the one Capsule its task needs, and goes deeper only for authority or detail. vulcanus stats measures that on your own vault — in the demo above, a task-scoped recall reads 59% less than the whole vault. vulcanus doctor then enforces that every link resolves and every project is reachable, so the memory fails loudly instead of rotting quietly.

Wire it to your agent

The vault is only worth as much as the recall it gives your tools, so that is one command each:

claude mcp add vulcanus -- vulcanus serve   # Claude Code, or any MCP client

vulcanus skills --install   # skills that run the real commands, in every repo

vulcanus agents             # the block to paste into a tool's global instructions

MCP server, Skills, and Making agents actually use it below cover what each one exposes.

What it creates

YourVault
├─ AGENTS.md              # the protocol AI agents must follow in this repo
├─ CLAUDE.md              # points Claude Code at that protocol
├─ USING-WITH-AI.md       # how to make every tool recall this vault
├─ README.md
├─ vulcanus.json          # the manifest everything is derived and validated from
├─ .claude/skills/        # invocable skills for Claude Code
├─ .agents/skills/        # the same skills for Codex, Cursor, and Gemini CLI
├─ 00_System/             # Index, Recall Map, Admin Profile, Rules, Update Format …
├─ 02_Projects/           # one cluster per project
└─ _imports/              # raw AI exports, ignored by Git

Each project cluster is five notes plus any specialized ones you ask for:

The point of the layering is token economy: an agent reads the Recall Map, then one Capsule, and only goes deeper when the task actually needs authority or detail.

What a project is, and who may hear about it

Two optional fields on each project in vulcanus.json carry what a note cannot enforce:

... View full README on GitHub