ClickHouse Loom

Official

Overview Schema Source Related Servers Discussions Admin

loom_memory_update

Update an existing saved fact in place by its memory key when its value changes or becomes more specific, preserving tags, confidence, expiry, and history without creating duplicates.

Instructions

Update a saved fact by memory_key: the operation for "the fact changed or got more specific".

WHEN: a read (memory.get or loom_search) returned this key and the user now states a new value, a correction, or a more precise version of it — 'the deploy day moved to Thursday', 'the budget is actually 40k'. It keeps the row's tags, confidence, expiry, lock and history; memory.set would write a new version blind. Revision policy: if a read this session returned the key of a fact that has now changed or got more precise, update it under that same key with memory.update — never save a second copy and never delete + re-save. A fact about a new subject or scope gets its own memory_key (include the project / scope token in the key). Do NOT use it for a genuinely new fact — call memory.set.

Resolves the key across the namespace; pass agent/user_id/session_id only to narrow when the key is live under several writers (409 AMBIGUOUS_KEY lists them). updated=false with reason=not_found means the key has no live row — save it with memory.set instead. Pass if_match_sha256 from the read for a no-clobber update. Given a memory_id rather than a key, call memory.update_by_id (via loom_op where it is not listed).

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": {
      "memory_key": "<memory_key>"
    },
    "name": "loom_memory_update"
  }
}

Input Schema

Name	Required	Description	Default
`tags`	No
`value`	No
`reason`	No
`revive`	No
`run_id`	No
`concepts`	No
`namespace`	No
`char_limit`	No
`confidence`	No
`memory_key`	Yes
`if_match_sha256`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv1.1.0Nov 12, 2026

TDQS

A3.9/5.0

Behavior3/5

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

Adds real context beyond the annotations: what is preserved (tags, confidence, expiry, lock, history), the 409 AMBIGUOUS_KEY ambiguity mode, and the updated=false/not_found outcome with a redirect to memory.set. However, it never states the return shape (updated flag, new sha?) or whether the old value is recoverable via history, so the mutation's blast radius is only half-disclosed for a non-idempotent write.

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 purpose, then WHEN, policy, prohibition, mechanics — a sensible order with little filler. The one wasted element is the paragraph about agent/user_id/session_id narrowing, which refers to parameters that do not exist in this schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The decision logic (update vs set vs update_by_id) is complete and usable, but for an 11-parameter, 0%-documented mutation with no output schema, the description says nothing about the value payload, tags, confidence or char_limit semantics. An agent knows when to call it but not how to populate half its arguments.

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

Parameters2/5

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

Schema coverage is 0% across 11 parameters, so the description must carry the burden — it explains memory_key and if_match_sha256 (no-clobber) but leaves value, tags, confidence, concepts, revive, run_id, char_limit, reason and namespace entirely undefined. Worse, it instructs passing agent/user_id/session_id, none of which appear in the input schema, which will mislead an agent trying to use it.

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+resource+key ("Update a saved fact by memory_key") and positions it exactly against siblings: memory.set writes a new version, memory.update_by_id handles memory_id. An agent can distinguish this from loom_memory_set and loom_memory_apply 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?

Explicit WHEN clause with concrete examples ("the deploy day moved to Thursday"), an explicit when-not ("Do NOT use it for a genuinely new fact — call memory.set"), a revision policy forbidding delete+re-save, and a named alternative for the id-based case.

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

Deploy Server