Skip to content

Memory System Adapter Framework Adapter Interface Contract

Jump to bottom
github-actions[bot] edited this page Aug 3, 2026 · 3 revisions

Adapter Interface Contract

Referenced Files in This Document

Table of Contents

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction

This document defines the adapter interface contract used by the memory subsystem to integrate diverse data sources and processing pipelines. It explains:

  • The core adapter interface methods and lifecycle hooks
  • Data flow patterns between adapters, builders, and handlers
  • Registration and dependency injection mechanisms
  • Configuration schemas and validation rules
  • Error handling patterns and type safety considerations
  • Versioning strategies and backward compatibility requirements
  • Practical examples for implementing basic adapters and handling different data formats

The goal is to provide a clear, actionable guide for building and maintaining adapters that are robust, testable, and compatible across versions.

Project Structure

Adapters live primarily under the memory services layer with supporting utilities, types, and documentation. Key areas include:

  • Core adapter interface and builder
  • Default and header handlers
  • Validation utilities for protocol structure and markdown size limits
  • Type definitions and shared contracts
  • Tooling for resolving and constructing adapter URIs
  • Migration and bulk insertion guides
  • Example adapters demonstrating various input/output patterns
graph TB
subgraph "Memory Services"
SA["store-adapter.ts"]
AB["adapter-builder.ts"]
DH["store-adapter-default-handler.ts"]
HH["store-adapter-header-handler.ts"]
SH["store-adapter-helpers.ts"]
VP["validate-protocol-structure.ts"]
VM["validate-adapter-markdown-size.ts"]
ACB["adapter-contract-blocks.ts"]
end
subgraph "Types"
TI["types/index.ts"]
TM["types/memory.ts"]
end
subgraph "Tools"
ERA["export-resolve-adapter.ts"]
TAU["train-artifact-adapter-uri.ts"]
TOU["train-output-adapter-uri.ts"]
end
subgraph "Docs & Examples"
AM["embed-docs/mem/adapter-migration.md"]
BI["embed-docs/mem/bulk-insert-adapters-via-cli.md"]
EXA["docs/examples/adapter-example-all-types.md"]
EXC["docs/examples/adapter-example-comment.md"]
EXM["docs/examples/adapter-example-mcp.md"]
EXS["docs/examples/adapter-example-shell.md"]
EXU["docs/examples/adapter-example-user-input.md"]
end
SA --> AB
SA --> DH
SA --> HH
SA --> SH
SA --> VP
SA --> VM
SA --> ACB
SA --> TI
SA --> TM
ERA --> SA
TAU --> SA
TOU --> SA
AM --> SA
BI --> SA
EXA --> SA
EXC --> SA
EXM --> SA
EXS --> SA
EXU --> SA
Loading

Diagram sources

Section sources

Core Components

This section outlines the primary components that implement and support the adapter contract.

  • Store Adapter Interface

    • Defines the canonical set of methods an adapter must implement to participate in the memory pipeline.
    • Includes lifecycle hooks for initialization, configuration, and cleanup.
    • Specifies typed inputs and outputs to ensure type safety across the system.

  • Adapter Builder

    • Constructs adapter instances from configuration or runtime context.
    • Applies default behaviors and injects dependencies (e.g., logging, storage).
    • Validates configuration against schema before instantiation.

  • Handlers

    • Default Handler: Provides baseline behavior when specific logic is not implemented.
    • Header Handler: Manages metadata headers and cross-cutting concerns such as tracing and audit.

  • Helpers and Validators

    • Helpers: Utility functions for common operations like URI resolution and payload shaping.
    • Protocol Structure Validator: Ensures adapter payloads conform to expected structures.
    • Markdown Size Validator: Enforces size constraints on markdown content to prevent resource exhaustion.

  • Contracts and Blocks

    • Contract Blocks: Reusable fragments describing required fields, enums, and constraints.
    • Shared Types: Centralized TypeScript types for consistent interfaces across modules.

Section sources

Architecture Overview

The adapter architecture follows a layered approach:

  • Adapters implement a strict interface and can be composed via builders.
  • Builders handle dependency injection and configuration validation.
  • Handlers encapsulate cross-cutting concerns and defaults.
  • Validators enforce structural and size constraints early in the pipeline.
  • Tools resolve and construct adapter URIs for export and training workflows.
