@elizaos/agent 0.25.9 → 2.0.0-alpha.144

package/packages/typescript/src/types/hook.d.ts

@@ -0,0 +1,338 @@
+/**
+ * Hook Service Type Definitions
+ *
+ * Provides the type system for the unified hook service that consolidates
+ * event-driven hooks across the Eliza agent runtime.
+ */
+import { type EventPayload, EventType } from "./events";
+import type { Service } from "./service";
+/**
+ * Identifies the origin of a hook registration.
+ */
+export type HookSource = "bundled" | "managed" | "workspace" | "plugin" | "runtime";
+/**
+ * Hook priority. Higher values run first. Default is 0.
+ * Hooks with the same priority run in FIFO order (registration time).
+ */
+export type HookPriority = number;
+/**
+ * Default hook priority (FIFO ordering)
+ */
+export declare const DEFAULT_HOOK_PRIORITY: HookPriority;
+/**
+ * Specifies requirements that must be met for a hook to be eligible.
+ * If any requirement is not met, the hook will not be triggered.
+ */
+export interface HookRequirements {
+    /** Operating systems where this hook is valid (e.g., ["darwin", "linux"]) */
+    os?: string[];
+    /** Binary executables that must be available in PATH (all required) */
+    bins?: string[];
+    /** Binary executables where at least one must be available */
+    anyBins?: string[];
+    /** Environment variables that must be set */
+    env?: string[];
+    /** Configuration paths that must be truthy (e.g., ["workspace.dir"]) */
+    config?: string[];
+}
+/**
+ * Result of an eligibility check for a hook.
+ */
+export interface HookEligibilityResult {
+    /** Whether the hook is eligible to run */
+    eligible: boolean;
+    /** Reasons why the hook is not eligible (if applicable) */
+    reasons?: string[];
+}
+/**
+ * Metadata describing a registered hook.
+ */
+export interface HookMetadata {
+    /** Display name of the hook */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Source/origin of the hook */
+    source: HookSource;
+    /** Plugin ID if registered by a plugin */
+    pluginId?: string;
+    /** Event types this hook listens to */
+    events: EventType[];
+    /** Execution priority (higher runs first) */
+    priority: HookPriority;
+    /** Whether the hook is currently enabled */
+    enabled: boolean;
+    /** If true, bypass eligibility checks (except explicit disable) */
+    always?: boolean;
+    /** Requirements for this hook to be eligible */
+    requires?: HookRequirements;
+}
+/**
+ * Handler function for hook events.
+ * Receives the event payload and can modify it (for modifying hooks).
+ */
+export type HookHandler<T extends EventPayload = EventPayload> = (payload: T) => Promise<void> | void;
+/**
+ * A registered hook with its handler and metadata.
+ */
+export interface HookRegistration {
+    /** Unique identifier for this registration */
+    id: string;
+    /** Hook metadata */
+    metadata: HookMetadata;
+    /** The handler function */
+    handler: HookHandler;
+    /** Unix timestamp when this hook was registered */
+    registeredAt: number;
+}
+/**
+ * Options for registering a hook.
+ */
+export interface HookRegistrationOptions {
+    /** Display name of the hook */
+    name: string;
+    /** Human-readable description */
+    description?: string;
+    /** Source/origin of the hook (defaults to "runtime") */
+    source?: HookSource;
+    /** Plugin ID if registered by a plugin */
+    pluginId?: string;
+    /** Execution priority (defaults to 0, higher runs first) */
+    priority?: HookPriority;
+    /** If true, bypass eligibility checks */
+    always?: boolean;
+    /** Requirements for this hook to be eligible */
+    requires?: HookRequirements;
+}
+/**
+ * Summary of a registered hook for introspection.
+ */
+export interface HookSummary {
+    /** Hook name */
+    name: string;
+    /** Event types this hook listens to */
+    events: EventType[];
+    /** Source/origin of the hook */
+    source: HookSource;
+    /** Whether the hook is enabled */
+    enabled: boolean;
+    /** Plugin ID if from a plugin */
+    pluginId?: string;
+    /** Priority */
+    priority: HookPriority;
+}
+/**
+ * Snapshot of all registered hooks at a point in time.
+ */
+export interface HookSnapshot {
+    /** List of hook summaries */
+    hooks: HookSummary[];
+    /** Snapshot version (increments on each change) */
+    version: number;
+    /** Timestamp when snapshot was taken */
+    timestamp: number;
+}
+/**
+ * Parsed frontmatter from a HOOK.md file.
+ */
+export interface HookFrontmatter {
+    /** Hook name */
+    name?: string;
+    /** Hook description */
+    description?: string;
+    /** Events this hook handles */
+    events?: string[];
+    /** Export name in handler module (default: "default") */
+    export?: string;
+    /** Operating systems supported */
+    os?: string[];
+    /** If true, bypass eligibility checks */
+    always?: boolean;
+    /** Requirements */
+    requires?: {
+        bins?: string[];
+        anyBins?: string[];
+        env?: string[];
+        config?: string[];
+    };
+}
+/**
+ * A hook discovered from a directory.
+ */
+export interface DiscoveredHook {
+    /** Hook name */
+    name: string;
+    /** Hook description */
+    description: string;
+    /** Source type */
+    source: HookSource;
+    /** Plugin ID if from plugin */
+    pluginId?: string;
+    /** Path to HOOK.md */
+    filePath: string;
+    /** Base directory containing the hook */
+    baseDir: string;
+    /** Path to handler module (handler.ts/js) */
+    handlerPath: string;
+    /** Parsed frontmatter */
+    frontmatter: HookFrontmatter;
+}
+/**
+ * Result of loading hooks from a directory.
+ */
+export interface HookLoadResult {
+    /** Hooks that were successfully loaded and registered */
+    loaded: string[];
+    /** Hooks that were skipped (eligibility, disabled, etc.) */
+    skipped: Array<{
+        name: string;
+        reason: string;
+    }>;
+    /** Errors encountered during loading */
+    errors: Array<{
+        name: string;
+        error: string;
+    }>;
+}
+/**
+ * The HookService provides a unified interface for registering, managing,
+ * and executing hooks across the Eliza agent runtime.
+ *
+ * Hooks are event-driven handlers that can respond to various lifecycle
+ * events in the agent system. The service integrates with the runtime's
+ * event system to dispatch hook handlers when events are emitted.
+ *
+ * @example
+ * ```typescript
+ * // Get the hook service
+ * const hookService = runtime.getService<IHookService>(ServiceType.HOOKS);
+ *
+ * // Register a hook programmatically
+ * const hookId = hookService.register(
+ *   [EventType.HOOK_COMMAND_NEW],
+ *   async (payload) => {
+ *     payload.messages.push("Session started!");
+ *   },
+ *   { name: "welcome-hook", description: "Welcomes users on new session" }
+ * );
+ *
+ * // Load hooks from a directory
+ * const result = await hookService.registerFromDirectory(
+ *   "./hooks",
+ *   "workspace"
+ * );
+ *
+ * // Introspect registered hooks
+ * const snapshot = hookService.getSnapshot();
+ * console.log(`${snapshot.hooks.length} hooks registered`);
+ * ```
+ */
+export interface IHookService extends Service {
+    /**
+     * Register a hook handler for one or more event types.
+     *
+     * @param events - Event type(s) to listen for
+     * @param handler - Handler function to call when event fires
+     * @param options - Registration options (name, priority, etc.)
+     * @returns Unique hook registration ID
+     */
+    register(events: EventType | EventType[], handler: HookHandler, options: HookRegistrationOptions): string;
+    /**
+     * Unregister a previously registered hook.
+     *
+     * @param hookId - The hook registration ID returned from register()
+     * @returns true if hook was found and removed, false otherwise
+     */
+    unregister(hookId: string): boolean;
+    /**
+     * Load and register hooks from a directory.
+     *
+     * Scans the directory for subdirectories containing HOOK.md files,
+     * validates eligibility, and registers eligible hooks.
+     *
+     * @param dir - Directory path to scan for hooks
+     * @param source - Source type for these hooks
+     * @param options - Additional options (plugin ID, etc.)
+     * @returns Result of the loading operation
+     */
+    registerFromDirectory(dir: string, source: HookSource, options?: {
+        pluginId?: string;
+    }): Promise<HookLoadResult>;
+    /**
+     * Get a snapshot of all registered hooks.
+     *
+     * @returns Snapshot with hook summaries and metadata
+     */
+    getSnapshot(): HookSnapshot;
+    /**
+     * Get all hooks registered for a specific event type.
+     *
+     * @param event - Event type to query
+     * @returns Array of hook registrations for that event
+     */
+    getHooksByEvent(event: EventType): HookRegistration[];
+    /**
+     * Get a specific hook registration by ID.
+     *
+     * @param hookId - Hook registration ID
+     * @returns The registration or undefined if not found
+     */
+    getHook(hookId: string): HookRegistration | undefined;
+    /**
+     * Get all registered hooks.
+     *
+     * @returns Array of all hook registrations
+     */
+    getAllHooks(): HookRegistration[];
+    /**
+     * Enable or disable a hook.
+     *
+     * @param hookId - Hook registration ID
+     * @param enabled - Whether the hook should be enabled
+     */
+    setEnabled(hookId: string, enabled: boolean): void;
+    /**
+     * Update a hook's priority.
+     *
+     * @param hookId - Hook registration ID
+     * @param priority - New priority value
+     */
+    setPriority(hookId: string, priority: HookPriority): void;
+    /**
+     * Check if a hook is eligible to run based on its requirements.
+     *
+     * @param hookId - Hook registration ID
+     * @returns Eligibility result with reasons if not eligible
+     */
+    checkEligibility(hookId: string): HookEligibilityResult;
+    /**
+     * Check if a hook meets specific requirements.
+     *
+     * @param requirements - Requirements to check
+     * @param config - Optional configuration to check against
+     * @returns Eligibility result
+     */
+    checkRequirements(requirements: HookRequirements, config?: Record<string, unknown>): HookEligibilityResult;
+}
+/**
+ * Legacy hook event type mapping for Otto compatibility.
+ * Maps old event strings to new EventType enum values.
+ */
+export declare const LEGACY_EVENT_MAP: Record<string, EventType>;
+/**
+ * Maps legacy event type strings to the canonical type.
+ * Handles both old format ("command:new") and new format ("HOOK_COMMAND_NEW").
+ *
+ * @param legacyEvent - Legacy event string
+ * @returns The canonical EventType or undefined if not mapped
+ */
+export declare function mapLegacyEvent(legacyEvent: string): EventType | undefined;
+/**
+ * Maps an array of legacy event strings to EventType values.
+ * Filters out any events that cannot be mapped.
+ *
+ * @param legacyEvents - Array of legacy event strings
+ * @returns Array of mapped EventType values
+ */
+export declare function mapLegacyEvents(legacyEvents: string[]): EventType[];
+//# sourceMappingURL=hook.d.ts.map

