ai-memory-layer 2.0.0

package/openapi.yaml

@@ -0,0 +1,843 @@
+openapi: 3.1.0
+info:
+  title: memory-layer HTTP API
+  version: 2.0.0
+  description: HTTP surface for the memory-layer standalone AI memory service.
+servers:
+  - url: http://localhost:3100
+tags:
+  - name: ingestion
+  - name: retrieval
+  - name: maintenance
+  - name: observability
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: API key
+    adminKey:
+      type: apiKey
+      in: header
+      name: x-admin-key
+  parameters:
+    Query:
+      name: query
+      in: query
+      schema:
+        type: string
+    ScopeTenant:
+      name: tenant_id
+      in: query
+      schema:
+        type: string
+    ScopeSystem:
+      name: system_id
+      in: query
+      schema:
+        type: string
+    ScopeWorkspace:
+      name: workspace_id
+      in: query
+      schema:
+        type: string
+    ScopeCollaboration:
+      name: collaboration_id
+      in: query
+      schema:
+        type: string
+    ScopeId:
+      name: scope_id
+      in: query
+      schema:
+        type: string
+    ScopeLevel:
+      name: scope_level
+      in: query
+      schema:
+        type: string
+        enum: [scope, workspace, system, tenant]
+    Since:
+      name: since
+      in: query
+      schema:
+        type: string
+        format: date-time
+    EventTypes:
+      name: event_types
+      in: query
+      schema:
+        type: string
+  schemas:
+    Error:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: string
+    MemoryEvent:
+      type: object
+      required: [type, scope, timestamp, durationMs, meta]
+      properties:
+        type:
+          type: string
+        scope:
+          $ref: '#/components/schemas/Scope'
+        timestamp:
+          type: integer
+        durationMs:
+          type: integer
+        meta:
+          type: object
+          additionalProperties: true
+    Scope:
+      type: object
+      required: [tenant_id, system_id, scope_id]
+      properties:
+        tenant_id:
+          type: string
+        system_id:
+          type: string
+        workspace_id:
+          type: string
+        collaboration_id:
+          type: string
+        scope_id:
+          type: string
+    TurnRequest:
+      type: object
+      required: [role, content]
+      properties:
+        role:
+          type: string
+          enum: [user, assistant, system]
+        content:
+          type: string
+        actor:
+          type: string
+        scope:
+          $ref: '#/components/schemas/Scope'
+    ExchangeRequest:
+      type: object
+      required: [userContent, assistantContent]
+      properties:
+        userContent:
+          type: string
+        assistantContent:
+          type: string
+        scope:
+          $ref: '#/components/schemas/Scope'
+    FactRequest:
+      type: object
+      required: [fact, factType]
+      properties:
+        fact:
+          type: string
+        factType:
+          type: string
+          enum: [preference, identity, project, constraint, procedure, entity, other]
+        confidence:
+          type: string
+          enum: [high, medium, low]
+          default: high
+        scope:
+          $ref: '#/components/schemas/Scope'
+    WorkRequest:
+      type: object
+      required: [title]
+      properties:
+        title:
+          type: string
+        kind:
+          type: string
+          enum: [objective, unresolved_work, constraint]
+          default: objective
+        status:
+          type: string
+          enum: [open, in_progress, blocked, done]
+          default: open
+        detail:
+          type: string
+        scope:
+          $ref: '#/components/schemas/Scope'
+    CompactRequest:
+      type: object
+      properties:
+        scope:
+          $ref: '#/components/schemas/Scope'
+    ContextResponse:
+      type: object
+      properties:
+        currentObjective:
+          type: string
+          nullable: true
+        activeTurnCount:
+          type: integer
+        workingMemory:
+          type: object
+          nullable: true
+          properties:
+            summary:
+              type: string
+            key_entities:
+              type: array
+              items:
+                type: string
+            topic_tags:
+              type: array
+              items:
+                type: string
+        relevantKnowledge:
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: integer
+              fact:
+                type: string
+              fact_type:
+                type: string
+              confidence:
+                type: string
+        activeObjectives:
+          type: array
+          items:
+            type: object
+            properties:
+              title:
+                type: string
+              status:
+                type: string
+        unresolvedWork:
+          type: array
+          items:
+            type: object
+        tokenEstimate:
+          type: integer
+    SearchResponse:
+      type: object
+      properties:
+        turns:
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: integer
+              role:
+                type: string
+              content:
+                type: string
+              rank:
+                type: number
+        knowledge:
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: integer
+              fact:
+                type: string
+              fact_type:
+                type: string
+              rank:
+                type: number
+    HealthResponse:
+      type: object
+      properties:
+        activeTurnCount:
+          type: integer
+        tokenEstimate:
+          type: integer
+        knowledgeCount:
+          type: integer
+        objectiveCount:
+          type: integer
+        unresolvedWorkCount:
+          type: integer
+    ReadyResponse:
+      type: object
+      properties:
+        ok:
+          type: boolean
+        scopes:
+          type: integer
+security:
+  - bearerAuth: []
+paths:
+  /v1/turns:
+    post:
+      tags: [ingestion]
+      summary: Store a single turn
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/TurnRequest'
+      responses:
+        '201':
+          description: Turn stored
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  turnId:
+                    type: integer
+                  role:
+                    type: string
+        '400':
+          description: Invalid request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/exchanges:
+    post:
+      tags: [ingestion]
+      summary: Store a user and assistant exchange
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ExchangeRequest'
+      responses:
+        '201':
+          description: Exchange stored
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  userTurnId:
+                    type: integer
+                  assistantTurnId:
+                    type: integer
+                  compacted:
+                    type: boolean
+  /v1/context:
+    get:
+      tags: [retrieval]
+      summary: Assemble prompt-ready context
+      parameters:
+        - $ref: '#/components/parameters/Query'
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Assembled context
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ContextResponse'
+  /v1/search:
+    get:
+      tags: [retrieval]
+      summary: Search turns and knowledge
+      parameters:
+        - name: q
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: limit
+          in: query
+          schema:
+            type: integer
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Search results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SearchResponse'
+        '400':
+          description: Missing search query
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/search/cross-scope:
+    get:
+      tags: [retrieval]
+      summary: Search knowledge across inherited or shared scopes
+      parameters:
+        - name: q
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: limit
+          in: query
+          schema:
+            type: integer
+        - $ref: '#/components/parameters/ScopeLevel'
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Cross-scope search results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SearchResponse'
+        '400':
+          description: Missing search query
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/facts:
+    post:
+      tags: [ingestion]
+      summary: Insert durable knowledge directly
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FactRequest'
+      responses:
+        '201':
+          description: Fact stored
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  knowledgeId:
+                    type: integer
+  /v1/work:
+    post:
+      tags: [ingestion]
+      summary: Track an objective or unresolved work item
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WorkRequest'
+      responses:
+        '201':
+          description: Work item stored
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  workItemId:
+                    type: integer
+  /v1/compact:
+    post:
+      tags: [maintenance]
+      summary: Force compaction
+      security:
+        - bearerAuth: []
+        - adminKey: []
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CompactRequest'
+      responses:
+        '200':
+          description: Compaction result
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  compacted:
+                    type: boolean
+                  archivedTurnCount:
+                    type: integer
+  /v1/maintenance:
+    post:
+      tags: [maintenance]
+      summary: Run maintenance
+      security:
+        - bearerAuth: []
+        - adminKey: []
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CompactRequest'
+      responses:
+        '200':
+          description: Maintenance report
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  expiredWorkingMemory:
+                    type: integer
+                  retiredKnowledge:
+                    type: integer
+                  deletedWorkItems:
+                    type: integer
+  /v1/health:
+    get:
+      tags: [observability]
+      summary: Return memory health counters
+      parameters:
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Health counters
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthResponse'
+  /v1/changes:
+    get:
+      tags: [observability]
+      summary: Poll for knowledge changes since a timestamp
+      parameters:
+        - $ref: '#/components/parameters/Since'
+        - $ref: '#/components/parameters/ScopeLevel'
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Matching knowledge changes
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  changes:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: integer
+                        fact:
+                          type: string
+                        fact_type:
+                          type: string
+                        knowledge_state:
+                          type: string
+                        scope_id:
+                          type: string
+                        collaboration_id:
+                          type: string
+                        created_at:
+                          type: integer
+        '400':
+          description: Invalid timestamp
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/inspect/knowledge:
+    get:
+      tags: [observability]
+      summary: Browse active knowledge for the current scope
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+        - name: cursor
+          in: query
+          schema:
+            type: integer
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Paginated knowledge inspection results
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  items:
+                    type: array
+                    items:
+                      type: object
+                  hasMore:
+                    type: boolean
+                  nextCursor:
+                    type: integer
+                    nullable: true
+  /v1/inspect/knowledge/{knowledgeId}:
+    get:
+      tags: [observability]
+      summary: Inspect one knowledge item with evidence and audits
+      parameters:
+        - name: knowledgeId
+          in: path
+          required: true
+          schema:
+            type: integer
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Full knowledge inspection payload
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  knowledge:
+                    type: object
+                  evidence:
+                    type: array
+                    items:
+                      type: object
+                  audits:
+                    type: array
+                    items:
+                      type: object
+        '404':
+          description: Knowledge not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/inspect/audits:
+    get:
+      tags: [observability]
+      summary: List recent knowledge audits or audits for one knowledge id
+      parameters:
+        - name: knowledge_id
+          in: query
+          schema:
+            type: integer
+        - name: limit
+          in: query
+          schema:
+            type: integer
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Matching audit rows
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  audits:
+                    type: array
+                    items:
+                      type: object
+  /v1/inspect/monitor:
+    get:
+      tags: [observability]
+      summary: Inspect the current context monitor
+      parameters:
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Context monitor payload
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  monitor:
+                    type: object
+                    nullable: true
+  /v1/inspect/compactions:
+    get:
+      tags: [observability]
+      summary: List recent compaction logs
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Recent compaction logs
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  logs:
+                    type: array
+                    items:
+                      type: object
+  /v1/inspect/reverification:
+    get:
+      tags: [observability]
+      summary: List knowledge currently due for reverification
+      parameters:
+        - name: limit
+          in: query
+          schema:
+            type: integer
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Due reverification items
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  due:
+                    type: array
+                    items:
+                      type: object
+  /v1/reverification/run:
+    post:
+      tags: [maintenance]
+      summary: Run batch reverification for due knowledge
+      security:
+        - bearerAuth: []
+        - adminKey: []
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                limit:
+                  type: integer
+      responses:
+        '200':
+          description: Reverification batch result
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  reverifiedKnowledgeIds:
+                    type: array
+                    items:
+                      type: integer
+                  demotedKnowledgeIds:
+                    type: array
+                    items:
+                      type: integer
+  /v1/reverification/{knowledgeId}:
+    post:
+      tags: [maintenance]
+      summary: Reverify one knowledge item immediately
+      security:
+        - bearerAuth: []
+        - adminKey: []
+      parameters:
+        - name: knowledgeId
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Knowledge trust assessment
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  trust_score:
+                    type: number
+                  state:
+                    type: string
+                  decision:
+                    type: string
+                  reasons:
+                    type: array
+                    items:
+                      type: string
+  /healthz:
+    get:
+      tags: [observability]
+      summary: Liveness probe
+      responses:
+        '200':
+          description: Liveness response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReadyResponse'
+  /readyz:
+    get:
+      tags: [observability]
+      summary: Readiness probe
+      responses:
+        '200':
+          description: Readiness response
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReadyResponse'
+  /v1/events:
+    get:
+      tags: [observability]
+      summary: Open an event stream for memory events
+      parameters:
+        - $ref: '#/components/parameters/EventTypes'
+        - $ref: '#/components/parameters/ScopeLevel'
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Server-sent event stream
+          content:
+            text/event-stream:
+              schema:
+                type: string
+              examples:
+                knowledgeChange:
+                  value: |
+                    data: {"type":"knowledge_change","scope":{"tenant_id":"acme","system_id":"agent","scope_id":"run-42"},"timestamp":1710000000000,"durationMs":0,"meta":{"action":"promote"}}