Skip to main content
Glama
arctop

Seamless

by arctop
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

memory_write

DestructiveIdempotent

Create or update a durable project memory so future sessions keep critical constraints, gotchas, decisions, and runbooks. Overwrite by name or supersede an outdated memory.

Instructions

Create or update a durable memory -- the compact knowledge a future session must not miss (a constraint, gotcha, decision, runbook). Long-form write-ups belong in notes_create; put the one-line lesson here. Writing an existing name updates it in place (its id is stable). On a new name, a semantically similar existing memory is reported as an advisory hint; the write still proceeds. The hint is withheld when the target project's content is fenced from you (see the withheld marker on the response) -- the write lands either way. Pass supersedes to replace a DIFFERENT, now-outdated memory: it is marked invalid and leaves every index (briefing, recall) but stays readable with a pointer here. If superseding fails, the new memory is still written and kept; the error says how to retry.

Input Schema

NameRequiredDescriptionDefault
bodyYesmarkdown body (aliases: content, text)
kindYesmemory kind; constraint = what any agent must or must not do regardless of task; convention = a project-local choice or layout fact (naming, branding, where things live or deploy, which files sync together); for kind=stage, open the body with Status: open|in_progress|blocked|done and optionally Gate: human|ai, and flip the status with memory_edit (or a full memory_write) -- append cannot change the header, which is parsed from the top of the body
nameYeskebab-case identifier, unique within the project
tagsNotags, replacing all (a comma-separated string is also accepted); omit to leave an existing memory's tags untouched, and note an empty list reads as absent, not as a clear
projectNoproject slug; defaults to the bound/ambient session's project. An unknown slug CREATES that project -- naming a new one is normal and never an error. Pass project=global ONLY for knowledge that belongs in EVERY project's briefing; it is not a neutral default. With no session and no explicit project the call is rejected as ambiguous. A session bound to a confidential or sealed project can write ONLY into that project.
sessionNothe session to act as: the name session_start returned, the cc/<id> or cx/<id> on your briefing's 'Seam session' line, or a session ULID. It scopes and credits this call. Defaults to this connection's session; pass it on every call when session_start reports the connection as stateless
supersedesNoname of an existing memory this one replaces; that memory is marked superseded (invalid) and pointed here
descriptionYesone line, <=150 chars -- the only text shown in indexes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.7.4
    • addedInput schema / properties / session
      Added value: +{
+  "description": "the session to act as: the name session_start returned, the cc/<id> or cx/<id> on your briefing's 'Seam session' line, or a session ULID. It scopes and credits this call. Defaults to this connection's session; pass it on every call when session_start reports the connection as stateless",
+  "type": "string"
+}
  2. Changed2 schema fields changedv0.4.11
    • changedInput schema / properties / kind / description
      Previous value: -"memory kind; constraint = what any agent must or must not do regardless of task; convention = a project-local choice or layout fact (naming, branding, where things live or deploy, which files sync together); for kind=stage, open the body with Status: open|in_progress|blocked|done and optionally Gate: human|ai, and update status by re-writing via memory_write -- append cannot change the header, which is parsed from the top of the body"New value: +"memory kind; constraint = what any agent must or must not do regardless of task; convention = a project-local choice or layout fact (naming, branding, where things live or deploy, which files sync together); for kind=stage, open the body with Status: open|in_progress|blocked|done and optionally Gate: human|ai, and flip the status with memory_edit (or a full memory_write) -- append cannot change the header, which is parsed from the top of the body"
    • changedInput schema / properties / project / description
      Previous value: -"project slug; defaults to the bound/ambient session's project. An unknown slug CREATES that project -- naming a new one is normal and never an error. Pass project=global ONLY for knowledge that belongs in EVERY project's briefing; it is not a neutral default. With no session and no explicit project the call is rejected as ambiguous."New value: +"project slug; defaults to the bound/ambient session's project. An unknown slug CREATES that project -- naming a new one is normal and never an error. Pass project=global ONLY for knowledge that belongs in EVERY project's briefing; it is not a neutral default. With no session and no explicit project the call is rejected as ambiguous. A session bound to a confidential or sealed project can write ONLY into that project."
  3. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations declare it is a non-readonly, idempotent, destructive write. The description goes well beyond that: update-in-place with a stable id, an advisory similarity hint on new names, the hint being withheld in fenced projects while the write still lands, supersession marking a memory invalid but keeping it readable, and partial-failure semantics where a failed supersede still leaves the new memory written. This is exactly the failure-mode and side-effect detail annotations cannot carry.

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?

Front-loaded with the core verb+resource and the notes_create boundary before descending into edge cases. It is dense but each sentence covers a distinct behavior (update-in-place, hint, fencing, supersede, retry); slightly long, but almost nothing is wasted.

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?

With no output schema and 8 parameters, the description carries the burden and does so: it explains update vs. create, hint behavior, supersession, and recovery from supersede failure. An agent has enough to invoke it correctly and interpret the outcomes.

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?

Schema description coverage is 100%, so every parameter including supersedes and project is already documented in the schema. The description largely restates those same semantics (supersedes, project=global) rather than adding new syntax or format guidance, so the baseline of 3 applies.

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 ('Create or update a durable memory') and immediately characterizes the artifact ('the compact knowledge a future session must not miss'). It explicitly distinguishes itself from the sibling notes_create, so an agent can route without opening either 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 explicit routing ('Long-form write-ups belong in notes_create; put the one-line lesson here') and a concrete condition for the alternative path ('Pass supersedes to replace a DIFFERENT, now-outdated memory'). When-to-use and when-to-use-something-else are both present.

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