A save can replace the whole object: fields you leave out of the request come back empty, and an empty string clears a field even on a merge; read the object, send it back whole with only your change, and diff it after the 200

Fix

1) Read the docs of that exact route for replaces, all fields or merge; if they say nothing, assume replace. 2) Read the current object, apply your change to that copy and send the full object back (read-modify-write). Never send placeholders such as '' or null for fields you do not mean to change; leave fields out only on a route documented as merge. 3) For text that grows (notes, memory), use a documented append route if there is one; otherwise read the whole text, append locally and save the whole. Keep a local copy before every save, and find out before you need it whether the API keeps a previous version you can roll back to. 4) Where the API offers a version, ETag or base version, send it (If-Match or the documented field) so that a stale save is refused with 409 or 412 instead of overwriting another writer; on a conflict, read again and redo the change. 5) After the 200, read the object back and diff it against the copy you read before: only the fields you named may differ (snippet). If the response lists what changed, check that list too. Restore from your copy if anything else changed. 6) When you run an API, document per route whether it replaces or merges, and refuse a body that would empty a required field.

Command

#!/usr/bin/env python3
"""replace_check.py 1.0 - did an update keep the fields you did not mean to change?
usage: python3 replace_check.py --selftest                       (local server on 127.0.0.1, no network)
       python3 replace_check.py BEFORE.json AFTER.json FIELD[,FIELD...]
BEFORE.json and AFTER.json are the object as read back before and after your update; FIELD
lists the fields you meant to change. The script lists every other field that was removed,
emptied or changed. Exit 0 = only the named fields changed / selftest pass, 1 = collateral
changes / selftest fail, 2 = usage."""
import json, sys, threading, urllib.error, urllib.request
from http.server import BaseHTTPRequestHandler, HTTPServer

EMPTY = (None, '', [], {})


def flat(doc, prefix=''):
    out = {}
    for k, v in (doc or {}).items():
        key = prefix + k
        if isinstance(v, dict) and v:
            out.update(flat(v, key + '.'))
        else:
            out[key] = v
    return out


def collateral(before, after, meant):
    """Fields outside `meant` that disappeared, became empty or changed value."""
    b, a = flat(before), flat(after)
    meant = set(meant)
    hits = []
    for k in sorted(set(b) | set(a)):
        if k in meant or any(k.startswith(m + '.') for m in meant):
            continue
        if k not in a:
            hits.append((k, 'missing after update'))
        elif b.get(k) not in EMPTY and a[k] in EMPTY:
            hits.append((k, 'emptied'))
        elif k in b and a[k] != b[k]:
            hits.append((k, 'changed'))
    return hits


def merged(current, changes):
    """Read-modify-write body: the full current object with only `changes` applied.
    A None in `changes` is left out rather than sent, so it cannot clear a field."""
    out = json.loads(json.dumps(current))
    for k, v in changes.items():
        if v is not None:
            out[k] = v
    return out


def selftest():
    start = {'name': 'a', 'bio': 'long bio', 'notes': ['n1', 'n2'], 'links': {'home': 'x'}, 'version': 1}
    store = {'replace': dict(start), 'merge': dict(start)}

    class H(BaseHTTPRequestHandler):
        def log_message(self, *a):
            pass

        def reply(self, code, doc):
            body = json.dumps(doc).encode()
            self.send_response(code)
            self.send_header('Content-Type', 'application/json')
            self.end_headers()
            self.wfile.write(body)

        def do_GET(self):
            self.reply(200, store[self.path.strip('/')])

        def do_POST(self):  # a 'save' route; whether it replaces or merges is not in its name
            kind = self.path.strip('/')
            doc = json.loads(self.rfile.read(int(self.headers.get('Content-Length', 0))))
            cur = store[kind]
            if 'version' in doc and doc['version'] != cur['version']:
                return self.reply(409, {'error': 'version_conflict'})
            if kind == 'replace':  # every field not in the body is reset
                new = {k: doc.get(k, [] if isinstance(v, list) else {} if isinstance(v, dict) else '')
                       for k, v in cur.items()}
            else:  # merge: only fields in the body change, but an empty string still clears
                new = dict(cur, **doc)
            new['version'] = cur['version'] + 1
            store[kind] = new
            self.reply(200, {'ok': True, 'version': new['version']})

    srv = HTTPServer(('127.0.0.1', 0), H)
    threading.Thread(target=srv.serve_forever, daemon=True).start()
    base = 'http://127.0.0.1:%d/' % srv.server_address[1]

    def call(kind, body=None):
        data = None if body is None else json.dumps(body).encode()
        req = urllib.request.Request(base + kind, data, {'Content-Type': 'application/json'})
        try:
            with urllib.request.urlopen(req, timeout=5) as r:
                return r.status, json.loads(r.read())
        except urllib.error.HTTPError as e:
            return e.code, json.loads(e.read())

    # 1) naive partial saves: send only the field you want to change
    before = call('replace')[1]
    s, r = call('replace', {'notes': ['n3']})
    naive_replace = collateral(before, call('replace')[1], ['notes', 'version'])
    before = call('merge')[1]
    call('merge', {'notes': ['n3'], 'bio': ''})  # '' meant as 'no change'
    naive_merge = collateral(before, call('merge')[1], ['notes', 'version'])
    # 2) read-modify-write with the version just read, then read back and diff
    store['replace'] = dict(start, version=10)
    before = call('replace')[1]
    s_ok, _ = call('replace', merged(before, {'notes': before['notes'] + ['n4'], 'bio': None}))
    safe = collateral(before, call('replace')[1], ['notes', 'version'])
    s_conflict, _ = call('replace', merged(before, {'notes': ['written from a stale read']}))
    srv.shutdown()
    print('naive partial save on a replace route (%d %s): %s' % (s, r, naive_replace))
    print('naive save with "" on a merge route: %s' % naive_merge)
    print('read-modify-write on the replace route: %d, collateral %s' % (s_ok, safe))
    print('second write based on the same, now stale read: %d' % s_conflict)
    ok = (s == 200 and r.get('ok') and [k for k, _ in naive_replace] == ['bio', 'links.home', 'name']
          and naive_merge == [('bio', 'emptied')] and s_ok == 200 and safe == [] and s_conflict == 409)
    print('pass: a 200 save cleared 3 fields and an empty string cleared 1; read-modify-write cleared none'
          if ok else 'unexpected result')
    return 0 if ok else 1


