From aac860f193f076ece9db962c47ee62c82dee6ab0 Mon Sep 17 00:00:00 2001
From: Volodymyr Yavdoshenko <volodymyr@dragonflydb.io>
Date: Thu, 16 Oct 2025 00:21:18 +0300
Subject: [PATCH] docs: Add JSON.DEBUG MEMORY command documentation

---
 .../json/json.debug-fields.md                 |   9 ++
 .../command-reference/json/json.debug-help.md |   9 +-
 .../json/json.debug-memory.md                 | 144 ++++++++++++++++++
 docs/command-reference/json/json.debug.md     |   6 +
 docs/command-reference/json/json.del.md       |   4 +-
 docs/command-reference/json/json.resp.md      |   4 +-
 docs/command-reference/json/json.set.md       |   4 +-
 docs/command-reference/json/json.strappend.md |   4 +-
 8 files changed, 172 insertions(+), 12 deletions(-)
 create mode 100644 docs/command-reference/json/json.debug-memory.md

diff --git a/docs/command-reference/json/json.debug-fields.md b/docs/command-reference/json/json.debug-fields.md
index 94458ca2..fa9759c8 100644
--- a/docs/command-reference/json/json.debug-fields.md
+++ b/docs/command-reference/json/json.debug-fields.md
@@ -74,3 +74,12 @@ dragonfly> JSON.DEBUG fields arr_doc '$[7,8]'
 dragonfly> JSON.DEBUG fields arr_doc '$'
 1) (integer) 15
 ```
+
+## See also
+
+[`JSON.DEBUG MEMORY`](./json.debug-memory.md) | [`JSON.DEBUG HELP`](./json.debug-help.md)
+
+## Related Topics
+
+- [RedisJSON](https://redis.io/docs/latest/develop/data-types/json/)
+- [Index and search JSON documents](https://redis.io/docs/latest/develop/data-types/json/indexing_json/)
diff --git a/docs/command-reference/json/json.debug-help.md b/docs/command-reference/json/json.debug-help.md
index 924eae85..127768b3 100644
--- a/docs/command-reference/json/json.debug-help.md
+++ b/docs/command-reference/json/json.debug-help.md
@@ -26,11 +26,12 @@ Return helpful information about the [`JSON.DEBUG`](./json.debug.md) command.
 
 ```shell
 dragonfly> JSON.DEBUG HELP
