Managing Projects

Relevant source files

• agent.py
• initialize.py
• models.py
• python/helpers/guids.py
• python/helpers/memory.py
• python/helpers/settings.py
• python/tools/browser_agent.py
• requirements.txt
• run_ui.py
• webui/components/chat/input/bottom-actions.html
• webui/components/sidebar/top-section/header-icons.html
• webui/components/sidebar/top-section/quick-actions.html
• webui/css/modals.css
• webui/css/settings.css
• webui/css/toast.css
• webui/js/modals.js

Purpose and Scope

This page documents how to create, configure, activate, and manage projects in Agent Zero. Projects provide isolated workspaces with dedicated memory, knowledge, skills, and secrets, enabling clean separation between different tasks, clients, or contexts.

For information about the project directory structure and isolation mechanisms, see Project Structure. For details on project-specific variables and secrets, see Variables and Secrets. For memory and knowledge isolation, see Project Isolation.

---

Project Management Overview

Projects in Agent Zero provide workspace isolation through a naming convention that affects how memory, knowledge, skills, and secrets are resolved. When a project is active, the system uses path prefixes like "projects/{project_name}" to route file system operations to project-specific directories.

The project system is implemented through:

• Path resolution functions in python/helpers/memory.py that detect "projects/" prefix
• Project helper module (python/helpers/projects.py) for context and metadata management
• Frontend project store accessible via $store.projects in the Web UI
• Backend API handlers for project CRUD operations

Project Storage Architecture

Sources: python/helpers/memory.py486-509 python/helpers/memory.py522-529

---

Creating Projects

Via Web UI

The Web UI provides a project management modal accessible from the sidebar quick actions dropdown:

1. Click the dropdown toggle button (expand_more icon) in the quick actions toolbar
2. Select Projects from the dropdown menu
3. In the projects modal, click Create New Project
4. Fill in the project configuration form
5. Click Create to initialize the project

UI Store Integration:

The frontend uses Alpine.js stores to manage project state:

• Access: $store.projects.openProjectsModal()
• Store Location: /components/projects/projects-store.js

Sources: webui/components/sidebar/top-section/quick-actions.html52

Via REST API

Projects are managed through backend API handlers. The project creation endpoint creates the directory structure and initializes project metadata:

Endpoint: POST /project_create

Expected Request Body:

Directory Structure Created:

/a0/usr/projects/client-alpha/
├── .a0proj/                    # Project metadata folder
│   ├── memory/                 # FAISS databases
│   ├── knowledge/              # Imported documents
│   │   ├── main/
│   │   ├── fragments/
│   │   └── solutions/
│   ├── skills/                 # Project-specific SKILL.md files
│   └── secrets                 # Project environment variables
└── workdir/                    # Working directory for code execution

Sources: webui/components/sidebar/top-section/quick-actions.html52 python/helpers/memory.py486-509

---

Configuring Projects

Project Settings

Each project contains a settings.json file at /a0/usr/projects/{name}/settings.json with project-specific configuration:

Setting	Type	Description
name	string	Project identifier (must be unique)
description	string	Human-readable project description
active	boolean	Whether this project is currently active
workdir	string	Working directory path (relative or absolute)
memory_subdir	string	Memory database subdirectory name
knowledge_subdir	string	Knowledge base subdirectory name
git_url	string	Git repository URL (if applicable)
git_branch	string	Git branch to use
custom_instructions	string	Project-specific agent instructions

Example settings.json:

Sources: docs/guides/usage.md79-83 README.md210-213

Custom Instructions

Projects support custom instructions that are injected into the agent's system prompt when the project is active. This allows project-specific behavior without modifying global prompts.

Custom instructions are stored in the custom_instructions field and are automatically loaded by the extension system.

Sources: README.md211 docs/guides/usage.md80

---

Activating Projects

Activation Implementation

Project activation is managed through the project helper module. The activation process modifies the AgentContext to use project-prefixed paths for memory and knowledge lookups.

Activation Flow:

Context-Based Resolution

Once a project is activated, all resource lookups go through context-aware functions:

Memory Resolution:

Knowledge Resolution:

Sources: python/helpers/memory.py522-529 agent.py296-317

Activation Methods

Via Web UI