sequenceDiagram
participant Client as "Client Code"
participant Builder as "AdapterBuilder"
participant Adapter as "StoreAdapter"
participant DefaultHandler as "DefaultHandler"
participant HeaderHandler as "HeaderHandler"
participant Validator as "Validators"
Client->>Builder : "build(config)"
Builder->>Validator : "validate(config)"
Validator-->>Builder : "valid"
Builder->>Adapter : "instantiate(adapterType, config)"
Adapter->>HeaderHandler : "applyHeaders(metadata)"
Adapter->>DefaultHandler : "fallbackBehavior()"
Adapter-->>Client : "result"
Loading

Diagram sources

Detailed Component Analysis

Store Adapter Interface

The store adapter interface defines the contract for all adapters. It includes:

  • Initialization and lifecycle hooks
  • Typed method signatures for reading/writing artifacts
  • Metadata and header management
  • Error signaling and status reporting
classDiagram
class StoreAdapter {
+initialize() void
+read(input) Result
+write(input) Result
+headers(metadata) Headers
+cleanup() void
}
class DefaultHandler {
+applyDefaults(payload) Payload
+fallbackAction() void
}
class HeaderHandler {
+setHeaders(metadata) void
+getHeaders() Headers
}
StoreAdapter --> DefaultHandler : "uses"
StoreAdapter --> HeaderHandler : "uses"
Loading

Diagram sources

Section sources

Adapter Builder and Dependency Injection

The adapter builder constructs adapters from configuration and injects dependencies:

  • Configuration validation using schema-driven checks
  • Dependency injection for logging, storage, and external services
  • Fallback to default handler when optional methods are missing
flowchart TD
Start(["Build Request"]) --> Validate["Validate Config Schema"]
Validate --> Valid{"Valid?"}
Valid --> |No| Error["Throw Validation Error"]
Valid --> |Yes| Resolve["Resolve Adapter Type"]
Resolve --> Inject["Inject Dependencies"]
Inject --> Instantiate["Instantiate Adapter"]
Instantiate --> WrapHandlers["Wrap With Default/Header Handlers"]
WrapHandlers --> Return(["Return Adapter Instance"])
Error --> End(["Exit"])
Return --> End
Loading

Diagram sources

Section sources

Validation and Type Safety

Validation ensures adapters adhere to structural and size constraints:

  • Protocol structure validator enforces required fields and types
  • Markdown size validator prevents oversized payloads
  • Shared types centralize contracts for consistency
flowchart TD
Input(["Adapter Payload"]) --> CheckStructure["Check Protocol Structure"]
CheckStructure --> StructureOK{"Structure OK?"}
StructureOK --> |No| StructErr["Return Structure Error"]
StructureOK --> |Yes| CheckSize["Check Markdown Size"]
CheckSize --> SizeOK{"Size Within Limit?"}
SizeOK --> |No| SizeErr["Return Size Error"]
SizeOK --> |Yes| Pass(["Pass Validation"])
StructErr --> End(["Exit"])
SizeErr --> End
Pass --> End
Loading

Diagram sources

Section sources

Adapter Registration and Resolution

Registration and resolution are facilitated through helper utilities and tools:

  • Export resolver maps URIs to concrete adapter implementations
  • Train artifact/output adapters build URIs for training workflows
  • Helpers provide common resolution logic and error handling
sequenceDiagram
participant Caller as "Caller"
participant Resolver as "ExportResolver"
participant Helper as "AdapterHelpers"
participant Registry as "Registry"
Caller->>Resolver : "resolve(uri)"
Resolver->>Helper : "normalizeAndParse(uri)"
Helper-->>Resolver : "parsedParts"
Resolver->>Registry : "lookup(adapterType)"
Registry-->>Resolver : "AdapterClass"
Resolver-->>Caller : "AdapterInstance"
Loading

Diagram sources

Section sources

Configuration Schemas and Blocks

Configuration schemas define the shape of adapter settings:

  • Contract blocks specify required fields, enums, and constraints
  • Schemas are validated during build time and runtime
  • Backward compatibility is maintained via versioned schema evolution
