ai-memory-layer 2.0.0 → 3.0.0

package/openapi.yaml

@@ -1,13 +1,18 @@
 openapi: 3.1.0
 info:
   title: memory-layer HTTP API
-  version: 2.0.0
+  version: 3.0.0
   description: HTTP surface for the memory-layer standalone AI memory service.
 servers:
   - url: http://localhost:3100
 tags:
   - name: ingestion
   - name: retrieval
+  - name: episodic
+  - name: cognitive
+  - name: profiles
+  - name: playbooks
+  - name: associations
   - name: maintenance
   - name: observability
 components:
@@ -75,6 +80,41 @@ components:
       properties:
         error:
           type: string
+    Association:
+      type: object
+      required: [id, tenant_id, system_id, workspace_id, collaboration_id, scope_id, source_kind, source_id, target_kind, target_id, association_type, confidence, auto_generated, created_at]
+      properties:
+        id:
+          type: integer
+        tenant_id:
+          type: string
+        system_id:
+          type: string
+        workspace_id:
+          type: string
+        collaboration_id:
+          type: string
+        scope_id:
+          type: string
+        source_kind:
+          type: string
+          enum: [knowledge, playbook, working_memory, work_item]
+        source_id:
+          type: integer
+        target_kind:
+          type: string
+          enum: [knowledge, playbook, working_memory, work_item]
+        target_id:
+          type: integer
+        association_type:
+          type: string
+          enum: [related_to, supports, contradicts, supersedes, depends_on, solves, applies_to, derived_from]
+        confidence:
+          type: number
+        auto_generated:
+          type: boolean
+        created_at:
+          type: integer
     MemoryEvent:
       type: object
       required: [type, scope, timestamp, durationMs, meta]
@@ -104,6 +144,129 @@ components:
           type: string
         scope_id:
           type: string
+    ActorRef:
+      type: object
+      required: [actor_kind, actor_id]
+      properties:
+        actor_kind:
+          type: string
+          enum: [agent, human, system, service]
+        actor_id:
+          type: string
+        system_id:
+          type: string
+          nullable: true
+        display_name:
+          type: string
+          nullable: true
+        metadata:
+          type: object
+          nullable: true
+          additionalProperties: true
+    WorkClaim:
+      type: object
+      required: [id, work_item_id, actor, claim_token, status, claimed_at, expires_at, visibility_class, version]
+      properties:
+        id:
+          type: integer
+        work_item_id:
+          type: integer
+        actor:
+          $ref: '#/components/schemas/ActorRef'
+        session_id:
+          type: string
+          nullable: true
+        claim_token:
+          type: string
+        status:
+          type: string
+          enum: [active, released, expired]
+        claimed_at:
+          type: integer
+        expires_at:
+          type: integer
+        released_at:
+          type: integer
+          nullable: true
+        release_reason:
+          type: string
+          nullable: true
+        source_event_id:
+          type: string
+          nullable: true
+        visibility_class:
+          type: string
+          enum: [private, shared_collaboration, workspace, tenant]
+        version:
+          type: integer
+    HandoffRecord:
+      type: object
+      required: [id, work_item_id, from_actor, to_actor, summary, status, created_at, visibility_class, version]
+      properties:
+        id:
+          type: integer
+        work_item_id:
+          type: integer
+        from_actor:
+          $ref: '#/components/schemas/ActorRef'
+        to_actor:
+          $ref: '#/components/schemas/ActorRef'
+        session_id:
+          type: string
+          nullable: true
+        summary:
+          type: string
+        context_bundle_ref:
+          type: string
+          nullable: true
+        status:
+          type: string
+          enum: [pending, accepted, rejected, canceled, expired]
+        created_at:
+          type: integer
+        accepted_at:
+          type: integer
+          nullable: true
+        rejected_at:
+          type: integer
+          nullable: true
+        canceled_at:
+          type: integer
+          nullable: true
+        expires_at:
+          type: integer
+          nullable: true
+        decision_reason:
+          type: string
+          nullable: true
+        source_event_id:
+          type: string
+          nullable: true
+        visibility_class:
+          type: string
+          enum: [private, shared_collaboration, workspace, tenant]
+        version:
+          type: integer
+    CoordinationState:
+      type: object
+      required: [ownedClaims, pendingInboundHandoffs, pendingOutboundHandoffs, sharedWorkItems]
+      properties:
+        ownedClaims:
+          type: array
+          items:
+            $ref: '#/components/schemas/WorkClaim'
+        pendingInboundHandoffs:
+          type: array
+          items:
+            $ref: '#/components/schemas/HandoffRecord'
+        pendingOutboundHandoffs:
+          type: array
+          items:
+            $ref: '#/components/schemas/HandoffRecord'
+        sharedWorkItems:
+          type: array
+          items:
+            type: object
     TurnRequest:
       type: object
       required: [role, content]
