Skip to main content
Glama
docmancer

docmancer

Official
by docmancer
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

pin_memory

Idempotent

Pin a durable line into a canonical memory section to protect it from automatic reconciliation. Use for corrections, preferences, or facts that the reconciler left out or got wrong.

Instructions

MUTATING: pin one durable line into a canonical memory section. Writes to local disk, machine-wide, so it takes no project_path. The pinned zone is the ONLY part of a canonical section that survives automatic reconciliation, so use this, not edit_memory or write_memory, for any correction, standing preference, or fact the reconciler got wrong or left out. Idempotent: pinning the same line twice changes nothing. Use unpin_memory to reverse it, and canonical_memory to see the result. Parameters: section selects which canonical section to pin into, one of about, preferences, working-principles, or active-projects; text is the complete line to pin, which should read as a standalone statement because it is stored verbatim. Returns an object with the section, its path, and the updated pinned-line count.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
textYesComplete durable line to add to the selected canonical section's pinned zone.
sectionYesCanonical section to modify. canonical-memory is excluded because it describes the store itself and is regenerated wholesale.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv0.9.13
    • removedInput schema / properties / section / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • removedInput schema / properties / section / default
      Removed value: -null
    • addedInput schema / properties / section / description
      Added value: +"Canonical section to modify. canonical-memory is excluded because it describes the store itself and is regenerated wholesale."
    • addedInput schema / properties / section / enum
      Added value: +[
+  "about",
+  "preferences",
+  "working-principles",
+  "active-projects"
+]
    • addedInput schema / properties / section / type
      Added value: +"string"
    • removedInput schema / properties / text / anyOf
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
    • removedInput schema / properties / text / default
      Removed value: -null
    • addedInput schema / properties / text / description
      Added value: +"Complete durable line to add to the selected canonical section's pinned zone."
    • addedInput schema / properties / text / type
      Added value: +"string"
    • addedInput schema / required
      Added value: +[
+  "section",
+  "text"
+]
  2. First observedv0.1.0

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 reveals machine-wide disk persistence, the reconciliation survival property, the meaning of idempotency, and the return value shape. There is no contradiction with the annotations; instead, it adds substantial context.

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?

Despite being lengthy, every sentence contributes essential information: action, persistence semantics, reconciliation behavior, usage guidance, idempotency, reversal, parameter details, and return value. There is no redundancy or filler; the structure is front-loaded and logical.

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?

The description is comprehensive for a mutating tool with subtle reconciliation implications. It covers the purpose, the critical survival property, when to use it, how to undo it, parameter semantics, and the return value. Since there is no output schema, the return-value note is essential and provided clearly.

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?

Although the schema already covers 100% of parameters, the description adds the key semantic that the text 'should read as a standalone statement because it is stored verbatim', which is not present in the schema. This elevates the parameter guidance beyond the baseline.

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 opens with 'pin one durable line into a canonical memory section', clearly stating the action and resource. It explicitly distinguishes from edit_memory and write_memory by specifying that this tool is for corrections, standing preferences, or facts the reconciler got wrong, giving it a clear purpose among siblings.

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?

It provides explicit when-to-use guidance ('for any correction, standing preference, or fact the reconciler got wrong or left out') and when-not-to-use alternatives ('use this, not edit_memory or write_memory'). It also mentions unpin_memory for reversal and canonical_memory for inspection, offering complete usage context.

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

Deploy Server

Other Tools