Vulcanus
Command-line memory vault generator
A command-line product that writes and validates a Git-versioned vault of linked Markdown both a person and an AI agent can navigate. It generates the vault, then checks the graph holds together.
Released · v0.5.0 on npm
- Commands
- 13Commands
- MCP tools
- 8MCP tools
What it does
vulcanus init asks a short series of questions and writes an entire vault: the routing layer, the operator profile, the agent protocol file, and one memory cluster per project.
vulcanus doctor then validates that graph. The manifest vulcanus.json is the single source of truth; both the generator and the validator derive from it.
A measurable claim
The product measures its own claim.
vulcanus stats compares three states: a cold start, task-scoped recall, and the whole vault. That makes visible how much context an agent actually reads to do the work.
vulcanus stats
- cold start
- 2687 tokens
- protocol · recall map · operator profile
- + capsule
- 2896 tokens
- task-scoped recall
- whole vault
- 6898 tokens
- 19 notes
The output above is a real run on an example vault. These numbers are estimates and must always be quoted with their method; the method is in the repository's docs/token-budget.md.
Agent integration
Three channels; none replaces another, because not every client speaks the same language.
vulcanus agents — a prose protocol file, rules any agent can read.
vulcanus skills — generated Agent Skills; ChatGPT has no skill mechanism, so no single channel is trusted alone.
vulcanus serve — the MCP server: recall, search, list_projects, append_decision, append_rule, update_capsule, vault_status, doctor.
MCP writes are section-scoped, and recall warns when a capsule has fallen behind the notes beneath it.
Since 0.4.4 serve starts in any directory and resolves the vault per tool call, so a globally registered client works wherever the operator happens to be.
Import and privacy
The first question init asks is whether to import existing AI history.
Sources: ChatGPT and Claude exports, local Claude Code, Codex, Gemini CLI, and Cursor sessions, and a plain Markdown folder.
Raw conversations are never copied in: they are read locally, reduced to candidate project names with evidence counts, then discarded. Only operator-confirmed names become notes.
Imports are incremental by default, and a source that would scan an ordinary directory is never probed uninvited.
Distribution and requirements
- Node
- 22.12+ (tested on 22, 24, and 26)
- MCP Registry
- io.github.sunsatosolutions/vulcanus