Allows using an existing Obsidian vault as the storage backend for the AI-readable memory vault, adding the memory structure to the vault.
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.
npx @sunsato/vulcanus
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. Nothing leaves your machine: no account, no network call beyond an optional once-a-day version check.
A Sunsato product · vulcanus.sunsato.com
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: agent-memory
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.
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.
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.
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.
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. 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.
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], --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.
initEvery 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.
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.
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.
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.
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 |
| layer-aware text search; Capsule and Recall Map hits rank first |
| the routing table: names, statuses, trigger words, capsule paths |
| records a confirmed decision in the Decision/Details format |
| records a standing rule in the project's Rules note |
| 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.
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.
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 full upgrade)
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.
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 keys
every 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.md describes the agent protocol this CLI writes, not a superseded one
the skill copies in .claude/skills/ and .agents/skills/ have not drifted apart
Missing structure is an error; extra hand-added links are a warning, because a vault is meant to be written in.
vulcanus sync refuses to commit while errors remain, and reports the push result exactly as it happened.
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 --repair rewrites these.
merge — AGENTS.md alone. 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.
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.
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 with no build step, deployed to Cloudflare Workers as static assets (wrangler.jsonc) on every push to main.
MIT © Sunsato
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. Writes to disk: it adds to the end of the note and never edits what is already there, 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.
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations all being false, the description explicitly discloses write side effects, append-only behavior, non-idempotency ('calling it twice records the decision twice'), and error conditions when the project or note is missing. It also says it never edits existing content, going well beyond the annotation fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences: purpose, key constraint, and side effects/return/errors. It is front-loaded, concise, and every sentence carries essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description states what it returns (note path and heading) and when it errors. With all parameters documented in the schema and the tool's non-idempotent behavior explicitly disclosed, the description is fully sufficient for an agent to invoke this tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers 100% of parameters with descriptions, so the baseline is 3. The description adds the Decision/Details format context but does not elaborate on individual parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: 'Append a confirmed decision to a project's Decisions note' in a defined format. It includes the resource (project Decisions note), the operation (append), and a format constraint, making it distinct from siblings like append_rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use it only for confirmed decisions, and it warns about duplication on repeated calls. It does not explicitly mention when to prefer alternatives like append_rule, but the decision-vs-rule distinction is implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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. Writes to disk: it appends and never edits existing rules, so calling it twice records the rule twice. Errors when the project or its Rules note is missing.
| 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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond annotations by describing side effects: 'appends and never edits existing rules, so calling it twice records the rule twice.' Also discloses error conditions when the project or Rules note is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences pack purpose, definition, alternative guidance, and error behavior without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a write tool with 3 required params, no output schema, and no annotations beyond safety hints. Covers concept, side effects, duplicate-call consequence, error conditions, and sibling differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, but the description enriches the meaning of 'rule' by defining it as 'standing constraints the operator has confirmed' and contrasting with observations. This adds context beyond the schema's basic field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Add a durable rule to a project's Rules note.' It distinguishes from siblings by contrasting with 'append_decision' and 'update_capsule', clearly defining what qualifies as a rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides when to use alternatives: 'Use `append_decision` instead for a choice that was made, and `update_capsule` when the summary itself is now wrong.' Also clarifies what counts as a rule versus a one-time observation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
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.
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.
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.
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.
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.
The entry point before working on any project: returns its Capsule (the compressed must-remember summary) plus the read-next list for deeper context. Query by project name, id, or a trigger word. Read-only; when nothing matches, the error lists the projects that exist.
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | Project name, id, or trigger word |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only.' It adds meaningful behavioral context by explaining the return value (Capsule + read-next list) and the error behavior (lists existing projects when nothing matches), which goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the primary purpose and value, and every sentence adds useful detail: what it returns, how to query, and side effects/error behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter, read-only tool with no output schema, the description covers purpose, return content, query method, and error behavior. It is sufficiently complete for an agent to select and invoke the tool without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a 100% description for the single 'project' parameter as 'Project name, id, or trigger word.' The tool description largely repeats this same information ('Query by project name, id, or a trigger word') without adding new details about format, examples, or edge cases, so it does not exceed the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that 'recall' returns a project's Capsule summary plus a read-next list, identifying the exact resource and action. It also positions itself as 'the entry point before working on any project,' effectively distinguishing it from sibling tools like 'search' and 'list_projects.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool: 'before working on any project.' It does not, however, explicitly state when not to use it or point to alternatives, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Layer-aware text search across the vault. Capsule and Recall Map hits rank first so the cheapest sufficient note surfaces on top. Read-only; prefer recall when you already know which project you need.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max hits, default 20 | |
| query | Yes | Text to look for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds 'Read-only' which is consistent. It further discloses ranking behavior (Capsule and Recall Map hits rank first) and the 'cheapest sufficient note' prioritization, providing valuable behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every sentence contributes meaningful information (what it does, ranking behavior, read-only, and when to use alternative). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, both documented), annotations cover the read-only aspect, and the description explains the ranking behavior and sibling differentiation. It is complete enough for an agent to invoke correctly without needing more details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% since both `query` and `limit` have descriptions. The description adds no additional parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'layer-aware text search across the vault', using a specific verb and resource. It also distinguishes itself from the sibling tool `recall` by noting that `recall` is preferable when you know which project you need, making the tool's unique purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly guides the agent to prefer `recall` when the project is already known, providing a clear when-to-use alternative. This gives actionable context for selecting between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| 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 |
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.
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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.
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.
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.
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.
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.
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.
Each tool has a clear, distinct purpose: recall for capsule retrieval, search for text search, list_projects for project routing, append_decision/update_capsule/append_rule for distinct write operations, and vault_status/doctor for health checks at different granularities. Descriptions explicitly cross-reference when to use which tool, eliminating ambiguity.
Most tools follow a verb_noun pattern (list_projects, append_decision, update_capsule, append_rule), but recall, search, and doctor are single verbs, and vault_status is a noun compound. The minor inconsistency is easy to read and does not hinder understanding.
With 8 tools, the set is well-scoped for a project memory and vault management server. Each tool earns its place, covering reading, searching, updating, and validating without bloat or redundancy.
The core workflows—accessing capsules, searching, updating summaries, appending decisions/rules, and checking health—are covered. Slight gaps exist: no direct tool to read decisions or rules (though search can find them) and no explicit project creation, but these may be out of scope for the vault's purpose.
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Portable AI memory shared across models and harnesses - plain markdown you own.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Project memory, semantic code search, and grounded agent context.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/sunsatosolutions/Vulcanus'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
