openclaw/qa/scenarios/memory/memory-tools-channel-context.yaml

title: Memory tools in channel context

scenario:
  id: memory-tools-channel-context
  surface: session-memory
  coverage:
    primary:
      - session-memory.group-memory
      - session-memory.memory-tools
      - session-memory.qa-channel-memory
    secondary:
      - channels.room-session-group-messages
  objective: Verify a shared QA-channel message causally recalls a fact from a nested memory file before the agent replies in the same room.
  successCriteria:
    - The initial model request does not contain the memory-only fact and plans memory_search with the expected arguments.
    - The matching memory_search result plans memory_get for the seeded path, whose correlated result supplies the recalled fact.
    - The ordered tool chain produces exactly one visible final reply in the originating QA room.
  docsRefs:
    - docs/concepts/memory.md
    - docs/concepts/memory-search.md
  codeRefs:
    - extensions/memory-core/src/tools.ts
    - extensions/qa-lab/src/suite.ts
  execution:
    kind: flow
    channel: qa-channel
    providerMode: mock-openai
    retryCount: 0
    summary: Prove a QA-channel group message consumes a matched nested-memory result before one in-room reply.
    config:
      requiredProviderMode: mock-openai
      channelId: qa-memory-room
      channelTitle: QA Memory Room
      expectedMemoryPath: memory/qa-shared-channel.md
      memoryFact: "Hidden QA fact: the project codename is ORBIT-9."
      memoryQuery: "hidden project codename"
      expectedCorpus: null
      expectedNeedle: ORBIT-9
      prompt: "@openclaw Memory tools check: what is the hidden project codename stored only in memory? Use memory tools first."
      promptSnippet: "Memory tools check"

