@aigne/core 1.17.0 → 1.18.0

package/lib/cjs/loader/index.js

@@ -4,24 +4,22 @@ exports.load = load;
 exports.loadAgent = loadAgent;
 exports.loadModel = loadModel;
 exports.loadAIGNEFile = loadAIGNEFile;
-const promises_1 = require("node:fs/promises");
-const node_path_1 = require("node:path");
 const yaml_1 = require("yaml");
 const zod_1 = require("zod");
 const agent_js_1 = require("../agents/agent.js");
 const ai_agent_js_1 = require("../agents/ai-agent.js");
 const mcp_agent_js_1 = require("../agents/mcp-agent.js");
+const nodejs_js_1 = require("../utils/nodejs.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const agent_js_js_1 = require("./agent-js.js");
 const agent_yaml_js_1 = require("./agent-yaml.js");
 const AIGNE_FILE_NAME = ["aigne.yaml", "aigne.yml"];
 async function load(options) {
-    const { path } = options;
-    const aigneFilePath = await getAIGNEFilePath(path);
-    const rootDir = (0, node_path_1.dirname)(aigneFilePath);
+    const aigneFilePath = await getAIGNEFilePath(options.path);
+    const rootDir = nodejs_js_1.nodejs.path.dirname(aigneFilePath);
     const aigne = await loadAIGNEFile(aigneFilePath);
-    const agents = await Promise.all((aigne.agents ?? []).map((filename) => loadAgent((0, node_path_1.join)(rootDir, filename))));
-    const skills = await Promise.all((aigne.skills ?? []).map((filename) => loadAgent((0, node_path_1.join)(rootDir, filename))));
+    const agents = await Promise.all((aigne.agents ?? []).map((filename) => loadAgent(nodejs_js_1.nodejs.path.join(rootDir, filename))));
+    const skills = await Promise.all((aigne.skills ?? []).map((filename) => loadAgent(nodejs_js_1.nodejs.path.join(rootDir, filename))));
     return {
         ...aigne,
         model: await loadModel(options.models, aigne.chat_model),
@@ -29,18 +27,21 @@ async function load(options) {
         skills,
     };
 }
-async function loadAgent(path) {
-    if ((0, node_path_1.extname)(path) === ".js") {
+async function loadAgent(path, options) {
+    if (nodejs_js_1.nodejs.path.extname(path) === ".js") {
         const agent = await (0, agent_js_js_1.loadAgentFromJsFile)(path);
         return agent_js_1.FunctionAgent.from(agent);
     }
-    if ((0, node_path_1.extname)(path) === ".yaml" || (0, node_path_1.extname)(path) === ".yml") {
+    if (nodejs_js_1.nodejs.path.extname(path) === ".yaml" || nodejs_js_1.nodejs.path.extname(path) === ".yml") {
         const agent = await (0, agent_yaml_js_1.loadAgentFromYamlFile)(path);
         if (agent.type === "ai") {
             return ai_agent_js_1.AIAgent.from({
                 ...agent,
+                memory: !options?.memories?.length || !agent.memory
+                    ? undefined
+                    : await loadMemory(options.memories, typeof agent.memory === "object" ? agent.memory.provider : undefined, typeof agent.memory === "object" ? agent.memory : {}),
                 skills: agent.skills &&
-                    (await Promise.all(agent.skills.map((filename) => loadAgent((0, node_path_1.join)((0, node_path_1.dirname)(path), filename))))),
+                    (await Promise.all(agent.skills.map((filename) => loadAgent(nodejs_js_1.nodejs.path.join(nodejs_js_1.nodejs.path.dirname(path), filename))))),
             });
         }
         if (agent.type === "mcp") {
@@ -60,7 +61,15 @@ async function loadAgent(path) {
     }
     throw new Error(`Unsupported agent file type: ${path}`);
 }
-const { MODEL_PROVIDER, MODEL_NAME } = process.env;
+async function loadMemory(memories, provider, options) {
+    const M = !provider
+        ? memories[0]
+        : memories.find((i) => i.name.toLowerCase().includes(provider.toLowerCase()));
+    if (!M)
+        throw new Error(`Unsupported memory: ${provider}`);
+    return new M(options);
+}
+const { MODEL_PROVIDER, MODEL_NAME } = nodejs_js_1.nodejs.env;
 const DEFAULT_MODEL_PROVIDER = "openai";
 async function loadModel(models, model, modelOptions) {
     const params = {
@@ -98,17 +107,17 @@ const aigneFileSchema = zod_1.z.object({
     skills: zod_1.z.array(zod_1.z.string()).nullish(),
 });
 async function loadAIGNEFile(path) {
-    const raw = await (0, type_utils_js_1.tryOrThrow)(() => (0, promises_1.readFile)(path, "utf8"), (error) => new Error(`Failed to load aigne.yaml from ${path}: ${error.message}`));
+    const raw = await (0, type_utils_js_1.tryOrThrow)(() => nodejs_js_1.nodejs.fs.readFile(path, "utf8"), (error) => new Error(`Failed to load aigne.yaml from ${path}: ${error.message}`));
     const json = await (0, type_utils_js_1.tryOrThrow)(() => (0, yaml_1.parse)(raw), (error) => new Error(`Failed to parse aigne.yaml from ${path}: ${error.message}`));
     const agent = (0, type_utils_js_1.tryOrThrow)(() => aigneFileSchema.parse({ ...json, skills: json.skills ?? json.tools }), (error) => new Error(`Failed to validate aigne.yaml from ${path}: ${error.message}`));
     return agent;
 }
 async function getAIGNEFilePath(path) {
-    const s = await (0, promises_1.stat)(path);
+    const s = await nodejs_js_1.nodejs.fs.stat(path);
     if (s.isDirectory()) {
         for (const file of AIGNE_FILE_NAME) {
-            const filePath = (0, node_path_1.join)(path, file);
-            if ((await (0, promises_1.stat)(filePath)).isFile())
+            const filePath = nodejs_js_1.nodejs.path.join(path, file);
+            if ((await nodejs_js_1.nodejs.fs.stat(filePath)).isFile())
                 return filePath;
         }
     }

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

@@ -39,11 +39,11 @@ export declare const memoryRetrieverInputSchema: z.ZodObject<{
     limit: z.ZodOptional<z.ZodNumber>;
     search: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    search?: string | undefined;
     limit?: number | undefined;
-}, {
     search?: string | undefined;
+}, {
     limit?: number | undefined;
+    search?: string | undefined;
 }>;
 /**
  * @hidden

package/lib/cjs/prompt/prompt-builder.d.ts

@@ -1,9 +1,7 @@
 import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
-import { Agent, type Message } from "../agents/agent.js";
+import { Agent, type AgentInvokeOptions, type Message } from "../agents/agent.js";
 import type { AIAgent } from "../agents/ai-agent.js";
 import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
-import type { Context } from "../aigne/context.js";
-import type { MemoryAgent } from "../memory/memory.js";
 import { ChatMessagesTemplate } from "./template.js";
 export declare const MESSAGE_KEY = "$message";
 export declare function createMessage<V extends Message>(message: string, variables?: V): {
@@ -17,9 +15,7 @@ export declare function getMessage(input: Message): string | undefined;
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
 }
-export interface PromptBuildOptions {
-    memory?: MemoryAgent | MemoryAgent[];
-    context: Context;
+export interface PromptBuildOptions extends AgentInvokeOptions {
     agent?: AIAgent;
     input?: Message;
     model?: ChatModel;

package/lib/cjs/prompt/prompt-builder.js

@@ -3,11 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PromptBuilder = exports.MESSAGE_KEY = void 0;
 exports.createMessage = createMessage;
 exports.getMessage = getMessage;
-const promises_1 = require("node:fs/promises");
 const yaml_1 = require("yaml");
 const zod_1 = require("zod");
 const agent_js_1 = require("../agents/agent.js");
 const json_schema_js_1 = require("../utils/json-schema.js");
+const nodejs_js_1 = require("../utils/nodejs.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const memory_message_template_js_1 = require("./prompts/memory-message-template.js");
 const template_js_1 = require("./template.js");
@@ -36,7 +36,7 @@ class PromptBuilder {
         throw new Error(`Invalid instructions ${instructions}`);
     }
     static async fromFile(path) {
-        const text = await (0, promises_1.readFile)(path, "utf-8");
+        const text = await nodejs_js_1.nodejs.fs.readFile(path, "utf-8");
         return PromptBuilder.from(text);
     }
     static fromMCPPromptResult(result) {
@@ -83,11 +83,15 @@ class PromptBuilder {
         const messages = (typeof this.instructions === "string"
             ? template_js_1.ChatMessagesTemplate.from([template_js_1.SystemMessageTemplate.from(this.instructions)])
             : this.instructions)?.format(options.input) ?? [];
-        for (const memory of (0, type_utils_js_1.orArrayToArray)(options.memory ?? options.agent?.memories)) {
-            const memories = (await memory.retrieve({ search: input && getMessage(input) }, options.context))?.memories;
-            if (memories?.length)
-                messages.push(...this.convertMemoriesToMessages(memories, options));
+        const memories = [];
+        if (options.agent) {
+            memories.push(...(await options.agent.retrieveMemories({ search: options.input }, options)));
         }
+        if (options.memories?.length) {
+            memories.push(...options.memories);
+        }
+        if (memories.length)
+            messages.push(...this.convertMemoriesToMessages(memories, options));
         const content = input && getMessage(input);
         // add user input if it's not the same as the last message
         if (content && messages.at(-1)?.content !== content) {

package/lib/cjs/prompt/template.js

@@ -5,10 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatMessagesTemplate = exports.ToolMessageTemplate = exports.AgentMessageTemplate = exports.UserMessageTemplate = exports.SystemMessageTemplate = exports.ChatMessageTemplate = exports.PromptTemplate = void 0;
 exports.parseChatMessages = parseChatMessages;
-const node_util_1 = require("node:util");
 const mustache_1 = __importDefault(require("mustache"));
 const zod_1 = require("zod");
-const type_utils_js_1 = require("../utils/type-utils.js");
 class PromptTemplate {
     template;
     static from(template) {
@@ -92,7 +90,7 @@ class ToolMessageTemplate extends ChatMessageTemplate {
     constructor(content, toolCallId, name) {
         super("tool", typeof content === "string"
             ? content
-            : (0, type_utils_js_1.tryOrThrow)(() => JSON.stringify(content, (_, value) => typeof value === "bigint" ? value.toString() : value), `Failed to stringify tool content. toolCallId: ${toolCallId}, content: ${(0, node_util_1.inspect)(content)}`), name);
+            : JSON.stringify(content, (_, value) => typeof value === "bigint" ? value.toString() : value), name);
         this.toolCallId = toolCallId;
     }
     format(variables) {

package/lib/cjs/utils/logger.js

@@ -4,8 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.logger = exports.Logger = exports.LogLevel = void 0;
-const node_tty_1 = require("node:tty");
 const debug_1 = __importDefault(require("debug"));
+const nodejs_js_1 = require("./nodejs.js");
 var LogLevel;
 (function (LogLevel) {
     LogLevel["ERROR"] = "error";
@@ -23,13 +23,13 @@ class Logger {
         this.errorLogger = (0, debug_1.default)(`${options.ns}:error`);
         for (const logger of [this.debugLogger, this.infoLogger, this.warnLogger]) {
             // @ts-ignore
-            logger.useColors = (0, node_tty_1.isatty)(process.stdout.fd);
+            logger.useColors = nodejs_js_1.nodejs.isStdoutATTY;
             logger.enabled = true;
             logger.log = (...args) => this.logMessage(...args);
         }
         this.errorLogger.log = (...args) => this.logError(...args);
         // @ts-ignore
-        this.errorLogger.useColors = (0, node_tty_1.isatty)(process.stderr.fd);
+        this.errorLogger.useColors = nodejs_js_1.nodejs.isStderrATTY;
         this.errorLogger.enabled = true;
     }
     level;

package/lib/cjs/utils/nodejs.d.ts

@@ -0,0 +1,8 @@
+export declare const nodejs: {
+    customInspect: any;
+    isStdoutATTY: boolean;
+    isStderrATTY: boolean;
+    env: NodeJS.ProcessEnv;
+    readonly fs: typeof import("node:fs/promises");
+    readonly path: typeof import("node:path");
+};

package/lib/cjs/utils/nodejs.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodejs = void 0;
+exports.nodejs = {
+    customInspect: isNodejsEnvironment() ? require("node:util").inspect.custom : Symbol("inspect"),
+    isStdoutATTY: isNodejsEnvironment() && process.stdout?.isTTY,
+    isStderrATTY: isNodejsEnvironment() && process.stderr?.isTTY,
+    env: isNodejsEnvironment() ? process.env : {},
+    get fs() {
+        ensureNodejsEnvironment();
+        return require("node:fs/promises");
+    },
+    get path() {
+        ensureNodejsEnvironment();
+        return require("node:path");
+    },
+};
+function isNodejsEnvironment() {
+    return typeof process !== "undefined";
+}
+function ensureNodejsEnvironment() {
+    if (!isNodejsEnvironment())
+        throw new Error("This code must run in a Node.js environment.");
+}

package/lib/dts/agents/agent.d.ts

@@ -1,8 +1,10 @@
-import { inspect } from "node:util";
 import { ZodObject, type ZodType } from "zod";
 import type { Context, UserContext } from "../aigne/context.js";
 import type { MessagePayload } from "../aigne/message-queue.js";
-import type { MemoryAgent } from "../memory/memory.js";
+import type { Memory, MemoryAgent } from "../memory/memory.js";
+import type { MemoryRecorderInput } from "../memory/recorder.js";
+import type { MemoryRetrieverInput } from "../memory/retriever.js";
+import { nodejs } from "../utils/nodejs.js";
 import { type Nullish, type PromiseOrValue, type XOr } from "../utils/type-utils.js";
 import type { GuideRailAgent, GuideRailAgentOutput } from "./guide-rail-agent.js";
 import { type TransferAgentOutput } from "./types.js";
@@ -95,6 +97,10 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      * One or more memory agents this agent can use
      */
     memory?: MemoryAgent | MemoryAgent[];
+    /**
+     * Maximum number of memory items to retrieve
+     */
+    maxRetrieveMemoryCount?: number;
 }
 export declare const agentOptionsSchema: ZodObject<{
     [key in keyof AgentOptions]: ZodType<AgentOptions[key]>;
@@ -125,6 +131,8 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
      * and returns the final JSON result
      */
     streaming?: boolean;
+    userContext?: U;
+    memories?: Pick<Memory, "content">[];
 }
 /**
  * Agent is the base class for all agents.
@@ -149,11 +157,24 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
  * {@includeCode ../../test/agents/agent.test.ts#example-custom-agent}
  */
 export declare abstract class Agent<I extends Message = Message, O extends Message = Message> {
+    /**
+     * Custom object inspection behavior
+     *
+     * When using Node.js's util.inspect function to inspect an agent,
+     * only the agent's name will be shown, making output more concise
+     *
+     * @returns Agent name
+     */
+    [nodejs.customInspect]: () => string;
     constructor(options?: AgentOptions<I, O>);
     /**
      * List of memories this agent can use
      */
     readonly memories: MemoryAgent[];
+    /**
+     * Maximum number of memory items to retrieve
+     */
+    maxRetrieveMemoryCount?: number;
     /**
      * Lifecycle hooks for agent processing.
      *
@@ -297,6 +318,10 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      */
     private checkContextStatus;
     private newDefaultContext;
+    retrieveMemories(input: Pick<MemoryRetrieverInput, "limit"> & {
+        search?: Message | string;
+    }, options: Pick<AgentInvokeOptions, "context">): Promise<Pick<Memory, "content">[]>;
+    recordMemories(input: MemoryRecorderInput, options: Pick<AgentInvokeOptions, "context">): Promise<void>;
     /**
      * Invoke the agent with regular (non-streaming) response
      *
@@ -460,15 +485,6 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-shutdown-by-using}
      */
     shutdown(): Promise<void>;
-    /**
-     * Custom object inspection behavior
-     *
-     * When using Node.js's util.inspect function to inspect an agent,
-     * only the agent's name will be shown, making output more concise
-     *
-     * @returns Agent name
-     */
-    [inspect.custom](): string;
     /**
      * Async dispose method for shutdown the agent
      *

package/lib/dts/agents/ai-agent.d.ts

@@ -1,5 +1,4 @@
 import { type ZodObject, type ZodType, z } from "zod";
-import { type DefaultMemoryOptions } from "../memory/default-memory/index.js";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessAsyncGenerator, type Message } from "./agent.js";
 import { ChatModel, type ChatModelInput } from "./chat-model.js";
@@ -13,7 +12,7 @@ import type { GuideRailAgentOutput } from "./guide-rail-agent.js";
  * @template I The input message type the agent accepts
  * @template O The output message type the agent returns
  */
-export interface AIAgentOptions<I extends Message = Message, O extends Message = Message> extends Omit<AgentOptions<I, O>, "memory"> {
+export interface AIAgentOptions<I extends Message = Message, O extends Message = Message> extends AgentOptions<I, O> {
     /**
      * The language model to use for this agent
      *
@@ -65,7 +64,6 @@ export interface AIAgentOptions<I extends Message = Message, O extends Message =
      * The template receives a {{memories}} variable containing serialized memory content.
      */
     memoryPromptTemplate?: string;
-    memory?: AgentOptions<I, O>["memory"] | DefaultMemoryOptions | true;
 }
 /**
  * Tool choice options for AI agents

package/lib/dts/agents/mcp-agent.d.ts

@@ -1,6 +1,6 @@
 import { Client, type ClientOptions } from "@modelcontextprotocol/sdk/client/index.js";
 import { type SSEClientTransportOptions } from "@modelcontextprotocol/sdk/client/sse.js";
-import { type StdioServerParameters } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { StdioServerParameters } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { type StreamableHTTPClientTransportOptions } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";

package/lib/dts/agents/user-agent.d.ts

@@ -1,4 +1,3 @@
-import { ReadableStream } from "node:stream/web";
 import type { Context } from "../aigne/context.js";
 import { type MessagePayload } from "../aigne/message-queue.js";
 import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessResult, type FunctionAgentFn, type Message } from "./agent.js";

package/lib/dts/aigne/context.d.ts

@@ -1,4 +1,4 @@
-import EventEmitter from "node:events";
+import { Emitter } from "strict-event-emitter";
 import { Agent, type AgentInvokeOptions, type AgentProcessAsyncGenerator, type AgentResponse, type AgentResponseStream, type Message } from "../agents/agent.js";
 import type { ChatModel } from "../agents/chat-model.js";
 import { UserAgent } from "../agents/user-agent.js";
@@ -42,7 +42,6 @@ export interface InvokeOptions<U extends UserContext = UserContext> extends Part
     returnActiveAgent?: boolean;
     disableTransfer?: boolean;
     sourceAgent?: Agent;
-    userContext?: U;
 }
 /**
  * @hidden
@@ -150,7 +149,7 @@ declare class AIGNEContextShared {
         messageQueue?: MessageQueue;
     }) | undefined, overrides?: Partial<Context>);
     readonly messageQueue: MessageQueue;
-    readonly events: EventEmitter<ContextEventMap>;
+    readonly events: Emitter<any>;
     get model(): ChatModel | undefined;
     get skills(): Agent<Message, Message>[] | undefined;
     get limits(): ContextLimits | undefined;

package/lib/dts/aigne/message-queue.d.ts

@@ -1,4 +1,4 @@
-import { EventEmitter } from "node:events";
+import { Emitter, type EventMap } from "strict-event-emitter";
 import type { Message } from "../agents/agent.js";
 import type { Context } from "./context.js";
 /**
@@ -30,11 +30,14 @@ export type MessageQueueListener = (message: MessagePayload) => void;
  * @hidden
  */
 export type Unsubscribe = () => void;
+interface MessageQueueEventMap extends EventMap {
+    [key: string]: any[];
+}
 /**
  * @hidden
  */
 export declare class MessageQueue {
-    events: EventEmitter<[never]>;
+    events: Emitter<MessageQueueEventMap>;
     publish(topic: string | string[], payload: MessagePayload): void;
     error(error: Error): void;
     subscribe(topic: string | string[], listener?: undefined): Promise<MessagePayload>;
@@ -42,3 +45,4 @@ export declare class MessageQueue {
     subscribe(topic: string | string[], listener?: MessageQueueListener): Unsubscribe | Promise<MessagePayload>;
     unsubscribe(topic: string | string[], listener: MessageQueueListener): void;
 }
+export {};

package/lib/dts/index.d.ts

@@ -7,5 +7,6 @@ export * from "./agents/team-agent.js";
 export * from "./agents/types.js";
 export * from "./agents/user-agent.js";
 export * from "./aigne/index.js";
+export * from "./memory/index.js";
 export * from "./prompt/prompt-builder.js";
 export * from "./prompt/template.js";

package/lib/dts/loader/agent-js.d.ts

@@ -1,8 +1,8 @@
 import { type ZodObject, type ZodType, z } from "zod";
 import type { Message } from "../agents/agent.js";
 export declare function loadAgentFromJsFile(path: string): Promise<{
-    name: string;
     process: (args_0: Message) => Message;
+    name: string;
     description?: string | undefined;
     inputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
         [x: string]: any;

package/lib/dts/loader/agent-yaml.d.ts

@@ -5,10 +5,11 @@ export declare function loadAgentFromYamlFile(path: string): Promise<{
     name: string;
     description?: string | undefined;
     skills?: string[] | undefined;
+    instructions?: string | undefined;
     memory?: true | {
+        provider: string;
         subscribeTopic?: string[] | undefined;
     } | undefined;
-    instructions?: string | undefined;
     inputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
         [x: string]: any;
     }, {

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

@@ -2,6 +2,7 @@ import type { Camelize } from "camelize-ts";
 import { z } from "zod";
 import { type Agent } from "../agents/agent.js";
 import type { ChatModel, ChatModelOptions } from "../agents/chat-model.js";
+import type { MemoryAgent, MemoryAgentOptions } from "../memory/memory.js";
 export interface LoadOptions {
     models: {
         new (parameters: {
@@ -9,6 +10,9 @@ export interface LoadOptions {
             modelOptions?: ChatModelOptions;
         }): ChatModel;
     }[];
+    memories?: {
+        new (parameters?: MemoryAgentOptions): MemoryAgent;
+    }[];
     path: string;
 }
 export declare function load(options: LoadOptions): Promise<{
@@ -26,7 +30,7 @@ export declare function load(options: LoadOptions): Promise<{
         presence_penalty?: number | null | undefined;
     } | null | undefined;
 }>;
-export declare function loadAgent(path: string): Promise<Agent>;
+export declare function loadAgent(path: string, options?: LoadOptions): Promise<Agent>;
 export declare function loadModel(models: LoadOptions["models"], model?: Camelize<z.infer<typeof aigneFileSchema>["chat_model"]>, modelOptions?: ChatModelOptions): Promise<ChatModel | undefined>;
 declare const aigneFileSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodNullable<z.ZodString>>;

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

@@ -39,11 +39,11 @@ export declare const memoryRetrieverInputSchema: z.ZodObject<{
     limit: z.ZodOptional<z.ZodNumber>;
     search: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    search?: string | undefined;
     limit?: number | undefined;
-}, {
     search?: string | undefined;
+}, {
     limit?: number | undefined;
+    search?: string | undefined;
 }>;
 /**
  * @hidden

package/lib/dts/prompt/prompt-builder.d.ts

@@ -1,9 +1,7 @@
 import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
-import { Agent, type Message } from "../agents/agent.js";
+import { Agent, type AgentInvokeOptions, type Message } from "../agents/agent.js";
 import type { AIAgent } from "../agents/ai-agent.js";
 import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
-import type { Context } from "../aigne/context.js";
-import type { MemoryAgent } from "../memory/memory.js";
 import { ChatMessagesTemplate } from "./template.js";
 export declare const MESSAGE_KEY = "$message";
 export declare function createMessage<V extends Message>(message: string, variables?: V): {
@@ -17,9 +15,7 @@ export declare function getMessage(input: Message): string | undefined;
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
 }
-export interface PromptBuildOptions {
-    memory?: MemoryAgent | MemoryAgent[];
-    context: Context;
+export interface PromptBuildOptions extends AgentInvokeOptions {
     agent?: AIAgent;
     input?: Message;
     model?: ChatModel;

package/lib/dts/utils/nodejs.d.ts

@@ -0,0 +1,8 @@
+export declare const nodejs: {
+    customInspect: any;
+    isStdoutATTY: boolean;
+    isStderrATTY: boolean;
+    env: NodeJS.ProcessEnv;
+    readonly fs: typeof import("node:fs/promises");
+    readonly path: typeof import("node:path");
+};

package/lib/esm/agents/agent.d.ts

@@ -1,8 +1,10 @@
-import { inspect } from "node:util";
 import { ZodObject, type ZodType } from "zod";
 import type { Context, UserContext } from "../aigne/context.js";
 import type { MessagePayload } from "../aigne/message-queue.js";
-import type { MemoryAgent } from "../memory/memory.js";
+import type { Memory, MemoryAgent } from "../memory/memory.js";
+import type { MemoryRecorderInput } from "../memory/recorder.js";
+import type { MemoryRetrieverInput } from "../memory/retriever.js";
+import { nodejs } from "../utils/nodejs.js";
 import { type Nullish, type PromiseOrValue, type XOr } from "../utils/type-utils.js";
 import type { GuideRailAgent, GuideRailAgentOutput } from "./guide-rail-agent.js";
 import { type TransferAgentOutput } from "./types.js";
@@ -95,6 +97,10 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      * One or more memory agents this agent can use
      */
     memory?: MemoryAgent | MemoryAgent[];
+    /**
+     * Maximum number of memory items to retrieve
+     */
+    maxRetrieveMemoryCount?: number;
 }
 export declare const agentOptionsSchema: ZodObject<{
     [key in keyof AgentOptions]: ZodType<AgentOptions[key]>;
@@ -125,6 +131,8 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
      * and returns the final JSON result
      */
     streaming?: boolean;
+    userContext?: U;
+    memories?: Pick<Memory, "content">[];
 }
 /**
  * Agent is the base class for all agents.
@@ -149,11 +157,24 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
  * {@includeCode ../../test/agents/agent.test.ts#example-custom-agent}
  */
 export declare abstract class Agent<I extends Message = Message, O extends Message = Message> {
+    /**
+     * Custom object inspection behavior
+     *
+     * When using Node.js's util.inspect function to inspect an agent,
+     * only the agent's name will be shown, making output more concise
+     *
+     * @returns Agent name
+     */
+    [nodejs.customInspect]: () => string;
     constructor(options?: AgentOptions<I, O>);
     /**
      * List of memories this agent can use
      */
     readonly memories: MemoryAgent[];
+    /**
+     * Maximum number of memory items to retrieve
+     */
+    maxRetrieveMemoryCount?: number;
     /**
      * Lifecycle hooks for agent processing.
      *
@@ -297,6 +318,10 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      */
     private checkContextStatus;
     private newDefaultContext;
+    retrieveMemories(input: Pick<MemoryRetrieverInput, "limit"> & {
+        search?: Message | string;
+    }, options: Pick<AgentInvokeOptions, "context">): Promise<Pick<Memory, "content">[]>;
+    recordMemories(input: MemoryRecorderInput, options: Pick<AgentInvokeOptions, "context">): Promise<void>;
     /**
      * Invoke the agent with regular (non-streaming) response
      *
@@ -460,15 +485,6 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-shutdown-by-using}
      */
     shutdown(): Promise<void>;
-    /**
-     * Custom object inspection behavior
-     *
-     * When using Node.js's util.inspect function to inspect an agent,
-     * only the agent's name will be shown, making output more concise
-     *
-     * @returns Agent name
-     */
-    [inspect.custom](): string;
     /**
      * Async dispose method for shutdown the agent
      *