@codesoul-co/hypha-memory / provider-observability

• Package index: @codesoul-co/hypha-memory
• Source: packages/memory/src/provider-observability.ts
• Exports: 11

Using this module

Use the Provider observability module for binding external or local providers to Hypha ports. It exports 2 classes, 6 interfaces, 3 types.

Import from the package entrypoint

import {
  MemoryProviderTelemetry,
  ObservedMemoryManagementProvider,
} from '@codesoul-co/hypha-memory';

import type {
  MemoryProviderMetricSample,
  MemoryProviderOperationalReport,
  MemoryProviderOperationEstimate,
  MemoryProviderTelemetryOptions,
  MemoryProviderTelemetryPolicy,
  ObservedMemoryManagementProviderOptions,
  MemoryProviderCostEstimator,
  MemoryProviderOperation,
} from '@codesoul-co/hypha-memory';

// The complete export list is documented below.

Usage patterns

• Use the 9 type/interface exports as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.
• The module exposes 2 classes as constructable runtime implementations. Each symbol entry lists its constructor and public methods.

Public exports

Symbol	Kind	Signature	Description
MemoryProviderTelemetry	class	new MemoryProviderTelemetry(options: MemoryProviderTelemetryOptions): MemoryProviderTelemetry	Bounded, content-free Provider telemetry with quota admission and SLO evaluation. Samples retain only operation metadata; requests, responses, scopes and content are never stored.
ObservedMemoryManagementProvider	class	new ObservedMemoryManagementProvider(options: ObservedMemoryManagementProviderOptions): ObservedMemoryManagementProvider	Provider decorator that instruments every canonical operation without changing Provider APIs.
MemoryProviderMetricSample	interface	interface MemoryProviderMetricSample	Memory Provider Metric Sample interface with 8 public fields or methods.
MemoryProviderOperationalReport	interface	interface MemoryProviderOperationalReport	Memory Provider Operational Report interface with 9 public fields or methods.
MemoryProviderOperationEstimate	interface	interface MemoryProviderOperationEstimate	Memory Provider Operation Estimate interface with 2 public fields or methods.
MemoryProviderTelemetryOptions	interface	interface MemoryProviderTelemetryOptions	Memory Provider Telemetry Options interface with 3 public fields or methods.
MemoryProviderTelemetryPolicy	interface	interface MemoryProviderTelemetryPolicy	Memory Provider Telemetry Policy interface with 4 public fields or methods.
ObservedMemoryManagementProviderOptions	interface	interface ObservedMemoryManagementProviderOptions	Observed Memory Management Provider Options interface with 3 public fields or methods.
MemoryProviderCostEstimator	type	type MemoryProviderCostEstimator = (operation: MemoryProviderOperation, request: unknown) => MemoryProviderOperationEstimate	Public type alias for Memory Provider Cost Estimator; the declaration contains its complete type expression.
MemoryProviderOperation	type	type MemoryProviderOperation = 'add' | 'search' | 'get' | 'list' | 'update' | 'delete' | 'history' | 'health'	Public type alias for Memory Provider Operation; the declaration contains its complete type expression.
MemoryProviderOperationOutcome	type	type MemoryProviderOperationOutcome = 'succeeded' | 'failed' | 'quota_rejected'	Public type alias for Memory Provider Operation Outcome; the declaration contains its complete type expression.

MemoryProviderTelemetry

Bounded, content-free Provider telemetry with quota admission and SLO evaluation. Samples retain only operation metadata; requests, responses, scopes and content are never stored.

• Kind: class
• Import: import { MemoryProviderTelemetry } from '@codesoul-co/hypha-memory';
• Source module: provider-observability

Declaration

export declare class MemoryProviderTelemetry {
    constructor(options: MemoryProviderTelemetryOptions);
    begin(providerId: string, operation: MemoryProviderOperation, estimate?: MemoryProviderOperationEstimate): Reservation;
    snapshot(providerId: string): MemoryProviderOperationalReport;
}

Public members

