feat: add a way to create/store/restore agents in the filesystem (#2389)

* Add a way to create/store/restore agents in the filesystem at agents/data/characters

* Update .env.example

---------

Co-authored-by: Sayo <hi@sayo.wtf>

Author: maxcoto

.env.example

@@ -18,6 +18,9 @@ SUPABASE_ANON_KEY=
 # Comma separated list of remote character urls (optional)
 REMOTE_CHARACTER_URLS=
 
+# Stores characters set by using the direct API in the data/character folder for further load when the app restarts
+USE_CHARACTER_STORAGE=false
+
 # Logging
 DEFAULT_LOG_LEVEL=warn
 LOG_JSON_FORMAT=false            # Print everything in logger as json; false by default
@@ -92,7 +95,7 @@ MEDIUM_OPENAI_MODEL=    # Default: gpt-4o
 LARGE_OPENAI_MODEL=     # Default: gpt-4o
 EMBEDDING_OPENAI_MODEL= # Default: text-embedding-3-small
 IMAGE_OPENAI_MODEL=     # Default: dall-e-3
-USE_OPENAI_EMBEDDING=   # Set to TRUE for OpenAI/1536, leave blank for local
+USE_OPENAI_EMBEDDING=TRUE   # Set to TRUE for OpenAI/1536, leave blank for local
 
 # Community Plugin for OpenAI Configuration
 ENABLE_OPEN_AI_COMMUNITY_PLUGIN=false

agent/src/index.ts

@@ -389,10 +389,31 @@ function commaSeparatedStringToArray(commaSeparated: string): string[] {
     return commaSeparated?.split(",").map((value) => value.trim());
 }
 
+async function readCharactersFromStorage(characterPaths: string[]): Promise<string[]> {
+    try {
+        const uploadDir = path.join(process.cwd(), "data", "characters");
+        await fs.promises.mkdir(uploadDir, { recursive: true });
+        const fileNames = await fs.promises.readdir(uploadDir);
+        fileNames.forEach(fileName => {
+            characterPaths.push(path.join(uploadDir, fileName));
+        });
+    } catch (err) {
+        elizaLogger.error(`Error reading directory: ${err.message}`);
+    }
+
+    return characterPaths;
+};
+
 export async function loadCharacters(
     charactersArg: string
 ): Promise<Character[]> {
-    const characterPaths = commaSeparatedStringToArray(charactersArg);
+
+    let characterPaths = commaSeparatedStringToArray(charactersArg);
+
+    if(process.env.USE_CHARACTER_STORAGE === "true") {
+        characterPaths = await readCharactersFromStorage(characterPaths);
+    }
+
     const loadedCharacters: Character[] = [];
 
     if (characterPaths?.length > 0) {
@@ -1248,7 +1269,9 @@ const startAgents = async () => {
         characters = await loadCharacterFromOnchain();
     }
 
-    if ((!onchainJson && charactersArg) || hasValidRemoteUrls()) {
+    const notOnchainJson = !onchainJson || onchainJson == "null";
+
+  if ((notOnchainJson && charactersArg) || hasValidRemoteUrls()) {
         characters = await loadCharacters(charactersArg);
     }
 

packages/client-direct/src/api.ts

@@ -1,6 +1,8 @@
 import express from "express";
 import bodyParser from "body-parser";
 import cors from "cors";
+import path from "path";
+import fs from "fs";
 
 import {
     type AgentRuntime,
@@ -80,6 +82,16 @@ export function createApiRouter(
         res.json({ agents: agentsList });
     });
 
+    router.get('/storage', async (req, res) => {
+        try {
+            const uploadDir = path.join(process.cwd(), "data", "characters");
+            const files = await fs.promises.readdir(uploadDir);
+            res.json({ files });
+        } catch (error) {
+            res.status(500).json({ error: error.message });
+        }
+    });
+
     router.get("/agents/:agentId", (req, res) => {
         const { agentId } = validateUUIDParams(req.params, res) ?? {
             agentId: null,
@@ -127,7 +139,7 @@ export function createApiRouter(
         };
         if (!agentId) return;
 
-        const agent: AgentRuntime = agents.get(agentId);
+        let agent: AgentRuntime = agents.get(agentId);
 
         // update character
         if (agent) {
@@ -137,6 +149,9 @@ export function createApiRouter(
             // if it has a different name, the agentId will change
         }
 
+        // stores the json data before it is modified with added data
+        const characterJson = { ...req.body };
+
         // load character from body
         const character = req.body;
         try {
@@ -152,7 +167,7 @@ export function createApiRouter(
 
         // start it up (and register it)
         try {
-            await directClient.startAgent(character);
+            agent = await directClient.startAgent(character);
             elizaLogger.log(`${character.name} started`);
         } catch (e) {
             elizaLogger.error(`Error starting agent: ${e}`);
@@ -162,6 +177,35 @@ export function createApiRouter(
             });
             return;
         }
+
+        if (process.env.USE_CHARACTER_STORAGE === "true") {
+            try {
+                const filename = `${agent.agentId}.json`;
+                const uploadDir = path.join(
+                    process.cwd(),
+                    "data",
+                    "characters"
+                );
+                const filepath = path.join(uploadDir, filename);
+                await fs.promises.mkdir(uploadDir, { recursive: true });
+                await fs.promises.writeFile(
+                    filepath,
+                    JSON.stringify(
+                        { ...characterJson, id: agent.agentId },
+                        null,
+                        2
+                    )
+                );
+                elizaLogger.info(
+                    `Character stored successfully at ${filepath}`
+                );
+            } catch (error) {
+                elizaLogger.error(
+                    `Failed to store character: ${error.message}`
+                );
+            }
+        }
+
         res.json({
             id: character.id,
             character: character,