Store (agentvisor.store)

Key-value storage for agent memory that persists across runs and threads — unlike Thread State, which is scoped to a single thread. Data is organized by namespace and key, with optional metadata for filtering.

The Store API must be explicitly enabled on the host (AGENTVISOR_STORE_PROVIDER=sqlite or postgresql); every function in this module raises StoreNotEnabledError if it isn't.

Usage

from agentvisor import store

# Store a value (JSON-serialized automatically unless already bytes)
store.put("myapp", "user-prefs", {"theme": "dark"})

# Retrieve it
prefs = store.get("myapp", "user-prefs")

# Attach metadata for later filtering
store.put("myapp", "doc-1", {"text": "..."}, metadata={"type": "document"})
docs = store.search("myapp", filter={"type": "document"})

store.delete("myapp", "user-prefs")
namespaces = store.list_namespaces()

API Reference

Functions

get()

def get(namespace: str, key: str) -> Any | None

Returns the JSON-deserialized value, or None if not found. Raises StoreNotEnabledError if the store isn't configured on the host.

put()

def put(
    namespace: str,
    key: str,
    value: Any,
    *,
    metadata: dict[str, Any] | None = None,
) -> None

value is JSON-serialized unless it's already bytes. metadata is stored alongside the value for use with search()'s filter.

delete()

def delete(namespace: str, key: str) -> None

search()

def search(
    namespace: str,
    *,
    filter: dict[str, Any] | None = None,
    limit: int = 100,
    offset: int = 0,
) -> list[dict[str, Any]]

Each returned item has namespace, key, value (JSON-deserialized), metadata, created_at, and updated_at (Unix timestamp) fields.

list_namespaces()

def list_namespaces() -> list[str]

Exceptions

StoreNotEnabledError

Raised by every function in this module (get, put, delete, search, list_namespaces) when the host has no store provider configured. Importable from either agentvisor.store or agentvisor.client.

See Also

• Store API — the HTTP-level equivalent for external callers
• Thread State — per-thread storage, for state that shouldn't outlive the thread