Drei Modelle, eine Linie.

WOS-Modelle sind danach benannt, wie Menschen im Lauf der Geschichte Wissen bewahrt haben - Tablet, Scroll, Book. Steintafel, Schriftrolle, gebundenes Buch: Jedes leistet mehr für Ihren Agenten als das vorherige.

Der vollständige Benchmark-Bericht zu Tablet 1 steht auf der Benchmark-Seite.

Zahlen Sie uns $2. Sparen Sie ein Vielfaches davon bei Ihrem LLM.

WOS führt Ihrem LLM ~1.200 Tokens pro Abfrage zu - einen begrenzten, relevanten Ausschnitt - statt die gesamte Historie in jeden Prompt zu stopfen. Der Abstand ist enorm und wächst mit Ihrer Historie.

Woher die Einsparungen kommen

• Ohne WOS packen Sie die gesamte Historie in jeden Prompt - 100K tokens × $2.50/1M = $0.25 pro Abfrage, zu GPT-4o-Eingabepreisen (bei Modellen der Opus-Klasse etwa das Doppelte).
• Mit WOS nehmen Sie die Daten einmal auf ($2/1M); danach ist jede Abfrage ein winziger Abruf ($3/1M × 1,200) plus Ihr LLM auf nur ~1.200 Tokens.
• Je weniger Tokens Ihr LLM liest, desto weniger zahlen Sie - und WOS hält diese Zahl konstant, während das Gedächtnis wächst.

Jede Sprache, dieselbe Genauigkeit.

Der Abruf ist rein semantisch - ausschließlich Embeddings, null Keyword- oder BM25-Matching. Die Recall-Qualität ist daher identisch, ob Ihre Nutzer auf 日本語, 中文, Español oder Englisch schreiben.

Lexikalisches Matching wie BM25 ist auf die Gestalt einer bestimmten Sprache abgestimmt - Morphologie, Leerzeichen, Schriftsystem. In einem mehrsprachigen Store heißt das: Die Abrufqualität variiert je nach Sprache. WOS verwendet überhaupt kein lexikalisches Matching, sodass jede Sprache denselben Weg nimmt.

Ein Store, drei Sprachen zugleich

Sie wählen keine Sprache pro Store - mischen Sie frei. Unten enthält das Gedächtnis eines Nutzers gleichzeitig Japanisch, Englisch und Spanisch, und jede Frage findet die richtige Erinnerung, unabhängig von der Sprache. Dies ist ein echter Austausch mit der Live-API:

# one user, three languages stored together
mem.add("彼女はコーヒーより紅茶が好き", user_id="alice")                      # Japanese
mem.add("she works at a design studio in Brooklyn", user_id="alice")       # English
mem.add("A ella le encanta hacer senderismo los sábados", user_id="alice")  # Spanish

"¿Qué bebe ella?"               -> 彼女はコーヒーより紅茶が好き
"what does she do on weekends?" -> A ella le encanta hacer senderismo los sábados
"彼女の仕事は?"                  -> she works at a design studio in Brooklyn

Kein Übersetzungsschritt, keine Spracherkennung, keine Konfiguration pro Sprache. Erinnerungen und Fragen werden nach Bedeutung eingeordnet, nicht nach Sprache - passt die Bedeutung, spielt die Sprache keine Rolle.

Warum wir Keywords bewusst verbannt haben

Lexikalisches Scoring wie BM25 stärkt den Abruf für manche Sprachen mehr als für andere - hinderlich, wenn ein Store viele Sprachen enthält. Wir haben es daher vollständig aus der Engine entfernt und setzen diese Regel im Code-Review durch: Mit jeglichem lexikalischem Scoring im Pfad würde die Recall-Qualität je nach Sprache abweichen.

Kein Modell läuft über Ihre Erinnerungen.

Die Speicherung erfolgt wortgetreu, und die Engine sucht über Embeddings - günstig, schnell und deterministisch. Über Ihre gespeicherten Erinnerungen läuft niemals ein Modell. Tablet verwendet gar kein Modell; Scroll und Book setzen für stärkere Ergebnisse eines um die Engine herum ein, doch es sieht immer nur Ihre Abfrage, nie das, was Sie gespeichert haben.

• Deterministische Engine. Die Engine liefert für dieselbe Abfrage jedes Mal dieselben Erinnerungen - deshalb stammt die Varianz in unserem Benchmark allein vom Reader-Modell.
• Günstig im großen Maßstab. Keine Generierungskosten beim Speichern oder Abrufen - Ihre Rechnung folgt dem Speicherplatz, nicht der Modellnutzung, während das Gedächtnis wächst.

Ihre Worte, unangetastet

Ein verbreitetes Design lässt beim Schreiben ein Sprachmodell laufen, um "Fakten" aus dem Text zu extrahieren und umzuschreiben. Dieses Design bezahlt dreifach: Generierungskosten bei jedem Schreibvorgang, zusätzliche Latenz und die Speicherung der Paraphrase eines Modells statt der ursprünglichen Worte. WOS trifft die entgegengesetzte Wahl - es speichert das Gesagte unverändert und lässt Ihr LLM die Interpretation zur Lesezeit übernehmen, mit dem Originaltext in der Hand.

67,5 %, gemessen und reproduzierbar.

67,5 % auf BEAM 1M, gemittelt über 5 unabhängige Läufe (σ 0,22 %, keiner handverlesen), bewertet von gpt-4.1-mini mit dem Judging-Prompt des Benchmarks selbst.

Auf demselben Benchmark schwanken die Ergebnisse stark mit dem Bewertungsprotokoll - dem Judge, dem Prompt und dem, was die Abrufschicht tun darf. Wir bewerten mit dem Judge, den das Repository der Autoren selbst mitliefert, verwenden ihren Judging-Prompt wie geschrieben, passen nichts an den Test an und veröffentlichen Harness, Bewertungscode und Reader-Prompt, sodass jeder die 67,5 % exakt reproduzieren kann.

Das Protokoll in einer Tabelle

Was es ehrlich hält: ein Judge von dritter Seite, der unverändert veröffentlichte Reader-Prompt, rein semantischer Abruf und die Veröffentlichung jedes Laufs - nicht nur des besten. Die Abruf-Engine ist deterministisch - führen Sie sie erneut aus, erhalten Sie dieselben Erinnerungen.

Wir erklimmen härtere Benchmarks

Wir testen auf dem härtesten Standard-Benchmark, den wir noch nicht bezwungen haben - und die Zahl ist die Bestmarke über alle WOS-Modelle hinweg, neu geschrieben, sobald ein besseres erscheint. Überschreiten wir klar 94%, steigen wir zu einem härteren Benchmark auf.

Zwei Token-Preise pro Modell,
plus $0.0001 pro Anfrage.

Pro Million Tokens plus pauschal $0.0001 pro Anfrage, Bezahlung nach Verbrauch. Kein Abonnement, keine Speichermiete, keine Gedächtnisgrenzen. Sie zahlen, wenn Ihr Agent schreibt oder liest - nie für das, was er sich merkt.

• $0.0001 pro Anfrage. Eine Pauschalgebühr auf jeden API-Aufruf, zusätzlich zur Token-Nutzung.
• Speicherung ist kostenlos. Die Aufnahme wird einmal bezahlt; das Aufbewahren kostet Sie nichts. Kein Mengenlimit, keine Aufbewahrungsgrenze.
• Wir speichern es. Wir trainieren nie darauf, verwenden es nicht und sehen es nicht ein. Das Gedächtnis Ihres Agenten gehört Ihnen - wir organisieren es nur, damit Sie es abrufen können.
• Warum Tablet so günstig ist: Seine Engine führt kein Modell aus, unsere Kosten sind also Embeddings und Festplatten - keine GPUs. Scroll und Book ergänzen ein Modell, und genau das deckt ihr höherer Preis ab.

Rate-Limits nach Nutzungsstufe →

Drei Aufrufe: Speichern, Abrufen, Antworten.

Eine API. Der Aufruf recall() liefert Kurzzeit-, Langzeit- und Umgebungskontext in einem einzigen Roundtrip - bereit zum Einfügen in Ihren Prompt.

from wontopos import Client
mem = Client(api_key="wos-...")
mem.add("she prefers tea over coffee", user_id="alice")
mem.add("I suggested the jasmine tea", user_id="alice", speaker="me")  # its own words
# one call: short + long + context
ctx = mem.recall("what does alice drink?", user_id="alice")

Erinnerungen tragen einen Sprecher. Standard sind die Worte deines Nutzers, speaker "me" speichert, was der Assistent selbst gesagt hat, und ein Name wie "Bob" merkt sich, wer es gesagt hat — Erinnern nach Person.

Ihr erster Recall in 5 Minuten.

Ein Schlüssel, eine Installationszeile, drei Aufrufe - und Ihr Agent hat ein Gedächtnis. Jedes Snippet auf dieser Seite wurde tatsächlich ausgeführt; die Antworten sind wortwörtlich wiedergegeben.

pip install wontopos        # Python
npm install wontopos        # TypeScript / JavaScript
cargo add wontopos          # Rust
# curl - nothing to install, just set WOS_API_KEY
# latest: SDK v2.2.32 · MCP v1.0.15

from wontopos import Client

mem = Client(api_key="wos-live-...", user_id="alice")  # set the store once
mem.create_store()              # create it (stores are explicit)
mem.add("she prefers tea over coffee")  # no user_id needed

# one call → short-term + long-term + context
ctx = mem.recall("what does alice drink?")

import { Client } from "wontopos";

const mem = new Client({ apiKey: "wos-live-...", userId: "alice" });  // set the store once
await mem.createStore();            // create it (stores are explicit)
await mem.add("she prefers tea over coffee");  // no userId needed

// one call → short-term + long-term + context
const ctx = await mem.recall("what does alice drink?");

use wontopos::Client;

let mem = Client::new("wos-live-...").with_user("alice");  // set the store once
mem.create_store(None).await?;            // create it (stores are explicit)
mem.add("she prefers tea over coffee", None, json!({})).await?;

// one call → short-term + long-term + context
let ctx = mem.recall("what does alice drink?", None).await?;

# create the store once - stores are explicit
curl -X POST https://api.wontopos.com/api/v1/memory/collection \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice"}'

# store - embedded on the way in, no LLM call
curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"she prefers tea over coffee"}'

# one call → short-term + long-term + context
curl -X POST https://api.wontopos.com/api/v1/memory/recall \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what does alice drink?"}'

{"user_id": "alice", "status": "created"}

{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}

recall() liefert vier Blöcke - short_term (jüngste Gesprächszüge), long_term (relevante Erinnerungen), context (das Umfeld des besten Treffers) und eine instruction, die dem LLM sagt, wie es sie verwenden soll. Fügen Sie das Ganze in Ihren Prompt ein.

Jede Methode, pro Sprache →

Ein Client, andere Einstellungen

mem = Client.from_env()                 # reads WONTOPOS_API_KEY
scroll = mem.with_model("scroll-1.2")  # this copy only: another engine
alice  = mem.with_user("alice")       # this copy only: another default store

