Metadata-Version: 2.4
Name: vaas-x
Version: 0.1.14
Summary: Persistent, outcome-grounded episodic memory for AI agents and connected devices -- zero-config ingestion, CPU-only retrieval, no vector database to run yourself.
Author-email: VAAS-X Ltd <hello@vaasx.com>
License: Proprietary -- see LICENSE
Project-URL: Homepage, https://vaasx.com
Project-URL: Documentation, https://vaasx.com/docs
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Provides-Extra: websocket
Requires-Dist: websockets>=12.0; extra == "websocket"
Provides-Extra: mqtt
Requires-Dist: paho-mqtt>=2.0; extra == "mqtt"
Provides-Extra: dataframe
Requires-Dist: pandas>=2.0; extra == "dataframe"
Provides-Extra: ac
Requires-Dist: torch>=2.0; extra == "ac"
Requires-Dist: torchvision>=0.18; extra == "ac"
Requires-Dist: torchaudio>=2.0; extra == "ac"
Requires-Dist: sentence-transformers>=3.0; extra == "ac"
Requires-Dist: pillow>=10.0; extra == "ac"
Provides-Extra: assistant
Requires-Dist: numpy>=1.24; extra == "assistant"
Requires-Dist: scikit-learn>=1.3; extra == "assistant"
Requires-Dist: llama-cpp-python>=0.2.90; extra == "assistant"

# vaas-x

Episodic memory that persists, for AI agents and connected devices. It keeps what happened, what was done and how it turned out, and brings back what worked.

`pip install vaas-x` gives any device or agent a persistent, queryable
record of what it has seen: what happened, what it did, what the outcome
was. It retrieves the closest matching past episode in milliseconds, on
CPU, with no cloud round-trip required for the actual similarity search.

## Install

```bash
pip install vaas-x
```

Get a free API key at [vaasx.com](https://vaasx.com): an email address, no card.

## Quickstart

```python
from vaasx import Bootstrap

brain = Bootstrap(api_key="...", device_id="my_device")

# Point it at a structured data stream (sensor readings, agent actions,
# API events: anything JSON-shaped) and it profiles the stream
# automatically, no schema design required.
brain.connect("https://your-data-stream.com/events")

# Query for the most similar past episodes, ranked by what actually
# worked, not just what is nearest in vector space.
hits = brain.query("engine running hot", k=5, prefer_success=True)
```

An agent that already knows its own outcome the moment it acts can log a
full state/action/outcome episode in one call instead of a separate
ingest-then-tag-later round trip:

```python
resp = brain.ingest([{
    "state": {"observation": observation},
    "action": {"taken": action},
    "outcome": {"success": result.success},
}])
episode_id = resp["episode_ids"][0]
```

## Prefer no code? Use the connector

If you use Claude, Cursor, VS Code or another agent that supports MCP, you
do not need this package. Add `https://mcp.vaasx.com/mcp` as a remote MCP
server and the agent gets the same memory, with no key to paste. Whether an
agent uses its memory without being asked depends on the agent. You can see
and manage everything it remembers at [app.vaasx.com](https://app.vaasx.com)
(sign in with an emailed code).

## Rate limits

The service limits how many requests one key can make in a minute (60 on Free, more on paid plans). When a request is refused for that reason, the SDK waits and tries again, for up to about a minute in total, before it raises an error. A request refused because your plan's note limit is full is never retried. Use `Bootstrap(..., max_retries=0)` to fail at once.

## What it does

- Profiles a raw data stream automatically: statistical profiling,
  schema classification and anomaly detection all run locally before
  anything touches the network.
- Stores episodes as (state, action, outcome) triples, so retrieval can be
  weighted toward what worked last time in a similar situation, not just
  nearest by embedding distance.
- Runs on both a small edge device and a standard server: same codebase,
  no domain-specific build.

## When files stop being enough

If one agent on one machine is all you have, a markdown file is a fine
place to start. A memory service earns its place when several agents need
the same memory, when facts change mid-project, and when you want recall
ranked by what worked. Every published result has a reproduction guide you
can run yourself: [vaasx.com/guides](https://vaasx.com/guides/index.html).
Comparisons: [Mem0](https://vaasx.com/vs-mem0.html),
[Supermemory](https://vaasx.com/vs-supermemory.html),
[a vector database](https://vaasx.com/vs-vector-database.html).

## Tiers

Free gets you an API key instantly (10,000 episodes, 500 queries a day,
1 device). Personal (£9.99 a month) adds the app, 50,000 notes, unlimited
searches and 3 devices. Developer and Professional are self-serve SDK
tiers with higher episode and device limits. Enterprise is contract-based,
for teams wanting on-prem or air-gapped deployment. See
[vaasx.com/pricing](https://vaasx.com/pricing) for current details.

## The honest caveat

This package ships as a compiled wheel, not source-available. The
retrieval and indexing internals are proprietary and protected as a trade
secret, not through patent filing. What *is* open: full API documentation,
working examples, and the wire format, so you can see exactly what goes in
and comes back even without reading the internals.

Multimodal support (vision/audio/depth/thermal, via the optional `ac`
extra) is real but still early: encoder models are in active training
and not yet production-tuned; treat it as a preview, not a finished
feature.

## Links

- [Documentation](https://vaasx.com/docs)
- [Homepage](https://vaasx.com)

## License

Proprietary -- see `LICENSE`.