@@ -158,6 +321,9 @@ components:
           default: open
         detail:
           type: string
+        visibility_class:
+          type: string
+          enum: [private, shared_collaboration, workspace, tenant]
         scope:
           $ref: '#/components/schemas/Scope'
     CompactRequest:
@@ -171,6 +337,35 @@ components:
         currentObjective:
           type: string
           nullable: true
+        sessionState:
+          type: object
+          nullable: true
+          properties:
+            currentObjective:
+              type: string
+              nullable: true
+            blockers:
+              type: array
+              items:
+                type: string
+            assumptions:
+              type: array
+              items:
+                type: string
+            pendingDecisions:
+              type: array
+              items:
+                type: string
+            activeTools:
+              type: array
+              items:
+                type: string
+            recentOutputs:
+              type: array
+              items:
+                type: string
+            updatedAt:
+              type: integer
         activeTurnCount:
           type: integer
         workingMemory:
@@ -212,7 +407,13 @@ components:
         unresolvedWork:
           type: array
           items:
-            type: object
+            type: string
+        debugTrace:
+          type: object
+          nullable: true
+        coordinationState:
+          type: object
+          nullable: true
         tokenEstimate:
           type: integer
     SearchResponse:
@@ -257,6 +458,148 @@ components:
           type: integer
         unresolvedWorkCount:
           type: integer
+        sessionStateUpdatedAt:
+          type: integer
+        circuitBreakers:
+          type: object
+    TemporalEventLogResponse:
+      type: object
+      required: [events]
+      properties:
+        events:
+          type: array
+          items:
+            $ref: '#/components/schemas/TemporalEventRecord'
+        nextCursor:
+          type: string
+          nullable: true
+    TemporalEventRecord:
+      type: object
+      required: [event_id, entity_kind, entity_id, event_type, payload, created_at]
+      properties:
+        event_id:
+          type: string
+        tenant_id:
+          type: string
+        system_id:
+          type: string
+        workspace_id:
+          type: string
+        collaboration_id:
+          type: string
+        scope_id:
+          type: string
+        session_id:
+          type: string
+          nullable: true
+        actor_id:
+          type: string
+          nullable: true
+        actor_kind:
+          type: string
+          nullable: true
+        actor_system_id:
+          type: string
+          nullable: true
+        actor_display_name:
+          type: string
+          nullable: true
+        actor_metadata:
+          type: object
+          nullable: true
+          additionalProperties: true
+        entity_kind:
+          type: string
+        entity_id:
+          type: string
+        event_type:
+          type: string
+        payload:
+          type: object
+          additionalProperties: true
+        causation_id:
+          type: string
+          nullable: true
+        correlation_id:
+          type: string
+          nullable: true
+        created_at:
+          type: integer
+    TemporalStateResponse:
+      type: object
+      required: [asOf, exact, cutoverAt, watermarkEventId, context, turns, workingMemory, knowledge, workItems, associations, playbooks, workClaims, handoffs]
+      properties:
+        asOf:
+          type: integer
+        exact:
+          type: boolean
+        cutoverAt:
+          type: integer
+          nullable: true
+        watermarkEventId:
+          type: string
+          nullable: true
+        context:
+          $ref: '#/components/schemas/ContextResponse'
+        sessionState:
+          type: object
+          nullable: true
+        turns:
+          type: array
+          items:
+            type: object
+        workingMemory:
+          type: array
+          items:
+            type: object
+        knowledge:
+          type: array
+          items:
+            type: object
+        workItems:
+          type: array
+          items:
+            type: object
+        associations:
+          type: array
+          items:
+            type: object
+        playbooks:
+          type: array
+          items:
+            type: object
+        workClaims:
+          type: array
+          items:
+            $ref: '#/components/schemas/WorkClaim'
+        handoffs:
+          type: array
+          items:
+            $ref: '#/components/schemas/HandoffRecord'
+        coordinationState:
+          type: object
+          nullable: true
+    TemporalStateDiffResponse:
+      type: object
+      required: [from, to, exact, cutoverAt, watermarkRange, events, summary]
+      properties:
+        from:
+          type: integer
+        to:
+          type: integer
+        exact:
+          type: boolean
+        cutoverAt:
+          type: integer
+          nullable: true
+        watermarkRange:
+          type: object
+        events:
+          type: array
+          items:
+            $ref: '#/components/schemas/TemporalEventRecord'
+        summary:
+          type: object
     ReadyResponse:
       type: object
       properties:
@@ -264,93 +607,1416 @@ components:
           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