const alice = mem.withUser("alice");
const scroll = mem.withModel("scroll-1.2");

let alice = mem.with_user("alice");
let scroll = mem.with_model("scroll-1.2");

# curl has no copies — send model and user_id with each request
curl ... -d '{"user_id":"alice","model":"scroll-1.2","query":"…"}'

Stores - anlegen, auflisten, löschen.

Ein Store ist die user_id, unter der Sie lesen und schreiben - ein isolierter Gedächtnisraum pro Endnutzer, Agent oder Thema. Stores sind explizit: Legen Sie einen an, bevor Sie hineinspeichern oder daraus abrufen, sonst liefert der Aufruf 404. Jedes Konto startet mit einem default-Store, Sie können also ohne Create-Aufruf beginnen.

mem.create_store("alice")        # create (idempotent)
mem.list_stores()              # [{"user_id","created_at"}, ...]
mem.delete_store("alice")        # delete the store + all its memories

await mem.createStore("alice");
await mem.listStores();          // [{ user_id, created_at }, ...]
await mem.deleteStore("alice");     // store + all its memories

mem.create_store("alice").await?;
let stores = mem.list_stores().await?;
mem.delete_store("alice").await?;

# create
curl -X POST https://api.wontopos.com/api/v1/memory/collection \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" -d '{"user_id":"alice"}'
# list
curl https://api.wontopos.com/api/v1/memory/collections -H "X-API-Key: $WOS_API_KEY"
# delete (store + all its memories)
curl -X DELETE https://api.wontopos.com/api/v1/memory/collection \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" -d '{"user_id":"alice"}'

{ "user_id": "alice", "status": "created" }   // "exists" if it already did

{ "collections": [
  { "user_id": "default", "created_at": "2026-06-26T02:23:14Z" },
  { "user_id": "alice",   "created_at": "2026-06-26T02:24:01Z" }
], "count": 2 }

{ "error": { "type": "not_found_error",
  "message": "Store 'ghost' does not exist. Create it first with
              POST /api/v1/memory/collection {\"user_id\":\"ghost\"}, then store or recall." } }

Stores auflisten und löschen

mem.list_stores()                # [{"user_id","created_at"}, …]
mem.delete_store("alice")      # the store and every memory in it

await mem.listStores();
await mem.deleteStore("alice");

let stores = mem.list_stores().await?;
mem.delete_store("alice").await?;

curl -X POST   .../api/v1/memory/collections -d '{}'
curl -X DELETE .../api/v1/memory/collection  -d '{"user_id":"alice"}'

Wiederholte Abrufe, zum Zehntel des Preises.

Aktiviere es pro Anfrage, und WOS cached das Suchergebnis unter dem Abfragetext, mit denselben Präfixregeln wie beim Prompt Caching von LLMs. Solange der Cache warm ist, nutzt eine wiederholte oder erweiterte Abfrage das vorherige Ergebnis wieder, und der gecachte Teil wird mit 10% des normalen Token-Preises berechnet.

Ein Gespräch, drei Runden

So sieht es wirklich aus, wenn ein Agent immer weiter mit seinem Gedächtnis spricht. Jede Runde schickt das bisherige Gespräch als Abfrage, mit aktiviertem cache_control.

Die Preise

Was es spart

Ein konkretes Beispiel: Dein Agent schickt ein Gespräch mit 3.000 Tokens als Abfrage und wiederholt oder verlängert es 10-mal innerhalb von fünf Minuten. Ohne Caching sind das 30.000 Eingabe-Tokens zum vollen Preis. Mit einem 5-Minuten-Cache sind es 6.000 für das erste Schreiben (2x) plus rund 2.700 für die neun Cache-Lesevorgänge: 8.700 abgerechnete Tokens, 71% weniger. Je länger das Gespräch läuft, desto größer die Ersparnis.

Die Präfixregel

Der Abgleich erfolgt am Anfang der Abfrage. Bleibt der Anfang identisch und wird nur neuer Text angehängt, wird der gecachte Teil wiederverwendet und nur der neue Teil gesucht. Ändert sich etwas vor dem Ende des gecachten Textes, kann nichts wiederverwendet werden.

cached    [ A B C D E F G ]

○   [ A B C D E F G ] E
✗   [ B C D E F G ] E

○ Treffer - der Anfang ist unverändert, nur E ist neu
✗ Fehltreffer - der Anfang hat sich geändert, die gesamte Abfrage wird neu gesucht und neu gecacht

Drei Regeln zum Merken

• Erweitern cached bis zum neuen Ende neu. Nach [A B C D E F G] + E endet der Cache jetzt bei E: Das Ende wird einmal zum Schreibtarif berechnet, und die nächste Runde kann wieder ganz A..E als Präfix abgleichen.
• Ein zusammenhängendes Präfix pro Anfrage. Eine Abfrage kann nicht in zwei Cache-Segmente geteilt werden; nur ihr Anfang kann übereinstimmen.
• Schreibvorgänge invalidieren sofort. Jedes store, store-turn, bulk-store, forget, supersede oder Löschen des Stores verwirft dessen Cache. Eine gecachte Antwort kann nie veraltet sein.

So wird es aktiviert

hits = mem.search(
    "...the conversation so far...", user_id="alice",
    cache_control={"ttl": "5m"},   # or "1h"
)

const hits = await mem.search(
  "...the conversation so far...", "alice", 10,
  { cache_control: { ttl: "5m" } },   // or "1h"
);

let hits = mem.search_with(
    "...the conversation so far...", "alice", 10,
    serde_json::json!({"cache_control": {"ttl": "5m"}}),   // or "1h"
).await?;

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice",
       "query":"...the conversation so far...",
       "cache_control":{"ttl":"5m"}}'   # or "1h"

{ "memories": [ ... ],
  "cache": { "status": "hit",              // "write" | "hit" | "extend"
             "ttl": "5m",
             "cache_read_input_tokens": 412,
             "cache_creation_input_tokens": 0 } }

Für all das brauchst du kein SDK. Caching ist ein Feld in einem HTTP-Aufruf und funktioniert daher aus jeder Programmiersprache. Der curl-Tab ist das universelle Rezept, und die Python-, TypeScript- und Rust-SDKs sind bequeme Hüllen um genau denselben Aufruf.

Gedächtnis, das weiß, wer es gesagt hat.

Menschen erinnern sich nach Person: was Bob versprochen hat, was du zugesagt hast. Gib jeder Erinnerung einen Sprecher und dein Agent tut dasselbe, auf jedem Tablet- und Scroll-Modell.

Ein Team, drei Erinnerungen

Ein Store hält viele Stimmen auseinander. Registriere eine Person einmal, speichere jede Äußerung unter ihrem Sprecher und frage später nach Person.

Drei Regeln zum Merken

• "me" ist der Assistent selbst. Nie registriert, nie gezählt. Reserviert und kleingeschrieben: speaker: "Me" oder "ME" liefert 400 invalid_request_error statt stiller Umdeutung.
• Das Limit zählt bei der Registrierung: zunächst 50 pro Store. Darüber hinaus liefert die Registrierung 400 invalid_request_error mit speaker_limit: 50 im Fehlerbody. Speichern mit unregistriertem Namen liefert ebenfalls 400 und speichert nichts. Suche mit unregistriertem Namen im Filter liefert 404 not_found_error. Verzweige auf Status und Felder, nicht auf den Meldungstext; wir planen, das Limit anzuheben.
• Labels leben in jeder Leseoperation. Suchergebnisse, der Langzeit-Kontext von recall und Engram-Ergebnisse tragen ihren Sprecher — das Modell weiß immer, wessen Worte es hält. Mit speaker in der Suche kommen nur die Worte einer Person zurück. Ein supersede behält den Sprecher; forget entfernt ihn.
• Namen sind Unicode: jede Sprache funktioniert. さくら, Иван und 하늘 sind gültige Sprecher, und die Zuordnung verhält sich in jeder Sprache identisch. Der Abgleich ist exakt nach Trim und Unicode-Normalisierung, also sind Bob und bob zwei Personen. Namen sind bis 80 Zeichen lang.

# POST /speakers past the limit
{ "type": "error",
  "error": { "type": "invalid_request_error",
             "message": "This store already has 50 registered speakers, ...",
             "speaker_limit": 50 } }

# store with an unregistered name → 400, nothing stored
{ "type": "error",
  "error": { "type": "invalid_request_error",
             "message": "speaker 'Bob' is not registered in this store. Register it first: ...",
             "speaker": "Bob" } }

# search filtered by an unregistered name → 404
{ "type": "error",
  "error": { "type": "not_found_error",
             "message": "speaker 'Bob' is not registered in this store.",
             "speaker": "Bob" } }

Zwei Randnotizen. speaker gehört zu add / store: add_turn merkt sich den ganzen Austausch, Personen-Labels und der Filter kommen aus Erinnerungen mit explizitem speaker. Und Sitzungspassagen (expand) sind Komposite mehrerer Erinnerungen, tragen also kein Label; ein speaker-Filter liefert immer atomare, gelabelte Erinnerungen. Und ein Schreibvorgang, dessen Bedeutung einer gespeicherten Erinnerung nahe genug kommt, wird verworfen - entscheidend ist die Bedeutung, nicht der Wortlaut: ein solcher store liefert status "duplicate" mit expliziter note, speichert nichts und hängt keinen Sprecher an. Auch eine wirklich neue Tatsache, die sich nur in einem Detail von einer vorhandenen unterscheidet ("Schalentierallergie" nach "Erdnussallergie"), fällt unter dieselbe Regel - lesen Sie also status, statt anzunehmen, der Schreibvorgang sei angekommen.

Wir testen das auf die harte Tour: Erinnerungen ohne Namen im Text, abgerufen pro Person. Die Zuordnung kommt aus dem Sprecher-Register, nicht aus Wortabgleich, und verhält sich daher in jeder Sprache gleich.

So nutzt du es

mem.add_speaker("Bob", user_id="alice")  # once per person; "me" needs no registration
mem.add("Bob said the deadline moved to Tuesday", user_id="alice", speaker="Bob")
mem.add("I promised the summary by Friday", user_id="alice", speaker="me")
hits = mem.search("what did Bob say about the deadline?", user_id="alice", speaker="Bob")
mem.list_speakers(user_id="alice")
mem.remove_speaker("Bob", user_id="alice")  # memories stay, the tag goes

await mem.addSpeaker("Bob", "alice");  // once per person; "me" needs no registration
await mem.add("Bob said the deadline moved to Tuesday", "alice", { speaker: "Bob" });
await mem.add("I promised the summary by Friday", "alice", { speaker: "me" });
const hits = await mem.search("what did Bob say about the deadline?", "alice", 10, { speaker: "Bob" });
await mem.listSpeakers("alice");
await mem.removeSpeaker("Bob", "alice");  // memories stay, the tag goes