1. Click the dropdown toggle in quick actions toolbar
2. Select Projects from the menu
3. In the projects modal, locate the target project
4. Click the Activate button for that project
5. The modal updates to show the active project status
6. Subsequent agent operations use project-scoped resources

UI Indicators:

• Active project shown with visual highlight in projects list
• Project name may display in sidebar or header when active
• Memory dashboard filters to show only project memories

Via API

Endpoint: POST /project_activate

Request:

Expected Response:

Effect on Agent Context:

• get_context_memory_subdir() returns "projects/client-alpha"
• agent.config.knowledge_subdirs updated to include project path
• Working directory paths resolve to project workdir
• Secrets loaded from project secrets file

Sources: webui/components/sidebar/top-section/quick-actions.html52 python/helpers/memory.py522-529

---

Using Active Projects

Agent Context Integration

The AgentContext class stores project state and provides it to all subsystems. When a project is active, helper functions read from the context to determine path resolution.

Integration Architecture:

Sources: agent.py45-179 python/helpers/memory.py512-529

Path Resolution Implementation

The project system uses string prefix detection in helper functions to route paths to project directories. The key functions are:

Memory Database Path Resolution

Function: abs_db_dir(memory_subdir: str) -> str

Knowledge Base Path Resolution

Function: abs_knowledge_dir(knowledge_subdir: str, *sub_dirs: str) -> str

Context Memory Subdir Retrieval

Function: get_context_memory_subdir(context: AgentContext) -> str

This function calls the project helper to determine if a project is active and returns the appropriate memory subdirectory string:

• If project active: Returns "projects/{project_name}"
• If no project: Returns configured memory_subdir from settings

Path Resolution Table:

Resource Type	Without Project	With Project "myproject"
Memory DB	/a0/usr/memory/default/	/a0/usr/projects/myproject/.a0proj/memory/
Knowledge	/a0/usr/knowledge/custom/	/a0/usr/projects/myproject/.a0proj/knowledge/
Skills	/a0/usr/skills/	/a0/usr/projects/myproject/.a0proj/skills/
Secrets	/a0/usr/secrets	/a0/usr/projects/myproject/.a0proj/secrets
Workdir	/a0/usr/workdir/	/a0/usr/projects/myproject/workdir/

Sources: python/helpers/memory.py486-493 python/helpers/memory.py496-509 python/helpers/memory.py522-529

---

Git-Based Projects

Cloning Repositories

Projects can be initialized from Git repositories, enabling version-controlled codebases:

Sources: README.md32-34 README.md193-194

Authentication Methods

Projects support multiple authentication methods for Git operations:

Method	Configuration	Use Case
Personal Access Token	git_token in settings	GitHub, GitLab, Bitbucket
SSH Key	Stored in project secrets	Private Git servers
OAuth	Token in secrets	GitHub Apps, OAuth providers
Public Access	No authentication	Public repositories

Example with Token:

Sources: README.md194 docs/guides/usage.md76

Git Operations

The agent can perform Git operations within the project's working directory using the code_execution_tool:

Sources: README.md32-34

---

Project-Specific Features

Memory Isolation Implementation

The Memory class provides isolation through the memory_subdir parameter. When a project is active, this parameter is set to "projects/{project_name}", which triggers special path resolution logic.

Memory Initialization with Projects

Memory Loading Flow:

Memory Areas

Each project's memory database contains three areas as defined in Memory.Area enum:

Area	Purpose	Enum Value
Memory.Area.MAIN	General project knowledge	"main"
Memory.Area.FRAGMENTS	Conversation snippets	"fragments"
Memory.Area.SOLUTIONS	Solved problems	"solutions"

These areas are stored as metadata within the same FAISS database but can be filtered during search operations using the filter parameter.

Sources: python/helpers/memory.py54-59 python/helpers/memory.py64-89 python/helpers/memory.py512-520

Knowledge Base Isolation

The knowledge import system uses the same path resolution strategy as memory. When documents are imported with an active project, they are stored in the project's metadata folder and only loaded when that project is active.

Knowledge Import with Projects

Directory Structure:

/a0/usr/projects/myproject/.a0proj/knowledge/
├── main/                    # Memory.Area.MAIN
│   ├── api-docs.pdf
│   └── infrastructure-guide.md
├── fragments/               # Memory.Area.FRAGMENTS
│   └── conversation-snippets.md
└── solutions/               # Memory.Area.SOLUTIONS
    └── deployment-procedures.txt