+    EpisodeSourceReference:
+      type: object
+      required: [type, id, excerpt]
+      properties:
+        type:
+          type: string
+          enum: [turn, working_memory, knowledge]
+        id:
+          type: integer
+        excerpt:
+          type: string
+          nullable: true
+    EpisodeRecap:
+      type: object
+      required: [objective, actions, outcomes, artifacts, unresolvedItems, sourceType, sources]
+      properties:
+        objective:
+          type: string
+        actions:
+          type: array
+          items:
+            type: string
+        outcomes:
+          type: array
+          items:
+            type: string
+        artifacts:
+          type: array
+          items:
+            type: string
+        unresolvedItems:
+          type: array
+          items:
+            type: string
+        sourceType:
+          type: string
+          enum: [episodic, declarative, mixed]
+        sources:
+          type: array
+          items:
+            $ref: '#/components/schemas/EpisodeSourceReference'
+    EpisodeSummary:
+      type: object
+      required: [sessionId, recap, detailLevel, turnRange, createdAt]
+      properties:
+        sessionId:
+          type: string
+        recap:
+          $ref: '#/components/schemas/EpisodeRecap'
+        detailLevel:
+          type: string
+          enum: [abstract, overview, full]
+        turnRange:
+          type: object
+          required: [start, end]
+          properties:
+            start:
+              type: integer
+            end:
+              type: integer
+        createdAt:
+          type: integer
+    ReflectResult:
+      type: object
+      required: [synthesis, sourceType, sources, episodes, detailLevel]
+      properties:
+        synthesis:
+          type: string
+        sourceType:
+          type: string
+          enum: [episodic, declarative, mixed]
+        sources:
+          type: array
+          items:
+            $ref: '#/components/schemas/EpisodeSourceReference'
+        episodes:
+          type: array
+          items:
+            $ref: '#/components/schemas/EpisodeSummary'
+        detailLevel:
+          type: string
+          enum: [abstract, overview, full]
+    CognitiveMemoryItem:
+      type: object
+      required: [id, type, fact, createdAt, lastAccessedAt, metadata]
+      properties:
+        id:
+          type: integer
+        type:
+          type: string
+          enum: [episodic, semantic, procedural, working]
+        fact:
+          type: string
+        createdAt:
+          type: integer
+        lastAccessedAt:
+          type: integer
+        metadata:
+          type: object
+          required: [trustScore, knowledgeClass]
+          properties:
+            trustScore:
+              type: number
+            knowledgeClass:
+              type: string
+            knowledgeState:
+              type: string
+    CognitiveSearchHit:
+      type: object
+      required: [item, rank]
+      properties:
+        item:
+          $ref: '#/components/schemas/CognitiveMemoryItem'
+        rank:
+          type: number
+    CognitiveSearchResult:
+      type: object
+      required: [byType, all]
+      properties:
+        byType:
+          type: object
+          required: [episodic, semantic, procedural, working]
+          properties:
+            episodic:
+              type: array
+              items:
+                $ref: '#/components/schemas/CognitiveSearchHit'
+            semantic:
+              type: array
+              items:
+                $ref: '#/components/schemas/CognitiveSearchHit'
+            procedural:
+              type: array
+              items:
+                $ref: '#/components/schemas/CognitiveSearchHit'
+            working:
+              type: array
+              items:
+                $ref: '#/components/schemas/CognitiveSearchHit'
+        all:
+          type: array
+          items:
+            $ref: '#/components/schemas/CognitiveSearchHit'
+    ProfileEntry:
+      type: object
+      required: [knowledgeId, fact, trustScore, knowledgeState, confidence, lastConfirmedAt]
+      properties:
+        knowledgeId:
+          type: integer
+        fact:
+          type: string
+        trustScore:
+          type: number
+        knowledgeState:
+          type: string
+          enum: [candidate, provisional, trusted, disputed, superseded, retired]
+        confidence:
+          type: string
+          enum: [high, medium, low]
+        lastConfirmedAt:
+          type: integer
+          nullable: true
+    Profile:
+      type: object
+      required: [view, sections, generatedAt]
+      properties:
+        view:
+          type: string
+          enum: [user, operator, workspace]
+        sections:
+          type: object
+          required: [identity, preferences, communication, constraints, workflows]
+          properties:
+            identity:
+              type: array
+              items:
+                $ref: '#/components/schemas/ProfileEntry'
+            preferences:
+              type: array
+              items:
+                $ref: '#/components/schemas/ProfileEntry'
+            communication:
+              type: array
+              items:
+                $ref: '#/components/schemas/ProfileEntry'
+            constraints:
+              type: array
+              items:
+                $ref: '#/components/schemas/ProfileEntry'
+            workflows:
+              type: array
+              items:
+                $ref: '#/components/schemas/ProfileEntry'
+        generatedAt:
+          type: integer
+    Playbook:
+      type: object
+      required: [id, tenant_id, system_id, workspace_id, collaboration_id, scope_id, title, description, instructions, references, templates, scripts, assets, tags, status, revision_count, use_count, created_at, updated_at, schema_version, visibility_class]
+      properties:
+        id:
+          type: integer
+        tenant_id:
+          type: string
+        system_id:
+          type: string
+        workspace_id:
+          type: string
+        collaboration_id:
+          type: string
+        scope_id:
+          type: string
+        visibility_class:
+          type: string
+          enum: [private, shared_collaboration, workspace, tenant]
+        title:
+          type: string
+        description:
+          type: string
+        instructions:
+          type: string
+        references:
+          type: array
+          items:
+            type: string
+        templates:
+          type: array
+          items:
+            type: string
+        scripts:
+          type: array
+          items:
+            type: string
+        assets:
+          type: array
+          items:
+            type: string
+        tags:
+          type: array
+          items:
+            type: string
+        status:
+          type: string
+          enum: [draft, active, deprecated, archived]
+        source_session_id:
+          type: string
+          nullable: true
+        source_working_memory_id:
+          type: integer
+          nullable: true
+        revision_count:
+          type: integer
+        last_used_at:
+          type: integer
+          nullable: true
+        use_count:
+          type: integer
+        created_at:
+          type: integer
+        updated_at:
+          type: integer
+        schema_version:
+          type: integer
+    NewPlaybookRequest:
+      type: object
+      required: [title, description, instructions]
+      properties:
+        title:
+          type: string
+        description:
+          type: string
+        instructions:
+          type: string
+        references:
+          type: array
+          items:
+            type: string
+        templates:
+          type: array
+          items:
+            type: string
+        scripts:
+          type: array
+          items:
+            type: string
+        assets:
+          type: array
+          items:
+            type: string
+        tags:
+          type: array
+          items:
+            type: string
+        status:
+          type: string
+          enum: [draft, active, deprecated, archived]
+        source_session_id:
+          type: string
+        source_working_memory_id:
+          type: integer
+        scope:
+          $ref: '#/components/schemas/Scope'
+    PlaybookRevision:
+      type: object
+      required: [id, tenant_id, system_id, workspace_id, collaboration_id, scope_id, playbook_id, instructions, revision_reason, created_at]
+      properties:
+        id:
+          type: integer
+        tenant_id:
+          type: string
+        system_id:
+          type: string
+        workspace_id:
+          type: string
+        collaboration_id:
+          type: string
+        scope_id:
+          type: string
+        playbook_id:
+          type: integer
+        instructions:
+          type: string
+        revision_reason:
+          type: string
+        source_session_id:
+          type: string
+          nullable: true
+        created_at:
+          type: integer
+    PlaybookSearchHit:
+      type: object
+      required: [item, rank]
+      properties:
+        item:
+          $ref: '#/components/schemas/Playbook'
+        rank:
+          type: number
+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'
+        - name: view
+          in: query
+          schema:
+            type: string
+            enum: [local_only, local_plus_shared_collaboration, operator_supervisor, workspace_shared]
+        - name: include_coordination
+          in: query
+          schema:
+            type: boolean
+        - name: viewer_actor_kind
+          in: query
+          schema:
+            type: string
+            enum: [agent, human, system, service]
+        - name: viewer_actor_id
+          in: query
+          schema:
+            type: string
+        - name: viewer_system_id
+          in: query
+          schema:
+            type: string
+        - name: viewer_display_name
+          in: query
+          schema:
+            type: string
+        - $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/state:
+    get:
+      tags: [retrieval]
+      summary: Get temporal state at a unix timestamp
+      parameters:
+        - name: as_of
+          in: query
+          required: true
+          schema:
+            type: integer
+        - $ref: '#/components/parameters/Query'
+        - name: view
+          in: query
+          schema:
+            type: string
+            enum: [local_only, local_plus_shared_collaboration, operator_supervisor, workspace_shared]
+        - name: include_coordination
+          in: query
+          schema:
+            type: boolean
+        - name: viewer_actor_kind
+          in: query
+          schema:
+            type: string
+            enum: [agent, human, system, service]
+        - name: viewer_actor_id
+          in: query
+          schema:
+            type: string
+        - name: viewer_system_id
+          in: query
+          schema:
+            type: string
+        - name: viewer_display_name
+          in: query
+          schema:
+            type: string
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Temporal state snapshot
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TemporalStateResponse'
+  /v1/timeline:
+    get:
+      tags: [retrieval]
+      summary: List memory events in chronological order
+      parameters:
+        - name: session_id
+          in: query
+          schema: { type: string }
+        - name: entity_kind
+          in: query
+          schema: { type: string }
+        - name: entity_id
+          in: query
+          schema: { type: string }
+        - name: start_at
+          in: query
+          schema: { type: integer }
+        - name: end_at
+          in: query
+          schema: { type: integer }
+        - name: limit
+          in: query
+          schema: { type: integer }
+        - name: cursor
+          in: query
+          schema: { type: string }
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Timeline page
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TemporalEventLogResponse'
+  /v1/state/diff:
+    get:
+      tags: [retrieval]
+      summary: Diff memory state between two timestamps
+      parameters:
+        - name: from
+          in: query
+          required: true
+          schema: { type: integer }
+        - name: to
+          in: query
+          required: true
+          schema: { type: integer }
+        - name: session_id
+          in: query
+          schema: { type: string }
+        - name: entity_kind
+          in: query
+          schema: { type: string }
+        - name: entity_id
+          in: query
+          schema: { type: string }
+        - name: max_events
+          in: query
+          description: Optional transport cap for accumulated events. Defaults to 5000 and must not exceed 20000.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 20000
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Temporal diff
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TemporalStateDiffResponse'
+  /v1/events/log:
+    get:
+      tags: [retrieval]
+      summary: List memory events in reverse chronological order
+      parameters:
+        - name: session_id
+          in: query
+          schema: { type: string }
+        - name: entity_kind
+          in: query
+          schema: { type: string }
+        - name: entity_id
+          in: query
+          schema: { type: string }
+        - name: start_at
+          in: query
+          schema: { type: integer }
+        - name: end_at
+          in: query
+          schema: { type: integer }
+        - name: limit
+          in: query
+          schema: { type: integer }
+        - name: cursor
+          in: query
+          schema: { type: string }
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Event log page
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TemporalEventLogResponse'
+  /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/episodes:
+    get:
+      tags: [episodic]
+      summary: Search episodic memory across sessions
+      parameters:
+        - name: q
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Search query
+        - name: detail
+          in: query
+          schema:
+            type: string
+            enum: [abstract, overview, full]
+          description: Detail level for episode summaries
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum number of episodes to return
+        - name: start_at
+          in: query
+          schema:
+            type: integer
+          description: Unix timestamp lower bound for time range filter
+        - name: end_at
+          in: query
+          schema:
+            type: integer
+          description: Unix timestamp upper bound for time range filter
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Episode search results
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [episodes]
+                properties:
+                  episodes:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/EpisodeSummary'
+        '400':
+          description: Missing search query
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/episodes/summarize:
+    post:
+      tags: [episodic]
+      summary: Summarize a specific session episode
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [session_id]
+              properties:
+                session_id:
+                  type: string
+                  description: Session ID to summarize
+                detailLevel:
+                  type: string
+                  enum: [abstract, overview, full]
+                  description: Detail level for the summary
+                scope:
+                  $ref: '#/components/schemas/Scope'
+      responses:
+        '200':
+          description: Episode summary
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [episode]
+                properties:
+                  episode:
+                    $ref: '#/components/schemas/EpisodeSummary'
+  /v1/reflect:
+    post:
+      tags: [episodic]
+      summary: Synthesize information across episodic and declarative memory
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [query]
+              properties:
+                query:
+                  type: string
+                  description: Reflection query
+                detailLevel:
+                  type: string
+                  enum: [abstract, overview, full]
+                includeDeclarative:
+                  type: boolean
+                  description: Include declarative knowledge in synthesis
+                includeEpisodic:
+                  type: boolean
+                  description: Include episodic memory in synthesis
+                limit:
+                  type: integer
+                  description: Maximum number of sources to include
+                timeRange:
+                  type: object
+                  properties:
+                    start_at:
+                      type: integer
+                      description: Unix timestamp lower bound
+                    end_at:
+                      type: integer
+                      description: Unix timestamp upper bound
+                scope:
+                  $ref: '#/components/schemas/Scope'
+      responses:
+        '200':
+          description: Reflection result
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ReflectResult'
+  /v1/memory:
+    get:
+      tags: [cognitive]
+      summary: Search memory using the cognitive taxonomy
+      parameters:
+        - name: q
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Search query
+        - name: types
+          in: query
+          schema:
+            type: string
+          description: Comma-separated cognitive types (episodic, semantic, procedural, working)
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum number of results
+        - name: minimumTrustScore
+          in: query
+          schema:
+            type: number
+          description: Minimum trust score filter
+        - name: activeOnly
+          in: query
+          schema:
+            type: boolean
+          description: Only return active memories (default true)
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Cognitive search results
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CognitiveSearchResult'
+        '400':
+          description: Missing search query
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/profile:
+    get:
+      tags: [profiles]
+      summary: Get a materialized profile view for the current scope
+      parameters:
+        - name: view
+          in: query
+          schema:
+            type: string
+            enum: [user, operator, workspace]
+          description: Profile view type (default user)
+        - name: min_trust
+          in: query
+          schema:
+            type: number
+          description: Minimum trust score filter
+        - name: includeProvisional
+          in: query
+          schema:
+            type: boolean
+          description: Include provisional knowledge entries (default false — profiles surface trusted knowledge by default)
+        - name: includeDisputed
+          in: query
+          schema:
+            type: boolean
+          description: Include disputed knowledge entries (default false)
+        - name: sections
+          in: query
+          schema:
+            type: string
+          description: Comma-separated profile sections to include
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Materialized profile
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [profile]
+                properties:
+                  profile:
+                    $ref: '#/components/schemas/Profile'
+  /v1/playbooks:
+    get:
+      tags: [playbooks]
+      summary: List or search playbooks
+      description: Without q param, lists active playbooks. With q param, searches by query.
+      parameters:
+        - name: q
+          in: query
+          schema:
+            type: string
+          description: Search query (optional — omit to list all active playbooks)
+        - name: limit
+          in: query
+          schema:
+            type: integer
+          description: Maximum results (for search)
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: Playbooks (with optional rank field when searching)
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [playbooks]
+                properties:
+                  playbooks:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Playbook'
+    post:
+      tags: [playbooks]
+      summary: Create a new playbook
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NewPlaybookRequest'
+      responses:
+        '201':
+          description: Playbook created
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [playbook]
+                properties:
+                  playbook:
+                    $ref: '#/components/schemas/Playbook'
+  /v1/playbooks/from-task:
+    post:
+      tags: [playbooks]
+      summary: Create a playbook from a completed task
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [title, description, sessionId]
+              properties:
+                title:
+                  type: string
+                  description: Playbook title
+                description:
+                  type: string
+                  description: Playbook description
+                sessionId:
+                  type: string
+                  description: Session ID containing the task to extract
+                tags:
+                  type: array
+                  items:
+                    type: string
+                sourceWorkingMemoryId:
+                  type: integer
+                  description: Optional working memory ID that triggered extraction
+                scope:
+                  $ref: '#/components/schemas/Scope'
+      responses:
+        '201':
+          description: Playbook created from task
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [playbook]
+                properties:
+                  playbook:
+                    $ref: '#/components/schemas/Playbook'
+  /v1/playbooks/{playbookId}:
+    get:
+      tags: [playbooks]
+      summary: Get a playbook by ID
+      parameters:
+        - name: playbookId
+          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: Playbook details
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [playbook]
+                properties:
+                  playbook:
+                    $ref: '#/components/schemas/Playbook'
+        '404':
+          description: Playbook not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+    put:
+      tags: [playbooks]
+      summary: Update a playbook
+      parameters:
+        - name: playbookId
+          in: path
+          required: true
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                title:
+                  type: string
+                description:
+                  type: string
+                instructions:
+                  type: string
+                references:
+                  type: array
+                  items:
+                    type: string
+                templates:
+                  type: array
+                  items:
+                    type: string
+                scripts:
+                  type: array
+                  items:
+                    type: string
+                assets:
+                  type: array
+                  items:
+                    type: string
+                tags:
+                  type: array
+                  items:
+                    type: string
+                status:
+                  type: string
+                  enum: [draft, active, deprecated, archived]
+                scope:
+                  $ref: '#/components/schemas/Scope'
+      responses:
+        '200':
+          description: Updated playbook
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [playbook]
+                properties:
+                  playbook:
+                    $ref: '#/components/schemas/Playbook'
+        '404':
+          description: Playbook not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/playbooks/{playbookId}/revise:
+    post:
+      tags: [playbooks]
+      summary: Revise a playbook's instructions
+      parameters:
+        - name: playbookId
+          in: path
+          required: true
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [instructions, revisionReason]
+              properties:
+                instructions:
+                  type: string
+                  description: New instructions
+                revisionReason:
+                  type: string
+                  description: Reason for the revision
+                sourceSessionId:
+                  type: string
+                  description: Optional session ID that triggered the revision
+                scope:
+                  $ref: '#/components/schemas/Scope'
+      responses:
+        '200':
+          description: Revised playbook with revision record
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [playbook, revision]
+                properties:
+                  playbook:
+                    $ref: '#/components/schemas/Playbook'
+                  revision:
+                    $ref: '#/components/schemas/PlaybookRevision'
+  /v1/playbooks/{playbookId}/use:
+    post:
+      tags: [playbooks]
+      summary: Record a playbook usage
+      parameters:
+        - name: playbookId
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Usage recorded
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [recorded, playbook]
+                properties:
+                  recorded:
+                    type: boolean
+                  playbook:
+                    $ref: '#/components/schemas/Playbook'
+        '404':
+          description: Playbook not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/associations:
+    post:
+      tags: [associations]
+      summary: Create an association between two memory artifacts
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [source_kind, source_id, target_kind, target_id, association_type]
+              properties:
+                source_kind:
+                  type: string
+                  enum: [knowledge, playbook, working_memory, work_item]
+                source_id:
+                  type: integer
+                target_kind:
+                  type: string
+                  enum: [knowledge, playbook, working_memory, work_item]
+                target_id:
+                  type: integer
+                association_type:
+                  type: string
+                  enum: [related_to, supports, contradicts, supersedes, depends_on, solves, applies_to, derived_from]
+                confidence:
+                  type: number
+                auto_generated:
+                  type: boolean
+      responses:
+        '201':
+          description: Association created
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [association]
+                properties:
+                  association:
+                    $ref: '#/components/schemas/Association'
+  /v1/associations/{kind}/{id}:
+    get:
+      tags: [associations]
+      summary: Get associations for a memory artifact
+      parameters:
+        - name: kind
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [knowledge, playbook, working_memory, work_item]
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Associations from and to the artifact
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  from:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Association'
+                  to:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Association'
+  /v1/associations/traverse:
+    post:
+      tags: [associations]
+      summary: Traverse association graph with bounded BFS
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [kind, id]
+              properties:
+                kind:
+                  type: string
+                  enum: [knowledge, playbook, working_memory, work_item]
+                id:
+                  type: integer
+                maxDepth:
+                  type: integer
+                  default: 2
+                maxNodes:
+                  type: integer
+                  default: 20
+      responses:
+        '200':
+          description: Association graph
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [nodes, edges]
+                properties:
+                  nodes:
+                    type: array
+                    items:
+                      type: object
+                      required: [kind, id]
+                      properties:
+                        kind:
+                          type: string
+                        id:
+                          type: integer
+                  edges:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Association'
+  /v1/associations/{id}:
+    delete:
+      tags: [associations]
+      summary: Delete an association
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Association deleted
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [deleted]
                 properties:
