From 0b9661ff6cb949809548e9aac1713820392a9723 Mon Sep 17 00:00:00 2001
From: re-pixel <relja.brdar@gmail.com>
Date: Fri, 26 Jun 2026 11:34:46 +0200
Subject: [PATCH] docs: document memory.findFirst and memory.find functions
 that can be used in expressions

---
 src/content/docs/concepts/canvas-memory.mdx   | 25 +++++++++++++++++++
 .../docs/concepts/expression-functions.md     |  2 ++
 src/content/docs/concepts/expressions.md      | 14 +++++++++++
 3 files changed, 41 insertions(+)

diff --git a/src/content/docs/concepts/canvas-memory.mdx b/src/content/docs/concepts/canvas-memory.mdx
index 72afd42..2404e2e 100644
--- a/src/content/docs/concepts/canvas-memory.mdx
+++ b/src/content/docs/concepts/canvas-memory.mdx
@@ -81,6 +81,31 @@ SuperPlane provides five memory components:
 
 See the [Components](/components/core) reference for field-level configuration.
 
+## Reading memory in expressions
+
+You can query memory directly in any expression field using `memory.find()` and `memory.findFirst()`, without adding a Read Memory node to the canvas.
+
+| Function | Returns |
+| -------- | ------- |
+| `memory.find(namespace, matches)` | All records in `namespace` whose fields contain `matches`. |
+| `memory.findFirst(namespace, matches)` | The first matching record, or `nil` if none. |
+
+`matches` is a JSON object — a record matches if its fields include all key-value pairs in the object.
+
+**Example — read a machine's status inline:**
+
+```
+{{memory.findFirst("machines", {"sandbox_id": $['Start'].data.sandbox_id}).status}}
+```
+
+**Example — check whether any machine is idle:**
+
+```
+memory.find("machines", {"status": "idle"}) != nil
+```
+
+Use `memory.findFirst()` when you expect a unique key and want a single value. Use `memory.find()` when you need all matches (for example, to pass the array to a downstream node or iterate over it).
+
 ## Manual memory entry and edits
 
 You don't have to rely solely on workflows to manage memory. You can manually view, add, edit, and delete records directly from the SuperPlane UI.
diff --git a/src/content/docs/concepts/expression-functions.md b/src/content/docs/concepts/expression-functions.md
index 3666baf..ed1db42 100644
--- a/src/content/docs/concepts/expression-functions.md
+++ b/src/content/docs/concepts/expression-functions.md
@@ -14,6 +14,8 @@ This page lists every function available in SuperPlane expressions. For an intro
 | `root()` | Root payload that started the run | `root().data.ref` |
 | `previous()` | Immediate upstream node's payload | `previous().data.status` |
 | `previous(n)` | Walk n levels upstream | `previous(2).data.version` |
+| `memory.find(namespace, matches)` | All [memory](/concepts/canvas-memory) records in `namespace` matching `matches` | `memory.find("machines", {"sandbox_id": "12121"})` |
+| `memory.findFirst(namespace, matches)` | First matching [memory](/concepts/canvas-memory) record, or `nil` | `memory.findFirst("machines", {"creator": "igor"}).sandbox_id` |
 
 ---
 
diff --git a/src/content/docs/concepts/expressions.md b/src/content/docs/concepts/expressions.md
index a71b0ea..51d69f0 100644
--- a/src/content/docs/concepts/expressions.md
+++ b/src/content/docs/concepts/expressions.md
@@ -41,6 +41,20 @@ Every entry also includes a **`.config`** property — the node's resolved confi
 
 `previous()` is not available when a node has multiple inputs (e.g. after a Merge). Use `$['Node Name']` instead.
 
+### `memory`
+
+The `memory` namespace lets you query [canvas memory](/concepts/canvas-memory) records directly in any expression, without adding a Read Memory node.
+
+| Function | Returns |
+| -------- | ------- |
+| `memory.find(namespace, matches)` | All records in `namespace` whose fields contain `matches`. |
+| `memory.findFirst(namespace, matches)` | The first matching record, or `nil` if none. |
+
+```
+{{memory.find("machines", {"sandbox_id": "12121"})}}
+{{memory.findFirst("machines", {"creator": "igor"}).sandbox_id}}
+```
+
 ---
 
 ## Syntax: text fields vs conditions