classDiagram
class ContractBlocks {
+requiredFields
+enums
+constraints
}
class Schema {
+version
+fields
+validationRules
}
ContractBlocks <.. Schema : "defines"
Loading

Diagram sources

Section sources

Lifecycle Hooks and State Management

Lifecycle hooks allow adapters to initialize resources, manage state, and clean up:

  • Initialize: Set up connections, caches, or temporary files
  • Read/Write: Perform core operations with typed inputs/outputs
  • Cleanup: Release resources and reset state
stateDiagram-v2
[*] --> Uninitialized
Uninitialized --> Initialized : "initialize()"
Initialized --> Active : "read()/write()"
Active --> CleaningUp : "cleanup()"
CleaningUp --> Uninitialized : "done"
Loading

Diagram sources

Section sources

Implementing Basic Adapters and Handling Different Data Formats

Examples demonstrate how to implement adapters for various scenarios:

  • All types: Comprehensive example covering multiple input/output types
  • Comment: Simple text-based adapter
  • MCP: Integration with Model Context Protocol
  • Shell: Command execution adapter
  • User Input: Interactive input adapter

These examples illustrate:

  • Implementing required methods
  • Handling different data formats (JSON, markdown, binary)
  • Managing adapter state and lifecycle
  • Applying validation and error handling

Section sources

Error Handling Patterns and Validation Rules

Error handling follows consistent patterns:

  • Early validation failures return structured errors
  • Runtime errors are wrapped with context and cause chains
  • Size and structure validations prevent malformed payloads

Validation rules include:

  • Required field presence
  • Type enforcement
  • Size limits for markdown content
  • Enum value constraints

Section sources

Versioning Strategies and Backward Compatibility

Versioning strategies ensure adapters evolve without breaking existing integrations:

  • Schema versioning with migration guides
  • Bulk insertion scripts for large-scale updates
  • Backward compatibility maintained through graceful degradation and fallbacks

Migration guidance covers:

  • Upgrading adapter configurations
  • Handling deprecated fields
  • Testing compatibility across versions

Section sources

Dependency Analysis

Adapters depend on shared types, validators, and helpers. The builder orchestrates these dependencies and ensures proper initialization order.

graph TB
SA["StoreAdapter"] --> TI["types/index.ts"]
SA --> TM["types/memory.ts"]
SA --> VP["validate-protocol-structure.ts"]
SA --> VM["validate-adapter-markdown-size.ts"]
SA --> SH["store-adapter-helpers.ts"]
AB["adapter-builder.ts"] --> SA
ERA["export-resolve-adapter.ts"] --> SA
TAU["train-artifact-adapter-uri.ts"] --> SA
TOU["train-output-adapter-uri.ts"] --> SA
Loading

Diagram sources

Section sources

Performance Considerations

  • Avoid heavy initialization in read/write paths; defer to lifecycle hooks
  • Cache frequently accessed resources where appropriate
  • Enforce size limits to prevent memory pressure
  • Use streaming for large payloads when possible
  • Profile adapter performance under realistic workloads

[No sources needed since this section provides general guidance]

Troubleshooting Guide

Common issues and resolutions:

  • Configuration validation errors: Review schema and required fields
  • Size limit exceeded: Reduce payload size or adjust limits if justified
  • Missing lifecycle hooks: Ensure initialize/cleanup are implemented
  • Type mismatches: Verify input/output types match contract expectations
  • URI resolution failures: Check adapter registration and naming conventions

Section sources

Conclusion

The adapter interface contract provides a robust foundation for integrating diverse data sources and processing pipelines. By adhering to the defined methods, lifecycle hooks, and validation rules, adapters can be reliably built, registered, and maintained. Versioning strategies and backward compatibility measures ensure long-term stability as the system evolves.

[No sources needed since this section summarizes without analyzing specific files]

Appendices

Quick Reference: Core Methods and Hooks

  • initialize(): Prepare resources and state
  • read(input): Process input and return result
  • write(input): Persist or transform output
  • headers(metadata): Manage metadata and headers
  • cleanup(): Release resources and reset state

Section sources

Example Implementation Paths

Section sources

KAIROS MCP

Clone this wiki locally