Hlix Memories API

openapi: 3.2.0
info:
  description: Explore the Hlix API for projects, agent teams, and delivery workflows. Authenticate with `x-api-key` and select a Workspace with `X-Organization-Id`. Session-only operations require a signed-in user session. Authentication setup.
  title: reference Memories API
  version: 1.0.0
servers:
- url: https://server.hlix.ai
  description: API server
security:
- apiKey: []
- sessionCookie: []
tags:
- name: Memories
paths:
  /v1/api/memories:
    get:
      operationId: listMemories
      parameters:
      - description: '`org` | `project` | `cycle` | `task` | `agent`.'
        in: query
        name: scope
        required: false
        schema:
          type: string
      - description: The scoped entity's id.
        in: query
        name: scopeId
        required: false
        schema:
          type: string
      - description: '`tentative` | `approved` | `archived`.'
        in: query
        name: status
        required: false
        schema:
          type: string
      - description: Filter memory text by substring. For semantic search with similarity scores, use `/memories/search/{scope}/{scopeId}`.
        in: query
        name: q
        required: false
        schema:
          type: string
      - description: Page size, clamped to 1–500; 100 when omitted or not an integer.
        in: query
        name: limit
        required: false
        schema:
          type: string
      - description: Rows to skip. Ask for the next page with `offset` + `limit` until a page comes back shorter than `limit`.
        in: query
        name: offset
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Memory'
                type: array
          description: The matching memories. No `score` — nothing was ranked.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: List the workspace's memories
      tags:
      - Memories
    post:
      operationId: createMemory
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMemory'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Memory'
          description: The stored memory, read back from the store.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`).
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The supersession target is not a current memory in the same scope.
      summary: Write a memory
      tags:
      - Memories
  /v1/api/memories/extract/{cycleId}:
    post:
      operationId: extractCycleMemories
      parameters:
      - in: path
        name: cycleId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageAck'
          description: Extraction finished. Read the project knowledge disposition to distinguish saved, skipped and rejected scope results. Failed classifier, embedding or storage writes return an error.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: Extract memories from a finished cycle
      tags:
      - Memories
  /v1/api/memories/project/{projectId}:
    get:
      operationId: getProjectKnowledge
      parameters:
      - in: path
        name: projectId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectKnowledge'
          description: Only this project's actual project, cycle and task scopes.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No memory with that id in this workspace — under the named scope, or under any of them when none was named.
      summary: Read learned knowledge and recording availability for one project
      tags:
      - Memories
  /v1/api/memories/search/{scope}/{scopeId}:
    get:
      operationId: searchMemories
      parameters:
      - in: path
        name: scope
        required: true
        schema:
          type: string
      - in: path
        name: scopeId
        required: true
        schema:
          type: string
      - description: The text to rank against. Omitted, the scope's memories come back unranked.
        in: query
        name: q
        required: false
        schema:
          type: string
      - description: '`tentative` | `approved` | `archived`.'
        in: query
        name: status
        required: false
        schema:
          type: string
      - description: Page size, clamped to 1–500.
        in: query
        name: limit
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Memory'
                type: array
          description: Memories ranked by similarity, each carrying `score` (cosine similarity, 1 − distance).
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The resource does not exist, or the caller is a task-scoped credential and this endpoint is outside its allowlist.
      summary: Search one scope by meaning
      tags:
      - Memories
  /v1/api/memories/{id}:
    delete:
      operationId: deleteMemory
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - description: '`org` | `project` | `cycle` | `task` | `agent`.'
        in: query
        name: scope
        required: false
        schema:
          type: string
      - description: The scoped entity's id.
        in: query
        name: scopeId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageAck'
          description: The memory is gone.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No memory with that id in this workspace — under the named scope, or under any of them when none was named.
      summary: Delete a memory
      tags:
      - Memories
    get:
      operationId: getMemory
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - description: '`org` | `project` | `cycle` | `task` | `agent`.'
        in: query
        name: scope
        required: false
        schema:
          type: string
      - description: The scoped entity's id.
        in: query
        name: scopeId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Memory'
          description: The memory. Supplying `scope` and `scopeId` narrows the lookup; otherwise all namespaces are searched.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The request named no active organization.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No memory with that id in this workspace — under the named scope, or under any of them when none was named.
      summary: Get one memory
      tags:
      - Memories
    patch:
      operationId: updateMemory
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - description: '`org` | `project` | `cycle` | `task` | `agent`.'
        in: query
        name: scope
        required: false
        schema:
          type: string
      - description: The scoped entity's id.
        in: query
        name: scopeId
        required: false
        schema:
          type: string
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMemory'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Memory'
          description: The updated memory. `category`, `key` and `source` are immutable — they are carried over from the stored row.
        '400':
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/ValidationError'
                - $ref: '#/components/schemas/ApiError'
          description: The JSON body failed schema validation (`ValidationError`), or the request named no active organization (`ApiError`).
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No valid session or API key.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The caller is a client collaborator; memory is restricted to the agency. (Or the caller is not a member of this workspace at all.)
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: No memory with that id in this workspace — under the named scope, or under any of them when none was named.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
          description: The supersession target is not a current memory in the same scope.
      summary: Update a memory
      tags:
      - Memories
components:
  schemas:
    ApiError:
      additionalProperties: {}
      properties:
        error:
          type: string
      required:
      - error
      type: object
    ProjectKnowledge:
      properties:
        extractions:
          items:
            properties:
              cycleId:
                type: string
              cycleStatus:
                type: string
              cycleUpdatedAt:
                type: string
              disposition:
                anyOf:
                - properties:
                    reason:
                      enum:
                      - extracting
                      - saved
                      - cycle_not_successful
                      - no_source
                      - no_useful
                      - foreign_scope
                      - classifier_error
                      - embedding_error
                      - write_error
                      - source_error
                      type: string
                    rejectedCount:
                      maximum: 9007199254740991
                      minimum: 0
                      type: integer
                    savedCount:
                      maximum: 9007199254740991
                      minimum: 0
                      type: integer
                    sourceCount:
                      maximum: 9007199254740991
                      minimum: 0
                      type: integer
                    status:
                      enum:
                      - started
                      - completed
                      - skipped
                      - failed
                      type: string
                  required:
                  - status
                  - reason
                  - sourceCount
                  - savedCount
                  - rejectedCount
                  type: object
                - type: 'null'
              recordedAt:
                type:
                - string
                - 'null'
            required:
            - cycleId
            - cycleStatus
            - cycleUpdatedAt
            - disposition
            - recordedAt
            type: object
          type: array
        memories:
          items:
            properties:
              category:
                enum:
                - convention
                - decision
                - lesson
                - preference
                - failure
                - heuristic
                type: string
              confidence:
                type: number
              createdAt:
                type: string
              id:
                type: string
              key:
                type: string
              organizationId:
                type: string
              scope:
                enum:
                - org
                - project
                - cycle
                - task
                - agent
                type: string
              scopeId:
                type: string
              score:
                type: number
              source:
                enum:
                - auto
                - user
                - interview
                - review
                type: string
              status:
                enum:
                - tentative
                - approved
                - archived
                type: string
              updatedAt:
                type: string
              value:
                type: string
            required:
            - id
            - organizationId
            - scope
            - scopeId
            - category
            - key
            - value
            - source
            - confidence
            - status
            - createdAt
            - updatedAt
            type: object
          type: array
        memoryAvailability:
          properties:
            configuredNow:
              enum:
              - enabled
              - disabled
              - unavailable
              type: string
            sources:
              items:
                properties:
                  current:
                    type: boolean
                  kind:
                    enum:
                    - conductor
                    - execution
                    - legacy
                    type: string
                  latestMessageAt:
                    type:
                    - string
                    - 'null'
                  messageCount:
                    type:
                    - number
                    - 'null'
                  observation:
                    anyOf:
                    - properties:
                        hasObservations:
                          type: boolean
                        lastObservedAt:
                          type:
                          - string
                          - 'null'
                        observationTokens:
                          type: number
                        pendingTokens:
                          type: number
                        processingRecorded:
                          type: boolean
                        threshold:
                          type:
                          - number
                          - 'null'
                      required:
                      - hasObservations
                      - pendingTokens
                      - observationTokens
                      - threshold
                      - lastObservedAt
                      - processingRecorded
                      type: object
                    - type: 'null'
                  state:
                    enum:
                    - recorded
                    - absent
                    - unavailable
                    type: string
                  taskId:
                    type:
                    - string
                    - 'null'
                required:
                - kind
                - taskId
                - current
                - state
                - messageCount
                - latestMessageAt
                - observation
                type: object
              type: array
          required:
          - configuredNow
          - sources
          type: object
        projectId:
          type: string
      required:
      - projectId
      - memories
      - extractions
      - memoryAvailability
      type: object
    MessageAck:
      properties:
        message:
          type: string
      required:
      - message
      type: object
    UpdateMemory:
      properties:
        confidence:
          maximum: 1
          minimum: 0
          type: number
        status:
          enum:
          - tentative
          - approved
          - archived
          type: string
        supersededById:
          type:
          - string
          - 'null'
        supersededReason:
          anyOf:
          - maxLength: 2000
            type: string
          - type: 'null'
        value:
          maxLength: 10000
          minLength: 1
          type: string
      type: object
    Memory:
      properties:
        category:
          enum:
          - convention
          - decision
          - lesson
          - preference
          - failure
          - heuristic
          type: string
        confidence:
          type: number
        createdAt:
          type: string
        id:
          type: string
        key:
          type: string
        organizationId:
          type: string
        scope:
          enum:
          - org
          - project
          - cycle
          - task
          - agent
          type: string
        scopeId:
          type: string
        score:
          type: number
        source:
          enum:
          - auto
          - user
          - interview
          - review
          type: string
        status:
          enum:
          - tentative
          - approved
          - archived
          type: string
        updatedAt:
          type: string
        value:
          type: string
      required:
      - id
      - organizationId
      - scope
      - scopeId
      - category
      - key
      - value
      - source
      - confidence
      - status
      - createdAt
      - updatedAt
      type: object
    ValidationError:
      properties:
        error:
          properties:
            message:
              type: string
            name:
              type: string
          required:
          - name
          - message
          type: object
        success:
          const: false
          type: boolean
      required:
      - success
      - error
      type: object
    CreateMemory:
      properties:
        category:
          enum:
          - convention
          - decision
          - lesson
          - preference
          - failure
          - heuristic
          type: string
        confidence:
          maximum: 1
          minimum: 0
          type: number
        key:
          maxLength: 200
          minLength: 1
          type: string
        scope:
          enum:
          - org
          - project
          - cycle
          - task
          - agent
          type: string
        scopeId:
          minLength: 1
          type: string
        source:
          enum:
          - auto
          - user
          - interview
          - review
          type: string
        status:
          enum:
          - tentative
          - approved
          - archived
          type: string
        supersededReason:
          maxLength: 2000
          type: string
        supersedesId:
          type: string
        value:
          maxLength: 10000
          minLength: 1
          type: string
      required:
      - scope
      - scopeId
      - category
      - key
      - value
      type: object
  parameters:
    OrganizationId:
      description: The workspace (organization) to act in. Omitted, the session's active organization is used.
      in: header
      name: X-Organization-Id
      required: false
      schema:
        type: string
      example: YOUR_WORKSPACE_ID
  securitySchemes:
    apiKey:
      description: An API key issued through `/v1/api/auth/api-key/*`. Browser clients can use their session cookie instead.
      in: header
      name: x-api-key
      type: apiKey
    sessionCookie:
      description: The complete session Cookie header issued by sign-in at the selected API host. Cookie names vary by hosting region and environment; preserve the issued name and value. Browsers send these HTTP-only cookies automatically. Session-only operations require this user session and do not accept an API key.
      in: header
      name: Cookie
      type: apiKey