Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.circuit.org/llms.txt

Use this file to discover all available pages before exploring further.

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
IsolationEach session has its own keyspaceAccessible across all sessions of the same agent
LifetimeCleared when the session endsPersists independently of any session
Use whenTracking per-session state (cycle counters, last-run timestamps)Storing learned configuration, cross-session counters, shared lookup data
ConcurrencySingle session — no conflictsLast-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
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)

​
Get Value

Retrieve a value by key. 
def get(key: str, shared: bool = False) -> MemoryGetResponse
Parameters:
  • key (string): The key to retrieve
  • shared / options.shared (boolean, optional): If true, read from shared memory
Response:
  • success (boolean): Whether the operation succeeded
  • data.key (string): The requested key (on success)
  • data.value (string): The stored value (on success)
  • data.updatedAt (number): Unix timestamp in seconds of when the value was last written — accessed as data.updated_at in Python (on success)
  • error (string | null): Error message if key not found
Example: 
# Session memory (default)
result = agent.memory.get("lastSwapNetwork")
if result.success and result.data:
    agent.log(f"Network: {result.data.value}")

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

​
Delete Value

Remove a key-value pair. 
def delete(key: str, shared: bool = False) -> 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)

​
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
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)

​
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 (R2). Reads and writes have low but non-zero latency — avoid calling memory methods in tight loops.
  • For tracking position changes within an execution cycle, memory is often more reliable than polling getCurrentPositions(). See Positions for details.

​
See Also

  • Positions — Use memory to track position deltas instead of polling
  • Execution Model — How the run loop and session lifecycle work