Vulcanus

# 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.

```bash
npm install -g @sunsato/vulcanus
vulcanus
```

Install it globally: the MCP server (`vulcanus serve`), the skills, and the commit hook all run the `vulcanus` command, so it has to be on your PATH. `npx @sunsato/vulcanus` works for a one-off look, but nothing you wire to your agents can reach it.

![Creating a vault with vulcanus init, then checking it with status and stats](https://raw.githubusercontent.com/sunsatosolutions/Vulcanus/main/docs/demo.gif)

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. It runs locally: no account, and no automatic network call beyond an optional once-a-day version check. Upgrade with `npm install -g @sunsato/vulcanus@latest`.

A [Sunsato](https://sunsato.com) product · [vulcanus.sunsato.com](https://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:

```bash
claude mcp add vulcanus -- vulcanus serve   # Claude Code, or any MCP client
```

```bash
vulcanus skills --install   # skills that run the real commands, in every repo
```

```bash
vulcanus agents             # the block to paste into a tool's global instructions
```

[MCP server](#mcp-server), [Skills](#skills), and [Making agents actually use it](#making-agents-actually-use-it) below cover what each one exposes.

## What it creates

```txt
YourVault
├─ AGENTS.md              # the protocol AI agents must follow in this repo
├─ CLAUDE.md              # points Claude Code at that protocol
├─ USING-WITH-AI.md       # how to make every tool recall this vault
├─ README.md
├─ vulcanus.json          # the manifest everything is derived and validated from
├─ .claude/skills/        # invocable skills for Claude Code
├─ .agents/skills/        # the same skills for Codex, Cursor, and Gemini CLI
├─ 00_System/             # Index, Recall Map, Admin Profile, Rules, Update Format …
├─ 02_Projects/           # one cluster per project
└─ _imports/              # raw AI exports, ignored by Git
```

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:

```json
{ "systemNotes": ["Release Notes", "Semantic Index Strategy"] }
```

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 unless you accept it.** 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.

### Decisions you already made

Your history usually holds more than project names: the choices you settled and the rules you kept repeating. After the project step, `import` asks whether to look for them (`--memory` says yes up front, `--no-memory` skips the question, and `--memory-only` skips project discovery for a vault that already has its projects).

- Only **your own messages** are read. An assistant's sentence is not your decision.
- Sentences are matched against decision and rule phrases in English, Turkish, German, and Spanish — "we decided", "from now on", "karar verdik", "ab sofort", "a partir de ahora" — and ranked by how strong the phrase is, how many conversations repeat it, and how recent it is. Questions and code are ignored.
- A conversation counts toward a project when its source grouped it there or its title names the project. Body mentions do not.
- What the vault already records is dropped. A candidate that looks like a revision of a live decision is offered as its **replacement**, so the old one is marked rather than contradicted (see [When a decision changes](#when-a-decision-changes)).
- You review each candidate: accept as decision, accept as replacement, accept as rule, edit the wording, skip, or stop. At most 15 per project per run. Nothing is accepted unattended — `--json` with `--memory-only` reports counts only.
- What you accept is written in the wording you accepted, with a `source:: import · <source> · <date>` line. Skipped candidates are discarded, and reviewed conversations are remembered so they are not proposed again (separately from project discovery, so one never hides conversations from the other).

`--ai-extract [cli]` hands the candidate sentences — not transcripts — to an installed AI CLI to merge duplicates, drop noise, and tighten wording, after showing you what will be sent. Anything it returns that does not trace back to a sentence it was given is discarded.

## Commands

```bash
vulcanus init            # create a vault, or add memory to an existing Obsidian vault (default command)
```

```bash
vulcanus status          # one-screen vault health: projects, notes, doctor result, git state
```

```bash
vulcanus stats           # token budget: what a cold-start agent reads, what recall saves
```

```bash
vulcanus doctor          # validate the vault against its manifest
```

```bash
vulcanus add project     # add projects and wire them into the graph
```

```