@aigne/core 1.71.0 → 1.72.0-beta.10

package/lib/dts/loader/index.d.ts

@@ -5,9 +5,8 @@ import type { ChatModel } from "../agents/chat-model.js";
 import type { ImageModel } from "../agents/image-model.js";
 import type { AIGNEOptions } from "../aigne/aigne.js";
 import type { MemoryAgent, MemoryAgentOptions } from "../memory/memory.js";
-import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { type PromiseOrValue } from "../utils/type-utils.js";
-import { type Instructions, loadAgentFromYamlFile, type NestAgentSchema } from "./agent-yaml.js";
+import { loadAgentFromYamlFile, type NestAgentSchema } from "./agent-yaml.js";
 export interface LoadOptions {
     memories?: {
         new (parameters?: MemoryAgentOptions): MemoryAgent;
@@ -19,7 +18,10 @@ export interface LoadOptions {
         availableModules?: {
             module: string;
             alias?: string[];
-            create: (options?: Record<string, any>) => PromiseOrValue<AFSModule>;
+            load: (options: {
+                filepath: string;
+                parsed?: object;
+            }) => PromiseOrValue<AFSModule>;
         }[];
     };
     aigne?: z.infer<typeof aigneFileSchema>;
@@ -27,6 +29,9 @@ export interface LoadOptions {
         parent?: string;
     }) => Promise<any>;
 }
+export interface AgentLoadOptions extends LoadOptions {
+    loadNestAgent: (path: string, agent: NestAgentSchema, options: LoadOptions, agentOptions?: AgentOptions<any, any> & Record<string, unknown>) => Promise<Agent>;
+}
 export declare function load(path: string, options?: LoadOptions): Promise<AIGNEOptions>;
 export declare function loadAgent(path: string, options: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;
 export declare function loadNestAgent(path: string, agent: NestAgentSchema, options: LoadOptions, agentOptions?: AgentOptions<any, any> & Record<string, unknown>): Promise<Agent>;
@@ -67,9 +72,9 @@ declare const aigneFileSchema: z.ZodObject<{
         } | undefined, z.ZodTypeDef, number | {
             $get: string;
         } | undefined>;
-        thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+        thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
-        } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+        } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
         } | undefined>;
     }, z.ZodTypeAny, "passthrough"> | undefined, z.ZodTypeDef, z.objectInputType<{
@@ -98,9 +103,9 @@ declare const aigneFileSchema: z.ZodObject<{
         } | undefined, z.ZodTypeDef, number | {
             $get: string;
         } | undefined>;
-        thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+        thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
-        } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+        } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
         } | undefined>;
     }, z.ZodTypeAny, "passthrough"> | undefined>;
@@ -158,9 +163,9 @@ declare const aigneFileSchema: z.ZodObject<{
         } | undefined, z.ZodTypeDef, number | {
             $get: string;
         } | undefined>;
-        thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+        thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
-        } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+        } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
         } | undefined>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
@@ -209,9 +214,9 @@ declare const aigneFileSchema: z.ZodObject<{
         } | undefined, z.ZodTypeDef, number | {
             $get: string;
         } | undefined>;
-        thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+        thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
-        } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+        } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
             $get: string;
         } | undefined>;
     }, z.ZodTypeAny, "passthrough"> | undefined;
@@ -239,5 +244,4 @@ export declare function loadAIGNEFile(path: string): Promise<{
     rootDir: string;
 }>;
 export declare function findAIGNEFile(path: string): Promise<string>;
-export declare function instructionsToPromptBuilder(instructions: Instructions): PromptBuilder;
 export {};

package/lib/dts/loader/schema.d.ts

@@ -1,4 +1,6 @@
 import { type ZodType, z } from "zod";
+import { type Role } from "../agents/chat-model.js";
+import { PromptBuilder } from "../prompt/prompt-builder.js";
 export declare const inputOutputSchema: ({ path }: {
     path: string;
 }) => z.ZodUnion<[ZodType<any, z.ZodTypeDef, any>, z.ZodEffects<z.ZodObject<{
@@ -55,9 +57,9 @@ declare const chatModelObjectSchema: z.ZodObject<{
     } | undefined, z.ZodTypeDef, number | {
         $get: string;
     } | undefined>;
-    thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+    thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
-    } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+    } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
     } | undefined>;
 }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
