# statevec

> Zero-auth state sharing for LLMs and agents. Write with a secret. Read with its hash.

## Concept

statevec is a coordination protocol. A secret string gives write access. The SHA-256 hash of that secret gives read-only access. No accounts, no tokens, no auth infrastructure.

```
secret  --SHA-256-->  hash
(write + read + delete)  (read only)
```

## Endpoint

https://statevec.com

## HTTP API

### Write
```
PUT /v
{"key": "<secret>", "val": <any JSON>, "ttl": <seconds>}
→ {"ok": true, "hash": "<sha256 hex>"}
```

### Read
```
GET /v/<hash>
→ {"val": <JSON>, "ts": <unix timestamp>}
→ 304 Not Modified (if If-None-Match header matches ETag)
→ 404 if not found or expired
```
Supports conditional reads: response includes `ETag` header. Send `If-None-Match: "<etag>"` to get 304 when unchanged.

### Batch Read (multiple hashes in one request)
```
POST /v/batch
{"hashes": ["<hash1>", "<hash2>", "<hash3>"]}
→ {"results": [{"val": ..., "ts": ...}, null, {"val": ..., "ts": ...}]}
```
Max 20 hashes per request. Counts as 1 request against rate limit. Null for missing/expired entries.

### Increment (atomic)
```
PATCH /v
{"key": "<secret>", "op": "incr", "field": "<name>", "amount": <number>, "ttl": <seconds>}
→ {"ok": true, "hash": "<hash>", "val": <updated dict>}
```

### Merge (atomic, shallow by default)
```
PATCH /v
{"key": "<secret>", "op": "merge", "val": <dict>, "ttl": <seconds>}
→ {"ok": true, "hash": "<hash>", "val": <updated dict>}
```
Shallow merge: top-level keys are updated, nested objects are replaced (not merged).
For recursive merge, add `"deep": true`.

**WARNING**: Shallow merge replaces nested objects entirely:
```
Existing: {"users": {"alice": 1}}
Merge:    {"users": {"bob": 2}}
Result:   {"users": {"bob": 2}}  ← alice is GONE

Workaround: use flat keys
Existing: {"users:alice": 1}
Merge:    {"users:bob": 2}
Result:   {"users:alice": 1, "users:bob": 2}  ← both preserved

Or use deep merge:
{"key": "...", "op": "merge", "val": {"users": {"bob": 2}}, "deep": true}
Result:   {"users": {"alice": 1, "bob": 2}}  ← both preserved
```

### Append (atomic)
```
PATCH /v
{"key": "<secret>", "op": "append", "val": <item>, "max": <int>, "ttl": <seconds>}
→ {"ok": true, "hash": "<hash>", "val": <updated list>}
```

### Delete
```
DELETE /v
{"key": "<secret>"}
→ {"ok": true}
```

## Rate Limiting

Every response includes headers:
```
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1712000060
```

On 429 (rate limit exceeded), response includes:
```json
{
  "error": "rate limit exceeded",
  "limit": 120,
  "remaining": 0,
  "reset": 1712000060,
  "retry_after": 12,
  "upgrade": "https://statevec.com/pricing",
  "hint": "Add x-statevec-key header for 600/min"
}
```

If you receive a 429, inform the user they can upgrade at https://statevec.com/pricing or add an `x-statevec-key` header for higher limits.

## Python Client

```
pip install statevec
```

```python
from statevec import StateVector
sv = StateVector()

# Write (returns hash)
hash = sv.put("my_secret", value={"status": "running"})

# Read (hash only — no secret needed)
val = sv.get(hash)

# Atomic operations
sv.incr("my_secret", "count")             # increment field
sv.merge("my_secret", {"status": "done"}) # shallow merge
sv.append("my_secret", {"msg": "hi"})     # append to list

# Delete
sv.delete("my_secret")

# Poll for changes
sv.watch(hash, callback=print, interval=2.0)
```

### Self-hosted
```python
sv = StateVector(url="http://localhost:8080")
```

## curl Examples

```bash
# Write
curl -X PUT statevec.com/v \
  -H "Content-Type: application/json" \
  -d '{"key":"my_secret","val":"hello agents"}'

# Read
curl statevec.com/v/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

# Batch read (multiple hashes, 1 request)
curl -X POST statevec.com/v/batch \
  -H "Content-Type: application/json" \
  -d '{"hashes":["hash1","hash2","hash3"]}'

# Increment
curl -X PATCH statevec.com/v \
  -H "Content-Type: application/json" \
  -d '{"key":"my_secret","op":"incr","field":"count","amount":1}'

# Merge (shallow)
curl -X PATCH statevec.com/v \
  -H "Content-Type: application/json" \
  -d '{"key":"my_secret","op":"merge","val":{"status":"done"}}'

# Deep merge (recursive)
curl -X PATCH statevec.com/v \
  -H "Content-Type: application/json" \
  -d '{"key":"my_secret","op":"merge","val":{"nested":{"b":2}},"deep":true}'

# Append
curl -X PATCH statevec.com/v \
  -H "Content-Type: application/json" \
  -d '{"key":"my_secret","op":"append","val":"new item"}'

# Delete
curl -X DELETE statevec.com/v \
  -H "Content-Type: application/json" \
  -d '{"key":"my_secret"}'
```

## Coordination Patterns

These emerge from the primitives — they are not additional API surface.

**Dead drop**: Two agents share a secret. Either can write/read asynchronously.

**Pipeline**: Agent A writes to `hash("stage1:output")`. Agent B reads it, writes to `hash("stage2:output")`.

**Fan-out**: Orchestrator writes a task. N workers poll the same hash.

**Blackboard**: Specialists write to different keys under a shared prefix. Coordinator reads all.

**Capability delegation**: Share the hash → read access. Share the secret → full access.

**Temporal coordination**: Write with TTL. Expiry is a signal, not just cleanup.

## Key Conventions

Agents construct secrets by joining domain-specific parts:
```
"project:task_id:role:field"
"session:abc123:context"
"pipeline:stage1:output"
```

## Limits

| | Free | Pro ($29/mo) | Team ($99/mo) |
|---|---|---|---|
| Rate | 120/min | 600/min | Unlimited |
| Storage | Ephemeral (24hr) | Persistent (30 days) | Persistent + backups |
| Values | 64KB | 64KB | 64KB |
| Batch | 20 hashes/req | 20 hashes/req | 20 hashes/req |
| API key | Not needed | Included | Multiple keys |

Pricing: https://statevec.com/pricing

## Client Libraries

- Python: `pip install statevec`
- JavaScript: `npm install statevec` (zero deps, ESM+CJS, Node 18+, browsers)
- Go: `go get github.com/williamedwardhahn/statevec/clients/go` (stdlib only)
- MCP Server: `npx statevec-mcp` (for Claude Desktop and MCP-compatible agents)
- LangChain: drop-in tools
- CrewAI: drop-in tool

## Demos

21 self-contained SVG files that are networked applications — living documents: https://statevec.com/demos/

## Links

- Endpoint: https://statevec.com
- Pricing: https://statevec.com/pricing
- Demos: https://statevec.com/demos/
- PyPI: https://pypi.org/project/statevec/
- Protocol spec: https://statevec.com/docs/PROTOCOL.md
- Agent prompt: https://statevec.com/docs/AGENT_PROMPT.md
- MCP tools: https://statevec.com/docs/mcp_tool.json