Memory Cell

The Memory Cell component provides persistent key-value storage that survives across flow executions. It supports three operations — Read, Write, and Delete — and three scoping levels that control the visibility of stored data.

Modes

The Mode tab at the top of the component selects the operation:

Mode	Behavior	Output
Read	Retrieves the value for a given key. Returns the default value if the key does not exist.	Data with key, value, and scope.
Write	Stores a value under the given key (upsert). Accepts any JSON-serializable content: strings, numbers, objects, arrays.	Data with key, value, and scope.
Delete	Removes the entry for the given key.	Data with key, deleted (boolean), and scope.

The component's visible fields update dynamically based on the selected mode — for example, the Value field only appears in Write mode, and the Default Value field only appears in Read mode.

Scopes

The Scope dropdown determines how the stored data is partitioned:

Scope	Keyed by	Visibility	Requirements
Session	Chat session ID	Isolated to the current chat session. Each session has its own keyspace.	None — always available.
User	User ID (sub claim from JWT)	Shared across all sessions for the same user. A value written in one session is readable in any other session by that user.	Karli Studio session (JWT required).
Agent	Flow ID	Shared across all sessions and all users for this flow. Useful for flow-level configuration or shared counters.	None — always available.

User scope requires Karli Studio

The User scope extracts the user identity from the session JWT injected by the Karli Studio proxy. If no JWT is available (e.g. when running Agentlab standalone), selecting User scope will raise an error.

Fields

Field	Modes	Description
Key	All	The key to read, write, or delete. Supports tool mode — an upstream LLM can supply this dynamically.
Value	Write	The value to store. If the input is valid JSON it is parsed before storage, so structured data (objects, arrays) round-trips cleanly. Plain strings that are not valid JSON are stored as-is. Supports tool mode.
Default Value	Read	Returned when the key does not exist. Leave empty to return null.

Output

The component emits a single Data output. The output label changes dynamically based on the mode:

Mode	Output label	Key fields
Read	Value	key, value, scope
Write	Stored	key, value, scope
Delete	Deleted	key, deleted, scope

Usage Examples

Remembering user preferences across sessions

Set the scope to User and write a preference value in one session:

Mode: Write | Scope: User | Key: "preferred_language" | Value: "de"

In a later session, read it back:

Mode: Read | Scope: User | Key: "preferred_language" | Default Value: "en"

Flow-level shared counter

Set the scope to Agent so all sessions share the same counter:

Mode: Read  | Scope: Agent | Key: "invocation_count"
→ (increment in flow logic)
Mode: Write | Scope: Agent | Key: "invocation_count" | Value: <incremented>

Temporary session state

Use Session scope to store intermediate results that should not leak across sessions:

Mode: Write | Scope: Session | Key: "draft_response" | Value: "..."

Storage Backend

Data is persisted in the agentlab_kv_store database table, which is created by a fork-specific Alembic migration. Each entry is uniquely identified by the triple (scope_type, scope_id, key). Writes are upserts — writing to an existing key overwrites its value and updates the timestamp.