@bluefly/openstandardagents 0.3.1 → 0.3.3

package/dist/spec/v0.3.3/runtime/memory-model.yaml

@@ -0,0 +1,871 @@
+# OSSA v0.3.3 - Agent Memory Model Specification
+# Defines memory types, providers, and interfaces for agent state management
+#
+# Related schemas:
+#   - ./runtime.yaml (agent lifecycle and execution)
+#   - ../schemas/agent-unified.yaml (agent specification)
+
+$schema: http://json-schema.org/draft-07/schema#
+$id: https://openstandardagents.org/schemas/v0.3.3/runtime/memory-model.yaml
+
+title: OSSA Agent Memory Model
+description: |
+  Memory model specification for OSSA agents defining:
+  - Short-term memory (conversation context, working memory)
+  - Long-term memory (persistent storage, knowledge base)
+  - Memory provider interface (pluggable backends)
+  - Memory lifecycle and garbage collection
+
+type: object
+required:
+  - apiVersion
+  - kind
+  - short_term
+  - long_term
+
+properties:
+  apiVersion:
+    type: string
+    const: ossa/v0.3.3
+    description: Memory model specification version
+
+  kind:
+    type: string
+    const: MemoryModel
+    description: Resource type for memory model
+
+  # ============================================
+  # SHORT-TERM MEMORY
+  # Conversation context and working memory
+  # ============================================
+  short_term:
+    type: object
+    description: |
+      Short-term memory for immediate context and working state.
+      Typically volatile and cleared between agent invocations.
+    required:
+      - enabled
+    properties:
+      enabled:
+        type: boolean
+        default: true
+        description: Enable short-term memory
+
+      provider:
+        type: string
+        description: Short-term memory provider
+        enum:
+          - in_memory
+          - redis
+          - memcached
+          - local_cache
+        default: in_memory
+
+      conversation_context:
+        type: object
+        description: Conversation history management
+        properties:
+          enabled:
+            type: boolean
+            default: true
+
+          max_messages:
+            type: integer
+            description: Maximum messages to retain
+            default: 100
+            minimum: 1
+            maximum: 10000
+
+          max_tokens:
+            type: integer
+            description: Maximum tokens in context window
+            default: 32000
+            minimum: 1000
+            maximum: 200000
+
+          truncation_strategy:
+            type: string
+            description: How to truncate when limit reached
+            enum:
+              - sliding_window
+              - summarize
+              - oldest_first
+              - importance_based
+            default: sliding_window
+
+          include_system_messages:
+            type: boolean
+            default: true
+            description: Include system messages in context
+
+          include_tool_results:
+            type: boolean
+            default: true
+            description: Include tool call results in context
+
+      working_memory:
+        type: object
+        description: Scratchpad for intermediate computations
+        properties:
+          enabled:
+            type: boolean
+            default: true
+
+          max_size_mb:
+            type: integer
+            description: Maximum working memory size in MB
+            default: 64
+            minimum: 1
+            maximum: 1024
+
+          ttl_seconds:
+            type: integer
+            description: Time-to-live for working memory entries
+            default: 3600
+            minimum: 60
+            maximum: 86400
+
+          namespaced:
+            type: boolean
+            default: true
+            description: Namespace working memory by agent/session
+
+      session_state:
+        type: object
+        description: Session-level state management
+        properties:
+          enabled:
+            type: boolean
+            default: true
+
+          session_ttl_seconds:
+            type: integer
+            description: Session expiration time
+            default: 3600
+            minimum: 60
+            maximum: 86400
+
+          persist_across_invocations:
+            type: boolean
+            default: false
+            description: Persist session state between agent runs
+
+          max_sessions:
+            type: integer
+            description: Maximum concurrent sessions per agent
+            default: 100
+            minimum: 1
+            maximum: 10000
+
+      connection:
+        $ref: '#/definitions/MemoryConnection'
+        description: Connection settings for short-term memory provider
+
+  # ============================================
+  # LONG-TERM MEMORY
+  # Persistent storage and knowledge base
+  # ============================================
+  long_term:
+    type: object
+    description: |
+      Long-term memory for persistent state, learned knowledge,
+      and cross-session information.
+    required:
+      - enabled
+    properties:
+      enabled:
+        type: boolean
+        default: true
+        description: Enable long-term memory
+
+      provider:
+        type: string
+        description: Long-term memory provider
+        enum:
+          - postgres
+          - mongodb
+          - sqlite
+          - dynamodb
+          - neo4j
+          - qdrant
+          - pinecone
+          - weaviate
+          - chromadb
+          - milvus
+          - redis
+          - file_system
+        default: postgres
+
+      storage_type:
+        type: string
+        description: Type of long-term storage
+        enum:
+          - relational
+          - document
+          - vector
+          - graph
+          - hybrid
+        default: hybrid
+
+      knowledge_base:
+        type: object
+        description: Structured knowledge storage
+        properties:
+          enabled:
+            type: boolean
+            default: true
+
+          schema:
+            type: string
+            description: Knowledge schema format
+            enum:
+              - json_schema
+              - rdf
+              - custom
+            default: json_schema
+
+          versioning:
+            type: boolean
+            default: true
+            description: Enable version history for knowledge
+
+          max_entries:
+            type: integer
+            description: Maximum knowledge entries
+            default: 100000
+            minimum: 100
+            maximum: 10000000
+
+      vector_store:
+        type: object
+        description: Vector embeddings for semantic search
+        properties:
+          enabled:
+            type: boolean
+            default: true
+
+          embedding_model:
+            type: string
+            description: Model for generating embeddings
+            default: '${EMBEDDING_MODEL:-text-embedding-3-small}'
+
+          embedding_dimensions:
+            type: integer
+            description: Embedding vector dimensions
+            default: 1536
+            minimum: 64
+            maximum: 4096
+
+          distance_metric:
+            type: string
+            description: Distance metric for similarity search
+            enum:
+              - cosine
+              - euclidean
+              - dot_product
+            default: cosine
+
+          index_type:
+            type: string
+            description: Vector index type
+            enum:
+              - flat
+              - hnsw
+              - ivf
+              - scann
+            default: hnsw
+
+          max_vectors:
+            type: integer
+            description: Maximum vectors to store
+            default: 1000000
+            minimum: 1000
+
+      conversation_history:
+        type: object
+        description: Persistent conversation archives
+        properties:
+          enabled:
+            type: boolean
+            default: true
+
+          retention_days:
+            type: integer
+            description: Days to retain conversation history
+            default: 90
+            minimum: 1
+            maximum: 3650
+
+          indexing:
+            type: boolean
+            default: true
+            description: Index conversations for search
+
+          summarization:
+            type: boolean
+            default: true
+            description: Auto-summarize old conversations
+
+      agent_state:
+        type: object
+        description: Persistent agent state across invocations
+        properties:
+          enabled:
+            type: boolean
+            default: true
+
+          checkpoint_interval_seconds:
+            type: integer
+            description: Interval for state checkpoints
+            default: 60
+            minimum: 10
+            maximum: 3600
+
+          max_checkpoints:
+            type: integer
+            description: Maximum checkpoints to retain
+            default: 10
+            minimum: 1
+            maximum: 100
+
+          compression:
+            type: boolean
+            default: true
+            description: Compress state checkpoints
+
+      learned_patterns:
+        type: object
+        description: Storage for learned behaviors and patterns
+        properties:
+          enabled:
+            type: boolean
+            default: true
+
+          feedback_integration:
+            type: boolean
+            default: true
+            description: Integrate user feedback
+
+          pattern_types:
+            type: array
+            items:
+              type: string
+              enum:
+                - task_completion
+                - error_recovery
+                - user_preferences
+                - tool_usage
+                - delegation_patterns
+            default:
+              - task_completion
+              - error_recovery
+
+          decay_enabled:
+            type: boolean
+            default: true
+            description: Enable pattern relevance decay
+
+          decay_half_life_days:
+            type: integer
+            description: Half-life for pattern decay
+            default: 30
+            minimum: 1
+            maximum: 365
+
+      connection:
+        $ref: '#/definitions/MemoryConnection'
+        description: Connection settings for long-term memory provider
+
+  # ============================================
+  # MEMORY PROVIDER INTERFACE
+  # Pluggable backend specification
+  # ============================================
+  provider_interface:
+    type: object
+    description: |
+      Standard interface that all memory providers MUST implement.
+      Enables pluggable memory backends with consistent API.
+    properties:
+      version:
+        type: string
+        const: '1.0'
+        description: Provider interface version
+
+      required_operations:
+        type: array
+        description: Operations all providers MUST implement
+        items:
+          $ref: '#/definitions/MemoryOperation'
+        default:
+          - name: get
+            description: Retrieve memory entry by key
+            parameters:
+              key:
+                type: string
+                required: true
+              namespace:
+                type: string
+                required: false
+            returns:
+              type: object
+              nullable: true
+
+          - name: set
+            description: Store memory entry
+            parameters:
+              key:
+                type: string
+                required: true
+              value:
+                type: any
+                required: true
+              ttl_seconds:
+                type: integer
+                required: false
+              namespace:
+                type: string
+                required: false
+            returns:
+              type: boolean
+
+          - name: delete
+            description: Remove memory entry
+            parameters:
+              key:
+                type: string
+                required: true
+              namespace:
+                type: string
+                required: false
+            returns:
+              type: boolean
+
+          - name: exists
+            description: Check if key exists
+            parameters:
+              key:
+                type: string
+                required: true
+              namespace:
+                type: string
+                required: false
+            returns:
+              type: boolean
+
+          - name: list
+            description: List keys matching pattern
+            parameters:
+              pattern:
+                type: string
+                required: true
+              namespace:
+                type: string
+                required: false
+              limit:
+                type: integer
+                required: false
+            returns:
+              type: array
+              items:
+                type: string
+
+          - name: clear
+            description: Clear all entries in namespace
+            parameters:
+              namespace:
+                type: string
+                required: false
+            returns:
+              type: boolean
+
+      optional_operations:
+        type: array
+        description: Operations providers MAY implement
+        items:
+          $ref: '#/definitions/MemoryOperation'
+        default:
+          - name: search
+            description: Semantic search in vector store
+            parameters:
+              query:
+                type: string
+                required: true
+              top_k:
+                type: integer
+                required: false
+              filters:
+                type: object
+                required: false
+            returns:
+              type: array
+
+          - name: batch_get
+            description: Retrieve multiple entries
+            parameters:
+              keys:
+                type: array
+                required: true
+            returns:
+              type: object
+
+          - name: batch_set
+            description: Store multiple entries
+            parameters:
+              entries:
+                type: array
+                required: true
+            returns:
+              type: boolean
+
+          - name: expire
+            description: Set expiration on existing key
+            parameters:
+              key:
+                type: string
+                required: true
+              ttl_seconds:
+                type: integer
+                required: true
+            returns:
+              type: boolean
+
+          - name: increment
+            description: Atomic increment for counters
+            parameters:
+              key:
+                type: string
+                required: true
+              delta:
+                type: integer
+                required: false
+            returns:
+              type: integer
+
+      lifecycle_hooks:
+        type: object
+        description: Provider lifecycle hooks
+        properties:
+          on_init:
+            type: string
+            description: Called when provider initializes
+          on_shutdown:
+            type: string
+            description: Called before provider shutdown
+          on_error:
+            type: string
+            description: Called on provider errors
+          on_connection_lost:
+            type: string
+            description: Called when connection is lost
+          on_connection_restored:
+            type: string
+            description: Called when connection is restored
+
+  # ============================================
+  # MEMORY LIFECYCLE
+  # Garbage collection and maintenance
+  # ============================================
+  lifecycle:
+    type: object
+    description: Memory lifecycle and maintenance configuration
+    properties:
+      garbage_collection:
+        type: object
+        description: Automatic cleanup of expired/unused memory
+        properties:
+          enabled:
+            type: boolean
+            default: true
+
+          strategy:
+            type: string
+            description: GC strategy
+            enum:
+              - lru
+              - lfu
+              - ttl
+              - size_based
+              - hybrid
+            default: hybrid
+
+          run_interval_seconds:
+            type: integer
+            description: Interval between GC runs
+            default: 3600
+            minimum: 60
+            maximum: 86400
+
+          max_memory_percent:
+            type: integer
+            description: Trigger GC when memory exceeds this percent
+            default: 80
+            minimum: 50
+            maximum: 95
+
+          target_memory_percent:
+            type: integer
+            description: GC target memory level
+            default: 60
+            minimum: 30
+            maximum: 80
+
+      backup:
+        type: object
+        description: Memory backup configuration
+        properties:
+          enabled:
+            type: boolean
+            default: true
+
+          interval_hours:
+            type: integer
+            description: Backup interval in hours
+            default: 24
+            minimum: 1
+            maximum: 168
+
+          retention_count:
+            type: integer
+            description: Number of backups to retain
+            default: 7
+            minimum: 1
+            maximum: 30
+
+          destination:
+            type: string
+            description: Backup destination
+            examples:
+              - s3://bucket/backups/
+              - file:///var/backups/
+              - gcs://bucket/backups/
+
+          encryption:
+            type: boolean
+            default: true
+            description: Encrypt backups
+
+      compaction:
+        type: object
+        description: Memory compaction settings
+        properties:
+          enabled:
+            type: boolean
+            default: true
+
+          threshold_percent:
+            type: integer
+            description: Fragmentation threshold to trigger compaction
+            default: 30
+            minimum: 10
+            maximum: 50
+
+          run_interval_hours:
+            type: integer
+            description: Compaction interval
+            default: 24
+            minimum: 1
+            maximum: 168
+
+      migration:
+        type: object
+        description: Memory migration between providers
+        properties:
+          enabled:
+            type: boolean
+            default: false
+
+          source_provider:
+            type: string
+            description: Source memory provider
+
+          target_provider:
+            type: string
+            description: Target memory provider
+
+          batch_size:
+            type: integer
+            description: Migration batch size
+            default: 1000
+            minimum: 100
+            maximum: 10000
+
+          verify_integrity:
+            type: boolean
+            default: true
+            description: Verify data integrity after migration
+
+# ============================================
+# DEFINITIONS
+# Reusable schema components
+# ============================================
+definitions:
+  MemoryConnection:
+    type: object
+    description: Connection configuration for memory providers
+    properties:
+      endpoint:
+        type: string
+        description: Provider endpoint URL
+        examples:
+          - redis://localhost:6379
+          - postgres://localhost:5432/memory
+          - mongodb://localhost:27017
+
+      credentials_ref:
+        type: string
+        description: Reference to credentials secret
+        examples:
+          - REDIS_PASSWORD
+          - POSTGRES_CONNECTION_STRING
+          - MONGODB_URI
+
+      pool_size:
+        type: integer
+        description: Connection pool size
+        default: 10
+        minimum: 1
+        maximum: 100
+
+      timeout_seconds:
+        type: integer
+        description: Connection timeout
+        default: 30
+        minimum: 1
+        maximum: 300
+
+      retry_policy:
+        type: object
+        properties:
+          max_attempts:
+            type: integer
+            default: 3
+          backoff:
+            type: string
+            enum:
+              - exponential
+              - linear
+              - constant
+            default: exponential
+          initial_delay_ms:
+            type: integer
+            default: 100
+          max_delay_ms:
+            type: integer
+            default: 10000
+
+      ssl:
+        type: object
+        description: SSL/TLS configuration
+        properties:
+          enabled:
+            type: boolean
+            default: true
+          verify:
+            type: boolean
+            default: true
+          ca_cert_ref:
+            type: string
+            description: CA certificate reference
+          client_cert_ref:
+            type: string
+            description: Client certificate reference
+
+  MemoryOperation:
+    type: object
+    description: Memory operation specification
+    required:
+      - name
+      - description
+    properties:
+      name:
+        type: string
+        description: Operation name
+
+      description:
+        type: string
+        description: Operation description
+
+      parameters:
+        type: object
+        description: Operation parameters
+        additionalProperties:
+          type: object
+          properties:
+            type:
+              type: string
+            required:
+              type: boolean
+            default: {}
+
+      returns:
+        type: object
+        description: Return type specification
+        properties:
+          type:
+            type: string
+          nullable:
+            type: boolean
+          items:
+            type: object
+
+      idempotent:
+        type: boolean
+        default: false
+        description: Whether operation is idempotent
+
+      async:
+        type: boolean
+        default: false
+        description: Whether operation is asynchronous
+
+examples:
+  - apiVersion: ossa/v0.3.3
+    kind: MemoryModel
+    short_term:
+      enabled: true
+      provider: redis
+      conversation_context:
+        enabled: true
+        max_messages: 100
+        max_tokens: 32000
+        truncation_strategy: sliding_window
+      working_memory:
+        enabled: true
+        max_size_mb: 64
+        ttl_seconds: 3600
+      connection:
+        endpoint: redis://localhost:6379
+        credentials_ref: REDIS_PASSWORD
+
+    long_term:
+      enabled: true
+      provider: postgres
+      storage_type: hybrid
+      knowledge_base:
+        enabled: true
+        schema: json_schema
+        versioning: true
+      vector_store:
+        enabled: true
+        embedding_model: text-embedding-3-small
+        embedding_dimensions: 1536
+        distance_metric: cosine
+      conversation_history:
+        enabled: true
+        retention_days: 90
+        summarization: true
+      connection:
+        endpoint: postgres://localhost:5432/agent_memory
+        credentials_ref: POSTGRES_CONNECTION_STRING
+
+    lifecycle:
+      garbage_collection:
+        enabled: true
+        strategy: hybrid
+        run_interval_seconds: 3600
+        max_memory_percent: 80
+      backup:
+        enabled: true
+        interval_hours: 24
+        retention_count: 7
+        encryption: true