Memory

This guide provides a step-by-step process for building a chatbot that remembers previous conversations. By following these instructions, you will create a stateful agent that uses the FSMemory plugin to persist session data, enabling continuous and context-aware interactions.

Overview#

This example demonstrates how to implement memory in a chatbot using the AIGNE Framework. The agent leverages the FSMemory plugin, which stores conversation history and user profile information on the local file system. This allows the chatbot to recall past interactions within a session, providing a more personalized and coherent user experience.

Prerequisites#

Before proceeding, ensure your development environment meets the following requirements:

• Node.js: Version 20.0 or higher.
• npm: Included with Node.js installation.
• OpenAI API Key: Required for connecting to OpenAI models. You can obtain a key from the OpenAI API keys page.

Quick Start#

You can run this example directly without a local installation using npx.

Run the Example#

Execute the following commands in your terminal to interact with the memory-enabled chatbot. The first command informs the bot of your preference, and the second command tests its ability to recall that information.

# Send the first message to establish a fact
npx -y @aigne/example-memory --input 'I like blue color'

# Send a second message to test the chatbot's memory
npx -y @aigne/example-memory --input 'What is my favorite color?'

To engage in a continuous conversation, run the chatbot in interactive mode:

npx -y @aigne/example-memory --chat

Connecting to an AI Model#

The chatbot requires a connection to a Large Language Model (LLM) to function. If you have not configured a model provider, the CLI will prompt you to choose a connection method upon the first run.

You have three primary options for connecting to an AI model:

1. Connect via the Official AIGNE Hub (Recommended)#

This is the simplest method. AIGNE Hub is a service that provides access to various models and includes free credits for new users.

1. Select the first option: Connect to the Arcblock official AIGNE Hub.
2. Your web browser will open to the AIGNE Hub authorization page.
3. Follow the on-screen instructions to approve the connection. New users will receive a complimentary grant of 400,000 tokens.

2. Connect via a Self-Hosted AIGNE Hub#

If your organization runs a private instance of AIGNE Hub, you can connect to it directly.

1. Select the second option: Connect to your self-hosted AIGNE Hub.
2. Enter the URL of your self-hosted AIGNE Hub instance when prompted.
3. Follow the subsequent prompts to complete the connection.

For instructions on deploying a self-hosted AIGNE Hub, refer to the Blocklet Store.

3. Connect via a Third-Party Model Provider#

You can connect directly to a third-party model provider, such as OpenAI, by configuring the appropriate API key as an environment variable.

For example, to connect to OpenAI, set the OPENAI_API_KEY environment variable:

export OPENAI_API_KEY="your-openai-api-key" # Replace with your actual key

After setting the environment variable, run the example again. For a list of supported providers and their corresponding environment variables, refer to the .env.local.example file.

How Memory Works#

The memory functionality is implemented using the history and UserProfileMemory modules, which are components of the AIGNE Framework's Augmented File System (AFS).

The following diagram illustrates how the chatbot records and retrieves information to maintain context across conversations.

Recording Conversations#

1. After the user sends a message and receives a response, the conversation pair (user input and AI output) is saved to the history module in AFS.
2. Simultaneously, the UserProfileMemory module analyzes the conversation history to extract and infer user profile details (e.g., name, preferences). This information is then stored in the user_profile module in AFS.

Retrieving Conversations#

When a new user message is received, the framework retrieves stored information to provide context to the AI model.

1. Load User Profile: The agent loads the data from UserProfileMemory and injects it into the system prompt. This ensures the AI is aware of the user's profile from the start.
   

   System Prompt with Memory

   You are a friendly chatbot
   
   <related-memories>
   - |
     name:
       - name: Bob
     interests:
       - content: likes blue color
   
   </related-memories>

2. Inject Conversation History: Recent conversation turns from the history module are appended to the message list, providing immediate conversational context.
   

   Chat Messages with History

   [
     {
       "role": "system",
       "content": "You are a friendly chatbot ..."
     },
     {
       "role": "user",
       "content": [
         {
           "type": "text",
           "text": "I'm Bob and I like blue color"
         }
       ]
     },
     {
       "role": "agent",
       "content": [
         {
           "type": "text",
           "text": "Nice to meet you, Bob! Blue is a great color.\n\nHow can I help you today?"
         }
       ]
     },
     {
       "role": "user",

   See all 8 lines

3. Generate Response: The AI model processes the complete context—including the system prompt with the user profile and the recent chat history—to generate an informed response.
   AI Response:
   
   You mentioned earlier that you like the color blue

Debugging#

To monitor and analyze agent behavior, you can use the aigne observe command. This tool starts a local web server that provides a user interface for inspecting execution traces, call details, and other runtime data.

1. Start the observation server:
   

   Start the AIGNE observer

   aigne observe

   
   
   
   
   
2. Open your browser and navigate to the local URL provided (typically http://localhost:7893) to view a list of recent agent executions and inspect their traces.
   
   
   
   

Summary#

This example has demonstrated the implementation of a chatbot with persistent memory using the AIGNE Framework. By leveraging the FSMemory plugin, the chatbot can record and retrieve conversation history and user profile information, leading to more context-aware and personalized interactions.

For more advanced memory persistence options, see the DID Spaces Memory example, which demonstrates using decentralized storage.