Engram Obsidian Memory Sync

Edit Note

edit_note

Destructive

Change part of an existing note. mode replace_text finds exact text and replaces it (first occurrence by default); mode replace_section replaces everything under one heading; mode insert_section adds content under a heading, at the start or end of that section, keeping what is there. Fails without writing if the text or heading is not found, if expected_replacements does not match, or if base_hash is given and the note changed since that read. To add text at the top or bottom of the note use append_to_note. To rewrite the whole note use write_note.

Input Schema

Name	Required	Description	Default
`find`	No	replace_text only: exact text to find
`mode`	Yes	replace_text, replace_section or insert_section
`path`	Yes	Path of the note, e.g. "Projects/Alpha.md"
`level`	No	replace_section and insert_section: heading level 1-6 (default 2)
`content`	No	replace_section: new content for under the heading; insert_section: content to add
`heading`	No	replace_section and insert_section: heading text without the # prefix
`replace`	No	replace_text only: text to put in its place
`position`	No	insert_section only: start (directly under the heading) or end (default; after the section's last line, including its subsections)	end
`vault_id`	No	Target vault: its name (e.g. "Engram") or its UUID. REQUIRED when you own more than one vault; the server keeps no active-vault state between calls, so it must be passed on every vault-scoped call. Omit only if you have a single vault. Call list_vaults if a name does not resolve.
`base_hash`	No	Optional content_hash from your get_notes read of this note. If the note changed since, nothing is written and you get a version_conflict: call get_notes again and retry with the new content_hash. Pass it when your change depends on what you read.
`occurrence`	No	replace_text only: 0 = first (default), 1 = second, -1 = all
`expected_replacements`	No	replace_text only: fail without writing unless exactly this many are replaced

Output Schema

Name	Required	Description
`mode`	Yes
`path`	Yes
`heading`	No	replace_section and insert_section: the heading edited; null for replace_text
`search_note`	No	When search will see this change; use get_notes until then
`replacements`	No	replace_text: occurrences replaced; null for the section modes
`search_indexing_starts_in_seconds`	No	At least this many seconds until indexing starts; search can lag further. Use get_notes to read the note until search finds it

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 7, 2026

addedInput schema / properties / base_hash

Added value: +{
+  "description": "Optional content_hash from your get_notes read of this note. If the note changed since, nothing is written and you get a version_conflict: call get_notes again and retry with the new content_hash. Pass it when your change depends on what you read.",
+  "type": "string"
+}

Changed2 schema fields changedNov 1, 2026

addedOutput schema / properties / search_indexing_starts_in_seconds

Added value: +{
+  "description": "At least this many seconds until indexing starts; search can lag further. Use get_notes to read the note until search finds it",
+  "type": "integer"
+}

addedOutput schema / properties / search_note

Added value: +{
+  "description": "When search will see this change; use get_notes until then",
+  "type": "string"
+}

Changed8 schema fields changedSep 30, 2026

changedInput schema / properties / content / description

Previous value: -"replace_section only: new content for under the heading"New value: +"replace_section: new content for under the heading; insert_section: content to add"

changedInput schema / properties / heading / description

Previous value: -"replace_section only: heading text without the # prefix"New value: +"replace_section and insert_section: heading text without the # prefix"

changedInput schema / properties / level / description

Previous value: -"replace_section only: heading level 1-6 (default 2)"New value: +"replace_section and insert_section: heading level 1-6 (default 2)"

changedInput schema / properties / mode / description

Previous value: -"replace_text or replace_section"New value: +"replace_text, replace_section or insert_section"

changedInput schema / properties / mode / enum

Previous value: -[
-  "replace_text",
-  "replace_section"
-]New value: +[
+  "replace_text",
+  "replace_section",
+  "insert_section"
+]

addedInput schema / properties / position

Added value: +{
+  "default": "end",
+  "description": "insert_section only: start (directly under the heading) or end (default; after the section's last line, including its subsections)",
+  "enum": [
+    "start",
+    "end"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / heading / description

Previous value: -"replace_section: heading updated"New value: +"replace_section and insert_section: the heading edited; null for replace_text"

changedOutput schema / properties / replacements / description

Previous value: -"replace_text: occurrences replaced"New value: +"replace_text: occurrences replaced; null for the section modes"

AddedSep 27, 2026

TDQS

A4.7/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds genuinely new behavioral facts: the operation is atomic and "fails without writing" under three specific conditions, insert_section preserves existing content, and base_hash produces a version_conflict requiring a re-read. It does not discuss partial matches within a section or how replace_section treats subsections' content beyond 'everything under one heading'.

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 the core action, then modes, then failure conditions, then sibling routing. Four sentences, each carrying distinct load, with no restatement of the title or schema boilerplate.

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?

For a 12-parameter mutation tool with an output schema and full schema coverage, the description covers the risky parts an agent cannot infer: atomicity, the three failure conditions, version-conflict recovery, and mode selection. Return values are delegated to the output schema, which is appropriate.

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 baseline is 3, but the description adds cross-parameter semantics the schema states only per-property: it explains the mode-to-parameter coupling (which of find/replace/heading/content/position apply in each mode) and that replace_text targets the first occurrence by default. This meaningfully reduces the chance of passing parameters under the wrong mode.

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 ("Change part of an existing note") and immediately enumerates the three modes with the exact operation each performs. It explicitly distinguishes itself from append_to_note and write_note, so an agent can route between the three write-path siblings 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 exclusions with named alternatives: append_to_note for top/bottom-of-note additions and write_note for whole-note rewrites. The mode sentences also imply the when-to-use split between exact-text edits and heading-scoped edits.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Engram Obsidian Memory Sync tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.