@@ -86,9 +88,9 @@ declare const chatModelObjectSchema: z.ZodObject<{
     } | undefined, z.ZodTypeDef, number | {
         $get: string;
     } | undefined>;
-    thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+    thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
-    } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+    } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
     } | undefined>;
 }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
@@ -117,9 +119,9 @@ declare const chatModelObjectSchema: z.ZodObject<{
     } | undefined, z.ZodTypeDef, number | {
         $get: string;
     } | undefined>;
-    thinkingEffort: ZodType<number | "high" | "medium" | "low" | "minimal" | {
+    thinkingEffort: ZodType<number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
-    } | undefined, z.ZodTypeDef, number | "high" | "medium" | "low" | "minimal" | {
+    } | undefined, z.ZodTypeDef, number | "high" | "low" | "medium" | "minimal" | {
         $get: string;
     } | undefined>;
 }, z.ZodTypeAny, "passthrough">>;
@@ -149,4 +151,17 @@ export declare function camelizeSchema<T extends ZodType>(schema: T, { shallow }
     shallow?: boolean;
 }): T;
 export declare function preprocessSchema<T extends ZodType>(fn: (data: unknown) => unknown, schema: T): T;
+export type Instructions = {
+    role: Exclude<Role, "tool">;
+    content: string;
+    path: string;
+    cacheControl?: {
+        type: "ephemeral";
+        ttl?: "5m" | "1h";
+    };
+}[];
+export declare const getInstructionsSchema: ({ filepath }: {
+    filepath: string;
+}) => ZodType<Instructions>;
+export declare function instructionsToPromptBuilder(instructions: Instructions | string): PromptBuilder;
 export {};

package/lib/dts/memory/recorder.d.ts

@@ -42,24 +42,24 @@ export declare const memoryRecorderOutputSchema: z.ZodObject<{
         content: ZodType<{}, z.ZodTypeDef, {}>;
         createdAt: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }, {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     memories: {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }[];
 }, {
     memories: {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }[];
 }>;

package/lib/dts/memory/retriever.d.ts

@@ -55,24 +55,24 @@ export declare const memoryRetrieverOutputSchema: z.ZodObject<{
         content: z.ZodType<{}, z.ZodTypeDef, {}>;
         createdAt: z.ZodString;
     }, "strip", z.ZodTypeAny, {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }, {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     memories: {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }[];
 }, {
     memories: {
-        content: {};
         id: string;
+        content: {};
         createdAt: string;
     }[];
 }>;

package/lib/dts/prompt/agent-session.d.ts

