docs(cli): improve memory command examples (#31803)

Merged via squash.

Prepared head SHA: 15dcda3027f836e3f780533f7dc6d05c81c6b65a
Co-authored-by: JasonOA888 <101583541+JasonOA888@users.noreply.github.com>
Co-authored-by: altaywtf <9790196+altaywtf@users.noreply.github.com>
Reviewed-by: @altaywtf

CHANGELOG.md

@@ -236,6 +236,7 @@ Docs: https://docs.openclaw.ai
 - Markdown/assistant image hardening: flatten remote markdown images to plain text across the Control UI, exported HTML, and shared Swift chat while keeping inline `data:image/...` markdown renderable, so model output no longer triggers automatic remote image fetches. (#38895) Thanks @obviyus.
 - Config/compaction safeguard settings: regression-test `agents.defaults.compaction.recentTurnsPreserve` through `loadConfig()` and cover the new help metadata entry so the exposed preserve knob stays wired through schema validation and config UX. (#25557) thanks @rodrigouroz.
 - iOS/Quick Setup presentation: skip automatic Quick Setup when a gateway is already configured (active connect config, last-known connection, preferred gateway, or manual host), so reconnecting installs no longer get prompted to connect again. (#38964) Thanks @ngutman.
+- CLI/Docs memory help accuracy: clarify `openclaw memory status --deep` behavior and align memory command examples/docs with the current search options. (#31803) Thanks @JasonOA888 and @Avi974.
 
 ## 2026.3.2
 

docs/cli/memory.md

@@ -21,33 +21,45 @@ Related:
 ```bash
 openclaw memory status
 openclaw memory status --deep
+openclaw memory index --force
+openclaw memory search "meeting notes"
+openclaw memory search --query "deployment" --max-results 20
+openclaw memory status --json
 openclaw memory status --deep --index
 openclaw memory status --deep --index --verbose
-openclaw memory index
-openclaw memory index --verbose
-openclaw memory search "release checklist"
-openclaw memory search --query "release checklist"
 openclaw memory status --agent main
 openclaw memory index --agent main --verbose
 ```
 
 ## Options
 
-Common:
+`memory status` and `memory index`:
 
-- `--agent <id>`: scope to a single agent (default: all configured agents).
+- `--agent <id>`: scope to a single agent. Without it, these commands run for each configured agent; if no agent list is configured, they fall back to the default agent.
 - `--verbose`: emit detailed logs during probes and indexing.
 
+`memory status`:
+
+- `--deep`: probe vector + embedding availability.
+- `--index`: run a reindex if the store is dirty (implies `--deep`).
+- `--json`: print JSON output.
+
+`memory index`:
+
+- `--force`: force a full reindex.
+
 `memory search`:
 
 - Query input: pass either positional `[query]` or `--query <text>`.
 - If both are provided, `--query` wins.
 - If neither is provided, the command exits with an error.
+- `--agent <id>`: scope to a single agent (default: the default agent).
+- `--max-results <n>`: limit the number of results returned.
+- `--min-score <n>`: filter out low-score matches.
+- `--json`: print JSON results.
 
 Notes:
 
-- `memory status --deep` probes vector + embedding availability.
-- `memory status --deep --index` runs a reindex if the store is dirty.
 - `memory index --verbose` prints per-phase details (provider, model, sources, batch activity).
 - `memory status` includes any extra paths configured via `memorySearch.extraPaths`.
 - If effectively active memory remote API key fields are configured as SecretRefs, the command resolves those values from the active gateway snapshot. If gateway is unavailable, the command fails fast.

src/cli/memory-cli.test.ts

@@ -113,6 +113,29 @@ describe("memory cli", () => {
     await program.parseAsync(["memory", ...args], { from: "user" });
   }
 
+  function captureHelpOutput(command: Command | undefined) {
+    let output = "";
+    const writeSpy = vi.spyOn(process.stdout, "write").mockImplementation(((
+      chunk: string | Uint8Array,
+    ) => {
+      output += String(chunk);
+      return true;
+    }) as typeof process.stdout.write);
+    try {
+      command?.outputHelp();
+      return output;
+    } finally {
+      writeSpy.mockRestore();
+    }
+  }
+
+  function getMemoryHelpText() {
+    const program = new Command();
+    registerMemoryCli(program);
+    const memoryCommand = program.commands.find((command) => command.name() === "memory");
+    return captureHelpOutput(memoryCommand);
+  }
+
   async function withQmdIndexDb(content: string, run: (dbPath: string) => Promise<void>) {
     const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "memory-cli-qmd-index-"));
     const dbPath = path.join(tmpDir, "index.sqlite");
@@ -220,6 +243,17 @@ describe("memory cli", () => {
     expect(hasLoggedInactiveSecretDiagnostic(log)).toBe(true);
   });
 
+  it("documents memory help examples", () => {
+    const helpText = getMemoryHelpText();
+
+    expect(helpText).toContain("openclaw memory status --deep");
+    expect(helpText).toContain("Probe embedding provider readiness.");
+    expect(helpText).toContain('openclaw memory search "meeting notes"');
+    expect(helpText).toContain("Quick search using positional query.");
+    expect(helpText).toContain('openclaw memory search --query "deployment" --max-results 20');
+    expect(helpText).toContain("Limit results for focused troubleshooting.");
+  });
+
   it("prints vector error when unavailable", async () => {
     const close = vi.fn(async () => {});
     mockManager({

src/cli/memory-cli.ts

@@ -582,9 +582,14 @@ export function registerMemoryCli(program: Command) {
       () =>
         `\n${theme.heading("Examples:")}\n${formatHelpExamples([
           ["openclaw memory status", "Show index and provider status."],
+          ["openclaw memory status --deep", "Probe embedding provider readiness."],
           ["openclaw memory index --force", "Force a full reindex."],
-          ['openclaw memory search --query "deployment notes"', "Search indexed memory entries."],
-          ["openclaw memory status --json", "Output machine-readable JSON."],
+          ['openclaw memory search "meeting notes"', "Quick search using positional query."],
+          [
+            'openclaw memory search --query "deployment" --max-results 20',
+            "Limit results for focused troubleshooting.",
+          ],
+          ["openclaw memory status --json", "Output machine-readable JSON (good for scripts)."],
         ])}\n\n${theme.muted("Docs:")} ${formatDocsLink("/cli/memory", "docs.openclaw.ai/cli/memory")}\n`,
     );