Storage

Defined in: src/storage/storage.ts:93

A backend for storing and retrieving raw bytes under string keys.

The interface is deliberately minimal — four operations over opaque Uint8Array values. Keys are opaque strings — implementations must round-trip the bytes they are given unchanged. The shipped backends interpret / as a logical separator (collapsing runs, rejecting ..), but custom backends may apply their own key scheme.

The ListQuery type parameter controls what list accepts. It defaults to string (a key prefix), which every backend supports. Implementations may widen it to accept a richer query object (e.g. a DynamoDB partition/sort-key filter) while still accepting a plain string for SDK-internal callers.

The SearchQuery type parameter controls what search accepts. It defaults to string (a natural-language query), which every backend interprets in its own way (keyword scan, vector similarity, full-text index). Implementations may widen it to accept a richer query object (e.g. a pre-computed embedding vector with filters).

Implement this to add a custom backend; the SDK ships InMemoryStorage, LocalFileStorage, and S3Storage.

Type Parameters

Type Parameter	Default type
ListQuery	string
SearchQuery	string

Methods

write()

write(key, data): Promise<void>;

Defined in: src/storage/storage.ts:101

Stores data under key, overwriting any existing value.

Parameters

Parameter	Type	Description
key	string	Opaque string key identifying the value
data	Uint8Array	Raw bytes to persist

Returns

Promise<void>

Throws

StorageError if the write fails

---

read()

read(key): Promise<Uint8Array<ArrayBufferLike>>;

Defined in: src/storage/storage.ts:110

Retrieves the bytes previously stored under key.

Parameters

Parameter	Type	Description
key	string	The key to read

Returns

Promise<Uint8Array<ArrayBufferLike>>

The stored bytes, or null if no value exists for key

Throws

StorageError if the read fails for a reason other than a missing key

---

delete()

delete(key): Promise<void>;

Defined in: src/storage/storage.ts:118

Deletes the value stored under key. A no-op if the key does not exist.

Parameters

Parameter	Type	Description
key	string	The key to delete

Returns

Promise<void>

Throws

StorageError if the delete fails

---

list()

list(query): Promise<string[]>;

Defined in: src/storage/storage.ts:134

Lists keys matching the given query.

When ListQuery is string (the default), this is a prefix match — returns full keys (not the suffix after the prefix), sorted lexicographically. An empty string lists every key.

Implementations may accept richer query objects (e.g. partition + sort-key filters) while still supporting a plain string prefix for SDK-internal callers.

Parameters

Parameter	Type	Description
query	ListQuery	A string prefix or backend-specific query object

Returns

Promise<string[]>

The matching keys, sorted ascending

Throws

StorageError if the listing fails

---

namespace()?

optional namespace(prefix): Storage;

Defined in: src/storage/storage.ts:145

Returns a view of this storage with all keys prefixed by prefix. The original storage is not mutated.

Optional — shipped backends implement this, custom backends may omit it.

Parameters

Parameter	Type	Description
prefix	string	Prefix to prepend to all keys

Returns

Storage

A Storage view scoped to the given prefix

---

search()?

optional search(query): Promise<StorageSearchResult[]>;

Defined in: src/storage/storage.ts:162

Searches stored content by query.

When SearchQuery is string (the default), the query is a natural-language string and how it is interpreted is backend-specific: keyword/lexical scan, full-text index, or vector similarity (the backend embeds the query internally).

Implementations may accept richer query objects (e.g. a pre-computed embedding vector with metadata filters) while still accepting a plain string for SDK-internal callers.

Optional — when absent, consumers fall back to client-side search.

Parameters

Parameter	Type	Description
query	SearchQuery	A string query or backend-specific query object

Returns

Promise<StorageSearchResult[]>

Matched keys with relevance scores, ranked best-first