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

• 2.2.10 — docs: the memory relevance field is similarity (not score); responses are plain dicts, so no code change — version bumped for lockstep with the TS/Rust Memory type fix.
• 2.2.9 — AsyncClient (same surface, pip install "wontopos[async]"); security round 2: TLS 1.2 floor, 64MB response cap, key/model-name hygiene, Client.from_env(), requests>=2.32 floor.
• 2.2.8 — reliability + hardening: automatic retries (429/502/503 + connection errors, backoff + jitter, honors Retry-After), redirects refused, key masked in repr, WosError.request_id, guard against delete() without memory_id, plain-HTTP warning, User-Agent, with_model().
• 2.2.7 — speakers: add_speaker / list_speakers / remove_speaker.
• 2.2.6 — docs: user_id = store, clarified everywhere.
• 2.2.5 — docs: speakers + recall caching sections.
• 2.2.4 — Python/TypeScript/Rust converge on one version; all three now release in lockstep (same version, same surface). Patch releases are additive.

License: MIT.