sunsatosolutions/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.
Install it globally: the MCP server (vulcanus serve), the skills, and the commit hook all run the vulcanus command, so it has to be on your PATH. npx @sunsato/vulcanus works for a one-off look, but nothing you wire to your agents can reach it.
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. It runs locally: no account, and no automatic network call beyond an optional once-a-day version check. Upgrade with npm install -g @sunsato/vulcanus@latest.
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:
MCP server, Skills, and Making agents actually use it below cover what each one exposes.
What it creates
Each project cluster is five notes plus any specialized ones you ask for:
| Note | Holds |
| --- | --- |
| Capsule | the compressed must-remember summary an agent reads first |
| Hub | navigation and cluster boundary |
| Context | identity, definitions, scope |
| Decisions | confirmed choices and corrections |
| Rules | constraints on future behavior |
| Architecture / Flow / Visual Direction / Content Guidelines | optional domain depth |
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:
| Field | Values | Answers |
| --- | --- | --- |
| kind | umbrella, product, lab, service-brand, client, client-product | what this project *is*, so an agent knows how to place and summarize it |
| visibility | public, private | whether an agent may name this project outside the vault |
init and add project ask for both, and visibility is recorded either way — "nobody has said" and "the operator said public" are different states, and only one of them is safe to act on. recall returns the marker and, for a private project, an instruction not to name it in anything public. doctor warns on a value it does not recognize rather than failing the vault, because a typo like privte would otherwise read as public to every agent.
This is a signal, not access control: nothing here encrypts or hides a file.
Notes you keep yourself
The generated system layer is a fixed list, so a note you write under the system
directory would otherwise read as unmanaged, and the System Hub linking it would
read as over-linked — two findings for doing nothing wrong. systemNotes in
vulcanus.json names those notes:
They are branded like every other system note, so Release Notes resolves to
Release Notes in a branded vault. Declaring one only makes the vault
aware of it: the note is never created, never rewritten, and update leaves it
alone. The System Hub may link it, sync adds the bullet if it is missing, and
a note declared but never written is reported so the declaration cannot quietly
point at nothing. A system note nobody declared is still reported as unmanaged.
The first question is import