> ## Documentation Index
> Fetch the complete documentation index at: https://docs.actx0.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Memories

> Semantic search over session memories. Default `limit` is 10.



## OpenAPI

````yaml /openapi.yaml post /workspaces/{workspaceId}/agents/{agentId}/sessions/{sessionId}/memories/search
openapi: 3.1.0
info:
  title: Actx0 API
  version: 1.0.0
  description: >-
    REST API for Actx0 workspaces, access keys, agents, sessions, messages,
    memories, prompts, and knowledge documents.


    Authenticate with `X-Access-Key` (workspace), `X-API-Key` (user), or a
    dashboard session.
servers:
  - url: https://app.actx0.com/api/v1
    description: Actx0 cloud
security: []
tags:
  - name: Me
    description: Inspect the authenticated access key or API key
  - name: API Keys
    description: User API keys for X-API-Key auth
  - name: Workspaces
    description: Team workspaces
  - name: Access Keys
    description: Scoped workspace keys for agents and SDKs
  - name: Agents
    description: Agents inside a workspace
  - name: Sessions
    description: Agent conversation sessions
  - name: Messages
    description: Session messages and semantic search
  - name: Memories
    description: Session memories, search, batch, and regenerate
  - name: Prompts
    description: Versioned prompts
  - name: Knowledge
    description: Document upload and semantic search
paths:
  /workspaces/{workspaceId}/agents/{agentId}/sessions/{sessionId}/memories/search:
    post:
      tags:
        - Memories
      summary: Search Memories
      description: Semantic search over session memories. Default `limit` is 10.
      operationId: searchMemories
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/AgentId'
        - $ref: '#/components/parameters/SessionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            example:
              query: UI preferences
              limit: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemorySearchResponse'
              example:
                results:
                  - id: 44444444-4444-4444-4444-444444444444
                    kind: preference
                    score: 0.94
                    text: User prefers dark mode
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - AccessKeyAuth: []
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl / acli
          source: >
            curl -X POST
            'https://app.actx0.com/api/v1/workspaces/<workspaceId>/agents/<agentId>/sessions/<sessionId>/memories/search'
            \
              -H "X-Access-Key: YOUR_ACCESS_KEY" \
              -H "Content-Type: application/json" \
              -H "Accept: application/json" \
              -d '{"query": "UI preferences", "limit": 10}'

            # ---


            # acli

            export ACTX0_ACCESS_KEY="YOUR_ACCESS_KEY"

            export ACTX0_WORKSPACE_ID="YOUR_WORKSPACE_ID"


            acli memory search "preferences" \
              --agent-id AGENT_ID \
              --session-id SESSION_ID \
              --limit 5
        - lang: python
          label: pctx0
          source: |
            from pctx0 import Pctx0Client

            client = Pctx0Client(
                access_key="YOUR_ACCESS_KEY",
                workspace_id="YOUR_WORKSPACE_ID",
            )

            hits = client.memory.search(
                "AGENT_ID",
                "SESSION_ID",
                query="preferences",
                limit=5,
            )
        - lang: javascript
          label: nctx0
          source: |
            import { Nctx0Client } from "@actx0/nctx0";

            const client = new Nctx0Client({
              accessKey: "YOUR_ACCESS_KEY",
              workspaceId: "YOUR_WORKSPACE_ID",
            });

            const hits = await client.memory.search("AGENT_ID", "SESSION_ID", {
              query: "preferences",
              limit: 5,
            });
        - lang: go
          label: gtcx0
          source: "package main\n\nimport (\n\t\"context\"\n\n\t\"github.com/Actx0/Gctx0\"\n)\n\nfunc main() {\n\tclient := gctx0.NewClient(\n\t\tgctx0.WithAccessKey(\"YOUR_ACCESS_KEY\"),\n\t\tgctx0.WithWorkspaceId(\"YOUR_WORKSPACE_ID\"),\n\t)\n\tdefer client.Close()\n\tctx := context.Background()\n\thits, err := client.Memory.Search(ctx, \"AGENT_ID\", \"SESSION_ID\", \"preferences\", 5)\n\t_ = hits\n\t_ = err\n}\n"
components:
  parameters:
    WorkspaceId:
      name: workspaceId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      example: 11111111-1111-1111-1111-111111111111
    AgentId:
      name: agentId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      example: 22222222-2222-2222-2222-222222222222
    SessionId:
      name: sessionId
      in: path
      required: true
      description: Internal session UUID (not externalId).
      schema:
        type: string
        format: uuid
      example: 33333333-3333-3333-3333-333333333333
  schemas:
    SearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          minLength: 1
          example: UI preferences
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          example: 10
    MemorySearchResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/MemorySearchHit'
    Error:
      type: object
      required:
        - errorMessage
      properties:
        errorMessage:
          type: string
          example: Name is required
    MemorySearchHit:
      type: object
      required:
        - id
        - kind
        - score
        - text
      properties:
        id:
          type: string
          format: uuid
          example: 44444444-4444-4444-4444-444444444444
        kind:
          type: string
          example: preference
        score:
          type: number
          example: 0.94
        text:
          type: string
          example: User prefers dark mode
  securitySchemes:
    AccessKeyAuth:
      type: apiKey
      in: header
      name: X-Access-Key
      description: Workspace access key for agent/runtime integrations.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: User API key for management and automation.

````