Skip to content

Agent Zero AI framework

refactor: migrate user data to usr/ + update frontend paths

linuztx10bc874f0518
diff --git a/initialize.py b/initialize.py
index ec26227fa..1ef2d0f88 100644
--- a/initialize.py
+++ b/initialize.py
@@ -140,6 +140,12 @@ def initialize_preload():
import preload
return defer.DeferredTask().start_task(preload.preload)
+def initialize_migration():
+ from python.helpers import migration
+ # run migration
+ migration.migrate_user_data()
+ # reload settings to ensure new paths are picked up
+ settings.reload_settings()
def _args_override(config):
# update config with runtime args
diff --git a/python/api/api_files_get.py b/python/api/api_files_get.py
index e021af60f..4d6dc2059 100644
--- a/python/api/api_files_get.py
+++ b/python/api/api_files_get.py
@@ -50,7 +50,7 @@ class ApiFilesGet(ApiHandler):
if path.startswith("/a0/tmp/uploads/"):
# Internal path - convert to external
filename = path.replace("/a0/tmp/uploads/", "")
- external_path = files.get_abs_path("tmp/uploads", filename)
+ external_path = files.get_abs_path("usr/uploads", filename)
filename = os.path.basename(external_path)
elif path.startswith("/a0/"):
# Other internal Agent Zero paths
diff --git a/python/api/api_message.py b/python/api/api_message.py
index 385d556dd..e3fd7e06b 100644
--- a/python/api/api_message.py
+++ b/python/api/api_message.py
@@ -40,8 +40,8 @@ class ApiMessage(ApiHandler):
# Handle attachments (base64 encoded)
attachment_paths = []
if attachments:
- upload_folder_int = "/a0/tmp/uploads"
- upload_folder_ext = files.get_abs_path("tmp/uploads")
+ upload_folder_int = "/a0/usr/uploads"
+ upload_folder_ext = files.get_abs_path("usr/uploads")
os.makedirs(upload_folder_ext, exist_ok=True)
for attachment in attachments:
diff --git a/python/api/message.py b/python/api/message.py
index bd378e4f7..e328b0660 100644
--- a/python/api/message.py
+++ b/python/api/message.py
@@ -29,8 +29,8 @@ class Message(ApiHandler):
attachments = request.files.getlist("attachments")
attachment_paths = []
- upload_folder_int = "/a0/tmp/uploads"
- upload_folder_ext = files.get_abs_path("tmp/uploads") # for development environment
+ upload_folder_int = "/a0/usr/uploads"
+ upload_folder_ext = files.get_abs_path("usr/uploads") # for development environment
if attachments:
os.makedirs(upload_folder_ext, exist_ok=True)
diff --git a/python/api/upload.py b/python/api/upload.py
index 4a596a577..14b656e04 100644
--- a/python/api/upload.py
+++ b/python/api/upload.py
@@ -14,7 +14,7 @@ class UploadFile(ApiHandler):
for file in file_list:
if file and self.allowed_file(file.filename): # Check file type
filename = secure_filename(file.filename) # type: ignore
- file.save(files.get_abs_path("tmp/upload", filename))
+ file.save(files.get_abs_path("usr/upload", filename))
saved_filenames.append(filename)
return {"filenames": saved_filenames} # Return saved filenames
diff --git a/python/helpers/backup.py b/python/helpers/backup.py
index 4e4873371..8ebc07033 100644
--- a/python/helpers/backup.py
+++ b/python/helpers/backup.py
@@ -60,28 +60,12 @@ class BackupService:
# Ensure paths don't have double slashes
agent_root = self.agent_zero_root.rstrip('/')
- return f"""# Agent Zero Knowledge (excluding defaults)
-{agent_root}/knowledge/**
-!{agent_root}/knowledge/default/**
-
-# Agent Zero Instruments (excluding defaults)
-{agent_root}/instruments/**
-!{agent_root}/instruments/default/**
-
-# Memory (excluding embeddings cache)
-{agent_root}/memory/**
-!{agent_root}/memory/**/embeddings/**
-
-# Configuration and Settings (CRITICAL)
-{agent_root}/.env
-{agent_root}/tmp/settings.json
-{agent_root}/tmp/secrets.env
-{agent_root}/tmp/chats/**
-{agent_root}/tmp/scheduler/**
-{agent_root}/tmp/uploads/**
-
-# User data
+ return f"""# User data
+# All persistent user data is now centralized in /usr for easier backup and restore
{agent_root}/usr/**
+
+# Explicitly include .env
+{agent_root}/usr/.env
"""
def _get_agent_zero_version(self) -> str:
diff --git a/python/helpers/dotenv.py b/python/helpers/dotenv.py
index 07ef0942b..3ce4d938f 100644
--- a/python/helpers/dotenv.py
+++ b/python/helpers/dotenv.py
@@ -15,7 +15,7 @@ def load_dotenv():
def get_dotenv_file_path():
- return get_abs_path(".env")
+ return get_abs_path("usr/.env")
def get_dotenv_value(key: str, default: Any = None):
# load_dotenv()
diff --git a/python/helpers/email_client.py b/python/helpers/email_client.py
index 741e00899..45e795ebe 100644
--- a/python/helpers/email_client.py
+++ b/python/helpers/email_client.py
@@ -537,7 +537,7 @@ async def read_messages(
port: int = 993,
username: str = "",
password: str = "",
- download_folder: str = "tmp/email",
+ download_folder: str = "usr/email",
options: Optional[Dict[str, Any]] = None,
filter: Optional[Dict[str, Any]] = None,
) -> List[Message]:
diff --git a/python/helpers/files.py b/python/helpers/files.py
index 0ed9cb06d..8fcf799c8 100644
--- a/python/helpers/files.py
+++ b/python/helpers/files.py
@@ -410,6 +410,10 @@ def move_dir(old_path: str, new_path: str):
abs_new = get_abs_path(new_path)
if not os.path.isdir(abs_old):
return # nothing to rename
+
+ # ensure parent directory exists
+ os.makedirs(os.path.dirname(abs_new), exist_ok=True)
+
try:
os.rename(abs_old, abs_new)
except Exception:
diff --git a/python/helpers/memory.py b/python/helpers/memory.py
index 8c8785c5a..d18af5453 100644
--- a/python/helpers/memory.py
+++ b/python/helpers/memory.py
@@ -139,7 +139,7 @@ class Memory:
log_item.stream(progress="\nInitializing VectorDB")
em_dir = files.get_abs_path(
- "memory/embeddings"
+ "tmp/memory/embeddings"
) # just caching, no need to parameterize
db_dir = abs_db_dir(memory_subdir)
@@ -333,6 +333,16 @@ class Memory:
recursive=True,
)
+ # load custom instruments descriptions
+ index = knowledge_import.load_knowledge(
+ log_item,
+ files.get_abs_path("usr/instruments"),
+ index,
+ {"area": Memory.Area.INSTRUMENTS.value},
+ filename_pattern="**/*.md",
+ recursive=True,
+ )
+
return index
def get_document_by_id(self, id: str) -> Document | None:
@@ -483,7 +493,7 @@ class Memory:
def get_custom_knowledge_subdir_abs(agent: Agent) -> str:
for dir in agent.config.knowledge_subdirs:
if dir != "default":
- return files.get_abs_path("knowledge", dir)
+ return files.get_abs_path("usr/knowledge", dir)
raise Exception("No custom knowledge subdir set")
@@ -499,7 +509,7 @@ def abs_db_dir(memory_subdir: str) -> str:
return files.get_abs_path(get_project_meta_folder(memory_subdir[9:]), "memory")
# standard subdirs
- return files.get_abs_path("memory", memory_subdir)
+ return files.get_abs_path("usr/memory", memory_subdir)
def abs_knowledge_dir(knowledge_subdir: str, *sub_dirs: str) -> str:
@@ -511,7 +521,9 @@ def abs_knowledge_dir(knowledge_subdir: str, *sub_dirs: str) -> str:
get_project_meta_folder(knowledge_subdir[9:]), "knowledge", *sub_dirs
)
# standard subdirs
- return files.get_abs_path("knowledge", knowledge_subdir, *sub_dirs)
+ if knowledge_subdir == "default":
+ return files.get_abs_path("knowledge", *sub_dirs)
+ return files.get_abs_path("usr/knowledge", knowledge_subdir, *sub_dirs)
def get_memory_subdir_abs(agent: Agent) -> str:
@@ -546,7 +558,7 @@ def get_existing_memory_subdirs() -> list[str]:
)
# Get subdirectories from memory folder
- subdirs = files.get_subdirectories("memory", exclude="embeddings")
+ subdirs = files.get_subdirectories("usr/memory")
project_subdirs = files.get_subdirectories(get_projects_parent_folder())
for project_subdir in project_subdirs:
diff --git a/python/helpers/migration.py b/python/helpers/migration.py
new file mode 100644
index 000000000..b49fe6ac4
--- /dev/null
+++ b/python/helpers/migration.py
@@ -0,0 +1,110 @@
+import os
+from python.helpers import files
+from python.helpers.print_style import PrintStyle
+
+def migrate_user_data() -> None:
+ """
+ Migrate user data from /tmp and other locations to /usr.
+ """
+
+ PrintStyle().print("Checking for data migration...")
+
+ # --- Migrate Directories -------------------------------------------------------
+ # Move directories from tmp/ or other source locations to usr/
+
+ _move_dir("tmp/chats", "usr/chats")
+ _move_dir("tmp/scheduler", "usr/scheduler")
+ _move_dir("tmp/uploads", "usr/uploads")
+ _move_dir("tmp/upload", "usr/upload")
+ _move_dir("tmp/downloads", "usr/downloads")
+ _move_dir("tmp/email", "usr/email")
+ _move_dir("knowledge/custom", "usr/knowledge")
+ _move_dir("instruments/custom", "usr/instruments")
+
+ # --- Migrate Files -------------------------------------------------------------
+ # Move specific configuration files to usr/
+
+ _move_file("tmp/settings.json", "usr/settings.json")
+ _move_file("tmp/secrets.env", "usr/secrets.env")
+ _move_file(".env", "usr/.env")
+
+ # --- Special Migration Cases ---------------------------------------------------
+
+ # Migrate Memory
+ _migrate_memory()
+
+ # Flatten default directories (knowledge/default -> knowledge/, etc.)
+ # We use _merge_dir_contents because we want to move the *contents* of default/
+ # into the parent directory, not move the default directory itself.
+ _merge_dir_contents("knowledge/default", "knowledge")
+ _merge_dir_contents("instruments/default", "instruments")
+
+ # --- Cleanup -------------------------------------------------------------------
+
+ # Remove obsolete directories after migration
+ _cleanup_obsolete()
+
+ PrintStyle().print("Migration check complete.")
+
+# --- Helper Functions ----------------------------------------------------------
+
+def _move_dir(src: str, dst: str) -> None:
+ """
+ Move a directory from src to dst if src exists and dst does not.
+ """
+ if files.exists(src) and not files.exists(dst):
+ PrintStyle().print(f"Migrating {src} to {dst}...")
+ files.move_dir(src, dst)
+
+def _move_file(src: str, dst: str) -> None:
+ """
+ Move a file from src to dst if src exists and dst does not.
+ """
+ if files.exists(src) and not files.exists(dst):
+ PrintStyle().print(f"Migrating {src} to {dst}...")
+ files.move_file(src, dst)
+
+def _migrate_memory(base_path: str = "memory") -> None:
+ """
+ Migrate memory subdirectories.
+ """
+ subdirs = files.get_subdirectories(base_path)
+ for subdir in subdirs:
+ if subdir == "embeddings":
+ # Special case: Embeddings
+ _move_dir("memory/embeddings", "tmp/memory/embeddings")
+ else:
+ # Move other memory items to usr/memory
+ dst = f"usr/memory/{subdir}"
+ _move_dir(f"memory/{subdir}", dst)
+
+def _merge_dir_contents(src_parent: str, dst_parent: str) -> None:
+ """
+ Moves all subdirectories from src_parent to dst_parent.
+ Useful for flattening structures like 'knowledge/default/*' -> 'knowledge/*'.
+ """
+ if not files.exists(src_parent):
+ return
+
+ # Iterate over subdirectories in the source parent
+ subdirs = files.get_subdirectories(src_parent)
+ for subdir in subdirs:
+ src = f"{src_parent}/{subdir}"
+ dst = f"{dst_parent}/{subdir}"
+
+ # Move the subdirectory if it doesn't exist in destination
+ _move_dir(src, dst)
+
+def _cleanup_obsolete() -> None:
+ """
+ Remove directories that are no longer needed.
+ """
+ to_remove = [
+ "knowledge/default",
+ "instruments/default",
+ "memory"
+ ]
+ for path in to_remove:
+ if files.exists(path):
+ PrintStyle().print(f"Removing {path}...")
+ files.delete_dir(path)
diff --git a/python/helpers/persist_chat.py b/python/helpers/persist_chat.py
index 55867e6fe..9cb708356 100644
--- a/python/helpers/persist_chat.py
+++ b/python/helpers/persist_chat.py
@@ -9,7 +9,7 @@ from initialize import initialize_agent
from python.helpers.log import Log, LogItem
-CHATS_FOLDER = "tmp/chats"
+CHATS_FOLDER = "usr/chats"
LOG_SIZE = 1000
CHAT_FILE_NAME = "chat.json"
diff --git a/python/helpers/secrets.py b/python/helpers/secrets.py
index 53ee85d9b..e87faca88 100644
--- a/python/helpers/secrets.py
+++ b/python/helpers/secrets.py
@@ -15,7 +15,7 @@ if TYPE_CHECKING:
# New alias-based placeholder format §§secret(KEY)
ALIAS_PATTERN = r"§§secret\(([A-Za-z_][A-Za-z0-9_]*)\)"
-DEFAULT_SECRETS_FILE = "tmp/secrets.env"
+DEFAULT_SECRETS_FILE = "usr/secrets.env"
def alias_for_key(key: str, placeholder: str = "§§secret({key})") -> str:
diff --git a/python/helpers/settings.py b/python/helpers/settings.py
index 9e71b7956..151c1f36b 100644
--- a/python/helpers/settings.py
+++ b/python/helpers/settings.py
@@ -161,7 +161,7 @@ class SettingsOutput(TypedDict):
PASSWORD_PLACEHOLDER = "****PSWD****"
API_KEY_PLACEHOLDER = "************"
-SETTINGS_FILE = files.get_abs_path("tmp/settings.json")
+SETTINGS_FILE = files.get_abs_path("usr/settings.json")
_settings: Settings | None = None
@@ -1343,6 +1343,12 @@ def get_settings() -> Settings:
return norm
+def reload_settings() -> Settings:
+ global _settings
+ _settings = None
+ return get_settings()
+
+
def set_settings(settings: Settings, apply: bool = True):
global _settings
previous = _settings
diff --git a/python/helpers/task_scheduler.py b/python/helpers/task_scheduler.py
index 5f9321754..f5c3ed0c2 100644
--- a/python/helpers/task_scheduler.py
+++ b/python/helpers/task_scheduler.py
@@ -26,7 +26,7 @@ from python.helpers import projects
import pytz
from typing import Annotated
-SCHEDULER_FOLDER = "tmp/scheduler"
+SCHEDULER_FOLDER = "usr/scheduler"
# ----------------------
# Task Models
diff --git a/python/tools/browser_agent.py b/python/tools/browser_agent.py
index 6d5f085b2..d9a53f822 100644
--- a/python/tools/browser_agent.py
+++ b/python/tools/browser_agent.py
@@ -56,7 +56,7 @@ class State:
disable_security=True,
chromium_sandbox=False,
accept_downloads=True,
- downloads_path=files.get_abs_path("tmp/downloads"),
+ downloads_path=files.get_abs_path("usr/downloads"),
allowed_domains=["*", "http://*", "https://*"],
executable_path=pw_binary,
keep_alive=True,
diff --git a/run_ui.py b/run_ui.py
index 1691f69e7..9872fbbb3 100644
--- a/run_ui.py
+++ b/run_ui.py
@@ -190,6 +190,9 @@ async def serve_index():
def run():
PrintStyle().print("Initializing framework...")
+ # migrate data before anything else
+ initialize.initialize_migration()
+
# Suppress only request logs but keep the startup messages
from werkzeug.serving import WSGIRequestHandler
from werkzeug.serving import make_server
diff --git a/webui/components/chat/attachments/attachmentsStore.js b/webui/components/chat/attachments/attachmentsStore.js
index 7e17b9b55..08b7815fd 100644
--- a/webui/components/chat/attachments/attachmentsStore.js
+++ b/webui/components/chat/attachments/attachmentsStore.js
@@ -259,11 +259,11 @@ const model = {
// Generate server-side API URL for file (for device sync)
getServerImgUrl(filename) {
- return `/image_get?path=/a0/tmp/uploads/${encodeURIComponent(filename)}`;
+ return `/image_get?path=/a0/usr/uploads/${encodeURIComponent(filename)}`;
},
getServerFileUrl(filename) {
- return `/a0/tmp/uploads/${encodeURIComponent(filename)}`;
+ return `/a0/usr/uploads/${encodeURIComponent(filename)}`;
},
// Check if file is an image based on extension
diff --git a/webui/components/settings/external/api-examples.html b/webui/components/settings/external/api-examples.html
index 08569a1e9..f0a2ce7f6 100644
--- a/webui/components/settings/external/api-examples.html
+++ b/webui/components/settings/external/api-examples.html
@@ -146,7 +146,7 @@
<div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 0 0 20px 0;">
<p style="margin: 0 0 8px 0; color: var(--color-text-secondary); font-size: 14px;">
<strong>Parameters:</strong><br>
- • <code>paths</code> (array, required): Array of file paths to retrieve (e.g., ["/a0/tmp/uploads/file.txt"])
+ • <code>paths</code> (array, required): Array of file paths to retrieve (e.g., ["/a0/usr/uploads/file.txt"])
</p>
<p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">
<strong>Headers:</strong> <code>X-API-KEY</code> (required), <code>Content-Type: application/json</code>
@@ -562,8 +562,8 @@ async function getFiles(filePaths) {
// Example 1: Get specific files
const filePaths = [
- "/a0/tmp/uploads/document.txt",
- "/a0/tmp/uploads/data.json"
+ "/a0/usr/uploads/document.txt",
+ "/a0/usr/uploads/data.json"
];
getFiles(filePaths);
@@ -590,7 +590,7 @@ async function attachmentWorkflow() {
console.log('Message sent with attachment');
// Step 2: Retrieve the uploaded file
- const retrievedFiles = await getFiles(["/a0/tmp/uploads/test.txt"]);
+ const retrievedFiles = await getFiles(["/a0/usr/uploads/test.txt"]);
if (retrievedFiles && retrievedFiles["test.txt"]) {
const originalContent = atob(retrievedFiles["test.txt"]);