Member	Kind	Signature	Description
begin	method	begin(providerId: string, operation: MemoryProviderOperation, estimate?: MemoryProviderOperationEstimate): Reservation	Public method; parameters and return type are shown in the signature.
constructor	constructor	(options: MemoryProviderTelemetryOptions): MemoryProviderTelemetry	Creates an instance of this class.
snapshot	method	snapshot(providerId: string): MemoryProviderOperationalReport	Public method; parameters and return type are shown in the signature.

ObservedMemoryManagementProvider

Provider decorator that instruments every canonical operation without changing Provider APIs.

• Kind: class
• Import: import { ObservedMemoryManagementProvider } from '@codesoul-co/hypha-memory';
• Source module: provider-observability

Declaration

export declare class ObservedMemoryManagementProvider implements MemoryManagementProvider {
    readonly id: string;
    constructor(options: ObservedMemoryManagementProviderOptions);
    capabilities(): Promise<import("./contracts").MemoryManagementCapabilities>;
    add(request: MemoryAddRequest, signal?: AbortSignal): Promise<ManagedMemoryWriteResult>;
    search(request: ManagedMemorySearchRequest, signal?: AbortSignal): Promise<ManagedMemorySearchResult[]>;
    get(request: MemoryGetRequest, signal?: AbortSignal): Promise<import("./contracts").ManagedMemoryRecord<unknown> | null>;
    list(request: MemoryListRequest, signal?: AbortSignal): Promise<MemoryListResult>;
    update(request: ManagedMemoryUpdateRequest, signal?: AbortSignal): Promise<ManagedMemoryWriteResult>;
    delete(request: ManagedMemoryDeleteRequest, signal?: AbortSignal): Promise<ManagedMemoryDeleteResult>;
    history(request: MemoryHistoryRequest, signal?: AbortSignal): Promise<MemoryVersion[]>;
    health(): Promise<ProviderHealth>;
    close(): Promise<void>;
}

Public members

Member	Kind	Signature	Description
add	method	add(request: MemoryAddRequest, signal?: AbortSignal): Promise<ManagedMemoryWriteResult>	Public method; parameters and return type are shown in the signature.
capabilities	method	capabilities(): Promise<import("./contracts").MemoryManagementCapabilities>	Public method; parameters and return type are shown in the signature.
close	method	close(): Promise<void>	Public method; parameters and return type are shown in the signature.
constructor	constructor	(options: ObservedMemoryManagementProviderOptions): ObservedMemoryManagementProvider	Creates an instance of this class.
delete	method	delete(request: ManagedMemoryDeleteRequest, signal?: AbortSignal): Promise<ManagedMemoryDeleteResult>	Public method; parameters and return type are shown in the signature.
get	method	get(request: MemoryGetRequest, signal?: AbortSignal): Promise<import("./contracts").ManagedMemoryRecord<unknown> | null>	Public method; parameters and return type are shown in the signature.
health	method	health(): Promise<ProviderHealth>	Public method; parameters and return type are shown in the signature.
history	method	history(request: MemoryHistoryRequest, signal?: AbortSignal): Promise<MemoryVersion[]>	Public method; parameters and return type are shown in the signature.
id	property	readonly id: string	Public property; its type, readonly modifier and optionality are shown in the signature.
list	method	list(request: MemoryListRequest, signal?: AbortSignal): Promise<MemoryListResult>	Public method; parameters and return type are shown in the signature.
search	method	search(request: ManagedMemorySearchRequest, signal?: AbortSignal): Promise<ManagedMemorySearchResult[]>	Public method; parameters and return type are shown in the signature.
update	method	update(request: ManagedMemoryUpdateRequest, signal?: AbortSignal): Promise<ManagedMemoryWriteResult>	Public method; parameters and return type are shown in the signature.

MemoryProviderMetricSample

Memory Provider Metric Sample interface with 8 public fields or methods.

• Kind: interface
• Import: import type { MemoryProviderMetricSample } from '@codesoul-co/hypha-memory';
• Source module: provider-observability

Declaration

export interface MemoryProviderMetricSample {
    providerId: string;
    operation: MemoryProviderOperation;
    outcome: MemoryProviderOperationOutcome;
    latencyMs: number;
    occurredAt: string;
    costUnits?: number;
    storedBytesDelta?: number;
    errorCode?: string;
}

Contract members