mem.add_speaker("Bob", "alice").await?;  // once per person; "me" needs no registration
mem.add("Bob said the deadline moved to Tuesday", "alice", json!({"speaker": "Bob"})).await?;
mem.add("I promised the summary by Friday", "alice", json!({"speaker": "me"})).await?;
let hits = mem.search_with("what did Bob say about the deadline?", "alice", 10, json!({"speaker": "Bob"})).await?;
mem.list_speakers("alice").await?;
mem.remove_speaker("Bob", "alice").await?;  // memories stay, the tag goes

curl -X POST https://api.wontopos.com/api/v1/memory/speakers \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","speaker":"Bob"}'   # once per person

curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"Bob said the deadline moved to Tuesday","metadata":{"speaker":"Bob"}}'

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what did Bob say about the deadline?","speaker":"Bob"}'

curl "https://api.wontopos.com/api/v1/memory/speakers?user_id=alice" -H "X-API-Key: $WOS_API_KEY"

curl -X DELETE https://api.wontopos.com/api/v1/memory/speakers \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","speaker":"Bob"}'   # memories stay, the tag goes

{ "memories": [
    { "content": "Bob said the deadline moved to Tuesday",
      "speaker": "Bob", ... } ] }

{ "user_id": "alice",
  "speakers": [ { "speaker": "Bob", "memories": 2, "created_at": "2026-07-10T04:20:39Z" } ],
  "count": 1, "limit": 50 }

Die Liste zeigt, wen der Store kennt, mit Erinnerungszahl pro Person gegen das Limit. Entfernen löscht nur die Registrierung: die Erinnerungen bleiben, nur das Namenslabel geht.

Die Erinnerungen einer einzelnen Person lesen

by_speaker gibt zurück, was eine Person gesagt hat, neueste zuerst, ohne Suchanfrage. "me" liefert die eigenen Äußerungen des Assistenten. Gleiche Cursor-Paginierung wie bei Bilder: Geben Sie next_before und next_skip_ids zurück.

page = mem.by_speaker("Bob", limit=50)
page["memories"], page["chunks"]

const page = await mem.bySpeaker("Bob", undefined, { limit: 50 });

let page = mem.by_speaker("Bob", None, 50, None, None).await?;

curl -X POST https://api.wontopos.com/api/v1/memory/by-speaker \
  -H "X-API-Key: $WOS_KEY" \
  -d '{"user_id":"alice","speaker":"Bob","limit":50}'

Sprecher auflisten, durchsehen und entfernen

mem.list_speakers()                    # who is registered
mem.by_speaker("Bob")                 # what Bob said, newest first
mem.remove_speaker("Bob")             # unregister; the memories stay

await mem.listSpeakers();
await mem.bySpeaker("Bob");
await mem.removeSpeaker("Bob");

mem.list_speakers(None).await?;
mem.by_speaker("Bob", None, None, None, None).await?;
mem.remove_speaker("Bob", None).await?;

curl -X GET    .../api/v1/memory/speakers   -d '{"user_id":"alice"}'
curl -X POST   .../api/v1/memory/by-speaker -d '{"user_id":"alice","speaker":"Bob"}'
curl -X DELETE .../api/v1/memory/speakers   -d '{"user_id":"alice","speaker":"Bob"}'

Bilder

Eine Erinnerung kann ein Bild enthalten. Die Engine indexiert das Bild, sodass eine Textanfrage in jeder Sprache darauf passt, auch wenn der Datensatz keine Bildunterschrift, keinen Titel und keinen Alt-Text hat.

Ein Bild speichern

Übergeben Sie ein image-Objekt an den normalen add-Aufruf. content darf leer sein; das Bild ist dann für sich allein durchsuchbar.

mem.add("at the beach", image={"data": b64})   # caption + image
mem.add("", image={"data": b64})               # the image IS the memory

// the image rides in the 4th argument; the 3rd is metadata
await mem.add("at the beach", undefined, {}, { image: { data: b64 } });
await mem.add("", undefined, {}, { image: { data: b64 } });   // the image IS the memory

let img = json!({"image": {"data": b64}});
mem.add_with("at the beach", None, json!({}), img.clone()).await?;
mem.add_with("", None, json!({}), img).await?;

curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"","image":{"data":"<base64>"}}'

data ist erforderlich. Ein Präfix data:image/jpeg;base64, sowie die von base64 und openssl eingefügten Zeilenumbrüche werden für Sie entfernt.

Ein Bild finden

Es gibt keine separate Bildsuche. search und recall geben Bilder zusammen mit Text zurück, gemeinsam gerankt.

Mit vorhandenen Bilder arbeiten

data, mime = mem.get_image(memory_id=mid)
page       = mem.list_images(limit=50)      # page["count"] = store total
mem.forget_image(memory_id=mid, preview=True)

const { bytes, contentType } = await mem.getImage(undefined, mid);
const page = await mem.listImages(undefined, { limit: 50 });
await mem.forgetImage(undefined, mid, { preview: true });

let (bytes, mime) = mem.get_image(None, mid).await?;
let page = mem.list_images(None, 50, None, None).await?;
mem.forget_image(None, mid, true).await?;

# original bytes — the one call on this plane that is not JSON
curl -X POST   .../api/v1/memory/image  -d '{"user_id":"alice","memory_id":"m_1"}'
curl -X POST   .../api/v1/memory/images -d '{"user_id":"alice","limit":50}'
curl -X DELETE .../api/v1/memory/image  -d '{"user_id":"alice","memory_id":"m_1","preview":true}'

Übergeben Sie preview=True an forget_image, um memory_kept zu erhalten, ohne etwas zu ändern. iter_images übernimmt die Paginierung für Sie.

Was ein Bild kostet

Ein Bild wird in Token abgerechnet, derselben Einheit wie Text. Token = Fläche in Pixeln / 556,7. Ab 1.568 px an der langen Kante wird mit 1.568 px gerechnet, ein Bild mit 2.500 px kostet also so viel wie eines mit 1.568 px.

Obergrenze: 4.417 Token pro Bild. Wir reservieren diese Obergrenze vor dem Aufruf von Ihrem Guthaben und rechnen danach den gemessenen Wert ab, der nie höher ausfällt.

Wie viele zurückkommen

Standard 1, maximal 5 Bilder pro Antwort. Fünf Bilder sind knapp 20.000 Tokens.

verify

verify erlaubt einer Suche zusätzliche Durchläufe. Jeder Durchlauf schließt aus, was frühere Durchläufe zurückgegeben haben, sodass ein zweiter Durchlauf Erinnerungen erreicht, die der erste nicht erreicht hat.

Eine Ganzzahl 0-3 bei search und recall. Es ist die Anzahl der zusätzlichen Durchläufe, 3 erlaubt also vier Abrufe. Standard 0.

hits = mem.search("what did I eat", verify=3)
# the SDKs hand back the memories; `verify_used` is on the HTTP response (curl tab)

const hits = await mem.search("what did I eat", undefined, 10, { verify: 3 });
// the SDKs hand back the memories; `verify_used` is on the HTTP response (curl tab)

let hits = mem.search_opts("what did I eat", None, 10,
                            &SearchOpts { verify: Some(3), ..Default::default() }).await?;
// the SDKs hand back the memories; `verify_used` is on the HTTP response (curl tab)

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what did I eat","verify":3}'
# → {"memories":[…], "verify_used":1}

In dieser Schleife läuft kein Sprachmodell

Die Durchläufe führen die bereits zurückgegebenen IDs mit; die Engine schließt sie aus und sucht darüber hinaus. Die Anfrage wird nicht umformuliert, die Ergebnisse sind für eine gegebene Anfrage also deterministisch, und es sind keine Modell-Zugangsdaten beteiligt. Ihr Code entscheidet, ob ein weiterer Durchlauf aufgewendet wird.

Was Sie senden und was zurückkommt

Die Durchläufe brechen vorzeitig ab, sobald einer nichts Neues zurückgibt; nicht genutzte Durchläufe werden nicht berechnet. Schlägt ein späterer Durchlauf fehl, werden die bis dahin gesammelten Ergebnisse zurückgegeben.

MCP - Gedächtnis für KI-Tools

Der Kern von WOS sind API und SDKs. Der MCP-Server ist ein Add-on darüber: dasselbe Gedächtnis, eingesteckt in Tools, die du nicht gebaut hast - Claude Code, Claude Desktop, Cursor.

Eine Installationszeile gibt dem Agenten neun Gedächtnis-Tools, die er selbstständig nutzt. Und weil das Gedächtnis im Konto lebt, erinnert jedes andere Tool, was eines schreibt - auch Agenten, die du mit dem SDK baust.

Was damit möglich ist

• Ein Claude Code, der sich an dein Projekt erinnert. Entscheidungen, Bugfixes, Vorlieben - in der nächsten Sitzung abgerufen, ohne etwas neu zu erklären.
• In ChatGPT anfangen, in Claude weitermachen. Gleicher Store, gleiches Gedächtnis - das Gespräch wechselt das Tool, statt neu zu starten.
• Dein eigener Agent bleibt im Kreis. Was Claude Code lernt, ruft ein SDK-Agent ab - und was dein Agent speichert, erinnert Claude Code zurück.

Läuft in Claude Code, Claude Desktop, Cursor, Windsurf und jedem MCP-Host. ChatGPT erreicht dasselbe Gedächtnis über Actions plus die OpenAPI-Spec.

Installation

claude mcp add wontopos --env WONTOPOS_API_KEY=wos-live-... -- npx -y wontopos-mcp

Der Agent bekommt neun Tools - recall · remember · search · update · forget · list_memories · engram · stats · create_store - jedes so beschrieben, dass er selbst weiß, wann er sie nutzt.

Entwicklerseite öffnen →

OpenAPI-Spec

Die vollständige maschinenlesbare Karte der API - jeder Endpoint, Request, Response und Fehler.

OpenAPI ist das Industriestandard-Format, um eine HTTP-API in einer maschinenlesbaren Datei zu beschreiben.

https://api.wontopos.com/openapi.json

Was damit möglich ist

Postman: File → Import → URL einfügen - alle Endpoints erscheinen als klickbare Collection. ChatGPT: GPT erstellen, Action hinzufügen, dieselbe URL einfügen. Codegen: openapi-generator -i .../openapi.json -g go baut einen Client in einer Sprache, die wir nicht ausliefern.

In Postman importieren, einen Client in einer Sprache generieren, die wir nicht ausliefern, ChatGPT Actions anbinden oder Contract-Checks in CI fahren. Ein Test pinnt sie an die echten Routen - sie kann nicht driften.

llms.txt

Die ganze API auf einer Textseite, die eine KI lesen kann.

llms.txt ist eine Web-Konvention: eine Klartextseite an der Site-Root, die einer KI alles Nötige über ein Produkt sagt.

https://wontopos.com/llms.txt

In die IDE oder den Coding-Agenten legen - er weiß sofort, wie man auf WOS baut: Auth, Endpoints, Patterns, Fehler. Mit jedem Release aktualisiert.

Dieselben Fakten wie die OpenAPI-Spec, anderes Publikum: Die Spec ist präzise Struktur für Tools, diese Datei ist Prosa, die eine KI (oder ein Mensch) in einem Zug liest. Beide aktualisieren sich mit jedem Release.

