@aigne/example-afs-memory 0.10.70-beta

package/.env.local.example

@@ -0,0 +1,44 @@
+# Change the name of this file to .env.local and fill in the following values
+
+# Uncomment the lines below to enable debug logging
+# DEBUG="aigne:*"
+
+# Use different Models
+
+# OpenAI
+MODEL="openai:gpt-4.1"
+OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
+
+# Anthropic claude
+# MODEL="anthropic:claude-3-7-sonnet-latest"
+# ANTHROPIC_API_KEY=""
+
+# Gemini
+# MODEL="gemini:gemini-2.0-flash"
+# GEMINI_API_KEY=""
+
+# Bedrock nova
+# MODEL=bedrock:us.amazon.nova-premier-v1:0
+# AWS_ACCESS_KEY_ID=""
+# AWS_SECRET_ACCESS_KEY=""
+# AWS_REGION=us-west-2
+
+# DeepSeek
+# MODEL="deepseek:deepseek-chat"
+# DEEPSEEK_API_KEY=""
+
+# OpenRouter
+# MODEL="openrouter:openai/gpt-4o"
+# OPEN_ROUTER_API_KEY=""
+
+# xAI
+# MODEL="xai:grok-2-latest"
+# XAI_API_KEY=""
+
+# Ollama
+# MODEL="ollama:llama3.2"
+# OLLAMA_DEFAULT_BASE_URL="http://localhost:11434/v1";
+
+
+# Setup proxy if needed
+# HTTPS_PROXY=http://localhost:7890

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,242 @@
+# Memory Example
+
+<p align="center">
+  <picture>
+    <source srcset="https://raw.githubusercontent.com/AIGNE-io/aigne-framework/main/logo-dark.svg" media="(prefers-color-scheme: dark)">
+    <source srcset="https://raw.githubusercontent.com/AIGNE-io/aigne-framework/main/logo.svg" media="(prefers-color-scheme: light)">
+    <img src="https://raw.githubusercontent.com/AIGNE-io/aigne-framework/main/logo.svg" alt="AIGNE Logo" width="400" />
+  </picture>
+</p>
+
+This example demonstrates how to create a chatbot with **long-term memory** using the [AIGNE Framework](https://github.com/AIGNE-io/aigne-framework). The chatbot can remember user information across conversations and recall details shared in previous interactions.
+
+The example uses two powerful AFS (Agentic File System) modules:
+- **AFSHistory**: Automatically records all conversations for context
+- **UserProfileMemory**: Intelligently extracts and stores user information (name, interests, location, etc.)
+
+**Agentic File System (AFS)** is a virtual file system abstraction that provides AI agents with unified access to various storage backends. For comprehensive documentation, see [AFS Documentation](../../afs/README.md).
+
+## Prerequisites
+
+* [Node.js](https://nodejs.org) (>=20.0) and npm installed on your machine
+* An [OpenAI API key](https://platform.openai.com/api-keys) for interacting with OpenAI's services
+* Optional dependencies (if running the example from source code):
+  * [Pnpm](https://pnpm.io) for package management
+  * [Bun](https://bun.sh) for running unit tests & examples
+
+## Quick Start (No Installation Required)
+
+```bash
+export OPENAI_API_KEY=YOUR_OPENAI_API_KEY # Set your OpenAI API key
+
+# First conversation - introduce yourself
+npx -y @aigne/example-afs-memory --input "I'm Bob, and I like blue color"
+# Response: Nice to meet you, Bob — I've saved that your favorite color is blue...
+
+# Second conversation - the bot remembers you!
+npx -y @aigne/example-afs-memory --input "Tell me all info about me you known"
+# Response: Here's what I currently have stored about you:
+#   * Name: Bob
+#   * Interests / favorite color: blue
+
+# Run in interactive chat mode
+npx -y @aigne/example-afs-memory --chat
+```
+
+## Installation
+
+### Clone the Repository
+
+```bash
+git clone https://github.com/AIGNE-io/aigne-framework
+```
+
+### Install Dependencies
+
+```bash
+cd aigne-framework/examples/afs-memory
+
+pnpm install
+```
+
+### Setup Environment Variables
+
+Setup your OpenAI API key in the `.env.local` file:
+
+```bash
+OPENAI_API_KEY="" # Set your OpenAI API key here
+```
+
+#### Using Different Models
+
+You can use different AI models by setting the `MODEL` environment variable along with the corresponding API key. The framework supports multiple providers:
+
+* **OpenAI**: `MODEL="openai:gpt-4.1"` with `OPENAI_API_KEY`
+* **Anthropic**: `MODEL="anthropic:claude-3-7-sonnet-latest"` with `ANTHROPIC_API_KEY`
+* **Google Gemini**: `MODEL="gemini:gemini-2.0-flash"` with `GEMINI_API_KEY`
+* **AWS Bedrock**: `MODEL="bedrock:us.amazon.nova-premier-v1:0"` with AWS credentials
+* **DeepSeek**: `MODEL="deepseek:deepseek-chat"` with `DEEPSEEK_API_KEY`
+* **OpenRouter**: `MODEL="openrouter:openai/gpt-4o"` with `OPEN_ROUTER_API_KEY`
+* **xAI**: `MODEL="xai:grok-2-latest"` with `XAI_API_KEY`
+* **Ollama**: `MODEL="ollama:llama3.2"` with `OLLAMA_DEFAULT_BASE_URL`
+
+For detailed configuration examples, please refer to the `.env.local.example` file in this directory.
+
+### Run the Example
+
+```bash
+# Run in interactive mode
+pnpm start
+
+# Run with a single message
+pnpm start --input "I'm Bob, and I like blue color"
+```
+
+### Example Conversation Flow
+
+```bash
+# First conversation - introduce yourself
+$ pnpm start --input "I'm Bob, and I like blue color"
+Response: Nice to meet you, Bob — I've saved that your favorite color is blue.
+If you'd like, I can remember more about you (location, hobbies, projects, etc.)...
+
+# Second conversation - the bot remembers you!
+$ pnpm start --input "Tell me all info about me you known"
+Response: Here's what I currently have stored about you:
+  * Name: Bob
+  * Interests / favorite color: blue
+
+Would you like to add or update anything (location, hobbies, projects, family, etc.)?
+```
+
+## How Memory Works
+
+This example uses two complementary memory modules that work together to provide intelligent, personalized conversations:
+
+### 1. AFSHistory Module - Conversation Context
+
+**Purpose**: Records every conversation turn to provide recent context.
+
+**How it works**:
+- Automatically saves each user message and AI response pair
+- Stores conversations with timestamps and unique IDs
+- Enables the AI to reference recent conversations
+
+**Example**:
+```bash
+# First conversation
+$ pnpm start --input "I'm Bob, and I like blue color"
+Response: Nice to meet you, Bob — I've saved that your favorite color is blue...
+
+# The conversation is automatically saved to /history/{uuid}
+```
+
+### 2. UserProfileMemory Module - User Information Extraction
+
+**Purpose**: Intelligently extracts and stores structured user information from conversations.
+
+**How it works**:
+1. **Listens** to conversation history events
+2. **Analyzes** each conversation using AI to identify user information
+3. **Extracts** relevant details (name, interests, location, family, projects, etc.)
+4. **Stores** in a structured JSON profile at `/user-profile-memory`
+5. **Updates** incrementally using JSON Patch operations
+
+**What it remembers**:
+- Name and personal details
+- Location (country, city, address)
+- Interests and hobbies
+- Family members and relationships
+- Projects and work
+- Languages spoken
+- Birthday and other personal info
+
+**Example**:
+```bash
+# After Bob introduces himself, the profile is automatically created:
+{
+  "name": [{ "name": "Bob" }],
+  "interests": [{ "content": "blue color" }]
+}
+
+# In the next conversation, the bot can recall this information:
+$ pnpm start --input "Tell me all info about me you known"
+Response: Here's what I currently have stored about you:
+  * Name: Bob
+  * Interests / favorite color: blue
+```
+
+### 3. Memory Injection - How the AI Uses Memory
+
+When you send a message, the system automatically:
+
+**Step 1: Inject User Profile into System Prompt**
+```text
+You are a friendly chatbot
+
+<related-memories>
+User Profile Memory: This contains structured information about the user...
+
+- name:
+    - name: Bob
+  interests:
+    - content: blue color
+</related-memories>
+```
+
+**Step 2: Add Recent Conversation History**
+```json
+[
+  {
+    "role": "system",
+    "content": "You are a friendly chatbot... [profile injected here]"
+  },
+  {
+    "role": "user",
+    "content": "I'm Bob and I like blue color"
+  },
+  {
+    "role": "assistant",
+    "content": "Nice to meet you, Bob..."
+  },
+  {
+    "role": "user",
+    "content": "Tell me all info about me you known"
+  }
+]
+```
+
+**Step 3: AI Generates Personalized Response**
+
+The AI can now:
+- Address the user by name
+- Reference their interests
+- Provide personalized recommendations
+- Maintain context across sessions
+
+### Key Design Benefits
+
+1. **Automatic**: No manual profile management needed
+2. **Intelligent**: AI determines what's important to remember
+3. **Incremental**: Profile updates gradually over time
+4. **Persistent**: Memory survives across multiple conversations
+5. **Structured**: Information is organized in a consistent format
+6. **Privacy-Aware**: All data stored locally in SQLite
+
+## Related Examples
+
+- [AFS LocalFS Example](../afs-local-fs/README.md) - File system access with AI agents
+- [AFS MCP Server Example](../afs-mcp-server/README.md) - Mount MCP servers as AFS modules
+
+## Related Packages
+
+- [@aigne/afs](../../afs/README.md) - AFS core package
+- [@aigne/afs-user-profile-memory](../../afs/user-profile-memory/README.md) - User profile memory module
+
+## TypeScript Support
+
+This package includes full TypeScript type definitions.
+
+## License
+
+[MIT](../../LICENSE.md)

package/index.test.ts

@@ -0,0 +1,11 @@
+import { expect, test } from "bun:test";
+import { runExampleTest } from "@aigne/test-utils/run-example-test.js";
+
+test(
+  "should successfully run the chatbot",
+  async () => {
+    const { status } = await runExampleTest();
+    expect(status).toBe(0);
+  },
+  { timeout: 600000 },
+);

package/index.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env npx -y bun
+
+import { AFS } from "@aigne/afs";
+import { AFSHistory } from "@aigne/afs-history";
+import { UserProfileMemory } from "@aigne/afs-user-profile-memory";
+import { loadAIGNEWithCmdOptions, runWithAIGNE } from "@aigne/cli/utils/run-with-aigne.js";
+import { AIAgent } from "@aigne/core";
+
+const aigne = await loadAIGNEWithCmdOptions();
+
+const sharedStorage = { url: "file:./memory.sqlite3" };
+
+const afs = new AFS()
+  .mount(new AFSHistory({ storage: sharedStorage }))
+  .mount(new UserProfileMemory({ storage: sharedStorage, context: aigne.newContext() }));
+
+const agent = AIAgent.from({
+  instructions: "You are a friendly chatbot",
+  inputKey: "message",
+  afs,
+});
+
+await runWithAIGNE(agent, {
+  aigne,
+  chatLoopOptions: {
+    welcome: "Hello! I'm a chatbot with memory. Try asking me a question!",
+  },
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@aigne/example-afs-memory",
+  "version": "0.10.70-beta",
+  "description": "A demonstration of using AIGNE Framework with memory-based AFS modules",
+  "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
+  "homepage": "https://github.com/AIGNE-io/aigne-framework/tree/main/examples/afs-memory",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AIGNE-io/aigne-framework"
+  },
+  "bin": "index.ts",
+  "files": [
+    ".env.local.example",
+    "*.ts",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aigne/afs": "^1.2.0-beta",
+    "@aigne/afs-history": "^1.0.0",
+    "@aigne/afs-user-profile-memory": "^1.1.0-beta",
+    "@aigne/cli": "^1.55.0-beta",
+    "@aigne/core": "^1.68.0-beta"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.22",
+    "@aigne/test-utils": "^0.5.60-beta"
+  },
+  "scripts": {
+    "start": "bun run index.ts",
+    "lint": "tsc --noEmit",
+    "test:llm": "bun test index.test.ts"
+  }
+}