package/packages/typescript/src/types/hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/types/hook.ts"],"names":[],"mappings":"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"}

package/packages/typescript/src/types/hook.js

@@ -0,0 +1,73 @@
+/**
+ * Hook Service Type Definitions
+ *
+ * Provides the type system for the unified hook service that consolidates
+ * event-driven hooks across the Eliza agent runtime.
+ */
+import { EventType } from "./events";
+/**
+ * Default hook priority (FIFO ordering)
+ */
+export const DEFAULT_HOOK_PRIORITY = 0;
+// ============================================================================
+// Legacy Compatibility Types (for Otto migration)
+// ============================================================================
+/**
+ * Legacy hook event type mapping for Otto compatibility.
+ * Maps old event strings to new EventType enum values.
+ */
+export const LEGACY_EVENT_MAP = {
+    "command:new": EventType.HOOK_COMMAND_NEW,
+    "command:reset": EventType.HOOK_COMMAND_RESET,
+    "command:stop": EventType.HOOK_COMMAND_STOP,
+    "session:start": EventType.HOOK_SESSION_START,
+    "session:end": EventType.HOOK_SESSION_END,
+    "agent:basic-capabilities": EventType.HOOK_AGENT_BASIC_CAPABILITIES,
+    "gateway:startup": EventType.HOOK_GATEWAY_START,
+    "gateway:stop": EventType.HOOK_GATEWAY_STOP,
+    // Plugin lifecycle hooks
+    before_agent_start: EventType.HOOK_AGENT_START,
+    agent_end: EventType.HOOK_AGENT_END,
+    before_compaction: EventType.HOOK_COMPACTION_BEFORE,
+    after_compaction: EventType.HOOK_COMPACTION_AFTER,
+    message_sending: EventType.HOOK_MESSAGE_SENDING,
+    before_tool_call: EventType.HOOK_TOOL_BEFORE,
+    after_tool_call: EventType.HOOK_TOOL_AFTER,
+    tool_result_persist: EventType.HOOK_TOOL_PERSIST,
+    session_start: EventType.HOOK_SESSION_START,
+    session_end: EventType.HOOK_SESSION_END,
+    gateway_start: EventType.HOOK_GATEWAY_START,
+    gateway_stop: EventType.HOOK_GATEWAY_STOP,
+};
+/**
+ * Maps legacy event type strings to the canonical type.
+ * Handles both old format ("command:new") and new format ("HOOK_COMMAND_NEW").
+ *
+ * @param legacyEvent - Legacy event string
+ * @returns The canonical EventType or undefined if not mapped
+ */
+export function mapLegacyEvent(legacyEvent) {
+    // Check if it's already a valid EventType
+    if (Object.values(EventType).includes(legacyEvent)) {
+        return legacyEvent;
+    }
+    // Check legacy mapping
+    return LEGACY_EVENT_MAP[legacyEvent];
+}
+/**
+ * Maps an array of legacy event strings to EventType values.
+ * Filters out any events that cannot be mapped.
+ *
+ * @param legacyEvents - Array of legacy event strings
+ * @returns Array of mapped EventType values
+ */
+export function mapLegacyEvents(legacyEvents) {
+    const mapped = [];
+    for (const event of legacyEvents) {
+        const mappedEvent = mapLegacyEvent(event);
+        if (mappedEvent) {
+            mapped.push(mappedEvent);
+        }
+    }
+    return mapped;
+}