-                  userTurnId:
+                  deleted:
+                    type: boolean
+  /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
-                  assistantTurnId:
+  /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
-                  compacted:
-                    type: boolean
-  /v1/context:
-    get:
-      tags: [retrieval]
-      summary: Assemble prompt-ready context
+  /v1/work-items/{id}:
+    post:
+      tags: [ingestion]
+      summary: Update a work item
       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'
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                title: { type: string }
+                detail: { type: string, nullable: true }
+                status:
+                  type: string
+                  enum: [open, in_progress, blocked, done]
+                visibility_class:
+                  type: string
+                  enum: [private, shared_collaboration, workspace, tenant]
+                expectedVersion:
+                  type: integer
       responses:
         '200':
-          description: Assembled context
+          description: Updated work item
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ContextResponse'
-  /v1/search:
-    get:
-      tags: [retrieval]
-      summary: Search turns and knowledge
+                type: object
+                properties:
+                  workItem:
+                    type: object
+  /v1/work-items/{id}/claim:
+    post:
+      tags: [ingestion]
+      summary: Claim a work item for an actor
       parameters:
-        - name: q
-          in: query
+        - name: id
+          in: path
           required: true
-          schema:
-            type: string
-        - name: limit
-          in: query
           schema:
             type: integer
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [actor]
+              properties:
+                actor:
+                  $ref: '#/components/schemas/ActorRef'
+                lease_seconds:
+                  type: integer
+      responses:
+        '200':
+          description: Claim result
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  claim:
+                    $ref: '#/components/schemas/WorkClaim'
+  /v1/work-claims:
+    get:
+      tags: [retrieval]
+      summary: List current work claims
+      parameters:
         - $ref: '#/components/parameters/ScopeTenant'
         - $ref: '#/components/parameters/ScopeSystem'
         - $ref: '#/components/parameters/ScopeWorkspace'
