The LAST free Semurg nodes EVER: the first 1,000 are free, for a limited time. After that, every node is US$139, paid once.

Blog / How-to guides

Put, get many, put if absent, delete: values under whole-number keys

12 October 2026 · Semurg · 2 min read · Markdown

Last checked on r11.168.20261114.da3a8f8 (14 Nov 2026): every command below ran on a fresh node of that release. The current release is r11.173.20261116.3006727 (16 Nov 2026), and the commands have not been re-checked on it yet (how)

key-valuecachedatabasehow-to

A key-value store answers one question very often: what is stored under this key? Semurg answers it with the same door it uses for objects and documents: a value under a whole-number key, read back by key. This post is about using that door as a key-value store.

Under one whole-number key: a put stores a new version, a put-if-absent leaves a held value alone, a get answers present or absent, and a delete makes later gets answer deleted.A whole-number keyPut: a new versionPut if absent: a heldvalue staysGet: present or absentDelete: later gets saydeletedUnder one whole-number key: a put stores a new version, a put-if-absent leaves a held value alone, a get answers present or absent, and a delete makes later gets answer deleted.A whole-number keyPut: a new versionPut if absent: a heldvalue staysGet: present or absentDelete: later gets saydeleted

Put, get and delete

Keys are whole numbers; values are base64 bytes. One call puts many, and "content": true makes it a put-if-absent: a key that already holds a value keeps it, and the reply counts it as skipped.

A string key such as a user name or a session token is hashed in your code to a whole-number key, which the object door stores and reads.Your string keyHash it in your codeA whole-number keyThe object door
bash
export SEMURG_API_TOKEN=<your token>
curl -sS http://localhost:4000/v1/query \
  -H "Authorization: Bearer $SEMURG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"op": "object_put", "content": true,
       "objects": [{"id": 900000000701, "value_b64": "c2Vzc2lvbjogZGFuYQ=="},
                   {"id": 900000000702, "value_b64": "c2Vzc2lvbjogbGVl"}]}'

Expected: both keys are written, because neither held a value

Run that put a second time, before anything else, and both keys are skipped. Without "content": true, a put to a key that holds a value replaces it with a new version, and reads return the newest.

Get many keys in one call; each answers in the order you asked:

bash
export SEMURG_API_TOKEN=<your token>
curl -sS http://localhost:4000/v1/query \
  -H "Authorization: Bearer $SEMURG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"op": "object_get", "ids": [900000000701, 900000000702, 900000000799]}'

Expected: the two keys you put are present with their values, and the third is absent

Delete a key:

bash
export SEMURG_API_TOKEN=<your token>
curl -sS http://localhost:4000/v1/query \
  -H "Authorization: Bearer $SEMURG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"op": "object_delete", "ids": [900000000702]}'

Expected: one key deleted

Read it again and the key answers deleted, with the version it was deleted at, rather than pretending it never existed:

bash
export SEMURG_API_TOKEN=<your token>
curl -sS http://localhost:4000/v1/query \
  -H "Authorization: Bearer $SEMURG_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"op": "object_get", "ids": [900000000702]}'

Expected: the deleted key answers deleted

How it behaves

  • Keys are whole numbers: map your names to them.
  • A put writes the whole value.

Next

What Semurg is: Give Claude Code, Cursor and your other AI agents a memory that lasts: install Semurg on your own machine in one line.

Why use it: your agent recalls the facts it needs, each with its source, instead of re-reading the project.

What it solves today: agents that forget between sessions, and data that must stay on your own machines.

This post was written with AI assistance. Every result in it is checked against a published release or record before the post goes out.

How these commands were checked

Our test farm ran each of the 4 command blocks marked runnable, exactly as written, with the answer checked against the expectation printed under it, against a fresh node of the published release r11.168.20261114.da3a8f8. A post is published only when every one of them passed there.

Related