package/packages/typescript/src/types/index.d.ts

@@ -0,0 +1,38 @@
+export { logger } from "../logger";
+export { addHeader, composePromptFromState, parseKeyValueXml } from "../utils";
+export * from "./agent";
+export * from "./channel-config";
+export * from "./components";
+export * from "./database";
+export * from "./environment";
+export * from "./events";
+export * from "./hook";
+export * from "./knowledge";
+export * from "./memory";
+export * from "./memory-storage";
+export * from "./messaging";
+export * from "./model";
+export * from "./onboarding";
+export * from "./pairing";
+export * from "./payment";
+export * from "./plugin";
+export * from "./plugin-store";
+export * from "./primitives";
+export * from "./prompt-batcher";
+export * from "./prompts";
+export * as proto from "./proto.js";
+export { fromJson, type JsonObject, type JsonValue, toJson } from "./proto.js";
+export * from "./runtime";
+export * from "./schema";
+export * from "./schema-builder";
+export * from "./service";
+export * from "./service-interfaces";
+export * from "./settings";
+export * from "./state";
+export * from "./streaming";
+export * from "./task";
+export * from "./tee";
+export * from "./testing";
+export * from "./tools";
+export * from "./trigger";
+//# sourceMappingURL=index.d.ts.map

package/packages/typescript/src/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/types/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAC/E,cAAc,SAAS,CAAC;AAExB,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,SAAS,CAAC;AAExB,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,WAAW,CAAC;AAI1B,OAAO,KAAK,KAAK,MAAM,YAAY,CAAC;AAGpC,OAAO,EAAE,QAAQ,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAC/E,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC"}

