The Nexus Tuple Space
The tuple space is a shared set of small records in the engine's Postgres database. Sessions, agents, hooks, and CI leave records there for each other. Any participant can add a record, read it, or take it. A take is exclusive: when two participants reach for the same record, one gets it. A reader can also wait for a record that has not arrived yet. A task queue, a lock, a board, and a mailbox are the same operations on different record shapes.
The reference, with the exact parameters of every operation, is docs/tuple-space.md. The walkthroughs draw each use as a sequence. RDR-205 records the design, and Linda in Nexus explains what was borrowed, what was left out, and why.
Terms used on this page
| Term | Meaning |
|---|---|
| tuple | One record in the space. It has keys, dimensions, and a body. A take operation matches on the keys, and the dimensions only describe the tuple. |
| subspace | A named part of the space, such as one queue. Every tuple belongs to exactly one subspace. |
| template | The rules for one kind of subspace: required keys, allowed dimensions, lifetime, limits, and whether a take is allowed. |
| nonce | A value that the writer chooses to name one write. It is part of the tuple's identity. |
| claim, lease | A claim is the state of a tuple between a take and its end. The lease is the time limit on a claim. |
| dead letter | A tuple that failed its last allowed attempt. Nobody can take it, but anybody can read it. |
The space at a glance
Sessions and agents write records, read them, and take them. Hooks run around harness events. The agent-start hook gives each agent its id and mailbox address. The prompt hook takes the messages that wait for a session and shows them to Claude. CI writes through a webhook adapter, which posts each state change of each run and job to the CI board.
The harness already has messaging. SendMessage and teammate panes reach a live session or agent by name, and they fit when the reader is running and the answer is quick. The tuple space adds three things at that edge. A take is exclusive, so a task goes to one worker. A wait wakes when a record arrives. A lease returns a task when its holder dies. A record also stays in the engine until it expires, so the reader need not be running when it is written. Coordination compares the two point by point and covers messages between sessions and agents.
Sessions on different machines share one space when they use one engine, as every session does in cloud mode. So the exclusive take and the lease hold across machines. In local mode each machine has its own engine.
One task, end to end
A task in a work queue passes through every operation the space has, so it serves as the example for the rest of the page.
Add the task
A producer calls out on a subspace such as queue/site-demo. The engine resolves the subspace name to a template and refuses an out that does not fit it. The queue template requires one key, queue, and one dimension, from. A task may carry a shorter lifetime than the template's, set with --ttl-seconds.
The producer also supplies a nonce. The task's identity comes from its keys, from, and the nonce, never from the insert time. So a retry after a dropped connection lands on the same task. The same nonce with a different body is refused as NonceReuseConflict, because a nonce names one write. The MCP tool tuple_out has two more parameters. With mode="replace" a repeat of the nonce rewrites the task instead of refusing it, and the result says created, replaced or dirtied. With delay_s the task cannot be claimed until that many seconds have passed.
nx tuple out queue/site-demo --key queue=site-demo --dim from=planner --body "rebuild the gate jar" --nonce job-17 --ttl-seconds 120
Example output: the task, the same task again, and a changed body
$ nx tuple out queue/site-demo … --body "rebuild the gate jar" --nonce job-17 48ba5b597a1e… $ nx tuple out queue/site-demo … --body "rebuild the gate jar" --nonce job-17 48ba5b597a1e… $ nx tuple out queue/site-demo … --body "rebuild something else" --nonce job-17 Error: NonceReuseConflictError: tuple id 48ba5b597a1e… already exists in subspace 'queue/site-demo' with a different body or dimensions; a nonce names one write, so mint a fresh nonce for a new message, or resend the original body to retry
Claim it
A worker calls in with every key the template pins. A take matches on keys alone, and the call must name them all, so a wide pattern cannot claim a task by accident. The engine picks the oldest available task, skips any task that another worker is claiming at that moment, and returns it with a claim id. The task is now claimed, and the worker holds a lease: a time limit after which the engine treats the claim as abandoned. On a queue the lease is at most 900 seconds.
A worker that finds nothing can wait. With --timeout-s 25, the engine holds the call until a task arrives or the timeout ends. A signal that the engine sends after a write commits wakes the call, so nothing polls. The engine refuses a timeout above 25 seconds with TimeoutTooLong, so a wait of minutes is a loop of waits. When the engine stops for a deploy it wakes every waiter, so a deploy costs one retry.
nx tuple in queue/site-demo --pattern queue=site-demo --claimant worker-a --lease-s 60
Example output
claim_id=f99cc6e2-759a-4bc2-907f-1f0790fa298f
id: 48ba5b597a1e…
subspace: queue/site-demo
template: queue/<name>
keys: {'queue': 'site-demo'}
dims: {'from': 'planner'}
body: rebuild the gate jar
claim_state: claimedFinish, or give it back
A worker whose job runs long calls renew before the lease ends. The engine moves the lease forward but never past the task's own expiry, and it refuses a request above the template's lease cap. A renew never counts as an attempt.
When the work is done, the worker calls ack, which consumes the task. An ack can carry a reply, which the engine writes in the same transaction. A crash therefore cannot deliver the reply and leave the task to run again. When the work fails, the worker calls nack, which returns the task to the queue and counts one failed attempt. A worker that hands the task back in good order calls release, which returns it without counting an attempt. A worker that crashes calls nothing: its lease ends, the task is claimable again, and the lapse counts as a failed attempt.
Example output: a renew, then the ack
$ nx tuple renew --claim-id f99cc6e2-… --claimant worker-a --lease-s 60 …T05:22:55.375602+00:00 $ nx tuple ack f99cc6e2-… --claimant worker-a Acked claim f99cc6e2-…
Fail, and the dead letter
After three failed attempts, the engine marks the task as a dead letter. The aspect-extraction queue allows six, because its worker retries on a ladder. Nobody can take a dead letter, but any reader can see it. So a task that makes every worker fail stays visible and does not loop. A task that nobody claims expires after its lifetime, which is two days on a queue.
Example output after three claims that each ended in a nack
$ nx tuple stats queue/site-demo subspace: queue/site-demo total: 1 available: 0 claimed: 0 lapsed: 0 dead: 1 consumed: 1 expired_unpurged: 0 $ nx tuple in queue/site-demo --pattern queue=site-demo --claimant worker-a --lease-s 30 No matching tuple.
The consumed row in the census is the task that was acked above. The dead row is a second task, one that failed every attempt.
The sweep
A sweep runs in the engine every six hours. It releases claims whose lease ended and nobody retook, and it dead-letters a task that has reached its attempt limit. It removes expired tuples, consumed tuples past their retention, and old claim-log rows. The claim log gets one row for every claim, renew, ack, nack, release, lease end, and dead letter. Rows are appended and never edited, except that the purge of a tuple sets its log rows' tuple id to null. The sweep is why a worker that dies costs a delay and no task.
The other kinds
The other kinds reuse these operations, and the template decides what differs. nx tuple templates lists the templates the engine loaded.
A board is a topic where take is disabled. Each post is a new tuple, so the board is an append-only log that any number of readers read with rd. A reader that was away resumes from a cursor to see what it missed. A reader waits for the next post with a timeout on rd. The poster's from dimension is what the poster typed, so a post is input and never proof of who wrote it. The CI board has the same shape with a larger cap, because CI writes many posts for each push.
A lock is a queue of one task for one resource. Its identity is its key alone, so any process can call out to make sure the lock exists. in holds the lock, renew keeps it while the holder works, and release hands it to the next holder. ack is refused on a lock, because a consumed lock could not be taken again. A lock never dead-letters, so when a holder dies and its lease ends, the lock is free.
The directory maps a session's name to the session that holds it, and a mailbox holds the messages for one session or one agent. Coordination covers both.
| Kind | Take | Lifetime | Limits |
|---|---|---|---|
queue/<name> | yes | 2 days | 10,000 live rows, 3 attempts |
aspects | yes | 90 days | 10,000 live rows, 6 attempts |
lock/<resource> | yes | 7 days | never dead-letters |
board/<topic> | no | 7 days, or less if the post sets it | 500 live posts, 1,024-byte body |
board/ci/<topic> | no | 3 days | 5,000 live posts, 1,024-byte body |
mailbox/<address> | yes | 7 days | 3 attempts |
directory/<name> | no | 7 days | no body |
Who decides what
| Decision | Made by |
|---|---|
| Which shapes exist, and their lifetimes and limits | The templates, which the engine loads from files at start, so every client sees the same shapes |
| Whether a write fits its template | The engine, on every out |
| Which caller wins a take | The engine, in one short transaction |
| Whether a lease still holds | The engine's clock |
| Whether work is done, failed, or handed back | The worker, by ack, nack, or release |
| What a body means and what to do about it | The producer and the worker. The engine never reads a body. |
| Who may write or take | Any caller that holds the tenant's credential. Nothing below the tenant has an identity the engine could check, with one exception: a board-ci token can only post with out to board/ci/<topic>. |
| Whether a session acts on a record | Claude, in that session. The prompt hook claims and acks a message and shows it to Claude, which decides what to do with it. |
Limits and health
The engine enforces each limit below except the last, and refuses a call that breaks one with a named error. The last is the page size of the tuple_list MCP tool.
| Limit | Value | When it is broken |
|---|---|---|
| Body | 4,096 bytes, or less if the template sets it | TooLarge |
| One key, dimension, or pattern value | 256 bytes | TooLarge |
| One request | 8,192 bytes | refused before parsing |
| One wait | 25 seconds by default | TimeoutTooLong |
| One lease | 900 seconds on a queue, a lock, or a mailbox | LeaseTooLong |
| Wait slots | 4 for each claimant, 16 for the engine, by default | ParkCapExceeded: the caller gets the probe result and backs off |
| Live rows in a subspace | the cap in the table above | the write is refused until rows are consumed or expire |
Subspaces in one tuple_list page over MCP | 100 | the page ends with the cursor for the next one |
Three reads show the state of the space. tuple_list and nx tuple list give one line for each subspace with its counts of available, claimed, dead, and consumed tuples. tuple_stats and nx tuple stats give the census of one subspace. tuple_rd and nx tuple rd with an empty pattern match every live tuple in a subspace, each with its state, including claimed tuples and dead letters. A read returns one tuple unless the caller sets n (-n on the command line) or passes --all to nx tuple rd.
Example output: list the mailboxes, then read one
$ nx tuple list --prefix mailbox/
mailbox/0f3c9023-… total=0 available=0 claimed=0 lapsed=0 dead=0 consumed=31 expired_unpurged=0
mailbox/9b5eeb37-… total=1 available=1 claimed=0 lapsed=0 dead=0 consumed=20 expired_unpurged=0
$ nx tuple rd mailbox/5b354c36-… -n 300
id: adb98e40…
subspace: mailbox/5b354c36-…
keys: {'to': '5b354c36-…'}
dims: {'from': 'cdeb12b5-…', 'kind': 'reply', 'address_kind': 'session', 'correlation_id': 'r-41'}
body: Subscribed. I am on the channel now …
claim_state: claimednx doctor has seven rows for the space. Each one watches one thing:
- the age of the oldest unclaimed tuple in each subspace
- a lock held for longer than four times its maximum lease, which is one hour for a lock
- the dead-tuple ratio and the last autovacuum of the tuple table
- the age of the least recently swept tenant
- how full the engine's wait slots are
- how deep a work queue's backlog has grown
- whether this session's push channel is alive
A stopped sweep, a subspace that fills faster than it drains, and a quiet channel each show up in one row.
Reference
Nothing here is needed to read the page. It holds the operations, the surfaces, the comparison with the other stores, and the engine's internals.
The operations
| Operation | Effect |
|---|---|
out | Adds a tuple. Its identity comes from fields that the caller supplies, so the same fields give the same tuple. |
rd | Reads matching tuples, which stay in the space. A read matches on keys only: equality on any subset of the pinned keys, and an empty pattern matches all. With a timeout it waits for a match, and a cursor resumes after the last row read. |
in | Claims one matching tuple. The call pins every key, and exactly one caller wins. |
ack | Consumes a claimed tuple, optionally with a reply written in the same transaction. A lock refuses it. |
nack | Returns a claimed tuple and counts a failed attempt. It can hold the tuple back for a number of seconds, or dead-letter it at once. |
renew | Extends a live lease. It never counts an attempt. |
release | Returns a claimed tuple without counting an attempt. |
wait | Parks one call across several subspaces, so a session that watches many mailboxes and boards spends one wait slot. The session's own Nexus server calls it. It has no MCP tool, and nx tuple wait is its command-line form, described under push delivery in Coordination. |
The surfaces
| Surface | What it is |
|---|---|
| MCP tools | mailbox_send, tuple_out, tuple_rd, tuple_in, tuple_ack, tuple_nack, tuple_renew, tuple_release, tuple_registry, tuple_list, tuple_stats, and three that manage what a session's own channel delivers: tuple_subscribe, tuple_unsubscribe, tuple_subscriptions. Claude calls these inside a session. |
nx tuple | The same operations from the terminal: out, rd, in, ack, nack, renew, release, wait, templates, dictionary, list, stats, and directory. The dictionary verb says what each template is for and shows the census of each subspace. Hooks and scripts call these. |
| Hooks | The agent-start hook gives each agent its id and mailbox address. The prompt hook takes the messages that wait for the session and shows them to Claude. |
| Skill | /conexus:mailbox holds the rules for sending and reading messages. |
The space and the three stores
| Store | Holds | Lifetime | Readers |
|---|---|---|---|
| Scratch (T1) | Working notes of one session and its agents | The session | Many |
| Memory (T2) | Decisions, findings, and the state of the work, by project and title | The project | Many |
| Knowledge (T3) | Documents, chunks, the catalog, and its links | Permanent | Many |
| Tuple space | Coordination: a task, a lock, a message, a post | Days, set by the template | Many read, one takes |
All four stores share one database and one tenant. A tuple can therefore name an item in any of the other three, and the reader opens it with the credential it already has. A tuple is a signal about data, so a body carries a pointer to its content. The pointer is a content hash for a chunk, a catalog address for a document, or a project and title for a memory entry. The content is stored once in the right store. A copy inside a body goes stale when somebody corrects the original, and a pointer can be checked where a copied value cannot.
Inside the engine
- One Postgres table holds the tuples. Subspace, keys, dimensions, body, expiry time, and claim state are columns, and a claim-log table beside it records every claim event. The row-level security that separates one tenant's memory from another's applies to tuples unchanged.
- A take is one statement. The engine selects the oldest available row for the given keys, skipping any row another transaction holds, then locks it, marks it claimed, and logs the claim. Every operation is one short transaction, so a busy subspace does not slow a quiet one.
- A lease bounds every failure. Every claim has an end time, and a claim can never outlast its tuple. A small set of operations with exact meanings makes it possible to say what happens to any tuple under any sequence of calls, including a crash between a take and its ack.
- Waiting happens inside the engine. A waiting call waits on a signal for its subspace, and a write in another subspace does not wake it. The client does not poll, and each wait is bounded below the client's own timeout, so the engine's cap always fires first.
- Templates are delivered with the engine. The engine loads them at start and checks them, and a client can ask for the templates and their digest, a short fingerprint that changes when any template changes.