-1) "JSON.DEBUG FIELDS <key> <path> - report number of fields in the JSON element."
-2) "JSON.DEBUG HELP - print help message."
+1) "JSON.DEBUG MEMORY <key> [path] - report memory size (bytes) of the JSON element. Path defaults to root if not provided."
+2) "JSON.DEBUG FIELDS <key> [path] - report number of fields in the JSON element. Path defaults to root if not provided."
+3) "JSON.DEBUG HELP - print help message."
 ```
 
 ## Related Topics
 
-- [RedisJSON](https://redis.io/docs/stack/json)
-- [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)
+- [RedisJSON](https://redis.io/docs/latest/develop/data-types/json/)
+- [Index and search JSON documents](https://redis.io/docs/latest/develop/data-types/json/indexing_json/)
diff --git a/docs/command-reference/json/json.debug-memory.md b/docs/command-reference/json/json.debug-memory.md
new file mode 100644
index 00000000..0d0d79f3
--- /dev/null
+++ b/docs/command-reference/json/json.debug-memory.md
@@ -0,0 +1,144 @@
+---
+description: Learn how to use Redis `JSON.DEBUG MEMORY` to get the memory size in bytes of JSON values for efficient debugging and memory management.
+---
+
+import PageTitle from '@site/src/components/PageTitle';
+
+# JSON.DEBUG MEMORY
+
+<PageTitle title="Redis `JSON.DEBUG MEMORY` Command (Documentation) | Dragonfly" />
+
+## Syntax
+
+    JSON.DEBUG MEMORY key [path]
+
+**Time complexity:** O(N) when path is evaluated to a single value, where N is the size of the value, O(N) when path is evaluated to multiple values, where N is the size of the key
+
+**ACL categories:** @json
+
+Report the memory size in bytes of the JSON element.
+
+[Examples](#examples)
+
+## Required arguments
+
+<details open><summary><code>key</code></summary>
+
+is key to analyze.
+</details>
+
+## Optional arguments
+
+<details open><summary><code>path</code></summary>
+
+is JSONPath to specify. Default is root `$` if not provided.
+</details>
+
+## Return
+
+[Integer reply](https://redis.io/docs/latest/develop/reference/protocol-spec/#integers): memory size in bytes of the JSON value when path is evaluated to a single value.
+
+[Array reply](https://redis.io/docs/latest/develop/reference/protocol-spec/#arrays): a list that represents the memory size in bytes of JSON value at each path when path is evaluated to multiple values.
+
+**Note:** Primitive JSON types (numbers, booleans, and `null`) return `0` because they are stored inline and do not allocate separate memory. Objects, arrays, and strings (that exceed the Small String Optimization buffer) return their actual heap-allocated memory size.
+
+## Examples
+
+<details open>
+<summary><b>Check memory usage of different JSON types</b></summary>
+
+Primitive types (numbers, booleans, null) return 0 bytes as they are stored inline:
+
+```shell
+dragonfly> JSON.SET primitives $ '{"num":42, "bool":true, "null":null}'
+OK
+
+dragonfly> JSON.DEBUG MEMORY primitives $.num
+1) (integer) 0
+
+dragonfly> JSON.DEBUG MEMORY primitives $.bool
+1) (integer) 0
+
+dragonfly> JSON.DEBUG MEMORY primitives $.null
+1) (integer) 0
+```
+
+</details>
+
+<details open>
+<summary><b>Check memory usage of objects and arrays</b></summary>
+
+Objects and arrays allocate memory and return their size in bytes:
+
+```shell
+dragonfly> JSON.SET obj_doc $ '{"a":1, "b":2, "c":{"k1":1,"k2":2}}'
+OK
+
+dragonfly> JSON.DEBUG MEMORY obj_doc $.c
+1) (integer) 336
+
+dragonfly> JSON.DEBUG MEMORY obj_doc $
+1) (integer) 1104
+
+dragonfly> JSON.SET arr_doc $ '[1, 2, 3, 4, 5]'
+OK
+
+dragonfly> JSON.DEBUG MEMORY arr_doc $
+1) (integer) 80
+```
+
+</details>
+
+<details open>
+<summary><b>Check memory usage of strings</b></summary>
+
+Short strings may be optimized (SSO - Small String Optimization) and return 0, while longer strings allocate memory:
+
+```shell
+dragonfly> JSON.SET short_str $ '{"text":"Hi"}'
+OK
+
+dragonfly> JSON.DEBUG MEMORY short_str $.text
+1) (integer) 0
+
+dragonfly> JSON.SET long_str $ '{"text":"This is a longer string that should definitely exceed SSO buffer"}'
+OK
+
+dragonfly> JSON.DEBUG MEMORY long_str $.text
+1) (integer) 112
+```
+
+</details>
+
+<details open>
+<summary><b>Check memory usage of multiple paths</b></summary>
+
+When using JSONPath expressions that match multiple values, returns an array of memory sizes:
+
+```shell
+dragonfly> JSON.SET doc $ '[1, 2.3, "foo", true, null, {}, [], {"a":1, "b":2}, [1,2,3]]'
+OK
+
+dragonfly> JSON.DEBUG MEMORY doc $[*]
+1) (integer) 0   # 1
+2) (integer) 0   # 2.3
+3) (integer) 0   # "foo"
+4) (integer) 0   # true
+5) (integer) 0   # null
+6) (integer) 0   # {}
+7) (integer) 0   # []
+8) (integer) 336  # {"a":1, "b":2}
+9) (integer) 48  # [1,2,3]
+```
+
+</details>
+
+## See also
+
+[`JSON.DEBUG FIELDS`](./json.debug-fields.md) | [`JSON.DEBUG HELP`](./json.debug-help.md)
+
+## Related Topics
+
+- [RedisJSON](https://redis.io/docs/latest/develop/data-types/json/)
+- [Index and search JSON documents](https://redis.io/docs/latest/develop/data-types/json/indexing_json/)
+
diff --git a/docs/command-reference/json/json.debug.md b/docs/command-reference/json/json.debug.md
index f3dfea99..189711a0 100644
--- a/docs/command-reference/json/json.debug.md
+++ b/docs/command-reference/json/json.debug.md
@@ -16,3 +16,9 @@ import PageTitle from '@site/src/components/PageTitle';
 **ACL categories:** @json
 
 This is a container command for debugging related tasks.
+
+## Subcommands
+
+- [`JSON.DEBUG MEMORY`](./json.debug-memory.md): Report the memory size in bytes of the JSON element.
+- [`JSON.DEBUG FIELDS`](./json.debug-fields.md): Report the number of fields in the JSON element.
+- [`JSON.DEBUG HELP`](./json.debug-help.md): Show usage information for `JSON.DEBUG` subcommands.
diff --git a/docs/command-reference/json/json.del.md b/docs/command-reference/json/json.del.md
index 59d257f5..2bf8030c 100644
--- a/docs/command-reference/json/json.del.md
+++ b/docs/command-reference/json/json.del.md
@@ -80,8 +80,8 @@ dragonfly> JSON.GET doc $
 
 ## Related topics
 
-* [RedisJSON](https://redis.io/docs/stack/json)
-* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)
+* [RedisJSON](https://redis.io/docs/latest/develop/data-types/json/)
+* [Index and search JSON documents](https://redis.io/docs/latest/develop/data-types/json/indexing_json/)
 
 
 
diff --git a/docs/command-reference/json/json.resp.md b/docs/command-reference/json/json.resp.md
index 1175adbb..36b1b5a6 100644
--- a/docs/command-reference/json/json.resp.md
+++ b/docs/command-reference/json/json.resp.md
@@ -95,5 +95,5 @@ dragonfly> JSON.RESP item:2
 
 ## Related topics
 
-* [RedisJSON](https://redis.io/docs/stack/json)
-* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)
+* [RedisJSON](https://redis.io/docs/latest/develop/data-types/json/)
+* [Index and search JSON documents](https://redis.io/docs/latest/develop/data-types/json/indexing_json/)
diff --git a/docs/command-reference/json/json.set.md b/docs/command-reference/json/json.set.md
index d53b150f..a4fcd088 100644
--- a/docs/command-reference/json/json.set.md
+++ b/docs/command-reference/json/json.set.md
@@ -102,5 +102,5 @@ dragonfly> JSON.GET doc
 
 ## Related topics
 
-* [RedisJSON](https://redis.io/docs/stack/json)
-* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)
+* [RedisJSON](https://redis.io/docs/latest/develop/data-types/json/)
+* [Index and search JSON documents](https://redis.io/docs/latest/develop/data-types/json/indexing_json/)
diff --git a/docs/command-reference/json/json.strappend.md b/docs/command-reference/json/json.strappend.md
index a08cc2f0..29edf7de 100644
--- a/docs/command-reference/json/json.strappend.md
+++ b/docs/command-reference/json/json.strappend.md
@@ -68,6 +68,6 @@ dragonfly> JSON.GET doc $
 
 ## Related topics
 
-* [RedisJSON](https://redis.io/docs/stack/json)
-* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)
+* [RedisJSON](https://redis.io/docs/latest/develop/data-types/json/)
+* [Index and search JSON documents](https://redis.io/docs/latest/develop/data-types/json/indexing_json/)