package/packages/typescript/src/types/index.js

@@ -0,0 +1,46 @@
+// Core types
+export { logger } from "../logger";
+// Utilities that are part of the public API.
+export { addHeader, composePromptFromState, parseKeyValueXml } from "../utils";
+export * from "./agent";
+// Channel configuration types for plugins
+export * from "./channel-config";
+export * from "./components";
+export * from "./database";
+export * from "./environment";
+export * from "./events";
+export * from "./hook";
+export * from "./knowledge";
+export * from "./memory";
+export * from "./memory-storage";
+export * from "./messaging";
+export * from "./model";
+// Onboarding types
+export * from "./onboarding";
+export * from "./pairing";
+export * from "./payment";
+export * from "./plugin";
+export * from "./plugin-store";
+export * from "./primitives";
+export * from "./prompt-batcher";
+export * from "./prompts";
+// Proto-generated types (single source of truth)
+// These types are generated from /schemas/eliza/v1/*.proto
+// Use these for new code and cross-language interoperability
+export * as proto from "./proto.js";
+// Re-export proto utilities for JSON conversion
+// JsonValue is also exported from primitives.ts, but we explicitly export it here for clarity
+export { fromJson, toJson } from "./proto.js";
+export * from "./runtime";
+export * from "./schema";
+export * from "./schema-builder";
+export * from "./service";
+export * from "./service-interfaces";
+export * from "./settings";
+export * from "./state";
+export * from "./streaming";
+export * from "./task";
+export * from "./tee";
+export * from "./testing";
+export * from "./tools";
+export * from "./trigger";

