memshelf-mcp

Overview Schema Source Related Servers Discussions Admin

memshelf_shelve

Idempotent

Offload one closed topic as a durable, indexed shelf episode with digest, redaction and commit, so it can be recalled later without re-reading the source.

Instructions

Offload one closed topic to the shelf as a durable, indexed episode — redaction, digest contract and git commit included. Derived files are not written here — they are rendered by memshelf_rebuild or the shelf's bot. Details: docs/tools.md.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`params`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed14 schema fields changedv0.3.0Sep 11, 2026

addedInput schema / $defs / ShelveInput / additionalProperties
```
Added value: +false
```

addedInput schema / $defs / ShelveInput / properties / amend

Added value: +{
+  "default": false,
+  "description": "Rewrite an episode already on the shelf, under the same slug (#71): one episode, one recomputed ledger row, redaction and the digest contract re-run. Errors if the slug is not there — that is a typo, not a create.",
+  "title": "Amend",
+  "type": "boolean"
+}

addedInput schema / $defs / ShelveInput / properties / approx_tokens / anyOf

Added value: +[
+  {
+    "type": "integer"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / $defs / ShelveInput / properties / approx_tokens / default
```
Previous value: -0New value: +null
```

addedInput schema / $defs / ShelveInput / properties / approx_tokens / description

Added value: +"Rough in-window size in tokens; an eyeball estimate is fine. OMIT when nothing was measured or estimated — the episode is then recorded as approx_tokens_source: unmeasured instead of a silent 0 (#113): absence of measurement must not look like a measured zero."

removedInput schema / $defs / ShelveInput / properties / approx_tokens / type
```
Removed value: -"integer"
```

addedInput schema / $defs / ShelveInput / properties / approx_tokens_source

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "estimate",
+        "measured"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Where the number came from (#79). Default for any passed number is 'estimate' — that is what callers actually produce; say 'measured' only when it was. Contradiction (a source with no number) is refused.",
+  "title": "Approx Tokens Source"
+}

addedInput schema / $defs / ShelveInput / properties / publish

Added value: +{
+  "default": false,
+  "description": "Publish the shelve commit to origin as a NEW branch shelve/<slug> and report a one-click compare link (#118) — the mode for shelves whose main requires a PR. Exclusive with `push`; the local checkout never switches branches, so recall keeps working from this clone.",
+  "title": "Publish",
+  "type": "boolean"
+}

addedInput schema / $defs / ShelveInput / properties / push

Added value: +{
+  "default": false,
+  "description": "Push the shelve commit; on a rejection, rebase and retry exactly once (#108). The result then carries the post-push sha — the only sha worth quoting, since a rebase rewrites the local one.",
+  "title": "Push",
+  "type": "boolean"
+}

addedInput schema / $defs / ShelveInput / properties / retain_until

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Retention (#15): ISO date after which `memshelf purge` drops this episode. Absent means keep — retention is opt-in per episode.",
+  "title": "Retain Until"
+}

addedInput schema / $defs / ShelveInput / properties / shelf_path / default
```
Added value: +""
```

changedInput schema / $defs / ShelveInput / properties / shelf_path / description

Previous value: -"Path to an initialized memory shelf."New value: +"Path to an initialized memory shelf. Optional: when omitted, the shelf named by $MEMSHELF_SHELF_PATH is used. Pass it explicitly to address a different shelf than that default."

addedInput schema / $defs / ShelveInput / properties / sync

Added value: +{
+  "default": true,
+  "description": "Fetch + fast-forward the shelf to its remote before anything is written (#108): a dirty tracked tree or a diverged branch refuses the shelve with the fix in the message instead of silently writing onto a stale base. A failed fetch (offline) does not refuse — it is reported loudly.",
+  "title": "Sync",
+  "type": "boolean"
+}

changedInput schema / $defs / ShelveInput / required

Previous value: -[
-  "shelf_path",
-  "slug",
-  "kind",
-  "digest"
-]New value: +[
+  "slug",
+  "kind",
+  "digest"
+]

First observedv0.1.0Jul 29, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true, openWorldHint=false), so the bar is lower. The description still adds real behavioral detail beyond them: redaction runs, a digest contract is enforced, and a git commit is produced, plus an explicit statement that derived artifacts are written by a different tool. It does not mention push/publish side effects, but the schema carries those.

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?

Three short clauses: what it does, what it deliberately does not do, and where the full documentation lives. The purpose is front-loaded and nothing is redundant — a good model of density for a tool with a heavy schema.

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?

An output schema exists, so return values need not be explained, and the rich schema plus annotations cover the mechanics. What is missing is onboarding context: the shelf must already exist (the sibling memshelf_init / default $MEMSHELF_SHELF_PATH is only implied), and no pointer is given to the lint/advise steps that normally precede a shelve.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description contributes nothing about arguments. The reported 0% schema description coverage is an artifact of the top-level 'params' wrapper having no description; the nested ShelveInput properties are in fact documented at high density (push/publish exclusivity, sync refusal behavior, amend semantics, retention, approx_tokens absent-vs-zero). With the schema effectively doing the work, the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — offloading one closed topic into a durable, indexed episode — with concrete constituents (redaction, digest contract, git commit). It also marks a boundary against memshelf_rebuild ('derived files are not written here'), which helps an agent separate the two. It does not distinguish itself from memshelf_import or memshelf_advise, so it stops short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Offload one closed topic' implies the trigger condition (a topic has been completed) and the rebuild reference routes one sub-concern elsewhere, but there is no explicit when-to-use/when-not guidance against the 13 siblings. The reader must infer that this is the write path that precede rebuild/index. Implied usage only.

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

Deploy Server