flow:
  steps:
    - name: uses memory_search before answering in-channel
      actions:
        - assert:
            expr: "env.providerMode === config.requiredProviderMode"
            message:
              expr: "`expected provider mode ${config.requiredProviderMode}, got ${env.providerMode}`"
        - call: reset
        - call: fs.mkdir
          args:
            - expr: "path.dirname(path.join(env.gateway.workspaceDir, config.expectedMemoryPath))"
            - recursive: true
        - call: fs.writeFile
          args:
            - expr: "path.join(env.gateway.workspaceDir, config.expectedMemoryPath)"
            - expr: "`${config.memoryFact}\\n`"
            - utf8
        - call: forceMemoryIndex
          args:
            - env:
                ref: env
              query:
                expr: config.memoryQuery
              expectedNeedle:
                expr: config.expectedNeedle
        - call: waitForGatewayHealthy
          args:
            - ref: env
            - 60000
        - call: waitForQaChannelReady
          args:
            - ref: env
            - 60000
        - set: requestCursorBeforeInbound
          value:
            expr: "(await fetchJson(`${env.mock.baseUrl}/debug/request-cursor`)).cursor"
        - set: outboundStartIndex
          value:
            expr: "state.getSnapshot().messages.length"
        - set: busCursorBeforeInbound
          value:
            expr: "state.getSnapshot().cursor"
        - sendInbound:
            conversation:
              id:
                expr: config.channelId
              kind: channel
              title:
                expr: config.channelTitle
            senderId: alice
            senderName: Alice
            text:
              expr: config.prompt
        - call: waitForCondition
          saveAs: scenarioRequests
          args:
            - lambda:
                async: true
                expr: "(async () => { const requests = (await fetchJson(`${env.mock.baseUrl}/debug/requests?after=${requestCursorBeforeInbound}`)).filter((request) => String(request.allInputText ?? '').includes(config.promptSnippet)); return requests.length >= 3 ? requests : undefined; })()"
            - expr: liveTurnTimeoutMs(env, 30000)
            - 100
        - assert:
            expr: scenarioRequests.length === 3
            message:
              expr: "`expected one memory_search plan, one matched result request, and one finalization request: ${JSON.stringify(scenarioRequests)}`"
        - set: searchPlanRequest
          value:
            expr: scenarioRequests[0]
        - set: searchResultRequest
          value:
            expr: scenarioRequests[1]
        - set: finalRequest
          value:
            expr: scenarioRequests[2]
        - assert:
            expr: "searchPlanRequest.plannedToolName === 'memory_search' && searchPlanRequest.plannedToolArgs?.query === config.memoryQuery && (searchPlanRequest.plannedToolArgs?.corpus ?? null) === config.expectedCorpus && typeof searchPlanRequest.plannedToolCallId === 'string' && searchPlanRequest.plannedToolCallId.length > 0 && !searchPlanRequest.toolOutputCallId && !String(searchPlanRequest.allInputText ?? '').includes(config.expectedNeedle)"
            message:
              expr: "`initial request exposed the hidden fact or missed the expected memory_search plan: ${JSON.stringify(searchPlanRequest)}`"
        - assert:
            expr: "searchResultRequest.cursor > searchPlanRequest.cursor && searchResultRequest.toolOutputCallId === searchPlanRequest.plannedToolCallId && searchResultRequest.toolOutputStructuredError !== true && String(searchResultRequest.toolOutput ?? '').includes(config.expectedMemoryPath) && String(searchResultRequest.toolOutput ?? '').includes(config.expectedNeedle) && searchResultRequest.plannedToolName === 'memory_get' && searchResultRequest.plannedToolArgs?.path === config.expectedMemoryPath && typeof searchResultRequest.plannedToolCallId === 'string' && searchResultRequest.plannedToolCallId.length > 0 && searchResultRequest.plannedToolCallId !== searchPlanRequest.plannedToolCallId"
            message:
              expr: "`following request did not consume memory_search and plan a distinct memory_get call for the expected path: ${JSON.stringify(searchResultRequest)}`"
        - assert:
            expr: "finalRequest.cursor > searchResultRequest.cursor && finalRequest.toolOutputCallId === searchResultRequest.plannedToolCallId && finalRequest.toolOutputStructuredError !== true && String(finalRequest.toolOutput ?? '').includes(config.expectedMemoryPath) && String(finalRequest.toolOutput ?? '').includes(config.expectedNeedle) && !finalRequest.plannedToolName"
            message:
              expr: "`final request did not consume the matching successful memory_get result: ${JSON.stringify(finalRequest)}`"
        - call: waitForCondition
          saveAs: durableChannelLifecycle
          args:
            - lambda:
                expr: |-
                  (() => {
                    const snapshot = state.getSnapshot();
                    const visible = snapshot.messages.slice(outboundStartIndex).filter((message) => message.accountId === transport.accountId && message.direction === "outbound" && !message.deleted && message.conversation.id === config.channelId && message.conversation.kind === "channel" && message.text.includes(config.expectedNeedle));
                    if (visible.length !== 1) return undefined;
                    const candidate = visible[0];
                    const events = snapshot.events.filter((event) => event.cursor > busCursorBeforeInbound && "message" in event && event.message.accountId === transport.accountId && event.message.direction === "outbound" && event.message.conversation.id === config.channelId && event.message.conversation.kind === "channel" && event.message.text.includes(config.expectedNeedle));
                    const finalSent = events.find((event) => event.kind === "outbound-message" && event.message.id === candidate.id);
                    if (!finalSent) return undefined;
                    const previewRetired = events.find((event) => event.kind === "message-deleted" && event.message.id !== candidate.id && event.cursor < finalSent.cursor);
                    if (!previewRetired) return undefined;
                    const previewSent = events.find((event) => event.kind === "outbound-message" && event.message.id === previewRetired.message.id && event.cursor < previewRetired.cursor);
                    return previewSent ? { message: candidate, previewId: previewRetired.message.id, finalId: candidate.id, previewSentCursor: previewSent.cursor, previewDeletedCursor: previewRetired.cursor, finalSentCursor: finalSent.cursor } : undefined;
                  })()
            - expr: liveTurnTimeoutMs(env, 30000)
        - set: durableChannelOutbound
          value:
            expr: durableChannelLifecycle.message
        - set: visibleChannelOutbounds
          value:
            expr: "state.getSnapshot().messages.slice(outboundStartIndex).filter((message) => message.accountId === transport.accountId && message.direction === 'outbound' && !message.deleted && message.conversation.id === config.channelId && message.conversation.kind === 'channel')"
        - assert:
            # Tool-backed finals replace their streamed preview; prove sent -> deleted -> final ordering first.
            expr: "visibleChannelOutbounds.length === 1 && visibleChannelOutbounds[0].id === durableChannelOutbound.id"
            message:
              expr: "`expected exactly one visible QA-room reply after the ordered memory result: ${JSON.stringify(visibleChannelOutbounds)}`"
        - assert:
            expr: "(durableChannelOutbound.text.match(new RegExp(config.expectedNeedle, 'g')) ?? []).length === 1"
            message:
              expr: "`final QA-room reply must contain ${config.expectedNeedle} exactly once: ${durableChannelOutbound.text}`"
      detailsExpr: "`${durableChannelOutbound.text}; path=${config.expectedMemoryPath}; matched=${searchResultRequest.toolOutputCallId === searchPlanRequest.plannedToolCallId}; room=${config.channelId}; lifecycle=${JSON.stringify({ previewId: durableChannelLifecycle.previewId, previewSentCursor: durableChannelLifecycle.previewSentCursor, previewDeletedCursor: durableChannelLifecycle.previewDeletedCursor, finalId: durableChannelLifecycle.finalId, finalSentCursor: durableChannelLifecycle.finalSentCursor })}`"