A
licenseA
qualityA
maintenanceLocal, searchable project memory for AI coding agents. Markdown source of truth, MCP interface, safe structured updates
3
13
Apache 2.0
Vulcanus
This MCP server exposes a Vulcanus vault as structured project memory, with read-only recall/search/validation tools plus tools that append decisions and rules and rewrite a capsule section.
recall— the entry point before working on a project: returns its Capsule (the must-remember summary) plus the read-next list for deeper context. Query by project name, id, or trigger word; when nothing matches, the error lists the projects that exist.search— layer-aware text search across the vault, with Capsule and Recall Map hits ranked first, so the cheapest sufficient note surfaces on top (default 20 hits, max 100).list_projects— the routing table: every project with its status, summary, trigger words, and capsule path. The cheapest way to see what exists first.append_decision— record an operator-confirmed decision in a project's Decisions note in the vault's Decision/Details format. Appends only; calling it twice records it twice.append_rule— add a durable, confirmed standing rule to a project's Rules note. Appends only.update_capsule— replace one Capsule section (Identity, Current Scope, Must Remember, Do Not Assume, Needs Confirmation) after the operator confirms the summary is wrong or incomplete. The generatedRead Nextsection cannot be written here.vault_status— one-shot health summary: projects, note counts, doctor result, stale capsules, git state.doctor— full structural validation returning every finding (unresolved links, missing frontmatter, unreachable projects, hubs not linking what they own), reported as errors or warnings. It never repairs.
Read-only tools: recall, search, list_projects, vault_status, doctor. Writing tools: append_decision, append_rule, update_capsule — all of which error when the project or target note is missing.
Allows using an existing Obsidian vault as the storage backend for the AI-readable memory vault, adding the memory structure to the vault.
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.
npm install -g @sunsato/vulcanus
vulcanusInstall 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.
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 product · 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.
Related MCP server: cardloom-mcp
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:
claude mcp add vulcanus -- vulcanus serve # Claude Code, or any MCP clientvulcanus skills --install # skills that run the real commands, in every repovulcanus agents # the block to paste into a tool's global instructionsMCP server, Skills, and Making agents actually use it below cover what each one exposes.
What it creates
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 GitEach project cluster is five notes plus any specialized ones you ask for:
Note | Holds |
| the compressed must-remember summary an agent reads first |
| navigation and cluster boundary |
| identity, definitions, scope |
| confirmed choices and corrections |
| constraints on future behavior |
| 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 |
|
| what this project is, so an agent knows how to place and summarize it |
|
| 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:
{ "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 |
|
Claude.ai data export |
|
Claude Code |
|
Codex |
|
Gemini CLI |
|
Cursor | per-workspace chat history ( |
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).
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 —
--jsonwith--memory-onlyreports 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
vulcanus init # create a vault, or add memory to an existing Obsidian vault (default command)vulcanus status # one-screen vault health: projects, notes, doctor result, git statevulcanus stats # token budget: what a cold-start agent reads, what recall savesvulcanus doctor # validate the vault against its manifestvulcanus add project # add projects and wire them into the graphvulcanus project remove "Name" # unlink a project; its notes move to _archive/
vulcanus project rename "Old" "New" # folder, notes, and every link, in one move
vulcanus project archive "Name" # mark it archived (--restore undoes it)vulcanus import # propose more projects from an AI export or a notes foldervulcanus serve # serve the vault to MCP clients: recall, search, append_decision, …vulcanus agents # print the block that makes your AI tools use the vaultvulcanus skills # agent skills that run these commands for youvulcanus update # bring the vault up to date with a newer CLIvulcanus sync "topic" # validate, then commit and push
vulcanus sync --watch # regenerate and revalidate on every edit; never commitsvulcanus hooks install # a pre-commit hook that refuses to commit a broken graphvulcanus completion zsh # completion script for bash | zsh | fish | pwshinit accepts --lang en|tr|de|es, --ai [cli], and a target directory; add project and import accept --ai [cli]; status and stats accept --json; doctor accepts --repair and --json; import accepts --source, --path, --ai-group [cli], --memory, --no-memory, --memory-only, --ai-extract [cli], --json, and --all; update accepts --dry-run, --force, --profile core|full, and --json; sync accepts --dry-run, --json, and --watch; skills accepts --raw, --install, and --force.
--verbose and --quiet work on every command, and --json implies quiet so machine-readable output owns stdout.
Exit codes are part of the contract: 0 the command did what it said, 1 the vault or the operation failed validation, 2 the command was used wrongly (no vault, bad flag), 130 cancelled at a prompt. Every failure prints what happened, why, and what to do next.
Scripting init
Every wizard question can be answered from a flag, so init also runs without a TTY — in CI, containers, or an agent's shell. A flag skips exactly its question; --defaults answers everything else with the default, and --dry-run prints the tree that would be created without writing:
vulcanus init ./vault --name ATLAS --operator Ada --projects "Meridian, Harbor" --defaults -y
vulcanus init ./vault --name ATLAS --defaults --dry-run # look before you leapThe full set: --name, --full-name, --tagline, --naming branded|generic, --profile core|full, --operator, --role, --aliases, --projects, --no-import, --git / --no-git, --defaults, --dry-run.
Filling the project notes
Whenever projects are added — by init, add project, or import — Vulcanus asks how their notes should get their content: answer the questions here, skip and write them yourself later, or hand the job to an AI CLI already installed on your machine.
The AI path probes your PATH for claude, codex, cursor-agent (also installed as agent), and gemini, offers only what is really there, and asks where each project's source code lives — proposing the directories your past Claude Code and Codex sessions ran in. Before anything starts it tells you which CLI is taking over your terminal, in which directory, and exactly which notes it has been told to write. Nothing is spawned without your confirmation, and that confirmation cannot be suppressed by a flag.
The short structural questions — hierarchy, grouping, which specialized notes to create — are asked in the terminal either way. They decide the folder layout and the generated system notes, and they have to be settled before a single file exists, while the AI session only starts once the notes are there. What the AI takes over is the note bodies, which is where the work actually is.
The CLI is asked to study the codebase, question you about what the code cannot answer, and write the cluster's notes to the vault's conventions. When the session exits, doctor runs immediately, so an edit that broke the graph is reported rather than discovered later.
Making agents actually use it
A vault nobody reads is a folder, so the enforcement layer ships with it.
Agents working inside the vault are already covered: AGENTS.md carries the full protocol, CLAUDE.md points Claude Code at it, and .cursor/rules/vault.mdc does the same for Cursor.
For everywhere else — other repositories, ordinary chat — run vulcanus agents. It prints a block naming your vault, its path, and its operator, to paste into a tool's global instructions:
Tool | Where it goes |
Claude Code |
|
Codex |
|
Cursor | Settings → Rules → User Rules |
ChatGPT | Settings → Personalization → Custom instructions |
Gemini CLI |
|
vulcanus agents --raw prints the snippet alone, so it can be appended straight to a file. Every generated vault also contains USING-WITH-AI.md with the same guidance.
Skills
Instructions are prose a model may or may not honour. A skill is a capability it can invoke, so "sync the vault" runs the real vulcanus sync instead of the model improvising an equivalent. Vulcanus writes one skill per vault operation, plus a recall skill that carries the Recall Map → Capsule → Hub → Context/Decisions/Rules routing:
Skill | Runs |
| nothing — it teaches the read order and the authority rules |
|
|
|
|
|
|
|
|
|
|
Skills follow the Agent Skills format: a directory per skill holding a SKILL.md with name and description frontmatter. The description is what decides whether a model reaches for the skill at all, so each one names the vault, the operator, and the phrasings that should trigger it.
Every vault ships its skills twice — .claude/skills/ for Claude Code, .agents/skills/ for Codex, Cursor, and Gemini CLI, which all read that vendor-neutral directory. Two copies of one text, versioned with the vault, so an agent opening the repository can act on day one. Tools without a skill mechanism keep the prose path; this adds a channel rather than replacing one.
That only covers agents working inside the vault, and the point of a second brain is recall from everywhere else. For that the skills have to live in your home configuration, which Vulcanus will not do behind your back:
vulcanus skills --installThat writes them to ~/.claude/skills/ and ~/.agents/skills/, with your vault's real path baked in so an agent in another repository knows where to run. It is the only thing Vulcanus writes outside the vault, it never happens during init, and it leaves existing files alone unless you pass --force. vulcanus skills on its own explains what would be installed; --raw prints the files.
sync pushes to a remote and update rewrites files, which is a lot of consequence for one sentence of chat. Both skills instruct the agent to show the --dry-run output and get your confirmation in that conversation first, and every skill is told to report the command's actual output and exit code rather than reporting success. Skills are managed files, so doctor --repair and update bring template improvements to existing vaults.
MCP server
vulcanus serve turns the vault into structured memory for any MCP client — Claude Code, Cursor, or your own agent runtime — instead of ad-hoc file reads:
Tool | Does |
| returns a project's Capsule plus the read-next list — the protocol's entry point — and names any decisions or rules that are superseded or expired |
| layer-aware text search; Capsule and Recall Map hits rank first, hits in superseded or expired sections rank last and say so |
| the routing table: names, statuses, trigger words, capsule paths |
| records a confirmed decision in the Decision/Details format; with |
| records a standing rule in the project's Rules note; with |
| replaces one section of a Capsule — never a blind whole-file rewrite |
| the |
| full structural validation with every finding |
Register it the way your client expects, e.g. for Claude Code:
claude mcp add vulcanus -- vulcanus serveRun it from inside the vault (or any subdirectory), or pass --cwd when the client starts elsewhere. Registering it globally is fine: the server starts anywhere, and in a directory with no vault the tools say so instead of the server failing to come up. The manifest and the vault location are both resolved on every call, so a vault created — or edited — while the server runs is visible immediately.
recall also tells the truth about its own freshness: when a Capsule is older than the Decisions, Rules, or Context beneath it, the answer carries a staleness warning instead of presenting an outdated summary as current.
Obsidian
The vault is a valid Obsidian vault the moment it exists — no plugin, no import. Open the folder and the graph is there, with shortest-path wikilinks and rename-safe links already configured.
Already keep an Obsidian vault? Run init inside it and Vulcanus adds the memory structure to that vault instead of creating a separate one beside it — a directory with a .obsidian folder, in the current directory or an immediate subdirectory, is detected automatically. A single detected vault is used without asking, and its identity is taken from the folder, so there is no vault name to answer; only a choice between several vaults is ever put to you. Your own notes are never overwritten — generated files are written only where nothing exists — and if the folder is already a Vulcanus vault, init stops and points you to add project or update.
The graph view doubles as a health check: projects appear as clusters, hubs at their centers, and an unlinked note stands out immediately. Edits made in Obsidian are plain Markdown, so the CLI and your agents pick them up straight away, and vulcanus doctor keeps hand edits, agent edits, and generated structure consistent.
Staying current
vulcanus.json records the CLI version that last wrote the vault. When a newer CLI runs against an older vault, doctor warns and vulcanus update:
runs any manifest schema migrations
refreshes the files the CLI owns, so template improvements reach existing vaults
creates notes a newer version added (including a
--profile fullupgrade)re-stamps the generator version and validates the result
Your own notes are never rewritten — update reports how many it left untouched. That includes the Index, the hubs, and the Import Log: they hold what you wrote, so a new project or a deeper system layer is linked in rather than regenerated. AGENTS.md is merged — sections you added stay, sections the protocol adds arrive. --dry-run shows the plan first, and notes the manifest no longer describes are listed rather than deleted. A vault written by a newer CLI is refused outright instead of being downgraded.
After a command, the CLI checks npm at most once a day and prints a one-line notice when a newer release exists. Set VULCANUS_NO_UPDATE_CHECK=1 (or NO_UPDATE_NOTIFIER, or run in CI) to turn it off; it fails silently offline.
Validation
vulcanus doctor is the part that keeps a growing vault honest. Every check is derived from vulcanus.json, so it stays correct as your tree changes:
frontmatter completeness (
type,project,status,tags) and duplicate or empty keysevery wikilink resolves, and resolves to exactly one note
every hub links to the notes the manifest says it owns
every project note links back to its own hub
every project has a Capsule reachable from the Recall Map
no duplicate or case-colliding note names
raw exports and generated state are actually ignored by Git
AGENTS.mddescribes the agent protocol this CLI writes, not a superseded onethe skill copies in
.claude/skills/and.agents/skills/have not drifted apartevery
supersedes::/superseded-by::link points at a real heading, both sides agree, and nothing supersedes itself in a loopno decision is past its
valid-until::date while still presented as current, and no Capsule links one that is
Missing structure is an error; extra hand-added links are a warning, because a vault is meant to be written in.
When a decision changes
A decision that stops being true is not deleted — it is history, and "why did we stop doing X" is a fair question. It is marked instead, with fields under its heading:
## Usage-Based Pricing
supersedes:: [[Acme Decisions#Flat Pricing]]
### Decision
Price per active seat.## Flat Pricing
superseded-by:: [[Acme Decisions#Usage-Based Pricing]]
superseded-on:: 2026-10-05A decision that holds only until a date carries valid-until:: 2026-12-31. The keys are English in every vault language; they are fields, not prose. The same fields work on rules.
Write one side and vulcanus doctor --repair adds the other — it inserts the missing back-reference and touches nothing else. append_decision and append_rule write both sides in one call when given supersedes, and refuse, writing nothing, when the target does not exist or is already superseded. recall lists what is no longer current so an agent skips it, search ranks it last, and vulcanus status counts it.
vulcanus sync refuses to commit while errors remain, and reports the push result exactly as it happened.
Editing safety
Generated files fall into three classes:
seed — everything that can hold what you wrote: every project note, the Recall Map, the Index, every hub, and the Import Log. Written once, never overwritten. Adding a project or deepening the system layer inserts the missing links surgically instead of regenerating the file around them.
managed — files the CLI fully owns:
CLAUDE.md, the Cursor rule, and the generated skills.doctor --repairrewrites these.merge —
AGENTS.mdalone. It has to be both: the protocol every agent reads, so a new step must reach existing vaults, and a file you extend with instructions of your own. An update keeps every section you already have, inserts the ones the protocol added, and refreshes its version stamp. Wording changes to a section you customized will not reach you — losing your customization would be worse.
--force still rewrites everything, including your own notes. It is the only flag that does.
Vault naming
The vault name you choose becomes the vault's identity: with the default branded naming, system notes are ATLAS Index.md, ATLAS Recall Map.md, and so on, and the vault folder is named after it — so Obsidian opens it under that name. Choose generic naming for portable Index.md / Recall Map.md filenames instead.
The generated vault is Obsidian-ready: shortest-form wikilinks, links that follow renames, and workspace files kept out of Git.
Development
npm install && npm run build && npm testnpm run dev -- doctorSource layout: manifest/ derives every path and link expectation, generate/ turns that plan into Markdown, doctor/ validates the result against the same plan, importers/ normalizes AI exports, mcp/ holds the transport-free vault operations serve exposes, and commands/ wires it to the CLI.
CONTRIBUTING.md covers the checks, the review bar, and how to add an importer or a language. docs/token-budget.md measures what the layered structure actually saves, and how that was measured.
The landing page for vulcanus.sunsato.com lives in site/ — a single static file served by Cloudflare Workers as static assets (wrangler.jsonc). It reaches production through a promotion chain: each release is packaged once, tested on a webtest copy closed to search engines, and only that tested package goes live after approval. Releases run the full CI matrix before publishing and smoke-test the published package afterwards; CONTRIBUTING.md has the details.
License
MIT © Sunsato
Available Tools
8 toolsappend_decisionRecord a decisionA
Append a confirmed decision to a project's Decisions note, in the vault's Decision/Details format. Only record what the operator has actually confirmed. When it replaces an earlier decision, pass that decision's heading as supersedes: the new section records supersedes::, and the old one gains superseded-by:: and superseded-on:: under its heading but is otherwise left as history — never delete or rewrite the old decision yourself. Writes to disk: it adds to the end of the note, so calling it twice records the decision twice. Returns the note path and the heading written; errors when the project or its Decisions note is missing, or when supersedes names no live section (then nothing is written).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Short heading for the decision | |
| details | No | Optional supporting details | |
| project | Yes | Project name, id, or trigger word | |
| decision | Yes | The decision itself, one or two sentences | |
| supersedes | No | Heading of the existing decision this one replaces, if any |
TDQS
A4.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses that this writes to disk, appends rather than replaces (matching non-idempotent behavior), never deletes or rewrites history even when superseding, and enumerates error conditions (missing project/note, dead supersedes target, nothing written). It does not spell out permission or concurrency behavior, so it is strong but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and side effects, and every sentence carries information (format, confirmation rule, supersede mechanics, disk behavior, return value, failures). It is dense and long, but not padded; a lighter touch on return/error detail would have tightened it further.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, yet the description compensates by naming the return payload (note path and heading written) and the failure modes. Combined with the mutation disclosures, an agent has everything required to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for supersedes: what value to pass, what markers get written where, and the non-destructive side effect on the older section. title/decision/project are only implicitly clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Append) and resource (a confirmed decision to a project's Decisions note) plus the target format. The resource naming (decisions vs. the sibling append_rule's rules) makes it self-evidently distinct from siblings without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives the operative precondition ('Only record what the operator has actually confirmed') and precise routing rules for the optional supersedes parameter, including the fact that a bad supersedes value writes nothing. It also warns that repeat calls duplicate the entry, which is exactly the when-not guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
append_ruleRecord a ruleA
Add a durable rule to a project's Rules note. Rules are standing constraints the operator has confirmed — how to work on this project, what never to assume — not observations about one conversation. Use append_decision instead for a choice that was made, and update_capsule when the summary itself is now wrong. When it replaces an earlier rule, pass that rule's heading as supersedes; the old rule is marked superseded-by:: and kept as history. Writes to disk: it appends, so calling it twice records the rule twice. Errors when the project or its Rules note is missing, or when supersedes names no live rule (then nothing is written).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Short name for the rule, e.g. "Naming" | |
| rule | Yes | The rule itself, in one or two sentences | |
| project | Yes | Project name, id, or trigger word | |
| supersedes | No | Heading of the existing rule this one replaces, if any |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the annotations: append semantics ('calling it twice records the rule twice', consistent with idempotentHint=false), the non-destructive supersede path (old rule marked `superseded-by::` and retained), and precise failure conditions (missing project/Rules note, or supersedes naming no live rule, in which case nothing is written). These are the exact details an agent needs before a write.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then disambiguation, then the supersede mechanism, then failure modes. Each sentence carries distinct information a caller needs; there is no filler or restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by describing side effects on disk, the supersede bookkeeping, and the error/no-write cases. For a 4-parameter write tool with annotations, this leaves no material gap an agent would need to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for `supersedes`: it takes the heading of an existing rule, triggers a `superseded-by::` marker on that rule, and errors if no live rule matches. That goes beyond the schema's one-line gloss, though `name`, `rule`, and `project` remain schema-only.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource ('Add a durable rule to a project's Rules note') and immediately distinguishes this artifact type from adjacent ones ('standing constraints... not observations about one conversation'). An agent can tell it apart from append_decision, update_capsule, and recall without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use ('standing constraints the operator has confirmed'), explicit when-not-to-use, and names the alternatives with their selecting conditions: append_decision for 'a choice that was made', update_capsule 'when the summary itself is now wrong'. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
doctorValidate the vaultARead-only
Run the full structural validation and return every finding: unresolved links, missing frontmatter, projects unreachable from the Recall Map, hubs that do not link what they own. Read-only — it reports and never repairs; repairing is vulcanus doctor --repair in a terminal. A finding is an error (structure the manifest requires is missing) or a warning (something added by hand that the manifest does not describe).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already mark readOnlyHint=true, the description adds valuable behavioral detail: it never repairs, it returns every finding, and it defines the two kinds of findings (error vs warning). This goes well beyond the annotation and gives the agent a clear model of what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences packed with essential information, front-loaded with the verb and subject. No fluff—each clause adds value, including the error/warning distinction and the repair pointer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description fully describes what the tool returns (all findings) and how to interpret them (error vs warning). Given the zero-parameter simplicity and strong annotations, this is complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is little to explain. The description implicitly signals that no configuration is needed by saying 'Run the full structural validation' without mentioning any inputs, matching the schema's 100% coverage baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('Run the full structural validation') and enumerates concrete finding categories (unresolved links, missing frontmatter, etc.), making the tool's purpose unmistakable. It also distinguishes itself from repair by explicitly separating reporting from the terminal repair command.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states this tool validates and reports, and explicitly directs repair to the terminal command `vulcanus doctor --repair`, providing an important when-not-to-use boundary. It does not explicitly compare to sibling tools like vault_status, but the validation scope is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_projectsList projectsARead-only
The routing table: every project with its status, summary, trigger words, and capsule path. Read-only, and the cheapest way to see what exists before calling recall or search.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already covers safety, and the description reinforces it with 'Read-only'. Beyond that, it adds valuable context: the tool returns a routing table of every project, including fields, and is 'cheapest' in terms of cost. No behavioral contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, densely packed with information. It front-loads the core purpose ('routing table'), immediately lists what is returned, and adds usage guidance. Every word contributes value with no redundancy or bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description must explain return values—it does, listing status, summary, trigger words, and capsule path. It also covers read-only nature, performance ('cheapest'), and usage context relative to sibling tools. For a simple list tool with no parameters, this is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty, so there is nothing to explain. Baseline for 0-param tools is 4. The description adds no new parameter information, but none is needed. It does clarify the scope ('every project'), which gives context about what the lack of parameters means.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all projects with specific fields (status, summary, trigger words, capsule path). The verb 'list' is specific and the resource is unambiguous. It also distinguishes from siblings by framing it as a routing table and the cheapest way to inspect available projects before using recall or search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly indicates when to use this tool: before calling recall or search, as it's the cheapest read-only way to see what exists. It names alternatives (recall, search) and clarifies the read-only nature, providing clear context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
recallRecall a projectARead-only
The entry point before working on any project: returns its Capsule (the compressed must-remember summary) plus the read-next list for deeper context, and lists any decisions or rules that are superseded or expired so you do not act on them. Query by project name, id, or a trigger word. Read-only; when nothing matches, the error lists the projects that exist.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name, id, or trigger word |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so 'Read-only' is redundant. The description earns credit for disclosing non-structured behavior: the return payload contents (Capsule + read-next list + superseded/expired decisions) and the no-match failure mode that returns an error listing existing projects. It does not cover freshness, pagination, or auth, but those are minor here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One information-dense sentence, front-loaded with the tool's role before its return contents. Every clause earns its place, though the multiple em-dash-free clauses make it slightly run-on and harder to scan than a two-sentence split would be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of describing returns and does so: Capsule, read-next list, superseded/expired decisions, and the no-match error. For a single-parameter read tool with supporting annotations, nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter is already documented as 'Project name, id, or trigger word'. The description's 'Query by project name, id, or a trigger word' restates that verbatim, adding no new syntax or matching rules (e.g., how trigger words resolve). Baseline 3 for a fully documented schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource ('returns its Capsule ... plus the read-next list') and frames the tool's role as 'the entry point before working on any project'. That framing lets an agent distinguish it from siblings like search and list_projects without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'The entry point before working on any project' is an explicit when-to-use statement, and the error behavior ('when nothing matches, the error lists the projects that exist') implicitly routes discovery to list_projects. It stops short of naming alternatives or stating when NOT to use recall, so it is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
searchSearch the vaultARead-only
Layer-aware text search across the vault. Capsule and Recall Map hits rank first so the cheapest sufficient note surfaces on top; hits inside superseded or expired sections carry a state and rank below every live hit. Read-only; prefer recall when you already know which project you need.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max hits, default 20 | |
| query | Yes | Text to look for |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: ranking order (Capsule and Recall Map hits first), the `state` marker on superseded/expired hits, and that those rank below live hits. It stops short of describing pagination or result shape, but the ranking semantics are genuinely useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the tool's identity and scope before ranking detail and the routing hint. No filler; every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by explaining hit ordering and the `state` field, so an agent understands what comes back. It is complete for a read-only search tool, with only minor gaps (no mention of result count behavior).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both `query` and `limit` (including the default of 20 and the 1-100 range). The description adds no syntax, format, or query-language guidance, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Layer-aware text search across the vault') with the distinguishing scope trait ('layer-aware') front and center, and names the sibling `recall` as the alternative. An agent can tell it apart from `recall` without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: 'prefer `recall` when you already know which project you need,' which implies search is the choice when the project is unknown. That is a clear alternative-selection rule, though it doesn't spell out the converse case directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update_capsuleRefresh a capsule sectionADestructiveIdempotent
Replace one section of a project's Capsule — the compressed summary every recall reads first. Use it after the operator confirms something that makes the summary wrong or incomplete; never to record a guess. Read Next is generated and cannot be written here. Writes to disk and overwrites that section's previous contents, which are recoverable only from Git; every other section and the rest of the file are left untouched. Errors when the project or its Capsule is missing.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The section's new Markdown body, without the heading itself | |
| project | Yes | Project name, id, or trigger word | |
| section | Yes | Which capsule section to replace |
TDQS
A4.6/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructive, idempotent), the description discloses important behaviors: it 'Writes to disk and overwrites that section's previous contents', notes recovery is 'only from Git', asserts other sections are untouched, and clarifies it 'Errors when the project or its Capsule is missing'. This gives the agent a full picture of side effects and failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four targeted sentences: action, usage condition, side effects/constraint, and error behavior. No redundant wording, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the purpose, usage, side effects, recovery, and error conditions, which is substantial for a simple update tool. However, there is no output schema and the description does not state what the tool returns on success or failure, leaving a small gap for an agent planning its next action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds general context about the Capsule and the body content ('never to record a guess') but does not add specific syntax or format details beyond the schema. It doesn't elevate the parameter understanding significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Replace one section of a project's Capsule' and the title 'Refresh a capsule section', clearly stating the verb and resource. It also distinguishes itself from siblings like recall/search (read-only) and append_decision/append_rule (appending) by explicitly noting 'Read Next is generated and cannot be written here' and framing this as a targeted replacement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use: 'Use it after the operator confirms something that makes the summary wrong or incomplete', and a clear exclusion: 'never to record a guess'. It also explains that Read Next cannot be written, guiding the agent away from attempting that section. This is strong usage guidance without naming alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
vault_statusVault statusARead-only
One-shot health summary: projects, note counts, doctor result, stale capsules, git state. Read-only — it inspects the working tree and reports, and writes nothing. Use doctor when you need every validation finding rather than the summary.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already include readOnlyHint=true, and the description adds behavioral specificity: 'it inspects the working tree and reports, and writes nothing.' It also discloses the scope of the summary (projects, note counts, doctor result, stale capsules, git state), which goes beyond the bare annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and front-loads the core purpose immediately. Every clause earns its place: the list of summary contents, the read-only guarantee, and the pointer to 'doctor' are all high-value information delivered with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description enumerates exactly what kind of information the summary includes (projects, note counts, doctor result, stale capsules, git state), which is sufficient for an agent to set expectations. The tool has no parameters and is a read-only health summary, so no additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters, so the baseline is 4. The description naturally includes no parameter details because none exist, and it does not need to compensate for schema gaps since there are no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies a specific resource ('vault') and a specific action ('one-shot health summary') with concrete contents: projects, note counts, doctor result, stale capsules, git state. It also distinguishes itself from the sibling tool 'doctor' by noting this is a summary rather than exhaustive validation findings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool versus the alternative: 'Use `doctor` when you need every validation finding rather than the summary.' It also clarifies the tool is read-only and only inspects/reports, giving clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
2 tool updates
v0.6.3- Changed
append_decision1 field changed- added
Input schema / properties / supersedesAdded value: +{ + "description": "Heading of the existing decision this one replaces, if any", + "type": "string" +}
- Changed
append_rule1 field changed- added
Input schema / properties / supersedesAdded value: +{ + "description": "Heading of the existing rule this one replaces, if any", + "type": "string" +}
8 tool updates
v0.4.4- First observed
append_decision - First observed
append_rule - First observed
doctor - First observed
list_projects - First observed
recall - First observed
search - First observed
update_capsule - First observed
vault_status
TDQS
A4.4/5.0
Scored across 8 tools
Disambiguation4/5
The read tools (recall, search, list_projects) overlap in purpose but descriptions cross-reference each other well, steering the agent to the cheapest correct call. append_rule vs append_decision vs update_capsule are clearly differentiated by what they write. doctor vs vault_status is explicitly disambiguated (full findings vs summary).
Naming Consistency4/5
Four tools use a clean verb_noun pattern (list_projects, append_rule, append_decision, update_capsule), but the read/inspect tools break it with bare verbs (recall, search, doctor) and one noun phrase (vault_status). Still readable and mostly predictable, with only minor deviations.
Tool Count5/5
Eight tools is well-scoped for a knowledge-vault server, covering retrieval, inspection, and targeted writes without redundancy. Each tool earns its place in the read/write/validate triad.
Completeness4/5
Core lifecycle is covered: read (recall, search, list_projects), validate (doctor, vault_status), and targeted writes (append_rule, append_decision, update_capsule) with supersede handling. Project/note creation and deletion are absent, but those appear intentionally delegated to the terminal, leaving only minor gaps.
Maintenance
ActivityActive
ResponsivenessNo issues
Related MCP Connectors
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Personal context for every AI: search, read, and write back to your private Markdown library.
Recall authorized Vault notes with keyword and hybrid search, original excerpts, and source paths.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides long-lived, cross-project technical memory for AI agents via markdown cards stored in git and indexed by SQLite, enabling search, retrieval, and human-reviewed knowledge management.ISC
- AlicenseNot gradedqualityBmaintenanceExposes a living systems memory vault to autonomous agents, letting them search notes with BM25 ranking, read sections within token budgets, extract API/port/schema contracts, compute dependency blast radius, and run machine-verifiable invariant assertions before mutating code. It also supports surgical frontmatter edits, schema linting, wikilink integrity checks, and worklog recording, over stdio MCP.MIT
- AlicenseNot gradedqualityBmaintenanceGives AI agents a long-term memory layer over plain Markdown notes, letting them run ranked, citable searches, record new facts, and inspect conflicts and stale entries. Results carry freshness labels, supersession history, and audit fields like search timestamp and no-match status so agents can prove a search actually ran.MIT