wontopos-mcp 1.0.18 → 1.0.19

package/README.md

@@ -1,8 +1,8 @@
 # wontopos-mcp — one memory across every AI tool
 
-> **Beta.** The ten tools work today and are tested, but the surface may still
-> change as we finish it. The [API and SDKs](https://wontopos.com/en/why)
-> underneath are stable and versioned.
+> **Stable.** The tool names, their arguments and the shape of their results are a
+> contract now: a change that would break a working install waits for a major version.
+> The [API and SDKs](https://wontopos.com/en/why) underneath are versioned separately.
 
 [Wontopos (WOS)](https://wontopos.com) long-term memory as an [MCP](https://modelcontextprotocol.io) server.
 
@@ -10,7 +10,7 @@ Memory belongs to your **account**, not to a tool. The same store recalls in
 Claude Code, Claude Desktop, Cursor — and in ChatGPT via Actions with the same
 API ([openapi.json](https://api.wontopos.com/openapi.json)) — so a conversation
 started in one tool continues in another. The same recall in every language - no language
-is privileged - with bounded context (~1,200 tokens) per recall.
+is privileged - with bounded context (~1,000 tokens on `tablet-2`, the default engine) per recall.
 
 ## Claude Code
 
@@ -59,14 +59,18 @@ Create a key in the [console](https://wontopos.com). Optional env:
 | `WONTOPOS_VERIFY` | Default re-ask passes for `search`, 0-3. Default `0`. Each pass is another engine call, billed for what it delivers; the agent can raise it per call. |
 | `WONTOPOS_MAX_IMAGES` | Default photo results per `search`, 0-5. Default `0` — see below. |
 | `WONTOPOS_BASE_URL` | A different API host. Leave unset for the default. |
+| `WONTOPOS_HTTP_PORT` | Serve over HTTP instead of stdio, for hosts that cannot spawn a process. Needs `WONTOPOS_HTTP_TOKEN`. |
+| `WONTOPOS_HTTP_TOKEN` | Bearer token every HTTP request must carry. The server refuses to start HTTP mode without one. |
+| `WONTOPOS_HTTP_HOST` | Interface to bind in HTTP mode. Default `127.0.0.1` - this machine only. |
+| `WONTOPOS_HTTP_ALLOWED_HOSTS` | Comma-separated `Host` values to accept in HTTP mode. A tunnel forwards its own name, and an undeclared one is refused 403. |
 | `WONTOPOS_READ_ONLY` | `1` / `true` / `yes` / `on` / `y` / `t` = read tools only, see Security. A value that is none of those (and none of `0` / `false` / `no` / `off`) stops the server rather than being read as off. |
 | `WONTOPOS_ALLOW_STORE_OVERRIDE` | `1` (same spellings) = multi-store; default = pinned, see Security. |
 
-**Why photos default to none.** The caller here is a model reading JSON. An image
-memory arrives as a row of metadata and a caption, not a picture it can look at, so
-the service default of one photo per search spends context on something the agent can
-only paraphrase. Raise `WONTOPOS_MAX_IMAGES` (or pass `max_images` on a single call)
-when the user is actually asking about photos.
+**Why photos default to none.** Not because the model cannot see them - `view_image`
+hands over the actual picture - but because the rows ride on *every* search, and most
+searches are not about photos. Raise `WONTOPOS_MAX_IMAGES` (or pass `max_images` on a
+single call) when the user is asking about pictures, then call `view_image` on the row
+worth looking at.
 
 The server asks the service what the configured model can serve, once at boot, and
 says so in its startup line. On an engine without the photo channel or re-ask, those
@@ -81,14 +85,19 @@ quietly ignored, and that refusal would otherwise land on every search.
   stores? Register the server once per store (each entry stays pinned).
 - **Bounded results.** A tool result is capped at 128 KB (measured in UTF-8
   bytes, so the bound holds for CJK too) before it reaches the model, so
-  an oversized memory cannot blow up the conversation context.
+  an oversized memory cannot blow up the conversation context. `view_image` is the
+  exception and is bounded differently: base64 cannot be trimmed without destroying
+  the picture, so a photo over 5 MB is refused rather than cut.
 - **Use a dedicated key.** Keys carry their workspace, so a key made just for
   MCP scopes what connected tools can ever touch. Rotate it in the console
   anytime without touching your app's keys.
 - **Read-only mode.** `WONTOPOS_READ_ONLY=1` registers no write tools at all:
-  the agent can recall, search, list memories, run engrams, read stats and read
-  revisions, but cannot store, update, forget, or delete. Right for agents that should consult
-  memory, not own it.
+  the agent can recall, search, list memories, run engrams, read stats, read
+  revisions, view an image and read `usage`, but cannot store, record turns, update,
+  forget, or delete. `usage` is a read, so read-only mode still lets the agent see
+  the account's balance and this key's spend. Right for agents that should consult memory, not own it. The connect-time
+  instructions drop the `store_turn` guidance there too, rather than pointing the
+  model at a tool that is not registered.
 - **Keep tool confirmation on.** MCP hosts ask before running tools by default;
   leave that on for `forget` in particular (deletes are shared by every tool on
   the store).
@@ -107,17 +116,55 @@ quietly ignored, and that refusal would otherwise land on every search.
 
 | Tool | What the agent does with it |
 |---|---|
-| `recall` | One-call context: recent turns + relevant long-term memories + surroundings. First call when past context matters. |
+| `recall` | One-call context: the **last 20 turns** (oldest first, one entry per utterance, so ten exchanges) plus relevant long-term memories and surroundings. First call when past context matters. `limit` (5-20) widens the sweep; `context_limit` (0-20) sets how much surrounding conversation rides along, `0` for the memories alone. Both need a limit-aware engine — an older one refuses the whole call, and the tool says which argument to drop. |
 | `remember` | Store what the user said that is worth keeping. `speaker: "me"` = the agent's own spoken commitments. Fetched content (search results, files) is not a memory. |
+| `store_turn` | Record one exchange as short-term history - what the user said and what the agent replied. This is what fills `recall`'s 20-turn window — one call appends two entries — and nothing else writes it, so the agent is told to call it after **each** exchange. A turn is billed like any write and is kept long-term as well, searchable afterwards. |
 | `search` | Search stored memories. `filters` narrows by TIME or topic (`event_from`/`event_to` = when the content happened, `categories`) — for "what did we decide in June?", which a query alone will not pin down. `verify` (0-3) spends extra passes to reach further back; `max_images` (0-5) asks for photos. Answers with `memories`, plus `images` and `verify_used` when those applied. |
 | `update` | Rewrite a memory the user's own words contradicted - keeps what is still true, adds what changed. |
 | `forget` | Delete one memory by id. |
 | `list_memories` | Browse everything stored (original text + metadata, paged) - "what do you know about me?", housekeeping. |
 | `engram` | Multi-hop retrieval, no LLM: `deep_recall` (thorough), `timeline` (when did X), `gather` (everything related), `equilibrium` (replies that have started to loop or flatten), `tone_stabilizer` (back to the assistant's usual register). The API is the authority - an unknown name answers with the list it accepts. |
-| `stats` | Memory counts for a store. |
+| `view_image` | Fetch the actual picture behind an image memory, as an image the model can look at rather than a caption it can only paraphrase. One photo per call. |
+| `usage` | What this key has spent and what is left — its lifetime cost, its workspace and per-store cost over the last `days` days, and the account's prepaid balance. Free to call. Lets an agent decide whether to keep going. |
+| `stats` | Counts for a store. Not the number of things a person told you, so it is a cheap check rather than an answer to "how much do you remember about me?" - `list_memories` answers that. |
 | `revisions` | How much of the store has been changed since it was written: counts by default, up to 20 memories on request. |
 | `create_store` | Creates the pinned store after asking the user (any store with `ALLOW_STORE_OVERRIDE=1`). |
 
+## Running it over HTTP yourself
+
+Some hosts reach a URL rather than spawning a command. The same server answers over
+HTTP when you give it a port:
+
+```bash
+# Make the token first — the server never prints it, and callers need it.
+TOKEN=$(openssl rand -hex 32); echo "bearer token: $TOKEN"
+
+WONTOPOS_API_KEY=wos-live-... \
+WONTOPOS_USER_ID=my-project \
+WONTOPOS_HTTP_PORT=8787 \
+WONTOPOS_HTTP_TOKEN="$TOKEN" \
+  npx -y wontopos-mcp
+```
+
+Same thirteen tools, same store, same 20-turn window. Callers send
+`Authorization: Bearer <token>`.
+
+It binds `127.0.0.1` unless `WONTOPOS_HTTP_HOST` says otherwise, and **will not start without a token**: the reason to run this mode
+is usually to put it behind a tunnel, and an open listener there is a public door to
+your memory. Put a tunnel in front of the port rather than binding a public interface,
+and treat the token like the API key.
+
+**Behind a tunnel, name it.** The server checks the `Host` header, and a tunnel forwards
+its own public name rather than `127.0.0.1` — so declare it or every call is refused 403
+before a tool runs:
+
+```bash
+WONTOPOS_HTTP_ALLOWED_HOSTS=your-name.ngrok.io   # or the trycloudflare / Funnel name
+```
+
+Loopback and the bind address are always accepted. The refusal names the header it saw
+and the variable to set, and the boot line lists what is currently accepted.
+
 ## Hosted endpoint (for hosts that can't run a local process)
 
 Some MCP hosts only speak remote MCP — they cannot spawn `npx` on your machine. Those
@@ -142,10 +189,12 @@ connect to the hosted endpoint instead. Same memory, same stores, same account:
 by the model — the tools take no store argument, so a prompt-injected model cannot move
 to a sibling store.
 
-It offers `recall` · `search` · `remember` · `list_memories` · `stats` · `revisions` ·
-`engram` — the retrieval and write core. The curation tools (`update`, `forget`,
-`create_store`) are local-only for now. That is all ten; the two lists used to account
-for nine, and `revisions` was in neither.
+It offers six of the thirteen: `recall` · `search` · `remember` · `list_memories` ·
+`stats` · `engram` — the retrieval core plus one write. `update`, `forget`,
+`create_store`, `revisions`, `store_turn`, `view_image` and `usage` are local-only. This list
+has been wrong twice: it once accounted for nine tools with `revisions` in neither
+column, and then named `revisions` as hosted when the endpoint has never served it.
+Six is what the endpoint answers `tools/list` with today.
 
 The endpoint is a protocol adapter, not a second way in: every tool call re-enters the
 ordinary `/api/v1/memory` routes carrying your key, so the same authentication, rate
@@ -166,12 +215,105 @@ we ship?" — same memory answers.
 
 Uses the [`wontopos`](https://www.npmjs.com/package/wontopos) SDK underneath, so
 automatic retries, redirect refusal, response caps, and key hygiene apply as-is.
+Pinned to one exact version, not a range: `search` and `recall` take their count
+bounds from it, so a range would let two installs of the same wontopos-mcp
+advertise different limits.
 
 - Docs: <https://wontopos.com/en/why>
 - Spec: <https://api.wontopos.com/openapi.json> · <https://wontopos.com/llms.txt>
 
 ## Changelog
 
+- **1.0.19** - out of beta, and the release that made `recall` keep the other half of
+  its promise. It opens by offering "recent turns", and nothing in this server could
+  ever write one: turns go through their own API route, every tool here wrote
+  memories, so on an install where MCP is the only client `short_term.turns` was
+  permanently empty. `store_turn` writes them, and the connect-time instructions ask for
+  one after each exchange — a window only holds what is fed to it every turn — which is
+  what makes a conversation started in one tool continue in another rather than merely
+  being briefed by it. That is a write per exchange, billed as one, and kept long-term
+  and searchable like any other; an agent that should only consult memory belongs in
+  `WONTOPOS_READ_ONLY=1`, where `store_turn` is not registered at all. `recall` also takes `limit` and
+  `context_limit` at last; it had exactly one argument, so every answer was ten
+  memories with ten rows of context and no way to ask for a wider sweep or to decline
+  the context block, which is the larger half of the reply.
+
+  `recall` now states a short-term contract: **the last 20 turns**, one per utterance, oldest
+  first, alongside the long-term matches. The window is applied on the way out, and
+  `count` reports what was delivered. Turns were always in the reply, but when one had to be
+  trimmed to fit the byte cap they were halved **from the front** — keeping the oldest
+  and dropping what had just been said, which is backwards for the one list whose whole
+  value is recency. The recent end is kept now. `search` carries no turns and never did:
+  recent conversation belongs to `recall`.
+
+  **You can look at the photos now.** `view_image` returns the actual picture as an
+  MCP image block. The reason `max_images` defaulted to 0 was written down plainly —
+  "you get a row of metadata and a caption, not a picture you can look at" — and that
+  was true of this tool, never of the protocol: MCP has carried an image content block
+  all along and the SDK has had `getImage` since Tablet 2. The default stays 0 for the
+  reason that is still true (those rows ride on every search, and most searches are
+  not about photos), and the picture is now one call away.
+
+  **Cancelling a tool call stops paying for it.** Hosts cancel — a user presses stop,
+  a turn is abandoned — and the host stops waiting the moment it sends
+  `notifications/cancelled`. Nothing here was listening, so the API call carried on: a
+  `verify=3` search ran three engine passes for an answer nobody would read, billed in
+  full, and a retry backoff outlived the conversation that asked for it. Every tool
+  call now runs against a client bound to that request's signal.
+
+  **Every tool declares an `outputSchema` and answers with `structuredContent`**, so a
+  host gets the reply as data instead of re-parsing it out of a string. The schemas
+  name fields and explain them but assert no types: the SDK validates structured
+  content and a mismatch is a *protocol* error, so a schema strict enough to reject an
+  added service field would break a live call over a compatible change.
+
+  Four bugs, one of which was writing wrong data. **A bare number was accepted as an
+  `event_date`** — `Date.parse` does not refuse one, it answers: `"5"` is May 2001,
+  `"0"` is January 2000, `"202603"` is the year 202603. A model emitting a day number
+  or a unix timestamp got a fabricated date written onto the memory, and `event_date`
+  is the axis `event_from`/`event_to` search on, so the memory was filed under a date
+  nobody would look in and nothing about it read as wrong. **List arguments had no
+  length bound**: the per-entry cap measured each string and nothing measured the
+  list, so `filters.categories` and `revisions.skip_ids` took fifty thousand entries
+  and put half a megabyte on the wire — the hole 1.0.17 closed for scalars, still open
+  on the axis that multiplies. **`event_date` had no size cap at all**, the one
+  free-text argument the audit skipped. And **the truncation note overwrote a service
+  field of the same name**, so a reply carrying its own `_truncated` had it replaced
+  by ours.
+
+  New tool: **`usage`**. A model spending an account's money should be able to see the
+  bill. It answers with this key's lifetime cost, its workspace and per-store cost over
+  the window, and the prepaid balance that gates the next call — so "should I keep
+  searching or stop" has numbers behind it. Free, and it skips the balance gate: charge
+  for it and an account at zero cannot find out why, because the gate would refuse the
+  very call that explains the refusal. Scoped to the calling key; it never returns a
+  sibling key's spend.
+
+  From an audit against the SDK, four configuration mistakes that used to be reported
+  wrong. A key with a stray newline or a control byte in it — the mistake most likely
+  to be made by hand, pasting out of a terminal or a YAML block — **killed the process
+  with a stack trace out of `node_modules`**, which most MCP hosts show only as "the
+  server failed to start"; the SDK refuses those by throwing from its constructor and
+  nothing here caught it. Same for an unusable `WONTOPOS_MODEL`. Both now exit with one
+  sentence naming the variable, and the key is never echoed. An unparseable
+  `WONTOPOS_BASE_URL` was worse than either: the SDK never parses that value, so the
+  server announced itself **ready**, and then every call failed with "Failed to parse
+  URL" while the boot check said "continuing anyway" — the same situation as an
+  unusable store id, which has exited since 1.0.12, and now so does this.
+
+  The count range is no longer restated. `search` and `recall` build their bounds from
+  the SDK's exported `SEARCH_LIMIT_MIN`/`MAX` and `CONTEXT_LIMIT_MIN`/`MAX` instead of
+  spelling `5` and `20` into four places — this package has already shipped `search`
+  declaring 1..60 while `recall` said 5..20 and the service capped at 50, and a copy is
+  a copy whether or not it agrees today.
+
+  The oversized-reply path no longer produces unparseable text. A single memory too big to
+  drop used to be handled by slicing the serialized JSON — no closing bracket,
+  unparseable, and labelled as such, which is the one outcome the whole cap exists to
+  avoid. The long strings inside the object are cut instead: the same tail is lost and
+  what arrives is still a document. Underneath, the `wontopos` SDK floor moves to
+  **2.2.37**, the release that carries the `usage()` this server's new tool calls.
+
 - **1.0.17** - an install-wide default is no longer refused as though it had been
   asked for. `WONTOPOS_VERIFY` or `WONTOPOS_MAX_IMAGES` set against an engine without
   that capability made *every* search fail with "needs Tablet 2 or newer … search
@@ -271,8 +413,7 @@ automatic retries, redirect refusal, response caps, and key hygiene apply as-is.
   whole store and hoped. A filter chooses what is searched, not what is kept
   afterwards, so a narrow filter still fills your `limit` from inside it. The object is
   `.strict()`: a typo like `catagories` is refused instead of silently widening the search
-  back to everything, and only customer-facing keys are accepted so the engine's internal
-  filter vocabulary cannot be enumerated a guess at a time.
+  back to everything.
 - **1.0.8** - two bugs found by driving the server over stdio rather than reading
   it. A store id with stray whitespace **split the store in two**: the client was
   built from the raw env while the boot check, the ready line and `create_store`