Vulcanus

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.

npm install -g @sunsato/vulcanus

vulcanus

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:

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:

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:

{ "systemNotes": ["Release Notes", "Semantic Index Strategy"] }

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

Before anything else, Vulcanus offers to read an existing AI history and propose your project tree from it:

Locations are auto-detected, so usually you just pick one from a list. A Markdown folder is the exception: it is never probed on its own, and only scanned when you name the path.

Re-running import on the same source proposes only what is new — conversation ids already read are remembered in the vault's state directory. --all re-reads everything. --json prints the candidates with their evidence and writes nothing.

Nothing from your history is copied into the vault unless you accept it. Conversations are read locally, reduced to candidate project names with evidence counts, and discarded. Only the names you tick become notes; the Import Log records how many conversations were scanned, never their content.

Names the source itself grouped conversations under — a Claude project, a repository directory — are the strong signal and come pre-checked. Names inferred purely from title frequency are proposals and start unchecked.

Decisions you already made

Your history usually holds more than project names: the choices you settled and the rules you kept repeating. After the project step, import asks whether to look for them (--memory says yes up front, --no-memory skips the question, and --memory-only skips project discovery for a vault that already has its projects).

• Only your own messages are read. An assistant's sentence is not your decision.
• Sentences are matched against decision and rule phrases in English, Turkish, German, and Spanish — "we decided", "from now on", "karar verdik", "ab sofort", "a partir de ahora" — and ranked by how strong the phrase is, how many conversations repeat it, and how recent it is. Questions and code are ignored.
• A conversation counts toward a project when its source grouped it there or its title names the project. Body mentions do not.
• What the vault already records is dropped. A candidate that looks like a revision of a live decision is offered as its replacement, so the old one is marked rather than contradicted (see When a decision changes).
• You review each candidate: accept as decision, accept as replacement, accept as rule, edit the wording, skip, or stop. At most 15 per project per run. Nothing is accepted unattended — --json with --memory-only reports counts only.
• What you accept is written in the wording you accepted, with a source:: import · · line. Skipped candidates are discarded, and reviewed conversations are remembered so they are not proposed again (separately from project discovery, so one never hides conversations from the other).

--ai-extract [cli] hands the candidate sentences — not transcripts — to an installed AI CLI to merge duplicates, drop noise, and tighten wording, after showing you what will be sent. Anything it returns that does not trace back to a sentence it was given is discarded.

Commands

vulcanus init            # create a vault, or add memory to an existing Obsidian vault (default command)

vulcanus status          # one-screen vault health: projects, notes, doctor result, git state

vulcanus stats           # token budget: what a cold-start agent reads, what recall saves

vulcanus doctor          # validate the vault against its manifest

vulcanus add project     # add projects and wire them into the graph

vulcanus project remove "Name"        # unlink a project; its notes move to _archive/

vulcanus project rename "Old" "New" # folder, notes, and every link, in one move vulcanus project archive "Name" # mark it archived (--restore undoes it)

vulcanus import          # propose more projects from an AI export or a notes folder

vulcanus serve           # serve the vault to MCP clients: recall, search, append_decision, …

vulcanus agents          # print the block that makes your AI tools use the vault

vulcanus skills          # agent skills that run these commands for you

vulcanus update          # bring the vault up to date with a newer CLI

vulcanus sync "topic"    # validate, then commit and push

vulcanus sync --watch # regenerate and revalidate on every edit; never commits

vulcanus hooks install   # a pre-commit hook that refuses to commit a broken graph

vulcanus completion zsh  # completion script for bash | zsh | fish | pwsh

init accepts --lang en|tr|de|es, --ai [cli], and a target directory; add project and import accept --ai [cli]; status and stats accept --json; doctor accepts --repair and --json; import accepts --source, --path, --ai-group [cli], --memory, --no-memory, --memory-only, --ai-extract [cli], --json, and --all; update accepts --dry-run, --force, --profile core|full, and --json; sync accepts --dry-run, --json, and --watch; skills accepts --raw, --install, and --force.

--verbose and --quiet work on every command, and --json implies quiet so machine-readable output owns stdout.

Exit codes are part of the contract: 0 the command did what it said, 1 the vault or the operation failed validation, 2 the command was used wrongly (no vault, bad flag), 130 cancelled at a prompt. Every failure prints what happened, why, and what to do next.

Scripting `