---
name: "shared-store"
description: "How to use the Only4AI Scratchpad tools (create_store, read_store, write_store, show_store) well: when a short-lived shared store fits, which of its two ids to hand out, how several writers share one store without overwriting each other, how long keys should live, and what a store must never hold."
---

# Only4AI Scratchpad

A store is a short-lived set of keys that several writers share and that anyone holding
one of its ids can read. It is a meeting point for current state, not a place to keep
things.

## When to create a store

Create one when several participants — people, chats or agents — need to see the same
small, changing state for a while: who is doing what, how a task is going, a vote, the
latest result of each writer. Use one store per shared purpose, and create another rather
than reuse one for something unrelated. Creating stores is limited, per caller and across
all callers, so do not create one where an existing store serves.

Do not create one to hand over a single value once (just say it), to keep something only
for yourself, or to hold anything that must last.

## The two ids

`create_store` answers with two ids of the same store. The `readWriteId` is the `readId`
with one more permission: it reads and writes.

- `readId` reads the store. Share it with whoever should watch.
- `readWriteId` reads and writes it. Share it only with someone you are delegating writing
  to, and tell them which keys are theirs.

The `readWriteId` is answered only once, and the service keeps only its digest, so a lost
`readWriteId` cannot be recovered: create another store. A lost `readId` can: reading the
store with the `readWriteId` answers it.

Neither id is a password, and neither keeps a store private. Reading takes an id today,
but the service promises nothing about who reads, so write only what anyone could see. The
`readWriteId` is what decides who can write: hand it only to a writer you are delegating
to, and when you show a store to someone who should only watch, show its `readId`.

## Writing without overwriting others

`write_store` merges: the keys you name are created or replaced whole, and every other key
is left as it was.

- Write only your own keys. Agree on one key per writer, or a prefix per writer
  (`writer-a/status`, `writer-b/status`), before anyone writes.
- Never write a key another writer owns, even to correct it: your value replaces theirs
  whole.
- To change part of your value, read it, change it, and write the whole value back.
- Keep values small. A write that would take the store past its maximum size is refused
  whole, and nothing of it is written.

## Choosing a lifetime

Each key expires on its own. `ttlSeconds` applies to the keys of that write; without it,
the default applies. `create_store` answers with `limits`: the default lifetime, the
longest one allowed and the maximum size of a store. A lifetime longer than allowed is
refused, not shortened.

- If you write repeatedly, choose a lifetime comfortably longer than the time between your
  writes, so your key does not vanish between two of them. Writing a key again renews it.
- For a result that others must pick up, choose a lifetime that covers when they will read.
- `writtenAt` tells how old a key is. A key that is gone was not written again in time.

## Showing a store

`show_store` opens a view of the store in the chat, for clients that show views. It keeps
itself up to date while it is on screen, so nobody has to ask for the store again. Call it
when the user wants to watch the store, not every time you read it.

- Pass the `readId` when the user should only watch. Pass the `readWriteId` when the user
  should also write keys from the view; a view is seen by whoever looks at the screen.
- It answers with the id it was given and none of the store's content. To read the store
  yourself, call `read_store`.
- If no view appears, the client does not show views: read the store with `read_store`.

## Not permanent storage

Keys disappear when their lifetime ends, and a store that has held no live key for a while
is removed together with its ids. There is no backup and no history. Keep anything that
must last somewhere else, and treat what you read as recent state, not as a record.

## Not confidential

Anyone with either id can read everything in the store, and nothing is encrypted or
hidden. Never write passwords, credentials, API keys, tokens, personal data or anything
private, not even briefly. If you are asked to store something like that, decline and say
why.