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.
npx @sunsato/vulcanus
No account. Nothing leaves your machine. Node 18+.
◆ Import an existing AI history to seed your project tree? │ ● Codex local sessions — ~/.codex, 268 rollout sessions │ ○ ChatGPT data export — 16 conversation files │ ○ No, I'll define projects myself │ ◇ 257 conversations read, 23 project candidates found │ ◆ Project candidates │ ◼ Atlas 104 conversations, high confidence │ ◼ Northwind 58 conversations, high confidence │ ◻ Kiln 6 conversations, medium confidence │ ◆ Vault name Flora ◆ Your name Ada │ ◇ 103 notes and 567 links validated └ Flora → ~/Flora
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.
YourVault ├─ AGENTS.md # how agents behave here ├─ vulcanus.json # the source of truth ├─ 00_System/ │ ├─ Index # the map │ ├─ Recall Map # triggers → the right note │ ├─ Admin Profile # who you are, how you work │ └─ Rules # what not to invent ├─ 02_Projects/ │ └─ Atlas/ │ ├─ Atlas Capsule # read this first │ ├─ Atlas Hub # navigation │ ├─ Atlas Context # identity and scope │ ├─ Atlas Decisions # confirmed choices │ └─ Atlas Rules # future constraints └─ _imports/ # raw exports, git-ignored
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.
Anything unconfirmed lives under Needs Confirmation and is never presented as fact. Corrections outrank older notes by design.
Every change is a commit. You can see when a decision changed, what it replaced, and why — the part chat history can never give you.
You have thousands of conversations describing your projects. The first question Vulcanus asks is whether to read them.
| 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 |
The vault is plain Markdown you can edit by hand in Obsidian or any editor. These keep it consistent as it grows.
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 from an AI export, any time after setup.
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.
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.
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.
AGENTS.md, CLAUDE.md, and
.cursor/rules ship with the vault. Open the folder in Codex, Claude
Code, or Cursor and the protocol is already in effect.
Most work happens in other repositories and in ordinary chat. Run
vulcanus agents and 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.
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.
Build it once. Keep it honest.
npx @sunsato/vulcanus
Open source, MIT licensed — read the source on GitHub.