Skip to main content

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).
  • No LLM reads your memories — no language model reads your stored memories, on any model. You pay retrieval, not generation.
  • Bounded retrieval — recall() returns the recent turns, at most limit long-term memories (default 10, up to 20) and at most context_limit rows of the surrounding conversation (default 10, up to 20), however much you've stored. Your LLM bill stops growing with history.

Methods

Method Purpose
add(content, user_id, **metadata) Store one memory
add_turn(user_msg, assistant_msg, user_id?) Store a conversation exchange
add_bulk(content, user_id, category=, timestamp=) Backfill a long history
update(old_memory_id, new_content, user_id?) Supersede an old fact
search(query, user_id, limit=10, **opts) Search stored memories
search_full(query, user_id, limit=10, **opts) The same search with every field kept — images and verify_used included
recall(query, user_id) One-call context (short + long + surrounding)
history(user_id) Recent turns (short-term)
stats(user_id) Counts
get(user_id, memory_id) Fetch one memory by id (the text you stored, and its metadata)
list_memories(user_id, limit=100, cursor=) Browse/export a store's raw memories, paged
delete(user_id, memory_id) Delete one memory
delete_all(user_id) GDPR erase (delete every memory for the user)
add_speaker(speaker, user_id?) Register a person (explicit, up to 50 to start)
list_speakers(user_id?) Registered people + per-person memory counts
remove_speaker(speaker, user_id?) Unregister; memories stay. The tag goes, except on tablet-2, which keeps it on memories already stored

All methods take 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.

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().

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. A write may already have landed when any of those four comes back, so a POST write gets 429, that 409 and connect-level failures only. The calls that are safe to send again retry all four: the reads sent as POST (search, recall, get, list_memories, stats, ...) and the GET and DELETE calls (ping, list_stores, list_speakers, list_models, list_engrams, usage, delete_store, remove_speaker, forget_image). Twice, with exponential backoff + jitter, honoring the server's Retry-After up to 30s. Tune with Client(retries=...); retries=0 disables.
  • Redirects refused — the API key never follows a 3xx to another host.
  • Timeouts — 30s per attempt by default (Client(timeout=...)), and a total budget for the whole call across every retry with Client(deadline=...) / with_deadline(secs). At the defaults one call can hold for 30s + backoff + 30s
    • backoff + 30s, which a request handler with five seconds cannot use.
  • Key never in logs — repr(client) masks the API key.
  • Wipe guard — delete() without a memory_id raises instead of silently meaning "delete everything"; wiping a store is only ever the explicit delete_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() reads WONTOPOS_API_KEY (or WOS_API_KEY) — keep keys out of source code.
  • Plain-HTTP base URLs on non-local hosts warn. One dependency (requests, floor >=2.32.4).

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). delete_store still works under a retired model.

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")

Reporting a bug

Found something wrong, or something that looks unsafe? Tell us — every report gets read.

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. Nine 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.46

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wontopos 2.2.46
File Size Uploaded Provenance Actions
wontopos-2.2.46.tar.gz 105.8 kB Without provenance Details for wontopos-2.2.46.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wontopos 2.2.46
File Interpreter ABI Platform Actions
wontopos-2.2.46-py3-none-any.whl Python 3 none any Details for wontopos-2.2.46-py3-none-any.whl

Total release size: 166.4 kB

Release files / wontopos-2.2.46.tar.gz

Download URL wontopos-2.2.46.tar.gz
Size 105.8 kB
Tags Source
SHA-256 checksum
How to use checksums
44b1453428812a9fa2c03b2a9d2634c6aba53e6d7f6ff8ec0709b5f6217b934c
BLAKE2b-256 checksum
How to use checksums
3eee9b50fd2543d4656d9cfa94af6644082b4bbf7f1f409d3467647068108572
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.46-py3-none-any.whl

Download URL wontopos-2.2.46-py3-none-any.whl
Size 60.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7e38977a72d5b38e6577cb33d9b7bb4e38628278be7e2965988653419ced1661
BLAKE2b-256 checksum
How to use checksums
78299d2bef5e23c81d69d479a6f556f266f692eaa617ca0f44c8f52e63ed2772
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.46

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.

Release history Release notifications | RSS feed

This release

2.2.46 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page