Vulcanus README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Vulcanus listing page.
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.
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:
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
<Vault> 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:
| Source | What it reads |
|---|---|
| ChatGPT data export | conversations-000.json … split batches |
| Claude.ai data export | conversations.json + projects.json |
| Claude Code | ~/.claude/projects/**/*.jsonl |
| Codex | ~/.codex/**/rollout-*.jsonl |
| Gemini CLI | ~/.gemini/tmp/**/logs.json and saved checkpoint-<tag>.json chats |
| Cursor | per-workspace chat history (state.vscdb), read through the built-in node:sqlite |
| Markdown folder | any directory of notes — the folder names become the project signal |
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. 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.
Commands
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], --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 init
Every wizard question can be answered from a flag, so init also runs without a TTY — in CI, containers, or an agent's shell. A flag skips exactly its question; --defaults answers everything else with the default, and --dry-run prints the tree that would be created without writing:
The full set: --name, --full-name, --tagline, --naming branded|generic, --profile core|full, --operator, --role, --aliases, --projects, --no-import, --git / --no-git, --defaults, --dry-run.
Filling the project notes
Whenever projects are added — by init, add project, or import — Vulcanus asks how their notes should get their content: answer the questions here, skip and write them yourself later, or hand the job to an AI CLI already installed on your machine.
The AI path probes your PATH for claude, codex, cursor-agent (also installed as agent), and gemini, offers only what is really there, and asks where each project's source code lives — proposing the directories your past Claude Code and Codex sessions ran in. Before anything starts it tells you which CLI is taking over your terminal, in which directory, and exactly which notes it has been told to write. Nothing is spawned without your confirmation, and that confirmation cannot be suppressed by a flag.
The short structural questions — hierarchy, grouping, which specialized notes to create — are asked in the terminal either way. They decide the folder layout and the generated system notes, and they have to be settled before a single file exists, while the AI session only starts once the notes are there. What the AI takes over is the note bodies, which is where the work actually is.
The CLI is asked to study the codebase, question you about what the code cannot answer, and write the cluster's notes to the vault's conventions. When the session exits, doctor runs immediately, so an edit that broke the graph is reported rather than discovered later.
Making agents actually use it
A vault nobody reads is a folder, so the enforcement layer ships with it.
Agents working inside the vault are already covered: AGENTS.md carries the full protocol, CLAUDE.md points Claude Code at it, and .cursor/rules/vault.mdc does the same for Cursor.
For everywhere else — other repositories, ordinary chat — run vulcanus agents. It prints a block naming your vault, its path, and its operator, to paste into a tool's global instructions:
| Tool | Where it goes |
|---|---|
| Claude Code | ~/.claude/CLAUDE.md |
| Codex | ~/.codex/AGENTS.md |
| Cursor | Settings → Rules → User Rules |
| ChatGPT | Settings → Personalization → Custom instructions |
| Gemini CLI | ~/.gemini/GEMINI.md |
vulcanus agents --raw prints the snippet alone, so it can be appended straight to a file. Every generated vault also contains USING-WITH-AI.md with the same guidance.
Skills
Instructions are prose a model may or may not honour. A skill is a capability it can invoke, so "sync the vault" runs the real vulcanus sync instead of the model improvising an equivalent. Vulcanus writes one skill per vault operation, plus a recall skill that carries the Recall Map → Capsule → Hub → Context/Decisions/Rules routing:
| Skill | Runs |
|---|---|
<vault>-recall | nothing — it teaches the read order and the authority rules |
<vault>-doctor | vulcanus doctor, and --repair when structure is missing |
<vault>-sync | vulcanus sync --dry-run, then vulcanus sync "topic" |
<vault>-add-project | vulcanus add project "Name" |
<vault>-import | vulcanus import |
<vault>-update | vulcanus update --dry-run, then vulcanus update |
Skills follow the Agent Skills format: a directory per skill holding a SKILL.md with name and description frontmatter. The description is what decides whether a model reaches for the skill at all, so each one names the vault, the operator, and the phrasings that should trigger it.
Every vault ships its skills twice — .claude/skills/ for Claude Code, .agents/skills/ for Codex, Cursor, and Gemini CLI, which all read that vendor-neutral directory. Two copies of one text, versioned with the vault, so an agent opening the repository can act on day one. Tools without a skill mechanism keep the prose path; this adds a channel rather than replacing one.
That only covers agents working inside the vault, and the point of a second brain is recall from everywhere else. For that the skills have to live in your home configuration, which Vulcanus will not do behind your back:
That writes them to ~/.claude/skills/ and ~/.agents/skills/, with your vault's real path baked in so an agent in another repository knows where to run. It is the only thing Vulcanus writes outside the vault, it never happens during init, and it leaves existing files alone unless you pass --force. vulcanus skills on its own explains what would be installed; --raw prints the files.
sync pushes to a remote and update rewrites files, which is a lot of consequence for one sentence of chat. Both skills instruct the agent to show the --dry-run output and get your confirmation in that conversation first, and every skill is told to report the command's actual output and exit code rather than reporting success. Skills are managed files, so doctor --repair and update bring template improvements to existing vaults.
MCP server
vulcanus serve turns the vault into structured memory for any MCP client — Claude Code, Cursor, or your own agent runtime — instead of ad-hoc file reads:
| Tool | Does |
|---|---|
recall | returns a project's Capsule plus the read-next list — the protocol's entry point |
search | layer-aware text search; Capsule and Recall Map hits rank first |
list_projects | the routing table: names, statuses, trigger words, capsule paths |
append_decision | records a confirmed decision in the Decision/Details format |
append_rule | records a standing rule in the project's Rules note |
update_capsule | replaces one section of a Capsule — never a blind whole-file rewrite |
vault_status | the vulcanus status summary, as JSON |
doctor | full structural validation with every finding |
Register it the way your client expects, e.g. for Claude Code:
Run it from inside the vault (or any subdirectory), or pass --cwd when the client starts elsewhere. Registering it globally is fine: the server starts anywhere, and in a directory with no vault the tools say so instead of the server failing to come up. The manifest and the vault location are both resolved on every call, so a vault created — or edited — while the server runs is visible immediately.
recall also tells the truth about its own freshness: when a Capsule is older than the Decisions, Rules, or Context beneath it, the answer carries a staleness warning instead of presenting an outdated summary as current.
Obsidian
The vault is a valid Obsidian vault the moment it exists — no plugin, no import. Open the folder and the graph is there, with shortest-path wikilinks and rename-safe links already configured.
Already keep an Obsidian vault? Run init inside it and Vulcanus adds the memory structure to that vault instead of creating a separate one beside it — a directory with a .obsidian folder, in the current directory or an immediate subdirectory, is detected automatically. A single detected vault is used without asking, and its identity is taken from the folder, so there is no vault name to answer; only a choice between several vaults is ever put to you. Your own notes are never overwritten — generated files are written only where nothing exists — and if the folder is already a Vulcanus vault, init stops and points you to add project or update.
The graph view doubles as a health check: projects appear as clusters, hubs at their centers, and an unlinked note stands out immediately. Edits made in Obsidian are plain Markdown, so the CLI and your agents pick them up straight away, and vulcanus doctor keeps hand edits, agent edits, and generated structure consistent.
Staying current
vulcanus.json records the CLI version that last wrote the vault. When a newer CLI runs against an older vault, doctor warns and vulcanus update:
- runs any manifest schema migrations
- refreshes the files the CLI owns, so template improvements reach existing vaults
- creates notes a newer version added (including a
--profile fullupgrade) - re-stamps the generator version and validates the result
Your own notes are never rewritten — update reports how many it left untouched. That includes the Index, the hubs, and the Import Log: they hold what you wrote, so a new project or a deeper system layer is linked in rather than regenerated. AGENTS.md is merged — sections you added stay, sections the protocol adds arrive. --dry-run shows the plan first, and notes the manifest no longer describes are listed rather than deleted. A vault written by a newer CLI is refused outright instead of being downgraded.
After a command, the CLI checks npm at most once a day and prints a one-line notice when a newer release exists. Set VULCANUS_NO_UPDATE_CHECK=1 (or NO_UPDATE_NOTIFIER, or run in CI) to turn it off; it fails silently offline.
Validation
vulcanus doctor is the part that keeps a growing vault honest. Every check is derived from vulcanus.json, so it stays correct as your tree changes:
- frontmatter completeness (
type,project,status,tags) and duplicate or empty keys - every wikilink resolves, and resolves to exactly one note
- every hub links to the notes the manifest says it owns
- every project note links back to its own hub
- every project has a Capsule reachable from the Recall Map
- no duplicate or case-colliding note names
- raw exports and generated state are actually ignored by Git
AGENTS.mddescribes the agent protocol this CLI writes, not a superseded one- the skill copies in
.claude/skills/and.agents/skills/have not drifted apart
Missing structure is an error; extra hand-added links are a warning, because a vault is meant to be written in.
vulcanus sync refuses to commit while errors remain, and reports the push result exactly as it happened.
Editing safety
Generated files fall into three classes:
- seed — everything that can hold what you wrote: every project note, the Recall Map, the Index, every hub, and the Import Log. Written once, never overwritten. Adding a project or deepening the system layer inserts the missing links surgically instead of regenerating the file around them.
- managed — files the CLI fully owns:
CLAUDE.md, the Cursor rule, and the generated skills.doctor --repairrewrites these. - merge —
AGENTS.mdalone. It has to be both: the protocol every agent reads, so a new step must reach existing vaults, and a file you extend with instructions of your own. An update keeps every section you already have, inserts the ones the protocol added, and refreshes its version stamp. Wording changes to a section you customized will not reach you — losing your customization would be worse.
--force still rewrites everything, including your own notes. It is the only flag that does.
Vault naming
The vault name you choose becomes the vault's identity: with the default branded naming, system notes are ATLAS Index.md, ATLAS Recall Map.md, and so on, and the vault folder is named after it — so Obsidian opens it under that name. Choose generic naming for portable Index.md / Recall Map.md filenames instead.
The generated vault is Obsidian-ready: shortest-form wikilinks, links that follow renames, and workspace files kept out of Git.
Development
Source layout: manifest/ derives every path and link expectation, generate/ turns that plan into Markdown, doctor/ validates the result against the same plan, importers/ normalizes AI exports, mcp/ holds the transport-free vault operations serve exposes, and commands/ wires it to the CLI.
CONTRIBUTING.md covers the checks, the review bar, and how to add an importer or a language. docs/token-budget.md measures what the layered structure actually saves, and how that was measured.
The landing page for vulcanus.sunsato.com lives in site/ — a single static file with no build step, deployed to Cloudflare Workers as static assets (wrangler.jsonc) on every push to main.
License
MIT © Sunsato