Knowledge Preload Process:

The Memory.preload_knowledge() method scans knowledge directories and imports documents into the FAISS database. With projects, the function:

1. Calls abs_knowledge_dir(kn_dir) to resolve the project path
2. Scans for files in the directory (root goes to MAIN area)
3. Scans subdirectories matching Memory.Area enum values
4. Tracks imported files in knowledge_import.json with file hashes
5. Re-imports only when files change

Area Assignment:

Sources: python/helpers/memory.py249-295 python/helpers/memory.py297-325 python/helpers/memory.py496-509

Skills Isolation

Projects can have dedicated skills at /a0/usr/projects/{project_name}/skills/. These skills are only discovered and loaded when the project is active, enabling project-specific capabilities.

Example project skill structure:

/a0/usr/projects/client-alpha/skills/
├── monitoring/
│   └── SKILL.md
└── deployment/
    └── SKILL.md

Sources: Diagram 5 (Extension and Plugin Architecture), README.md212

Secrets Management

Project secrets are stored in /a0/usr/projects/{project_name}/secrets as environment variables that the agent can reference without seeing the actual values.

Example secrets file:

The agent can reference these as $CLIENT_ALPHA_API_KEY in commands without the values being exposed in the chat logs.

Sources: README.md237-239 docs/guides/usage.md84

---

Task Scheduler Integration

Projects integrate with the task scheduler, allowing scheduled tasks to run in project context:

Sources: Diagram 6 (Task Scheduling and Background Execution), README.md122

Creating Project-Scoped Tasks

Via Scheduler Tool:

Via REST API:

Sources: README.md122 docs/guides/usage.md82-83

---

MCP, A2A, and External API Integration

Project-Scoped MCP Servers

Projects can configure dedicated MCP servers that are only available when the project is active:

Project MCP Configuration:

Sources: README.md202

Project-Scoped A2A Connections

Agent-to-Agent (A2A) connections can be scoped to projects, enabling project-specific agent collaboration:

Configuration:

Sources: README.md202

Project-Scoped External APIs

External API endpoints configured for projects are only accessible when that project is active:

API Configuration:

Sources: README.md202

---

Common Use Cases

Multi-Client Isolation

Use projects to maintain separate workspaces for different clients:

Sources: README.md124 docs/guides/usage.md78

Development Environments

Use projects for different development environments:

• dev: Development environment with test credentials
• staging: Staging environment with staging API keys
• production: Production environment with production secrets

Sources: docs/guides/usage.md78

Codebase Analysis

Create projects from Git repositories for code analysis tasks:

1. Create project from repository URL
2. Agent clones codebase to project workdir
3. Import documentation to project knowledge base
4. Store analysis results in project memory
5. All context remains isolated to the project

Sources: README.md32-34

---

Project Listing and Management

List All Projects

Via REST API:

Via Web UI:

• Click Projects dropdown in sidebar
• View list of all projects with status indicators
• Active project shown with highlight

Sources: docs/guides/usage.md73

Update Project Settings

Endpoint: POST /project_update

Request:

Sources: docs/guides/usage.md79

Delete Project

Endpoint: POST /project_delete

Request:

Deleting a project removes:

• Project directory and all contents
• Associated memory databases
• Knowledge base documents
• Settings and secrets

Warning: This operation is irreversible. Backup important data before deletion.

Sources: docs/guides/usage.md73

---

Best Practices

Naming Conventions

Use descriptive, unique project names:

• Good: client-alpha-monitoring, project-website-redesign, dev-environment
• Avoid: test, temp, project1

Memory Management

• Regularly review project memories using the Memory Dashboard
• Consolidate duplicate or outdated memories
• Use project-specific memory areas (MAIN, FRAGMENTS, SOLUTIONS)

Secrets Security

• Never commit secrets to Git repositories
• Use project secrets file for all credentials
• Reference secrets as environment variables ($SECRET_NAME)
• Rotate credentials regularly

Git Integration

• Use feature branches for development projects
• Commit and push changes regularly
• Keep project Git configuration up to date
• Use .gitignore to exclude sensitive files

Task Scheduling

• Scope scheduled tasks to appropriate projects
• Use dedicated contexts for long-running tasks
• Monitor task execution logs
• Set appropriate error handling and alerting

Sources: README.md122-124 docs/guides/usage.md84