Tirith

Official

Overview Schema Source Related Servers Discussions Admin

memory_write

Idempotent

Save durable Markdown notes about repository paths for future agents; update existing notes or target by permalink, with conflict detection.

Instructions

Save a durable note about repository paths (a lesson, trap, handoff or research) as committed Markdown; the next agent that claims those paths gets its excerpt in the brief. A title that already exists updates that note in place, and permalink targets one explicitly. Pass the updated_at you read as if_updated_at so a concurrent edit returns conflict instead of being overwritten. Not for settled choices (decision_record) or talk between agents (message_send).

Input Schema

TableJSON Schema

Name	Required	Description
`body`	Yes	The note itself, as Markdown.
`kind`	No	One of `fact`, `lesson`, `gotcha`, `handoff`, `research`, `decision`, `note` (the default).
`tags`	No	Tags for filtering; lowercased, and a leading `#` is dropped.
`agent`	Yes	Your stable agent name.
`paths`	No	Repo-relative paths this note is about.
`title`	Yes	Short title. Becomes the permalink the first time.
`permalink`	No	Overwrite this note instead of matching on the title.
`if_updated_at`	No	RFC 3339 `updated_at` from a read; refused if the note changed since.

Output Schema

TableJSON Schema

Name	Required	Description
`note`	No	The note as stored: id, permalink, title, kind, body, observations, relations, paths, tags, author, updated_by, created_at, updated_at.
`status`	Yes	ok. conflict: if_updated_at was set and the note changed since. not_found: an explicit permalink that does not exist. invalid: bad kind or input.
`created`	No	True for a new note, false when an existing title or permalink was updated.
`message`	No	Human-readable detail, on most outcomes other than ok.
`permalink`	No	On conflict: the note that changed.
`updated_at`	No	On conflict: its real updated_at; read again and retry.

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedv1.1.2Sep 18, 2026

addedInput schema / properties / agent / description
```
Added value: +"Your stable agent name."
```
addedInput schema / properties / body / description
```
Added value: +"The note itself, as Markdown."
```

addedInput schema / properties / if_updated_at / description

Added value: +"RFC 3339 `updated_at` from a read; refused if the note changed since."

addedInput schema / properties / kind / description

Added value: +"One of `fact`, `lesson`, `gotcha`, `handoff`, `research`, `decision`,\n`note` (the default)."

addedInput schema / properties / kind / enum

Added value: +[
+  "fact",
+  "lesson",
+  "gotcha",
+  "handoff",
+  "research",
+  "decision",
+  "note"
+]

addedInput schema / properties / paths / description

Added value: +"Repo-relative paths this note is about."

addedInput schema / properties / permalink / description

Added value: +"Overwrite this note instead of matching on the title."

addedInput schema / properties / tags / description

Added value: +"Tags for filtering; lowercased, and a leading `#` is dropped."

addedInput schema / properties / title / description

Added value: +"Short title. Becomes the permalink the first time."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "description": "Any result may also carry lost, inbox, inbox_more and persist_error; see guide.",
+  "properties": {
+    "created": {
+      "description": "True for a new note, false when an existing title or permalink was updated.",
+      "type": "boolean"
+    },
+    "message": {
+      "description": "Human-readable detail, on most outcomes other than ok.",
+      "type": "string"
+    },
+    "note": {
+      "description": "The note as stored: id, permalink, title, kind, body, observations, relations, paths, tags, author, updated_by, created_at, updated_at.",
+      "type": "object"
+    },
+    "permalink": {
+      "description": "On conflict: the note that changed."
+    },
+    "status": {
+      "description": "ok. conflict: if_updated_at was set and the note changed since. not_found: an explicit permalink that does not exist. invalid: bad kind or input.",
+      "enum": [
+        "ok",
+        "conflict",
+        "not_found",
+        "none",
+        "invalid",
+        "cancelled"
+      ],
+      "type": "string"
+    },
+    "updated_at": {
+      "description": "On conflict: its real updated_at; read again and retry."
+    }
+  },
+  "required": [
+    "status"
+  ],
+  "type": "object"
+}

First observedv1.1.1Sep 18, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Beyond the idempotentHint and destructiveHint annotations, the description discloses substantive behavior: notes are committed Markdown, the next agent claiming the associated paths receives the excerpt, matching titles update in place, permalink allows explicit targeting, and if_updated_at prevents overwriting concurrent edits. This is rich, high-value behavioral context that annotations alone do not provide.

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 three dense sentences with no filler. The first sentence front-loads the core purpose and scope, the second explains update and concurrency behavior, and the third gives exclusions. Every sentence earns its place, making the description easy to parse quickly.

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 tool with 8 parameters, the description covers the essential context: what kind of content to store, how it is persisted, how future agents consume it, how to update versus target, how to handle concurrency, and which sibling tools are not appropriate. The output schema covers return values, so the description does not need to repeat them. Nothing critical is missing for an agent to call this tool 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 semantic value beyond the schema: it explains that an existing title updates the note in place, that permalink targets a specific note, and that if_updated_at should carry the read value to get conflict detection instead of silent overwrites. This enhances the agent's understanding of title, permalink, and if_updated_at beyond their schema descriptions.

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 states a specific verb and resource: 'Save a durable note about repository paths ... as committed Markdown.' It clearly differentiates from siblings by explicitly naming decision_record and message_send as not-this-tool. An agent can immediately understand what memory_write accomplishes and how it differs from nearby alternatives.

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 gives explicit when-to-use context ('a lesson, trap, handoff or research') and explicit when-not-to-use alternatives ('Not for settled choices (decision_record) or talk between agents (message_send)'). It also provides operational guidance about updating existing titles and using if_updated_at for concurrency, leaving little to inference.

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