@aigne/core 1.62.0 → 1.63.0-beta

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.63.0-beta](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.62.0...core-v1.63.0-beta) (2025-10-07)
+
+
+### Features
+
+* **afs:** add basic AFS(AIGNE File System) support ([#505](https://github.com/AIGNE-io/aigne-framework/issues/505)) ([ac2a18a](https://github.com/AIGNE-io/aigne-framework/commit/ac2a18a82470a2f31c466f329386525eb1cdab6d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs bumped to 1.0.0
+    * @aigne/observability-api bumped to 0.11.2-beta
+
 ## [1.62.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.62.0-beta.6...core-v1.62.0) (2025-10-04)
 
 

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

@@ -1,3 +1,4 @@
+import { AFS, type AFSOptions } from "@aigne/afs";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import type * as prompts from "@inquirer/prompts";
 import { type ZodObject, type ZodType } from "zod";
@@ -120,6 +121,7 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      * One or more memory agents this agent can use
      */
     memory?: MemoryAgent | MemoryAgent[];
+    afs?: true | AFSOptions | AFS | ((afs: AFS) => AFS);
     asyncMemoryRecord?: boolean;
     /**
      * Maximum number of memory items to retrieve
@@ -205,8 +207,11 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
     constructor(options?: AgentOptions<I, O>);
     /**
      * List of memories this agent can use
+     *
+     * @deprecated use afs instead
      */
     readonly memories: MemoryAgent[];
+    afs?: AFS;
     asyncMemoryRecord?: boolean;
     tag?: string;
     /**

package/lib/cjs/agents/agent.js

@@ -46,6 +46,7 @@ exports.isAgentResponseProgress = isAgentResponseProgress;
 exports.textDelta = textDelta;
 exports.jsonDelta = jsonDelta;
 exports.agentProcessResultToObject = agentProcessResultToObject;
+const afs_1 = require("@aigne/afs");
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
 const fast_deep_equal_1 = __importDefault(require("fast-deep-equal"));
 const nunjucks_1 = __importDefault(require("nunjucks"));
@@ -151,6 +152,15 @@ class Agent {
         else if (options.memory) {
             this.memories.push(options.memory);
         }
+        this.afs = !options.afs
+            ? undefined
+            : options.afs === true
+                ? new afs_1.AFS()
+                : typeof options.afs === "function"
+                    ? options.afs(new afs_1.AFS())
+                    : options.afs instanceof afs_1.AFS
+                        ? options.afs
+                        : new afs_1.AFS(options.afs);
         this.asyncMemoryRecord = options.asyncMemoryRecord;
         this.maxRetrieveMemoryCount = options.maxRetrieveMemoryCount;
         this.hooks = (0, type_utils_js_1.flat)(options.hooks);
@@ -164,8 +174,11 @@ class Agent {
     }
     /**
      * List of memories this agent can use
+     *
+     * @deprecated use afs instead
      */
     memories = [];
+    afs;
     asyncMemoryRecord;
     tag;
     /**
@@ -537,6 +550,7 @@ class Agent {
         const o = await this.callHooks(["onSuccess", "onEnd"], { input, output: finalOutput }, options);
         if (o?.output)
             finalOutput = o.output;
+        this.afs?.emit("agentSucceed", { input, output: finalOutput });
         if (!this.disableEvents)
             context.emit("agentSucceed", { agent: this, output: finalOutput });
         return finalOutput;

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

@@ -1,6 +1,6 @@
 import { type ZodObject, type ZodType, z } from "zod";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
-import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessAsyncGenerator, type Message } from "./agent.js";
+import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessAsyncGenerator, type AgentProcessResult, type Message } from "./agent.js";
 import type { ChatModel, ChatModelInput } from "./chat-model.js";
 import type { GuideRailAgentOutput } from "./guide-rail-agent.js";
 import type { FileType } from "./model.js";
@@ -304,7 +304,8 @@ export declare class AIAgent<I extends Message = any, O extends Message = any> e
      *
      * @protected
      */
-    process(input: I, options: AgentInvokeOptions): AgentProcessAsyncGenerator<O>;
+    process(input: I, options: AgentInvokeOptions): AgentProcessResult<O>;
+    private _process;
     protected onGuideRailError(error: GuideRailAgentOutput): Promise<O | GuideRailAgentOutput>;
     /**
      * Process router mode requests

package/lib/cjs/agents/ai-agent.js

@@ -235,7 +235,10 @@ class AIAgent extends agent_js_1.Agent {
      *
      * @protected
      */
-    async *process(input, options) {
+    process(input, options) {
+        return this._process(input, options);
+    }
+    async *_process(input, options) {
         const model = this.model || options.model || options.context.model;
         if (!model)
             throw new Error("model is required to run AIAgent");

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PromptBuilder = void 0;
+const afs_1 = require("@aigne/afs");
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
 const yaml_1 = require("yaml");
 const zod_1 = require("zod");
@@ -98,6 +99,18 @@ class PromptBuilder {
         if (options.agent?.useMemoriesFromContext && options.context?.memories?.length) {
             memories.push(...options.context.memories);
         }
+        if (options.agent?.afs) {
+            const history = await options.agent.afs.list(afs_1.AFSHistory.Path, {
+                limit: options.agent.maxRetrieveMemoryCount || 1,
+                orderBy: [["createdAt", "desc"]],
+            });
+            if (message) {
+                const result = await options.agent.afs.search("/", message);
+                const ms = result.list.map((entry) => ({ content: (0, yaml_1.stringify)(entry.content) }));
+                memories.push(...ms);
+            }
+            memories.push(...history.list.filter((i) => (0, type_utils_js_1.isNonNullable)(i.content)));
+        }
         if (memories.length)
             messages.push(...(await this.convertMemoriesToMessages(memories, options)));
         // if the agent is using structured stream mode, add the instructions

package/lib/cjs/utils/agent-utils.d.ts

@@ -1,4 +1,4 @@
-import type { AgentHooks } from "../agents/agent.ts";
+import type { AgentHooks } from "../agents/agent.js";
 import type { AIGNECLIAgents } from "../aigne/type.js";
 export declare function sortHooks(hooks: AgentHooks[]): AgentHooks[];
 export interface CLIAgent<T> {
@@ -9,4 +9,4 @@ export interface CLIAgent<T> {
     agents?: CLIAgent<T>[];
 }
 export declare function mapCliAgent<A, O>({ agent, agents, ...input }: CLIAgent<A>, transform: (input: A) => O): CLIAgent<O>;
-export declare function findCliAgent(cli: AIGNECLIAgents, parent: string[] | "*", name: string): import("../agents/agent.ts").Agent<any, any> | undefined;
+export declare function findCliAgent(cli: AIGNECLIAgents, parent: string[] | "*", name: string): import("../agents/agent.js").Agent<any, any> | undefined;

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

@@ -1,3 +1,4 @@
+import { AFS, type AFSOptions } from "@aigne/afs";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import type * as prompts from "@inquirer/prompts";
 import { type ZodObject, type ZodType } from "zod";
@@ -120,6 +121,7 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      * One or more memory agents this agent can use
      */
     memory?: MemoryAgent | MemoryAgent[];
+    afs?: true | AFSOptions | AFS | ((afs: AFS) => AFS);
     asyncMemoryRecord?: boolean;
     /**
      * Maximum number of memory items to retrieve
@@ -205,8 +207,11 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
     constructor(options?: AgentOptions<I, O>);
     /**
      * List of memories this agent can use
+     *
+     * @deprecated use afs instead
      */
     readonly memories: MemoryAgent[];
+    afs?: AFS;
     asyncMemoryRecord?: boolean;
     tag?: string;
     /**

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

@@ -1,6 +1,6 @@
 import { type ZodObject, type ZodType, z } from "zod";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
-import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessAsyncGenerator, type Message } from "./agent.js";
+import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessAsyncGenerator, type AgentProcessResult, type Message } from "./agent.js";
 import type { ChatModel, ChatModelInput } from "./chat-model.js";
 import type { GuideRailAgentOutput } from "./guide-rail-agent.js";
 import type { FileType } from "./model.js";
@@ -304,7 +304,8 @@ export declare class AIAgent<I extends Message = any, O extends Message = any> e
      *
      * @protected
      */
-    process(input: I, options: AgentInvokeOptions): AgentProcessAsyncGenerator<O>;
+    process(input: I, options: AgentInvokeOptions): AgentProcessResult<O>;
+    private _process;
     protected onGuideRailError(error: GuideRailAgentOutput): Promise<O | GuideRailAgentOutput>;
     /**
      * Process router mode requests

package/lib/dts/utils/agent-utils.d.ts

@@ -1,4 +1,4 @@
-import type { AgentHooks } from "../agents/agent.ts";
+import type { AgentHooks } from "../agents/agent.js";
 import type { AIGNECLIAgents } from "../aigne/type.js";
 export declare function sortHooks(hooks: AgentHooks[]): AgentHooks[];
 export interface CLIAgent<T> {
@@ -9,4 +9,4 @@ export interface CLIAgent<T> {
     agents?: CLIAgent<T>[];
 }
 export declare function mapCliAgent<A, O>({ agent, agents, ...input }: CLIAgent<A>, transform: (input: A) => O): CLIAgent<O>;
-export declare function findCliAgent(cli: AIGNECLIAgents, parent: string[] | "*", name: string): import("../agents/agent.ts").Agent<any, any> | undefined;
+export declare function findCliAgent(cli: AIGNECLIAgents, parent: string[] | "*", name: string): import("../agents/agent.js").Agent<any, any> | undefined;

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

@@ -1,3 +1,4 @@
+import { AFS, type AFSOptions } from "@aigne/afs";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import type * as prompts from "@inquirer/prompts";
 import { type ZodObject, type ZodType } from "zod";
@@ -120,6 +121,7 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      * One or more memory agents this agent can use
      */
     memory?: MemoryAgent | MemoryAgent[];
+    afs?: true | AFSOptions | AFS | ((afs: AFS) => AFS);
     asyncMemoryRecord?: boolean;
     /**
      * Maximum number of memory items to retrieve
@@ -205,8 +207,11 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
     constructor(options?: AgentOptions<I, O>);
     /**
      * List of memories this agent can use
+     *
+     * @deprecated use afs instead
      */
     readonly memories: MemoryAgent[];
+    afs?: AFS;
     asyncMemoryRecord?: boolean;
     tag?: string;
     /**

package/lib/esm/agents/agent.js

@@ -1,3 +1,4 @@
+import { AFS } from "@aigne/afs";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import equal from "fast-deep-equal";
 import nunjucks from "nunjucks";
@@ -103,6 +104,15 @@ export class Agent {
         else if (options.memory) {
             this.memories.push(options.memory);
         }
+        this.afs = !options.afs
+            ? undefined
+            : options.afs === true
+                ? new AFS()
+                : typeof options.afs === "function"
+                    ? options.afs(new AFS())
+                    : options.afs instanceof AFS
+                        ? options.afs
+                        : new AFS(options.afs);
         this.asyncMemoryRecord = options.asyncMemoryRecord;
         this.maxRetrieveMemoryCount = options.maxRetrieveMemoryCount;
         this.hooks = flat(options.hooks);
@@ -116,8 +126,11 @@ export class Agent {
     }
     /**
      * List of memories this agent can use
+     *
+     * @deprecated use afs instead
      */
     memories = [];
+    afs;
     asyncMemoryRecord;
     tag;
     /**
@@ -489,6 +502,7 @@ export class Agent {
         const o = await this.callHooks(["onSuccess", "onEnd"], { input, output: finalOutput }, options);
         if (o?.output)
             finalOutput = o.output;
+        this.afs?.emit("agentSucceed", { input, output: finalOutput });
         if (!this.disableEvents)
             context.emit("agentSucceed", { agent: this, output: finalOutput });
         return finalOutput;

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

@@ -1,6 +1,6 @@
 import { type ZodObject, type ZodType, z } from "zod";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
-import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessAsyncGenerator, type Message } from "./agent.js";
+import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessAsyncGenerator, type AgentProcessResult, type Message } from "./agent.js";
 import type { ChatModel, ChatModelInput } from "./chat-model.js";
 import type { GuideRailAgentOutput } from "./guide-rail-agent.js";
 import type { FileType } from "./model.js";
@@ -304,7 +304,8 @@ export declare class AIAgent<I extends Message = any, O extends Message = any> e
      *
      * @protected
      */
-    process(input: I, options: AgentInvokeOptions): AgentProcessAsyncGenerator<O>;
+    process(input: I, options: AgentInvokeOptions): AgentProcessResult<O>;
+    private _process;
     protected onGuideRailError(error: GuideRailAgentOutput): Promise<O | GuideRailAgentOutput>;
     /**
      * Process router mode requests

package/lib/esm/agents/ai-agent.js

@@ -232,7 +232,10 @@ export class AIAgent extends Agent {
      *
      * @protected
      */
-    async *process(input, options) {
+    process(input, options) {
+        return this._process(input, options);
+    }
+    async *_process(input, options) {
         const model = this.model || options.model || options.context.model;
         if (!model)
             throw new Error("model is required to run AIAgent");

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

@@ -1,3 +1,4 @@
+import { AFSHistory } from "@aigne/afs";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import { stringify } from "yaml";
 import { ZodObject } from "zod";
@@ -7,7 +8,7 @@ import { DEFAULT_OUTPUT_FILE_KEY, DEFAULT_OUTPUT_KEY } from "../agents/ai-agent.
 import { fileUnionContentsSchema } from "../agents/model.js";
 import { optionalize } from "../loader/schema.js";
 import { outputSchemaToResponseFormatSchema } from "../utils/json-schema.js";
-import { checkArguments, flat, isRecord, unique } from "../utils/type-utils.js";
+import { checkArguments, flat, isNonNullable, isRecord, unique } from "../utils/type-utils.js";
 import { MEMORY_MESSAGE_TEMPLATE } from "./prompts/memory-message-template.js";
 import { STRUCTURED_STREAM_INSTRUCTIONS } from "./prompts/structured-stream-instructions.js";
 import { AgentMessageTemplate, ChatMessagesTemplate, PromptTemplate, SystemMessageTemplate, UserMessageTemplate, } from "./template.js";
@@ -95,6 +96,18 @@ export class PromptBuilder {
         if (options.agent?.useMemoriesFromContext && options.context?.memories?.length) {
             memories.push(...options.context.memories);
         }
+        if (options.agent?.afs) {
+            const history = await options.agent.afs.list(AFSHistory.Path, {
+                limit: options.agent.maxRetrieveMemoryCount || 1,
+                orderBy: [["createdAt", "desc"]],
+            });
+            if (message) {
+                const result = await options.agent.afs.search("/", message);
+                const ms = result.list.map((entry) => ({ content: stringify(entry.content) }));
+                memories.push(...ms);
+            }
+            memories.push(...history.list.filter((i) => isNonNullable(i.content)));
+        }
         if (memories.length)
             messages.push(...(await this.convertMemoriesToMessages(memories, options)));
         // if the agent is using structured stream mode, add the instructions

package/lib/esm/utils/agent-utils.d.ts

@@ -1,4 +1,4 @@
-import type { AgentHooks } from "../agents/agent.ts";
+import type { AgentHooks } from "../agents/agent.js";
 import type { AIGNECLIAgents } from "../aigne/type.js";
 export declare function sortHooks(hooks: AgentHooks[]): AgentHooks[];
 export interface CLIAgent<T> {
@@ -9,4 +9,4 @@ export interface CLIAgent<T> {
     agents?: CLIAgent<T>[];
 }
 export declare function mapCliAgent<A, O>({ agent, agents, ...input }: CLIAgent<A>, transform: (input: A) => O): CLIAgent<O>;
-export declare function findCliAgent(cli: AIGNECLIAgents, parent: string[] | "*", name: string): import("../agents/agent.ts").Agent<any, any> | undefined;
+export declare function findCliAgent(cli: AIGNECLIAgents, parent: string[] | "*", name: string): import("../agents/agent.js").Agent<any, any> | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.62.0",
+  "version": "1.63.0-beta",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"
@@ -92,8 +92,9 @@
     "zod": "^3.25.67",
     "zod-from-json-schema": "^0.0.5",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/observability-api": "^0.11.1",
-    "@aigne/platform-helpers": "^0.6.3"
+    "@aigne/observability-api": "^0.11.2-beta",
+    "@aigne/platform-helpers": "^0.6.3",
+    "@aigne/afs": "^1.0.0"
   },
   "devDependencies": {
     "@types/bun": "^1.2.22",