@@ -358,32 +2024,118 @@ paths:
         - $ref: '#/components/parameters/ScopeId'
       responses:
         '200':
-          description: Search results
+          description: Work claims
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/SearchResponse'
-        '400':
-          description: Missing search query
+                type: object
+                properties:
+                  claims:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/WorkClaim'
+  /v1/work-claims/{id}/renew:
+    post:
+      tags: [ingestion]
+      summary: Renew a work claim
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: integer }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [actor]
+              properties:
+                actor:
+                  $ref: '#/components/schemas/ActorRef'
+                lease_seconds:
+                  type: integer
+      responses:
+        '200':
+          description: Renewed claim
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-  /v1/search/cross-scope:
+                type: object
+                properties:
+                  claim:
+                    $ref: '#/components/schemas/WorkClaim'
+  /v1/work-claims/{id}/release:
+    post:
+      tags: [ingestion]
+      summary: Release a work claim
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: integer }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [actor]
+              properties:
+                actor:
+                  $ref: '#/components/schemas/ActorRef'
+                reason:
+                  type: string
+      responses:
+        '200':
+          description: Released claim
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  claim:
+                    $ref: '#/components/schemas/WorkClaim'
+  /v1/work-items/{id}/handoffs:
+    post:
+      tags: [ingestion]
+      summary: Create a work-item handoff
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: integer }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [from_actor, to_actor, summary]
+              properties:
+                from_actor:
+                  $ref: '#/components/schemas/ActorRef'
+                to_actor:
+                  $ref: '#/components/schemas/ActorRef'
+                summary:
+                  type: string
+                context_bundle_ref:
+                  type: string
+      responses:
+        '201':
+          description: Created handoff
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  handoff:
+                    $ref: '#/components/schemas/HandoffRecord'
+  /v1/handoffs:
     get:
       tags: [retrieval]
