Forge a second brain your agents can read
Every session your AI starts cold. Vulcanus builds the memory it should have started with: a Git-versioned vault of linked Markdown, structured so an agent finds the right context in one hop instead of reading everything.
npm install -g @sunsato/vulcanus
Then run vulcanus. Installed globally, so your agents can reach it too. No
account, runs locally, Node 22.12+. A Sunsato product.
Share of the vault read by each depth. Each layer opens only when the one above is not enough.
- AGENTS.md · Recall Map The protocol and the routing layer: trigger words lead to the right project in one hop.
- Capsule Compressed must-remember. Most tasks stop here.
- Hub · Context · Decisions · Rules Navigation, authority and detail, opened only when the task needs it.
Measured on a freshly generated six-project vault with vulcanus stats.
The measurement
Structure is the feature
A folder of notes is not memory — an agent still has to read all of it. Vulcanus writes a layered graph: routing at the top, a compressed capsule per project, authoritative detail underneath. Agents read down only as far as the task actually requires.
-
Capsules keep it cheap
Each project opens with a compressed must-remember note. Most questions never need more than that, so context windows stay small and answers stay grounded.
-
Uncertainty is explicit
Anything unconfirmed lives under Needs Confirmation and is never presented as fact. Corrections outrank older notes by design.
-
Git is the memory history
Every change is a commit, and a decision that changes is marked rather than erased: the new one names what it replaced. You can see when it changed, what it replaced, and why — the part chat history can never give you.
-
The vault speaks your language
English, Turkish, German, Spanish — and not just the setup questions. The capsules, hubs, rules and section headings are written in the language the vault records, so the memory you read every day is in the language you think in. The agent protocol stays English on purpose: it carries the version stamp
doctorchecks.
Start from what you already said
You have thousands of conversations describing your projects. The first question Vulcanus asks is whether to read them.
Run it again later and it proposes only what is new: conversations already read are remembered, so a second import is not a second pile of the same candidates.
- ChatGPTdata export
- Claude Codelocal sessions
- Codexrollout sessions
- Cursorworkspace history
- Gemini CLIsaved chats
| Source | What it reads |
|---|---|
| ChatGPT | Data export, including exports split across many conversation files |
| Claude | Data export, using Claude Projects as the grouping signal |
| Claude Code | Local sessions — no export needed, working directories name the projects |
| Codex | Local rollout sessions, grouped the same way |
| Gemini CLI | Local sessions, plus chats you saved under a name with /chat save |
| Cursor | Per-workspace chat history, with the workspace folder naming the project |
| Markdown folder | Notes you already keep — never scanned on its own, only when you name the directory |
And the decisions you already made
Your history holds more than project names: the choices you settled and the rules you kept repeating. Say yes to one more question and Vulcanus finds them — in English, Turkish, German, or Spanish — and asks you about each one.
Your words, not the assistant's
Only your own messages are read, matched against phrases like “we decided” and “from now on”, and ranked by how often you repeated them and how recently.
Nothing lands unreviewed
Accept it, edit it, keep it as a rule, skip it, or stop. Up to fifteen per project, never accepted unattended, and what the vault already records is not asked again.
Revisions, not contradictions
A statement that revises a recorded decision is offered as its replacement, so the old one is marked as superseded instead of sitting beside it, contradicting it.
Fourteen commands
The vault is plain Markdown you can edit by hand in Obsidian or any editor. These keep it consistent as it grows.
initimportadd projectproject
doctorstatusstatshooksupdate
serveagentsskillssynccompletion
initAnswer the questions, get a validated vault. This is the default command.
doctorValidate structure, links, and coverage against the manifest.
add projectAdd a project and wire it into the graph — routes, hubs, and links included.
importPropose more projects — and the decisions you already made — from an AI export.
agentsPrint the block that makes your AI tools recall the vault from everywhere.
skillsGenerate agent skills that run these commands, and install them where agents look.
updateBring an existing vault up to a newer CLI, without touching your writing.
syncValidate, then commit and push. It refuses to commit a broken vault.
statusOne screen: projects, notes, doctor result, git state, and stale capsules.
statsWhat a cold-start agent must read, and how much task-scoped recall saves.
serveExpose the vault to MCP clients as typed tools instead of raw file reads.
projectRemove, rename, or archive a project — every link and route follows.
hooksA pre-commit hook that keeps a broken memory graph out of your history.
completionPrint a shell completion script for bash, zsh, fish, or pwsh.
Memory as tools, not file reads
vulcanus serve exposes the vault over MCP, so an agent asks for what it
needs instead of guessing which file to open.
claude mcp add vulcanus -- vulcanus serverecallproject: "Atlas"recall returns the Capsule, the read order, and what is
no longer current.
-
recallOne project's Capsule plus the order to read deeper. The call an agent makes before touching anything — and it says so when the Capsule has fallen behind, when the project is one you marked private, and which decisions are no longer current.
-
searchLayer-aware: Capsule and Recall Map hits rank above everything else, and memory that is no longer current ranks last.
-
append_decision·append_ruleConfirmed outcomes go back into the right note, in the vault's own format. Pass
supersedesand the decision it replaces is marked in the same call. -
update_capsuleRefresh one section of a summary — never a blind whole-file rewrite.
-
list_projects·vault_status·doctorThe routing table, a one-shot health summary, and the full structural validation, as tool calls.
The saving, measured
The claim is that a layered vault is cheaper to read than a pile of notes.
vulcanus stats reports what your own vault costs, so the claim is
something you can check rather than something you have to believe.
- 24%Cold start · 3,167 tokens
- +2%One project capsule · 203 tokens
- 74%The rest of the vault · 9,832 tokens
| What an agent reads | Tokens | Share of the vault |
|---|---|---|
| Cold start — protocol, routing, operator profile | 3,167 | 24% |
| Cold start + one project capsule | 3,370 | 26% |
| The whole vault | 13,202 | 100% |
It checks its own work
Memory rots quietly: a renamed note, a link that stopped resolving, a project nothing routes to. Every check is derived from your manifest, so it stays correct as the vault grows.
vulcanus doctor- Every note carries complete, well-formed frontmatter
- Every link resolves — and resolves to exactly one note
- Every hub links to the notes it owns
- Every note links back to its hub
- Every project is reachable from the routing layer
- No duplicate or case-colliding note names
- Raw exports are actually ignored by Git
- Agents are following the current protocol, not a superseded one
- Superseded decisions link both ways, and nothing replaces itself in a loop
- No decision past its expiry date is still presented as current
Make your agents actually use it
A vault nobody reads is a folder. Vulcanus writes the enforcement layer too — so recalling your memory becomes a standing rule instead of something you remember to mention.
-
Inside the vault — already done
AGENTS.md,CLAUDE.md, and.cursor/rulesship with the vault. Open the folder in Codex, Claude Code, or Cursor and the protocol is already in effect. -
Everywhere else — one paste
Most work happens in other repositories and in ordinary chat. Run
vulcanus agentsand paste the block into your tool's global instructions. From then on, every session recalls before working and consolidates after.
| 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 |
## Flora is my second brain — ## use it in every session I maintain Flora, an AI-readable memory vault at ~/Flora. Using it is a standing requirement, not an optional extra. - Before working on anything related to my projects, recall from it first: read ~/Flora/AGENTS.md, then route through the Recall Map → the matching project Capsule → Hub → Context, Decisions, and Rules. Treat Flora as the source of truth, and prefer my latest correction and the most specific file. - After work that creates durable knowledge, consolidate it into the correct note, then run vulcanus doctor and vulcanus sync. - Never record uncertain information as fact. Put it under Needs Confirmation. - Do not add new projects without my explicit confirmation.
See your memory as a graph
The vault is a valid Obsidian vault the moment it exists — no plugin, no import step. Open the folder and every note, link, and cluster is there, with shortest-path wikilinks and rename-safe links already configured.
Obsidian's graph view is the fastest health check you have: projects show up as clusters, hubs sit at their center, and a note nothing links to stands out immediately. Edit anything there and it stays plain Markdown — the CLI and your agents see the change straight away.
vulcanus doctor keeps all three honest.
vulcanus init detects an
existing Obsidian vault and offers to add the memory structure to it, instead of
scaffolding a separate one beside it. Your own notes are never overwritten.
Questions
What people ask before they point an agent at it.
vulcanusVULCANUS_NO_UPDATE_CHECK=1
What is Vulcanus?
An open-source command-line tool that builds and validates an AI-readable second brain: a Git-versioned vault of linked Markdown that you and your coding agents both read. It serves that vault over MCP, so an agent can recall a project instead of starting every session cold.
How is it different from a CLAUDE.md or AGENTS.md file?
A single instructions file is read in full on every task, grows without limit, and nothing checks that it is still true. A Vulcanus vault is layered: an agent reads the Recall Map, then the one project Capsule its task needs, and goes deeper only for authority or detail. vulcanus doctor then validates that every link resolves and every project is reachable, so outdated memory shows up as an error.
How is it different from other MCP memory servers?
Many memory servers keep facts in a database or index past conversations for retrieval. Vulcanus keeps memory as plain Markdown notes you can read, edit, and review in Git or Obsidian, organized into a fixed structure per project — Capsule, Hub, Context, Decisions, Rules — that is validated against a manifest. What your agent remembers is exactly what is written in the vault.
Which AI tools does it work with?
Any MCP client, including Claude Code and Cursor, through vulcanus serve. The vault also ships skills for Claude Code, Codex, Cursor, and Gemini CLI, and vulcanus agents prints a block to paste into any tool's global instructions.
Does my data leave my machine?
No. There is no account and no server. The only automatic network call is an optional once-a-day check for a newer release, which VULCANUS_NO_UPDATE_CHECK=1 turns off. Importing AI history reads conversations locally: only the project names you confirm and the decisions you accept are written to the vault, never transcripts. Two opt-in flags, --ai-group and --ai-extract, hand a short digest to an AI CLI you already have installed, and show you what will be sent before anything is.
Can I use it with my existing Obsidian vault?
Yes. Run vulcanus init inside it and Vulcanus adds the memory structure to that vault instead of creating a separate one. Your own notes are never overwritten, and the graph view shows each project as its own cluster.
Can agents write to the memory, and is that safe?
Agents record outcomes through scoped MCP tools: append_decision and append_rule add one entry to the right note, and update_capsule replaces one named section rather than rewriting the file. When a decision replaces an older one, the tool links the two instead of overwriting the old one. Every change is a plain Markdown edit you can review and revert in Git, and vulcanus hooks install refuses commits that break the vault's structure.
What happens when a decision changes?
The old decision stays as history and is marked, not deleted: the new one records supersedes:: with a link to the heading it replaces, and the old one gains superseded-by::. vulcanus doctor checks that both sides agree, recall tells an agent which decisions are no longer current, and a decision can carry valid-until:: so it expires instead of quietly going stale.
What does it cost, and what does it need?
Vulcanus is free and MIT-licensed. It needs Node 22.12 or newer and runs on macOS, Linux, and Windows. Install it with npm install -g @sunsato/vulcanus and run vulcanus; it is installed globally because the MCP server, skills, and commit hook all call the vulcanus command.
Your agents are only as good as their memory
Build it once. Keep it honest.
npm install -g @sunsato/vulcanus