Member	Kind	Signature	Description
costUnits	property	costUnits?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
errorCode	property	errorCode?: string	Public property; its type, readonly modifier and optionality are shown in the signature.
latencyMs	property	latencyMs: number	Public property; its type, readonly modifier and optionality are shown in the signature.
occurredAt	property	occurredAt: string	Public property; its type, readonly modifier and optionality are shown in the signature.
operation	property	operation: MemoryProviderOperation	Public property; its type, readonly modifier and optionality are shown in the signature.
outcome	property	outcome: MemoryProviderOperationOutcome	Public property; its type, readonly modifier and optionality are shown in the signature.
providerId	property	providerId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
storedBytesDelta	property	storedBytesDelta?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

MemoryProviderOperationalReport

Memory Provider Operational Report interface with 9 public fields or methods.

• Kind: interface
• Import: import type { MemoryProviderOperationalReport } from '@codesoul-co/hypha-memory';
• Source module: provider-observability

Declaration

export interface MemoryProviderOperationalReport {
    providerId: string;
    window: {
        startedAt: string;
        endedAt: string;
        durationMs: number;
    };
    operations: {
        total: number;
        succeeded: number;
        failed: number;
        quotaRejected: number;
        inFlight: number;
        byOperation: Partial<Record<MemoryProviderOperation, number>>;
    };
    availability: number | null;
    latencyMs: {
        p50: number | null;
        p95: number | null;
        p99: number | null;
        max: number | null;
    };
    cost: {
        measuredUnits: number;
        unpricedOperations: number;
        complete: boolean;
    };
    storage: {
        measuredBytes: number;
    };
    quota: {
        maxOperations?: number;
        remainingOperations?: number;
        maxCostUnits?: number;
        remainingCostUnits?: number;
        maxStoredBytes?: number;
        remainingStoredBytes?: number;
    };
    slo: {
        status: 'met' | 'breached' | 'insufficient_data';
        reasons: string[];
        minimumOperations: number;
        availabilityTarget?: number;
        latencyP95Ms?: number;
    };
}

Contract members

Member	Kind	Signature	Description
availability	property	availability: number	Public property; its type, readonly modifier and optionality are shown in the signature.
cost	property	cost: { measuredUnits: number; unpricedOperations: number; complete: boolean; }	Public property; its type, readonly modifier and optionality are shown in the signature.
latencyMs	property	latencyMs: { p50: number | null; p95: number | null; p99: number | null; max: number | null; }	Public property; its type, readonly modifier and optionality are shown in the signature.
operations	property	operations: { total: number; succeeded: number; failed: number; quotaRejected: number; inFlight: number; byOperation: Partial<Record<MemoryProviderOperation, number>>; }	Public property; its type, readonly modifier and optionality are shown in the signature.
providerId	property	providerId: string	Public property; its type, readonly modifier and optionality are shown in the signature.
quota	property	quota: { maxOperations?: number; remainingOperations?: number; maxCostUnits?: number; remainingCostUnits?: number; maxStoredBytes?: number; remainingStoredBytes?: number; }	Public property; its type, readonly modifier and optionality are shown in the signature.
slo	property	slo: { status: "met" | "breached" | "insufficient_data"; reasons: string[]; minimumOperations: number; availabilityTarget?: number; latencyP95Ms?: number; }	Public property; its type, readonly modifier and optionality are shown in the signature.
storage	property	storage: { measuredBytes: number; }	Public property; its type, readonly modifier and optionality are shown in the signature.
window	property	window: { startedAt: string; endedAt: string; durationMs: number; }	Public property; its type, readonly modifier and optionality are shown in the signature.

MemoryProviderOperationEstimate

Memory Provider Operation Estimate interface with 2 public fields or methods.

• Kind: interface
• Import: import type { MemoryProviderOperationEstimate } from '@codesoul-co/hypha-memory';
• Source module: provider-observability

Declaration

export interface MemoryProviderOperationEstimate {
    costUnits?: number;
    storedBytesDelta?: number;
}

Contract members

Member	Kind	Signature	Description
costUnits	property	costUnits?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
storedBytesDelta	property	storedBytesDelta?: number	Public property; its type, readonly modifier and optionality are shown in the signature.

MemoryProviderTelemetryOptions

Memory Provider Telemetry Options interface with 3 public fields or methods.