-      summary: Search knowledge across inherited or shared scopes
+      summary: List pending handoffs
       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'
@@ -391,57 +2143,134 @@ paths:
         - $ref: '#/components/parameters/ScopeId'
       responses:
         '200':
-          description: Cross-scope search results
+          description: Pending handoffs
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/SearchResponse'
-        '400':
-          description: Missing search query
+                type: object
+                properties:
+                  handoffs:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/HandoffRecord'
+  /v1/handoffs/{id}/accept:
+    post:
+      tags: [ingestion]
+      summary: Accept a handoff
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: integer }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [actor]
+              properties:
+                actor:
+                  $ref: '#/components/schemas/ActorRef'
+                reason:
+                  type: string
+      responses:
+        '200':
+          description: Accepted handoff
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Error'
-  /v1/facts:
+                type: object
+                properties:
+                  handoff:
+                    $ref: '#/components/schemas/HandoffRecord'
+  /v1/handoffs/{id}/reject:
     post:
       tags: [ingestion]
-      summary: Insert durable knowledge directly
+      summary: Reject a handoff
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: integer }
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/FactRequest'
+              type: object
+              required: [actor]
+              properties:
+                actor:
+                  $ref: '#/components/schemas/ActorRef'
+                reason:
+                  type: string
       responses:
