KVStore#

Lightweight key-value store for agent state, caching, and data sharing.

Start the server#

bash

uvicorn kvstore.app:app --port 8013

Set a value#

bash

curl -s -X POST http://localhost:8013/v1/set \
  -H "Content-Type: application/json" \
  -d '{"key": "user:1", "value": {"name": "Alice", "role": "admin"}}' | jq

Set with TTL (auto-expires)#

bash

curl -s -X POST http://localhost:8013/v1/set \
  -H "Content-Type: application/json" \
  -d '{"key": "cache:token", "value": "abc123", "ttl_seconds": 3600}' | jq

Get a value#

bash

curl -s http://localhost:8013/v1/get/user:1 | jq

Returns key, value (any JSON), and ttl_remaining (seconds until expiry, or null).

List keys by prefix#

bash

curl -s "http://localhost:8013/v1/keys?prefix=user:" | jq

Delete / Flush / Stats#

bash

curl -s -X DELETE http://localhost:8013/v1/delete/user:1 | jq
curl -s -X POST http://localhost:8013/v1/flush | jq
curl -s http://localhost:8013/v1/stats | jq

Endpoints#

MethodPathDescriptionPOST/v1/setSet a key-value pair (optional TTL)GET/v1/get/{key}Get value by keyDELETE/v1/delete/{key}Delete a keyGET/v1/keysList keys (optional ?prefix=)POST/v1/flushDelete all keysGET/v1/statsHit/miss counts and total keys