openapi.yaml

openapi: "3.0.3"
info:
  title: Engram Memory API
  description: |
    HTTP API for the Engram memory graph system.

    Engram stores memories as a four-tier graph:
    - **Episodes** (Tier 1): Raw ingested messages and events
    - **Entities** (Tier 2): Named entities extracted from episodes
    - **Engrams** (Tier 3): Consolidated memories built from episode clusters
    - **Schemas** (Tier 4): Cross-cutting pattern templates extracted from L2+ engrams

    All `/v1/*` endpoints require Bearer token authentication.
    The `/health` endpoint is public.

    ## Identity Configuration

    Set `identity` in `engram.yaml` to enable role-aware memory consolidation.
    When configured, the consolidation pipeline labels episode fragments by role
    (bot, owner, or third party) so memories are generated with correct attribution.

    ```yaml
    identity:
      name: "Bud"          # Bot display name; matches episode.author
      author_id: "bud"     # Matches episode.author_id set by callers
      owner_ids:            # Optional; enables owner-specific framing
        - "thunder"
    ```

    `POST /v1/thoughts` automatically stamps `author`/`author_id` from the
    identity config so the bot's internal monologue is correctly attributed.

    Env var overrides: `ENGRAM_IDENTITY_NAME`, `ENGRAM_IDENTITY_AUTHOR_ID`.
  version: "0.1.0"
  license:
    name: MIT

servers:
  - url: http://localhost:8080
    description: Local development