package/packages/typescript/src/types/knowledge.d.ts

@@ -0,0 +1,49 @@
+import type { Content, UUID } from "./primitives";
+import type { MemoryMetadata, KnowledgeItem as ProtoKnowledgeItem, KnowledgeRecord as ProtoKnowledgeRecord } from "./proto.js";
+/**
+ * Directory-based knowledge source configuration.
+ * Supports both 'path' (proto standard) and 'directory' (legacy) property names.
+ */
+export type KnowledgeDirectory = {
+    /** Path to the knowledge directory (proto standard) */
+    path?: string;
+    /** Path to the knowledge directory (legacy, same as path) */
+    directory?: string;
+    /** Whether this knowledge is shared across characters */
+    shared?: boolean;
+};
+/**
+ * Knowledge source item for Character.knowledge array.
+ * Can be a path to a file or a directory configuration.
+ * Matches the proto KnowledgeItem structure used in character definitions.
+ */
+export type KnowledgeSourceItem = Omit<ProtoKnowledgeItem, "$typeName" | "$unknown" | "item"> & {
+    item: {
+        case: "path";
+        value: string;
+    } | {
+        case: "directory";
+        value: KnowledgeDirectory;
+    } | {
+        case: undefined;
+        value?: undefined;
+    };
+};
+/**
+ * Stored knowledge record with content, metadata, and optional similarity score.
+ * Used for knowledge retrieval results and internal knowledge processing.
+ */
+export interface KnowledgeItem {
+    id: UUID;
+    content: Content;
+    metadata?: MemoryMetadata;
+    worldId?: UUID;
+    similarity?: number;
+}
+/**
+ * Proto-backed knowledge record stored by the agent.
+ * This is different from KnowledgeItem - it represents stored knowledge,
+ * not a knowledge source specification.
+ */
+export type KnowledgeRecord = Partial<Omit<ProtoKnowledgeRecord, "$typeName" | "$unknown">>;
+//# sourceMappingURL=knowledge.d.ts.map

package/packages/typescript/src/types/knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/types/knowledge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EACX,cAAc,EACd,aAAa,IAAI,kBAAkB,EACnC,eAAe,IAAI,oBAAoB,EACvC,MAAM,YAAY,CAAC;AAEpB;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAChC,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACrC,kBAAkB,EAClB,WAAW,GAAG,UAAU,GAAG,MAAM,CACjC,GAAG;IACH,IAAI,EACD;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAC/B;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,KAAK,EAAE,kBAAkB,CAAA;KAAE,GAChD;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,KAAK,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC;CAC1C,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,CACpC,IAAI,CAAC,oBAAoB,EAAE,WAAW,GAAG,UAAU,CAAC,CACpD,CAAC"}

package/packages/typescript/src/types/knowledge.js

@@ -0,0 +1 @@
+export {};

