Metadata-Version: 2.4
Name: wontopos
Version: 2.0.0
Summary: Wontopos — long-term memory for AI agents. Pure semantic retrieval, identical recall in every language, ~100× lower LLM bill.
Author: Wontopos
License: MIT
Project-URL: Homepage, https://wontopos.com
Project-URL: Documentation, https://wontopos.com/why
Project-URL: Repository, https://github.com/Irina1920/Wos_API
Project-URL: Issues, https://github.com/Irina1920/Wos_API/issues
Keywords: memory,ai,agent,llm,vector,embedding,semantic,rag,context
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Dynamic: license-file

# Wontopos — long-term memory for AI agents

```bash
pip install wontopos
```

```python
from wontopos import Client

mem = Client(api_key="wos-...")
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

| Method | Purpose |
|---|---|
| `add(content, user_id, **metadata)` | Store one memory |
| `add_turn(user_id, user_msg, assistant_msg)` | Store a conversation exchange |
| `add_bulk(content, user_id, category=, timestamp=)` | Backfill a long history |
| `update(user_id, old_memory_id, new_content)` | Supersede an old fact |
| `search(query, user_id, limit=10, **opts)` | Semantic search |
| `recall(query, user_id)` | One-call context (short + long + surrounding) |
| `history(user_id)` | Recent turns (short-term) |
| `stats(user_id)` | Counts |
| `delete(user_id, memory_id)` | Delete one memory |
| `delete_all(user_id)` | GDPR erase (delete every memory for the user) |

All methods take a `user_id` — memories are isolated per user, then per account (your API key).

## Errors

Any non-2xx response raises `WosError(status, message)`:

```python
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")
    else:
        print(e.status, e.message)
```

## Self-host

Point at your own engine:

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

## Links

- Homepage: <https://wontopos.com>
- API reference: <https://wontopos.com/why> (Developers tab)
- Repo: <https://github.com/Irina1920/Wos_API>

License: MIT.
