A Sunsato product

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.

$ npx @sunsato/vulcanus

No account. Nothing leaves your machine. Node 22.12+.

vulcanus init 
◆  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

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. 

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

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. You can see when a decision 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 doctor checks.

Start from what you already said

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
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
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 confirm become notes, and the import log records how many conversations were scanned — never their content.

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.

Thirteen commands

The vault is plain Markdown you can edit by hand in Obsidian or any editor. These keep it consistent as it grows.

init

Answer the questions, get a validated vault. This is the default command.

doctor

Validate structure, links, and coverage against the manifest.

add project

Add a project and wire it into the graph — routes, hubs, and links included.

import

Propose more projects from an AI export, any time after setup.

agents

Print the block that makes your AI tools recall the vault from everywhere.

skills

Generate agent skills that run these commands, and install them where agents look.

update

Bring an existing vault up to a newer CLI, without touching your writing.

sync

Validate, then commit and push. It refuses to commit a broken vault.

status

One screen: projects, notes, doctor result, git state, and stale capsules.

stats

What a cold-start agent must read, and how much task-scoped recall saves.

serve

Expose the vault to MCP clients as typed tools instead of raw file reads.

project

Remove, rename, or archive a project — every link and route follows.

hooks

A pre-commit hook that keeps a broken memory graph out of your history.

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.

recall

One 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, or when the project is one you marked private.

search

Layer-aware: Capsule and Recall Map hits rank above everything else.

append_decision · append_rule

Confirmed outcomes go back into the right note, in the vault's own format.

update_capsule

Refresh one section of a summary — never a blind whole-file rewrite.

claude mcp add vulcanus -- vulcanus serve

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.

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%
A six-project vault, freshly generated. A capsule costs about a fifth of its cluster, and the entry layer is paid once per session — so each further task costs roughly 200 tokens to route instead of a full re-read. Counts are estimated at ~4 characters per token: the ratio is the measurement, not the absolute number, and the write-up is explicit about what it does not prove.

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.

Your writing is never overwritten. Notes, hubs, and the index hold what you wrote, so an upgrade links a new project in rather than regenerating the file around it. The agent protocol is merged: sections you added stay, sections the protocol gained arrive.
  • 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

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/rules ship 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 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
CursorSettings → Rules → User Rules
ChatGPTSettings → Personalization → Custom instructions
Gemini CLI~/.gemini/GEMINI.md
vulcanus agents 
## 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.

Both directions stay in sync. Write in Obsidian, let an agent write through the protocol, or edit by hand — it is one Git repository either way, and vulcanus doctor keeps all three honest.
Already have a vault? 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.
Index Project hubs Notes

Your agents are only as good as their memory

Build it once. Keep it honest.

$ npx @sunsato/vulcanus

Open source, MIT licensed — read the source on GitHub.