package/packages/typescript/src/types/memory-storage.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Memory Storage Provider interface.
+ *
+ * Abstracts advanced-memory storage so MemoryService in core has zero
+ * database or ORM dependencies. Database plugins (plugin-sql, etc.)
+ * register a service that implements this interface. MemoryService
+ * discovers it at init time via runtime.getService("memoryStorage").
+ *
+ * If no provider is registered, MemoryService gracefully disables
+ * storage-backed features. Non-SQL adapters (in-memory, file-based)
+ * simply don't register one.
+ */
+import type { LongTermMemory, LongTermMemoryCategory, SessionSummary } from "../features/advanced-memory/types.ts";
+import type { UUID } from "./primitives.ts";
+export interface MemoryStorageProvider {
+    storeLongTermMemory(memory: Omit<LongTermMemory, "id" | "createdAt" | "updatedAt" | "accessCount">): Promise<LongTermMemory>;
+    getLongTermMemories(agentId: UUID, entityId: UUID, opts?: {
+        category?: LongTermMemoryCategory;
+        limit?: number;
+    }): Promise<LongTermMemory[]>;
+    updateLongTermMemory(id: UUID, agentId: UUID, entityId: UUID, updates: Partial<Omit<LongTermMemory, "id" | "agentId" | "entityId" | "createdAt">>): Promise<void>;
+    deleteLongTermMemory(id: UUID, agentId: UUID, entityId: UUID): Promise<void>;
+    storeSessionSummary(summary: Omit<SessionSummary, "id" | "createdAt" | "updatedAt">): Promise<SessionSummary>;
+    getCurrentSessionSummary(agentId: UUID, roomId: UUID): Promise<SessionSummary | null>;
+    updateSessionSummary(id: UUID, agentId: UUID, roomId: UUID, updates: Partial<Omit<SessionSummary, "id" | "agentId" | "roomId" | "createdAt" | "updatedAt">>): Promise<void>;
+    getSessionSummaries(agentId: UUID, roomId: UUID, limit?: number): Promise<SessionSummary[]>;
+}
+//# sourceMappingURL=memory-storage.d.ts.map

package/packages/typescript/src/types/memory-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-storage.d.ts","sourceRoot":"","sources":["../../../../../../typescript/src/types/memory-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACX,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C,MAAM,WAAW,qBAAqB;IAGrC,mBAAmB,CAClB,MAAM,EAAE,IAAI,CACX,cAAc,EACd,IAAI,GAAG,WAAW,GAAG,WAAW,GAAG,aAAa,CAChD,GACC,OAAO,CAAC,cAAc,CAAC,CAAC;IAE3B,mBAAmB,CAClB,OAAO,EAAE,IAAI,EACb,QAAQ,EAAE,IAAI,EACd,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,sBAAsB,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1D,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAE7B,oBAAoB,CACnB,EAAE,EAAE,IAAI,EACR,OAAO,EAAE,IAAI,EACb,QAAQ,EAAE,IAAI,EACd,OAAO,EAAE,OAAO,CACf,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC,CACjE,GACC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,oBAAoB,CAAC,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAI7E,mBAAmB,CAClB,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC,GAC7D,OAAO,CAAC,cAAc,CAAC,CAAC;IAE3B,wBAAwB,CACvB,OAAO,EAAE,IAAI,EACb,MAAM,EAAE,IAAI,GACV,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAElC,oBAAoB,CACnB,EAAE,EAAE,IAAI,EACR,OAAO,EAAE,IAAI,EACb,MAAM,EAAE,IAAI,EACZ,OAAO,EAAE,OAAO,CACf,IAAI,CACH,cAAc,EACd,IAAI,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,CACvD,CACD,GACC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,mBAAmB,CAClB,OAAO,EAAE,IAAI,EACb,MAAM,EAAE,IAAI,EACZ,KAAK,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;CAC7B"}

package/packages/typescript/src/types/memory-storage.js

@@ -0,0 +1,13 @@
+/**
+ * Memory Storage Provider interface.
+ *
+ * Abstracts advanced-memory storage so MemoryService in core has zero
+ * database or ORM dependencies. Database plugins (plugin-sql, etc.)
+ * register a service that implements this interface. MemoryService
+ * discovers it at init time via runtime.getService("memoryStorage").
+ *
+ * If no provider is registered, MemoryService gracefully disables
+ * storage-backed features. Non-SQL adapters (in-memory, file-based)
+ * simply don't register one.
+ */
+export {};