@aigne/afs-history 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 1.0.0 (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))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs bumped to 1.2.0-beta

package/LICENSE.md

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,396 @@
+# @aigne/afs-history
+
+**@aigne/afs-history** is a history tracking module for the Agentic File System (AFS). It automatically records conversation history and agent interactions, storing them in a persistent SQLite database.
+
+## Overview
+
+AFSHistory is an AFS module that listens to agent events and automatically records conversation history. Each conversation is stored with a unique identifier, making it easy to retrieve and review past interactions.
+
+## Features
+
+- **Automatic Recording**: Listens to `agentSucceed` events and automatically stores conversation history
+- **SQLite Storage**: Uses SQLite database for persistent, structured storage
+- **UUID-based Paths**: Each conversation is stored with a UUID v7 path for easy retrieval
+- **Event Integration**: Emits `historyCreated` events when new history entries are recorded
+- **Full CRUD Support**: Supports list, read, and write operations
+- **Shared Storage**: Can share storage with other AFS modules using `SharedAFSStorage`
+
+## Installation
+
+```bash
+npm install @aigne/afs-history
+# or
+yarn add @aigne/afs-history
+# or
+pnpm add @aigne/afs-history
+```
+
+## Quick Start
+
+```typescript
+import { AFS } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
+
+// Create AFS instance
+const afs = new AFS();
+
+// Mount history module
+afs.mount(new AFSHistory({
+  storage: { url: "file:./memory.sqlite3" }
+}));
+
+// History entries are now accessible at /modules/history
+const { list } = await afs.list('/modules/history');
+console.log(list); // Array of conversation history entries
+```
+
+## Configuration
+
+### AFSHistoryOptions
+
+```typescript
+interface AFSHistoryOptions {
+  storage?: SharedAFSStorage | SharedAFSStorageOptions;
+}
+```
+
+#### Storage Options
+
+```typescript
+interface SharedAFSStorageOptions {
+  url?: string;  // Database URL (default: ":memory:")
+}
+```
+
+**Examples:**
+
+```typescript
+// In-memory database (default)
+new AFSHistory()
+
+// File-based database
+new AFSHistory({
+  storage: { url: "file:./memory.sqlite3" }
+})
+
+// Shared storage instance
+const sharedStorage = new SharedAFSStorage({ url: "file:./memory.sqlite3" });
+new AFSHistory({ storage: sharedStorage })
+```
+
+## API Reference
+
+### AFSHistory Class
+
+#### Constructor
+
+```typescript
+new AFSHistory(options?: AFSHistoryOptions)
+```
+
+#### Properties
+
+- `name`: `string` - Module name (always `"history"`)
+
+#### Methods
+
+##### list(path: string, options?: AFSListOptions)
+
+List history entries:
+
+```typescript
+const { list } = await afs.list('/modules/history');
+
+// With options
+const { list } = await afs.list('/modules/history', {
+  maxDepth: 1,
+  limit: 10,
+  offset: 0
+});
+```
+
+**Returns:** `Promise<{ list: AFSEntry[] }>`
+
+**Note:** Only root path `/` is supported. Subdirectories return empty arrays.
+
+##### read(path: string)
+
+Read a specific history entry:
+
+```typescript
+const { result } = await afs.read('/modules/history/01933e4e-7c8f-7000-8000-123456789abc');
+
+if (result) {
+  console.log(result.content.input);   // Original input
+  console.log(result.content.output);  // Agent's output
+  console.log(result.createdAt);       // Timestamp
+}
+```
+
+**Returns:** `Promise<{ result?: AFSEntry; message?: string }>`
+
+##### write(path: string, content: AFSWriteEntryPayload)
+
+Manually create a history entry:
+
+```typescript
+const { result } = await afs.write('/modules/history/custom-id', {
+  content: {
+    input: "User question",
+    output: "Agent response"
+  },
+  summary: "Conversation summary",
+  metadata: { tags: ["important"] }
+});
+```
+
+**Returns:** `Promise<{ result: AFSEntry; message?: string }>`
+
+#### Lifecycle
+
+##### onMount(afs: AFSRoot)
+
+Called when the module is mounted. Sets up event listeners:
+
+```typescript
+onMount(afs: AFSRoot) {
+  afs.on('agentSucceed', ({ input, output }) => {
+    // Automatically stores history
+  });
+}
+```
+
+## Data Structure
+
+### AFSEntry Format
+
+History entries follow the standard AFSEntry structure:
+
+```typescript
+interface AFSEntry {
+  id: string;                          // UUID v7
+  path: string;                        // Full path in AFS (e.g., "/modules/history/01933e4e...")
+  content: {
+    input: string | object;            // Original input to agent
+    output: string | object;           // Agent's output
+  };
+  summary?: string;                    // Optional summary
+  metadata?: Record<string, any>;      // Custom metadata
+  createdAt: Date;                     // Creation timestamp
+  updatedAt: Date;                     // Last update timestamp
+  userId?: string;                     // Associated user (if available)
+  sessionId?: string;                  // Associated session (if available)
+  linkTo?: string;                     // Link to another entry
+}
+```
+
+### Database Schema
+
+History entries are stored in SQLite with the following schema:
+
+```sql
+CREATE TABLE Entries_history (
+  "id" TEXT NOT NULL PRIMARY KEY,
+  "createdAt" DATETIME NOT NULL,
+  "updatedAt" DATETIME NOT NULL,
+  "path" TEXT NOT NULL UNIQUE,
+  "userId" TEXT,
+  "sessionId" TEXT,
+  "summary" TEXT,
+  "metadata" JSON,
+  "linkTo" TEXT,
+  "content" JSON
+)
+```
+
+## Events
+
+### Listening to Events
+
+AFSHistory listens to these events from the AFS root:
+
+- `agentSucceed`: Triggered when an agent successfully completes. Automatically creates a history entry.
+
+### Emitting Events
+
+AFSHistory emits these events:
+
+- `historyCreated`: Emitted after a history entry is successfully created
+
+**Example:**
+
+```typescript
+afs.on('historyCreated', ({ entry }) => {
+  console.log('New history entry:', entry.id);
+  console.log('Input:', entry.content.input);
+  console.log('Output:', entry.content.output);
+});
+```
+
+## Usage with AI Agents
+
+When AFS is configured with an AI agent, history tracking happens automatically:
+
+```typescript
+import { AIGNE, AIAgent } from "@aigne/core";
+import { AFS } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
+import { OpenAIChatModel } from "@aigne/openai";
+
+// Create AIGNE instance
+const aigne = new AIGNE({
+  model: new OpenAIChatModel({ apiKey: process.env.OPENAI_API_KEY })
+});
+
+// Create AFS with history
+const afs = new AFS();
+afs.mount(new AFSHistory({
+  storage: { url: "file:./memory.sqlite3" }
+}));
+
+// Create agent
+const agent = AIAgent.from({
+  name: "assistant",
+  instructions: "You are a helpful assistant",
+  afs
+});
+
+// Use the agent - history is automatically tracked
+const context = aigne.newContext();
+const result = await context.invoke(agent, {
+  message: "Hello, how are you?"
+});
+
+// View history
+const { list } = await afs.list('/modules/history');
+console.log(`Total conversations: ${list.length}`);
+```
+
+## Advanced Usage
+
+### Shared Storage
+
+Share storage between multiple AFS modules:
+
+```typescript
+import { SharedAFSStorage } from "@aigne/afs-history";
+
+const storage = new SharedAFSStorage({
+  url: "file:./shared-memory.sqlite3"
+});
+
+const history = new AFSHistory({ storage });
+const customModule = new CustomModule({ storage });
+
+afs.mount(history);
+afs.mount(customModule);
+```
+
+### Custom Event Handling
+
+React to history creation:
+
+```typescript
+afs.on('historyCreated', async ({ entry }) => {
+  // Custom processing
+  console.log(`Stored conversation ${entry.id}`);
+
+  // Update external analytics
+  await analytics.track('conversation_stored', {
+    entryId: entry.id,
+    timestamp: entry.createdAt
+  });
+});
+```
+
+### Manual History Recording
+
+Manually record history without agent events:
+
+```typescript
+const { result } = await afs.write('/modules/history/manual-entry', {
+  content: {
+    input: "Manual input",
+    output: "Manual output"
+  },
+  summary: "Manually recorded conversation",
+  metadata: {
+    source: "manual",
+    tags: ["important", "review"]
+  },
+  userId: "user-123",
+  sessionId: "session-456"
+});
+```
+
+### Searching History
+
+If your storage implementation supports search:
+
+```typescript
+const { list } = await afs.search('/modules/history', 'authentication error');
+
+for (const entry of list) {
+  console.log(`Found in ${entry.id}:`, entry.content);
+}
+```
+
+## Migration from @aigne/afs
+
+If you were previously using AFSHistory from `@aigne/afs`, update your imports:
+
+**Before:**
+```typescript
+import { AFS, AFSHistory } from "@aigne/afs";
+```
+
+**After:**
+```typescript
+import { AFS } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
+```
+
+No other changes are required - the API remains identical.
+
+## TypeScript Support
+
+This package includes full TypeScript type definitions:
+
+```typescript
+import type {
+  AFSHistory,
+  AFSHistoryOptions,
+  AFSStorage,
+  SharedAFSStorage,
+  SharedAFSStorageOptions,
+  AFSStorageWithModule,
+  AFSStorageCreatePayload,
+  AFSStorageListOptions
+} from "@aigne/afs-history";
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Run tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+```
+
+## License
+
+[Elastic-2.0](../../LICENSE.md)
+
+## Related Packages
+
+- [@aigne/afs](../core/README.md) - Core AFS implementation
+- [@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
+
+See the [AFS examples](../../examples/afs-memory/README.md) for more usage examples.

package/lib/cjs/index.d.ts

@@ -0,0 +1,23 @@
+import type { AFSEntry, AFSListOptions, AFSModule, AFSRoot, AFSWriteEntryPayload } from "@aigne/afs";
+import { SharedAFSStorage, type SharedAFSStorageOptions } from "./storage/index.js";
+export * from "./storage/index.js";
+export interface AFSHistoryOptions {
+    storage?: SharedAFSStorage | SharedAFSStorageOptions;
+}
+export declare class AFSHistory implements AFSModule {
+    constructor(options?: AFSHistoryOptions);
+    private storage;
+    readonly name: string;
+    onMount(afs: AFSRoot): void;
+    list(path: string, options?: AFSListOptions): Promise<{
+        list: AFSEntry[];
+    }>;
+    read(path: string): Promise<{
+        result: AFSEntry | undefined;
+        message?: string;
+    }>;
+    write(path: string, content: AFSWriteEntryPayload): Promise<{
+        result: AFSEntry;
+        message?: string;
+    }>;
+}

package/lib/cjs/index.js

@@ -0,0 +1,60 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AFSHistory = void 0;
+const uuid_1 = require("@aigne/uuid");
+const ufo_1 = require("ufo");
+const index_js_1 = require("./storage/index.js");
+__exportStar(require("./storage/index.js"), exports);
+class AFSHistory {
+    constructor(options) {
+        this.storage =
+            options?.storage instanceof index_js_1.SharedAFSStorage
+                ? options.storage.withModule(this)
+                : new index_js_1.SharedAFSStorage(options?.storage).withModule(this);
+    }
+    storage;
+    name = "history";
+    onMount(afs) {
+        afs.on("agentSucceed", ({ input, output }) => {
+            this.storage
+                .create({
+                path: (0, ufo_1.joinURL)("/", (0, uuid_1.v7)()),
+                content: { input, output },
+            })
+                .then((entry) => {
+                afs.emit("historyCreated", { entry });
+            })
+                .catch((error) => {
+                console.error("Failed to store history entry", error);
+            });
+        });
+    }
+    async list(path, options) {
+        if (path !== "/")
+            return { list: [] };
+        return await this.storage.list(options);
+    }
+    async read(path) {
+        const result = await this.storage.read(path);
+        return { result };
+    }
+    async write(path, content) {
+        const result = await this.storage.create({ ...content, path });
+        return { result };
+    }
+}
+exports.AFSHistory = AFSHistory;

package/lib/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/lib/cjs/storage/index.d.ts

@@ -0,0 +1,25 @@
+import type { AFSEntry, AFSModule } from "@aigne/afs";
+import { initDatabase } from "@aigne/sqlite";
+import { entriesTable } from "./models/entries.js";
+import type { AFSStorage, AFSStorageCreatePayload, AFSStorageListOptions } from "./type.js";
+export * from "./type.js";
+export interface SharedAFSStorageOptions {
+    url?: string;
+}
+export declare class SharedAFSStorage {
+    options?: SharedAFSStorageOptions | undefined;
+    constructor(options?: SharedAFSStorageOptions | undefined);
+    private _db;
+    get db(): Promise<import("drizzle-orm/libsql/driver-core.js").LibSQLDatabase<Record<string, never>> | import("drizzle-orm/sqlite-proxy/driver.js").SqliteRemoteDatabase<Record<string, never>>>;
+    withModule(module: AFSModule): AFSStorage;
+}
+export declare class AFSStorageWithModule implements AFSStorage {
+    private db;
+    private table;
+    constructor(db: ReturnType<typeof initDatabase>, table: Promise<ReturnType<typeof entriesTable>>);
+    list(options?: AFSStorageListOptions): Promise<{
+        list: AFSEntry[];
+    }>;
+    read(path: string): Promise<AFSEntry | undefined>;
+    create(entry: AFSStorageCreatePayload): Promise<AFSEntry>;
+}

package/lib/cjs/storage/index.js

@@ -0,0 +1,87 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AFSStorageWithModule = exports.SharedAFSStorage = void 0;
+const sqlite_1 = require("@aigne/sqlite");
+const migrate_js_1 = require("./migrate.js");
+const entries_js_1 = require("./models/entries.js");
+__exportStar(require("./type.js"), exports);
+const DEFAULT_AFS_STORAGE_LIST_LIMIT = 10;
+class SharedAFSStorage {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    _db;
+    get db() {
+        this._db ??= (0, sqlite_1.initDatabase)({ url: this.options?.url });
+        return this._db;
+    }
+    withModule(module) {
+        return new AFSStorageWithModule(this.db, (0, migrate_js_1.migrate)(this.db, module).then(() => (0, entries_js_1.entriesTable)(module)));
+    }
+}
+exports.SharedAFSStorage = SharedAFSStorage;
+class AFSStorageWithModule {
+    db;
+    table;
+    constructor(db, table) {
+        this.db = db;
+        this.table = table;
+    }
+    async list(options = {}) {
+        const { filter, limit = DEFAULT_AFS_STORAGE_LIST_LIMIT } = options;
+        const db = await this.db;
+        const table = await this.table;
+        const list = await db
+            .select()
+            .from(table)
+            .where((0, sqlite_1.and)(filter?.userId ? (0, sqlite_1.eq)(table.userId, filter.userId) : undefined, filter?.sessionId ? (0, sqlite_1.eq)(table.sessionId, filter.sessionId) : undefined))
+            .orderBy(...(options.orderBy ?? []).map((item) => (item[1] === "asc" ? sqlite_1.asc : sqlite_1.desc)(sqlite_1.sql.identifier(item[0]))))
+            .limit(limit)
+            .execute();
+        return { list };
+    }
+    async read(path) {
+        const db = await this.db;
+        const table = await this.table;
+        return db
+            .select()
+            .from(table)
+            .where((0, sqlite_1.eq)(table.path, path))
+            .limit(1)
+            .execute()
+            .then((memory) => memory.at(0));
+    }
+    async create(entry) {
+        const db = await this.db;
+        const table = await this.table;
+        let result = await db
+            .update(table)
+            .set(entry)
+            .where((0, sqlite_1.eq)(table.path, entry.path))
+            .returning()
+            .execute();
+        if (!result.length) {
+            result = await db.insert(table).values(entry).returning().execute();
+        }
+        const [res] = result;
+        if (!res)
+            throw new Error("Failed to create AFS entry, no result");
+        return res;
+    }
+}
+exports.AFSStorageWithModule = AFSStorageWithModule;