Wontopos — long-term memory for AI agents

pip install wontopos

from wontopos import Client

mem = Client(api_key="wos-...")

# 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

• Pure semantic retrieval — no keyword/BM25. Identical recall in every language (한국어 · 日本語 · 中文 · English).
• No LLM in the loop — store / search / recall never call a language model. You pay embeddings, not generation.
• Bounded retrieval — recall() returns a small, fixed-size slice (~1,200 tokens) regardless of how much you've stored. Your LLM bill stops growing with history.

Methods

All methods take a user_id — it names the store: one isolated memory space per end-user, agent, or topic, then per account (your API key). 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")

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

from wontopos import AsyncClient

async with AsyncClient(api_key="wos-...", user_id="alice") as mem:
    await mem.add("she prefers tea over coffee")
    hits = await mem.search("what does alice drink?")

Every Client method exists on AsyncClient with identical arguments and semantics (retries, redirect refusal, guards). Close with async with or await mem.aclose().

Recall caching

Opt in per search and repeated or extended queries reuse the previous result at 10% of the normal rate (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. Only hits inside the TTL bill at 0.1x. 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 / 502 / 503 and connection errors retry twice with exponential backoff + jitter, honoring the server's Retry-After. 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=...)).
• 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 for its certificate-verification fix).

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)

Self-host

Point at your own engine:

mem = Client(api_key="...", base_url="https://wos.your-host.com")

Links

• Homepage: https://wontopos.com
• API reference: https://wontopos.com/en/why (Developers tab)

Changelog

The three clients release in lockstep — same version, same surface, same day. Patch releases are additive: nothing is removed or reordered within a minor line.

• 2.2.30 — documentation only: this changelog, which had not been updated in the shipped package since 2.2.10.
• 2.2.29 — a store id that was PASSED but unusable no longer becomes the default store. 2.2.28 caught a blank string; the value a failed tenant lookup actually produces in Python is an integer primary key. user_id=0 is falsy and fell through to the client default, and any other integer died inside the warn helper as 'int' object has no attribute 'lower'. Anything but a non-blank string now raises, on the destructive calls too. Omitting the argument still means "use the default". Also: delete_store now warns when a store id folds (delete_all already did, and it is the call that removes a whole store), and an idempotency_key ending in a newline is refused here instead of failing inside http.client as Invalid header value.
• 2.2.28 — audit: warn caches made thread-safe, a whitespace memory_id can no longer read as a whole-store delete, a blank store id raises instead of silently using the default, and a gzip bomb no longer bypasses the response cap on the async client.
• 2.2.11–2.2.27 — additive fixes and hardening across all three clients.
• 2.2.10 — Memory fix: the relevance field is similarity (not score); added typed importance, category, is_superseded, superseded_by, created_at, event_date.
• 2.2.4–2.2.9 — one version across Python, TypeScript and Rust, released in lockstep; retries, redirect refusal, response cap, key masking, speakers.

License: MIT.