• Kind: interface
• Import: import type { MemoryProviderTelemetryOptions } from '@codesoul-co/hypha-memory';
• Source module: provider-observability

Declaration

export interface MemoryProviderTelemetryOptions {
    defaultPolicy: MemoryProviderTelemetryPolicy;
    providerPolicies?: Record<string, MemoryProviderTelemetryPolicy>;
    now?: () => Date;
}

Contract members

Member	Kind	Signature	Description
defaultPolicy	property	defaultPolicy: MemoryProviderTelemetryPolicy	Public property; its type, readonly modifier and optionality are shown in the signature.
now	method	now?(): Date	Public method; parameters and return type are shown in the signature.
providerPolicies	property	providerPolicies?: Record<string, MemoryProviderTelemetryPolicy>	Public property; its type, readonly modifier and optionality are shown in the signature.

MemoryProviderTelemetryPolicy

Memory Provider Telemetry Policy interface with 4 public fields or methods.

• Kind: interface
• Import: import type { MemoryProviderTelemetryPolicy } from '@codesoul-co/hypha-memory';
• Source module: provider-observability

Declaration

export interface MemoryProviderTelemetryPolicy {
    windowMs: number;
    maxSamples?: number;
    quota?: {
        maxOperations?: number;
        maxCostUnits?: number;
        maxStoredBytes?: number;
    };
    slo?: {
        minimumOperations?: number;
        availabilityTarget?: number;
        latencyP95Ms?: number;
    };
}

Contract members

Member	Kind	Signature	Description
maxSamples	property	maxSamples?: number	Public property; its type, readonly modifier and optionality are shown in the signature.
quota	property	quota?: { maxOperations?: number; maxCostUnits?: number; maxStoredBytes?: number; }	Public property; its type, readonly modifier and optionality are shown in the signature.
slo	property	slo?: { minimumOperations?: number; availabilityTarget?: number; latencyP95Ms?: number; }	Public property; its type, readonly modifier and optionality are shown in the signature.
windowMs	property	windowMs: number	Public property; its type, readonly modifier and optionality are shown in the signature.

ObservedMemoryManagementProviderOptions

Observed Memory Management Provider Options interface with 3 public fields or methods.

• Kind: interface
• Import: import type { ObservedMemoryManagementProviderOptions } from '@codesoul-co/hypha-memory';
• Source module: provider-observability

Declaration

export interface ObservedMemoryManagementProviderOptions {
    provider: MemoryManagementProvider;
    telemetry: MemoryProviderTelemetry;
    estimate?: MemoryProviderCostEstimator;
}

Contract members

Member	Kind	Signature	Description
estimate	method	estimate?(operation: MemoryProviderOperation, request: unknown): MemoryProviderOperationEstimate	Public method; parameters and return type are shown in the signature.
provider	property	provider: MemoryManagementProvider	Public property; its type, readonly modifier and optionality are shown in the signature.
telemetry	property	telemetry: MemoryProviderTelemetry	Public property; its type, readonly modifier and optionality are shown in the signature.

MemoryProviderCostEstimator

Public type alias for Memory Provider Cost Estimator; the declaration contains its complete type expression.

• Kind: type
• Import: import type { MemoryProviderCostEstimator } from '@codesoul-co/hypha-memory';
• Source module: provider-observability

Declaration

export type MemoryProviderCostEstimator = (operation: MemoryProviderOperation, request: unknown) => MemoryProviderOperationEstimate;

MemoryProviderOperation

Public type alias for Memory Provider Operation; the declaration contains its complete type expression.

• Kind: type
• Import: import type { MemoryProviderOperation } from '@codesoul-co/hypha-memory';
• Source module: provider-observability

Declaration

export type MemoryProviderOperation = 'add' | 'search' | 'get' | 'list' | 'update' | 'delete' | 'history' | 'health';

MemoryProviderOperationOutcome

Public type alias for Memory Provider Operation Outcome; the declaration contains its complete type expression.

• Kind: type
• Import: import type { MemoryProviderOperationOutcome } from '@codesoul-co/hypha-memory';
• Source module: provider-observability

Declaration

export type MemoryProviderOperationOutcome = 'succeeded' | 'failed' | 'quota_rejected';