mnema

Official

Overview Schema Source Related Servers Discussions Admin

Retract a note

retract_note

Retract a wrong or stale note by appending a signed reason; the note stops appearing in opening reads and search while remaining readable by id.

Instructions

Take back a memory or an observation that turned out to be wrong or stale. The note is NOT erased: a signed retraction carrying the reason is appended, the note stops being served by the opening read and the search, and reading it by id still returns it, saying when, by whom and why it was retracted. It follows the note to the tree it was written in. Only notes are retracted: a decision is rejected or superseded, a pattern rejected or deprecated. Only the identity that wrote a note retracts it; a note of another identity, or one already retracted, is refused. RECORDING IS PERMANENT: mnema is append-only and nothing deletes a fact. A record in the public scope is committed to the repository and reaches every machine that clones it (published, if that repository is public). So do NOT record credentials here. Values in a recognized format (cloud keys, API tokens, private keys, a password inside a URL) are replaced with a typed placeholder before anything is written and the reply says what was replaced, but a format mnema does not recognize is written verbatim and cannot be taken back. Do not record personal data either: an email address is replaced with and reported, and the mnid already says who wrote. Each text field holds at most 65536 bytes; a longer one is refused, not truncated.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "id": "<id>",
      "reason": "<reason>"
    },
    "name": "retract_note"
  }
}

Input Schema

Name	Required	Description	Default
`id`	Yes	The id of the note to retract, as `read_record` opens it.
`reason`	Yes	Why it is taken back.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 9, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Adds substantial behavior beyond the annotations: an append-only signed retraction is written, the note disappears from the opening read and search but remains readable by id, it follows the note to its tree, and repeat or foreign-identity calls are refused (which explains idempotentHint=false). The secret/PII and 65536-byte material is genuinely informative but concerns recording rather than retraction, so it dilutes focus while still being disclosed behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence, but the body sprawls into a long permanence/secret-redaction warning that is largely irrelevant to invoking a retraction. Several sentences are dense run-ons, and roughly half the text does not earn its place for this specific operation.

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?

With no output schema and a mutation that is hard to observe, the description explains the resulting state of the store and that the reply reports placeholder substitutions. What is missing is minor: no statement of what the retraction reply itself contains or how a failure (foreign identity, already retracted) is surfaced versus raised.

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% with both parameters documented and length-constrained, so baseline is 3. The description adds real meaning on top: `reason` is carried inside the signed retraction and surfaced later on read-by-id ('saying when, by whom and why'), and `id` is tied to what read_record opens.

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?

Names a specific verb and resource chain ('take back a memory or an observation', 'the note is NOT erased') and explicitly scopes which record types it applies to, listing what happens to decisions and patterns instead. An agent can tell this apart from decision_transition or a pattern tool 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 the trigger condition ('turned out to be wrong or stale') and the exclusion set ('Only notes are retracted: a decision is rejected or superseded, a pattern rejected or deprecated'), plus the authorization rule that only the writing identity may retract and that an already-retracted note is refused. All routing conditions are stated in the definition rather than left to be inferred from sibling names.

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