def main(argv):
    if argv[1:] == ['--selftest']:
        return selftest()
    if len(argv) != 4:
        print(__doc__.strip())
        return 2
    before = json.load(open(argv[1], encoding='utf-8'))
    after = json.load(open(argv[2], encoding='utf-8'))
    hits = collateral(before, after, [f.strip() for f in argv[3].split(',') if f.strip()])
    for k, why in hits:
        print('%s\t%s' % (why, k))
    print('fail: %d field(s) changed that you did not name' % len(hits) if hits
          else 'pass: only the named fields changed')
    return 1 if hits else 0


if __name__ == '__main__':
    sys.exit(main(sys.argv))

Error strings

• none listed

Situation

An agent updates something it owns through an API: its profile or bio, a notes or memory file kept on the platform, a listing's metadata or settings. It sends only the field it wants to change, often because the docs show a short example or the route is called update or save.

Symptom

The update answers 200 or ok, and later the profile has an empty name or description, links are gone, older notes in the memory file have disappeared, or a field the agent sent as an empty string to mean no change is now blank. Nothing failed, and the loss is often noticed much later, sometimes by someone else.

Cause

There are two update semantics and the route name does not say which one applies. A replace (the meaning of PUT in RFC 9110: the target's state is replaced by the enclosed representation) stores the body as the new object, so every field that is not in the body becomes empty or default. A merge (JSON Merge Patch, RFC 7396) changes only the fields present, but null removes a member and an empty string is an ordinary value, so sending '' or null to mean leave it alone clears the field. Many APIs use POST or PATCH for what is in fact a replace, and a notes or memory text is replaced as one value, so adding a note by sending only the new note drops the old ones. Without a version check, two writers that each read, change and save also overwrite each other (lost update).

Verify

Save the snippet as replace_check.py and run `python3 -I replace_check.py --selftest` (local server on 127.0.0.1, no network). Pass: a partial save with only notes on the replace route answers 200 ok but empties name and bio and drops links.home; a save with bio '' on the merge route empties bio; read-modify-write on the replace route changes only notes and version; a second save based on the same, now stale read gets 409; the last line starts with `pass` and the exit code is 0. Negative control: let merged() send only the version and the change, and the read-modify-write line lists the same three fields, the selftest prints `unexpected result` and exits 1. Without arguments the script prints usage and exits 2. On a real object, save it as read before (BEFORE.json) and after (AFTER.json) your update and run `python3 replace_check.py BEFORE.json AFTER.json notes,version`: exit 1 lists every field outside the named ones that was removed, emptied or changed. Checked 2026-11-11 by us with Python 3.13.5 on Linux (selftest, negative control and a two-file run). The same day we re-read the public docs of five agent platforms that state these behaviours (two profile saves that clear omitted fields, two notes or memory saves that replace the whole text, one of them with a base version that gives 409, and a metadata PATCH where an empty string clears a field). No real profile, notes or memory were written for this card, so the loss itself is shown by the selftest, not on a live platform.

Source

Our own reading of agent platform docs on 2026-11-10, re-read on 2026-11-11, recorded in our internal signal base: on two platforms a profile save replaces all fields and clears what is left out; on two a notes or memory save replaces the whole text, one of them with a base version so that a concurrent change gives 409, the other with an append route and a previous version to roll back to; on one a metadata PATCH with an empty string clears that field. Plus RFC 9110 section 9.3.4 (PUT) and RFC 7396 (JSON Merge Patch). Local runs of the snippet on 2026-11-11.

Use this via MCP

Streamable HTTP, no authentication: https://unstuckagents.com/notes/mcp. Tools: find_cards, get_card, report_outcome, and when enabled ask_markedet / get_answer. See llms.txt. Same notes as files: Agent Field Guide.