agent-memory-client 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,828 @@
+/**
+ * Filter classes for search operations.
+ *
+ * These filters allow for filtering memory search results.
+ */
+/**
+ * Filter by session ID
+ */
+declare class SessionId {
+    eq?: string;
+    in_?: string[];
+    not_eq?: string;
+    not_in?: string[];
+    ne?: string;
+    constructor(options?: {
+        eq?: string;
+        in_?: string[];
+        not_eq?: string;
+        not_in?: string[];
+        ne?: string;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Filter by namespace
+ */
+declare class Namespace {
+    eq?: string;
+    in_?: string[];
+    not_eq?: string;
+    not_in?: string[];
+    constructor(options?: {
+        eq?: string;
+        in_?: string[];
+        not_eq?: string;
+        not_in?: string[];
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Filter by user ID
+ */
+declare class UserId {
+    eq?: string;
+    in_?: string[];
+    not_eq?: string;
+    not_in?: string[];
+    constructor(options?: {
+        eq?: string;
+        in_?: string[];
+        not_eq?: string;
+        not_in?: string[];
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Filter by topics
+ */
+declare class Topics {
+    any?: string[];
+    all?: string[];
+    none?: string[];
+    constructor(options?: {
+        any?: string[];
+        all?: string[];
+        none?: string[];
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Filter by entities
+ */
+declare class Entities {
+    any?: string[];
+    all?: string[];
+    none?: string[];
+    constructor(options?: {
+        any?: string[];
+        all?: string[];
+        none?: string[];
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Filter by creation date
+ */
+declare class CreatedAt {
+    gte?: Date | string;
+    lte?: Date | string;
+    eq?: Date | string;
+    constructor(options?: {
+        gte?: Date | string;
+        lte?: Date | string;
+        eq?: Date | string;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Filter by last accessed date
+ */
+declare class LastAccessed {
+    gte?: Date | string;
+    lte?: Date | string;
+    eq?: Date | string;
+    constructor(options?: {
+        gte?: Date | string;
+        lte?: Date | string;
+        eq?: Date | string;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Filter by event date
+ */
+declare class EventDate {
+    gte?: Date | string;
+    lte?: Date | string;
+    eq?: Date | string;
+    constructor(options?: {
+        gte?: Date | string;
+        lte?: Date | string;
+        eq?: Date | string;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Filter by memory type
+ */
+declare class MemoryType {
+    eq?: string;
+    in_?: string[];
+    not_eq?: string;
+    not_in?: string[];
+    constructor(options?: {
+        eq?: string;
+        in_?: string[];
+        not_eq?: string;
+        not_in?: string[];
+    });
+    toJSON(): Record<string, unknown>;
+}
+
+/**
+ * Data models for the Agent Memory Client.
+ *
+ * This module contains essential data models needed by the client.
+ */
+/**
+ * Supported LLM model names for context window determination
+ */
+type ModelNameLiteral = "gpt-3.5-turbo" | "gpt-3.5-turbo-16k" | "gpt-4" | "gpt-4-32k" | "gpt-4o" | "gpt-4o-mini" | "o1" | "o1-mini" | "o3-mini" | "gpt-5-mini" | "gpt-5-nano" | "gpt-5.1-chat-latest" | "gpt-5.2-chat-latest" | "text-embedding-ada-002" | "text-embedding-3-small" | "text-embedding-3-large" | "claude-3-opus-20240229" | "claude-3-sonnet-20240229" | "claude-3-haiku-20240307" | "claude-3-5-sonnet-20240620" | "claude-3-7-sonnet-20250219" | "claude-3-5-sonnet-20241022" | "claude-3-5-haiku-20241022" | "claude-3-7-sonnet-latest" | "claude-3-5-sonnet-latest" | "claude-3-5-haiku-latest" | "claude-3-opus-latest";
+/**
+ * Enum for memory types
+ */
+declare enum MemoryTypeEnum {
+    EPISODIC = "episodic",
+    SEMANTIC = "semantic",
+    MESSAGE = "message"
+}
+/**
+ * Memory extraction strategy types
+ */
+type MemoryStrategyType = "discrete" | "summary" | "preferences" | "custom";
+/**
+ * Configuration for memory extraction strategy
+ */
+interface MemoryStrategyConfig {
+    /** Type of memory extraction strategy to use */
+    strategy?: MemoryStrategyType;
+    /** Strategy-specific configuration options */
+    config?: Record<string, unknown>;
+}
+/**
+ * A message in the memory system
+ */
+interface MemoryMessage {
+    /** Message role (user, assistant, system, tool) */
+    role: string;
+    /** Message content */
+    content: string;
+    /** Unique identifier for the message */
+    id?: string;
+    /** Timestamp when the message was created */
+    created_at?: string;
+    /** Server-assigned timestamp when message was persisted */
+    persisted_at?: string | null;
+    /** Whether memory extraction has run for this message */
+    discrete_memory_extracted?: "t" | "f";
+}
+/**
+ * A memory record
+ */
+interface MemoryRecord {
+    /** Client-provided ID for deduplication and overwrites */
+    id: string;
+    /** Memory content text */
+    text: string;
+    /** Optional session ID for the memory record */
+    session_id?: string | null;
+    /** Optional user ID for the memory record */
+    user_id?: string | null;
+    /** Optional namespace for the memory record */
+    namespace?: string | null;
+    /** Datetime when the memory was last accessed */
+    last_accessed?: string;
+    /** Datetime when the memory was created */
+    created_at?: string;
+    /** Datetime when the memory was last updated */
+    updated_at?: string;
+    /** Optional topics for the memory record */
+    topics?: string[] | null;
+    /** Optional entities for the memory record */
+    entities?: string[] | null;
+    /** Hash representation of the memory for deduplication */
+    memory_hash?: string | null;
+    /** Whether memory extraction has run for this memory */
+    discrete_memory_extracted?: "t" | "f";
+    /** Type of memory */
+    memory_type?: MemoryTypeEnum;
+    /** Server-assigned timestamp when memory was persisted */
+    persisted_at?: string | null;
+    /** List of message IDs that this memory was extracted from */
+    extracted_from?: string[] | null;
+    /** Date/time when the event described in this memory occurred */
+    event_date?: string | null;
+}
+/** JSON value types for working memory data */
+type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+/**
+ * Working memory for a session
+ */
+interface WorkingMemory {
+    /** Session ID (required) */
+    session_id: string;
+    /** Conversation messages */
+    messages?: MemoryMessage[];
+    /** Structured memory records */
+    memories?: MemoryRecord[];
+    /** Arbitrary JSON data storage */
+    data?: Record<string, JSONValue> | null;
+    /** Optional summary of past session messages */
+    context?: string | null;
+    /** Optional user ID */
+    user_id?: string | null;
+    /** Token count */
+    tokens?: number;
+    /** Optional namespace */
+    namespace?: string | null;
+    /** Configuration for memory extraction strategy */
+    long_term_memory_strategy?: MemoryStrategyConfig;
+    /** TTL for the working memory in seconds */
+    ttl_seconds?: number | null;
+    /** Datetime when the working memory was last accessed */
+    last_accessed?: string;
+}
+/**
+ * Response from working memory operations
+ */
+interface WorkingMemoryResponse extends WorkingMemory {
+    /** Percentage of total context window currently used (0-100) */
+    context_percentage_total_used?: number | null;
+    /** Percentage until auto-summarization triggers (0-100) */
+    context_percentage_until_summarization?: number | null;
+    /** True if session was created, False if existing */
+    new_session?: boolean | null;
+    /** True if this session data has not been persisted yet */
+    unsaved?: boolean | null;
+}
+/**
+ * Generic acknowledgement response
+ */
+interface AckResponse {
+    status: string;
+}
+/**
+ * Health check response
+ */
+interface HealthCheckResponse {
+    now: number;
+}
+/**
+ * Response containing a list of sessions
+ */
+interface SessionListResponse {
+    sessions: string[];
+    total: number;
+}
+/**
+ * Result from a memory search
+ */
+interface MemoryRecordResult extends MemoryRecord {
+    /** Distance/similarity score */
+    dist: number;
+}
+/**
+ * Results from memory search operations
+ */
+interface MemoryRecordResults {
+    memories: MemoryRecordResult[];
+    total: number;
+    next_offset?: number | null;
+}
+/**
+ * Client-side configuration for recency-aware ranking
+ */
+interface RecencyConfig {
+    /** Enable recency-aware re-ranking */
+    recency_boost?: boolean | null;
+    /** Weight for semantic similarity */
+    semantic_weight?: number | null;
+    /** Weight for recency score */
+    recency_weight?: number | null;
+    /** Weight for freshness component */
+    freshness_weight?: number | null;
+    /** Weight for novelty/age component */
+    novelty_weight?: number | null;
+    /** Half-life (days) for last_accessed decay */
+    half_life_last_access_days?: number | null;
+    /** Half-life (days) for created_at decay */
+    half_life_created_days?: number | null;
+    /** If true, attempt server-side recency ranking */
+    server_side_recency?: boolean | null;
+}
+/**
+ * Response from memory prompt endpoint
+ */
+interface MemoryPromptResponse {
+    messages: Record<string, unknown>[];
+}
+/**
+ * Session parameters for memory prompt
+ */
+interface SessionParams {
+    session_id: string;
+    user_id?: string | null;
+    namespace?: string | null;
+    model_name?: ModelNameLiteral | null;
+    context_window_max?: number | null;
+}
+/**
+ * Request for memory prompt endpoint
+ */
+interface MemoryPromptRequest {
+    query: string;
+    session?: SessionParams | null;
+    long_term_search?: SearchRequestParams | boolean | null;
+}
+/**
+ * Parameters for long-term memory search
+ */
+interface SearchRequestParams {
+    text?: string;
+    session_id?: SessionIdFilter | null;
+    namespace?: NamespaceFilter | null;
+    topics?: TopicsFilter | null;
+    entities?: EntitiesFilter | null;
+    created_at?: CreatedAtFilter | null;
+    last_accessed?: LastAccessedFilter | null;
+    user_id?: UserIdFilter | null;
+    memory_type?: MemoryTypeFilter | null;
+    event_date?: EventDateFilter | null;
+    distance_threshold?: number | null;
+    limit?: number;
+    offset?: number;
+    recency_boost?: boolean | null;
+    recency_semantic_weight?: number | null;
+    recency_recency_weight?: number | null;
+    recency_freshness_weight?: number | null;
+    recency_novelty_weight?: number | null;
+    recency_half_life_last_access_days?: number | null;
+    recency_half_life_created_days?: number | null;
+    server_side_recency?: boolean | null;
+}
+interface SessionIdFilter {
+    eq?: string | null;
+    in_?: string[] | null;
+    not_eq?: string | null;
+    not_in?: string[] | null;
+    ne?: string | null;
+}
+interface NamespaceFilter {
+    eq?: string | null;
+    in_?: string[] | null;
+    not_eq?: string | null;
+    not_in?: string[] | null;
+}
+interface UserIdFilter {
+    eq?: string | null;
+    in_?: string[] | null;
+    not_eq?: string | null;
+    not_in?: string[] | null;
+}
+interface TopicsFilter {
+    any?: string[] | null;
+    all?: string[] | null;
+    none?: string[] | null;
+}
+interface EntitiesFilter {
+    any?: string[] | null;
+    all?: string[] | null;
+    none?: string[] | null;
+}
+interface CreatedAtFilter {
+    gte?: string | null;
+    lte?: string | null;
+    eq?: string | null;
+}
+interface LastAccessedFilter {
+    gte?: string | null;
+    lte?: string | null;
+    eq?: string | null;
+}
+interface EventDateFilter {
+    gte?: string | null;
+    lte?: string | null;
+    eq?: string | null;
+}
+interface MemoryTypeFilter {
+    eq?: string | null;
+    in_?: string[] | null;
+    not_eq?: string | null;
+    not_in?: string[] | null;
+}
+/**
+ * Policy for forgetting memories
+ */
+interface ForgetPolicy {
+    /** Maximum age in days for memories to keep */
+    max_age_days?: number | null;
+    /** Maximum inactive days before forgetting */
+    max_inactive_days?: number | null;
+    /** Budget limit for forgetting operation */
+    budget?: number | null;
+    /** Allowlist of memory types to consider for forgetting */
+    memory_type_allowlist?: string[] | null;
+}
+/**
+ * Response from forget operation
+ */
+interface ForgetResponse {
+    /** Number of memories scanned */
+    scanned: number;
+    /** Number of memories deleted */
+    deleted: number;
+    /** IDs of deleted memories */
+    deleted_ids: string[];
+    /** Whether this was a dry run */
+    dry_run: boolean;
+}
+/**
+ * Source type for summary views
+ */
+type SummaryViewSource = "long_term" | "working_memory";
+/**
+ * Summary view configuration
+ */
+interface SummaryView {
+    /** Unique identifier for the view */
+    id: string;
+    /** Optional human-readable name */
+    name?: string | null;
+    /** Memory source to summarize */
+    source: SummaryViewSource;
+    /** Fields to group by for partitioning */
+    group_by: string[];
+    /** Optional filters to apply */
+    filters?: Record<string, unknown> | null;
+    /** Time window in days for filtering */
+    time_window_days?: number | null;
+    /** Whether background workers refresh this view */
+    continuous?: boolean;
+    /** Custom summarization prompt */
+    prompt?: string | null;
+    /** Model override for summarization */
+    model_name?: string | null;
+}
+/**
+ * Request to create a summary view
+ */
+interface CreateSummaryViewRequest {
+    /** Optional human-readable name */
+    name?: string | null;
+    /** Memory source to summarize */
+    source: SummaryViewSource;
+    /** Fields to group by for partitioning */
+    group_by: string[];
+    /** Optional filters to apply */
+    filters?: Record<string, unknown> | null;
+    /** Time window in days for filtering */
+    time_window_days?: number | null;
+    /** Whether background workers refresh this view */
+    continuous?: boolean;
+    /** Custom summarization prompt */
+    prompt?: string | null;
+    /** Model override for summarization */
+    model_name?: string | null;
+}
+/**
+ * Result of summarizing one partition
+ */
+interface SummaryViewPartitionResult {
+    /** ID of the SummaryView that produced this result */
+    view_id: string;
+    /** Concrete values for the view's group_by fields */
+    group: Record<string, string>;
+    /** Summarized text for this partition */
+    summary: string;
+    /** Number of memories that contributed to this summary */
+    memory_count: number;
+    /** When this summary was computed */
+    computed_at?: string;
+}
+/**
+ * Request to run a summary view partition
+ */
+interface RunSummaryViewPartitionRequest {
+    /** Concrete values for the view's group_by fields */
+    group: Record<string, string>;
+}
+/**
+ * Request to run a full summary view
+ */
+interface RunSummaryViewRequest {
+    /** Force recomputation even if cached */
+    force?: boolean;
+}
+/**
+ * Task type enum
+ */
+type TaskType = "summary_view_full_run" | string;
+/**
+ * Task status enum
+ */
+type TaskStatus = "pending" | "running" | "completed" | "failed";
+/**
+ * Background task representation
+ */
+interface Task {
+    /** Unique task identifier */
+    id: string;
+    /** Type of task */
+    type: TaskType;
+    /** Current task status */
+    status: TaskStatus;
+    /** Associated SummaryView ID, if applicable */
+    view_id?: string | null;
+    /** When the task record was created */
+    created_at?: string;
+    /** When execution started */
+    started_at?: string | null;
+    /** When execution finished */
+    completed_at?: string | null;
+    /** Error message if failed */
+    error_message?: string | null;
+}
+
+/**
+ * Agent Memory API Client
+ *
+ * A TypeScript/JavaScript client for the Agent Memory Server REST API.
+ */
+
+/**
+ * Configuration for the Memory API Client
+ */
+interface MemoryClientConfig {
+    /** Base URL of the memory server (e.g., 'http://localhost:8000') */
+    baseUrl: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Optional default namespace to use for operations */
+    defaultNamespace?: string;
+    /** Optional default model name for auto-summarization */
+    defaultModelName?: ModelNameLiteral;
+    /** Optional default context window limit for auto-summarization */
+    defaultContextWindowMax?: number;
+    /** Optional API key for authentication */
+    apiKey?: string;
+    /** Optional bearer token for authentication */
+    bearerToken?: string;
+    /** Custom fetch function (for testing or custom implementations) */
+    fetch?: typeof fetch;
+}
+/**
+ * Options for search operations
+ */
+interface SearchOptions {
+    text: string;
+    sessionId?: SessionId | {
+        eq?: string;
+        in_?: string[];
+        not_eq?: string;
+        not_in?: string[];
+    };
+    namespace?: Namespace | {
+        eq?: string;
+        in_?: string[];
+        not_eq?: string;
+        not_in?: string[];
+    };
+    topics?: Topics | {
+        any?: string[];
+        all?: string[];
+        none?: string[];
+    };
+    entities?: Entities | {
+        any?: string[];
+        all?: string[];
+        none?: string[];
+    };
+    createdAt?: CreatedAt | {
+        gte?: Date | string;
+        lte?: Date | string;
+        eq?: Date | string;
+    };
+    lastAccessed?: LastAccessed | {
+        gte?: Date | string;
+        lte?: Date | string;
+        eq?: Date | string;
+    };
+    userId?: UserId | {
+        eq?: string;
+        in_?: string[];
+        not_eq?: string;
+        not_in?: string[];
+    };
+    memoryType?: MemoryType | {
+        eq?: string;
+        in_?: string[];
+        not_eq?: string;
+        not_in?: string[];
+    };
+    eventDate?: EventDate | {
+        gte?: Date | string;
+        lte?: Date | string;
+        eq?: Date | string;
+    };
+    distanceThreshold?: number;
+    limit?: number;
+    offset?: number;
+    recency?: RecencyConfig;
+    optimizeQuery?: boolean;
+}
+/**
+ * Client for the Agent Memory Server REST API.
+ *
+ * Provides methods to interact with all server endpoints:
+ * - Health check
+ * - Session management (list, get, put, delete)
+ * - Long-term memory (create, search, edit, delete)
+ */
+declare class MemoryAPIClient {
+    private readonly config;
+    private readonly fetchFn;
+    constructor(config: MemoryClientConfig);
+    /**
+     * Get default headers for requests
+     */
+    private getHeaders;
+    /**
+     * Make an HTTP request with error handling
+     */
+    private request;
+    /**
+     * Handle HTTP error responses
+     */
+    private handleHttpError;
+    /**
+     * Check server health
+     */
+    healthCheck(): Promise<HealthCheckResponse>;
+    /**
+     * List all session IDs
+     */
+    listSessions(options?: {
+        namespace?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<SessionListResponse>;
+    /**
+     * Get working memory for a session
+     */
+    getWorkingMemory(sessionId: string, options?: {
+        namespace?: string;
+        modelName?: ModelNameLiteral;
+        contextWindowMax?: number;
+    }): Promise<WorkingMemoryResponse | null>;
+    /**
+     * Get or create working memory for a session
+     */
+    getOrCreateWorkingMemory(sessionId: string, options?: {
+        namespace?: string;
+        userId?: string;
+        modelName?: ModelNameLiteral;
+        contextWindowMax?: number;
+        ttlSeconds?: number;
+        longTermMemoryStrategy?: MemoryStrategyConfig;
+    }): Promise<WorkingMemoryResponse>;
+    /**
+     * Create or update working memory for a session
+     */
+    putWorkingMemory(sessionId: string, workingMemory: Partial<WorkingMemory>, options?: {
+        namespace?: string;
+        modelName?: ModelNameLiteral;
+        contextWindowMax?: number;
+        background?: boolean;
+    }): Promise<WorkingMemoryResponse>;
+    /**
+     * Delete working memory for a session
+     */
+    deleteWorkingMemory(sessionId: string, options?: {
+        namespace?: string;
+    }): Promise<AckResponse>;
+    /**
+     * Create long-term memory records
+     */
+    createLongTermMemory(memories: MemoryRecord[], options?: {
+        namespace?: string;
+    }): Promise<AckResponse>;
+    /**
+     * Search long-term memory
+     */
+    searchLongTermMemory(options: SearchOptions): Promise<MemoryRecordResults>;
+    /**
+     * Get a long-term memory by ID
+     */
+    getLongTermMemory(memoryId: string, options?: {
+        namespace?: string;
+    }): Promise<MemoryRecord | null>;
+    /**
+     * Delete long-term memories by IDs
+     */
+    deleteLongTermMemories(memoryIds: string[], options?: {
+        namespace?: string;
+    }): Promise<AckResponse>;
+    /**
+     * Get memory-enhanced prompt
+     */
+    memoryPrompt(request: MemoryPromptRequest): Promise<MemoryPromptResponse>;
+    /**
+     * Edit a long-term memory by ID
+     */
+    editLongTermMemory(memoryId: string, updates: Partial<MemoryRecord>): Promise<MemoryRecord>;
+    /**
+     * Run a forgetting pass with the provided policy
+     */
+    forgetLongTermMemories(options: {
+        policy: ForgetPolicy;
+        namespace?: string;
+        userId?: string;
+        sessionId?: string;
+        limit?: number;
+        dryRun?: boolean;
+        pinnedIds?: string[];
+    }): Promise<ForgetResponse>;
+    /**
+     * List all summary views
+     */
+    listSummaryViews(): Promise<SummaryView[]>;
+    /**
+     * Create a new summary view
+     */
+    createSummaryView(request: CreateSummaryViewRequest): Promise<SummaryView>;
+    /**
+     * Get a summary view by ID
+     */
+    getSummaryView(viewId: string): Promise<SummaryView | null>;
+    /**
+     * Delete a summary view
+     */
+    deleteSummaryView(viewId: string): Promise<AckResponse>;
+    /**
+     * Run a summary view partition
+     */
+    runSummaryViewPartition(viewId: string, group: Record<string, string>): Promise<SummaryViewPartitionResult>;
+    /**
+     * List summary view partitions
+     */
+    listSummaryViewPartitions(viewId: string, options?: {
+        namespace?: string;
+        userId?: string;
+        sessionId?: string;
+        memoryType?: string;
+    }): Promise<SummaryViewPartitionResult[]>;
+    /**
+     * Run a full summary view (async task)
+     */
+    runSummaryView(viewId: string, options?: {
+        force?: boolean;
+    }): Promise<Task>;
+    /**
+     * Get a task by ID
+     */
+    getTask(taskId: string): Promise<Task | null>;
+}
+
+/**
+ * Exception classes for the Agent Memory Client.
+ */
+/**
+ * Base error for all memory client errors.
+ */
+declare class MemoryClientError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raised when memory record or filter validation fails.
+ */
+declare class MemoryValidationError extends MemoryClientError {
+    constructor(message: string);
+}
+/**
+ * Raised when a requested memory or session is not found.
+ */
+declare class MemoryNotFoundError extends MemoryClientError {
+    constructor(message: string);
+}
+/**
+ * Raised when the memory server returns an error.
+ */
+declare class MemoryServerError extends MemoryClientError {
+    statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+
+export { type AckResponse, type CreateSummaryViewRequest, CreatedAt, Entities, EventDate, type ForgetPolicy, type ForgetResponse, type HealthCheckResponse, LastAccessed, MemoryAPIClient, type MemoryClientConfig, MemoryClientError, type MemoryMessage, MemoryNotFoundError, type MemoryPromptRequest, type MemoryPromptResponse, type MemoryRecord, type MemoryRecordResult, type MemoryRecordResults, MemoryServerError, MemoryType, MemoryValidationError, Namespace, type RecencyConfig, type RunSummaryViewPartitionRequest, type RunSummaryViewRequest, type SearchOptions, SessionId, type SessionListResponse, type SummaryView, type SummaryViewPartitionResult, type SummaryViewSource, type Task, type TaskStatus, type TaskType, Topics, UserId, type WorkingMemory, type WorkingMemoryResponse };