gosidian

Close a claimed handoff: sets status to done or rejected, stamps completed_by/completed_at, and optionally appends an '## Outcome' section to the note body. Only the token that claimed the handoff (or an admin token) can complete it.

Create a new note at the given path. Fails if the note already exists. Markdown (.md) is the default note format; a path ending in .html creates a native single-file HTML note (frontmatter in a leading HTML comment, indexed/linked like a .md, rendered sandboxed in the web UI) when the instance has html_notes enabled — see `capabilities` in memory_bootstrap. Reserve .html for intrinsically-HTML content (generated reports, self-contained dashboards); prefer .md otherwise. Size guard: content is capped (default 1 MiB) and costs ~1 token/char through the context — for a large body already on disk …

Create a handoff note that passes context from one agent to another. Stored at <project>/handoffs/YYYYMMDD-HHMMSS-<slug>.md (the server's local time, as created, which carries its offset) with frontmatter {type: handoff, from_agent, to_agent, status: pending, created, created_by}. created_by is stamped server-side from the caller's token identity; from_agent/to_agent are declarative role slugs. The destination agent picks it up via memory_pending_handoffs, takes it in charge with memory_claim_handoff and closes it with memory_complete_handoff. Use this instead of an ad-hoc note when control sw…

Create an image media note: upload (or reference) an image AND create the markdown note that points to it, in one call. The note is a normal .md (frontmatter `type: image` + `media:`), indexed/linked like any note. The body is the caption — WRITE A DESCRIPTIVE ONE: it is the only searchable text (image bytes are not indexed). Images only (png/jpg/jpeg/gif/webp/svg). Requires media_notes (see bootstrap `capabilities`). Provide the image ONE way, cheapest first: `attachment` (already-uploaded path), `bridge_filename`, `source_path`, or base64 `data` (last resort).

Create a new project (top-level folder) in the vault.

Create a CSV table note: upload (or reference) a CSV AND create the markdown note that points to it, in one call. The note is a normal .md (frontmatter `type: table` + `media:`), indexed/linked like any note; the web UI renders the CSV as a paginated table. Use it for long tabular data (audit reports, exports) instead of bloating a markdown body. Column headers + row count are inlined into the body for search; cell VALUES are not indexed — write a caption. Requires table_notes (see bootstrap `capabilities`). Provide the CSV ONE way, cheapest first: `attachment` (already-uploaded path), `bridge…

Delete a note from the vault and the index. With the server's trash on (trash_id in the result) the note can be restored from the web UI's trash, as one deleted there; otherwise it is gone.

Delete an attachment file from the vault. The file is permanently removed. Does not update notes that reference it.

Delete a project (top-level folder) and all notes inside, recursively. With the server's trash on (trash_id in the result) the project can be restored from the web UI's trash, with its access; otherwise it is gone. MCP tokens scoped to this project alone are revoked, and it is removed from the scope of tokens that list others (tokens_revoked, tokens_narrowed). Admin tokens only.

Replace a specific substring inside an existing note. Same semantics as the Edit tool in Claude Code: old_string must match exactly (whitespace included). With replace_all=false (default) the match must be unique; with replace_all=true every occurrence is replaced. Use this instead of memory_update when changing only part of a large note — orders of magnitude cheaper in tokens. Pass if_match for optimistic locking.

Find the attachments of a project that no file of the vault names any more (a note deleted or edited, an upload never linked), older than min_age_hours. A dry run (the default) only lists them, with size and age; with dry_run:false they go to the server's trash when it is on (restorable from the web UI), else they are deleted. References count from every project, canvases, bases and the trash, so a file another project uses, or a trashed note would need, stays. Use the dry run first and show the list before removing.

Read a note by its vault-relative path (e.g. 'project/note.md'). Oversize guard: when the body exceeds 24 KiB (and raw is not set) the response is truncated — frontmatter + heading outline + the first chunk, with truncated:true, the full size, and the note's real etag (if_match still works). Fetch just the section you need via memory_get_section, or pass raw:true only when you really need the whole body. To get a large note onto your own disk without spending context tokens, GET the HTTP /download endpoint instead (your MCP base URL plus /download?path=<path>, bearer token), or pass transfer:"…

Read only the YAML frontmatter of a note. Use this for cheap triage (check tag/status/type) before deciding whether to fetch the full body with memory_get. Returns both the raw YAML block and a parsed map of common fields.

Read the heading outline of a note (level + text + anchor id). Use to discover the structure of a long note so you can target a specific section with memory_get_section instead of fetching the whole body. A heading with views:N holds N ```view blocks: read that section with render_views:true to see their rows.

Read a single section of a note (heading + content up to the next heading of equal or higher level). Use when a note is long and you only need one section — much cheaper than memory_get on large files.

Before publishing a project (private→public), list the global-private notes it references via wikilinks, and for each which OTHER projects also reference it. Promoting any of them to the public global (e.g. with memory_move_note) is a deliberate, human-gated step — this tool only reports, it never moves anything. Returns an empty list when the global feature is off or nothing is referenced.

List the most-connected notes ("hubs"/"god nodes") ranked by undirected wikilink degree, descending. The inverse signal of orphan notes: hubs are where the vault graph concentrates. Pass `project` to scope to one top-level folder (degree then counts only intra-project links); empty = vault-wide. A token scoped to a single project may omit it (that project is used); a project outside the token's scope is refused with an error.

Save a file into the vault with automatic routing — the ONE tool for "store this file/report". Provide the file ONE way, cheapest first: `bridge_filename` (staged in the server's bridge dir), `source_path` (server-side path inside an allowed upload root), `url` (the server fetches it — allowlisted prefixes only), `attachment` (vault path of a file already uploaded), or base64 `data` (small files only). Remote agents with a shell: pass `transfer:"http"` instead of a source to mint a single-use upload URL, then POST the bytes there (no bearer needed). Routing by extension: .csv → table note, ima…

Produce an init-prompt payload for adopting gosidian as the memory layer in a project. Returns a `prompt` instructing the caller to create/update its agent-native instruction file plus a thin parametric `gosidian_block` stub to innest (Regola Zero pointing at memory_bootstrap; the operational directives are served by bootstrap, NOT embedded — ADR-010). Mode is picked by `existing_content`: augment (merge preserving existing sections) or from-scratch. All filesystem scanning/writing happens agent-side; `needs_scaffold=true` means call memory_project_scaffold first.

Run structural health checks on a project's notes. Returns issues grouped by severity (error/warning/info). Rules check: broken wikilinks, links to a heading that is not there (broken-anchor; an ID alone such as ADR-010 names "ADR-010 — …"), orphan notes, missing frontmatter, unknown tags (closed vocabulary violation; projects with the use_tag_vocabulary flag extend it via `tag_vocabulary:` in memory/conventions.md frontmatter — exact tags or ns:* wildcards), plan status incoherent with hot.md Active plans, oversized hot.md (it is inlined into every bootstrap payload), type:skill notes larger …

List attachments in the vault, optionally filtered by project. Returns path, size, MIME type, and modification time for each attachment.

List the bootstrap templates installed under <vault>/.gosidian/templates/. Each entry includes name, description, a human-readable prompt explaining when to pick it, the declared variables, and the number of files that would be created. Pair with memory_project_scaffold(project, template=<name>) to create a new project from a chosen template.

List notes in the vault, optionally filtered by project (top-level folder).

List all projects (top-level directories) in the vault with their note counts.

List tags with usage counts. When `project` is given, counts are scoped to notes under that project prefix; otherwise they are vault-wide. A token scoped to a single project may omit it (that project is used); a project outside the token's scope is refused with an error.

Move a note to a different project. Both the current and target locations must be inside the token's scope.

List notes in a project ranked by their frontmatter `importance` field (integer 1..5, default 3 when missing). Filtered to importance >= min_level and sorted DESC. Use this instead of memory_list_notes when you need the most important notes of a project for triage or pinned views. Convention: 5=critical, 3=default, 1=archival.

List notes that carry a specific tag. Pass `project` to restrict the results to one top-level folder. A token scoped to a single project may omit it (that project is used); a project outside the token's scope is refused with an error.

List wiki-links leaving the given note, with their resolved paths (if any); a link written in a frontmatter value carries its key in `field`. Pass include_cross_project=true to also flag links that point into a different top-level project via `cross_project: true` on each entry — scoped tokens always ignore this flag (they cannot see outside their project).

Find the shortest path between two notes over the undirected wikilink graph (resolved links only). Returns the ordered list of note paths from `from` to `to`, inclusive of both endpoints, or path:[] with found:false when they are not connected. Both endpoints must be inside the token's scope; if the shortest path traverses a note outside the caller's scope the call reports no reachable path rather than leaking foreign paths.

List handoff notes under a project, filtered by lifecycle status (default: pending) and optionally by destination agent. Use at session start when taking over from another agent, or with status=claimed/done to monitor handoffs in flight.

List pinned notes in a project. Convention: a note is pinned by adding 'pinned' to its frontmatter tags array. Pinned notes are those the author wants surfaced in every session — keep the list small.

Start, resume or cancel a pipeline run. start (the default): path names the pipeline note, input is the JSON object its nodes read as {{ trigger.… }} (pass files as vault paths, not bytes), idempotency_key starts it once for the same key, callback_url is POSTed the run's summary when it ends (only addresses in [pipelines] http_allowlist), wait (seconds, at most [pipelines] max_sync_wait, 60 by default) returns once the run ended or waits for a call (wait.call), with its steps and the output of the node the pipeline names as its answer, else at once with the run's id. resume: run (and step when…

Read the pipelines of a project (notes `type: pipeline` with a ```pipeline YAML block, run by the server when [pipelines] is on and the project has use_pipelines): with project only, the pipelines with their trigger, nodes, problems and last run, and the plugins with the node types they add (<plugin>.<node>, status ok when they run) and the tools they offer agents (<plugin>_<tool>, in the projects listed in exposed_in); with path, the runs of that pipeline, newest first; with run, one run with the status, error and output of each step. Start, resume or cancel a run with memory_pipeline_run. Fo…

List plans (notes with frontmatter type:plan) under a project, optionally filtered by status (draft/in-progress/done/archived). Returns path, title, status, updated and description from the frontmatter; the status comes from the status: field or, when the note has none, its status: tag. For other filters (updated after a date, importance, several statuses, fields to return) use memory_query, which answers with only the fields asked.

Populate a project with a bootstrap template. Templates live under <vault>/.gosidian/templates/<name>/ and can be inspected with memory_list_bootstrap_templates. Idempotent — existing files are skipped, never overwritten. Default template is "karpathy-wiki" (full Karpathy-Wiki-Stack layout); pass template="minimal" for a lightweight scaffold or template="team" for the team-oriented preset with pre-populated agents/.

Adopt a foreign, hand-written local agent file (a CLI subagent definition not produced by gosidian — no `gosidian:anchor` marker) into a canonical vault `type:agent` note, then return the anchor to replace it with. Use this when the bootstrap `anchors.reconcile` flow reports a foreign file and the USER confirms adoption: the file's content becomes a shared, version-controlled role at `<project>/agents/<slug>.md` (its system-prompt body preserved; name/tools captured into a `harness:` block), and the returned `anchor` is the thin local file (pulling the role from the vault) to write in place of…

Find notes by their frontmatter, like a Dataview filter: every condition in `where` must hold. A field is a frontmatter key (a list matches element by element); a namespaced tag counts as a field when the note has no field of that name (tag status:done → status = done), and `tags` is the tag list. created_by and modified_by are who created and last modified the note through gosidian (audit log), usable as fields; over the rows of a database (from its source) its rollup fields are computed when fields or sort names them. Operators: eq, ne, in, exists, lt, lte, gt, gte, contains. ISO dates and n…

List the most recently modified notes. Use to catch up with 'what changed since I was last here'. Returns path, title, and mtime (unix seconds) ordered by descending mtime.

Rebuild the `## Recent decisions` section of <project>/hot.md from the latest ADRs in memory/decisions.md and the latest plans with status:done. Opt-in: the target section of hot.md must be wrapped in `<!-- auto:recent-decisions -->` / `<!-- /auto -->` markers; without them the tool is a no-op. Safe to re-run; everything outside the markers is preserved verbatim.

Rename a note. Updates the index and rewrites wiki-links in other notes that referenced the old name. Both the source and destination paths must be inside the token's scope.

Rename a project (top-level folder). All note paths under the project are reindexed under the new prefix. Admin tokens only.

Search notes in the vault using full-text search. Hits are ranked by text match (title weighs most, then frontmatter such as tags and description, then body) with small boosts for backlinks, importance, recent edits and the pinned tag; each hit carries `score` (relative to the best hit of this response, 1 = best) and `why` (the signals behind it). A link is searchable by the words it shows (its alias, or the linked note's name and heading), not by its folder path: to find the notes that link a page use memory_backlinks. Snippets are short excerpts around the match: before reporting a detail (a…

Record a structured insight about friction you hit while USING gosidian itself (the MCP/UI/tools), not about the vault content. Writes one note to the private insights project for human triage. Only works when the operator has enabled the self-improvement loop and this token is opted in; otherwise it returns an error. IMPORTANT: describe the friction in the abstract — never include note content, project names, file paths, or user data.

Introspect the calling token's current state: rate-limit budget of this MCP session (max_per_minute, used, remaining; all the sessions of a token share token_max_per_minute, of which token_used are spent), token identity (id, name, projects, scopes), access (every project the token can reach with its live level, read or write: an account can hold write on some projects only, whatever the token's scopes say), and correlation id of the current MCP session when available. Use this before a burst of writes to avoid hitting the rate limit, or to confirm which credentials you're running under and wh…

List skills (notes with frontmatter type:skill) under a project. Optionally filter by a substring matching the '## Trigger phrase' section of the skill body. Returns path, title, description from frontmatter, and the first ~400 chars of the trigger phrase section as an excerpt. A skill that keeps reference notes in the folder named like it (skills/<slug>/) also carries bundle {notes, bytes, oversize}: read the references when the entry's steps call for them, and the oversize ones (larger than memory_get returns whole) by section with memory_get_section, or with raw:true.

Freeze a note as it reads now into a dated note beside it, <folder>/<name>.snapshots/YYYY-MM-DD.md (the server's day; its time is added for a second one the same day): its views replaced by their rows, its `=count(…)` values by their numbers and its embeds included, so the vault's history keeps what they showed and the snapshot never recomputes. The note itself does not change; the snapshot has type: snapshot, source: [[note]] and the project's tag. Returns its path and how many views, values and embeds it froze.

List notes in a project that have NOT been modified recently — review/archive candidates. Returns path, title, mtime (unix seconds) and closed (true when tagged status:done or status:archived), in ascending mtime order (oldest first). By default every old note is listed; pass exclude_closed:true to drop closed plans and archived notes — that is exactly what memory_bootstrap's maintenance.stale_count counts (with its fixed 90d cutoff), so the two agree only with the flag on.

Extract GitHub-flavored markdown checkboxes (`- [ ]` / `- [x]`) from all notes under a project. Returns path, line, text, checked state, parent heading context, and plan_status from the frontmatter when the note has type:plan. Use instead of memory_get + manual regex when you need granular pending-work awareness. A token scoped to a single project may omit it (that project is used); a project outside the token's scope is refused with an error.

Overwrite an existing note's content. Fails if the note does not exist. Pass if_match (the etag returned by a previous memory_get) for optimistic locking: the call is rejected if the note has changed since you last read it. Size guard: content is capped (default 1 MiB) — for a large body already on disk use memory_ingest with overwrite:true instead. Shrink guard: a content that would empty a note (by default under 10% of a note of 1 KiB or more, as a placeholder written by mistake does) is refused unless allow_shrink is true; to change only a part, use memory_edit.

Upload a file attachment to the vault and get a ready-to-splice markdown embed. CHEAPEST for large files: POST multipart (field 'file', bearer token) to the /upload endpoint — your MCP base URL plus /upload (drop a trailing /sse from the URL you configured); bytes travel over HTTP, not the model context. This tool takes ONE source: base64 `data`, server-side `source_path`, or `bridge_filename` (staged in the bridge dir). Size cap and allowed extensions are in bootstrap `capabilities`.

Upload a file resource decoupled from any note (returns the handle path/url/hash/mime/kind/size, no embed markdown) — the pre-uploader for the stage-then-attach pattern. CHEAPEST for large files: POST multipart (field 'file', bearer token) to the /upload endpoint (your MCP base URL plus /upload; drop a trailing /sse). ONE source: base64 `data`, `source_path`, or `bridge_filename`. Storage is <project>/attachments/<hash>.<ext>, magic-bytes verified; caps/extensions in bootstrap `capabilities`.

Long-poll for note changes inside the token's scope. Blocks up to timeout_s seconds and returns as soon as a note is created/updated/deleted (topics: note, tree), or with an empty events list on timeout. Pass the cursor returned by the previous call to resume without gaps; the first call (cursor 0) just establishes the cursor. resync=true means the cursor fell out of the short replay window — reconcile with memory_recent instead of trusting the stream. One wait per MCP session: poll loops should call this back-to-back, not in parallel. Use this instead of polling memory_recent/memory_pending_h…