security:
  - bearerAuth: []

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        API key passed as Bearer token. Only required when `server.api_key` is set
        in the server config. If no key is configured, auth is disabled and all
        `/v1/*` requests are accepted without a header.

  schemas:
    Episode:
      type: object
      properties:
        id:
          type: string
          description: 32-char BLAKE3 hex ID; use any 5+ char prefix to reference
          example: "a3f2b9c1d4e7f0a2b5c8d1e4f7a0b3c6"
        content:
          type: string
        token_count:
          type: integer
          description: Pre-computed token count
        source:
          type: string
          example: "discord"
        author:
          type: string
        author_id:
          type: string
        channel:
          type: string
        timestamp_event:
          type: string
          format: date-time
          description: When the event occurred
        timestamp_ingested:
          type: string
          format: date-time
          description: When the episode was stored
        dialogue_act:
          type: string
        entropy_score:
          type: number
          format: double
        embedding:
          type: array
          items:
            type: number
            format: double
          description: Vector embedding (omitted by default)
        reply_to:
          type: string
          description: ID of episode this replies to
        authorization_checked:
          type: boolean
        has_authorization:
          type: boolean
        created_at:
          type: string
          format: date-time

    Entity:
      type: object
      properties:
        id:
          type: string
          description: Canonical key — type:name in lowercase (e.g. person:alice)
          example: "person:alice"
        name:
          type: string
          example: "Alice"
        type:
          $ref: "#/components/schemas/EntityType"
        salience:
          type: number
          format: double
        embedding:
          type: array
          items:
            type: number
            format: double
          description: Vector embedding (omitted by default)
        aliases:
          type: array
          items:
            type: string
        summary:
          type: string
          description: Pyramid summary (populated when level>0 is requested)
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    Engram:
      type: object
      properties:
        id:
          type: string
          description: 32-char BLAKE3 hex ID; use any 5+ char prefix to reference
          example: "c9d4e8f1a2b3c4d5e6f7a8b9c0d1e2f3"
        summary:
          type: string
          description: Consolidated summary of source episodes
        level:
          type: integer
          description: Compression level applied to summary (0 = stored verbatim)
        depth:
          type: integer
          description: "Hierarchy depth: 0 = L1 (built from episodes), 1 = L2 (from L1s), etc."
        topic:
          type: string
        engram_type:
          $ref: "#/components/schemas/EngramType"
        activation:
          type: number
          format: double
          description: Current activation level (0.0–1.0)
        strength:
          type: integer
          description: Number of reinforcements
        embedding:
          type: array
          items:
            type: number
            format: double
          description: Vector embedding (omitted by default)
        event_time:
          type: string
          format: date-time
          description: MAX(timestamp_event) of source episodes
        created_at:
          type: string
          format: date-time
        last_accessed:
          type: string
          format: date-time
        labile_until:
          type: string
          format: date-time
          description: If set, engram is in reconsolidation window until this time
        source_ids:
          type: array
          items:
            type: string
          description: IDs of source episodes (populated on retrieval)
        entity_ids:
          type: array
          items:
            type: string
          description: IDs of linked entities (populated on retrieval)
        schema_ids:
          type: array
          items:
            type: string
          description: IDs of matched schemas (populated on retrieval)

    EngramType:
      type: string
      enum:
        - knowledge
        - operational
      description: |
        - `knowledge`: Facts, decisions, preferences — long-lived
        - `operational`: Meeting reminders, state syncs, deploys — short-lived

    EntityType:
      type: string
      enum:
        - PERSON
        - ORG
        - GPE
        - LOC
        - FAC
        - PRODUCT
        - EVENT
        - WORK_OF_ART
        - LAW
        - LANGUAGE
        - NORP
        - DATE
        - TIME
        - MONEY
        - PERCENT
        - QUANTITY
        - CARDINAL
        - ORDINAL
        - EMAIL
        - PET
        - TECHNOLOGY
        - OTHER
      description: OntoNotes-compatible entity type with custom extensions

    EngramContextResponse:
      type: object
      properties:
        engram:
          $ref: "#/components/schemas/Engram"
        source_episodes:
          type: array
          items:
            $ref: "#/components/schemas/Episode"
        linked_entities:
          type: array
          items:
            $ref: "#/components/schemas/Entity"

    Schema:
      type: object
      description: |
        A cross-cutting pattern template extracted from L2+ engrams.
        Not a summary of what happened — a template for what class of event this is,
        with generalizations extracted from multiple instances.
      properties:
        id:
          type: string
          description: 32-char BLAKE3 hex ID; use any 5+ char prefix to reference
        name:
          type: string
          description: Short human-readable label (e.g. "Memory System Debugging")
        content:
          type: string
          description: |
            Full semi-structured prose with PATTERN, GENERALIZATIONS, INSTANCES, etc.
            When `?level=N` is requested, replaced by a precomputed N-word summary of
            the GENERALIZATIONS section.
        is_labile:
          type: boolean
          description: If true, needs reconsolidation at the next induction run
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        instances:
          type: array
          items:
            $ref: "#/components/schemas/SchemaInstance"
          description: Engrams that matched this schema (populated on retrieval)

    SchemaInstance:
      type: object
      description: Records that a specific engram matched a schema, with extracted slot values.
      properties:
        schema_id:
          type: string
        engram_id:
          type: string
        slot_values:
          type: object
          additionalProperties:
            type: string
          description: "Extracted slot values keyed by slot name (e.g. {\"trigger\": \"...\", \"fix\": \"...\"})"
        is_anomaly:
          type: boolean
          description: True if the instance deviates from the schema pattern
        matched_at:
          type: string
          format: date-time

    SchemaSummaryCard:
      type: object
      description: Lightweight schema representation returned by POST /v1/schemas/search.
      properties:
        id:
          type: string
        name:
          type: string
        summary:
          type: string
          description: Precomputed summary at the requested compression level
        level:
          type: integer
          description: Compression level applied (words)

    ErrorResponse:
      type: object
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: Machine-readable error code
          example: "missing_field"