Dein Gedächtnis in jedem KI-Tool

Ein Befehl gibt Claude Code, Claude Desktop, Cursor oder jedem MCP-Host ein Langzeitgedächtnis auf Basis deines WOS-Kontos. Kein Integrationscode: Der Agent bekommt neun Gedächtnis-Tools und entscheidet selbst, wann er sie nutzt.

Installation

Claude Code, eine Zeile (Key vorher in der Konsole erstellen):

claude mcp add wontopos --env WONTOPOS_API_KEY=wos-live-... -- npx -y wontopos-mcp
# pick which store it remembers into (optional): add --env WONTOPOS_USER_ID=my-project

# ~/.cursor/mcp.json
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

# .vscode/mcp.json
{ "servers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

# ~/.codeium/windsurf/mcp_config.json
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

# Claude Desktop and any other MCP host
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

Add to Cursor →  ·  Add to VS Code →

Optionale Env: WONTOPOS_USER_ID setzt den Standard-Store, WONTOPOS_MODEL die Engine, WONTOPOS_BASE_URL ein Self-Hosted-Deployment. WONTOPOS_READ_ONLY=1 schaltet auf Nur-Lesen (nur Recall/Suche/Liste).

Bevor du einen Store teilst

• Nutze einen eigenen Key. Keys tragen ihren Workspace: Ein nur für MCP erstellter Key begrenzt, was verbundene Tools überhaupt erreichen - und lässt sich in der Konsole rotieren, ohne die App-Keys anzufassen.
• Nur-Lese-Modus. WONTOPOS_READ_ONLY=1 registriert gar keine Schreib-Tools: Der Agent kann erinnern, suchen, Erinnerungen auflisten, Engrams ausführen und Statistiken lesen, aber nichts speichern, aktualisieren, vergessen oder löschen. Richtig für Agenten, die Gedächtnis nutzen, nicht besitzen sollen.
• Tool-Bestätigung anlassen. MCP-Hosts fragen standardmäßig vor jedem Tool-Lauf - lass das besonders für forget an, denn Löschungen teilen sich alle Tools des Stores.
• Alles Gespeicherte kann jedes Tool mit dem Key abrufen. Speichere niemals Geheimnisse - API-Keys, Passwörter - als Erinnerungen.
• Erinnerte Inhalte sind Daten, keine Anweisungen. Die Tool-Beschreibungen sagen das dem Agenten explizit. Speichere trotzdem keinen nicht vertrauenswürdigen Fremdtext in einem Store, dem ein autonomer Agent folgt.
• Löschungen werden ebenfalls geteilt. Ein forget oder delete_all aus einem Tool löscht für alle.
• "me" meint den Agenten, der in den Store schreibt. Teilen sich mehrere Agenten einen Store, verschmelzen ihre "me"-Stimmen. Gib jedem Agenten einen eigenen Store (WONTOPOS_USER_ID) für getrennte Identitäten.
• Ein Konto zahlt. Alle verbundenen Tools ziehen vom selben Guthaben und Rate-Limit.

Dann einfach reden

Sag einfach

• "Dieses Repo nutzt pnpm, merk dir das" → remember speichert es; die nächste Sitzung weiß es schon.
• "Welches Fehlerformat hatten wir letzte Woche festgelegt?" → recall holt die Entscheidung zurück in den Kontext.
• „Die Deadline ist jetzt Freitag.“ → der Agent merkt, dass es dem widerspricht, was er abgerufen hat, und ruft update auf, um die Erinnerung an Ort und Stelle zu korrigieren.
• "Das ist falsch, vergiss es" → der Agent findet die Memory-Id und ruft forget auf - dein Host fragt vorher nach.
• „Was weißt du über mich?“ → list_memories blättert durch alles Gespeicherte, damit der Agent antworten oder aufräumen kann.

Nichts Besonderes zu formulieren - das sind normale Sätze, keine Befehle. Der Agent liest die Tool-Beschreibungen und wählt selbst.

Die neun Tools

• recall - Kontext in einem Aufruf: jüngste Turns plus relevante Langzeiterinnerungen. Die Tool-Beschreibung weist den Agenten an, es zuerst aufzurufen, wenn Vergangenes zählt.
• remember - Speichert einen dauerhaften Fakt oder Beschluss. speaker: "me" markiert die eigenen Worte des Agenten; ein registrierter Name, wer es gesagt hat.
• search - Semantische Suche, mit optionalem speaker-Filter je Person — und filters, um sie zeitlich oder thematisch einzugrenzen ("Was haben wir im Juni entschieden?"), die eine Achse, die Bedeutung allein nicht eingrenzen kann.
• update - Ersetzt eine Erinnerung, deren Fakt sich geändert hat, und behält die Spur, statt sie zu löschen.
• forget - Löscht eine Erinnerung per id.
• list_memories - Blättert durch alles Gespeicherte, damit der Agent "Was weißt du über mich?" beantworten oder aufräumen kann.
• engram - Führt eine eingebaute Multi-Hop-Pipeline aus (deep_recall, timeline, gather), wenn eine einzelne Suche nicht reicht.
• stats - Wie viel in einem Store liegt - nützlich vor dem Aufräumen und um zu bestätigen, dass ein Schreibvorgang angekommen ist.
• create_store - Stores sind explizit: einer pro Endnutzer, Projekt oder Agent.

SDK oder MCP?

• Das SDK gehört in eine App, die du schreibst. Dein Code entscheidet exakt, wann gespeichert und was erinnert wird - deterministisch, typisiert, versioniert. Du baust ein Produkt? SDK.
• MCP steckt man in ein KI-Tool, das du nicht geschrieben hast. Der Agent entscheidet anhand der Tool-Beschreibungen, wann er Gedächtnis nutzt - null Code. Richtig für Claude Code, Claude Desktop, Cursor oder um einem fertigen Assistenten Gedächtnis zu geben.

Darunter dieselbe API, dieselben Stores - eine SDK-App und eine Claude-Code-Sitzung über MCP teilen ein Gedächtnis. Man wählt pro Oberfläche, nicht entweder-oder.

Ein Gedächtnis über alle Tools hinweg

Das Gedächtnis gehört dem Konto, nicht dem Tool. Derselbe Store, aus ChatGPT (Actions plus OpenAPI-Spec) geschrieben, wird in Claude Code und in deinen eigenen Agenten erinnert, und umgekehrt: Ein Gespräch, das in einem Tool beginnt, geht in einem anderen weiter.

Und weil es ein Store ist, kannst du Claude Code verlassen und dort weiterreden, wo du baust: Ein SDK-Agent mit demselben Key und Store erinnert alles, was Claude Code gerade gelernt hat - und was dein Agent speichert, erinnert Claude Code in der nächsten Sitzung.

Claude Code

Der Hauptweg: ein Befehl im Terminal, und jede Sitzung startet mit Gedächtnis.

1. Erstelle einen API-Key in der Konsole. Der Key trägt seinen Workspace: ein Key = ein Gedächtnisraum.
2. Registriere den Server. --scope user macht ihn in jedem Projekt verfügbar; ohne sieht ihn nur das aktuelle Projekt.
3. Prüfen: /mcp in Claude Code ausführen - wontopos sollte mit neun Tools gelistet sein.
4. Mach es automatisch: eine Zeile in deiner CLAUDE.md - "wenn Vergangenes zählt, zuerst wontopos recall aufrufen" - und jede Sitzung startet ungefragt mit Gedächtnis.

claude mcp add wontopos --scope user \
  --env WONTOPOS_API_KEY=wos-live-... -- npx -y wontopos-mcp
# pick a store (optional): add --env WONTOPOS_USER_ID=my-project

Claude Desktop

Füge den Block unten in claude_desktop_config.json ein (Einstellungen → Developer → Edit Config), starte die App neu - die neun Tools erscheinen. Hinweis: claude.ai im Web und mobil braucht einen Remote-MCP-Server, den WOS noch nicht anbietet - die Desktop-App ist der unterstützte Weg.

# claude_desktop_config.json
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

Cursor

Füge den Block unten in ~/.cursor/mcp.json ein - oder nutze den Ein-Klick-Button - und starte Cursor neu. Der Agent übernimmt die neun Tools.

# ~/.cursor/mcp.json
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

Add to Cursor →

VS Code

VS Code (Copilot-Agentenmodus) liest MCP-Server aus .vscode/mcp.json im Projekt - füge den Block unten ein oder nutze den Ein-Klick-Button.

# .vscode/mcp.json
{ "servers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

Add to VS Code →

Windsurf

Windsurf (Cascade) liest ~/.codeium/windsurf/mcp_config.json: Block unten einfügen und neu laden - dieselben neun Tools erscheinen.

# ~/.codeium/windsurf/mcp_config.json
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

ChatGPT

ChatGPTs MCP-Konnektoren akzeptieren nur Remote-Server; der unterstützte Weg ist heute ein Custom GPT mit einer Action: GPT erstellen, Action hinzufügen, die OpenAPI-Spec-URL unten einfügen und den API-Key als Auth-Header setzen. Dieses GPT ruft dann dasselbe Gedächtnis auf wie deine anderen Tools.

# GPT → Configure → Actions → Import from URL
https://api.wontopos.com/openapi.json
# Authentication: API Key · Header name: X-API-Key

Gleicher Store, gleiches Gedächtnis: Was ChatGPT über die Action speichert, erinnert Claude Code über MCP - und umgekehrt.

Gemini CLI

Gemini CLI liest MCP-Server aus ~/.gemini/settings.json: Block unten einfügen, CLI neu starten - dieselben neun Tools erscheinen auch dort.

# ~/.gemini/settings.json
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

Python - jede Methode, drei Gruppen.

Schreiben, Lesen, Löschen. Jedes Beispiel unten wurde am 2026-08-01 gegen die Live-API ausgeführt; die Antworten sind wortwörtlich wiedergegeben.

pip install wontopos

from wontopos import Client

mem = Client(api_key="wos-live-...")  # or read from an env var

Modell wählen

mem = Client(api_key="wos-live-...", model="tablet-1")  # default engine
mem.recall("...", user_id="alice")                  # tablet-1
mem.recall("...", user_id="alice", model="scroll-1")  # or pick a model per call

mem.list_models()

[{"id": "tablet-1", "name": "Tablet 1", "available": true, "memory": "shared"},
 {"id": "tablet-2", "name": "Tablet 2", "available": true, "memory": "shared"},
 {"id": "scroll-1", "name": "Scroll 1", "available": true, "memory": "shared"},
 {"id": "scroll-1.2", "name": "Scroll 1.2", "available": true, "memory": "shared"}]

mem.ping()   # True, or raises AuthenticationError / PaymentRequiredError

Der Katalog oben spiegelt stets die aktuell verfügbaren Modelle wider - übergeben Sie eine andere ID, erhalten Sie einen klaren Fehler. Neue Modelle erscheinen dort automatisch, sobald sie ausgeliefert werden.

Schreiben

mem.add("she prefers tea over coffee", user_id="alice")
mem.add("I promised the summary by Friday", user_id="alice", speaker="me")  # its own words - no registration needed

{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}

mem.add_turn("hi", "hello!", user_id="alice")

{"status": "ok"}

mem.add_speaker("Bob", user_id="alice")  # once per person; "me" needs no registration
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")

[{"content": "Bob said the deadline moved to Tuesday", "speaker": "Bob", ...}]

mem.add_bulk("Alice moved to Brooklyn in March. She works at a design studio downtown.", user_id="alice")

{"elapsed_secs": 0.154154944, "status": "ok", "stored": 1, "total_chunks": 1}

mem.update("576700aa-...", "she switched to coffee this year", user_id="alice")

{"new_memory_id": "07e94433-b7cc-4e49-8d8f-f37fc1a392b7",
 "old_memory_id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "superseded"}

Lesen

r = mem.search("what does she drink?", user_id="alice", limit=1)

[{
   "id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624",
   "content": "she prefers tea over coffee",
   "category": "general",
   "time_bucket": "2026-06",
   "importance": 0.3,
   "similarity": 0.6316057443618774,
   "is_superseded": false,
   "superseded_by": null,
   "created_at": "2026-07-10T04:20:39.688276876Z"
 }]

ctx = mem.recall("what does she drink?", user_id="alice")

{"short_term":  {"count": 2, "turns": [{"role": "user", "content": "hi", ...}]},
 "long_term":   {"count": 4, "memories": [{"content": "she prefers tea over coffee",
                                           "similarity": 0.63, ...}]},
 "context":     {"count": 4, "around_top_memory": [
                  "[match] she prefers tea over coffee",
                  "[after] Alice moved to Brooklyn in March. ..."]},
 "instruction": "Use short_term for recent context, long_term for relevant
                 past memories, context for surrounding conversation of the
                 most relevant memory."}

turns = mem.history("alice")

{"count": 2, "turns": [
   {"role": "user",      "content": "hi",     "timestamp": "2026-07-10T04:20:40.989011337Z"},
   {"role": "assistant", "content": "hello!", "timestamp": "2026-07-10T04:20:40.989013416Z"}
 ], "user_id": "alice"}

mem.stats("alice")

{"short_term_turns": 2, "total_memories": 4, "user_id": "alice"}

m = mem.get("alice", memory_id="576700aa-...")

{"id": "576700aa-...", "content": "she prefers tea over coffee",
 "category": "general", "created_at": "2026-07-10T04:20:39Z", "event_date": null,
 "is_superseded": false, "superseded_by": null}

{"memory": {"id": "8bd090de-...", "content": "the office moved to the seventh floor in June",
  "category": "general", "created_at": "2026-07-31T18:20:30.531518060+00:00", "event_date": null,
  "is_superseded": false, "superseded_by": null}, "user_id": "docs_livetest"}

page = mem.list_memories("alice", limit=100)

{"count": 2, "next_cursor": null, "memories": [
   {"id": "576700aa-...", "content": "she prefers tea over coffee",
    "category": "general", "created_at": "2026-07-10T04:20:39Z", "event_date": null,
 "is_superseded": false, "superseded_by": null}
 ]}

for m in mem.iter_memories("alice"):   # every page, no cursor bookkeeping
    print(m["id"], m["content"])
everything = mem.export_memories("alice")   # the whole store as a list

Löschen

mem.delete("alice", memory_id="576700aa-...")

{"memory_id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "deleted"}

mem.delete_all("alice")

{"memories_deleted": 4, "status": "deleted", "user_id": "alice"}

Fehler und Zuverlässigkeit

from wontopos import PaymentRequiredError, NotFoundError
try:
    mem.add("...", user_id="alice")
except NotFoundError:
    mem.create_store("alice")   # store didn't exist yet
except PaymentRequiredError:
    top_up()                       # out of credit - don't retry

mem.search("...", user_id="alice")
rl = mem.rate_limit   # {"limit": 150, "remaining": 3, "reset": ...}

r = mem.search_self("what did I promise?", user_id="alice")
r["memories"]       # what others said / general memories
r["self_memories"]  # the agent's OWN words (speaker "me")

cat = mem.list_engrams()
[e["name"] for e in cat["engrams"]]   # ask, never hard-code

mem.search("what did we decide", user_id="alice", filters={
    "categories": ["work"],
    "event_from": "2026-01-01",   # when it HAPPENED
})

mem.add("she prefers tea", "alice", idempotency_key=f"import:{row.id}")

mem.with_timeout(120).add_bulk(big_blob, "alice")  # this slow call only
mem.with_retries(0).add("...", "alice")              # you retry, not the SDK

TypeScript - jede Methode, drei Gruppen.

Schreiben, Lesen, Löschen. Jedes Beispiel unten wurde am 2026-08-01 gegen die Live-API ausgeführt; die Antworten sind wortwörtlich wiedergegeben.

npm install wontopos

import { Client } from "wontopos";

const mem = new Client({ apiKey: "wos-live-..." });

Modell wählen

const mem = new Client({ apiKey: "wos-live-...", model: "tablet-1" });  // default
mem.recall("...", "alice");                          // tablet-1
mem.withModel("scroll-1").recall("...", "alice");  // or pick a model per call

await mem.listModels();

[{"id": "tablet-1", "name": "Tablet 1", "available": true, "memory": "shared"},
 {"id": "tablet-2", "name": "Tablet 2", "available": true, "memory": "shared"},
 {"id": "scroll-1", "name": "Scroll 1", "available": true, "memory": "shared"},
 {"id": "scroll-1.2", "name": "Scroll 1.2", "available": true, "memory": "shared"}]

await mem.ping();   // true, or throws AuthenticationError / PaymentRequiredError

Der Katalog oben spiegelt stets die aktuell verfügbaren Modelle wider - übergeben Sie eine andere ID, erhalten Sie einen klaren Fehler. Neue Modelle erscheinen dort automatisch, sobald sie ausgeliefert werden.

Schreiben

await mem.add("she prefers tea over coffee", "alice");
await mem.add("I promised the summary by Friday", "alice", { speaker: "me" });  // its own words - no registration needed

{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}

await mem.addTurn("hi", "hello!", "alice");

{"status": "ok"}

await mem.addSpeaker("Bob", "alice");  // once per person; "me" needs no registration
await mem.add("I promised to send the report on Friday", "alice", { speaker: "me" });
await mem.add("Bob said the deadline moved to Tuesday", "alice", { speaker: "Bob" });
await mem.search("what did Bob say about deadlines?", "alice", 10, { speaker: "Bob" });

await mem.addBulk("Alice moved to Brooklyn in March. She works at a design studio downtown.", "alice");

{"elapsed_secs": 0.154154944, "status": "ok", "stored": 1, "total_chunks": 1}

await mem.update("576700aa-...", "she switched to coffee this year", "alice");

{"new_memory_id": "07e94433-b7cc-4e49-8d8f-f37fc1a392b7",
 "old_memory_id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "superseded"}

Lesen

const r = await mem.search("what does she drink?", "alice", 1);

[{
   "id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624",
   "content": "she prefers tea over coffee",
   "category": "general",
   "time_bucket": "2026-06",
   "importance": 0.3,
   "similarity": 0.6316057443618774,
   "is_superseded": false,
   "superseded_by": null,
   "created_at": "2026-07-10T04:20:39.688276876Z"
 }]

const ctx = await mem.recall("what does she drink?", "alice");

{"short_term":  {"count": 2, "turns": [{"role": "user", "content": "hi", ...}]},
 "long_term":   {"count": 4, "memories": [{"content": "she prefers tea over coffee",
                                           "similarity": 0.63, ...}]},
 "context":     {"count": 4, "around_top_memory": [
                  "[match] she prefers tea over coffee",
                  "[after] Alice moved to Brooklyn in March. ..."]},
 "instruction": "Use short_term for recent context, long_term for relevant
                 past memories, context for surrounding conversation of the
                 most relevant memory."}

const turns = await mem.history("alice");

{"count": 2, "turns": [
   {"role": "user",      "content": "hi",     "timestamp": "2026-07-10T04:20:40.989011337Z"},
   {"role": "assistant", "content": "hello!", "timestamp": "2026-07-10T04:20:40.989013416Z"}
 ], "user_id": "alice"}

await mem.stats("alice");

{"short_term_turns": 2, "total_memories": 4, "user_id": "alice"}

const m = await mem.get("alice", "576700aa-...");

{"id": "576700aa-...", "content": "she prefers tea over coffee",
 "category": "general", "created_at": "2026-07-10T04:20:39Z", "event_date": null,
 "is_superseded": false, "superseded_by": null}

const page = await mem.listMemories("alice", { limit: 100 });

{"count": 2, "next_cursor": null, "memories": [
   {"id": "576700aa-...", "content": "she prefers tea over coffee",
    "category": "general", "created_at": "2026-07-10T04:20:39Z", "event_date": null,
 "is_superseded": false, "superseded_by": null}
 ]}

for await (const m of mem.iterMemories("alice")) console.log(m.id, m.content);
const everything = await mem.exportMemories("alice");

Löschen

await mem.delete("alice", "576700aa-...");

{"memory_id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "deleted"}

await mem.deleteAll("alice");

{"memories_deleted": 4, "status": "deleted", "user_id": "alice"}

Fehler und Zuverlässigkeit

import { NotFoundError, PaymentRequiredError } from "wontopos";
try {
  await mem.add("...", "alice");
} catch (e) {
  if (e instanceof NotFoundError) await mem.createStore("alice");
  else if (e instanceof PaymentRequiredError) topUp();   // out of credit
  else throw e;
}

await mem.search("...", "alice");
const rl = mem.rateLimit;   // { limit: 150, remaining: 3, reset: ... }

const { memories, self_memories } = await mem.searchSelf("what did I promise?", "alice");
// memories = what others said · self_memories = the agent's OWN words

const { engrams, forms } = await mem.listEngrams();  // ask, never hard-code

await mem.search("what did we decide", "alice", 10, {
  filters: { categories: ["work"], event_from: "2026-01-01" },  // when it HAPPENED
});

await mem.add("she prefers tea", "alice", {}, { idempotencyKey: `import:${row.id}` });

await mem.withTimeout(120_000).addBulk(bigBlob, "alice");  // this slow call only
await mem.withRetries(0).add("...", "alice");            // you retry, not the SDK

Rust - jede Methode, drei Gruppen.

Schreiben, Lesen, Löschen. Jedes Beispiel unten wurde am 2026-08-01 gegen die Live-API ausgeführt; die Antworten sind wortwörtlich wiedergegeben.

cargo add wontopos

use wontopos::Client;

let mem = Client::new("wos-live-...");

Modell wählen

let mem = Client::new("wos-live-...").with_model("tablet-1");  // default
mem.recall("...", "alice").await?;                       // tablet-1
mem.with_model("scroll-1").recall("...", "alice").await?;  // or pick a model per call

mem.list_models().await?;

[{"id": "tablet-1", "name": "Tablet 1", "available": true, "memory": "shared"},
 {"id": "tablet-2", "name": "Tablet 2", "available": true, "memory": "shared"},
 {"id": "scroll-1", "name": "Scroll 1", "available": true, "memory": "shared"},
 {"id": "scroll-1.2", "name": "Scroll 1.2", "available": true, "memory": "shared"}]

mem.ping().await?;   // Ok(true), or Err whose .kind() is Auth / PaymentRequired

Der Katalog oben spiegelt stets die aktuell verfügbaren Modelle wider - übergeben Sie eine andere ID, erhalten Sie einen klaren Fehler. Neue Modelle erscheinen dort automatisch, sobald sie ausgeliefert werden.

Schreiben

mem.add("she prefers tea over coffee", "alice", json!({})).await?;
mem.add("I promised the summary by Friday", "alice", json!({"speaker": "me"})).await?;  // its own words - no registration needed

{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}

mem.add_turn("hi", "hello!", "alice").await?;

{"status": "ok"}

mem.add_speaker("Bob", "alice").await?;  // once per person; "me" needs no registration
mem.add("I promised to send the report on Friday", "alice", json!({"speaker": "me"})).await?;
mem.add("Bob said the deadline moved to Tuesday", "alice", json!({"speaker": "Bob"})).await?;
mem.search_with("what did Bob say about deadlines?", "alice", 10, json!({"speaker": "Bob"})).await?;

mem.add_bulk("Alice moved to Brooklyn in March...", "alice", "general").await?;

{"elapsed_secs": 0.154154944, "status": "ok", "stored": 1, "total_chunks": 1}

mem.update("576700aa-...", "she switched to coffee this year", "alice").await?;

{"new_memory_id": "07e94433-b7cc-4e49-8d8f-f37fc1a392b7",
 "old_memory_id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "superseded"}

Lesen

let r = mem.search("what does she drink?", "alice", 1).await?;

[{
   "id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624",
   "content": "she prefers tea over coffee",
   "category": "general",
   "time_bucket": "2026-06",
   "importance": 0.3,
   "similarity": 0.6316057443618774,
   "is_superseded": false,
   "superseded_by": null,
   "created_at": "2026-07-10T04:20:39.688276876Z"
 }]

let ctx = mem.recall("what does she drink?", "alice").await?;

{"short_term":  {"count": 2, "turns": [{"role": "user", "content": "hi", ...}]},
 "long_term":   {"count": 4, "memories": [{"content": "she prefers tea over coffee",
                                           "similarity": 0.63, ...}]},
 "context":     {"count": 4, "around_top_memory": [
                  "[match] she prefers tea over coffee",
                  "[after] Alice moved to Brooklyn in March. ..."]},
 "instruction": "Use short_term for recent context, long_term for relevant
                 past memories, context for surrounding conversation of the
                 most relevant memory."}

let turns = mem.history("alice").await?;

{"count": 2, "turns": [
   {"role": "user",      "content": "hi",     "timestamp": "2026-07-10T04:20:40.989011337Z"},
   {"role": "assistant", "content": "hello!", "timestamp": "2026-07-10T04:20:40.989013416Z"}
 ], "user_id": "alice"}

mem.stats("alice").await?;

{"short_term_turns": 2, "total_memories": 4, "user_id": "alice"}

let m = mem.get("alice", "576700aa-...").await?;

{"id": "576700aa-...", "content": "she prefers tea over coffee",
 "category": "general", "created_at": "2026-07-10T04:20:39Z", "event_date": null,
 "is_superseded": false, "superseded_by": null}

mem.list_memories("alice", 100, None).await?;

{"count": 2, "next_cursor": null, "memories": [
   {"id": "576700aa-...", "content": "she prefers tea over coffee",
    "category": "general", "created_at": "2026-07-10T04:20:39Z", "event_date": null,
 "is_superseded": false, "superseded_by": null}
 ]}

let all = mem.list_all_memories("alice").await?;   // every page, collected

Löschen

mem.delete("alice", "576700aa-...").await?;

{"memory_id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "deleted"}

mem.delete_all("alice").await?;

{"memories_deleted": 4, "status": "deleted", "user_id": "alice"}

Fehler und Zuverlässigkeit

use wontopos::ErrorKind;
match mem.search("...", "alice", 10).await {
    Ok(hits) => { /* use hits */ }
    Err(e) if e.kind() == ErrorKind::NotFound => { mem.create_store("alice").await?; }
    Err(e) if e.is_rate_limited() => { /* back off */ }
    Err(e) => return Err(e),
}

mem.search("...", "alice", 10).await?;
let rl = mem.rate_limit();   // Some(RateLimit { remaining: Some(3), .. })

let r = mem.search_self("what did I promise?", "alice", 10).await?;
// r.memories = what others said · r.self_memories = the agent's OWN words

let cat = mem.list_engrams().await?;  // ask, never hard-code

mem.search_with("what did we decide", "alice", 10, json!({"filters": {
    "categories": ["work"], "event_from": "2026-01-01"   // when it HAPPENED
}})).await?;

mem.add_idempotent("she prefers tea", "alice", json!({}), &format!("import:{}", row.id)).await?;

mem.with_timeout(120).add_bulk(big_blob, "alice", "general").await?;
mem.with_retries(0).add("...", "alice", json!({})).await?;

curl - keine Installation, dieselben Methoden.

Kein SDK zu installieren - jeder HTTP-Client funktioniert. Setzen Sie Ihren Schlüssel einmal und rufen Sie dieselben Endpunkte auf, die die SDKs kapseln. Basis-URL https://api.wontopos.com, Authentifizierung über X-API-Key, JSON rein und raus.

# set your key once (never hard-code it)
export WOS_API_KEY="wos-live-..."

Schreiben

curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"she prefers tea over coffee"}'

{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}

curl -X POST https://api.wontopos.com/api/v1/memory/store-turn \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","user_msg":"hi","assistant_msg":"hello!"}'

{"status": "ok"}

curl -X POST https://api.wontopos.com/api/v1/memory/speakers \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","speaker":"Bob"}'   # once per person

curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"I promised to send the report on Friday","metadata":{"speaker":"me"}}'

curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"Bob said the deadline moved to Tuesday","metadata":{"speaker":"Bob"}}'

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what did Bob say about deadlines?","speaker":"Bob"}'

curl -X POST https://api.wontopos.com/api/v1/memory/supersede \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","old_memory_id":"576700aa-...","new_content":"she switched to coffee this year"}'

{"new_memory_id": "07e94433-...", "old_memory_id": "576700aa-...", "status": "superseded"}

curl -X POST https://api.wontopos.com/api/v1/memory/bulk-store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"...a long history...","category":"general"}'

{"elapsed_secs": 0.138589761, "status": "ok", "stored": 1, "total_chunks": 1}

# same key + same body = the FIRST response is replayed, nothing is stored twice
curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: import:row-42" \
  -d '{"user_id":"alice","content":"she prefers tea over coffee"}'

Lesen

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what does she drink?","max_results":1}'

{"memories": [{"id": "576700aa-...", "content": "she prefers tea over coffee",
   "similarity": 0.63, "is_superseded": false}], "search_ms": 315, "total_found": 1}

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what did we decide",
       "filters":{"categories":["work"],"event_from":"2026-01-01","event_to":"2026-06-30"}}'

curl -X POST https://api.wontopos.com/api/v1/memory/get \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","memory_id":"576700aa-f0e0-4c26-99a0-10e2d5b0d624"}'

curl -X POST https://api.wontopos.com/api/v1/memory/list \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","limit":100}'   # pass next_cursor back for the next page

{"count": 3, "memories": [{"id": "1a1cfc47-...", "content": "...", "category": "general",
   "created_at": "2026-07-31T18:04:51.937117314+00:00", "event_date": null, "is_superseded": false}],
 "next_cursor": "722c08e5-8998-4882-979e-d71995b5b4af", "user_id": "docs_livetest"}

curl -X POST https://api.wontopos.com/api/v1/memory/recall \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what does she drink?"}'

{"short_term": {"count": 2, "turns": [...]},
 "long_term":  {"count": 4, "memories": [{"content": "she prefers tea over coffee", "similarity": 0.63}]},
 "context":    {"count": 4, "around_top_memory": ["[match] she prefers tea over coffee"]},
 "instruction": "Use short_term for recent context, long_term for relevant past memories..."}

Löschen

curl -X POST https://api.wontopos.com/api/v1/memory/forget \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice"}'  # omit memory_id = delete all

{"memories_deleted": 1, "status": "deleted", "user_id": "alice"}

Jeder Endpunkt + Body-Felder →

Varianten nur in Rust

Python und TypeScript nehmen diese als optionale Argumente entgegen. Stable Rust kennt keine Standard- oder Schlüsselwortargumente, daher ist jede Variante eine eigene Methode und kein Builder, den Sie abschließen müssen.

mem.add_with(text, None, json!({}), extra)   // add + extra body fields
mem.search_opts(q, None, 10, &opts)            // search + verify / max_images
mem.search_with(q, None, 10, extra)            // search + any other field
mem.recall_with(q, None, extra)                // recall + extra
mem.search_self_with(q, None, 10, extra)       // self lane + extra
mem.engram_with(name, q, None, extra)          // engram + extra
mem.update_idempotent(old, new, None, key)     // update + Idempotency-Key
mem.add_turn_idempotent(u, a, None, key)
mem.add_bulk_idempotent(text, None, cat, key)
mem.revisions_page(None, "revised", 20, None, None)
mem.list_all_images(None, None)              // = iter_images, collected

list_all_images wird zusätzlich als iter_images exportiert, passend zu dem Namen, den die beiden anderen SDKs verwenden - wer aus jener Dokumentation kommt, tippt zuerst diesen Namen.

Engrams

Aufrufbare Recall-Werkzeuge, die Ihr Modell einsetzen kann - jedes eine eigene Abrufstrategie über dasselbe Gedächtnis. Nutzen Sie eines oder führen Sie mehrere zugleich aus.

Regelmäßig erscheinen weitere Engramme - diese Liste wächst.

Memoir & Archive Scroll 1.2+

Dies ist eine Auslieferungs-Form, kein aufrufbares Werkzeug. Ab Scroll 1.2 wählen Sie sie pro Aufruf - form: "memoir" oder form: "archive" - und dieser Recall, eine einfache Suche eingeschlossen, kommt mit entsprechend geschriebener Zeit zurück.

Time_awareness Scroll 1.2+

Eine Auslieferungsform - pro Aufruf gewählt. Übergeben Sie form - memoir oder archive - bei einem beliebigen Aufruf eines formfähigen Modells (ab Scroll 1.2), und die Antwort kommt entsprechend gerendert zurück: eine einfache Suche, ein Recall oder jedes Engramm. In den SDKs ist es ein form-Feld wie tz; über HTTP der Header X-WOS-Form. Ein Memoir liest sich, wie ein Mensch sich erinnert; ein Archive führt ein exaktes Protokoll - der Unterschied zeigt sich am deutlichsten darin, wie beide die Zeit schreiben.

# the memoir form on a plain search — and on recall, the LLM's one-call context
r   = mem.search("what does Alice drink?", user_id="alice", model="scroll-1.2", form="memoir", tz=9)
ctx = mem.recall("what does Alice drink?", user_id="alice", model="scroll-1.2", form="memoir", tz=9)
# every memory's .time reads "a couple weeks ago" (archive → "2 weeks ago (Jun 09)") — the LLM sees human time

// the memoir form on search — and on recall, the LLM's one-call context
const s = await mem.withModel("scroll-1.2").search("what does Alice drink?", "alice", 10, { form: "memoir", tz: 9 });
const ctx = await mem.withModel("scroll-1.2").recall("what does Alice drink?", "alice", { form: "memoir", tz: 9 });

// form on search AND recall — the _with helpers merge extra fields into the body
let s = mem.with_model("scroll-1.2").search_with("what does Alice drink?", "alice", 10, json!({"form": "memoir", "tz": 9})).await?;
let ctx = mem.with_model("scroll-1.2").recall_with("what does Alice drink?", "alice", json!({"form": "memoir", "tz": 9})).await?;

# same X-WOS-Form header on /search, /recall, or /engram/run
curl -X POST https://api.wontopos.com/api/v1/memory/recall \
  -H "X-API-Key: wos-live-..." -H "X-WOS-Model: scroll-1.2" -H "X-WOS-Form: memoir" -H "X-WOS-Timezone: 9" \
  -d '{"user_id":"alice","query":"what does Alice drink?"}'
# every memory comes back with a "time" field; use X-WOS-Form: archive for exact time

tz ist der UTC-Versatz des Aufrufers in Stunden - damit "heute Morgen" und die 4-Uhr-Tagesgrenze in dessen Ortszeit landen. Weglassen für UTC; über HTTP ist es der X-WOS-Timezone-Header. Grob nach Region: US-Ostküste -5, US-Zentral -6, US-Westküste -8 · UK / Lissabon 0 · Mitteleuropa +1 · Osteuropa +2 · Indien +5.5 · China / Singapur +8 · Korea / Japan +9 · Sydney +10. (Normalzeit - die Sommerzeit verschiebt manche Regionen um +1; übergeben Sie, was für Ihre Nutzer tatsächlich gilt.)

Dieselbe Suche, zwei Formen - die Erinnerungen sind identisch, nur time ändert sich:

{ "count": 3, "memories": [
  { "content": "Alice prefers tea over coffee", "time": "a couple weeks ago" },
  { "content": "met Alice at the cafe downtown",  "time": "yesterday afternoon" },
  { "content": "Alice moved to Brooklyn",          "time": "about half a year ago" }
] }

{ "count": 3, "memories": [
  { "content": "Alice prefers tea over coffee", "time": "2 weeks ago (Jun 09)" },
  { "content": "met Alice at the cafe downtown",  "time": "yesterday at 14:00" },
  { "content": "Alice moved to Brooklyn",          "time": "6 months ago (Dec 2025)" }
] }

Jeder Wert oben ist die tatsächliche Ausgabe des Renderers. Betrachten Sie die beiden "gestern"-Zeilen: Ein Memoir trennt den Nachmittag von der letzten Nacht - ein Tag ist ein Schlaf - während ein Archive eine einzelne Uhrzeit schreibt und keine Tag-Nacht-Grenze zieht.

Wie jeder Modus die Zeit liest

Memoir - so, wie Menschen es tatsächlich sagen. Jüngste Momente bleiben recht scharf (etwa 15 Minuten, eine halbe Stunde), dann weitet sich die Formulierung, je weiter man zurückgeht - ein paar Wochen, etwa ein halbes Jahr, ein paar Jahre - so, wie sich Erinnerung selbst mit der Entfernung lockert. Innerhalb eines Tages weicht die Uhr einem Orientierungspunkt: heute Morgen, letzte Nacht, gestern Nachmittag. Und ein Tag ist ein Schlaf, kein Kalendersprung: Die Grenze liegt bei etwa 4 Uhr Ortszeit, sodass eine späte Nacht noch als derselbe Abend gilt, nicht schon als morgen.

Archive - präzise, stets mit Anker. Jede Zeile trägt die exakte verstrichene Zeit plus eine absolute Referenz, mit der ein Modell rechnen kann, und der Anker wird enger, je näher es rückt: eine Uhrzeit für heute (vor 8 Stunden, um 07:10), Wochentag und Uhrzeit für diese Woche (vor 2 Tagen (Di 15:10)), ein Datum für diesen Monat (letzte Woche (16. Jun)), Monat und Jahr darüber hinaus (vor 6 Monaten (Dez 2025)). Nie vage, nie falsch.

deep_recall

Multi-Hop-Recall. Sucht nach Ihrer Abfrage, nimmt dann den besten Treffer und sucht erneut nach dessen Inhalt - und holt so verknüpften Kontext ein, den eine einzelne Suche übersehen würde. Am stärksten, wenn Erinnerungen aufeinander verweisen (eine Person → ihre Projekte → Details). Liefert bis zu ~12.

out = mem.engram("deep_recall", "what should I know about Alice?", user_id="alice")

const out = await mem.engram("deep_recall", "what should I know about Alice?", "alice");

let out = mem.engram("deep_recall", "what should I know about Alice?", "alice").await?;

curl -X POST https://api.wontopos.com/api/v1/engram/run \
  -H "X-API-Key: wos-live-..." -H "Content-Type: application/json" \
  -d '{"name":"deep_recall","user_id":"alice","query":"what should I know about Alice?"}'

{ "engram": "deep_recall", "hops": 2, "count": 12,
  "memories": [ ... ],
  "usage": { "input_tokens": 200, "output_tokens": 589 } }

timeline

Zeitlich geordneter Recall. Liefert Erinnerungen neueste zuerst, sortiert nach dem Zeitpunkt des Ereignisses, nicht nach Relevanz. Für "Wann war X", Verlauf und Reihenfolgefragen. Liefert bis zu 15.

events = mem.engram("timeline", "project milestones", user_id="alice")

const events = await mem.engram("timeline", "project milestones", "alice");

let events = mem.engram("timeline", "project milestones", "alice").await?;

curl -X POST https://api.wontopos.com/api/v1/engram/run \
  -H "X-API-Key: wos-live-..." -H "Content-Type: application/json" \
  -d '{"name":"timeline","user_id":"alice","query":"project milestones"}'

{ "engram": "timeline", "hops": 1, "count": 15,
  "memories": [ ... ],
  "usage": { "input_tokens": 100, "output_tokens": 736 } }

gather

Breites Sammeln. Sucht und erweitert dann um die besten drei Treffer herum - ein weiteres Netz als deep_recall. Damit holen Sie alles zu einer Person, einem Projekt oder einem Thema in einem Aufruf ein. Liefert bis zu ~18.

related = mem.engram("gather", "everything about Project Atlas", user_id="alice")

const related = await mem.engram("gather", "everything about Project Atlas", "alice");

let related = mem.engram("gather", "everything about Project Atlas", "alice").await?;

curl -X POST https://api.wontopos.com/api/v1/engram/run \
  -H "X-API-Key: wos-live-..." -H "Content-Type: application/json" \
  -d '{"name":"gather","user_id":"alice","query":"everything about Project Atlas"}'

{ "engram": "gather", "hops": 4, "count": 18,
  "memories": [ ... ],
  "usage": { "input_tokens": 400, "output_tokens": 637 } }

equilibrium

Driftkorrektur. Semantische Suche verengt sich im Verlauf einer Sitzung: die Anfrage trägt den aktuellen Zustand, holt Erinnerungen desselben Zustands und der nächste Zug neigt sich weiter dorthin. Dieses Engram weitet das Ergebnis entlang dreier Achsen, die die Anfrage nicht kontrolliert: Streuung über die Zeit, Assoziation weg von der Anfrage und der inhaltlich tragende Teil des Speichers. Nutzen Sie es, wenn Antworten kreisen oder flach werden. Für einen konkreten Fakt passen deep_recall oder gather besser, die näher an der Anfrage bleiben. Liefert bis zu 12.

wide = mem.engram("equilibrium", "how have things been lately?", user_id="alice")

const wide = await mem.engram("equilibrium", "how have things been lately?", "alice");

let wide = mem.engram("equilibrium", "how have things been lately?", "alice").await?;

curl -X POST https://api.wontopos.com/api/v1/engram/run \
  -H "X-API-Key: wos-live-..." -H "Content-Type: application/json" \
  -d '{"name":"equilibrium","user_id":"alice","query":"how have things been lately?"}'

{ "engram": "equilibrium", "hops": 3, "count": 12,
  "memories": [ ... ],
  "usage": { "input_tokens": 300, "output_tokens": 293 } }

tone_stabilizer

Die eigene Stimme. Lange Sitzungen ziehen einen Assistenten aus seiner Tonlage: Antworten werden länger, geraten zum Bericht oder nehmen die Stimmung der letzten Strecke an. Gewöhnliches Selbst-Recall verschlimmert das, weil es den aktuellen Zustand trifft und die neuesten Zeilen zurückgibt, als wären sie der Charakter. Dieses Engram liefert stattdessen die eigenen Worte von vor dieser Strecke. Es braucht Beiträge, die mit speaker me gespeichert wurden; ohne solche gibt es nichts zurück statt zu raten. Liefert bis zu 10.

# store the assistant's turns as speaker "me", then pull its own register back
mem.add("I keep answers short unless you ask for detail.", user_id="alice", speaker="me")
mine = mem.engram("tone_stabilizer", "how do I usually answer?", user_id="alice")

await mem.add("I keep answers short unless you ask for detail.", "alice", { speaker: "me" });
const mine = await mem.engram("tone_stabilizer", "how do I usually answer?", "alice");

mem.add("I keep answers short unless you ask for detail.", "alice", json!({"speaker": "me"})).await?;
let mine = mem.engram("tone_stabilizer", "how do I usually answer?", "alice").await?;

curl -X POST https://api.wontopos.com/api/v1/engram/run \
  -H "X-API-Key: wos-live-..." -H "Content-Type: application/json" \
  -d '{"name":"tone_stabilizer","user_id":"alice","query":"how do I usually answer?"}'

{ "engram": "tone_stabilizer", "hops": 2, "count": 10,
  "memories": [ { "content": "I keep answers short unless you ask for detail.", "speaker": "me" }, ... ],
  "usage": { "input_tokens": 200, "output_tokens": 442 } }

Jeder Endpunkt, eine Basis-URL.

Kein SDK erforderlich - jeder HTTP-Client funktioniert. Basis-URL https://api.wontopos.com, Authentifizierung über den X-API-Key-Header, JSON rein und raus. Memory-Operationen sind POST; die Verwaltung von Stores nutzt POST / GET / DELETE auf /collection. Ein Store muss zuerst existieren (siehe Stores), sonst liefern Operationen im Store 404.

Header

Endpunkt

# create the store once (stores are explicit)
curl -X POST https://api.wontopos.com/api/v1/memory/collection \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice"}'

# store a memory
curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"she prefers tea over coffee"}'

# recall - one call, ready for your prompt
curl -X POST https://api.wontopos.com/api/v1/memory/recall \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what does alice drink?"}'

{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}

Dieselben Funktionen für alle.
Stufen erhöhen nur Ihre Limits.

Jede Stufe nutzt die vollständige Engine - dieselbe Recall-Qualität, dieselben Sprachen, jede Methode. Die Stufen steigen automatisch bis Stufe 5, während Ihre kumulierten Guthabenkäufe wachsen - ohne Antrag oder Vertriebsgespräch. Enterprise (Stufe 6) ist die einzige Ausnahme.

Ausgabenlimits

Jede Stufe begrenzt, wie viel Sie pro Kalendermonat ausgeben können. Sie steigen sofort auf, sobald Ihre kumulierten Guthabenkäufe die nächste Schwelle erreichen.

Rate-Limits

Rate-Limits gelten pro Konto - alle API-Schlüssel eines Kontos teilen sich ein Limit, das mit Ihrer Stufe skaliert. Bei Überschreitung kommt ein 429 mit einem retry-after-Header zurück; warten Sie gestaffelt (1s → 2s → 4s) und versuchen Sie es erneut. Jeder Endpunkt ist idempotenzfreundlich, Wiederholungen sind also sicher.

Enterprise (Stufe 6) erhält individuelle Rate-Limits, ein SLA, dedizierten Support und optional eine Self-Host-Lizenz - sprechen Sie mit uns.

Kostenlose Aufrufe

Ein paar Endpunkte kosten überhaupt nichts - sie sind unter Won zusammengefasst. Statt eines Preises haben sie zwei Limits.

• 10 Anfragen pro Minute, pro Endpunkt. Jeder kostenlose Endpunkt hat seinen eigenen Bucket, das Verbrauchen des einen verbraucht also nicht den anderen.
• 300 Anfragen pro Stunde, gemeinsam. Alle kostenlosen Endpunkte schöpfen aus einem Stundenkontingent pro Konto.

Beides wird im normalen Betrieb nicht erreicht, und beides berührt die oben genannten kostenpflichtigen Limits nicht.

Wenn etwas schiefgeht.

Fehler kommen als JSON-Umschlag zurück, mit einem stabilen type, einer menschenlesbaren Meldung und einer request_id, die Sie uns bei der Meldung eines Problems mitschicken können.

{"type": "error", "error": {
   "type": "authentication_error",
   "message": "Invalid or revoked API key.",
   "request_id": "063f8b83-eee2-4383-a5cf-11e4bcd29d7c"
 }}

Jeder Fehler ist ein WosError, und jeder Status hat zusätzlich eine eigene Klasse - BadRequestError, AuthenticationError, PaymentRequiredError, NotFoundError, ConflictError, RateLimitError, ServerError, APIConnectionError. Fangen Sie die ab, die Sie behandeln wollen, statt Zahlen zu vergleichen.

# SDK error handling (Python)
from wontopos import Client, WosError, RateLimitError, PaymentRequiredError

try:
    mem.search("...", user_id="alice")
except PaymentRequiredError: ...      # 402 - top up
except RateLimitError: ...            # 429 - the SDK already retried; slow down
except WosError as e: ...            # e.status, e.message, e.request_id
except (ValueError, TypeError): ...    # never left the client

Manche Fehler erreichen uns nie. Der API-Schlüssel, die Store-id, der Idempotenzschlüssel und das Bild werden alle geprüft, bevor die Anfrage hinausgeht, und dabei wird ValueError oder TypeError ausgelöst - nicht WosError. Ein except WosError allein fängt sie nicht ab.

Rate-Limits gelten pro Konto, geteilt über alle Ihre Schlüssel, und skalieren mit Ihrer Stufe - siehe Nutzungsstufen. Die Nutzung Ihres Kontos sehen Sie in der Konsole.

lineage

Die Kette der Änderungen hinter einer Erinnerung, älteste zuerst. revisions gibt an, wie stark sich ein Store verändert hat; dies gibt an, was mit einer einzelnen Tatsache geschehen ist.

Übergeben Sie die ID einer beliebigen Erinnerung in der Kette. Ersetzte Versionen werden aufbewahrt statt gelöscht, sodass eine Suche, die nur die aktuelle Tatsache zurückgibt, weiterhin zurückverfolgt werden kann.

chain = mem.lineage(memory_id=mid)["chain"]
for step in chain:
    print(step["changed_at"], step["action"], step["content"])

const { chain } = await mem.lineage(undefined, mid);
for (const step of chain) {
  console.log(step.changed_at, step.action, step.content);
}

let r = mem.lineage(None, mid).await?;
for step in r["chain"].as_array().unwrap_or(&vec![]) {
    println!("{} {} {}", step["changed_at"], step["action"], step["content"]);
}

curl -X POST https://api.wontopos.com/api/v1/memory/lineage \
  -H "X-API-Key: $WOS_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","memory_id":"m_9"}'

{ "memory_id": "m_9", "count": 3, "truncated": false,
  "chain": [
    { "memory_id": "m_3", "content": "lives in Seoul",
      "created_at": "2026-03-02T…", "changed_at": "2026-06-11T…",
      "action": "replaced", "confidence": 0.94,
      "superseded_by": "m_7", "is_current": false },
    { "memory_id": "m_7", "content": "moved to Busan",   … },
    { "memory_id": "m_9", "content": "Haeundae, specifically",
      "changed_at": null, "superseded_by": null, "is_current": true }
  ] }

Wofür es gedacht ist

Zwei Anwendungsfälle. Debugging: warum eine Erinnerung heute so lautet, wie sie lautet. Und einem Assistenten den Blick auf seine eigene Historie zu ermöglichen - eine dreimal korrigierte Tatsache ist eine andere Art von Tatsache als eine einmal geschriebene, und nur die Kette zeigt das.

Won ist für diejenigen gedacht, die die Erinnerung lesen.

Der größte Teil dieser API antwortet mit Erinnerung. Won antwortet über sie: wie viel von einem Store neu geschrieben wurde und wie weit man ihm vertrauen kann. Gedacht ist das für die lesende Seite, meist für den Assistenten, den Sie bauen, und nicht für die Person, von der die Erinnerungen handeln.

Wontopos ist Won + Topos, ein Ort, an dem Erinnerung wohnt. Won ist der Teil dieses Ortes, der über die Erinnerung Auskunft gibt, statt sie zurückzugeben. Diese Aufrufe sind kostenlos, nur lesend, und rühren den Abruf nie an: Das Fragen kostet Ihre Nutzer nichts und ändert nichts an dem, was gespeichert ist.

Was es heute umfasst

Heute ein Aufruf.

Ein durchgerechnetes Beispiel

Verwenden Sie das Verhältnis, nicht die absolute Zahl. 3 von 40 und 30 von 40 erfordern eine unterschiedliche Behandlung.

r = mem.revisions()
# {"revised": 3, "total": 40, "counts": "…", "excludes": "…"}

if r["revised"] / r["total"] > 0.1:
    system += "Some of what you remember here has been corrected since."

const r = await mem.revisions();
// { revised: 3, total: 40, counts: "…", excludes: "…" }

if (r.revised / r.total > 0.1) {
  system += "Some of what you remember here has been corrected since.";
}

let r = mem.revisions(None).await?;
let (rev, tot) = (r["revised"].as_f64().unwrap_or(0.0),
                r["total"].as_f64().unwrap_or(1.0));
if rev / tot > 0.1 { /* say so in the system prompt */ }

curl -X POST https://api.wontopos.com/api/v1/won/revisions \
  -H "X-API-Key: $WOS_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice"}'

# → {"user_id":"alice","revised":3,"total":40,
#     "counts":"memories a transform has touched (supersede, update, retract, image removed)",
#     "excludes":"deletions — a deleted memory leaves nothing to count"}

counts und excludes werden als Sätze zurückgegeben, nicht als Flags, da der Aufrufer oft ein Modell ist. Löschungen werden nicht gezählt.

Preis und Limits

Beide Obergrenzen antworten mit 429 und Retry-After in Sekunden sowie einer Meldung, die nennt, welche davon erreicht wurde.

Retry-After: 41

{ "error": { "type": "rate_limit_error",
    "message": "This endpoint is free and limited to 10 requests per
                minute, counted per endpoint. Retry in 41s." } }

Wie viel von einem Store neu geschrieben wurde

revisions antwortet mit revised von total: wie viele Erinnerungen in einem Store nach dem Schreiben verändert wurden. Es lohnt sich, danach zu fragen, bevor Sie sich bei etwas Wichtigem auf das Gedächtnis stützen, oder wenn ein abgerufener Fakt nicht zu dem passt, was der Nutzer gerade sagt. Ein Store, in dem drei von zehn Fakten ersetzt wurden, verdient weniger Vertrauen als einer, den niemand bearbeitet hat.

Anzahlen

Gezählt wird, was eine Transformation berührt hat - ersetzt, aktualisiert, zurückgezogen sowie entfernte Bilder.

mem.revisions()
# {"revised": 3, "unrevised": 37, "total": 40, …}

await mem.revisions();

mem.revisions(None).await?;

curl -X POST https://api.wontopos.com/api/v1/won/revisions \
  -H "X-API-Key: $WOS_KEY" -d '{"user_id":"alice"}'

Die Liste lesen

Übergeben Sie include, um die Erinnerungen selbst zu erhalten, nicht nur deren Anzahl. Ohne diesen Parameter erhalten Sie nur die Zählwerte, was der günstige Aufruf ist.

page = mem.revisions(include="revised", limit=20)
page["memories"], page["matched"], page["has_more"]

const page = await mem.revisions(undefined, { include: "revised", limit: 20 });

let page = mem.revisions_page(None, "revised", 20, None, None).await?;

curl -X POST https://api.wontopos.com/api/v1/won/revisions \
  -H "X-API-Key: $WOS_KEY" \
  -d '{"user_id":"alice","include":"revised","limit":20}'

Jenseits des Kontextfensters.

WOS ruft aus Historien von 1.4M Tokens ab - weit größer als jedes LLM-Kontextfenster - und liefert dennoch einen kompakten Ausschnitt von ~1.470 Tokens zurück.

Das Gedächtnis Ihres Agenten ist nicht dadurch begrenzt, was in einen Prompt passt. Es behält alles und ruft nur das Wesentliche ab, egal wie groß die Historie wird.

Privat, und Ihr Eigentum.

Ihre Daten bleiben in Ihrem Store. Wir trainieren nie darauf, sehen sie nicht ein und verwenden sie nicht weiter - wir organisieren sie nur, damit Sie sie abrufen können.

• BYOK. Ihr LLM-Schlüssel wird pro Anfrage gesendet und nie gespeichert.
• Isoliert. Erinnerungen sind pro Konto und darin pro user_id abgegrenzt.
• DSGVO-Löschung & Self-Hosting. Ein Aufruf löscht einen Nutzer vollständig; auf Wunsch betreiben Sie die Engine in Ihrer eigenen Umgebung.