Skip to main content
Glama
Sign In
bantamkit

bantamkit

by Ink01101011
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Save a memory

memory_save
Destructive

Save one durable fact—a user preference, decision, or working fix—to persistent memory so a future session can recall it. Use for lasting facts only, not repo-derivable or one-off state.

Instructions

Save ONE durable fact to persistent memory — a preference the user stated, a decision, the fix that worked — so a future session can recall it. Use it only for facts a future session needs; never for anything derivable from the repo, git history or docs, nor for one-off state of this conversation. To find a fact use memory_recall; to change one, save again under its EXACT name, which replaces it in place; to free room call memory_compact. Refused with nothing written, each with its own sentence: a description too close to an existing fact's (the reply names that fact — save under that SAME name or skip, never rename to force a copy), a spelling that normalises onto an existing name (Deploy Command onto deploy-command), and a save that would push the always-loaded index over its byte budget (the reply names the remedy). Every save lands in the writable project store (.bantamkit/memory), never in the profile or a read-only grant, and is appended to the usage ledger. Optional outcome (error|success) tags a lesson and status: done closes a project fact; nothing here archives — that is the operator's bantamkit-memory candidates/merge.

Input Schema

NameRequiredDescriptionDefault
bodyYesThe fact itself, terse
nameYesshort-kebab-case slug
typeYesWhat kind of fact: `user` (who the user is, their role and preferences), `feedback` (a correction or confirmed way of working, with the why), `project` (ongoing work, a decision, a constraint), `reference` (a URL, ticket or dashboard pointer).
linksNonames of related memories
statusNoLifecycle of a project fact. Save an existing name with `done` when the work it describes has shipped; `bantamkit-memory candidates` lists done facts for the operator to archive. Absent means active; `active` is never written.
outcomeNoWhat the lesson records: `error` (a failure to avoid) or `success` (a way that worked). Only on feedback and project facts; refused on user and reference. Read back by `bantamkit-memory list --outcome` and by memory_recall's `outcome` filter.
queriesNoThe prompts a user would type when this fact is what they need: three in the user's language and three in English, at most 8, each at most 200 characters
keywordsNoWords the user will type when they need this fact, in the user's own language as well as English (e.g. Thai and English terms)
descriptionYesOne line written to match the FUTURE recall query, not to summarize the body

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.37.1
    • addedInput schema / properties / keywords
      Added value: +{
+  "description": "Words the user will type when they need this fact, in the user's own language as well as English (e.g. Thai and English terms)",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / queries
      Added value: +{
+  "description": "The prompts a user would type when this fact is what they need: three in the user's language and three in English, at most 8, each at most 200 characters",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
  2. Changed3 schema fields changedv0.36.2
    • addedInput schema / properties / outcome
      Added value: +{
+  "description": "What the lesson records: `error` (a failure to avoid) or `success` (a way that worked). Only on feedback and project facts; refused on user and reference. Read back by `bantamkit-memory list --outcome` and by memory_recall's `outcome` filter.",
+  "enum": [
+    "error",
+    "success"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / status
      Added value: +{
+  "description": "Lifecycle of a project fact. Save an existing name with `done` when the work it describes has shipped; `bantamkit-memory candidates` lists done facts for the operator to archive. Absent means active; `active` is never written.",
+  "enum": [
+    "active",
+    "done"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / type / description
      Added value: +"What kind of fact: `user` (who the user is, their role and preferences), `feedback` (a correction or confirmed way of working, with the why), `project` (ongoing work, a decision, a constraint), `reference` (a URL, ticket or dashboard pointer)."
  3. First observedv0.36.0

TDQS

A4.8/5.0
Behavior5/5

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

Goes well beyond the annotations: it enumerates the three refusal modes each with their remedy (duplicate description, name normalisation collision, index byte budget), states where the write lands (.bantamkit/memory, never profile or read-only grant), and notes the usage-ledger append. It also explains that a re-save replaces in place, which gives meaning to destructiveHint=true rather than contradicting it.

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

Conciseness4/5

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

The core instruction and the exclusion rule are front-loaded in the first two sentences, which is the right order. The remainder is dense and clause-heavy (nested parentheticals around the refusal cases), so it is efficient for its complexity but occasionally hard to parse in one pass.

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 9-parameter mutation tool with an output schema, this covers everything the agent needs: scope, exclusions, failure modes with remedies, storage destination, replacement semantics, and lifecycle via status/outcome. Return values are already covered by the output schema, so nothing material is missing.

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 genuine semantics on top: re-saving under the EXACT name replaces in place, renaming to force a copy is refused, and `status: done` closes a project fact while nothing archives. These are behavioural consequences of specific parameter values that the schema descriptions alone do not fully convey.

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 ('Save ONE durable fact to persistent memory') and immediately bounds the scope with examples of what counts. It also names the complementary siblings (memory_recall for finding, memory_compact for freeing room), so an agent can place it among its neighbours 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?

Explicitly says when NOT to use it ('never for anything derivable from the repo, git history or docs, nor for one-off state of this conversation') and routes to the right alternatives: memory_recall to find, re-saving under the exact name to change, memory_compact to free space. That is the full when/when-not/alternative triad.

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