paths:

  /health:
    get:
      summary: Health check
      description: Returns server status. No authentication required.
      security: []
      operationId: getHealth
      tags:
        - Health
      responses:
        "200":
          description: Server is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "ok"
                  time:
                    type: string
                    format: date-time

  /health/detailed:
    get:
      summary: Detailed health check
      description: |
        Returns service status, DB aggregate counts, and service capability flags.
        No authentication required.
      security: []
      operationId: getHealthDetailed
      tags:
        - Health
      responses:
        "200":
          description: Server is healthy with detailed stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "ok"
                  time:
                    type: string
                    format: date-time
                  db:
                    type: object
                    properties:
                      total_engrams:
                        type: integer
                        example: 490
                      engrams_by_depth:
                        type: object
                        description: Engram count keyed by depth level ("0" = L0, "1" = L1, "2" = L2+)
                        additionalProperties:
                          type: integer
                        example: {"0": 12, "1": 210, "2": 268}
                      engrams_missing_pyramids:
                        type: integer
                        description: Engrams with no precomputed pyramid summary at level 4 or above
                        example: 0
                      total_episodes:
                        type: integer
                        example: 3821
                      episodes_without_summaries:
                        type: integer
                        description: Episodes with no precomputed pyramid summaries at any level
                        example: 14
                      total_entities:
                        type: integer
                        example: 87
                      total_schemas:
                        type: integer
                        example: 9
                  services:
                    type: object
                    description: Flags indicating which optional capabilities are active
                    properties:
                      embedding:
                        type: boolean
                      ner:
                        type: boolean
                      consolidation:
                        type: boolean
                      compression_queue:
                        type: boolean
                      schema_induction:
                        type: boolean
                    example:
                      embedding: true
                      ner: false
                      consolidation: true
                      compression_queue: true
                      schema_induction: true
        "500":
          $ref: "#/components/responses/InternalError"

  /v1/episodes/search:
    post:
      summary: Search episodes by text or fetch by IDs
      description: |
        Supports two modes — exactly one of `query` or `ids` must be provided.

        **Text search mode** (`query`): Full-text substring search over episode content.

        **ID lookup mode** (`ids`): Fetch specific episodes by ID in request order. Supports
        the same `level` and `detail` options as text search. Unknown IDs are silently skipped.

        Returns `[{id, content}]` by default; add `"detail": "full"` for all fields.
      operationId: searchEpisodes
      tags:
        - Episodes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: Text substring search over episode content (mutually exclusive with `ids`)
                ids:
                  type: array
                  items:
                    type: string
                  description: Fetch episodes by these IDs in order (mutually exclusive with `query`)
                limit:
                  type: integer
                  default: 10
                  description: Maximum results for text search mode (default 10; ignored in ID lookup mode)
                detail:
                  type: string
                  enum: [full]
                  description: "Return full fields instead of minimal. Use `\"detail\": \"full\"`."
                level:
                  type: integer
                  default: 0
                  minimum: 0
                  description: |
                    Apply pyramid compression to the `content` field before returning.
                    Valid targets: 4, 8, 16, 32, 64 (approx word count). 0 = verbatim (default).
      responses:
        "200":
          description: List of matching episodes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Episode"
        "400":
          description: Missing or invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/episodes:
    get:
      summary: List episodes
      description: |
        List raw episodes with optional filtering.

        **Default response** is minimal: `[{id, content}]`.
        Add `?detail=full` for all fields (embeddings are never returned).

        All filters compose freely: `?channel=X&unconsolidated=true&before={id}&level=8` is valid.
      operationId: listEpisodes
      tags:
        - Episodes
      parameters:
        - name: channel
          in: query
          schema:
            type: string
          description: Filter by channel value
        - name: unconsolidated
          in: query
          schema:
            type: boolean
          description: "If true, return only episodes not yet part of any engram"
        - name: before
          in: query
          schema:
            type: string
          description: |
            Cursor-based pagination. Return only episodes older than this episode ID
            (full 32-char ID or 5-char prefix). Returns 400 if the ID is not found.
        - name: level
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
          description: |
            Apply pyramid compression to the `content` field before returning.
            Valid targets: 4, 8, 16, 32, 64 (approx word count).
            Episodes with no pre-generated summary at the requested level return raw content.
            0 = verbatim (default).
        - name: detail
          in: query
          schema:
            type: string
            enum: [full]
          description: "Return full fields instead of minimal. Use `detail=full`."
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
          description: Maximum results (default 50)
      responses:
        "200":
          description: List of episodes (minimal by default)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Episode"
        "400":
          description: Invalid `before` episode ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    post:
      summary: Ingest an episode
      description: |
        Store a raw episode (message, event, observation) in the memory graph.

        If `embedding` is not provided and an embed service is configured,
        the embedding is computed automatically. Named entities are extracted
        in the background if a NER service is configured.
      operationId: ingestEpisode
      tags:
        - Ingest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - content
                - source
              properties:
                content:
                  type: string
                  description: The episode text content
                source:
                  type: string
                  description: Origin source identifier (e.g. "discord", "calendar")
                  example: "discord"
                author:
                  type: string
                author_id:
                  type: string
                channel:
                  type: string
                timestamp_event:
                  type: string
                  format: date-time
                  description: When the event occurred; defaults to now if omitted
                reply_to:
                  type: string
                  description: ID of the episode this is a reply to
                embedding:
                  type: array
                  items:
                    type: number
                    format: double
                  description: Pre-computed embedding; computed automatically if omitted
      responses:
        "201":
          description: Episode stored
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: 32-char BLAKE3 hex ID
        "400":
          description: Missing required field or malformed JSON
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/thoughts:
    post:
      summary: Ingest a thought
      description: |
        Store a free-form thought or observation. Shorthand for ingesting
        an episode with `source: "thought"` — no source or author metadata required.

        `author`/`author_id` are automatically stamped from the identity config
        (if configured). Named entities are extracted in the background if a NER
        service is configured, identical to `POST /v1/episodes`.
      operationId: ingestThought
      tags:
        - Ingest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - content
              properties:
                content:
                  type: string
      responses:
        "201":
          description: Thought stored
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        "400":
          description: Missing content
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/episodes/count:
    get:
      summary: Count episodes
      description: |
        Returns the episode count matching optional filters.

        | Request | Returns |
        |---------|---------|
        | (no params) | Total episode count |
        | `?unconsolidated=true` | Global unconsolidated count |
        | `?channel=X` | Total for channel |
        | `?channel=X&unconsolidated=true` | Unconsolidated count for channel |
      operationId: countEpisodes
      tags:
        - Episodes
      parameters:
        - name: channel
          in: query
          schema:
            type: string
          description: Filter by channel value
        - name: unconsolidated
          in: query
          schema:
            type: boolean
          description: "If true, count only unconsolidated episodes"
      responses:
        "200":
          description: Episode count
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/episodes/summaries:
    post:
      summary: Batch fetch episode pyramid summaries
      description: |
        Returns pyramid summaries for a set of episode IDs at the requested compression level.
        Episodes with no pre-generated summary at the requested level are absent from the result.
        Valid levels: 4, 8, 16, 32, 64.
      operationId: batchEpisodeSummaries
      tags:
        - Episodes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - episode_ids
                - level
              properties:
                episode_ids:
                  type: array
                  items:
                    type: string
                  description: List of episode IDs (full or 5-char prefix)
                level:
                  type: integer
                  description: "Compression level: 4, 8, 16, 32, or 64"
                  example: 8
      responses:
        "200":
          description: Map of episode ID to summary string
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
        "400":
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/episodes/{id}/edges:
    post:
      summary: Add an edge between episodes
      description: |
        Create a directed structural edge from `{id}` to another episode.
        Edge types: `REPLIES_TO`, `FOLLOWS`, `RELATED_TO`. Defaults to `FOLLOWS`.
      operationId: addEpisodeEdge
      tags:
        - Episodes
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Source episode ID (full or 5-char prefix)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - to_id
              properties:
                to_id:
                  type: string
                  description: Target episode ID
                edge_type:
                  type: string
                  description: "Edge type. Default: FOLLOWS"
                  example: "REPLIES_TO"
                confidence:
                  type: number
                  format: double
                  description: "Edge confidence (0.0–1.0). Default: 1.0"
      responses:
        "201":
          description: Edge created
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
        "400":
          description: Missing to_id or invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/consolidate:
    post:
      summary: Trigger consolidation
      description: |
        Run the consolidation pipeline: clusters recent episodes by semantic
        similarity, generates summaries, and promotes them to engrams.
        Returns 503 if no consolidation service is configured.
      operationId: consolidate
      tags:
        - Consolidation
      responses:
        "200":
          description: Consolidation complete
          content:
            application/json:
              schema:
                type: object
                properties:
                  engrams_created:
                    type: integer
                  duration_ms:
                    type: integer
                    format: int64
        "500":
          description: Consolidation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: Consolidation not configured
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/engrams/search:
    post:
      summary: Search engrams by semantic query or fetch by IDs
      description: |
        Supports two modes — exactly one of `query` or `ids` must be provided.

        **Text search mode** (`query`): Semantic search via spreading activation. Retrieval uses
        three concurrent seed triggers: semantic KNN, lexical BM25, and entity regex matching.
        When a NER service is configured, entities extracted from the query string also seed
        the activation graph (fourth trigger). Returns results ranked by activation.

        **ID lookup mode** (`ids`): Fetch specific engrams by ID in request order. Supports the
        same `level` and `detail` options as text search. Unknown IDs are silently skipped.

        **Default response** is minimal: `[{id, summary}]`.
        Add `"detail": "full"` for all fields. Both modes populate `schema_ids` on results.
      operationId: searchEngrams
      tags:
        - Engrams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: Natural language search query (mutually exclusive with `ids`)
                ids:
                  type: array
                  items:
                    type: string
                  description: Fetch engrams by these IDs in order (mutually exclusive with `query`)
                limit:
                  type: integer
                  default: 10
                  description: Maximum results for text search mode (default 10; ignored in ID lookup mode)
                detail:
                  type: string
                  enum: [full]
                  description: "Return full fields instead of minimal. Use `\"detail\": \"full\"`."
                level:
                  type: integer
                  default: 0
                  minimum: 0
                  description: "Summary compression level: 0 = verbatim (default); N = approx N-word summary"
      responses:
        "200":
          description: Ranked list of matching engrams (minimal by default)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Engram"
        "400":
          description: Missing or invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/engrams:
    get:
      summary: List engrams
      description: |
        List consolidated memory engrams.

        **Default response** is minimal: `[{id, summary}]`.
        Add `?detail=full` for all fields (embeddings are never returned).
      operationId: listEngrams
      tags:
        - Engrams
      parameters:
        - name: detail
          in: query
          schema:
            type: string
            enum: [full]
          description: "Return full fields instead of minimal. Use `detail=full`."
        - name: level
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
          description: "Summary compression level for all returned engrams: 0 = verbatim (default); N = approx N-word summary"
        - name: threshold
          in: query
          schema:
            type: number
            format: double
          description: Filter by minimum activation level
      responses:
        "200":
          description: List of engrams (minimal by default)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Engram"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/engrams/{id}:
    delete:
      summary: Delete an engram
      description: |
        Permanently delete an engram by its full ID or 5-character short ID.
        Cascades to associated summary records and edge links.
      operationId: deleteEngram
      tags:
        - Engrams
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Full engram ID or 5-char short ID
      responses:
        "204":
          description: Engram deleted
        "404":
          description: Engram not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    get:
      summary: Get an engram
      description: |
        Retrieve a single engram by its full ID or 5-character short ID.
        By default (`level=0`) returns the verbatim summary. Set `level=N`
        to get an approximately N-word pyramid summary (valid generation
        targets: 4, 8, 16, 32, 64; the nearest available level is used).
      operationId: getEngram
      tags:
        - Engrams
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Full engram ID or 5-char short ID
        - name: level
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
          description: "Summary compression level: 0 = verbatim (default); N = approx N-word summary"
        - name: detail
          in: query
          schema:
            type: string
            enum: [full]
          description: "Return full fields instead of minimal. Use `detail=full`."
      responses:
        "200":
          description: Engram object (minimal by default)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Engram"
        "404":
          description: Engram not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/engrams/{id}/context:
    get:
      summary: Get engram with full context
      description: |
        Returns the engram along with its source episodes and linked entities.
        Useful for understanding what the engram was derived from.

        **Default response** is minimal: engram/episode/entity objects are cards
        `{id, summary}` / `{id, content}` / `{id, name}`.
        Add `?detail=full` for all fields (embeddings are never returned).
      operationId: getEngramContext
      tags:
        - Engrams
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Full engram ID or 5-char short ID
        - name: detail
          in: query
          schema:
            type: string
            enum: [full]
          description: "Return full fields instead of minimal. Use `detail=full`."
      responses:
        "200":
          description: Engram with source episodes and entities
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EngramContextResponse"
        "404":
          description: Engram not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/engrams/{id}/reinforce:
    post:
      summary: Reinforce an engram
      description: |
        Boost the activation of an engram, simulating memory reconsolidation.
        Increases strength counter and resets the labile window.
        Optionally provide an updated embedding to shift the engram's semantic center.
      operationId: reinforceEngram
      tags:
        - Engrams
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Full engram ID or 5-char short ID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                embedding:
                  type: array
                  items:
                    type: number
                    format: double
                  description: Updated embedding for the engram
                alpha:
                  type: number
                  format: double
                  description: Reinforcement strength (0.0–1.0)
                  default: 0.3
      responses:
        "200":
          description: Engram reinforced
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/engrams/boost:
    post:
      summary: Batch boost engram activations
      description: |
        Boost activation for a set of engrams in one call. Useful after retrieval
        to reinforce memories that were accessed. Activation is capped at 1.0.
        If `boost` is omitted, defaults to `0.1`.
      operationId: boostEngrams
      tags:
        - Engrams
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - engram_ids
              properties:
                engram_ids:
                  type: array
                  items:
                    type: string
                  description: List of engram IDs to boost (full or 5-char prefix)
                boost:
                  type: number
                  format: double
                  default: 0.1
                  description: Additive activation increase per engram (capped at 1.0)
                threshold:
                  type: number
                  format: double
                  description: Only boost engrams whose current activation is above this threshold
      responses:
        "200":
          description: Boost applied
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
        "400":
          description: Missing or invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/episodes/{id}:
    get:
      summary: Get an episode
      description: |
        Retrieve a single episode by its full ID or 5-character short ID.

        **Default response** is minimal: `{id, content}`.
        Set `level=N` to replace `content` with an approximately N-word pyramid summary
        (valid generation targets: 4, 8, 16, 32, 64; episodes with no pre-generated
        summary at the requested level return raw content).
        Add `?detail=full` for all fields (embeddings are never returned).
      operationId: getEpisode
      tags:
        - Episodes
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Full episode ID or 5-char short ID
        - name: level
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
          description: |
            Apply pyramid compression to the `content` field before returning.
            Valid targets: 4, 8, 16, 32, 64 (approx word count).
            Episodes with no pre-generated summary at the requested level return raw content.
            0 = verbatim (default).
        - name: detail
          in: query
          schema:
            type: string
            enum: [full]
          description: "Return full fields instead of minimal. Use `detail=full`."
      responses:
        "200":
          description: Episode object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Episode"
        "404":
          description: Episode not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/entities/search:
    post:
      summary: Search entities by name
      description: |
        Text search over entity names and aliases. Returns `[{id, name}]` by default.
        Add `"detail": "full"` in the request body for all fields.
      operationId: searchEntities
      tags:
        - Entities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: Text search over entity names and aliases
                limit:
                  type: integer
                  default: 10
                  description: Maximum results (default 10)
                detail:
                  type: string
                  enum: [full]
                  description: "Return full fields instead of minimal. Use `\"detail\": \"full\"`."
                level:
                  type: integer
                  default: 0
                  minimum: 0
                  description: "Summary compression level: 0 = verbatim (default); N = approx N-word summary"
      responses:
        "200":
          description: List of matching entities
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Entity"
        "400":
          description: Missing or invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/entities:
    get:
      summary: List entities
      description: |
        List extracted named entities.

        **Default response** is minimal: `[{id, name}]`.
        Add `?detail=full` for all fields (embeddings are never returned).
      operationId: listEntities
      tags:
        - Entities
      parameters:
        - name: detail
          in: query
          schema:
            type: string
            enum: [full]
          description: "Return full fields instead of minimal. Use `detail=full`."
        - name: level
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
          description: "Summary compression level for all returned entities: 0 = verbatim (default); N = approx N-word summary"
        - name: type
          in: query
          schema:
            $ref: "#/components/schemas/EntityType"
          description: Filter by entity type
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
          description: Maximum results (default 100)
      responses:
        "200":
          description: List of entities
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Entity"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/entities/{id}:
    get:
      summary: Get an entity
      description: |
        Retrieve a single entity by its canonical ID (type:name).
        By default (`level=0`) returns the raw entity record. Set `level=N`
        to get an approximately N-word pyramid summary assembled from the
        entity's metadata and known relations (valid targets: 4, 8, 16, 32, 64).

        **Default response** is minimal: `{id, name}`.
        Add `?detail=full` for all fields (embeddings are never returned).
      operationId: getEntity
      tags:
        - Entities
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Entity ID (e.g. person:alice)
        - name: level
          in: query
          schema:
            type: integer
            default: 0
            minimum: 0
          description: "Summary compression level: 0 = raw entity (default); N = approx N-word summary"
        - name: detail
          in: query
          schema:
            type: string
            enum: [full]
          description: "Return full fields instead of minimal. Use `detail=full`."
      responses:
        "200":
          description: Entity object
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Entity"
        "404":
          description: Entity not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/entities/{id}/engrams:
    get:
      summary: List engrams linked to an entity
      description: |
        Returns all consolidated engrams that mention the given entity.
        Engrams are linked to entities during the consolidation pipeline when
        episode-entity associations (from NER at ingestion time) are present.

        **Default response** is minimal: `[{id, summary}]`.
        Add `?detail=full` for all fields (embeddings are never returned).
      operationId: getEntityEngrams
      tags:
        - Entities
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: "Entity ID (e.g. ent:Alice)"
        - name: detail
          in: query
          schema:
            type: string
            enum: [full]
          description: "Return full fields instead of minimal. Use `detail=full`."
      responses:
        "200":
          description: List of engrams linked to the entity
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Engram"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/activation/decay:
    post:
      summary: Decay activation
      description: |
        Apply exponential decay to all engram activation levels.
        Older, less-accessed engrams lose activation faster.
        Useful to run periodically to implement memory forgetting.
      operationId: decayActivation
      tags:
        - Activation
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                lambda:
                  type: number
                  format: double
                  description: Decay rate (higher = faster decay). Uses server default if omitted.
                floor:
                  type: number
                  format: double
                  description: Minimum activation floor. Uses server default if omitted.
      responses:
        "200":
          description: Decay applied
          content:
            application/json:
              schema:
                type: object
                properties:
                  updated:
                    type: integer
                    description: Number of engrams whose activation was updated
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/memory/flush:
    post:
      summary: Flush memory
      description: |
        Trigger consolidation and any pending cleanup. Equivalent to manually
        running consolidation. Useful before shutdown or testing.
      operationId: flushMemory
      tags:
        - Management
      responses:
        "200":
          description: Flush complete
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true

  /v1/memory/reset:
    delete:
      summary: Reset memory
      description: |
        **Destructive.** Clears all episodes, entities, engrams, and edges from the graph.
        Cannot be undone. Useful for testing.
      operationId: resetMemory
      tags:
        - Management
      responses:
        "200":
          description: Memory cleared
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
        "500":
          description: Reset error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/schemas:
    get:
      summary: List schemas
      description: |
        Returns all schemas ordered by `updated_at` descending.
        Embeddings are never returned. Content is the full semi-structured prose.
      operationId: listSchemas
      tags:
        - Schemas
      responses:
        "200":
          description: List of schemas
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    content:
                      type: string
                    is_labile:
                      type: boolean
                    created_at:
                      type: string
                      format: date-time
                    updated_at:
                      type: string
                      format: date-time
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/schemas/search:
    post:
      summary: Search schemas by IDs or semantic query
      description: |
        Supports two modes — exactly one of `ids` or `query` must be provided.

        **ID lookup mode** (`ids`): Returns a lightweight summary card for each schema ID, using
        precomputed summaries at the requested compression level. Results follow request order;
        unknown IDs are silently skipped.

        **Text search mode** (`query`): Semantic similarity search via embedding cosine distance.
        Returns schemas ranked by relevance (threshold 0.5). Use `limit` to control result count
        (default 10). Results include precomputed summaries at the requested `level`.
      operationId: searchSchemas
      tags:
        - Schemas
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: string
                  description: Schema IDs to fetch (mutually exclusive with `query`)
                query:
                  type: string
                  description: Semantic search query (mutually exclusive with `ids`)
                level:
                  type: integer
                  default: 32
                  description: "Compression level for the returned summary: 4, 8, 16, 32, 64 (default 32)"
                limit:
                  type: integer
                  default: 10
                  description: "Maximum results for text search mode (default 10; ignored in ID lookup mode)"
      responses:
        "200":
          description: List of schema summary cards in request order
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SchemaSummaryCard"
        "400":
          description: Missing or invalid request body
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: Embedding service not configured
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/schemas/{id}:
    get:
      summary: Get a schema
      description: |
        Returns a single schema with its instance list.

        Add `?level=N` to replace the `content` field with a precomputed N-word summary
        of the GENERALIZATIONS section (the most stable part of the schema). Valid levels:
        4, 8, 16, 32, 64. If no precomputed summary exists at that level, `content` is
        returned verbatim.
      operationId: getSchema
      tags:
        - Schemas
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Full schema ID or 5-char short ID
        - name: level
          in: query
          schema:
            type: integer
          description: "Return a precomputed summary at this compression level instead of full content"
      responses:
        "200":
          description: Schema with instance list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Schema"
        "400":
          description: Invalid ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "404":
          description: Schema not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
    delete:
      summary: Delete a schema
      description: Permanently deletes a schema and its instance annotations.
      operationId: deleteSchema
      tags:
        - Schemas
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Full schema ID or 5-char short ID
      responses:
        "200":
          description: Schema deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "deleted"
        "400":
          description: Invalid ID
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /v1/schemas/induce:
    post:
      summary: Trigger schema induction
      description: |
        Runs the schema induction pipeline asynchronously over all L2+ engrams. Requires
        at least 3 L2+ engrams; returns `{"started": false}` otherwise.

        Induction clusters engrams by activity type/pattern, then uses an LLM to extract
        cross-cutting schemas. Requires `llm` to be configured in `engram.yaml`.

        Returns HTTP 202 immediately when started; induction continues in the background.
        Run this manually to backfill `schema_summaries` after first deployment, or after
        a DB wipe. Otherwise induction runs automatically as part of consolidation.
      operationId: induceSchemas
      tags:
        - Schemas
      responses:
        "200":
          description: Not enough L2+ engrams to run induction
          content:
            application/json:
              schema:
                type: object
                properties:
                  started:
                    type: boolean
                    example: false
                  reason:
                    type: string
                    example: "not enough L2+ engrams (need at least 3)"
        "202":
          description: Induction started asynchronously
          content:
            application/json:
              schema:
                type: object
                properties:
                  started:
                    type: boolean
                    example: true
        "500":
          description: Database error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "503":
          description: Schema induction not configured (no LLM)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

tags:
  - name: Health
    description: Health check endpoint
  - name: Ingest
    description: Store new episodes and thoughts
  - name: Consolidation
    description: Run the consolidation pipeline
  - name: Engrams
    description: Access consolidated memories (Tier 3)
  - name: Episodes
    description: Access raw episode memories (Tier 1)
  - name: Entities
    description: Access extracted named entities (Tier 2)
  - name: Schemas
    description: Cross-cutting pattern templates extracted from L2+ engrams (Tier 4)
  - name: Activation
    description: Manage memory activation and forgetting
  - name: Management
    description: System management operations