@@ -0,0 +1,135 @@
+import type { AFS } from "@aigne/afs";
+import type { AgentInvokeOptions } from "../agents/agent.js";
+import type { ChatModelInputMessage } from "../agents/chat-model.js";
+import { type CompactConfig, type SessionMemoryConfig, type SessionMode, type UserMemoryConfig } from "./compact/types.js";
+export * from "./compact/types.js";
+export interface AgentSessionOptions {
+    sessionId: string;
+    userId?: string;
+    agentId?: string;
+    afs?: AFS;
+    /**
+     * Session mode
+     * - "auto": Enable history recording, compaction, and memory extraction
+     * - "disabled": Disable all session features (history, compaction, memory)
+     *
+     * **Should be "disabled" for internal utility agents** (extractors, compactors, etc.)
+     * to avoid recursive memory extraction and unnecessary overhead.
+     *
+     * @default DEFAULT_SESSION_MODE ("auto")
+     */
+    mode?: SessionMode;
+    /**
+     * Compaction configuration
+     */
+    compact?: CompactConfig;
+    /**
+     * Session memory configuration
+     */
+    sessionMemory?: SessionMemoryConfig;
+    /**
+     * User memory configuration
+     */
+    userMemory?: UserMemoryConfig;
+}
+export declare class AgentSession {
+    readonly sessionId: string;
+    readonly userId?: string;
+    readonly agentId?: string;
+    private afs?;
+    private historyModulePath?;
+    private mode;
+    private compactConfig;
+    private sessionMemoryConfig;
+    private userMemoryConfig;
+    private runtimeState;
+    private initialized?;
+    private compactionPromise?;
+    private sessionMemoryUpdatePromise?;
+    private userMemoryUpdatePromise?;
+    constructor(options: AgentSessionOptions);
+    /**
+     * Check if memory extraction is enabled
+     * Memory extraction requires mode to be "auto" AND AFS history module to be available
+     */
+    private get isMemoryEnabled();
+    setSystemMessages(...messages: ChatModelInputMessage[]): Promise<void>;
+    getMessages(): Promise<ChatModelInputMessage[]>;
+    /**
+     * Format user memory facts into a system message
+     * Applies token budget limit to ensure memory injection fits within constraints
+     */
+    private formatUserMemory;
+    /**
+     * Format session memory facts into a system message
+     * Applies token budget limit to ensure memory injection fits within constraints
+     */
+    private formatSessionMemory;
+    private formatMemoryTemplate;
+    startMessage(input: unknown, message: ChatModelInputMessage, options: AgentInvokeOptions): Promise<void>;
+    endMessage(output: unknown, message: ChatModelInputMessage | undefined, options: AgentInvokeOptions): Promise<void>;
+    /**
+     * Manually trigger compaction
+     */
+    compact(options: AgentInvokeOptions): Promise<void>;
+    /**
+     * Internal method that performs the actual compaction
+     */
+    private doCompact;
+    private compactCurrentEntry;
+    private maybeCompactCurrentEntry;
+    private maybeAutoCompact;
+    /**
+     * Estimate token count for an array of messages
+     */
+    private estimateMessagesTokens;
+    /**
+     * Split entries into batches based on token limit
+     * Each batch will not exceed the specified maxTokens
+     */
+    private splitIntoBatches;
+    appendCurrentMessages(messages: ChatModelInputMessage | ChatModelInputMessage[], options: AgentInvokeOptions): Promise<void>;
+    private truncateLargeMessage;
+    private ensureInitialized;
+    private initialize;
+    /**
+     * Load session memory facts
+     * @returns Array of memory fact entries for the current session
+     */
+    private loadSessionMemory;
+    /**
+     * Load user memory facts
+     * @returns Array of memory fact entries for the current user
+     */
+    private loadUserMemory;
+    /**
+     * Load session history including compact summary and history entries
+     * @returns Object containing compact summary and history entries
+     */
+    private loadSessionHistory;
+    /**
+     * Manually trigger session memory update
+     */
+    updateSessionMemory(options: AgentInvokeOptions): Promise<void>;
+    private maybeAutoUpdateSessionMemory;
+    private maybeAutoUpdateUserMemory;
+    /**
+     * Internal method that performs the actual session memory update
+     */
+    private doUpdateSessionMemory;
+    /**
+     * Manually trigger user memory update
+     */
+    updateUserMemory(options: AgentInvokeOptions): Promise<void>;
+    /**
+     * Internal method that performs the actual user memory extraction
+     */
+    private doUpdateUserMemory;
+    private initializeDefaultCompactor;
+    private initializeDefaultSessionMemoryExtractor;
+    private initializeDefaultUserMemoryExtractor;
+    private get maxTokens();
+    private get keepRecentRatio();
+    private get keepTokenBudget();
+    private get singleMessageLimit();
+}

package/lib/dts/prompt/compact/compactor.d.ts

@@ -0,0 +1,7 @@
+import { AIAgent, type AIAgentOptions } from "../../agents/ai-agent.js";
+import type { CompactContent, CompactorInput } from "./types.js";
+export interface CreateCompactorOptions extends AIAgentOptions<CompactorInput, CompactContent> {
+}
+export declare class AISessionCompactor extends AIAgent<CompactorInput, CompactContent> {
+    constructor(options?: CreateCompactorOptions);
+}

