`@codesoul-co/hypha-memory` / `lifecycle-contracts`

Package index: @codesoul-co/hypha-memory
Source: packages/memory/src/lifecycle-contracts.ts
Exports: 22

Using this module

Use the Lifecycle contracts module for declaring and runtime-validating contracts. It exports 20 interfaces, 2 types.

Import from the package entrypoint

import type {
  EpisodicRecordInput,
  ExtractedMemoryCandidate,
  ExtractedMemoryEvidence,
  MemoryExtractionBatch,
  MemoryExtractionCursor,
  MemoryExtractionJob,
  MemoryExtractionProfileSpec,
  MemoryExtractionRequest,
} from '@codesoul-co/hypha-memory';

// The complete export list is documented below.

Usage patterns

Use the 22 type/interface exports as static contracts in application code, adapters, or tests. Import them with import type; they do not exist at runtime.

Public exports

Symbol	Kind	Signature	Description
`EpisodicRecordInput`	interface	`interface EpisodicRecordInput`	Episodic Record Input interface with 14 public fields or methods.
`ExtractedMemoryCandidate`	interface	`interface ExtractedMemoryCandidate`	Extracted Memory Candidate interface with 20 public fields or methods.
`ExtractedMemoryEvidence`	interface	`interface ExtractedMemoryEvidence`	Extracted Memory Evidence interface with 4 public fields or methods.
`MemoryExtractionBatch`	interface	`interface MemoryExtractionBatch`	Memory Extraction Batch interface with 9 public fields or methods.
`MemoryExtractionCursor`	interface	`interface MemoryExtractionCursor`	Memory Extraction Cursor interface with 6 public fields or methods.
`MemoryExtractionJob`	interface	`interface MemoryExtractionJob`	Memory Extraction Job interface with 16 public fields or methods.
`MemoryExtractionProfileSpec`	interface	`interface MemoryExtractionProfileSpec`	Memory Extraction Profile Spec interface with 14 public fields or methods.
`MemoryExtractionRequest`	interface	`interface MemoryExtractionRequest`	Memory Extraction Request interface with 9 public fields or methods.
`MemoryExtractionSourceAdapter`	interface	`interface MemoryExtractionSourceAdapter`	Memory Extraction Source Adapter interface with 4 public fields or methods.
`MemoryExtractionSourceBatch`	interface	`interface MemoryExtractionSourceBatch`	Memory Extraction Source Batch interface with 3 public fields or methods.
`MemoryExtractionSourceRef`	interface	`interface MemoryExtractionSourceRef`	Memory Extraction Source Ref interface with 15 public fields or methods.
`MemoryExtractionStageSpec`	interface	`interface MemoryExtractionStageSpec`	Memory Extraction Stage Spec interface with 6 public fields or methods.
`MemoryExtractor`	interface	`interface MemoryExtractor`	Memory Extractor interface with 3 public fields or methods.
`MemoryMaintenanceApplyRequest`	interface	`interface MemoryMaintenanceApplyRequest`	Memory Maintenance Apply Request interface with 3 public fields or methods.
`MemoryMaintenanceDecision`	interface	`interface MemoryMaintenanceDecision`	Memory Maintenance Decision interface with 18 public fields or methods.
`MemoryMaintenancePlanner`	interface	`interface MemoryMaintenancePlanner`	Memory Maintenance Planner interface with 3 public fields or methods.
`MemoryMaintenancePlanRequest`	interface	`interface MemoryMaintenancePlanRequest`	Memory Maintenance Plan Request interface with 5 public fields or methods.
`MemoryMaintenancePolicySpec`	interface	`interface MemoryMaintenancePolicySpec`	Memory Maintenance Policy Spec interface with 8 public fields or methods.
`NormalizedExtractionInput`	interface	`interface NormalizedExtractionInput`	Normalized Extraction Input interface with 3 public fields or methods.
`TruthAssertion`	interface	`interface TruthAssertion`	Truth Assertion interface with 11 public fields or methods.
`MemoryExtractionSourceType`	type	`type MemoryExtractionSourceType = 'conversation' \| 'truth' \| 'episodic_record' \| 'runtime_event' \| 'tool_observation' \| 'artifact' \| 'structured_record' \| 'custom'`	Public type alias for Memory Extraction Source Type; the declaration contains its complete type expression.
`MemoryMaintenanceAction`	type	`type MemoryMaintenanceAction = 'create' \| 'noop' \| 'reuse' \| 'update' \| 'merge' \| 'supersede' \| 'invalidate' \| 'reject' \| 'require_review'`	Public type alias for Memory Maintenance Action; the declaration contains its complete type expression.

`EpisodicRecordInput`

Episodic Record Input interface with 14 public fields or methods.