-        '201':
-          description: Fact stored
+        '200':
+          description: Rejected handoff
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  knowledgeId:
-                    type: integer
-  /v1/work:
+                  handoff:
+                    $ref: '#/components/schemas/HandoffRecord'
+  /v1/handoffs/{id}/cancel:
     post:
       tags: [ingestion]
-      summary: Track an objective or unresolved work item
+      summary: Cancel a handoff
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: integer }
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/WorkRequest'
+              type: object
+              required: [actor]
+              properties:
+                actor:
+                  $ref: '#/components/schemas/ActorRef'
+                reason:
+                  type: string
       responses:
-        '201':
-          description: Work item stored
+        '200':
+          description: Canceled handoff
           content:
             application/json:
               schema:
                 type: object
                 properties:
-                  workItemId:
-                    type: integer
+                  handoff:
+                    $ref: '#/components/schemas/HandoffRecord'
+  /v1/changes/stream:
+    get:
+      tags: [retrieval]
+      summary: Stream durable memory changes as SSE
+      parameters:
+        - name: cursor
+          in: query
+          schema: { type: string }
+        - name: session_id
+          in: query
+          schema: { type: string }
+        - name: entity_kind
+          in: query
+          schema: { type: string }
+        - name: entity_id
+          in: query
+          schema: { type: string }
+        - $ref: '#/components/parameters/ScopeTenant'
+        - $ref: '#/components/parameters/ScopeSystem'
+        - $ref: '#/components/parameters/ScopeWorkspace'
+        - $ref: '#/components/parameters/ScopeCollaboration'
+        - $ref: '#/components/parameters/ScopeId'
+      responses:
+        '200':
+          description: SSE stream of change events
   /v1/compact:
     post:
       tags: [maintenance]
@@ -494,6 +2323,10 @@ paths:
                     type: integer
                   deletedWorkItems:
                     type: integer
+                  deletedAssociationIds:
+                    type: array
+                    items:
+                      type: integer
   /v1/health:
     get:
       tags: [observability]