@aigne/afs 1.1.2-beta → 1.2.0-beta

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.2.0-beta](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.1.2...afs-v1.2.0-beta) (2025-11-14)
+
+
+### Features
+
+* support mount mcp agent into AFS ([#740](https://github.com/AIGNE-io/aigne-framework/issues/740)) ([6d474fc](https://github.com/AIGNE-io/aigne-framework/commit/6d474fc05845a15e2c3e8fa97727b409bdd70945))
+
+## [1.1.2](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.1.2-beta...afs-v1.1.2) (2025-11-12)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/sqlite bumped to 0.4.4
+
 ## [1.1.2-beta](https://github.com/AIGNE-io/aigne-framework/compare/afs-v1.1.1...afs-v1.1.2-beta) (2025-11-12)
 
 

package/README.md

@@ -0,0 +1,359 @@
+# @aigne/afs
+
+**@aigne/afs** is the core package of the Agentic File System (AFS), providing a virtual file system abstraction layer that enables AI agents to access various storage backends through a unified, path-based API.
+
+## Overview
+
+AFS Core provides the foundational infrastructure for building virtual file systems that can integrate with different storage backends. It includes the base AFS implementation, module mounting system, and event-driven architecture for building modular storage solutions.
+
+## Features
+
+- **Virtual File System**: Hierarchical path-based structure with `/modules` root directory
+- **Module System**: Pluggable architecture for custom storage backends
+- **Unified API**: Consistent interface for list, read, write, search, and exec operations
+- **Event System**: Event-driven architecture for module communication
+- **AI Agent Integration**: Seamless integration with AIGNE agents
+
+## Installation
+
+```bash
+npm install @aigne/afs
+# or
+yarn add @aigne/afs
+# or
+pnpm add @aigne/afs
+```
+
+## Quick Start
+
+```typescript
+import { AFS } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
+
+// Create AFS instance
+const afs = new AFS();
+
+// Mount history module (optional)
+afs.mount(new AFSHistory({
+  storage: { url: "file:./memory.sqlite3" }
+}));
+
+// All modules are mounted under /modules
+// List modules
+const modules = await afs.listModules();
+
+// List entries in a module
+const { list } = await afs.list('/modules/history');
+
+// Read an entry
+const { result } = await afs.read('/modules/history/some-id');
+
+// Write an entry (if module supports write)
+await afs.write('/modules/history/notes', {
+  content: 'My notes',
+  summary: 'Personal notes'
+});
+
+// Search for content
+const { list: results } = await afs.search('/modules/history', 'search query');
+```
+
+## Core Concepts
+
+### AFSEntry
+
+All data in AFS is represented as `AFSEntry` objects:
+
+```typescript
+interface AFSEntry {
+  id: string;                      // Unique identifier
+  path: string;                    // Full path in AFS
+  content?: any;                   // File/data content
+  summary?: string;                // Optional summary
+  metadata?: Record<string, any>;  // Custom metadata
+  createdAt?: Date;                // Creation timestamp
+  updatedAt?: Date;                // Last update timestamp
+  userId?: string;                 // Associated user
+  sessionId?: string;              // Associated session
+  linkTo?: string;                 // Link to another entry
+}
+```
+
+### Modules
+
+Modules are pluggable components that implement storage backends. All modules are automatically mounted under the `/modules` path prefix:
+
+```typescript
+interface AFSModule {
+  name: string;                   // Module name (used as mount path)
+  description?: string;           // Description for AI agents
+
+  // Operations (all optional)
+  list?(path: string, options?: AFSListOptions): Promise<{ list: AFSEntry[]; message?: string }>;
+  read?(path: string): Promise<{ result?: AFSEntry; message?: string }>;
+  write?(path: string, entry: AFSWriteEntryPayload): Promise<{ result: AFSEntry; message?: string }>;
+  search?(path: string, query: string, options?: AFSSearchOptions): Promise<{ list: AFSEntry[]; message?: string }>;
+  exec?(path: string, args: Record<string, any>, options: { context: any }): Promise<{ result: Record<string, any> }>;
+
+  // Lifecycle
+  onMount?(afs: AFSRoot): void;
+  onUnmount?(): void;
+}
+```
+
+**Mount Path Convention**: When you mount a module with name `"my-module"`, it will be accessible at `/modules/my-module`.
+
+## API Reference
+
+### AFS Class
+
+#### Constructor
+
+```typescript
+new AFS(options?: AFSOptions)
+```
+
+Options:
+- `modules`: Optional array of modules to mount on initialization
+
+#### Methods
+
+##### mount(module: AFSModule)
+##### mount(path: string, module: AFSModule)
+
+Mount a module. The module will be accessible under `/modules/{module.name}` or `/modules/{path}`:
+
+```typescript
+// Mount using module's name
+afs.mount(new CustomModule());
+
+// Mount with custom path (advanced usage)
+afs.mount("/custom-path", new CustomModule());
+```
+
+##### listModules()
+
+Get all mounted modules:
+
+```typescript
+const modules = await afs.listModules();
+// Returns: [{ name: string, path: string, description?: string, module: AFSModule }]
+```
+
+##### list(path: string, options?: AFSListOptions)
+
+List entries in a directory:
+
+```typescript
+const { list, message } = await afs.list('/modules/history', {
+  maxDepth: 2
+});
+```
+
+Options:
+- `maxDepth`: Maximum recursion depth (default: 1)
+
+##### read(path: string)
+
+Read a specific entry:
+
+```typescript
+const { result, message } = await afs.read('/modules/history/uuid-123');
+```
+
+##### write(path: string, content: AFSWriteEntryPayload)
+
+Write or update an entry:
+
+```typescript
+const { result, message } = await afs.write('/modules/my-module/file.txt', {
+  content: 'Hello, world!',
+  summary: 'Greeting file',
+  metadata: { type: 'greeting' }
+});
+```
+
+##### search(path: string, query: string, options?: AFSSearchOptions)
+
+Search for content:
+
+```typescript
+const { list, message } = await afs.search('/modules/history', 'authentication');
+```
+
+##### exec(path: string, args: Record<string, any>, options: { context: any })
+
+Execute a module-specific operation:
+
+```typescript
+const { result } = await afs.exec('/modules/my-module/action', { param: 'value' }, { context });
+```
+
+### Events
+
+AFS uses an event system for module communication:
+
+```typescript
+// Modules can listen to events
+afs.on('agentSucceed', ({ input, output }) => {
+  console.log('Agent succeeded:', input, output);
+});
+
+// Modules can emit custom events
+afs.emit('customEvent', { data: 'value' });
+```
+
+Common events from `AFSRootEvents`:
+- `agentSucceed`: Emitted when an agent successfully completes
+- `agentFail`: Emitted when an agent fails
+
+## Built-in Modules
+
+### AFSHistory
+
+The history module tracks conversation history. It is available as a separate package: `@aigne/afs-history`.
+
+**Features:**
+- Listens to `agentSucceed` events and records agent interactions
+- Stores input/output pairs with UUID paths
+- Supports list and read operations
+- Can be extended with search capabilities
+- Persistent SQLite storage
+
+**Installation:**
+```bash
+npm install @aigne/afs-history
+```
+
+**Usage:**
+
+```typescript
+import { AFS } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
+
+const afs = new AFS();
+afs.mount(new AFSHistory({
+  storage: { url: "file:./memory.sqlite3" }
+}));
+
+// History entries are accessible at /modules/history
+const { list } = await afs.list('/modules/history');
+```
+
+**Configuration:**
+- `storage`: Storage configuration (e.g., `{ url: "file:./memory.sqlite3" }`) or a SharedAFSStorage instance
+
+**Note:** History is NOT automatically mounted. You must explicitly mount it if needed.
+
+**Documentation:** See [@aigne/afs-history](../history/README.md) for detailed documentation.
+
+## Creating Custom Modules
+
+Create a custom module by implementing the `AFSModule` interface:
+
+```typescript
+import { AFSModule, AFSEntry, AFSListOptions } from "@aigne/afs";
+
+export class CustomModule implements AFSModule {
+  readonly name = "custom-module";
+  readonly description = "My custom storage";
+
+  async list(path: string, options?: AFSListOptions): Promise<{ list: AFSEntry[]; message?: string }> {
+    // path is the subpath within your module
+    // Implement your list logic
+    return { list: [] };
+  }
+
+  async read(path: string): Promise<{ result?: AFSEntry; message?: string }> {
+    // Implement your read logic
+    return { result: undefined };
+  }
+
+  async write(path: string, content: AFSWriteEntryPayload): Promise<{ result: AFSEntry; message?: string }> {
+    // Implement your write logic
+    const entry: AFSEntry = { id: 'id', path, ...content };
+    return { result: entry };
+  }
+
+  async search(path: string, query: string, options?: AFSSearchOptions): Promise<{ list: AFSEntry[]; message?: string }> {
+    // Implement your search logic
+    return { list: [] };
+  }
+
+  onMount(afs: AFSRoot) {
+    console.log(`${this.name} mounted`);
+
+    // Listen to events
+    afs.on('agentSucceed', (data) => {
+      // Handle event
+    });
+  }
+}
+
+// Mount the module
+afs.mount(new CustomModule());
+// Now accessible at /modules/custom-module
+```
+
+## Module Path Resolution
+
+When a module is mounted, AFS handles path resolution automatically:
+
+1. Module mounted with name `"my-module"` → accessible at `/modules/my-module`
+2. When listing `/modules`, AFS shows all mounted modules
+3. When accessing `/modules/my-module/foo`, the module receives `"/foo"` as the path parameter
+
+This allows modules to focus on their internal logic without worrying about mount paths.
+
+## Integration with AI Agents
+
+When an agent has AFS configured, these tools are automatically registered:
+
+- **afs_list**: Browse directory contents
+- **afs_read**: Read file contents
+- **afs_write**: Write/create files
+- **afs_search**: Search for content
+- **afs_exec**: Execute module operations
+
+Example:
+
+```typescript
+import { AIAgent, AIGNE } from "@aigne/core";
+import { AFS } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
+
+const afs = new AFS();
+afs.mount(new AFSHistory({
+  storage: { url: "file:./memory.sqlite3" }
+}));
+
+const agent = AIAgent.from({
+  name: "assistant",
+  afs: afs
+});
+
+const context = aigne.newContext();
+const result = await context.invoke(agent, {
+  message: "What's in my history?"
+});
+```
+
+## Related Packages
+
+- [@aigne/afs-history](../history/README.md) - History tracking module
+- [@aigne/afs-local-fs](../local-fs/README.md) - Local file system module
+- [@aigne/afs-user-profile-memory](../user-profile-memory/README.md) - User profile memory module
+
+## Examples
+
+- [AFS Memory Example](../../examples/afs-memory/README.md) - Conversational memory with user profiles
+- [AFS LocalFS Example](../../examples/afs-local-fs/README.md) - File system access with AI agents
+- [AFS MCP Server Example](../../examples/afs-mcp-server/README.md) - Mount MCP servers as AFS modules
+
+## TypeScript Support
+
+This package includes full TypeScript type definitions.
+
+## License
+
+[Elastic-2.0](../../LICENSE.md)

package/lib/cjs/afs.d.ts

@@ -1,23 +1,18 @@
 import { Emitter } from "strict-event-emitter";
-import { SharedAFSStorage, type SharedAFSStorageOptions } from "./storage/index.js";
-import type { AFSStorage } from "./storage/type.js";
 import type { AFSEntry, AFSListOptions, AFSModule, AFSRoot, AFSRootEvents, AFSSearchOptions, AFSWriteEntryPayload } from "./type.js";
 export interface AFSOptions {
-    storage?: SharedAFSStorage | SharedAFSStorageOptions;
     modules?: AFSModule[];
 }
 export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
-    moduleId: string;
-    path: string;
+    name: string;
     constructor(options?: AFSOptions);
-    private _storage;
-    storage(module: AFSModule): AFSStorage;
     private modules;
-    use(module: AFSModule): this;
+    mount(module: AFSModule): this;
     listModules(): Promise<{
-        moduleId: string;
+        name: string;
         path: string;
         description?: string;
+        module: AFSModule;
     }[]>;
     list(path: string, options?: AFSListOptions): Promise<{
         list: AFSEntry[];
@@ -36,4 +31,9 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
         message?: string;
     }>;
     private findModules;
+    exec(path: string, args: Record<string, any>, options: {
+        context: any;
+    }): Promise<{
+        result: Record<string, any>;
+    }>;
 }

package/lib/cjs/afs.js

@@ -3,38 +3,36 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AFS = void 0;
 const strict_event_emitter_1 = require("strict-event-emitter");
 const ufo_1 = require("ufo");
-const index_js_1 = require("./history/index.js");
-const index_js_2 = require("./storage/index.js");
 const DEFAULT_MAX_DEPTH = 1;
+const MODULES_ROOT_DIR = "/modules";
 class AFS extends strict_event_emitter_1.Emitter {
-    moduleId = "AFSRoot";
-    path = "/";
+    name = "AFSRoot";
     constructor(options) {
         super();
-        this._storage =
-            options?.storage instanceof index_js_2.SharedAFSStorage
-                ? options.storage
-                : new index_js_2.SharedAFSStorage(options?.storage);
-        this.use(new index_js_1.AFSHistory());
         for (const module of options?.modules ?? []) {
-            this.use(module);
+            this.mount(module);
         }
     }
-    _storage;
-    storage(module) {
-        return this._storage.withModule(module);
-    }
     modules = new Map();
-    use(module) {
-        this.modules.set(module.path, module);
+    mount(module) {
+        let path = (0, ufo_1.joinURL)("/", module.name);
+        if (!/^\/[^/]+$/.test(path)) {
+            throw new Error(`Invalid mount path: ${path}. Must start with '/' and contain no other '/'`);
+        }
+        if (this.modules.has(path)) {
+            throw new Error(`Module already mounted at path: ${path}`);
+        }
+        path = (0, ufo_1.joinURL)(MODULES_ROOT_DIR, path);
+        this.modules.set(path, module);
         module.onMount?.(this);
         return this;
     }
     async listModules() {
         return Array.from(this.modules.entries()).map(([path, module]) => ({
-            moduleId: module.moduleId,
             path,
+            name: module.name,
             description: module.description,
+            module,
         }));
     }
     async list(path, options) {
@@ -46,7 +44,7 @@ class AFS extends strict_event_emitter_1.Emitter {
         const matches = this.findModules(path, options);
         for (const matched of matches) {
             const moduleEntry = {
-                id: matched.module.moduleId,
+                id: matched.module.name,
                 path: matched.remainedModulePath,
                 summary: matched.module.description,
             };
@@ -64,7 +62,7 @@ class AFS extends strict_event_emitter_1.Emitter {
                 if (list.length) {
                     results.push(...list.map((entry) => ({
                         ...entry,
-                        path: (0, ufo_1.joinURL)(matched.module.path, entry.path),
+                        path: (0, ufo_1.joinURL)(matched.modulePath, entry.path),
                     })));
                 }
                 else {
@@ -74,21 +72,21 @@ class AFS extends strict_event_emitter_1.Emitter {
                     messages.push(message);
             }
             catch (error) {
-                console.error(`Error listing from module at ${matched.module.path}`, error);
+                console.error(`Error listing from module at ${matched.modulePath}`, error);
             }
         }
         return { list: results, message: messages.join("; ").trim() || undefined };
     }
     async read(path) {
         const modules = this.findModules(path, { exactMatch: true });
-        for (const { module, subpath } of modules) {
+        for (const { module, modulePath, subpath } of modules) {
             const res = await module.read?.(subpath);
             if (res?.result) {
                 return {
                     ...res,
                     result: {
                         ...res.result,
-                        path: (0, ufo_1.joinURL)(module.path, res.result.path),
+                        path: (0, ufo_1.joinURL)(modulePath, res.result.path),
                     },
                 };
             }
@@ -104,27 +102,27 @@ class AFS extends strict_event_emitter_1.Emitter {
             ...res,
             result: {
                 ...res.result,
-                path: (0, ufo_1.joinURL)(module.module.path, res.result.path),
+                path: (0, ufo_1.joinURL)(module.modulePath, res.result.path),
             },
         };
     }
     async search(path, query, options) {
         const results = [];
         const messages = [];
-        for (const { module, subpath } of this.findModules(path)) {
+        for (const { module, modulePath, subpath } of this.findModules(path)) {
             if (!module.search)
                 continue;
             try {
                 const { list, message } = await module.search(subpath, query, options);
                 results.push(...list.map((entry) => ({
                     ...entry,
-                    path: (0, ufo_1.joinURL)(module.path, entry.path),
+                    path: (0, ufo_1.joinURL)(modulePath, entry.path),
                 })));
                 if (message)
                     messages.push(message);
             }
             catch (error) {
-                console.error(`Error searching in module at ${module.path}`, error);
+                console.error(`Error searching in module at ${modulePath}`, error);
             }
         }
         return { list: results, message: messages.join("; ") };
@@ -153,9 +151,15 @@ class AFS extends strict_event_emitter_1.Emitter {
             }
             if (newMaxDepth < 0)
                 continue;
-            matched.push({ module, maxDepth: newMaxDepth, subpath, remainedModulePath });
+            matched.push({ module, modulePath, maxDepth: newMaxDepth, subpath, remainedModulePath });
         }
         return matched;
     }
+    async exec(path, args, options) {
+        const module = this.findModules(path)[0];
+        if (!module?.module.exec)
+            throw new Error(`No module found for path: ${path}`);
+        return await module.module.exec(module.subpath, args, options);
+    }
 }
 exports.AFS = AFS;

package/lib/cjs/index.d.ts

@@ -1,4 +1,2 @@
 export * from "./afs.js";
-export * from "./history/index.js";
-export * from "./storage/index.js";
 export * from "./type.js";

package/lib/cjs/index.js

@@ -15,6 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./afs.js"), exports);
-__exportStar(require("./history/index.js"), exports);
-__exportStar(require("./storage/index.js"), exports);
 __exportStar(require("./type.js"), exports);

package/lib/cjs/type.d.ts

@@ -1,5 +1,4 @@
 import type { Emitter } from "strict-event-emitter";
-import type { AFSStorage } from "./storage/type.js";
 export interface AFSListOptions {
     filter?: {
         userId?: string;
@@ -16,8 +15,7 @@ export interface AFSSearchOptions {
 export interface AFSWriteEntryPayload extends Omit<AFSEntry, "id" | "path"> {
 }
 export interface AFSModule {
-    readonly moduleId: string;
-    readonly path: string;
+    readonly name: string;
     readonly description?: string;
     onMount?(root: AFSRoot): void;
     list?(path: string, options?: AFSListOptions): Promise<{
@@ -36,6 +34,11 @@ export interface AFSModule {
         list: AFSEntry[];
         message?: string;
     }>;
+    exec?(path: string, args: Record<string, any>, options: {
+        context: any;
+    }): Promise<{
+        result: Record<string, any>;
+    }>;
 }
 export type AFSRootEvents = {
     agentSucceed: [{
@@ -47,7 +50,14 @@ export type AFSRootEvents = {
     }];
 };
 export interface AFSRoot extends Emitter<AFSRootEvents>, AFSModule {
-    storage(module: AFSModule): AFSStorage;
+}
+export interface AFSEntryMetadata extends Record<string, any> {
+    execute?: {
+        name: string;
+        description?: string;
+        inputSchema?: Record<string, any>;
+        outputSchema?: Record<string, any>;
+    };
 }
 export interface AFSEntry<T = any> {
     id: string;
@@ -57,7 +67,8 @@ export interface AFSEntry<T = any> {
     userId?: string | null;
     sessionId?: string | null;
     summary?: string | null;
-    metadata?: Record<string, any> | null;
+    description?: string | null;
+    metadata?: AFSEntryMetadata | null;
     linkTo?: string | null;
     content?: T;
 }

package/lib/dts/afs.d.ts

@@ -1,23 +1,18 @@
 import { Emitter } from "strict-event-emitter";
-import { SharedAFSStorage, type SharedAFSStorageOptions } from "./storage/index.js";
-import type { AFSStorage } from "./storage/type.js";
 import type { AFSEntry, AFSListOptions, AFSModule, AFSRoot, AFSRootEvents, AFSSearchOptions, AFSWriteEntryPayload } from "./type.js";
 export interface AFSOptions {
-    storage?: SharedAFSStorage | SharedAFSStorageOptions;
     modules?: AFSModule[];
 }
 export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
-    moduleId: string;
-    path: string;
+    name: string;
     constructor(options?: AFSOptions);
-    private _storage;
-    storage(module: AFSModule): AFSStorage;
     private modules;
-    use(module: AFSModule): this;
+    mount(module: AFSModule): this;
     listModules(): Promise<{
-        moduleId: string;
+        name: string;
         path: string;
         description?: string;
+        module: AFSModule;
     }[]>;
     list(path: string, options?: AFSListOptions): Promise<{
         list: AFSEntry[];
@@ -36,4 +31,9 @@ export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
         message?: string;
     }>;
     private findModules;
+    exec(path: string, args: Record<string, any>, options: {
+        context: any;
+    }): Promise<{
+        result: Record<string, any>;
+    }>;
 }

package/lib/dts/index.d.ts

@@ -1,4 +1,2 @@
 export * from "./afs.js";
-export * from "./history/index.js";
-export * from "./storage/index.js";
 export * from "./type.js";