Kind: interface
Import: import type { EpisodicRecordInput } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface EpisodicRecordInput {
    episodeId: string;
    title?: string;
    startAt: string;
    endAt?: string;
    actors?: string[];
    goal?: string;
    actions?: string[];
    observations?: string[];
    outcome?: unknown;
    success?: boolean;
    failureCode?: string;
    causalEventIds?: string[];
    artifactRefs?: string[];
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
`actions`	property	`actions?: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`actors`	property	`actors?: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`artifactRefs`	property	`artifactRefs?: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`causalEventIds`	property	`causalEventIds?: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`endAt`	property	`endAt?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`episodeId`	property	`episodeId: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`failureCode`	property	`failureCode?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`goal`	property	`goal?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`metadata`	property	`metadata?: Record<string, unknown>`	Public property; its type, readonly modifier and optionality are shown in the signature.
`observations`	property	`observations?: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`outcome`	property	`outcome?: unknown`	Public property; its type, readonly modifier and optionality are shown in the signature.
`startAt`	property	`startAt: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`success`	property	`success?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`title`	property	`title?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.

`ExtractedMemoryCandidate`

Extracted Memory Candidate interface with 20 public fields or methods.

Kind: interface
Import: import type { ExtractedMemoryCandidate } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface ExtractedMemoryCandidate {
    candidateId: string;
    type: ManagedMemoryType;
    content: unknown;
    canonicalText: string;
    summary?: string;
    confidence: number;
    importance?: number;
    canonicalKey?: string;
    subject?: string;
    predicate?: string;
    object?: unknown;
    temporal?: {
        observedAt?: string;
        validFrom?: string;
        validTo?: string;
        temporalConfidence?: number;
    };
    entities?: MemoryEntityRef[];
    relations?: MemoryRelation[];
    sensitive?: boolean;
    authority?: MemoryExtractionSourceRef['authority'];
    evidence: ExtractedMemoryEvidence[];
    extractionRationale?: string;
    extractionProfileRevision: string;
    sourceHash: string;
}

Contract members

Member	Kind	Signature	Description
`authority`	property	`authority?: "verified" \| "unverified" \| "user_asserted" \| "system_observed" \| "authoritative"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`candidateId`	property	`candidateId: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`canonicalKey`	property	`canonicalKey?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`canonicalText`	property	`canonicalText: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`confidence`	property	`confidence: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`content`	property	`content: unknown`	Public property; its type, readonly modifier and optionality are shown in the signature.
`entities`	property	`entities?: MemoryEntityRef[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`evidence`	property	`evidence: ExtractedMemoryEvidence[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`extractionProfileRevision`	property	`extractionProfileRevision: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`extractionRationale`	property	`extractionRationale?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`importance`	property	`importance?: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`object`	property	`object?: unknown`	Public property; its type, readonly modifier and optionality are shown in the signature.
`predicate`	property	`predicate?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`relations`	property	`relations?: MemoryRelation[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sensitive`	property	`sensitive?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceHash`	property	`sourceHash: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`subject`	property	`subject?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`summary`	property	`summary?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`temporal`	property	`temporal?: { observedAt?: string; validFrom?: string; validTo?: string; temporalConfidence?: number; }`	Public property; its type, readonly modifier and optionality are shown in the signature.
`type`	property	`type: ManagedMemoryType`	Public property; its type, readonly modifier and optionality are shown in the signature.

`ExtractedMemoryEvidence`

Extracted Memory Evidence interface with 4 public fields or methods.

Kind: interface
Import: import type { ExtractedMemoryEvidence } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface ExtractedMemoryEvidence {
    sourceRef: MemoryExtractionSourceRef;
    sourceSpan?: {
        messageId?: string;
        eventId?: string;
        artifactRef?: string;
        start?: number;
        end?: number;
        quoteHash?: string;
    };
    supportType: 'direct' | 'derived' | 'contradicting';
    confidence?: number;
}

Contract members

Member	Kind	Signature	Description
`confidence`	property	`confidence?: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceRef`	property	`sourceRef: MemoryExtractionSourceRef`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceSpan`	property	`sourceSpan?: { messageId?: string; eventId?: string; artifactRef?: string; start?: number; end?: number; quoteHash?: string; }`	Public property; its type, readonly modifier and optionality are shown in the signature.
`supportType`	property	`supportType: "derived" \| "direct" \| "contradicting"`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryExtractionBatch`

Memory Extraction Batch interface with 9 public fields or methods.

Kind: interface
Import: import type { MemoryExtractionBatch } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryExtractionBatch {
    id: string;
    jobId: string;
    sourceRefs: MemoryExtractionSourceRef[];
    candidates: ExtractedMemoryCandidate[];
    rejectedCandidates: MemoryRejectedItem[];
    sourceHash: string;
    extractorVersion: string;
    modelObservationRef?: string;
    createdAt: string;
}

Contract members

Member	Kind	Signature	Description
`candidates`	property	`candidates: ExtractedMemoryCandidate[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`createdAt`	property	`createdAt: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`extractorVersion`	property	`extractorVersion: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`id`	property	`id: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`jobId`	property	`jobId: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`modelObservationRef`	property	`modelObservationRef?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`rejectedCandidates`	property	`rejectedCandidates: MemoryRejectedItem[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceHash`	property	`sourceHash: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceRefs`	property	`sourceRefs: MemoryExtractionSourceRef[]`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryExtractionCursor`

Memory Extraction Cursor interface with 6 public fields or methods.

Kind: interface
Import: import type { MemoryExtractionCursor } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryExtractionCursor {
    sourceType: MemoryExtractionSourceType;
    sourceId: string;
    sequence?: number;
    timestamp?: string;
    sourceHash?: string;
    opaqueCursor?: string;
}

Contract members

Member	Kind	Signature	Description
`opaqueCursor`	property	`opaqueCursor?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sequence`	property	`sequence?: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceHash`	property	`sourceHash?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceId`	property	`sourceId: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceType`	property	`sourceType: MemoryExtractionSourceType`	Public property; its type, readonly modifier and optionality are shown in the signature.
`timestamp`	property	`timestamp?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryExtractionJob`

Memory Extraction Job interface with 16 public fields or methods.

Kind: interface
Import: import type { MemoryExtractionJob } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryExtractionJob {
    id: string;
    operationId: string;
    scopeHash: string;
    profileRef: MemoryContractSpecRef;
    profileRevision: string;
    sourceRefs: MemoryExtractionSourceRef[];
    status: 'queued' | 'running' | 'awaiting_review' | 'completed' | 'partial' | 'failed' | 'cancelled';
    cursorBefore?: MemoryExtractionCursor;
    cursorAfter?: MemoryExtractionCursor;
    attempts: number;
    leaseOwner?: string;
    leaseExpiresAt?: string;
    lastError?: NormalizedMemoryError;
    createdAt: string;
    startedAt?: string;
    completedAt?: string;
}

Contract members

Member	Kind	Signature	Description
`attempts`	property	`attempts: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`completedAt`	property	`completedAt?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`createdAt`	property	`createdAt: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`cursorAfter`	property	`cursorAfter?: MemoryExtractionCursor`	Public property; its type, readonly modifier and optionality are shown in the signature.
`cursorBefore`	property	`cursorBefore?: MemoryExtractionCursor`	Public property; its type, readonly modifier and optionality are shown in the signature.
`id`	property	`id: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`lastError`	property	`lastError?: NormalizedMemoryError`	Public property; its type, readonly modifier and optionality are shown in the signature.
`leaseExpiresAt`	property	`leaseExpiresAt?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`leaseOwner`	property	`leaseOwner?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`operationId`	property	`operationId: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`profileRef`	property	`profileRef: MemoryContractSpecRef`	Public property; its type, readonly modifier and optionality are shown in the signature.
`profileRevision`	property	`profileRevision: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`scopeHash`	property	`scopeHash: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceRefs`	property	`sourceRefs: MemoryExtractionSourceRef[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`startedAt`	property	`startedAt?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`status`	property	`status: "completed" \| "queued" \| "running" \| "cancelled" \| "failed" \| "partial" \| "awaiting_review"`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryExtractionProfileSpec`

Memory Extraction Profile Spec interface with 14 public fields or methods.

Kind: interface
Import: import type { MemoryExtractionProfileSpec } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryExtractionProfileSpec {
    id: string;
    version: string;
    revision?: string;
    acceptedSourceTypes: MemoryExtractionSourceType[];
    outputMemoryTypes: ManagedMemoryType[];
    extractor: {
        type: 'deterministic';
        extractorRef: MemoryContractSpecRef;
    } | {
        type: 'model';
        modelProfileRef: MemoryContractSpecRef;
        promptTemplateRef: MemoryContractSpecRef;
    } | {
        type: 'provider';
        providerRef: MemoryContractSpecRef;
    } | {
        type: 'hybrid';
        stages: MemoryExtractionStageSpec[];
    };
    conversation?: {
        maxMessagesPerWindow: number;
        overlapMessages?: number;
        includeSystemMessages?: boolean;
        includeToolMessages?: boolean;
        extractionTrigger: 'each_turn' | 'window' | 'run_end' | 'session_idle' | 'manual';
    };
    episodic?: {
        boundary: 'run' | 'workflow_state' | 'task' | 'time_window' | 'custom';
        includeFailedEpisodes?: boolean;
        includeIntermediateObservations?: boolean;
    };
    truth?: {
        minimumAuthority: TruthAssertion['authority'];
        requireEvidence?: boolean;
        preserveValidityInterval?: boolean;
    };
    sensitiveDataPolicyRef?: MemoryContractSpecRef;
    candidateValidation: {
        minConfidence: number;
        requireCanonicalText: boolean;
        requireEvidence: boolean;
        maxCandidatesPerJob?: number;
        rejectInstructionLikeContent?: boolean;
    };
    writePolicyRef: MemoryContractSpecRef;
    maintenancePolicyRef: MemoryContractSpecRef;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
`acceptedSourceTypes`	property	`acceptedSourceTypes: MemoryExtractionSourceType[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`candidateValidation`	property	`candidateValidation: { minConfidence: number; requireCanonicalText: boolean; requireEvidence: boolean; maxCandidatesPerJob?: number; rejectInstructionLikeContent?: boolean; }`	Public property; its type, readonly modifier and optionality are shown in the signature.
`conversation`	property	`conversation?: { maxMessagesPerWindow: number; overlapMessages?: number; includeSystemMessages?: boolean; includeToolMessages?: boolean; extractionTrigger: "each_turn" \| "window" \| "run_end" \| "session_idle" \| "manual"; }`	Public property; its type, readonly modifier and optionality are shown in the signature.
`episodic`	property	`episodic?: { boundary: "run" \| "workflow_state" \| "task" \| "time_window" \| "custom"; includeFailedEpisodes?: boolean; includeIntermediateObservations?: boolean; }`	Public property; its type, readonly modifier and optionality are shown in the signature.
`extractor`	property	`extractor: { type: "deterministic"; extractorRef: MemoryContractSpecRef; } \| { type: "model"; modelProfileRef: MemoryContractSpecRef; promptTemplateRef: MemoryContractSpecRef; } \| { type: "provider"; providerRef: MemoryContractSpecRef; } \| { type: "hybrid"; stages: MemoryExtractionStageSpec[]; }`	Public property; its type, readonly modifier and optionality are shown in the signature.
`id`	property	`id: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`maintenancePolicyRef`	property	`maintenancePolicyRef: MemoryContractSpecRef`	Public property; its type, readonly modifier and optionality are shown in the signature.
`metadata`	property	`metadata?: Record<string, unknown>`	Public property; its type, readonly modifier and optionality are shown in the signature.
`outputMemoryTypes`	property	`outputMemoryTypes: ManagedMemoryType[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`revision`	property	`revision?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sensitiveDataPolicyRef`	property	`sensitiveDataPolicyRef?: MemoryContractSpecRef`	Public property; its type, readonly modifier and optionality are shown in the signature.
`truth`	property	`truth?: { minimumAuthority: TruthAssertion["authority"]; requireEvidence?: boolean; preserveValidityInterval?: boolean; }`	Public property; its type, readonly modifier and optionality are shown in the signature.
`version`	property	`version: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`writePolicyRef`	property	`writePolicyRef: MemoryContractSpecRef`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryExtractionRequest`

Memory Extraction Request interface with 9 public fields or methods.

Kind: interface
Import: import type { MemoryExtractionRequest } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryExtractionRequest {
    operationId: string;
    principal: MemoryPrincipal;
    scope: ManagedMemoryScope;
    profileRef: MemoryContractSpecRef;
    sources: MemoryExtractionSourceRef[];
    mode: 'sync' | 'async';
    force?: boolean;
    idempotencyKey?: string;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
`force`	property	`force?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`idempotencyKey`	property	`idempotencyKey?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`metadata`	property	`metadata?: Record<string, unknown>`	Public property; its type, readonly modifier and optionality are shown in the signature.
`mode`	property	`mode: "sync" \| "async"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`operationId`	property	`operationId: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`principal`	property	`principal: MemoryPrincipal`	Public property; its type, readonly modifier and optionality are shown in the signature.
`profileRef`	property	`profileRef: MemoryContractSpecRef`	Public property; its type, readonly modifier and optionality are shown in the signature.
`scope`	property	`scope: ManagedMemoryScope`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sources`	property	`sources: MemoryExtractionSourceRef[]`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryExtractionSourceAdapter`

Memory Extraction Source Adapter interface with 4 public fields or methods.

Kind: interface
Import: import type { MemoryExtractionSourceAdapter } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryExtractionSourceAdapter<T = unknown> {
    readonly type: MemoryExtractionSourceType;
    load(refs: MemoryExtractionSourceRef[], cursor?: MemoryExtractionCursor): Promise<MemoryExtractionSourceBatch<T>>;
    normalize(batch: MemoryExtractionSourceBatch<T>): Promise<NormalizedExtractionInput[]>;
    health(): Promise<ProviderHealth>;
}

Contract members

Member	Kind	Signature	Description
`health`	method	`health(): Promise<ProviderHealth>`	Public method; parameters and return type are shown in the signature.
`load`	method	`load(refs: MemoryExtractionSourceRef[], cursor?: MemoryExtractionCursor): Promise<MemoryExtractionSourceBatch<T>>`	Public method; parameters and return type are shown in the signature.
`normalize`	method	`normalize(batch: MemoryExtractionSourceBatch<T>): Promise<NormalizedExtractionInput[]>`	Public method; parameters and return type are shown in the signature.
`type`	property	`readonly type: MemoryExtractionSourceType`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryExtractionSourceBatch`

Memory Extraction Source Batch interface with 3 public fields or methods.

Kind: interface
Import: import type { MemoryExtractionSourceBatch } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryExtractionSourceBatch<T = unknown> {
    sourceRefs: MemoryExtractionSourceRef[];
    items: Array<{
        sourceRef: MemoryExtractionSourceRef;
        value: T;
    }>;
    nextCursor?: MemoryExtractionCursor;
}

Contract members

Member	Kind	Signature	Description
`items`	property	`items: { sourceRef: MemoryExtractionSourceRef; value: T; }[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`nextCursor`	property	`nextCursor?: MemoryExtractionCursor`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceRefs`	property	`sourceRefs: MemoryExtractionSourceRef[]`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryExtractionSourceRef`

Memory Extraction Source Ref interface with 15 public fields or methods.

Kind: interface
Import: import type { MemoryExtractionSourceRef } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryExtractionSourceRef {
    type: MemoryExtractionSourceType;
    sourceId: string;
    sourceVersion?: string;
    sourceHash?: string;
    sessionId?: string;
    runId?: string;
    messageIds?: string[];
    eventIds?: string[];
    artifactRefs?: string[];
    observedAt?: string;
    validFrom?: string;
    validTo?: string;
    authority?: 'unverified' | 'user_asserted' | 'system_observed' | 'verified' | 'authoritative';
    trustScore?: number;
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
`artifactRefs`	property	`artifactRefs?: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`authority`	property	`authority?: "verified" \| "unverified" \| "user_asserted" \| "system_observed" \| "authoritative"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`eventIds`	property	`eventIds?: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`messageIds`	property	`messageIds?: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`metadata`	property	`metadata?: Record<string, unknown>`	Public property; its type, readonly modifier and optionality are shown in the signature.
`observedAt`	property	`observedAt?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`runId`	property	`runId?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sessionId`	property	`sessionId?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceHash`	property	`sourceHash?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceId`	property	`sourceId: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceVersion`	property	`sourceVersion?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`trustScore`	property	`trustScore?: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`type`	property	`type: MemoryExtractionSourceType`	Public property; its type, readonly modifier and optionality are shown in the signature.
`validFrom`	property	`validFrom?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`validTo`	property	`validTo?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryExtractionStageSpec`

Memory Extraction Stage Spec interface with 6 public fields or methods.

Kind: interface
Import: import type { MemoryExtractionStageSpec } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryExtractionStageSpec {
    id: string;
    type: 'normalize' | 'classify' | 'extract' | 'validate' | 'enrich' | 'custom';
    handlerRef: MemoryContractSpecRef;
    optional?: boolean;
    timeoutMs?: number;
    retryPolicy?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
`handlerRef`	property	`handlerRef: MemoryContractSpecRef`	Public property; its type, readonly modifier and optionality are shown in the signature.
`id`	property	`id: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`optional`	property	`optional?: boolean`	Public property; its type, readonly modifier and optionality are shown in the signature.
`retryPolicy`	property	`retryPolicy?: Record<string, unknown>`	Public property; its type, readonly modifier and optionality are shown in the signature.
`timeoutMs`	property	`timeoutMs?: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`type`	property	`type: "custom" \| "validate" \| "normalize" \| "classify" \| "extract" \| "enrich"`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryExtractor`

Memory Extractor interface with 3 public fields or methods.

Kind: interface
Import: import type { MemoryExtractor } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryExtractor {
    readonly id: string;
    extract(inputs: NormalizedExtractionInput[], profile: MemoryExtractionProfileSpec): Promise<ExtractedMemoryCandidate[]>;
    health(): Promise<ProviderHealth>;
}

Contract members

Member	Kind	Signature	Description
`extract`	method	`extract(inputs: NormalizedExtractionInput[], profile: MemoryExtractionProfileSpec): Promise<ExtractedMemoryCandidate[]>`	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.
`id`	property	`readonly id: string`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryMaintenanceApplyRequest`

Memory Maintenance Apply Request interface with 3 public fields or methods.

Kind: interface
Import: import type { MemoryMaintenanceApplyRequest } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryMaintenanceApplyRequest {
    decision: MemoryMaintenanceDecision;
    candidate: ExtractedMemoryCandidate;
    scope: ManagedMemoryScope;
}

Contract members

Member	Kind	Signature	Description
`candidate`	property	`candidate: ExtractedMemoryCandidate`	Public property; its type, readonly modifier and optionality are shown in the signature.
`decision`	property	`decision: MemoryMaintenanceDecision`	Public property; its type, readonly modifier and optionality are shown in the signature.
`scope`	property	`scope: ManagedMemoryScope`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryMaintenanceDecision`

Memory Maintenance Decision interface with 18 public fields or methods.

Kind: interface
Import: import type { MemoryMaintenanceDecision } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryMaintenanceDecision {
    id: string;
    operationId: string;
    candidateId: string;
    scopeHash: string;
    action: MemoryMaintenanceAction;
    targetMemoryIds: string[];
    expectedRevisions: Record<string, number>;
    duplicateScore?: number;
    conflictScore?: number;
    authorityComparison?: 'candidate_higher' | 'existing_higher' | 'equal' | 'unknown';
    mergedContent?: unknown;
    patch?: MemoryPatch;
    relationsToCreate?: MemoryRelation[];
    recordsToInvalidate?: string[];
    reasonCode: 'NEW_FACT' | 'EXACT_DUPLICATE' | 'SEMANTIC_DUPLICATE' | 'ADDITIONAL_EVIDENCE' | 'FACT_CORRECTION' | 'TEMPORAL_UPDATE' | 'AUTHORITY_OVERRIDE' | 'CONFLICT_REQUIRES_REVIEW' | 'LOW_CONFIDENCE' | 'POLICY_REJECTED' | 'CUSTOM';
    explanation?: string;
    policyRevision: string;
    createdAt: string;
}

Contract members

Member	Kind	Signature	Description
`action`	property	`action: MemoryMaintenanceAction`	Public property; its type, readonly modifier and optionality are shown in the signature.
`authorityComparison`	property	`authorityComparison?: "unknown" \| "candidate_higher" \| "existing_higher" \| "equal"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`candidateId`	property	`candidateId: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`conflictScore`	property	`conflictScore?: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`createdAt`	property	`createdAt: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`duplicateScore`	property	`duplicateScore?: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`expectedRevisions`	property	`expectedRevisions: Record<string, number>`	Public property; its type, readonly modifier and optionality are shown in the signature.
`explanation`	property	`explanation?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`id`	property	`id: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`mergedContent`	property	`mergedContent?: unknown`	Public property; its type, readonly modifier and optionality are shown in the signature.
`operationId`	property	`operationId: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`patch`	property	`patch?: MemoryPatch`	Public property; its type, readonly modifier and optionality are shown in the signature.
`policyRevision`	property	`policyRevision: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`reasonCode`	property	`reasonCode: "CUSTOM" \| "NEW_FACT" \| "EXACT_DUPLICATE" \| "SEMANTIC_DUPLICATE" \| "ADDITIONAL_EVIDENCE" \| "FACT_CORRECTION" \| "TEMPORAL_UPDATE" \| "AUTHORITY_OVERRIDE" \| "CONFLICT_REQUIRES_REVIEW" \| "LOW_CONFIDENCE" \| "POLICY_REJECTED"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`recordsToInvalidate`	property	`recordsToInvalidate?: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`relationsToCreate`	property	`relationsToCreate?: MemoryRelation[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`scopeHash`	property	`scopeHash: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`targetMemoryIds`	property	`targetMemoryIds: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryMaintenancePlanner`

Memory Maintenance Planner interface with 3 public fields or methods.

Kind: interface
Import: import type { MemoryMaintenancePlanner } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryMaintenancePlanner {
    plan(request: MemoryMaintenancePlanRequest): Promise<MemoryMaintenanceDecision>;
    apply(request: MemoryMaintenanceApplyRequest): Promise<ManagedMemoryWriteResult>;
    explain(decisionId: string): Promise<MemoryMaintenanceDecision | null>;
}

Contract members

Member	Kind	Signature	Description
`apply`	method	`apply(request: MemoryMaintenanceApplyRequest): Promise<ManagedMemoryWriteResult>`	Public method; parameters and return type are shown in the signature.
`explain`	method	`explain(decisionId: string): Promise<MemoryMaintenanceDecision \| null>`	Public method; parameters and return type are shown in the signature.
`plan`	method	`plan(request: MemoryMaintenancePlanRequest): Promise<MemoryMaintenanceDecision>`	Public method; parameters and return type are shown in the signature.

`MemoryMaintenancePlanRequest`

Memory Maintenance Plan Request interface with 5 public fields or methods.

Kind: interface
Import: import type { MemoryMaintenancePlanRequest } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryMaintenancePlanRequest {
    operationId: string;
    scope: ManagedMemoryScope;
    candidate: ExtractedMemoryCandidate;
    existingRecords: ManagedMemoryRecord[];
    policy: MemoryMaintenancePolicySpec;
}

Contract members

Member	Kind	Signature	Description
`candidate`	property	`candidate: ExtractedMemoryCandidate`	Public property; its type, readonly modifier and optionality are shown in the signature.
`existingRecords`	property	`existingRecords: ManagedMemoryRecord<unknown>[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`operationId`	property	`operationId: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`policy`	property	`policy: MemoryMaintenancePolicySpec`	Public property; its type, readonly modifier and optionality are shown in the signature.
`scope`	property	`scope: ManagedMemoryScope`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryMaintenancePolicySpec`

Memory Maintenance Policy Spec interface with 8 public fields or methods.

Kind: interface
Import: import type { MemoryMaintenancePolicySpec } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface MemoryMaintenancePolicySpec {
    id: string;
    version: string;
    revision?: string;
    preWriteRetrieval: {
        enabled: boolean;
        exactKeyLookup: boolean;
        semanticLookup?: boolean;
        maxCandidates: number;
        semanticThreshold?: number;
        includeSuperseded?: boolean;
        includeInvalidated?: boolean;
    };
    duplicateResolution: 'reuse_existing' | 'increase_support' | 'create_version' | 'require_review';
    updateResolution: 'patch_current' | 'create_version' | 'supersede' | 'require_review';
    conflictResolution: 'keep_both_marked' | 'prefer_authoritative' | 'prefer_verified' | 'prefer_latest' | 'invalidate_old' | 'require_review';
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
`conflictResolution`	property	`conflictResolution: "prefer_latest" \| "prefer_verified" \| "require_review" \| "keep_both_marked" \| "prefer_authoritative" \| "invalidate_old"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`duplicateResolution`	property	`duplicateResolution: "reuse_existing" \| "increase_support" \| "create_version" \| "require_review"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`id`	property	`id: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`metadata`	property	`metadata?: Record<string, unknown>`	Public property; its type, readonly modifier and optionality are shown in the signature.
`preWriteRetrieval`	property	`preWriteRetrieval: { enabled: boolean; exactKeyLookup: boolean; semanticLookup?: boolean; maxCandidates: number; semanticThreshold?: number; includeSuperseded?: boolean; includeInvalidated?: boolean; }`	Public property; its type, readonly modifier and optionality are shown in the signature.
`revision`	property	`revision?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`updateResolution`	property	`updateResolution: "create_version" \| "require_review" \| "patch_current" \| "supersede"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`version`	property	`version: string`	Public property; its type, readonly modifier and optionality are shown in the signature.

`NormalizedExtractionInput`

Normalized Extraction Input interface with 3 public fields or methods.

Kind: interface
Import: import type { NormalizedExtractionInput } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface NormalizedExtractionInput {
    sourceRef: MemoryExtractionSourceRef;
    value: unknown;
    canonicalText?: string;
}

Contract members

Member	Kind	Signature	Description
`canonicalText`	property	`canonicalText?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`sourceRef`	property	`sourceRef: MemoryExtractionSourceRef`	Public property; its type, readonly modifier and optionality are shown in the signature.
`value`	property	`value: unknown`	Public property; its type, readonly modifier and optionality are shown in the signature.

`TruthAssertion`

Truth Assertion interface with 11 public fields or methods.

Kind: interface
Import: import type { TruthAssertion } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export interface TruthAssertion {
    assertionId: string;
    subject: string;
    predicate: string;
    object: unknown;
    authority: 'user_confirmed' | 'human_reviewed' | 'system_of_record' | 'policy_defined';
    confidence: number;
    validFrom?: string;
    validTo?: string;
    supersedesAssertionId?: string;
    evidenceRefs: string[];
    metadata?: Record<string, unknown>;
}

Contract members

Member	Kind	Signature	Description
`assertionId`	property	`assertionId: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`authority`	property	`authority: "user_confirmed" \| "human_reviewed" \| "system_of_record" \| "policy_defined"`	Public property; its type, readonly modifier and optionality are shown in the signature.
`confidence`	property	`confidence: number`	Public property; its type, readonly modifier and optionality are shown in the signature.
`evidenceRefs`	property	`evidenceRefs: string[]`	Public property; its type, readonly modifier and optionality are shown in the signature.
`metadata`	property	`metadata?: Record<string, unknown>`	Public property; its type, readonly modifier and optionality are shown in the signature.
`object`	property	`object: unknown`	Public property; its type, readonly modifier and optionality are shown in the signature.
`predicate`	property	`predicate: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`subject`	property	`subject: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`supersedesAssertionId`	property	`supersedesAssertionId?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`validFrom`	property	`validFrom?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.
`validTo`	property	`validTo?: string`	Public property; its type, readonly modifier and optionality are shown in the signature.

`MemoryExtractionSourceType`

Public type alias for Memory Extraction Source Type; the declaration contains its complete type expression.

Kind: type
Import: import type { MemoryExtractionSourceType } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export type MemoryExtractionSourceType = 'conversation' | 'truth' | 'episodic_record' | 'runtime_event' | 'tool_observation' | 'artifact' | 'structured_record' | 'custom';

`MemoryMaintenanceAction`

Public type alias for Memory Maintenance Action; the declaration contains its complete type expression.

Kind: type
Import: import type { MemoryMaintenanceAction } from '@codesoul-co/hypha-memory';
Source module: lifecycle-contracts

Declaration

text

export type MemoryMaintenanceAction = 'create' | 'noop' | 'reuse' | 'update' | 'merge' | 'supersede' | 'invalidate' | 'reject' | 'require_review';

@codesoul-co/hypha-memory / lifecycle-contracts ​

Using this module ​

Import from the package entrypoint ​

Usage patterns ​

Public exports ​

EpisodicRecordInput ​

Declaration ​

Contract members ​

ExtractedMemoryCandidate ​

Declaration ​

Contract members ​

ExtractedMemoryEvidence ​

Declaration ​

Contract members ​

MemoryExtractionBatch ​

Declaration ​

Contract members ​

MemoryExtractionCursor ​

Declaration ​

Contract members ​

MemoryExtractionJob ​

Declaration ​

Contract members ​

MemoryExtractionProfileSpec ​

Declaration ​

Contract members ​

MemoryExtractionRequest ​

Declaration ​

Contract members ​

MemoryExtractionSourceAdapter ​

Declaration ​

Contract members ​

MemoryExtractionSourceBatch ​

Declaration ​

Contract members ​

MemoryExtractionSourceRef ​

Declaration ​

Contract members ​

MemoryExtractionStageSpec ​

Declaration ​

Contract members ​

MemoryExtractor ​

Declaration ​

Contract members ​

MemoryMaintenanceApplyRequest ​

Declaration ​

Contract members ​

MemoryMaintenanceDecision ​

Declaration ​

Contract members ​

MemoryMaintenancePlanner ​

Declaration ​

Contract members ​

MemoryMaintenancePlanRequest ​

Declaration ​

Contract members ​

MemoryMaintenancePolicySpec ​

Declaration ​

Contract members ​

NormalizedExtractionInput ​

Declaration ​

Contract members ​

TruthAssertion ​

Declaration ​

Contract members ​

MemoryExtractionSourceType ​

Declaration ​

MemoryMaintenanceAction ​

Declaration ​

`@codesoul-co/hypha-memory` / `lifecycle-contracts`

Using this module

Import from the package entrypoint

Usage patterns

Public exports

`EpisodicRecordInput`

Declaration

Contract members

`ExtractedMemoryCandidate`

Declaration

Contract members

`ExtractedMemoryEvidence`

Declaration

Contract members

`MemoryExtractionBatch`

Declaration

Contract members

`MemoryExtractionCursor`

Declaration

Contract members

`MemoryExtractionJob`

Declaration

Contract members

`MemoryExtractionProfileSpec`

Declaration

Contract members

`MemoryExtractionRequest`

Declaration

Contract members

`MemoryExtractionSourceAdapter`

Declaration

Contract members

`MemoryExtractionSourceBatch`

Declaration

Contract members

`MemoryExtractionSourceRef`

Declaration

Contract members

`MemoryExtractionStageSpec`

Declaration

Contract members

`MemoryExtractor`

Declaration

Contract members

`MemoryMaintenanceApplyRequest`

Declaration

Contract members

`MemoryMaintenanceDecision`

Declaration

Contract members

`MemoryMaintenancePlanner`

Declaration

Contract members

`MemoryMaintenancePlanRequest`

Declaration

Contract members

`MemoryMaintenancePolicySpec`

Declaration

Contract members

`NormalizedExtractionInput`

Declaration

Contract members

`TruthAssertion`

Declaration

Contract members

`MemoryExtractionSourceType`

Declaration

`MemoryMaintenanceAction`

Declaration