Wontopos — long-term memory for AI agents
pip install wontopos
Get an API key in the console. Keys look like wos-live-...;
Client.from_env() reads WONTOPOS_API_KEY from the environment instead.
from wontopos import Client
mem = Client(api_key="wos-live-...")
# Each end-user / agent / topic gets its own store — create it once.
# (A "default" store already exists, so you can skip this and omit the id.)
mem.create_store("alice")
mem.add("she prefers tea over coffee", user_id="alice")
# one call → short-term + long-term + context, ready for your LLM prompt
ctx = mem.recall("what does alice drink?", user_id="alice")
Why
- The same in every language — identical recall whichever language a memory was written in (Korean · Japanese · Chinese · English).
- We never run an LLM over your stored memories. Sleep, when you turn it on, runs on your own model with your own key.
- Bounded retrieval —
recall()returns the recent turns, at mostlimitlong-term memories (default 10, up to 20) and at mostcontext_limitrows of the surrounding conversation (default 10, up to 20), however much you've stored. Your LLM bill stops growing with history.
Methods
| Method | What it does |
|---|---|
| Write | |
add(content, user_id, **metadata) |
Store one memory. Alias store. image= attaches a photo, and created_at= says when it was said (from Scroll 2 on). |
add_turn(user_msg, assistant_msg, user_id?, created_at=, user_speaker=, assistant_speaker=) |
Store one exchange of a conversation, optionally with when it was said (an RFC 3339 time with Z or ±hh:mm, or an aware datetime) and who said each side. |
add_bulk(content, user_id, category=, timestamp=) |
Backfill a long history in one call. |
update(old_memory_id, new_content, user_id?) |
Replace a fact that changed. The old version stays in its history. |
| Read | |
recall(query, user_id) |
The recent turns, the memories that match and the conversation around the best one, in one call. From Scroll 2 on, the last three days by part of the day too. |
search(query, user_id, limit=10, **opts) |
The memories that match, best first. limit caps these; the assistant's own words and image memories, when there are any, follow them (with filters, the assistant's words are left out). For an LLM's context, use recall. |
search_full(query, user_id, limit=10, **opts) |
The same search with each part kept apart, images and verify_used included. |
search_self(query, user_id, ...) |
The assistant's own words, kept apart from what others said. |
history(user_id) |
The recent conversation. |
memory_tools(user_id, preset="S-2", seen=True) |
Adds memory_recent and memory_seen to the memory tools: the recent conversation, newest first, and the memories held for one of its lines as they stand now. Off by default; memory_recent takes each reply's count from history, and memory_seen asks seen once. |
get(user_id, memory_id) |
One memory by id and its metadata. |
list_memories · iter_memories · export_memories |
Every memory in a store: a page at a time, as a stream, or all at once. |
lineage(user_id, memory_id) |
The edits that followed one memory. |
revisions(user_id) |
How many of a store's memories were edited, and which. |
stats(user_id) |
Counts for a store. |
engram(name, query, user_id) · list_engrams() |
Built-in retrieval routines, and the ones a model can run. |
| Photos | |
list_images · iter_images · export_images |
A store's image memories, newest first. |
get_image(user_id, memory_id) |
The bytes of one image, and its content type. |
forget_image(user_id, memory_id, preview=False) |
Remove the photo from a memory. preview=True first says whether the memory itself stays. |
| People | |
add_speaker(speaker, user_id?) |
Register a person (explicit, up to 50 to start). |
list_speakers(user_id?) |
Registered people and per-person memory counts. |
remove_speaker(speaker, user_id?) |
Unregister; memories stay. On scroll-2 and tablet-2 they keep the name. The store's default speaker is refused (409 speaker_is_default). |
by_speaker(speaker, user_id?) |
What one person said, newest first. |
| Stores | |
create_store · list_stores · delete_store |
One isolated memory space per end-user, agent or topic. Where only an admin key lists stores, list_stores with a standard key raises PermissionDeniedError. |
delete(user_id, memory_id) · delete_all(user_id) |
Delete one memory, or every memory in a store. delete_all also clears the store's time zone and speakers: a Scroll 2 store needs set_settings and its speakers again before the next write. |
| Account | |
list_models() |
The models you can use, and what each can do. |
usage(days=7) |
What this key, its workspace and its stores have spent. Free. |
ping() |
Check the key and the connection. |
key_scope() |
What the key may do: "full", "read" or "admin". An admin key lists stores and reads usage, and opens no memory. |
| Client | |
with_model · with_user · with_deadline · with_timeout · with_retries |
A copy of the client with another model, store, budget, timeout or retry count. |
Client.from_env() · rate_limit · close() |
A client with the key from the environment; the last call's rate-limit numbers; release the connections. |
Every method that works on a store takes a user_id — it names the store: one isolated memory space per end-user, agent, or topic, then per workspace (your API key's). WHO said each memory inside a store is the speaker tag below — storing the assistant's own words never needs a separate id.
Memory tools presets
The memory tools have two presets on scroll-2:
| Preset | For | Its first look |
|---|---|---|
S-2 |
measuring memory | the question alone, the assistant's own lines included |
S-2-live (default) |
everyday conversation | the question with the last two lines said in the past five minutes, the assistant's own lines left out, spread across topics and time |
Putting recall into a prompt
ctx = mem.recall(user_message, user_id="alice")
system = "\n".join([
"What you remember about this user, most relevant first:",
*(f"- {m['content']}" for m in ctx["long_term"]["memories"]),
"",
"From the last three days:",
*(f"- {m['content']}" for m in (ctx.get("rooms") or {}).get("memories", [])),
"",
"Around the most relevant memory:",
*ctx["context"]["around_top_memory"],
"",
"The conversation so far:",
*(f"{t['role']}: {t['content']}" for t in ctx["short_term"]["turns"]),
])
# Call your language model with `system` and the user's message, then store the exchange:
mem.add_turn(user_message, reply, user_id="alice")
Each row of around_top_memory starts with [before] , [match] or [after] : where it
sits next to the best memory. Keep every list in the order it arrives. From Scroll 2 on, the rooms' memories, from the last three days, come in
rooms; on a model before it that list is empty.
Who said it (speakers)
Every memory can carry a speaker: "me" for the assistant's own words, or a
person's name. Speakers are explicit, like stores: register a person once,
then store under their name — a typo can never silently become a new person.
Search accepts a speaker too, so you can recall one person's words only.
mem.add_speaker("Bob", user_id="alice") # once per person
mem.add("I promised to send the report on Friday", user_id="alice", speaker="me")
mem.add("Bob said the deadline moved to Tuesday", user_id="alice", speaker="Bob")
mem.search("what did Bob say about deadlines?", user_id="alice", speaker="Bob")
Memories arrive best-first, and the assistant's own words and image memories, when there
are any, follow them in their own order. Take the list in the order given. similarity on each
memory is a raw closeness score, not the ranking key: what produces the order is
internal and is not returned, so sorting by it makes results worse. There is no
score field.
A store registers up to 50 people to start (a limit we plan to raise);
"me" never needs registration and never counts against it.
Async
Same surface, awaitable — needs the extra:
pip install "wontopos[async]"
import asyncio
from wontopos import AsyncClient
async def main():
async with AsyncClient(api_key="wos-live-...", user_id="alice") as mem:
await mem.add("she prefers tea over coffee")
hits = await mem.search("what does alice drink?")
asyncio.run(main())
Every Client method but close exists on AsyncClient with identical arguments
and semantics (retries, redirect refusal, guards). Close it with async with or
await mem.aclose().
Photos
On a model whose list_models() capabilities include images, a memory can carry a photo.
The caption is still required.
import base64
with open("beach.jpg", "rb") as f:
data = base64.b64encode(f.read()).decode()
stored = mem.add("At the beach with Bob", user_id="alice",
image={"data": data, "taken_at": "2026-08-14"})
image, content_type = mem.get_image("alice", stored["id"])
with open(f"beach.{content_type.split('/')[1]}", "wb") as f:
f.write(image)
Both edges must be 700px or more, the long edge at most 2500px and the file at most 7MB;
anything else is refused (400) with the reason. A long edge over 1568px is stored at
1568px, so keep your own copy of the original. search returns image memories after
the others, and list_images pages through them newest first. forget_image removes the
photo, and it can remove the whole memory with it: call it with preview=True first, and
memory_kept says whether the memory stays.
Export, edit history and usage
- Export:
export_memories(user_id)returns every memory in a store, the text you stored and its metadata;export_images(user_id)every image memory. For a large store,iter_memoriesanditer_imagesstream them a page at a time. - Edit history:
updatereplaces a fact that changed.lineage(user_id, memory_id)lists the versions from the id you pass forward, oldest first, and marks the one in force withis_current; pass the first version's id to see the whole history.revisions()counts how many of a store's memories were edited. - Usage:
usage(days)reports this key's spend, the workspace's spend over the window, the stores that spent the most, and the balance. It is free, and works at a zero balance. Where only an admin key sees the stores,storesis empty andstores_admin_onlyis true.
Recall caching
Opt in per search and a repeated query reuses the previous result at 10% of the normal rate; an extended one reuses part of it (Tablet and Scroll models).
It is not free to turn on: the FIRST call writes the cache and bills the query
tokens at 2x for a 5m TTL, 3x for 1h. The same query again inside the TTL bills
its query and its results at 0.1x. A query that extends the cached one (its text plus
more) bills the cached part at 0.1x, the new part at the write rate and its results
at the normal rate. A store keeps one cached query per model and set of options, so a
different query replaces it. So it pays for a query you repeat or extend, and costs
more for one you issue once — do not switch it on globally. Any write to the store invalidates its cache
at once, so a hit can never predate a new memory.
hits = mem.search("...the conversation so far...", user_id="alice",
cache_control={"ttl": "5m"}) # or "1h"
Reliability
Built in, no configuration needed:
- Automatic retries — 429 and a 409 for a write already in flight always, and 408 /
502 / 503 / 504 or a connection error only when a retry cannot double-process a write.
The calls that are safe to send again retry all four: the reads sent as POST (
search,recall,get,list_memories,stats, ...), the GET and DELETE calls (ping,list_stores,list_speakers,list_models,list_engrams,usage,delete_store,remove_speaker,forget_image), and the memory writes (add,add_turn,add_bulk,update) and the sleep's writes (sleep_done,write_sleep_files,write_sleep_notes). Those carry an idempotency key, so the service answers a repeat with the first attempt's result instead of storing again. The other writes sent as POST (create_store,add_speaker,delete,delete_all) get 429, that 409 and connect-level failures only. Twice, with exponential backoff + jitter, honoring the server'sRetry-Afterup to 30s. Tune withClient(retries=...);retries=0disables. - Your own retries — pass
idempotency_key=when the retry is yours (a job that is re-run, a queue that redelivers). The service keeps a key for 24 hours and answers a repeat with the first response, marked"replayed": True. When the first attempt did not come back with an answer, so whether it was applied is not known, a repeat is refused with aConflictError(409) rather than stored twice: check before sending it again under a new key. Derive the key from what you store (f"import:{row.id}"), never a constant. - Redirects refused — the API key never follows a 3xx to another host.
- Timeouts — 30s per attempt by default, and 200s for
add,add_turnandadd_bulk: storing a long text can take the service up to three minutes. AClient(timeout=...)you set applies to every call. A total budget for the whole call across every retry isClient(deadline=...)/with_deadline(secs). At the defaults one call can hold for three attempts and the backoff between them, which a request handler with five seconds cannot use. - Key never in logs —
repr(client)masks the API key. - Wipe guard —
delete()without amemory_idraises instead of silently meaning "delete everything"; wiping a store is only ever the explicitdelete_all(user_id)/delete_store(user_id).
Security
Built in, none of it configurable off:
- TLS 1.2 floor and certificate verification that cannot be disabled.
- Redirects refused — a 3xx is an error, so the key never follows one to another host.
- Response size cap — anything over 64MB is refused instead of buffered.
- Key hygiene — keys are trimmed (a stray newline from a file otherwise becomes a mystery 401) and inner whitespace is rejected; model names are validated before they reach a header.
Client.from_env()readsWONTOPOS_API_KEY(orWOS_API_KEY) — keep keys out of source code.- Plain-HTTP base URLs on non-local hosts warn. Three dependencies:
requests(floor>=2.32.4),urllib3(floor>=1.26.20) andtzdata.
Errors
Any non-2xx response raises WosError(status, message). When the server sent a
request id it's on e.request_id — include it when contacting support.
from wontopos import Client, WosError
try:
mem.search("...", user_id="alice")
except WosError as e:
if e.status == 401:
print("API key invalid or revoked")
elif e.status == 429:
print("Rate limited — back off") # already retried twice by then
else:
print(e.status, e.message, e.request_id)
A retired model answers 410, raised as GoneError: retrying cannot succeed, so name
a live model (list_models() lists them, with retires_at on one that is scheduled to
retire). Before the day, the client logs a warning once with the date the model you use
retires. delete_store still works under a retired model. A 410 whose code is
sleep_expired is a sleep plan too old to finish, not a retired model: it is raised as
WosError, not GoneError, with the service's own message. Read again and run the
sleep anew.
A different API host
Point the client somewhere other than the default endpoint - a dedicated region, a proxy of your own, or a local test server:
mem = Client(api_key="...", base_url="https://api.example.com")
Links
- Homepage: https://wontopos.com
- API reference: https://wontopos.com/en/why (Developers tab)
Reporting a bug
Found something wrong, or something that looks unsafe? Tell us — every report gets read.
- Bugs: https://wontopos.com/contact?topic=bug
- Security: https://wontopos.com/contact?topic=security (also published at
/.well-known/security.txt)
Include the SDK version (wontopos.__version__) and the language. If it involves a store id or a
memory, describe the shape rather than pasting the contents — we do not need your
data to fix it.
Changelog
The three clients release in lockstep — same version, same surface, same day. Patch releases are additive. Sixteen inside 2.2 were not, deliberately and each with its reason; the changelog lists them.
See CHANGELOG.md.
Metadata
Release files for wontopos 2.2.53
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| wontopos-2.2.53.tar.gz | 121.8 kB | Without provenance | Details for wontopos-2.2.53.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wontopos-2.2.53-py3-none-any.whl | Python 3 | none | any | Details for wontopos-2.2.53-py3-none-any.whl |
Total release size: 240.7 kB
Release files / wontopos-2.2.53.tar.gz
| Download URL | wontopos-2.2.53.tar.gz |
|---|---|
| Size | 121.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a43c5b89ff0ad35f77feefa54514e89ecc2e99540efc122b7e8323f0720a4c55
|
|
BLAKE2b-256 checksum How to use checksums |
1c3c05bc14ced3d48e06f28b911e8af909e54ea07d6bd8970c1ef4777aca6409
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.18
|
Release files / wontopos-2.2.53-py3-none-any.whl
| Download URL | wontopos-2.2.53-py3-none-any.whl |
|---|---|
| Size | 118.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
da813b46635cbafdb74a3e6123528f1833c2c5e75ff69e087d7a9dac67787991
|
|
BLAKE2b-256 checksum How to use checksums |
9b5ce7ac6106b425896af1866c745fd8925cdff5ce589f1520a67dd9cdc4de36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.18
|
Security for wontopos 2.2.53
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.