package/lib/dts/prompt/compact/session-memory-extractor.d.ts

@@ -0,0 +1,7 @@
+import { AIAgent, type AIAgentOptions } from "../../agents/ai-agent.js";
+import type { MemoryExtractorInput, MemoryExtractorOutput } from "./types.js";
+export interface CreateSessionMemoryExtractorOptions extends AIAgentOptions<MemoryExtractorInput, MemoryExtractorOutput> {
+}
+export declare class AISessionMemoryExtractor extends AIAgent<MemoryExtractorInput, MemoryExtractorOutput> {
+    constructor(options?: CreateSessionMemoryExtractorOptions);
+}

package/lib/dts/prompt/compact/types.d.ts

@@ -0,0 +1,329 @@
+import type { Agent, Message } from "../../agents/agent.js";
+import type { ChatModelInputMessage } from "../../agents/chat-model.js";
+/**
+ * Session mode type
+ */
+export type SessionMode = "auto" | "disabled";
+/**
+ * Default session mode
+ */
+export declare const DEFAULT_SESSION_MODE: SessionMode;
+/**
+ * Default compaction mode
+ */
+export declare const DEFAULT_COMPACT_MODE: "auto";
+/**
+ * Default maximum tokens before triggering compaction
+ */
+export declare const DEFAULT_MAX_TOKENS = 80000;
+/**
+ * Default ratio of maxTokens to reserve for keeping recent messages
+ */
+export declare const DEFAULT_KEEP_RECENT_RATIO = 0.5;
+/**
+ * Default async mode for compaction
+ */
+export declare const DEFAULT_COMPACT_ASYNC = true;
+/**
+ * Content structure for history entries
+ */
+export interface EntryContent {
+    input?: unknown;
+    output?: unknown;
+    messages?: ChatModelInputMessage[];
+}
+/**
+ * Output structure from the compactor agent
+ */
+export interface CompactContent extends Message {
+    summary: string;
+}
+/**
+ * Input structure for the compactor agent
+ */
+export interface CompactorInput extends Message {
+    previousSummary?: string[];
+    messages: ChatModelInputMessage[];
+}
+/**
+ * Type alias for a compactor agent
+ */
+export type Compactor = Agent<CompactorInput, CompactContent>;
+/**
+ * Configuration for session compaction
+ */
+export interface CompactConfig {
+    /**
+     * Compaction mode
+     * @default DEFAULT_COMPACT_MODE ("auto")
+     */
+    mode?: "auto" | "disabled";
+    /**
+     * Maximum tokens before triggering compaction
+     * @default DEFAULT_MAX_TOKENS (80000)
+     */
+    maxTokens?: number;
+    /**
+     * Ratio of maxTokens to reserve for keeping recent messages (0-1)
+     *
+     * Defines what portion of maxTokens budget should be allocated for
+     * preserving recent conversation history without compaction.
+     *
+     * @default 0.5 (50% of maxTokens)
+     * @example 0.5 means if maxTokens=80000, keep up to 40000 tokens of recent messages
+     */
+    keepRecentRatio?: number;
+    /**
+     * Whether to perform compaction asynchronously
+     * @default DEFAULT_COMPACT_ASYNC (true)
+     */
+    async?: boolean;
+    /**
+     * Agent that generates summaries from conversation entries
+     * Input: { entries: EntryContent[] }
+     * Output: { summary: string }
+     */
+    compactor?: Compactor;
+}
+/**
+ * Default ratio of maxTokens to allocate for user memory
+ */
+export declare const DEFAULT_MEMORY_RATIO = 0.04;
+/**
+ * Default query limit for loading memory facts
+ */
+export declare const DEFAULT_MEMORY_QUERY_LIMIT = 200;
+/**
+ * Content structure for a single memory fact
+ *
+ * Used by both session memory and user memory to store learned facts.
+ * Each fact is stored as an individual AFSEntry with metadata at the AFSEntry level.
+ *
+ * Storage paths:
+ * - Session Memory:
+ *   - List: /by-session/:sessionId/@metadata/memory
+ *   - Create: /by-session/:sessionId/@metadata/memory/new
+ *   - Read: /by-session/:sessionId/@metadata/memory/:memoryId
+ * - User Memory:
+ *   - List: /by-user/:userId/@metadata/memory
+ *   - Create: /by-user/:userId/@metadata/memory/new
+ *   - Read: /by-user/:userId/@metadata/memory/:memoryId
+ *
+ * @example
+ * AFSEntry<MemoryFact> {
+ *   id: "fact-001",           // AFSEntry ID (auto-generated)
+ *   userId: "user-001",
+ *   agentId: "assistant",      // which agent learned this fact
+ *   sessionId: "session-123",  // which session it was learned from (if applicable)
+ *   createdAt: Date,
+ *   content: {
+ *     label: "pref-package-manager",  // semantic label for this fact
+ *     fact: "User prefers using pnpm",
+ *     confidence: 0.9,
+ *     tags: ["preference", "tooling"]
+ *   }
+ * }
+ */
+export interface MemoryFact {
+    /**
+     * Semantic label for this fact (short, human-readable)
+     * Used for updates and deletions to uniquely identify facts
+     * @example "pref-package-manager", "skill-typescript", "proj-main-language"
+     */
+    label: string;
+    /**
+     * The fact content (text description)
+     */
+    fact: string;
+    /**
+     * Confidence score (0-1)
+     * Higher values indicate more certain facts
+     * @default 1.0
+     */
+    confidence?: number;
+    /**
+     * Classification tags for the fact
+     * @example ['preference', 'technical', 'project-specific']
+     */
+    tags?: string[];
+}
+/**
+ * Input structure for the memory extractor agent
+ */
+export interface MemoryExtractorInput extends Message {
+    /**
+     * User memory facts (long-term, cross-session) to avoid duplication
+     */
+    existingUserFacts?: MemoryFact[];
+    /**
+     * Existing session memory facts (for context and deduplication)
+     */
+    existingFacts?: MemoryFact[];
+    /**
+     * Recent conversation messages to extract facts from
+     */
+    messages: ChatModelInputMessage[];
+}
+/**
+ * Output structure from the memory extractor agent
+ */
+export interface MemoryExtractorOutput extends Message {
+    /**
+     * New or updated facts from the conversation
+     * Only include facts that need to be added or updated
+     * Do not include unchanged facts that already exist
+     */
+    newFacts: MemoryFact[];
+    /**
+     * Fact labels to remove from existing memory
+     * Each string should match a label in existingFacts
+     * @example ["pref-package-manager", "skill-old-framework"]
+     */
+    removeFacts?: string[];
+}
+/**
+ * Type alias for a memory extractor agent
+ */
+export type MemoryExtractor = Agent<MemoryExtractorInput, MemoryExtractorOutput>;
+/**
+ * Default session memory mode
+ */
+export declare const DEFAULT_SESSION_MEMORY_MODE: "auto";
+/**
+ * Default async mode for session memory extraction
+ */
+export declare const DEFAULT_SESSION_MEMORY_ASYNC = true;
+/**
+ * Metadata for tracking session memory extraction progress
+ *
+ * This metadata is stored in each memory entry's metadata field.
+ * When extracting new facts, the latestEntryId is recorded in the metadata
+ * to track which history entries have been processed.
+ */
+export interface SessionMemoryMetadata {
+    /**
+     * ID of the last extracted history entry
+     * Used to determine which entries still need processing
+     */
+    latestEntryId?: string;
+}
+/**
+ * Default user memory mode
+ */
+export declare const DEFAULT_USER_MEMORY_MODE: "auto";
+/**
+ * Default async mode for user memory consolidation
+ */
+export declare const DEFAULT_USER_MEMORY_ASYNC = true;
+/**
+ * Input structure for the user memory extractor agent
+ */
+export interface UserMemoryExtractorInput extends Message {
+    /**
+     * Session memory facts from multiple sessions to consolidate
+     */
+    sessionFacts: MemoryFact[];
+    /**
+     * Existing user memory facts (for context and deduplication)
+     */
+    existingUserFacts?: MemoryFact[];
+}
+/**
+ * Output structure from the user memory extractor agent
+ */
+export interface UserMemoryExtractorOutput extends Message {
+    /**
+     * New or updated facts for user memory
+     * Only include facts that need to be added or updated
+     * Do not include unchanged facts that already exist
+     * Each label should be unique - these will replace old facts with same labels
+     */
+    newFacts: MemoryFact[];
+    /**
+     * Fact labels to remove from user memory
+     * Each string should match a label in existingUserFacts
+     */
+    removeFacts?: string[];
+}
+/**
+ * Type alias for a user memory extractor agent
+ */
+export type UserMemoryExtractor = Agent<UserMemoryExtractorInput, UserMemoryExtractorOutput>;
+/**
+ * Configuration for user memory
+ * User memory contains long-term facts consolidated from multiple sessions
+ */
+export interface UserMemoryConfig {
+    /**
+     * User memory mode
+     * - "auto": Enable memory and auto-consolidate at appropriate times
+     * - "disabled": Disable user memory completely
+     * @default DEFAULT_USER_MEMORY_MODE ("auto")
+     */
+    mode?: "auto" | "disabled";
+    /**
+     * Ratio of maxTokens to allocate for user memory (0-1)
+     *
+     * Defines what portion of maxTokens budget should be allocated for
+     * injecting user memory facts into the prompt.
+     *
+     * @default DEFAULT_MEMORY_RATIO (0.04 = 4% of maxTokens)
+     * @example 0.04 means if maxTokens=80000, allocate 3200 tokens for memory
+     */
+    memoryRatio?: number;
+    /**
+     * Maximum number of fact entries to load from storage
+     * @default DEFAULT_MEMORY_QUERY_LIMIT (200)
+     */
+    queryLimit?: number;
+    /**
+     * Whether to perform memory consolidation asynchronously
+     * @default DEFAULT_USER_MEMORY_ASYNC (true)
+     */
+    async?: boolean;
+    /**
+     * Agent that extracts user memory facts from session memory
+     * Input: { sessionFacts: MemoryFact[], existingUserFacts?: MemoryFact[] }
+     * Output: { newFacts: MemoryFact[], removeFacts?: string[] }
+     */
+    extractor?: UserMemoryExtractor;
+}
+/**
+ * Configuration for session memory
+ * Session memory contains facts extracted from the current session's conversation
+ */
+export interface SessionMemoryConfig {
+    /**
+     * Session memory mode
+     * - "auto": Enable memory and auto-update after each conversation turn
+     * - "disabled": Disable memory completely
+     * @default DEFAULT_SESSION_MEMORY_MODE ("auto")
+     */
+    mode?: "auto" | "disabled";
+    /**
+     * Ratio of maxTokens to allocate for session memory (0-1)
+     *
+     * Defines what portion of maxTokens budget should be allocated for
+     * injecting session memory facts into the prompt.
+     *
+     * @default DEFAULT_MEMORY_RATIO (0.04 = 4% of maxTokens)
+     * @example 0.04 means if maxTokens=80000, allocate 3200 tokens for memory
+     */
+    memoryRatio?: number;
+    /**
+     * Maximum number of fact entries to load from storage
+     * @default DEFAULT_MEMORY_QUERY_LIMIT (200)
+     */
+    queryLimit?: number;
+    /**
+     * Whether to perform memory extraction asynchronously
+     * @default DEFAULT_SESSION_MEMORY_ASYNC (true)
+     */
+    async?: boolean;
+    /**
+     * Agent that extracts facts from conversation messages
+     * Input: { existingUserFacts?: MemoryFact[], existingFacts?: MemoryFact[], messages: ChatModelInputMessage[] }
+     * Output: { newFacts: MemoryFact[], removeFacts?: string[] }
+     */
+    extractor?: MemoryExtractor;
+}