Memory

Use memory to persist state between run cycles - for example, storing the last rebalance timestamp to avoid trading too frequently, tracking cumulative PnL, or caching external API responses. Access memory methods via agent.memory.

Shared vs Session Memory

Memory supports two scopes:

	Session (default)	Shared
Isolation	Each session has its own keyspace	Accessible across all sessions of the same agent
Lifetime	Cleared when the session ends	Persists independently of any session
Use when	Tracking per-session state (cycle counters, last-run timestamps)	Storing learned configuration, cross-session counters, shared lookup data
Concurrency	Single session - no conflicts	Last-write-wins across concurrent sessions

Pass { shared: true } (TypeScript) or shared=True (Python) to any memory method to use shared scope. Omitting the option defaults to session scope.

Set Value

Store a key-value pair.

def set(key: str, value: str, shared: bool = False) -> MemorySetResponse

async set(key: string, value: string, options?: { shared?: boolean }): Promise<MemorySetResponse>

Parameters:

key (string): Unique identifier (1-255 characters)
value (string): String value to store
shared / options.shared (boolean, optional): If true, store in shared memory

Response:

success (boolean): Whether the operation succeeded
data.key (string): The key that was set (on success)
error (string | null): Error message (on failure)

Example:

# Session memory (default)
result = agent.memory.set("lastSwapNetwork", "ethereum:42161")
if result.success and result.data:
    agent.log(f"Stored: {result.data.key}")

# Shared memory (accessible across sessions)
agent.memory.set("preferredSlippage", "0.5", shared=True)

// Session memory (default)
const result = await agent.memory.set("lastSwapNetwork", "ethereum:42161");
if (result.success && result.data) {
  await agent.log(`Stored: ${result.data.key}`);
}

// Shared memory (accessible across sessions)
await agent.memory.set("preferredSlippage", "0.5", { shared: true });

Get Value

Retrieve a value by key.

def get(key: str, shared: bool = False) -> MemoryGetResponse

async get(key: string, options?: { shared?: boolean }): Promise<MemoryGetResponse>

Parameters:

key (string): The key to retrieve
shared / options.shared (boolean, optional): If true, read from shared memory

Response:

success (boolean): Whether the lookup ran (true even when the key is not set)
data.key (string): The requested key
data.value (string | null): The stored value, or null if the key is not set
data.updatedAt (number | null): Unix timestamp in seconds of the last write, or null if the key is not set - accessed as data.updated_at in Python
error (string | null): Error message on a real failure (auth, bad scope, store unavailable)

A missing key is not an error: the lookup returns success: true with data.value: null. Check value for null / None to detect a miss - success: false means the lookup itself failed. Example:

# Session memory (default)
result = agent.memory.get("lastSwapNetwork")
if result.data and result.data.value is not None:
    agent.log(f"Network: {result.data.value}")
else:
    agent.log("No saved network yet")

# Shared memory
result = agent.memory.get("preferredSlippage", shared=True)

// Session memory (default)
const result = await agent.memory.get("lastSwapNetwork");
if (result.data?.value != null) {
  await agent.log(`Network: ${result.data.value}`);
} else {
  await agent.log("No saved network yet");
}

// Shared memory
const result = await agent.memory.get("preferredSlippage", { shared: true });

Delete Value

Remove a key-value pair.

def delete(key: str, shared: bool = False) -> MemoryDeleteResponse

async delete(key: string, options?: { shared?: boolean }): Promise<MemoryDeleteResponse>

Parameters:

key (string): The key to delete
shared / options.shared (boolean, optional): If true, delete from shared memory

Response:

success (boolean): Whether the operation succeeded
data.key (string): The deleted key (on success)
error (string | null): Error message (on failure)

Note: Succeeds even if the key doesn’t exist. Example:

# Session memory (default)
agent.memory.delete("tempSwapQuote")

# Shared memory
agent.memory.delete("preferredSlippage", shared=True)

// Session memory (default)
await agent.memory.delete("tempSwapQuote");

// Shared memory
await agent.memory.delete("preferredSlippage", { shared: true });

List Keys

Enumerate keys in the current scope, optionally filtered by a prefix. Results are returned in lexicographic ascending order.

def list(
    prefix: Optional[str] = None,
    shared: bool = False,
) -> MemoryListResponse

async list(
  options?: { prefix?: string; shared?: boolean },
): Promise<MemoryListResponse>

Parameters:

prefix (string, optional): Only return keys that start with this prefix
shared / options.shared (boolean, optional): If true, list shared-scope keys

TypeScript-specific constraint: If you pass an options object, at least one of prefix or shared must be present - agent.memory.list({}) is a type error. Call agent.memory.list() with no argument for the default session-scoped enumeration. Response:

success (boolean): Whether the operation succeeded
data.items ({ key, updatedAt }[] / list[MemoryListItem]): Matching keys with last-updated timestamps (on success)
error (string | null): Error message (on failure)

Ordering: Keys are returned in lexicographic ascending order. Result limit: list() returns at most 1000 items per call. If you expect to manage more than 1000 keys in a single scope, use a more granular prefix to scope the result, or restructure how you store state. Example:

# Session keys (default)
result = agent.memory.list()
if result.success and result.data:
    for item in result.data.items:
        agent.log(f"{item.key} (updated {item.updated_at})")

# Filter by prefix
result = agent.memory.list(prefix="lastSwap")

# Shared scope
result = agent.memory.list(shared=True)

// Session keys (default)
const result = await agent.memory.list();
if (result.success && result.data) {
  for (const item of result.data.items) {
    await agent.log(`${item.key} (updated ${item.updatedAt})`);
  }
}

// Filter by prefix
const prefixed = await agent.memory.list({ prefix: "lastSwap" });

// Shared scope
const sharedKeys = await agent.memory.list({ shared: true });

Notes

Values must be strings. Serialize complex data (JSON, numbers) before storing.
Keys must be 1-255 characters.
Session and shared memory are completely separate namespaces - the same key name can exist in both without collision.
Session memory persists across execution cycles within the same session and is cleared when the session ends.
Shared memory persists independently of any session and is accessible from all sessions of the same agent.
Shared memory uses last-write-wins concurrency - if two sessions write the same key simultaneously, the last write is kept.
delete() is idempotent - it succeeds even if the key does not exist.
API transport: The SDKs send a ?scope=shared or ?scope=session query parameter to the underlying REST endpoints. Valid values are "session" (default) and "shared". Invalid values return a 400 error.
Memory is backed by object storage. Reads and writes have low but non-zero latency - avoid calling memory methods in tight loops.
Do not mirror balances or position quantities in memory. Each new invocation receives them in agent.allocation; use memory only for strategy state. See Positions for details.

Getting Started

Core Concepts

Examples

CLI Reference

SDK Reference

Advanced

Shared vs Session Memory

Set Value

Get Value

Delete Value

List Keys

Notes

See Also

​Shared vs Session Memory

​Set Value

​Get Value

​Delete Value

​List Keys

​Notes

​See Also

Shared vs Session Memory

Set Value

Get Value

Delete Value

List Keys

Notes

See Also